spectoflow 0.22.3 → 0.22.5

package/bin/spectoflow.js

@@ -9,6 +9,7 @@ const adapters = require('../lib/adapters');
 const detect = require('../lib/detect');
 const ownership = require('../lib/ownership');
 const manifest = require('../lib/manifest');
+const registry = require('../lib/registry');
 const mcp = require('../lib/mcp');
 const { startRun } = require('../templates/dashboard/runner');
 const { buildCustomizePrompt } = require('../templates/lib/customize-prompts');
@@ -283,6 +284,28 @@ async function dashboard() {
   return startDashboard();
 }
 
+// ---- projects: the multi-project registry's CLI surface (~/.spectoflow/projects.json) ----
+function projectsCmd() {
+  const sub = argv[1];
+  if (sub === 'remove') return projectsRemove(argv[2]);
+  return projectsList();
+}
+function projectsList() {
+  console.log(wordmark());
+  const rows = registry.listProjects();
+  if (!rows.length) {
+    console.log(c.dim('  no projects registered yet — run `spectoflow dashboard` inside one'));
+    return;
+  }
+  const w = Math.max(4, ...rows.map((r) => r.name.length));
+  rows.forEach((r) => console.log(`  ${c.g(r.id)}  ${r.name.padEnd(w)}  ${c.dim(r.path)}`));
+}
+function projectsRemove(id) {
+  if (!id) { console.log('Usage: spectoflow projects remove <id>'); return; }
+  const ok = registry.removeProject(id);
+  console.log(ok ? `${c.g('✓')} removed ${id}` : `${c.y('!')} no project registered with id ${id}`);
+}
+
 // ---- Customize: `spectoflow skill/agent/dashboard create` — the CLI mirror of the dashboard's
 // Settings → Customize UI. Both surfaces build the same natural-language prompt (customize-prompts.js)
 // and post it through the same pipeline (runner.js's startRun — the function /api/run itself calls),
@@ -479,6 +502,7 @@ ${c.bold('Dashboard')}
   ${c.g('dashboard status')}             is it running? (url + pid)
   ${c.g('dashboard stop')}               stop it ${c.dim('(alias: stop)')}
   ${c.g('dashboard restart')}            stop then start
+  ${c.g('projects')} ${c.dim('[remove <id>]')}     list every project seen so far (~/.spectoflow/projects.json)
 
 ${c.bold('Customize')} ${c.dim('— same as Settings → Customize, from the terminal')}
   ${c.g('skill create')} ${c.dim('"<description>" | --auto')}      generate a project skill
@@ -522,6 +546,10 @@ const HELP = {
     ${c.g('stop')}      stop it            ${c.dim('(alias: spectoflow stop)')}
     ${c.g('restart')}   stop then start
     ${c.g('create')}    generate a custom dashboard, e.g. ${c.dim('spectoflow dashboard create "..." --auto')}`,
+  projects: `${c.bold('spectoflow projects')} ${c.dim('[remove <id>]')}\n
+  List every registered project in the global registry at ${c.dim('~/.spectoflow/projects.json')} (stored by
+  ${c.g('spectoflow dashboard')}) — id, name, path. ${c.g('remove <id>')} drops one (e.g. a project that moved
+  or was deleted) from this list only; it never touches that project's own files.`,
   skill: `${c.bold('spectoflow skill create')} ${c.dim('"<description>" [--agent=name]')}\n${c.bold('spectoflow skill create')} ${c.dim('--auto [--agent=name]')}\n
   Generate a project-specific skill — the CLI mirror of Settings → Customize → ${c.bold('Skills')} →
   ${c.bold('Add skill')} in the dashboard. Describe what it should do, or pass ${c.g('--auto')} to have
@@ -547,6 +575,7 @@ const showHelp = (name) => console.log('\n' + HELP[name].trim() + '\n');
 // ---- dispatch ---------------------------------------------------------------
 const fns = {
   init, update, dashboard, stop: stopDashboard, status, list: listAll, help, version,
+  projects: projectsCmd,
   agents: () => { console.log(wordmark()); printAgents(false); },
   skills: () => { console.log(wordmark()); printSkills(false); },
   workflow: () => { console.log(wordmark()); printWorkflow(false); },

package/lib/registry.js

@@ -0,0 +1,98 @@
+'use strict';
+/*
+ * The project registry — ~/.spectoflow/projects.json. Tracks every project spectoflow has seen (via
+ * `spectoflow dashboard`, wired in a later sub-project), so the multi-project hub knows what to list
+ * and switch between. This module owns only the registry file itself; it has no opinion about
+ * dashboards, ports, or servers, and nothing else in the codebase calls it yet.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const REGISTRY_FILE = 'projects.json';
+
+// Resolution order: an explicit baseDir (unit tests) > SPECTOFLOW_HOME (CLI-level test isolation,
+// same convention as SPECTOFLOW_ROOT/SPECTOFLOW_PORT elsewhere in this codebase) > the real home dir.
+function registryDir(baseDir) {
+  return baseDir || process.env.SPECTOFLOW_HOME || path.join(os.homedir(), '.spectoflow');
+}
+function registryPath(baseDir) {
+  return path.join(registryDir(baseDir), REGISTRY_FILE);
+}
+
+function readRegistry(baseDir) {
+  try { return JSON.parse(fs.readFileSync(registryPath(baseDir), 'utf8')); }
+  catch { return { projects: [] }; }
+}
+
+function writeRegistry(baseDir, data) {
+  const dir = registryDir(baseDir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(registryPath(baseDir), JSON.stringify(data, null, 2) + '\n');
+}
+
+// 6 hex chars; regenerated on the rare collision against ids already in the registry. `randomFn` is
+// injectable (defaults to crypto.randomBytes) so collision handling is testable without depending on
+// genuine randomness to ever actually collide.
+function genId(existingIds, randomFn) {
+  const rand = randomFn || ((n) => crypto.randomBytes(n));
+  let id;
+  do { id = rand(3).toString('hex'); } while (existingIds.includes(id));
+  return id;
+}
+
+function findByPath(projectPath, baseDir) {
+  const target = path.resolve(projectPath);
+  return readRegistry(baseDir).projects.find((p) => path.resolve(p.path) === target) || null;
+}
+
+// Registers `projectPath` if it isn't already known (matched by normalized path); either way stamps
+// lastOpened to now and returns the entry. Never duplicates the same folder under a second id.
+function addProject(projectPath, baseDir) {
+  const reg = readRegistry(baseDir);
+  const target = path.resolve(projectPath);
+  let entry = reg.projects.find((p) => path.resolve(p.path) === target);
+  if (!entry) {
+    entry = {
+      id: genId(reg.projects.map((p) => p.id)),
+      path: target,
+      name: path.basename(target),
+      lastOpened: new Date().toISOString(),
+    };
+    reg.projects.push(entry);
+  } else {
+    entry.lastOpened = new Date().toISOString();
+  }
+  writeRegistry(baseDir, reg);
+  return entry;
+}
+
+function removeProject(id, baseDir) {
+  const reg = readRegistry(baseDir);
+  const before = reg.projects.length;
+  reg.projects = reg.projects.filter((p) => p.id !== id);
+  writeRegistry(baseDir, reg);
+  return reg.projects.length < before;
+}
+
+function touchProject(id, baseDir) {
+  const reg = readRegistry(baseDir);
+  const entry = reg.projects.find((p) => p.id === id);
+  if (!entry) return false;
+  entry.lastOpened = new Date().toISOString();
+  writeRegistry(baseDir, reg);
+  return true;
+}
+
+// Newest-first — the natural "what did I touch most recently" order for both `spectoflow projects
+// list` and (in a later sub-project) the hub landing page.
+function listProjects(baseDir) {
+  return readRegistry(baseDir).projects.slice()
+    .sort((a, b) => (b.lastOpened || '').localeCompare(a.lastOpened || ''));
+}
+
+module.exports = {
+  readRegistry, writeRegistry, genId, addProject, removeProject, touchProject,
+  findByPath, listProjects, registryPath,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.22.3",
+  "version": "0.22.5",
   "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/handlers.js

@@ -0,0 +1,241 @@
+'use strict';
+/*
+ * spectoflow dashboard — per-project route logic, vendored into every project's
+ * .spectoflow/dashboard/ (copied by init/update, exactly like server.js). Split out of server.js so
+ * a single global hub process (lib/hub-server.js) can load a different project's routes on demand —
+ * see docs/multi-project-hub-design.md's "the server must split in two" addendum.
+ *
+ * createHandlers(root) returns the per-project surface a listener-owning process needs:
+ *   - handleApi(req, res, u, emit): Promise<boolean> — true if this request was an API route and was
+ *     handled (caller should not also try static/SPA fallback); false otherwise. Deliberately excludes
+ *     /api/events: SSE client registration stays owned by whichever file owns the HTTP listener.
+ *   - watchDirs: string[] — dirs (relative to root) whose changes should emit {type:'change'}. The
+ *     caller owns the actual fs.watch calls (it owns emit).
+ *   - onBoot(): call once, the first time this project is opened in a server's lifetime (creates the
+ *     custom-dashboards dir if missing, reconciles any stale in-flight orchestration).
+ */
+const fs = require('fs');
+const path = require('path');
+const store = require('../lib/store');
+const { startRun } = require('./runner');
+const { runSummarize } = require('./summarize');
+const orchestrator = require('./orchestrator');
+const agentsRegistry = require('../lib/agents-registry');
+const files = require('./files');
+
+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({}); } }); }); }
+
+function createHandlers(root) {
+  // Installed framework version: the manifest records it at init/update time. Fallback to the kit's
+  // own package.json — only reachable (and only used) when the server is run straight from templates/
+  // (dev/preview), never from an installed project whose sibling package.json belongs to the user.
+  function frameworkVersion() {
+    try { return JSON.parse(fs.readFileSync(path.join(root, '.spectoflow', '.manifest.json'), 'utf8')).version; } catch {}
+    try { const pk = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')); if (pk.name === 'spectoflow') return pk.version; } catch {}
+    return null;
+  }
+  function project() {
+    const p = store.readProject(root);
+    const v = frameworkVersion(); if (v) p.version = v;
+    p.projectName = path.basename(root);
+    p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label, headless: a.headless, docsUrl: a.docsUrl }));
+    p.installedAgents = agentsRegistry.installedAgents(root);
+    return p;
+  }
+  function findPlanFileForTask(id) { for (const pl of store.readPlans(root)) for (const ph of pl.phases) if (ph.tasks.find((t) => t.id === id)) return pl.file; return null; }
+
+  const configPath = () => path.join(root, '.spectoflow', 'config.json');
+  function writeConfig(patch) {
+    const cp = configPath(); const cfg = JSON.parse(fs.readFileSync(cp, 'utf8'));
+    if (patch.mode && ['autopilot', 'semi', 'manual'].includes(patch.mode)) cfg.mode = patch.mode;
+    if (typeof patch.language === 'string' && patch.language.trim()) cfg.language = patch.language.trim();
+    if (typeof patch.design === 'string' && /^[a-z0-9-]{1,40}$/.test(patch.design)) cfg.design = patch.design;
+    if (typeof patch.agent === 'string' && patch.agent.trim()) {
+      const id = patch.agent.trim();
+      // Never activate an agent whose CLI isn't actually there — a picked-but-absent agent would just
+      // fail silently the next time something tries to run it.
+      if (!agentsRegistry.isAgentInstalled(id, root)) {
+        const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
+        const label = known ? known.label : id;
+        throw new Error(`${label} isn't installed here (its command wasn't found on PATH). Install it, then try again.`);
+      }
+      cfg.agent = id;
+      const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
+      if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
+    }
+    fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
+    return cfg;
+  }
+  function promoteAttention(item) {
+    return store.addTask(root, { phase: 'Attention', title: item.text, owner: 'user' });
+  }
+
+  async function handleApi(req, res, u, emit) {
+    const p = u.pathname;
+
+    if (p === '/api/project') { sendJSON(res, 200, project()); return true; }
+
+    if (p === '/api/agentfile' && req.method === 'GET') {
+      const rel = new URL(req.url, 'http://x').searchParams.get('path') || '';
+      const base = path.join(root, '.spectoflow');
+      const aDir = path.join(base, 'agents'), sDir = path.join(base, 'skills');
+      const abs = path.resolve(base, rel);
+      const okDir = abs.startsWith(aDir + path.sep) || abs.startsWith(sDir + path.sep);
+      if (!okDir || !abs.endsWith('.md') || !fs.existsSync(abs) || fs.statSync(abs).isDirectory())
+        { sendJSON(res, 400, { error: 'not an agent/skill file' }); return true; }
+      // Symlink guard: the resolved real path must stay within the (real) scope dirs.
+      let real; try { real = fs.realpathSync(abs); } catch { real = null; }
+      const realA = (() => { try { return fs.realpathSync(aDir); } catch { return aDir; } })();
+      const realS = (() => { try { return fs.realpathSync(sDir); } catch { return sDir; } })();
+      const okReal = real && (real.startsWith(realA + path.sep) || real.startsWith(realS + path.sep));
+      if (!okReal || !real.endsWith('.md') || fs.statSync(real).isDirectory())
+        { sendJSON(res, 400, { error: 'not an agent/skill file' }); return true; }
+      sendJSON(res, 200, { content: fs.readFileSync(real, 'utf8') }); return true;
+    }
+
+    if (p === '/api/files/tree' && req.method === 'GET') { sendJSON(res, 200, { tree: files.tree(root) }); return true; }
+    if (p === '/api/files/read' && req.method === 'GET') {
+      const rel = new URL(req.url, 'http://x').searchParams.get('path') || '';
+      const r = files.readFile(root, rel);
+      sendJSON(res, r.error ? 400 : 200, r); return true;
+    }
+    if (p === '/api/files/write' && req.method === 'POST') {
+      const { path: rel, content } = await body(req);
+      const r = files.writeFile(root, rel, content);
+      if (r.error) { sendJSON(res, 400, r); return true; }
+      emit({ type: 'change' }); sendJSON(res, 200, r); return true;
+    }
+    if (p === '/api/files/mkdir' && req.method === 'POST') {
+      const { path: rel } = await body(req);
+      const r = files.mkdir(root, rel);
+      if (r.error) { sendJSON(res, 400, r); return true; }
+      emit({ type: 'change' }); sendJSON(res, 200, r); return true;
+    }
+
+    if (p === '/api/task' && req.method === 'POST') {
+      const { title, phase, file, owner, level } = await body(req);
+      if (!title || !String(title).trim()) { sendJSON(res, 400, { error: 'A title is required.' }); return true; }
+      const t = store.addTask(root, { title: String(title).trim(), phase, file, owner, level });
+      emit({ type: 'change' }); sendJSON(res, 200, { task: t }); return true;
+    }
+    if (p.startsWith('/api/task/') && req.method === 'PATCH') {
+      const id = decodeURIComponent(p.split('/')[3] || ''); const patch = await body(req);
+      const file = findPlanFileForTask(id); if (!file) { sendJSON(res, 404, { error: `Task ${id} not found.` }); return true; }
+      store.updateTaskLine(root, file, id, patch); emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+    if (/^\/api\/task\/[^/]+\/comment$/.test(p) && req.method === 'POST') {
+      const id = decodeURIComponent(p.split('/')[3] || ''); const { text, action } = await body(req);
+      if (!text || !String(text).trim()) { sendJSON(res, 400, { error: 'Empty comment.' }); return true; }
+      const file = findPlanFileForTask(id); if (!file) { sendJSON(res, 404, { error: `Task ${id} not found.` }); return true; }
+      store.addTaskComment(root, file, id, String(text).trim(), 'me');
+      if (action === 'analyze') store.updateTaskLine(root, file, id, { status: 'to_analyze' });
+      emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+    if (p === '/api/workflow/toggle' && req.method === 'POST') {
+      const { name } = await body(req); const wf = path.join(root, '.spectoflow', 'workflow.md');
+      const lines = fs.readFileSync(wf, 'utf8').split('\n');
+      for (let i = 0; i < lines.length; i++) { const m = lines[i].match(/^(\s*- \[)( |x|X)(\]\s+)(.*)$/);
+        if (m && m[4].replace(/\s*\(optional\)\s*$/i, '').trim() === name) lines[i] = m[1] + (m[2].trim() ? ' ' : 'x') + m[3] + m[4]; }
+      fs.writeFileSync(wf, lines.join('\n')); emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+
+    if (p === '/api/run' && req.method === 'POST') {
+      const { prompt, agent } = await body(req);
+      if (!prompt || !String(prompt).trim()) { sendJSON(res, 400, { error: 'Empty request.' }); return true; }
+      const r = startRun(root, { prompt, agent }, emit);
+      if (r.error) { sendJSON(res, 400, { error: r.error }); return true; }
+      sendJSON(res, 200, { runId: r.runId }); return true;
+    }
+
+    if (p === '/api/chat/summarize' && req.method === 'POST') {
+      const { agent } = await body(req);
+      const r = runSummarize(root, { agent }, emit);
+      if (r.error) { sendJSON(res, 400, { error: r.error }); return true; }
+      sendJSON(res, 200, { ok: true }); return true;
+    }
+    if (p === '/api/chat/clear' && req.method === 'POST') {
+      const rt = store.readRuntime(root); rt.messages = []; store.writeRuntime(root, rt);
+      emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+
+    if (p === '/api/orchestrate' && req.method === 'POST') {
+      const { request } = await body(req);
+      if (!request || !String(request).trim()) { sendJSON(res, 400, { error: 'Empty request.' }); return true; }
+      const active = store.readRuntime(root).orchestration;
+      if (active && ['running', 'awaiting_approval'].includes(active.status))
+        { sendJSON(res, 409, { error: 'An orchestration is already active.' }); return true; }
+      const mode = store.readConfig(root).mode || 'semi';
+      orchestrator.runOrchestration({ root, request: String(request).trim(), mode,
+        runStep: orchestrator.defaultRunStep, confirm: orchestrator.defaultConfirm }, emit)
+        .catch((e) => emit({ type: 'message', message: { role: 'orchestrator', kind: 'status', text: 'orchestration error: ' + e.message } }));
+      const o = store.readRuntime(root).orchestration;
+      sendJSON(res, 200, { orchestrationId: o && o.id }); return true;
+    }
+    if (p === '/api/orchestrate/approve' && req.method === 'POST') {
+      const { decision, note } = await body(req);
+      const ok = orchestrator.submitDecision(decision, note);
+      sendJSON(res, ok ? 200 : 409, ok ? { ok: true } : { error: 'No pending approval.' }); return true;
+    }
+
+    if (p === '/api/settings' && req.method === 'POST') {
+      const patch = await body(req);
+      try { const cfg = writeConfig(patch); emit({ type: 'change' }); sendJSON(res, 200, { config: cfg }); }
+      catch (e) { sendJSON(res, 400, { error: String(e && e.message || e) }); }
+      return true;
+    }
+
+    if (p === '/api/attention' && req.method === 'POST') {
+      const { text } = await body(req);
+      if (!text || !String(text).trim()) { sendJSON(res, 400, { error: 'Empty note.' }); return true; }
+      const rt = store.readRuntime(root); rt.attention = rt.attention || [];
+      const item = { id: 'att' + Date.now().toString(36), at: new Date().toISOString(), by: 'me', source: 'user', status: 'open', text: String(text).trim() };
+      rt.attention.unshift(item); store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { item }); return true;
+    }
+    if (/^\/api\/attention\/[^/]+\/promote$/.test(p) && req.method === 'POST') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+      if (!it) { sendJSON(res, 404, { error: 'Note not found.' }); return true; }
+      const t = promoteAttention(it); it.status = 'resolved'; it.promotedTo = t.id;
+      store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { task: t }); return true;
+    }
+    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'PATCH') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const patch = await body(req);
+      const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+      if (!it) { sendJSON(res, 404, { error: 'Note not found.' }); return true; }
+      if (typeof patch.text === 'string' && patch.text.trim()) it.text = patch.text.trim();
+      if (patch.status && ['open', 'resolved'].includes(patch.status)) it.status = patch.status;
+      store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { item: it }); return true;
+    }
+    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'DELETE') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const rt = store.readRuntime(root); rt.attention = (rt.attention || []).filter((x) => x.id !== id);
+      store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { ok: true }); return true;
+    }
+
+    return false;
+  }
+
+  function onBoot() {
+    // A project that hasn't used Customize yet won't have this dir on disk, and `spectoflow init` on
+    // an older install won't have created it either.
+    try { fs.mkdirSync(path.join(root, '.spectoflow', 'dashboard', 'custom'), { recursive: true }); } catch (_) {}
+    // A process restart loses any in-flight orchestration; without this, a stale 'running' or
+    // 'awaiting_approval' status wedges the /api/orchestrate 409 guard forever. Not a real resume —
+    // just clears the wedge so a fresh orchestration can start.
+    try { orchestrator.reconcileOnBoot(root); } catch (_) {}
+  }
+
+  return {
+    handleApi,
+    watchDirs: ['plans', 'specs', '.spectoflow', '.spectoflow/dashboard/custom'],
+    onBoot,
+  };
+}
+
+module.exports = { createHandlers };

package/templates/dashboard/public/app.js

@@ -1321,6 +1321,7 @@ function renderDocs(){
 // event refreshes the TREE listing but never overwrites an open file's editor buffer, so an
 // unrelated agent write elsewhere can't clobber unsaved work here. ----
 let filesTreeData=null, filesOpenPath=null, filesOpenDirty=false;
+let filesSelectedDir=''; // '' = project root — the folder + File/+ Folder create inside
 const filesOpenDirs=new Set(); // persists which tree folders are expanded across a refresh
 async function loadFilesTree(){
   try{
@@ -1338,7 +1339,8 @@ function renderFiles(){
   loadFilesTree();
 }
 function fNode(entry){
-  const row=el('div','f-row'+(entry.type==='dir'&&filesOpenDirs.has(entry.path)?' is-open':'')+(entry.path===filesOpenPath?' is-active':''));
+  const isTarget=entry.type==='dir'&&entry.path===filesSelectedDir;
+  const row=el('div','f-row'+(entry.type==='dir'&&filesOpenDirs.has(entry.path)?' is-open':'')+(entry.path===filesOpenPath?' is-active':'')+(isTarget?' is-target':''));
   row.tabIndex=0;
   if(entry.type==='dir'){
     const chev=document.createElementNS('http://www.w3.org/2000/svg','svg');
@@ -1353,10 +1355,17 @@ function fNode(entry){
     const kids=el('div','f-children'); kids.hidden=!filesOpenDirs.has(entry.path);
     (entry.children||[]).forEach(c=> kids.append(fNode(c)));
     wrap.append(kids);
+    // a click both toggles expand/collapse AND marks this folder as where +File/+Folder create —
+    // the two are independent ideas but sharing the click keeps the tree from needing a second,
+    // easy-to-miss gesture just to pick a target folder.
     row.addEventListener('click',()=>{
       const open=filesOpenDirs.has(entry.path);
       if(open) filesOpenDirs.delete(entry.path); else filesOpenDirs.add(entry.path);
       row.classList.toggle('is-open',!open); kids.hidden=open;
+      filesSelectedDir=entry.path;
+      const root=$('#filesRootRow'); if(root) root.classList.remove('is-target');
+      $$('#filesTree .f-row.is-target').forEach(r=> r!==row && r.classList.remove('is-target'));
+      row.classList.add('is-target');
     });
   } else {
     row.addEventListener('click',()=> openFilesFile(entry.path));
@@ -1366,10 +1375,104 @@ function fNode(entry){
 function renderFilesTree(){
   const box=$('#filesTree'); if(!box) return;
   box.innerHTML='';
+  const root=$('#filesRootRow'); if(root) root.classList.toggle('is-target',filesSelectedDir==='');
   if(!filesTreeData || !filesTreeData.length){ box.append(el('div','empty',t('files.empty'))); return; }
   filesTreeData.forEach(e=> box.append(fNode(e)));
 }
 function filesExt(p){ const m=/\.([a-z0-9]+)$/i.exec(p||''); return m?m[1].toLowerCase():''; }
+
+// ---- lightweight syntax highlighting — zero-dependency (no CodeMirror/Monaco, per the explicit
+// call made when this tab was designed): a single char-scanner tokenizer good enough to make code
+// readable at a glance in a file browser, not a language-correct parser. Anything not recognized
+// (or with no lang mapping) just renders as plain, unstyled text — never a rendering error. ----
+const FILES_HL_LANG = {
+  js: { comments:[['//','\n'],['/*','*/']], strings:['"',"'",'`'],
+    keywords:'const let var function return if else for while do switch case break continue new class extends super this typeof instanceof in of try catch finally throw async await yield import export default from as null undefined true false void delete'.split(' ') },
+  json: { comments:[], strings:['"'], keywords:'true false null'.split(' ') },
+  css: { comments:[['/*','*/']], strings:['"',"'"], keywords:[] },
+  html: { comments:[['<!--','-->']], strings:['"',"'"], keywords:[], tags:true },
+  py: { comments:[['#','\n']], strings:['"',"'"],
+    keywords:'def class return if elif else for while break continue pass import from as try except finally raise with lambda yield async await None True False and or not in is del global nonlocal'.split(' ') },
+  sh: { comments:[['#','\n']], strings:['"',"'"],
+    keywords:'if then else elif fi for while do done case esac function return exit export local readonly'.split(' ') },
+  yml: { comments:[['#','\n']], strings:['"',"'"], keywords:'true false null'.split(' ') },
+};
+function filesHlLang(ext){
+  if(['js','mjs','cjs','ts','jsx','tsx'].includes(ext)) return 'js';
+  if(ext==='json') return 'json';
+  if(ext==='css') return 'css';
+  if(['html','htm'].includes(ext)) return 'html';
+  if(ext==='py') return 'py';
+  if(['sh','bash'].includes(ext)) return 'sh';
+  if(['yml','yaml'].includes(ext)) return 'yml';
+  return null;
+}
+// Scans `src` one character at a time, classifying spans as it goes; returns an HTML string with
+// each span wrapped in a colored <span> (escaped — this is the only place raw file content becomes
+// markup, so nothing here may skip escHtml).
+function filesHighlight(src,langKey){
+  const lang=FILES_HL_LANG[langKey];
+  if(!lang) return escHtml(src);
+  const n=src.length;
+  let i=0,html='',plain='';
+  const flushPlain=()=>{ if(plain){ html+=escHtml(plain); plain=''; } };
+  const isWordChar=c=>/[A-Za-z0-9_$]/.test(c);
+  while(i<n){
+    let matched=false;
+    // comments
+    for(const [open,close] of lang.comments){
+      if(src.startsWith(open,i)){
+        const end = close==='\n' ? (src.indexOf('\n',i)===-1?n:src.indexOf('\n',i)) : (src.indexOf(close,i+open.length)===-1?n:src.indexOf(close,i+open.length)+close.length);
+        flushPlain(); html+='<span class="hl-comment">'+escHtml(src.slice(i,end))+'</span>'; i=end; matched=true; break;
+      }
+    }
+    if(matched) continue;
+    // strings
+    if(lang.strings.includes(src[i])){
+      const q=src[i]; let j=i+1;
+      while(j<n && src[j]!==q){ if(src[j]==='\\') j++; j++; }
+      j=Math.min(j+1,n);
+      flushPlain(); html+='<span class="hl-string">'+escHtml(src.slice(i,j))+'</span>'; i=j; continue;
+    }
+    // html tags (bonus: <tag ...> / </tag>) — a light touch, not full attribute-vs-value parsing
+    if(lang.tags && src[i]==='<' && /[a-zA-Z/!]/.test(src[i+1]||'')){
+      const end=src.indexOf('>',i); const j=end===-1?n:end+1;
+      flushPlain(); html+='<span class="hl-tag">'+escHtml(src.slice(i,j))+'</span>'; i=j; continue;
+    }
+    // numbers
+    if(/[0-9]/.test(src[i]) && !isWordChar(src[i-1]||'')){
+      let j=i; while(j<n && /[0-9.]/.test(src[j])) j++;
+      flushPlain(); html+='<span class="hl-number">'+escHtml(src.slice(i,j))+'</span>'; i=j; continue;
+    }
+    // keywords
+    if(isWordChar(src[i]) && !isWordChar(src[i-1]||'')){
+      let j=i; while(j<n && isWordChar(src[j])) j++;
+      const word=src.slice(i,j);
+      if(lang.keywords.includes(word)){ flushPlain(); html+='<span class="hl-keyword">'+escHtml(word)+'</span>'; i=j; continue; }
+      plain+=word; i=j; continue;
+    }
+    plain+=src[i]; i++;
+  }
+  flushPlain();
+  return html;
+}
+// A textarea can't render colored text itself, so this overlays one, transparent, on top of a
+// highlighted <pre><code> "backdrop" showing through it (the standard technique for a highlighted
+// plain-text editor without a full editor component) — same font metrics on both, scroll positions
+// kept in lockstep, backdrop re-rendered on every keystroke.
+function filesCodeEditor(content,langKey,onInput){
+  const wrap=el('div','files-code-wrap');
+  const pre=document.createElement('pre'); pre.className='files-code-backdrop'; pre.setAttribute('aria-hidden','true');
+  const code=document.createElement('code'); pre.append(code);
+  const ta=el('textarea','files-editor files-code-input'); ta.spellcheck=false; ta.value=content;
+  const paint=()=>{ code.innerHTML=filesHighlight(ta.value,langKey)+'\n'; }; // trailing \n: a final blank line still gets backdrop height
+  const syncScroll=()=>{ pre.scrollTop=ta.scrollTop; pre.scrollLeft=ta.scrollLeft; };
+  ta.addEventListener('input',()=>{ paint(); if(onInput) onInput(ta.value); });
+  ta.addEventListener('scroll',syncScroll);
+  paint();
+  wrap.append(pre,ta);
+  return { wrap, textarea:ta };
+}
 async function openFilesFile(relPath){
   // no native confirm() dialog (it blocks the whole tab, including our own SSE/automation) — a
   // dirty editor just refuses to switch until the user explicitly saves or discards.
@@ -1432,15 +1535,19 @@ function renderFilesMd(box,actions,relPath,content){
   const showEditor=()=>{
     body.innerHTML='';
     const tb=el('div','files-md-toolbar');
-    const ta=el('textarea','files-editor'); ta.value=content;
-    const wrapSel=(before,after)=>{ const s=ta.selectionStart,e=ta.selectionEnd; const v=ta.value; ta.value=v.slice(0,s)+before+v.slice(s,e)+after+v.slice(e); ta.focus(); ta.selectionStart=s+before.length; ta.selectionEnd=e+before.length; content=ta.value; filesOpenDirty=true; };
+    const {wrap,textarea:ta}=filesCodeEditor(content,null,(v)=>{ content=v; filesOpenDirty=true; });
+    const wrapSel=(before,after)=>{
+      const s=ta.selectionStart,e=ta.selectionEnd; const v=ta.value;
+      ta.value=v.slice(0,s)+before+v.slice(s,e)+after+v.slice(e);
+      ta.dispatchEvent(new Event('input')); // repaints the backdrop and marks dirty via the same path as typing
+      ta.focus(); ta.selectionStart=s+before.length; ta.selectionEnd=e+before.length;
+    };
     [['B','**','**'],['I','_','_'],['H','## ',''],['Link','[','](url)']].forEach(([label,a,b])=>{
       const bt=el('button',null,label); bt.type='button'; bt.addEventListener('click',()=>wrapSel(a,b)); tb.append(bt);
     });
     const saveBtn=el('button',null,t('files.save')); saveBtn.type='button'; saveBtn.addEventListener('click',()=>{ content=ta.value; filesSave(relPath,content,actions); });
     tb.append(saveBtn,filesDiscardBtn(relPath));
-    ta.addEventListener('input',()=>{ content=ta.value; filesOpenDirty=true; });
-    body.append(tb,ta); ta.focus(); editBtn.textContent=t('files.preview');
+    body.append(tb,wrap); ta.focus(); editBtn.textContent=t('files.preview');
   };
   editBtn.addEventListener('click',()=>{ editing=!editing; if(editing) showEditor(); else showPreview(); });
   showPreview();
@@ -1461,23 +1568,21 @@ function renderFilesHtml(box,actions,relPath,content){
   };
   const showEditor=()=>{
     body.innerHTML='';
-    const ta=el('textarea','files-editor'); ta.value=content;
-    ta.addEventListener('input',()=>{ content=ta.value; filesOpenDirty=true; });
+    const {wrap,textarea:ta}=filesCodeEditor(content,'html',(v)=>{ content=v; filesOpenDirty=true; });
     const saveBtn=el('button','btn primary',t('files.save')); saveBtn.type='button'; saveBtn.addEventListener('click',()=>filesSave(relPath,content,actions));
     const tb=el('div','files-md-toolbar'); tb.append(saveBtn,filesDiscardBtn(relPath));
-    body.append(tb,ta); ta.focus(); editBtn.textContent=t('files.preview');
+    body.append(tb,wrap); ta.focus(); editBtn.textContent=t('files.preview');
   };
   editBtn.addEventListener('click',()=>{ editing=!editing; if(editing) showEditor(); else showPreview(); });
   showPreview();
 }
 // Anything else that reads as text: a plain monospace editor, editable straight away.
 function renderFilesText(box,actions,relPath,content){
-  const ta=el('textarea','files-editor'); ta.value=content;
-  ta.addEventListener('input',()=>{ filesOpenDirty=true; });
+  const {wrap,textarea:ta}=filesCodeEditor(content,filesHlLang(filesExt(relPath)),()=>{ filesOpenDirty=true; });
   const saveBtn=el('button','btn primary',t('files.save')); saveBtn.type='button';
   saveBtn.addEventListener('click',()=>filesSave(relPath,ta.value,actions));
   actions.append(saveBtn,filesDiscardBtn(relPath));
-  box.append(ta); ta.focus();
+  box.append(wrap); ta.focus();
 }
 // "+ File"/"+ Folder" open the same inline form (never a native prompt()/alert() — those block the
 // whole tab, including our own SSE connection, until dismissed).
@@ -1488,6 +1593,7 @@ function openFilesCreateForm(kind){
   const input=$('#filesCreateInput');
   input.placeholder = kind==='dir' ? t('files.newFolderPrompt') : t('files.newFilePrompt');
   input.value='';
+  const target=$('#filesCreateTarget'); if(target) target.textContent=t('files.creatingIn',{path:filesSelectedDir||t('files.projectRoot')});
   const err=$('#filesCreateError'); if(err) err.hidden=true;
   form.hidden=false; form.classList.add('is-open');
   input.focus();
@@ -1500,7 +1606,7 @@ async function submitFilesCreate(){
   const input=$('#filesCreateInput'); const err=$('#filesCreateError');
   const name=(input.value||'').trim();
   if(!name){ if(err){ err.textContent=t('backlog.addTitleRequired'); err.hidden=false; } return; }
-  const rel=name.replace(/^\/+/,'');
+  const rel=(filesSelectedDir?filesSelectedDir+'/':'')+name.replace(/^\/+/,'');
   const kind=filesCreateKind;
   const endpoint = kind==='dir' ? '/api/files/mkdir' : '/api/files/write';
   const payload = kind==='dir' ? {path:rel} : {path:rel,content:''};
@@ -1638,6 +1744,12 @@ $$('#backlogTable thead th').forEach(th=> th.addEventListener('click', ()=>{
 const filesNewFileBtn=$('#filesNewFile'); if(filesNewFileBtn) filesNewFileBtn.addEventListener('click',()=>openFilesCreateForm('file'));
 const filesNewFolderBtn=$('#filesNewFolder'); if(filesNewFolderBtn) filesNewFolderBtn.addEventListener('click',()=>openFilesCreateForm('dir'));
 const filesRefreshBtn=$('#filesRefresh'); if(filesRefreshBtn) filesRefreshBtn.addEventListener('click',loadFilesTree);
+const filesRootRowBtn=$('#filesRootRow');
+if(filesRootRowBtn) filesRootRowBtn.addEventListener('click',()=>{
+  filesSelectedDir='';
+  $$('#filesTree .f-row.is-target').forEach(r=> r.classList.remove('is-target'));
+  filesRootRowBtn.classList.add('is-target');
+});
 const filesCreateGoBtn=$('#filesCreateGo'); if(filesCreateGoBtn) filesCreateGoBtn.addEventListener('click',submitFilesCreate);
 const filesCreateCancelBtn=$('#filesCreateCancel'); if(filesCreateCancelBtn) filesCreateCancelBtn.addEventListener('click',closeFilesCreateForm);
 const filesCreateInputEl=$('#filesCreateInput'); if(filesCreateInputEl) filesCreateInputEl.addEventListener('keydown',e=>{ if(e.key==='Enter') submitFilesCreate(); });

package/templates/dashboard/public/i18n.js

@@ -85,7 +85,7 @@ en: {
   'team.skillsTitle':'Skills','team.skillsSub':'Evolving procedures — the <em>how</em>.',
   'team.standardsLabel':'standards','team.usesLabel':'uses','team.standardLabel':'standard',
   'drawer.agent':'Agent','drawer.skill':'Skill','drawer.file':'File · {rel}',
-  'drawer.loading':'Loading…','drawer.loadError':'Could not load this file.','files.title':'Files','files.sub':'Browse the project\'s files — view Markdown & HTML, edit any text file, create new ones.','files.newFile':'+ File','files.newFolder':'+ Folder','files.pickFile':'Select a file to view it.','files.empty':'No files yet.','files.edit':'Edit','files.preview':'Preview','files.save':'Save','files.saved':'✓ saved','files.saveError':'Could not save this file.','files.loadError':'Could not load this file.','files.binary':'This file can\'t be previewed here (not text).','files.discardConfirm':'Discard unsaved changes?','files.newFilePrompt':'New file path (e.g. notes/todo.md):','files.newFolderPrompt':'New folder path:','files.refresh':'Refresh','files.discard':'Discard','files.create':'Create',
+  'drawer.loading':'Loading…','drawer.loadError':'Could not load this file.','files.title':'Files','files.sub':'Browse the project\'s files — view Markdown & HTML, edit any text file, create new ones.','files.newFile':'+ File','files.newFolder':'+ Folder','files.pickFile':'Select a file to view it.','files.empty':'No files yet.','files.edit':'Edit','files.preview':'Preview','files.save':'Save','files.saved':'✓ saved','files.saveError':'Could not save this file.','files.loadError':'Could not load this file.','files.binary':'This file can\'t be previewed here (not text).','files.discardConfirm':'Discard unsaved changes?','files.newFilePrompt':'New file name (e.g. todo.md):','files.newFolderPrompt':'New folder name:','files.projectRoot':'project root','files.creatingIn':'Creating in: {path}','files.refresh':'Refresh','files.discard':'Discard','files.create':'Create',
   'chat.widgetTitle':'Run an agent','chat.widgetSub':'Quick access · full view in the Chat tab',
   'chat.tabSub':'Full conversation with the runner — the same run as the widget, more room to read it.',
   'chat.idle':'Type a request — the agent runs headless in this project with full memory (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.',
@@ -197,7 +197,7 @@ fr: {
   'team.skillsTitle':'Compétences','team.skillsSub':'Procédures évolutives — le <em>comment</em>.',
   'team.standardsLabel':'standards','team.usesLabel':'utilise','team.standardLabel':'standard',
   'drawer.agent':'Agent','drawer.skill':'Compétence','drawer.file':'Fichier · {rel}',
-  'drawer.loading':'Chargement…','drawer.loadError':'Impossible de charger ce fichier.','files.title':'Fichiers','files.sub':'Parcourez les fichiers du projet — visualisez Markdown et HTML, modifiez tout fichier texte, créez-en de nouveaux.','files.newFile':'+ Fichier','files.newFolder':'+ Dossier','files.pickFile':'Sélectionnez un fichier pour l’afficher.','files.empty':'Aucun fichier pour l’instant.','files.edit':'Modifier','files.preview':'Aperçu','files.save':'Enregistrer','files.saved':'✓ enregistré','files.saveError':'Impossible d’enregistrer ce fichier.','files.loadError':'Impossible de charger ce fichier.','files.binary':'Ce fichier ne peut pas être prévisualisé ici (non textuel).','files.discardConfirm':'Abandonner les modifications non enregistrées ?','files.newFilePrompt':'Chemin du nouveau fichier (ex. notes/todo.md) :','files.newFolderPrompt':'Chemin du nouveau dossier :','files.refresh':'Actualiser','files.discard':'Annuler','files.create':'Créer',
+  'drawer.loading':'Chargement…','drawer.loadError':'Impossible de charger ce fichier.','files.title':'Fichiers','files.sub':'Parcourez les fichiers du projet — visualisez Markdown et HTML, modifiez tout fichier texte, créez-en de nouveaux.','files.newFile':'+ Fichier','files.newFolder':'+ Dossier','files.pickFile':'Sélectionnez un fichier pour l’afficher.','files.empty':'Aucun fichier pour l’instant.','files.edit':'Modifier','files.preview':'Aperçu','files.save':'Enregistrer','files.saved':'✓ enregistré','files.saveError':'Impossible d’enregistrer ce fichier.','files.loadError':'Impossible de charger ce fichier.','files.binary':'Ce fichier ne peut pas être prévisualisé ici (non textuel).','files.discardConfirm':'Abandonner les modifications non enregistrées ?','files.newFilePrompt':'Nom du nouveau fichier (ex. todo.md) :','files.newFolderPrompt':'Nom du nouveau dossier :','files.projectRoot':'racine du projet','files.creatingIn':'Création dans : {path}','files.refresh':'Actualiser','files.discard':'Annuler','files.create':'Créer',
   'chat.widgetTitle':'Lancer un agent','chat.widgetSub':'Accès rapide · vue complète dans l’onglet Chat',
   'chat.tabSub':'Conversation complète avec l’exécuteur — la même exécution que le widget, avec plus de place pour la lire.',
   'chat.idle':'Tapez une demande — l’agent s’exécute sans supervision dans ce projet avec toute sa mémoire (<code>CLAUDE.md → AGENTS.md</code>) et met le tableau à jour en direct.',
@@ -309,7 +309,7 @@ es: {
   'team.skillsTitle':'Habilidades','team.skillsSub':'Procedimientos en evolución — el <em>cómo</em>.',
   'team.standardsLabel':'estándares','team.usesLabel':'usa','team.standardLabel':'estándar',
   'drawer.agent':'Agente','drawer.skill':'Habilidad','drawer.file':'Archivo · {rel}',
-  'drawer.loading':'Cargando…','drawer.loadError':'No se pudo cargar este archivo.','files.title':'Archivos','files.sub':'Explora los archivos del proyecto — visualiza Markdown y HTML, edita cualquier archivo de texto, crea otros nuevos.','files.newFile':'+ Archivo','files.newFolder':'+ Carpeta','files.pickFile':'Selecciona un archivo para verlo.','files.empty':'Aún no hay archivos.','files.edit':'Editar','files.preview':'Vista previa','files.save':'Guardar','files.saved':'✓ guardado','files.saveError':'No se pudo guardar este archivo.','files.loadError':'No se pudo cargar este archivo.','files.binary':'Este archivo no se puede previsualizar aquí (no es texto).','files.discardConfirm':'¿Descartar los cambios sin guardar?','files.newFilePrompt':'Ruta del nuevo archivo (p. ej. notes/todo.md):','files.newFolderPrompt':'Ruta de la nueva carpeta:','files.refresh':'Actualizar','files.discard':'Descartar','files.create':'Crear',
+  'drawer.loading':'Cargando…','drawer.loadError':'No se pudo cargar este archivo.','files.title':'Archivos','files.sub':'Explora los archivos del proyecto — visualiza Markdown y HTML, edita cualquier archivo de texto, crea otros nuevos.','files.newFile':'+ Archivo','files.newFolder':'+ Carpeta','files.pickFile':'Selecciona un archivo para verlo.','files.empty':'Aún no hay archivos.','files.edit':'Editar','files.preview':'Vista previa','files.save':'Guardar','files.saved':'✓ guardado','files.saveError':'No se pudo guardar este archivo.','files.loadError':'No se pudo cargar este archivo.','files.binary':'Este archivo no se puede previsualizar aquí (no es texto).','files.discardConfirm':'¿Descartar los cambios sin guardar?','files.newFilePrompt':'Nombre del nuevo archivo (p. ej. todo.md):','files.newFolderPrompt':'Nombre de la nueva carpeta:','files.projectRoot':'raíz del proyecto','files.creatingIn':'Creando en: {path}','files.refresh':'Actualizar','files.discard':'Descartar','files.create':'Crear',
   'chat.widgetTitle':'Ejecutar un agente','chat.widgetSub':'Acceso rápido · vista completa en la pestaña Chat',
   'chat.tabSub':'Conversación completa con el ejecutor — la misma ejecución que el widget, con más espacio para leerla.',
   'chat.idle':'Escribe una solicitud — el agente se ejecuta sin supervisión en este proyecto con toda su memoria (<code>CLAUDE.md → AGENTS.md</code>) y actualiza el tablero en vivo.',
@@ -421,7 +421,7 @@ de: {
   'team.skillsTitle':'Skills','team.skillsSub':'Sich weiterentwickelnde Vorgehensweisen — das <em>Wie</em>.',
   'team.standardsLabel':'Standards','team.usesLabel':'nutzt','team.standardLabel':'Standard',
   'drawer.agent':'Agent','drawer.skill':'Skill','drawer.file':'Datei · {rel}',
-  'drawer.loading':'Lädt…','drawer.loadError':'Diese Datei konnte nicht geladen werden.','files.title':'Dateien','files.sub':'Durchsuche die Projektdateien — Markdown & HTML ansehen, jede Textdatei bearbeiten, neue erstellen.','files.newFile':'+ Datei','files.newFolder':'+ Ordner','files.pickFile':'Wähle eine Datei aus, um sie anzuzeigen.','files.empty':'Noch keine Dateien.','files.edit':'Bearbeiten','files.preview':'Vorschau','files.save':'Speichern','files.saved':'✓ gespeichert','files.saveError':'Diese Datei konnte nicht gespeichert werden.','files.loadError':'Diese Datei konnte nicht geladen werden.','files.binary':'Diese Datei kann hier nicht angezeigt werden (kein Text).','files.discardConfirm':'Nicht gespeicherte Änderungen verwerfen?','files.newFilePrompt':'Pfad der neuen Datei (z. B. notes/todo.md):','files.newFolderPrompt':'Pfad des neuen Ordners:','files.refresh':'Aktualisieren','files.discard':'Verwerfen','files.create':'Erstellen',
+  'drawer.loading':'Lädt…','drawer.loadError':'Diese Datei konnte nicht geladen werden.','files.title':'Dateien','files.sub':'Durchsuche die Projektdateien — Markdown & HTML ansehen, jede Textdatei bearbeiten, neue erstellen.','files.newFile':'+ Datei','files.newFolder':'+ Ordner','files.pickFile':'Wähle eine Datei aus, um sie anzuzeigen.','files.empty':'Noch keine Dateien.','files.edit':'Bearbeiten','files.preview':'Vorschau','files.save':'Speichern','files.saved':'✓ gespeichert','files.saveError':'Diese Datei konnte nicht gespeichert werden.','files.loadError':'Diese Datei konnte nicht geladen werden.','files.binary':'Diese Datei kann hier nicht angezeigt werden (kein Text).','files.discardConfirm':'Nicht gespeicherte Änderungen verwerfen?','files.newFilePrompt':'Name der neuen Datei (z. B. todo.md):','files.newFolderPrompt':'Name des neuen Ordners:','files.projectRoot':'Projektstamm','files.creatingIn':'Erstellen in: {path}','files.refresh':'Aktualisieren','files.discard':'Verwerfen','files.create':'Erstellen',
   'chat.widgetTitle':'Agenten ausführen','chat.widgetSub':'Schnellzugriff · vollständige Ansicht im Chat-Tab',
   'chat.tabSub':'Vollständiges Gespräch mit dem Runner — derselbe Lauf wie im Widget, mit mehr Platz zum Lesen.',
   'chat.idle':'Geben Sie eine Anfrage ein — der Agent läuft eigenständig in diesem Projekt mit vollem Gedächtnis (<code>CLAUDE.md → AGENTS.md</code>) und aktualisiert das Board live.',
@@ -533,7 +533,7 @@ pt: {
   'team.skillsTitle':'Habilidades','team.skillsSub':'Procedimentos em evolução — o <em>como</em>.',
   'team.standardsLabel':'padrões','team.usesLabel':'usa','team.standardLabel':'padrão',
   'drawer.agent':'Agente','drawer.skill':'Habilidade','drawer.file':'Ficheiro · {rel}',
-  'drawer.loading':'A carregar…','drawer.loadError':'Não foi possível carregar este ficheiro.','files.title':'Ficheiros','files.sub':'Percorra os ficheiros do projeto — veja Markdown e HTML, edite qualquer ficheiro de texto, crie novos.','files.newFile':'+ Ficheiro','files.newFolder':'+ Pasta','files.pickFile':'Selecione um ficheiro para o ver.','files.empty':'Ainda não há ficheiros.','files.edit':'Editar','files.preview':'Pré-visualizar','files.save':'Guardar','files.saved':'✓ guardado','files.saveError':'Não foi possível guardar este ficheiro.','files.loadError':'Não foi possível carregar este ficheiro.','files.binary':'Este ficheiro não pode ser pré-visualizado aqui (não é texto).','files.discardConfirm':'Descartar alterações não guardadas?','files.newFilePrompt':'Caminho do novo ficheiro (ex. notes/todo.md):','files.newFolderPrompt':'Caminho da nova pasta:','files.refresh':'Atualizar','files.discard':'Descartar','files.create':'Criar',
+  'drawer.loading':'A carregar…','drawer.loadError':'Não foi possível carregar este ficheiro.','files.title':'Ficheiros','files.sub':'Percorra os ficheiros do projeto — veja Markdown e HTML, edite qualquer ficheiro de texto, crie novos.','files.newFile':'+ Ficheiro','files.newFolder':'+ Pasta','files.pickFile':'Selecione um ficheiro para o ver.','files.empty':'Ainda não há ficheiros.','files.edit':'Editar','files.preview':'Pré-visualizar','files.save':'Guardar','files.saved':'✓ guardado','files.saveError':'Não foi possível guardar este ficheiro.','files.loadError':'Não foi possível carregar este ficheiro.','files.binary':'Este ficheiro não pode ser pré-visualizado aqui (não é texto).','files.discardConfirm':'Descartar alterações não guardadas?','files.newFilePrompt':'Nome do novo ficheiro (ex. todo.md):','files.newFolderPrompt':'Nome da nova pasta:','files.projectRoot':'raiz do projeto','files.creatingIn':'A criar em: {path}','files.refresh':'Atualizar','files.discard':'Descartar','files.create':'Criar',
   'chat.widgetTitle':'Executar um agente','chat.widgetSub':'Acesso rápido · vista completa no separador Chat',
   'chat.tabSub':'Conversa completa com o executor — a mesma execução do widget, com mais espaço para ler.',
   'chat.idle':'Escreva um pedido — o agente corre sem supervisão neste projeto com toda a sua memória (<code>CLAUDE.md → AGENTS.md</code>) e atualiza o painel em direto.',
@@ -645,7 +645,7 @@ it: {
   'team.skillsTitle':'Skill','team.skillsSub':'Procedure in evoluzione — il <em>come</em>.',
   'team.standardsLabel':'standard','team.usesLabel':'usa','team.standardLabel':'standard',
   'drawer.agent':'Agente','drawer.skill':'Skill','drawer.file':'File · {rel}',
-  'drawer.loading':'Caricamento…','drawer.loadError':'Impossibile caricare questo file.','files.title':'File','files.sub':'Sfoglia i file del progetto — visualizza Markdown e HTML, modifica qualsiasi file di testo, creane di nuovi.','files.newFile':'+ File','files.newFolder':'+ Cartella','files.pickFile':'Seleziona un file per visualizzarlo.','files.empty':'Nessun file ancora.','files.edit':'Modifica','files.preview':'Anteprima','files.save':'Salva','files.saved':'✓ salvato','files.saveError':'Impossibile salvare questo file.','files.loadError':'Impossibile caricare questo file.','files.binary':'Questo file non può essere visualizzato qui (non è testo).','files.discardConfirm':'Scartare le modifiche non salvate?','files.newFilePrompt':'Percorso del nuovo file (es. notes/todo.md):','files.newFolderPrompt':'Percorso della nuova cartella:','files.refresh':'Aggiorna','files.discard':'Scarta','files.create':'Crea',
+  'drawer.loading':'Caricamento…','drawer.loadError':'Impossibile caricare questo file.','files.title':'File','files.sub':'Sfoglia i file del progetto — visualizza Markdown e HTML, modifica qualsiasi file di testo, creane di nuovi.','files.newFile':'+ File','files.newFolder':'+ Cartella','files.pickFile':'Seleziona un file per visualizzarlo.','files.empty':'Nessun file ancora.','files.edit':'Modifica','files.preview':'Anteprima','files.save':'Salva','files.saved':'✓ salvato','files.saveError':'Impossibile salvare questo file.','files.loadError':'Impossibile caricare questo file.','files.binary':'Questo file non può essere visualizzato qui (non è testo).','files.discardConfirm':'Scartare le modifiche non salvate?','files.newFilePrompt':'Nome del nuovo file (es. todo.md):','files.newFolderPrompt':'Nome della nuova cartella:','files.projectRoot':'radice del progetto','files.creatingIn':'Creazione in: {path}','files.refresh':'Aggiorna','files.discard':'Scarta','files.create':'Crea',
   'chat.widgetTitle':'Avvia un agente','chat.widgetSub':'Accesso rapido · vista completa nella scheda Chat',
   'chat.tabSub':'Conversazione completa con l’esecutore — la stessa esecuzione del widget, con più spazio per leggerla.',
   'chat.idle':'Digita una richiesta — l’agente viene eseguito senza supervisione in questo progetto con tutta la sua memoria (<code>CLAUDE.md → AGENTS.md</code>) e aggiorna la bacheca in diretta.',

package/templates/dashboard/public/index.html

@@ -226,6 +226,7 @@
               <button id="filesRefresh" class="btn" type="button" title="Refresh" data-i18n-title="files.refresh">⟳</button>
             </div>
             <div class="files-create-form" id="filesCreateForm" hidden>
+              <div class="files-create-target" id="filesCreateTarget"></div>
               <input type="text" id="filesCreateInput" class="bl-add-input" autocomplete="off" />
               <div class="files-create-actions">
                 <button id="filesCreateGo" class="btn primary" type="button" data-i18n="files.create">Create</button>
@@ -233,6 +234,7 @@
               </div>
               <span class="files-error-tip" id="filesCreateError" hidden></span>
             </div>
+            <div class="f-row f-root" id="filesRootRow" tabindex="0" data-i18n="files.projectRoot">project root</div>
             <div class="files-tree" id="filesTree"></div>
           </div>
           <div class="files-content-col" id="filesContent">

package/templates/dashboard/public/styles.css

@@ -294,7 +294,7 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .team-wrap { max-width:1500px; } /* the agent/skill .cards grid fills more columns instead of sitting capped */
 
 /* Files tab — a two-pane explorer: a collapsible tree, and the selected file's preview/editor */
-.files-wrap { padding:26px 28px 60px; max-width:1600px; height:calc(100vh - 130px); display:flex; flex-direction:column; }
+.files-wrap { padding:26px 28px 16px; max-width:1600px; height:calc(100vh - 90px); display:flex; flex-direction:column; }
 .files-body { flex:1; min-height:0; display:flex; gap:16px; margin-top:8px; }
 .files-tree-col { width:280px; flex-shrink:0; display:flex; flex-direction:column; gap:8px; min-height:0; }
 .files-toolbar { display:flex; gap:8px; }
@@ -313,6 +313,9 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .f-row { display:flex; align-items:center; gap:6px; padding:4px 6px; border-radius:6px; cursor:pointer; font-size:12.5px; white-space:nowrap; color:var(--muted); }
 .f-row:hover { background:var(--surface-2); color:var(--ink); }
 .f-row.is-active { background:var(--surface-2); color:var(--signal); font-weight:600; }
+.f-row.is-target { background:color-mix(in srgb,var(--signal) 14%,transparent); color:var(--ink); } /* the folder new files/folders will be created in */
+.f-root { font-weight:600; margin-bottom:4px; padding-bottom:6px; border-bottom:1px solid var(--line); border-radius:0; }
+.files-create-target { font-size:11px; color:var(--muted); font-family:var(--mono); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
 .f-row .f-chevron { width:11px; height:11px; flex-shrink:0; transition:transform .15s; color:var(--faint); }
 .f-row.is-open .f-chevron { transform:rotate(90deg); }
 .f-row .f-name { overflow:hidden; text-overflow:ellipsis; }
@@ -329,6 +332,23 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .files-view::-webkit-scrollbar-track,.files-editor::-webkit-scrollbar-track { background:transparent; }
 .files-view { flex:1; min-height:0; overflow:auto; padding:16px 20px; }
 .files-editor { flex:1; min-height:0; width:100%; border:0; resize:none; padding:16px 20px; font-family:var(--mono); font-size:12.5px; line-height:1.6; background:var(--surface); color:var(--ink); outline:none; }
+/* syntax-highlighted editor: a transparent textarea (real caret, real selection, real typing) sits
+   exactly on top of a highlighted <pre><code> backdrop showing through it — the standard technique
+   for highlighting without a full editor component. Both share identical font metrics so characters
+   line up; the backdrop never scrolls on its own (overflow:hidden), its scroll position is just
+   copied from the textarea on every scroll event. */
+.files-code-wrap { position:relative; flex:1; min-height:0; }
+/* Ligatures (calt/liga — e.g. "===", "!==", "=>" fused into one glyph, common in Cascadia Code and
+   JetBrains Mono) must be off on BOTH layers: this overlay depends on the backdrop and the textarea
+   laying out every character at an identical pixel width, and a fused ligature glyph breaks that. */
+.files-code-backdrop { position:absolute; inset:0; margin:0; overflow:hidden; pointer-events:none; white-space:pre-wrap; word-break:break-word; padding:16px 20px; font-family:var(--mono); font-size:12.5px; line-height:1.6; color:var(--ink); background:transparent; font-variant-ligatures:none; font-feature-settings:"liga" 0,"calt" 0; }
+.files-code-backdrop code { font:inherit; background:none; }
+.files-code-wrap .files-code-input { position:absolute; inset:0; background:transparent; color:transparent; caret-color:var(--ink); white-space:pre-wrap; word-break:break-word; font-variant-ligatures:none; font-feature-settings:"liga" 0,"calt" 0; }
+.hl-comment { color:var(--faint); font-style:italic; }
+.hl-string { color:var(--s-done); }
+.hl-number { color:var(--cool); }
+.hl-keyword { color:var(--signal); font-weight:600; }
+.hl-tag { color:var(--s-in_progress); }
 .files-iframe { flex:1; min-height:0; width:100%; border:0; background:#fff; }
 .files-md-toolbar { display:flex; gap:6px; padding:8px 14px; border-bottom:1px solid var(--line); }
 .files-md-toolbar button { font-family:var(--mono); font-size:12px; padding:4px 9px; border:1px solid var(--line); border-radius:6px; background:var(--surface-2); color:var(--ink); cursor:pointer; }

package/templates/dashboard/server.js

@@ -1,256 +1,43 @@
 'use strict';
 /*
- * spectoflow dashboard — ZERO-DEPENDENCY server, real-time (SSE + fs.watch).
- * v0.4 adds an agent launcher: POST /api/run spawns the configured agent headless in the project
- * root (with project memory: CLAUDE.md → AGENTS.md), streams its output over SSE, and records the
- * run in .spectoflow/runtime.json. As the agent edits plans/*.md, the board refreshes live.
+ * spectoflow dashboard — ZERO-DEPENDENCY server, real-time (SSE + fs.watch), single project.
+ * The actual /api/* route behavior lives in ./handlers.js — split out so the future multi-project hub
+ * (lib/hub-server.js) can load a different project's handlers.js on demand (see
+ * docs/multi-project-hub-design.md's "the server must split in two" addendum). This file remains the
+ * direct single-project entry point (`node .spectoflow/dashboard/server.js`, today's `spectoflow
+ * dashboard`) — its own external behavior is unchanged by the split.
  */
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
-const store = require('../lib/store');
-const { startRun } = require('./runner');
-const { runSummarize } = require('./summarize');
-const orchestrator = require('./orchestrator');
-const agentsRegistry = require('../lib/agents-registry');
-const files = require('./files');
+const { createHandlers } = require('./handlers');
 
 const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : 4319;
 const PUBLIC = path.join(__dirname, 'public');
 const ROOT = process.env.SPECTOFLOW_ROOT || path.resolve(__dirname, '..', '..');
 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' };
 const clients = new Set();
-
-// Installed framework version: the manifest records it at init/update time. Fallback to the kit's
-// own package.json — only reachable (and only used) when the server is run straight from templates/
-// (dev/preview), never from an installed project whose sibling package.json belongs to the user.
-function frameworkVersion(){
-  try { return JSON.parse(fs.readFileSync(path.join(ROOT, '.spectoflow', '.manifest.json'), 'utf8')).version; } catch {}
-  try { const pk = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')); if (pk.name === 'spectoflow') return pk.version; } catch {}
-  return null;
-}
-function project(){
-  const p = store.readProject(ROOT);
-  const v = frameworkVersion(); if (v) p.version = v;
-  p.projectName = path.basename(ROOT); // the actual project folder, always shown in the topbar
-  // Known vs. actually-installed agents — the topbar switcher needs both: the full list to offer,
-  // and which ones are real (bin on PATH, or the project already has that agent's config dir) so it
-  // can refuse to activate one that isn't there.
-  p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label, headless: a.headless, docsUrl: a.docsUrl }));
-  p.installedAgents = agentsRegistry.installedAgents(ROOT);
-  return p;
-}
 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({});} }); }); }
 function emit(obj){ const line='data: '+JSON.stringify(obj)+'\n\n'; for(const res of clients) res.write(line); }
-function findPlanFileForTask(id){ for(const pl of store.readPlans(ROOT)) for(const ph of pl.phases) if(ph.tasks.find(t=>t.id===id)) return pl.file; return null; }
 
-// ---- helpers for settings + attention points -----------------------------
-const configPath = () => path.join(ROOT, '.spectoflow', 'config.json');
-function writeConfig(patch){
-  const cp = configPath(); const cfg = JSON.parse(fs.readFileSync(cp, 'utf8'));
-  if (patch.mode && ['autopilot','semi','manual'].includes(patch.mode)) cfg.mode = patch.mode;
-  if (typeof patch.language === 'string' && patch.language.trim()) cfg.language = patch.language.trim();
-  if (typeof patch.design === 'string' && /^[a-z0-9-]{1,40}$/.test(patch.design)) cfg.design = patch.design;
-  if (typeof patch.agent === 'string' && patch.agent.trim()) {
-    const id = patch.agent.trim();
-    // Never activate an agent whose CLI isn't actually there — a picked-but-absent agent would just
-    // fail silently the next time something tries to run it.
-    if (!agentsRegistry.isAgentInstalled(id, ROOT)) {
-      const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
-      const label = known ? known.label : id;
-      throw new Error(`${label} isn't installed here (its command wasn't found on PATH). Install it, then try again.`);
-    }
-    cfg.agent = id;
-    // Seed a default runner if this agent was never configured (e.g. installed after init/update).
-    // A headless:false agent (e.g. kimi) has no runner to seed — it can still be the active agent,
-    // it just can't be spawned by Run/Orchestrate/Summarize (disabled client-side; runner.js and
-    // summarize.js also refuse server-side either way).
-    const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
-    if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
-  }
-  fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
-  return cfg;
-}
-// Promote an attention item into a real checkbox task under an `## Attention` phase.
-function promoteAttention(item){
-  return store.addTask(ROOT, { phase: 'Attention', title: item.text, owner: 'user' });
-}
+const handlers = createHandlers(ROOT);
 
 function watch(dir){ try{ fs.watch(dir,{recursive:false},()=>emit({type:'change'})); }catch(_){} }
-// Custom dashboards (Customize page) live in their own subdirectory of .spectoflow, which the
-// top-level `.spectoflow` watch below does NOT cover — fs.watch here is non-recursive on purpose
-// (a recursive watch on the whole .spectoflow tree would also fire on every runtime.json write).
-// Ensure the directory exists before watching it: a project that hasn't used Customize yet won't
-// have it on disk, and `spectoflow init` on an older install won't have created it either.
-try { fs.mkdirSync(path.join(ROOT,'.spectoflow','dashboard','custom'), { recursive: true }); } catch (_) {}
-['plans','specs','.spectoflow','.spectoflow/dashboard/custom'].forEach(d=>{ const p=path.join(ROOT,d); if(fs.existsSync(p)) watch(p); });
-
-// A process restart loses any in-flight orchestration; without this, a stale 'running' or
-// 'awaiting_approval' status wedges the /api/orchestrate 409 guard forever. Not a real
-// resume — just clears the wedge so a fresh orchestration can start.
-try { orchestrator.reconcileOnBoot(ROOT); } catch {}
+handlers.onBoot();
+handlers.watchDirs.forEach((d)=>{ const p=path.join(ROOT,d); if(fs.existsSync(p)) watch(p); });
 
 const server = http.createServer(async (req,res)=>{
   const u=new URL(req.url,`http://localhost:${PORT}`); const p=u.pathname;
   try{
-    if(p==='/api/project') return sendJSON(res,200,project());
-
-    // ---- read-only agent/skill file viewer (scoped to .spectoflow/{agents,skills}/**) ----
-    if (p === '/api/agentfile' && req.method === 'GET') {
-      const rel = new URL(req.url, 'http://x').searchParams.get('path') || '';
-      const base = path.join(ROOT, '.spectoflow');
-      const aDir = path.join(base, 'agents'), sDir = path.join(base, 'skills');
-      const abs = path.resolve(base, rel);
-      const okDir = abs.startsWith(aDir + path.sep) || abs.startsWith(sDir + path.sep);
-      if (!okDir || !abs.endsWith('.md') || !fs.existsSync(abs) || fs.statSync(abs).isDirectory())
-        return sendJSON(res, 400, { error: 'not an agent/skill file' });
-      // Symlink guard: the resolved real path must stay within the (real) scope dirs.
-      let real; try { real = fs.realpathSync(abs); } catch { real = null; }
-      const realA = (() => { try { return fs.realpathSync(aDir); } catch { return aDir; } })();
-      const realS = (() => { try { return fs.realpathSync(sDir); } catch { return sDir; } })();
-      const okReal = real && (real.startsWith(realA + path.sep) || real.startsWith(realS + path.sep));
-      if (!okReal || !real.endsWith('.md') || fs.statSync(real).isDirectory())
-        return sendJSON(res, 400, { error: 'not an agent/skill file' });
-      return sendJSON(res, 200, { content: fs.readFileSync(real, 'utf8') });
-    }
-
-    // ---- File Explorer: browse/read/write/create anywhere under the project root ----
-    if (p === '/api/files/tree' && req.method === 'GET') return sendJSON(res, 200, { tree: files.tree(ROOT) });
-    if (p === '/api/files/read' && req.method === 'GET') {
-      const rel = new URL(req.url, 'http://x').searchParams.get('path') || '';
-      const r = files.readFile(ROOT, rel);
-      return sendJSON(res, r.error ? 400 : 200, r);
-    }
-    if (p === '/api/files/write' && req.method === 'POST') {
-      const { path: rel, content } = await body(req);
-      const r = files.writeFile(ROOT, rel, content);
-      if (r.error) return sendJSON(res, 400, r);
-      emit({ type: 'change' }); return sendJSON(res, 200, r);
-    }
-    if (p === '/api/files/mkdir' && req.method === 'POST') {
-      const { path: rel } = await body(req);
-      const r = files.mkdir(ROOT, rel);
-      if (r.error) return sendJSON(res, 400, r);
-      emit({ type: 'change' }); return sendJSON(res, 200, r);
-    }
-
     if(p==='/api/events'){
       res.writeHead(200,{'Content-Type':'text/event-stream','Cache-Control':'no-cache',Connection:'keep-alive'});
       res.write('data: '+JSON.stringify({type:'hello'})+'\n\n');
       clients.add(res); req.on('close',()=>clients.delete(res)); return;
     }
 
-    // ---- manual task creation: add a checkbox task straight to a plan, no agent involved ----
-    if(p==='/api/task'&&req.method==='POST'){
-      const { title, phase, file, owner, level } = await body(req);
-      if(!title||!String(title).trim()) return sendJSON(res,400,{error:'A title is required.'});
-      const t = store.addTask(ROOT,{ title:String(title).trim(), phase, file, owner, level });
-      emit({type:'change'}); return sendJSON(res,200,{task:t});
-    }
-    if(p.startsWith('/api/task/')&&req.method==='PATCH'){
-      const id=decodeURIComponent(p.split('/')[3]||''); const patch=await body(req);
-      const file=findPlanFileForTask(id); if(!file) return sendJSON(res,404,{error:`Task ${id} not found.`});
-      store.updateTaskLine(ROOT,file,id,patch); emit({type:'change'}); return sendJSON(res,200,{ok:true});
-    }
-    if(/^\/api\/task\/[^/]+\/comment$/.test(p)&&req.method==='POST'){
-      const id=decodeURIComponent(p.split('/')[3]||''); const {text,action}=await body(req);
-      if(!text||!String(text).trim()) return sendJSON(res,400,{error:'Empty comment.'});
-      const file=findPlanFileForTask(id); if(!file) return sendJSON(res,404,{error:`Task ${id} not found.`});
-      store.addTaskComment(ROOT,file,id,String(text).trim(),'me');
-      if(action==='analyze') store.updateTaskLine(ROOT,file,id,{status:'to_analyze'});
-      emit({type:'change'}); return sendJSON(res,200,{ok:true});
-    }
-    if(p==='/api/workflow/toggle'&&req.method==='POST'){
-      const {name}=await body(req); const wf=path.join(ROOT,'.spectoflow','workflow.md');
-      const lines=fs.readFileSync(wf,'utf8').split('\n');
-      for(let i=0;i<lines.length;i++){ const m=lines[i].match(/^(\s*- \[)( |x|X)(\]\s+)(.*)$/);
-        if(m&&m[4].replace(/\s*\(optional\)\s*$/i,'').trim()===name) lines[i]=m[1]+(m[2].trim()?' ':'x')+m[3]+m[4]; }
-      fs.writeFileSync(wf,lines.join('\n')); emit({type:'change'}); return sendJSON(res,200,{ok:true});
-    }
-
-    // ---- agent launcher (pipeline lives in runner.js; posts to the group-chat log) ----
-    if(p==='/api/run'&&req.method==='POST'){
-      const {prompt,agent}=await body(req);
-      if(!prompt||!String(prompt).trim()) return sendJSON(res,400,{error:'Empty request.'});
-      const r=startRun(ROOT,{prompt,agent},emit);
-      if(r.error) return sendJSON(res,400,{error:r.error});
-      return sendJSON(res,200,{runId:r.runId});
-    }
-
-    // ---- chat context management: condense the log via the agent, or wipe it ----
-    if (p === '/api/chat/summarize' && req.method === 'POST') {
-      const { agent } = await body(req);
-      const r = runSummarize(ROOT, { agent }, emit);
-      if (r.error) return sendJSON(res, 400, { error: r.error });
-      return sendJSON(res, 200, { ok: true });
-    }
-    if (p === '/api/chat/clear' && req.method === 'POST') {
-      const rt = store.readRuntime(ROOT); rt.messages = []; store.writeRuntime(ROOT, rt);
-      emit({ type: 'change' });
-      return sendJSON(res, 200, { ok: true });
-    }
-
-    // ---- orchestrator ----
-    if (p === '/api/orchestrate' && req.method === 'POST') {
-      const { request } = await body(req);
-      if (!request || !String(request).trim()) return sendJSON(res, 400, { error: 'Empty request.' });
-      const active = store.readRuntime(ROOT).orchestration;
-      if (active && ['running', 'awaiting_approval'].includes(active.status))
-        return sendJSON(res, 409, { error: 'An orchestration is already active.' });
-      const mode = store.readConfig(ROOT).mode || 'semi';
-      // fire and forget; state + messages stream over SSE
-      orchestrator.runOrchestration({ root: ROOT, request: String(request).trim(), mode,
-        runStep: orchestrator.defaultRunStep, confirm: orchestrator.defaultConfirm }, emit)
-        .catch((e) => emit({ type: 'message', message: { role: 'orchestrator', kind: 'status', text: 'orchestration error: ' + e.message } }));
-      const o = store.readRuntime(ROOT).orchestration;
-      return sendJSON(res, 200, { orchestrationId: o && o.id });
-    }
-    if (p === '/api/orchestrate/approve' && req.method === 'POST') {
-      const { decision, note } = await body(req);
-      const ok = orchestrator.submitDecision(decision, note);
-      return sendJSON(res, ok ? 200 : 409, ok ? { ok: true } : { error: 'No pending approval.' });
-    }
-
-    // ---- settings: change autonomy mode + output language (writes config.json) ----
-    if (p === '/api/settings' && req.method === 'POST') {
-      const patch = await body(req);
-      try { const cfg = writeConfig(patch); emit({ type: 'change' }); return sendJSON(res, 200, { config: cfg }); }
-      catch (e) { return sendJSON(res, 400, { error: String(e && e.message || e) }); }
-    }
-
-    // ---- attention points: agent- or user-raised notes; validate → real task ----
-    if (p === '/api/attention' && req.method === 'POST') {
-      const { text } = await body(req);
-      if (!text || !String(text).trim()) return sendJSON(res, 400, { error: 'Empty note.' });
-      const rt = store.readRuntime(ROOT); rt.attention = rt.attention || [];
-      const item = { id: 'att' + Date.now().toString(36), at: new Date().toISOString(), by: 'me', source: 'user', status: 'open', text: String(text).trim() };
-      rt.attention.unshift(item); store.writeRuntime(ROOT, rt); emit({ type: 'change' });
-      return sendJSON(res, 200, { item });
-    }
-    if (/^\/api\/attention\/[^/]+\/promote$/.test(p) && req.method === 'POST') {
-      const id = decodeURIComponent(p.split('/')[3] || '');
-      const rt = store.readRuntime(ROOT); const it = (rt.attention || []).find((x) => x.id === id);
-      if (!it) return sendJSON(res, 404, { error: 'Note not found.' });
-      const t = promoteAttention(it); it.status = 'resolved'; it.promotedTo = t.id;
-      store.writeRuntime(ROOT, rt); emit({ type: 'change' });
-      return sendJSON(res, 200, { task: t });
-    }
-    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'PATCH') {
-      const id = decodeURIComponent(p.split('/')[3] || '');
-      const patch = await body(req);
-      const rt = store.readRuntime(ROOT); const it = (rt.attention || []).find((x) => x.id === id);
-      if (!it) return sendJSON(res, 404, { error: 'Note not found.' });
-      if (typeof patch.text === 'string' && patch.text.trim()) it.text = patch.text.trim();
-      if (patch.status && ['open', 'resolved'].includes(patch.status)) it.status = patch.status;
-      store.writeRuntime(ROOT, rt); emit({ type: 'change' });
-      return sendJSON(res, 200, { item: it });
-    }
-    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'DELETE') {
-      const id = decodeURIComponent(p.split('/')[3] || '');
-      const rt = store.readRuntime(ROOT); rt.attention = (rt.attention || []).filter((x) => x.id !== id);
-      store.writeRuntime(ROOT, rt); emit({ type: 'change' });
-      return sendJSON(res, 200, { ok: true });
+    if (p.startsWith('/api/')) {
+      const handled = await handlers.handleApi(req, res, u, emit);
+      if (handled) return;
     }
 
     // ---- static files, with SPA fallback: a route like /backlog (no file extension)