spectoflow 0.23.5 → 0.27.0

package/lib/dashboard/public/vendor/prism/prism-yaml.min.js

@@ -0,0 +1 @@
+!function(e){var n=/[*&][^\s[\]{},]+/,r=/!(?:<[\w\-%#;/?:@&=+$,.!~*'()[\]]+>|(?:[a-zA-Z\d-]*!)?[\w\-%#;/?:@&=+$.~*'()]+)?/,t="(?:"+r.source+"(?:[ \t]+"+n.source+")?|"+n.source+"(?:[ \t]+"+r.source+")?)",a="(?:[^\\s\\x00-\\x08\\x0e-\\x1f!\"#%&'*,\\-:>?@[\\]`{|}\\x7f-\\x84\\x86-\\x9f\\ud800-\\udfff\\ufffe\\uffff]|[?:-]<PLAIN>)(?:[ \t]*(?:(?![#:])<PLAIN>|:<PLAIN>))*".replace(/<PLAIN>/g,(function(){return"[^\\s\\x00-\\x08\\x0e-\\x1f,[\\]{}\\x7f-\\x84\\x86-\\x9f\\ud800-\\udfff\\ufffe\\uffff]"})),d="\"(?:[^\"\\\\\r\n]|\\\\.)*\"|'(?:[^'\\\\\r\n]|\\\\.)*'";function o(e,n){n=(n||"").replace(/m/g,"")+"m";var r="([:\\-,[{]\\s*(?:\\s<<prop>>[ \t]+)?)(?:<<value>>)(?=[ \t]*(?:$|,|\\]|\\}|(?:[\r\n]\\s*)?#))".replace(/<<prop>>/g,(function(){return t})).replace(/<<value>>/g,(function(){return e}));return RegExp(r,n)}e.languages.yaml={scalar:{pattern:RegExp("([\\-:]\\s*(?:\\s<<prop>>[ \t]+)?[|>])[ \t]*(?:((?:\r?\n|\r)[ \t]+)\\S[^\r\n]*(?:\\2[^\r\n]+)*)".replace(/<<prop>>/g,(function(){return t}))),lookbehind:!0,alias:"string"},comment:/#.*/,key:{pattern:RegExp("((?:^|[:\\-,[{\r\n?])[ \t]*(?:<<prop>>[ \t]+)?)<<key>>(?=\\s*:\\s)".replace(/<<prop>>/g,(function(){return t})).replace(/<<key>>/g,(function(){return"(?:"+a+"|"+d+")"}))),lookbehind:!0,greedy:!0,alias:"atrule"},directive:{pattern:/(^[ \t]*)%.+/m,lookbehind:!0,alias:"important"},datetime:{pattern:o("\\d{4}-\\d\\d?-\\d\\d?(?:[tT]|[ \t]+)\\d\\d?:\\d{2}:\\d{2}(?:\\.\\d*)?(?:[ \t]*(?:Z|[-+]\\d\\d?(?::\\d{2})?))?|\\d{4}-\\d{2}-\\d{2}|\\d\\d?:\\d{2}(?::\\d{2}(?:\\.\\d*)?)?"),lookbehind:!0,alias:"number"},boolean:{pattern:o("false|true","i"),lookbehind:!0,alias:"important"},null:{pattern:o("null|~","i"),lookbehind:!0,alias:"important"},string:{pattern:o(d),lookbehind:!0,greedy:!0},number:{pattern:o("[+-]?(?:0x[\\da-f]+|0o[0-7]+|(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:e[+-]?\\d+)?|\\.inf|\\.nan)","i"),lookbehind:!0},tag:r,important:n,punctuation:/---|[:[\]{}\-,|>?]|\.\.\./},e.languages.yml=e.languages.yaml}(Prism);

package/lib/dashboard/routes.js

@@ -0,0 +1,38 @@
+'use strict';
+/*
+ * The dashboard's HTTP route table — method + path → op name + args extraction — with NO reference
+ * to ops.js. Two consumers share it: handlers.js (local hub, calls ops directly) and the online
+ * relay server (server/src/relay.js), which turns the same rows into `op` frames sent to the machine.
+ * Keeping it dependency-free is what lets the server require it without loading ops.js (which
+ * would drag in the runner, the orchestrator, agent detection… none of which exist server-side).
+ */
+const seg = (p, i) => decodeURIComponent(p.split('/')[i] || '');
+const q = (u, k) => u.searchParams.get(k) || '';
+// [method, matcher, op, args(u, body, pathname)]
+const ROUTES = [
+  ['GET', '/api/project', 'project.read', () => ({})],
+  ['GET', '/api/agentfile', 'agentfile.read', (u) => ({ path: q(u, 'path') })],
+  ['GET', '/api/files/tree', 'files.tree', () => ({})],
+  ['GET', '/api/files/read', 'files.read', (u) => ({ path: q(u, 'path') })],
+  ['POST', '/api/files/write', 'files.write', (_u, b) => b],
+  ['POST', '/api/files/mkdir', 'files.mkdir', (_u, b) => b],
+  ['POST', '/api/task', 'task.add', (_u, b) => b],
+  ['PATCH', /^\/api\/task\/[^/]+$/, 'task.update', (_u, b, p) => ({ id: seg(p, 3), patch: b })],
+  ['POST', /^\/api\/task\/[^/]+\/comment$/, 'task.comment', (_u, b, p) => ({ id: seg(p, 3), text: b.text, action: b.action })],
+  ['POST', '/api/workflow/toggle', 'workflow.toggle', (_u, b) => b],
+  ['POST', '/api/run', 'run.start', (_u, b) => b],
+  ['POST', '/api/chat/summarize', 'chat.summarize', (_u, b) => b],
+  ['POST', '/api/meeting/generate', 'meeting.generate', (_u, b) => b],
+  ['POST', '/api/chat/clear', 'chat.clear', () => ({})],
+  ['POST', '/api/orchestrate', 'orchestrate.start', (_u, b) => b],
+  ['POST', '/api/orchestrate/approve', 'orchestrate.approve', (_u, b) => b],
+  ['POST', '/api/settings', 'settings.save', (_u, b) => b],
+  ['POST', '/api/attention', 'attention.add', (_u, b) => b],
+  ['POST', /^\/api\/attention\/[^/]+\/promote$/, 'attention.promote', (_u, _b, p) => ({ id: seg(p, 3) })],
+  ['PATCH', /^\/api\/attention\/[^/]+$/, 'attention.update', (_u, b, p) => ({ id: seg(p, 3), patch: b })],
+  ['DELETE', /^\/api\/attention\/[^/]+$/, 'attention.remove', (_u, _b, p) => ({ id: seg(p, 3) })],
+];
+const matches = (m, p) => (typeof m === 'string' ? m === p : m.test(p));
+const findRoute = (method, pathname) => ROUTES.find(([m, matcher]) => m === method && matches(matcher, pathname));
+
+module.exports = { ROUTES, seg, q, matches, findRoute };

package/{templates → lib}/dashboard/runner.js

@@ -5,11 +5,12 @@
  * printing sentinel lines (::spectoflow role=… kind=… msg=…) which become structured messages;
  * any other output streams raw as run-line events. `emit` publishes SSE events to the dashboard.
  *
- * Kept separate from server.js so the pipeline is unit-testable without an HTTP server.
+ * Kept separate from the HTTP layer so the pipeline is unit-testable without a server.
  */
 const { spawn } = require('child_process');
-const store = require('../lib/store');
-const agentsRegistry = require('../lib/agents-registry');
+const store = require('../store');
+const adapters = require('../adapters');
+const detect = require('../detect');
 
 // The command to run `which`: config.json's own runners map first (an explicit user choice always
 // wins), falling back to the registry's default for a known, headless-capable, genuinely-installed
@@ -17,8 +18,8 @@ const agentsRegistry = require('../lib/agents-registry');
 // the project's "active agent" and had a runner seeded into config.json for it.
 function resolveRunnerCommand(root, cfg, which, opts) {
   if (cfg.runners && cfg.runners[which]) return cfg.runners[which];
-  const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === which);
-  if (known && known.runner && agentsRegistry.isAgentInstalled(which, root, opts)) return known.runner;
+  const known = adapters.knownAgents().find((a) => a.id === which);
+  if (known && known.runner && detect.isAgentInstalled(which, root, opts)) return known.runner;
   return null;
 }
 
@@ -59,7 +60,8 @@ function pushAttention(root, text, by) {
 // Start an agent run. Returns { runId, child } or { error } if no runner is configured.
 // logPrompt:false suppresses echoing the prompt as a user bubble — used by the orchestrator,
 // whose priming prompt ("You are the …") is machinery the user shouldn't have to read.
-function startRun(root, { prompt, agent, logPrompt = true }, emit) {
+// display: when a non-empty string, the chat bubble shows this while the child still receives prompt.
+function startRun(root, { prompt, agent, logPrompt = true, display }, emit) {
   const cfg = store.readConfig(root);
   const which = agent || cfg.agent || 'claude';
   const cmdStr = resolveRunnerCommand(root, cfg, which);
@@ -67,9 +69,13 @@ function startRun(root, { prompt, agent, logPrompt = true }, emit) {
   const parts = cmdStr.split(/\s+/).filter(Boolean);
   const runId = 'r' + Date.now().toString(36);
   const p = String(prompt).trim();
+  // The chat bubble can show a shorter, friendlier text than what the agent actually receives — e.g.
+  // a slash-command invocation "/rapport_jour focus bugs" instead of the full expanded instruction.
+  // The child (line ~84) always spawns with `p`, the real prompt.
+  const shown = (typeof display === 'string' && display.trim()) ? display.trim() : p;
 
   if (logPrompt) {
-    const um = store.appendMessage(root, { role: 'user', kind: 'message', text: p, agent: which, runId });
+    const um = store.appendMessage(root, { role: 'user', kind: 'message', text: shown, agent: which, runId });
     emit({ type: 'message', message: um });
   }
 

package/{templates → lib}/dashboard/summarize.js

@@ -7,7 +7,7 @@
  * sitting right below it doesn't condense anything — it just adds noise on top of noise.
  */
 const { spawn } = require('child_process');
-const store = require('../lib/store');
+const store = require('../store');
 const { resolveRunnerCommand } = require('./runner');
 
 const DEFAULT_LIMIT = 40;

package/lib/detect.js

@@ -31,4 +31,19 @@ function detectAgents(projectRoot, opts = {}) {
   }).map((a) => a.id);
 }
 
-module.exports = { binOnPath, detectAgents };
+// True if `id` looks genuinely installed: its bin resolves on PATH, or the project already has its
+// config dir (a project can be set up for an agent whose bin isn't on THIS machine's PATH, e.g. a
+// remote/CI runner). Unknown ids are never "installed".
+function isAgentInstalled(id, projectRoot, opts) {
+  const a = REGISTRY.find((x) => x.id === id);
+  if (!a) return false;
+  if (a.detect.bin && binOnPath(a.detect.bin, opts)) return true;
+  return (a.detect.dirs || []).some((d) => fs.existsSync(path.join(projectRoot, d)));
+}
+
+// ids of every known agent actually installed for this project, in REGISTRY (priority) order.
+function installedAgents(projectRoot, opts) {
+  return REGISTRY.filter((a) => isAgentInstalled(a.id, projectRoot, opts)).map((a) => a.id);
+}
+
+module.exports = { binOnPath, detectAgents, isAgentInstalled, installedAgents };

package/lib/global-config.js

@@ -0,0 +1,65 @@
+'use strict';
+/*
+ * Global config — ~/.spectoflow/config.json (or $SPECTOFLOW_HOME/config.json). Settings that apply
+ * to every project on this machine: where the dashboard workspace lives, which dashboard URL
+ * projects talk to, and the defaults `spectoflow init` seeds a new project's config.json with.
+ * Layering, lowest to highest: kit templates < these defaults < the project's own config.json.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { REGISTRY } = require('./adapters');
+
+const KEYS = ['dashboard.url', 'dashboard.path', 'defaults.agent', 'defaults.language', 'defaults.mode', 'defaults.design'];
+const MODES = ['autopilot', 'semi', 'manual'];
+
+function homeDir() { return process.env.SPECTOFLOW_HOME || path.join(os.homedir(), '.spectoflow'); }
+function configPath() { return path.join(homeDir(), 'config.json'); }
+function defaultDashboardPath() { return path.join(homeDir(), 'dashboard'); }
+function expandHome(p) { return p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p; }
+
+function defaults() {
+  return { dashboard: { url: 'http://localhost:4319', path: defaultDashboardPath() }, defaults: { agent: 'claude', language: 'en', mode: 'semi', design: 'console' } };
+}
+function readRaw() {
+  try { return JSON.parse(fs.readFileSync(configPath(), 'utf8')) || {}; } catch { return {}; }
+}
+function writeRaw(obj) {
+  fs.mkdirSync(homeDir(), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(obj, null, 2) + '\n');
+}
+const getPath = (obj, key) => key.split('.').reduce((o, k) => (o && o[k] !== undefined ? o[k] : undefined), obj);
+const setPath = (obj, key, value) => { const ks = key.split('.'); let o = obj; for (const k of ks.slice(0, -1)) o = (o[k] = o[k] || {}); o[ks[ks.length - 1]] = value; };
+
+function read() {
+  const d = defaults(), raw = readRaw();
+  return { dashboard: { ...d.dashboard, ...(raw.dashboard || {}) }, defaults: { ...d.defaults, ...(raw.defaults || {}) } };
+}
+function get(key) {
+  if (!KEYS.includes(key)) throw new Error(`unknown key "${key}" — valid keys: ${KEYS.join(', ')}`);
+  const raw = getPath(readRaw(), key);
+  return raw !== undefined ? { value: raw, source: 'set' } : { value: getPath(defaults(), key), source: 'default' };
+}
+function list() { return KEYS.map((key) => ({ key, ...get(key) })); }
+
+function validate(key, value) {
+  const v = String(value).trim();
+  switch (key) {
+    case 'dashboard.url': { let u; try { u = new URL(v); } catch { throw new Error('dashboard.url must be a URL, e.g. http://localhost:4319'); } if (!/^https?:$/.test(u.protocol)) throw new Error('dashboard.url must start with http:// or https://'); return u.origin; }
+    case 'dashboard.path': { if (!v) throw new Error('dashboard.path must be a folder path'); return path.resolve(expandHome(v)); }
+    case 'defaults.agent': { if (!REGISTRY.some((a) => a.id === v)) throw new Error(`unknown agent "${v}" — one of: ${REGISTRY.map((a) => a.id).join(', ')}`); return v; }
+    case 'defaults.language': { if (!/^[a-z]{2}$/.test(v)) throw new Error('defaults.language must be a 2-letter code (en, fr, es, de, pt, it…)'); return v; }
+    case 'defaults.mode': { if (!MODES.includes(v)) throw new Error(`defaults.mode must be one of: ${MODES.join(', ')}`); return v; }
+    case 'defaults.design': { if (!/^[a-z0-9-]{1,40}$/.test(v)) throw new Error('defaults.design must be a design id (console, orbit, …)'); return v; }
+    default: throw new Error(`unknown key "${key}" — valid keys: ${KEYS.join(', ')}`);
+  }
+}
+function set(key, value) {
+  const v = validate(key, value);
+  const raw = readRaw(); setPath(raw, key, v); writeRaw(raw);
+  return v;
+}
+// Creates the file (empty object) if it doesn't exist — never touches an existing one.
+function ensure() { if (!fs.existsSync(configPath())) writeRaw({}); }
+
+module.exports = { KEYS, homeDir, configPath, defaultDashboardPath, expandHome, read, get, set, list, ensure };

package/lib/init.js

@@ -12,7 +12,8 @@ const adapters = require('./adapters');
 const ownership = require('./ownership');
 const manifest = require('./manifest');
 const mcp = require('./mcp');
-const store = require('../templates/lib/store');
+const store = require('./store');
+const globalConfig = require('./global-config');
 
 function copyDir(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
@@ -47,7 +48,7 @@ function normalizePlans(root, config) {
   return added;
 }
 
-function runInit({ target, templatesDir, version, agentsArg }) {
+function runInit({ target, templatesDir, version, agentsArg, defaults }) {
   fs.mkdirSync(target, { recursive: true });
   const notes = [];
 
@@ -79,7 +80,12 @@ function runInit({ target, templatesDir, version, agentsArg }) {
 
   const cfgPath = path.join(spectoflowDir, 'config.json');
   const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-  cfg.agent = agents[0];
+  const d = defaults || globalConfig.read().defaults;
+  cfg.mode = d.mode; cfg.language = d.language; cfg.design = d.design;
+  // The active agent: an explicit --agent wins; else the global default when it's actually detected
+  // here (or nothing is); else the first detected one.
+  cfg.agent = agentsArg ? agents[0] : ((detected.includes(d.agent) || !detected.length) ? d.agent : detected[0]);
+  if (!agents.includes(cfg.agent)) agents.unshift(cfg.agent);
   cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
   fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
 
@@ -106,7 +112,7 @@ function runInit({ target, templatesDir, version, agentsArg }) {
 
   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']) {
+  for (const line of ['.spectoflow/runtime.json']) {
     if (!giText.includes(line)) fs.appendFileSync(gi, ((fs.existsSync(gi) && fs.readFileSync(gi, 'utf8').length) ? '\n' : '') + line + '\n');
   }
 

package/lib/registry.js

@@ -1,21 +1,20 @@
 '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.
+ * The project registry — projects.json inside the dashboard workspace (see lib/workspace.js; default
+ * ~/.spectoflow/dashboard/). Tracks every project spectoflow has seen (via `spectoflow dashboard`), 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 ports or servers.
  */
 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.
+// The registry lives inside the dashboard workspace (D64). An explicit baseDir (unit tests) wins;
+// otherwise the workspace is wherever the global config says (default $SPECTOFLOW_HOME/dashboard).
 function registryDir(baseDir) {
-  return baseDir || process.env.SPECTOFLOW_HOME || path.join(os.homedir(), '.spectoflow');
+  return baseDir || require('./global-config').read().dashboard.path;
 }
 function registryPath(baseDir) {
   return path.join(registryDir(baseDir), REGISTRY_FILE);
@@ -62,6 +61,7 @@ function addProject(projectPath, baseDir) {
       path: target,
       name: path.basename(target),
       lastOpened: new Date().toISOString(),
+      kind: 'spectoflow',
     };
     reg.projects.push(entry);
   } else {

package/{templates/lib → lib}/store.js

@@ -269,19 +269,23 @@ function readWorkflow(projectRoot) {
   } catch { return []; }
 }
 
-// ---- user-generated custom dashboards (.spectoflow/dashboard/custom/<id>.json) --------------
-// One JSON file per custom dashboard page (see lib/custom-dashboard.js for the block schema this
-// validates against). A malformed file is skipped, never thrown — one bad custom dashboard must
-// never take down the whole /api/project response.
+// ---- user-generated custom views (.spectoflow/dashboards/<id>.json) ---------------------------
+// One JSON file per custom dashboard page (lib/custom-dashboard.js owns the block schema). The
+// pre-0.24 location (.spectoflow/dashboard/custom/) is still read — a project that hasn't run
+// `spectoflow update` yet must show its views — but the new folder wins on an id collision. A
+// malformed file is skipped, never thrown.
+const CUSTOM_VIEW_DIRS = [['.spectoflow', 'dashboards'], ['.spectoflow', 'dashboard', 'custom']];
 function readCustomDashboards(projectRoot) {
-  const dir = path.join(projectRoot, '.spectoflow', 'dashboard', 'custom');
-  if (!fs.existsSync(dir)) return [];
-  const out = [];
-  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
-    try {
-      const spec = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
-      if (validateSpec(spec).valid) out.push(spec);
-    } catch { /* skip malformed */ }
+  const out = []; const seen = new Set();
+  for (const parts of CUSTOM_VIEW_DIRS) {
+    const dir = path.join(projectRoot, ...parts);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
+      try {
+        const spec = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+        if (validateSpec(spec).valid && !seen.has(spec.id)) { seen.add(spec.id); out.push(spec); }
+      } catch { /* skip malformed */ }
+    }
   }
   return out;
 }

package/lib/update.js

@@ -9,7 +9,9 @@
  *   otherwise (user-edited, or legacy-divergent) . preserve; write <file>.new for manual merge
  *
  * User-owned files (config.json, workflow.md) are not in the framework set, so they are never read
- * for writing. No 3-way auto-merge and no deletions in v1 — refresh the safe, offer the rest as .new.
+ * for writing. No 3-way auto-merge for a diverged framework file — refresh the safe, offer the rest
+ * as .new. Files the kit no longer ships (retired since D64) get their own rule below: deleted only
+ * when untouched by the user, kept and reported otherwise — never via .new, and never via --force.
  */
 const fs = require('fs');
 const path = require('path');
@@ -20,6 +22,47 @@ function toDisk(sf, rel) {
   return path.join(sf, rel.split('/').join(path.sep));
 }
 
+// Files the kit shipped before 0.24 and no longer does. Used ONLY for the no-manifest hint: with a
+// manifest, retired files are computed from it, not from this list.
+const LEGACY_LEFTOVERS = ['dashboard', 'lib/store.js', 'lib/agents-registry.js', 'lib/customize-prompts.js', 'lib/custom-dashboard.js'];
+
+// Data migration (0.23 → 0.24): custom views out of the old dashboard folder, the per-project lock
+// and its .gitignore line gone. Runs before any removal, is idempotent, and never overwrites.
+function migrateProjectData(projectRoot, sf, dryRun) {
+  const r = { movedViews: [], conflicts: [], removedLock: false, gitignoreCleaned: false };
+  const oldDir = path.join(sf, 'dashboard', 'custom'), newDir = path.join(sf, 'dashboards');
+  if (fs.existsSync(oldDir)) {
+    for (const f of fs.readdirSync(oldDir).filter((x) => x.endsWith('.json')).sort()) {
+      if (fs.existsSync(path.join(newDir, f))) { r.conflicts.push(f); continue; }
+      r.movedViews.push(f);
+      if (!dryRun) { fs.mkdirSync(newDir, { recursive: true }); fs.renameSync(path.join(oldDir, f), path.join(newDir, f)); }
+    }
+    // Every view that could move did; if nothing was left behind (no conflict), the folder the
+    // retired-files loop can't see (it never tracked a data folder as a framework file) won't prune
+    // itself — do it here so an all-clear migration doesn't block dashboard/ from fully retiring.
+    if (!dryRun) { try { if (fs.readdirSync(oldDir).length === 0) fs.rmdirSync(oldDir); } catch { /* not empty, or already gone */ } }
+  }
+  const lock = path.join(sf, '.dashboard.lock');
+  if (fs.existsSync(lock)) { r.removedLock = true; if (!dryRun) fs.unlinkSync(lock); }
+  const gi = path.join(projectRoot, '.gitignore');
+  if (fs.existsSync(gi)) {
+    const lines = fs.readFileSync(gi, 'utf8').split('\n');
+    const kept = lines.filter((l) => l.trim() !== '.spectoflow/.dashboard.lock');
+    if (kept.length !== lines.length) { r.gitignoreCleaned = true; if (!dryRun) fs.writeFileSync(gi, kept.join('\n')); }
+  }
+  return r;
+}
+
+// Remove `fp`, then every now-empty parent up to (not including) `stop`.
+function removeAndPrune(fp, stop) {
+  fs.unlinkSync(fp);
+  let dir = path.dirname(fp);
+  while (dir.startsWith(stop + path.sep)) {
+    try { if (fs.readdirSync(dir).length) break; fs.rmdirSync(dir); } catch { break; }
+    dir = path.dirname(dir);
+  }
+}
+
 function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force = false }) {
   const sf = path.join(projectRoot, '.spectoflow');
   const prev = manifest.readManifest(sf);
@@ -34,9 +77,14 @@ function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force =
     adopted: [],
     unchanged: [],
     forced: [],
+    removed: [],
+    kept: [],
+    migration: null,
+    legacyLeftovers: [],
   };
   const baseline = (prev && prev.files) || {};
   const nextFiles = {}; // manifest to write after this run
+  report.migration = migrateProjectData(projectRoot, sf, dryRun);
 
   const write = (fp, buf) => {
     if (dryRun) return;
@@ -77,6 +125,26 @@ function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force =
     }
   }
 
+  // Retired files: in the previous manifest, no longer in the kit. Intact (hash == baseline) → gone;
+  // modified → kept and reported, and it stays in the manifest so the next run warns again. --force
+  // never applies here: there is no kit version to restore, so nothing legitimate to force.
+  const kit = new Set(ownership.listFrameworkFiles(templatesDir));
+  for (const rel of Object.keys(baseline)) {
+    if (kit.has(rel)) continue;
+    const diskPath = toDisk(sf, rel);
+    if (!fs.existsSync(diskPath)) continue; // already gone — just drop it from the manifest
+    if (manifest.sha256(fs.readFileSync(diskPath)) === baseline[rel]) {
+      if (!dryRun) removeAndPrune(diskPath, sf);
+      report.removed.push(rel);
+    } else {
+      report.kept.push(rel);
+      nextFiles[rel] = baseline[rel];
+    }
+  }
+  if (!prev) {
+    for (const rel of LEGACY_LEFTOVERS) if (fs.existsSync(toDisk(sf, rel))) report.legacyLeftovers.push(rel);
+  }
+
   if (!dryRun) manifest.writeManifest(sf, { version, files: nextFiles });
   return report;
 }

package/lib/workspace.js

@@ -0,0 +1,119 @@
+'use strict';
+/*
+ * The dashboard workspace — the dashboard's own state, outside every project: dashboard.json
+ * (name/port/design), projects.json (the registry), hub.lock, and projects/<id>/ for dashboard-side
+ * per-project data (meta.json today; B adds a scan cache, C adds members/tokens). Default location
+ * $SPECTOFLOW_HOME/dashboard (~/.spectoflow/dashboard); movable via global config dashboard.path.
+ */
+const fs = require('fs');
+const path = require('path');
+const globalConfig = require('./global-config');
+const registry = require('./registry');
+
+const SETTINGS_DEFAULTS = { name: null, port: 4319, design: 'console' };
+
+function dir(baseDir) { return baseDir || globalConfig.read().dashboard.path; }
+function settingsPath(baseDir) { return path.join(dir(baseDir), 'dashboard.json'); }
+function lockPath(baseDir) { return path.join(dir(baseDir), 'hub.lock'); }
+function projectDir(id, baseDir) { return path.join(dir(baseDir), 'projects', id); }
+
+function readJSON(fp) { try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; } }
+function settings(baseDir) {
+  const raw = readJSON(settingsPath(baseDir)) || {};
+  const s = { ...SETTINGS_DEFAULTS, ...raw };
+  if (!s.name) s.name = path.basename(dir(baseDir));
+  return s;
+}
+function exists(baseDir) { return fs.existsSync(settingsPath(baseDir)); }
+
+// Idempotent: creates what is missing, never deletes, updates dashboard.json only for fields passed.
+// Moving the workspace (a new `path`) carries the registry over when the new one has no projects.
+function init({ path: newPath, port, name, design } = {}) {
+  migrateLegacyHome(); // pre-0.24 registry/lock, if still stranded in the bare home dir
+  const prevDir = globalConfig.read().dashboard.path;
+  const target = newPath ? path.resolve(globalConfig.expandHome(newPath)) : prevDir;
+  const created = !exists(target);
+  fs.mkdirSync(path.join(target, 'projects'), { recursive: true });
+  const s = { ...SETTINGS_DEFAULTS, ...(readJSON(settingsPath(target)) || {}) };
+  if (!s.name) s.name = path.basename(target);
+  if (name !== undefined) s.name = String(name);
+  if (port !== undefined) s.port = Number(port);
+  if (design !== undefined) s.design = String(design);
+  fs.writeFileSync(settingsPath(target), JSON.stringify(s, null, 2) + '\n');
+  let registryCarried = false;
+  const targetReg = registry.readRegistry(target);
+  if (!fs.existsSync(registry.registryPath(target))) {
+    const prevReg = path.resolve(prevDir) !== path.resolve(target) ? registry.readRegistry(prevDir) : { projects: [] };
+    if (prevReg.projects.length && !targetReg.projects.length) { registry.writeRegistry(target, prevReg); registryCarried = true; }
+    else registry.writeRegistry(target, { projects: [] });
+  }
+  if (path.resolve(target) !== path.resolve(prevDir) || globalConfig.get('dashboard.path').source === 'default') globalConfig.set('dashboard.path', target);
+  return { dir: target, created, registryCarried };
+}
+
+function registerProject(projectPath, baseDir) {
+  const entry = registry.addProject(projectPath, baseDir);
+  const pd = projectDir(entry.id, baseDir);
+  fs.mkdirSync(pd, { recursive: true });
+  const metaPath = path.join(pd, 'meta.json');
+  if (!fs.existsSync(metaPath)) fs.writeFileSync(metaPath, JSON.stringify({ addedAt: new Date().toISOString(), lastOpened: entry.lastOpened, kind: entry.kind || 'spectoflow' }, null, 2) + '\n');
+  return entry;
+}
+
+// Pre-0.24 the registry and lock sat directly in ~/.spectoflow/. Move them into the workspace the
+// first time the new code runs — one-time, and only when the workspace has none of its own.
+function migrateLegacyHome(baseDir) {
+  const home = globalConfig.homeDir();
+  const target = dir(baseDir);
+  const r = { movedRegistry: false, movedLock: false };
+  if (path.resolve(home) === path.resolve(target)) return r;
+  fs.mkdirSync(target, { recursive: true });
+  const legacyReg = path.join(home, 'projects.json');
+  if (fs.existsSync(legacyReg) && !fs.existsSync(registry.registryPath(target))) { fs.renameSync(legacyReg, registry.registryPath(target)); r.movedRegistry = true; }
+  const legacyLock = path.join(home, 'hub.lock');
+  if (fs.existsSync(legacyLock) && !fs.existsSync(lockPath(target))) { fs.renameSync(legacyLock, lockPath(target)); r.movedLock = true; }
+  return r;
+}
+
+// The hub's lock: the workspace's, else a legacy one still written by a pre-0.24 hub that may be
+// running right now (so `dashboard status/stop` keep finding it across the upgrade).
+function readLock(baseDir) {
+  return readJSON(lockPath(baseDir)) || readJSON(path.join(globalConfig.homeDir(), 'hub.lock'));
+}
+
+// ---- online dashboard (sub-project C1): remote.json + the per-project `published` flag ----
+// remote.json = { url, token, machineName, transport } written by `spectoflow dashboard login`; the
+// hub reads it at boot to start the connector. It holds a secret, hence mode 0600 (no-op on Windows).
+function remotePath(baseDir) { return path.join(dir(baseDir), 'remote.json'); }
+function readRemote(baseDir) {
+  const r = readJSON(remotePath(baseDir));
+  return r && r.url && r.token ? r : null;
+}
+function writeRemote({ url, token, machineName, transport }, baseDir) {
+  const obj = { url: String(url).replace(/\/+$/, ''), token: String(token), machineName: String(machineName || ''), transport: transport === 'http' ? 'http' : 'ws' };
+  fs.mkdirSync(dir(baseDir), { recursive: true });
+  fs.writeFileSync(remotePath(baseDir), JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
+  try { fs.chmodSync(remotePath(baseDir), 0o600); } catch (_) {}
+  return obj;
+}
+function clearRemote(baseDir) {
+  try { fs.unlinkSync(remotePath(baseDir)); return true; } catch { return false; }
+}
+
+function metaPath(id, baseDir) { return path.join(projectDir(id, baseDir), 'meta.json'); }
+function readMeta(id, baseDir) { return readJSON(metaPath(id, baseDir)); }
+// `published: true` means "announce this project to the online dashboard". Only registered projects
+// can carry it; null tells the caller the id is unknown (a 404, not a silent write).
+function setPublished(id, published, baseDir) {
+  const entry = registry.listProjects(baseDir).find((p) => p.id === id);
+  if (!entry) return null;
+  fs.mkdirSync(projectDir(id, baseDir), { recursive: true });
+  const meta = { addedAt: new Date().toISOString(), lastOpened: entry.lastOpened, kind: entry.kind || 'spectoflow', ...(readMeta(id, baseDir) || {}), published: !!published };
+  fs.writeFileSync(metaPath(id, baseDir), JSON.stringify(meta, null, 2) + '\n');
+  return meta;
+}
+function isPublished(id, baseDir) { const m = readMeta(id, baseDir); return !!(m && m.published); }
+function listPublished(baseDir) { return registry.listProjects(baseDir).filter((p) => isPublished(p.id, baseDir)); }
+
+module.exports = { dir, exists, settings, settingsPath, lockPath, projectDir, init, registerProject, migrateLegacyHome, readLock,
+  remotePath, readRemote, writeRemote, clearRemote, readMeta, setPublished, isPublished, listPublished };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.23.5",
+  "version": "0.27.0",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",
@@ -41,9 +41,9 @@
   "scripts": {
     "status": "node bin/spectoflow.js status",
     "postinstall": "node bin/postinstall.js",
-    "test": "node --test"
+    "test": "node --test \"test/**/*.test.js\""
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/templates/AGENTS.md

@@ -91,7 +91,7 @@ worth building" for the Auto mode). Hand it to the `framework-curator` agent (ca
 
 - **`generate-dashboard`** — a declarative block-spec page (never raw HTML/CSS/JS — see
   `.spectoflow/skills/generate-dashboard` for why), written to
-  `.spectoflow/dashboard/custom/<id>.json`.
+  `.spectoflow/dashboards/<id>.json`.
 - **`generate-skill`** — a new `.spectoflow/skills/<slug>/SKILL.md`, grounded in real, cited domain
   standards, following the gold-standard shape.
 - **`generate-agent`** — a new `.spectoflow/agents/<slug>.md` persona, same shape discipline.
@@ -119,12 +119,12 @@ destructive migration, security). Mode sets routine friction; policy is non-nego
 
 ## Dashboard
 
-Launch it with `spectoflow dashboard` (default http://localhost:4319, or `SPECTOFLOW_PORT` /
-`--port=NNNN`; falls back to `node .spectoflow/dashboard/server.js` if the CLI isn't on PATH). Zero
-deps, live via SSE.
+Launch it with `spectoflow dashboard` (default http://localhost:4319 — or the workspace's port; `--port=NNNN`
+overrides). The dashboard is part of the spectoflow package, not of this project: nothing under
+`.spectoflow/` runs it. Zero deps, live via SSE.
 
 **At the end of `init`, and on the first request in a session,** check whether the dashboard is
 running — UNLESS the user said they don't want it, or `.spectoflow/config.json` →
 `dashboard.autostart` is `false`. If it's not running, start it **detached** (spawn `spectoflow
-dashboard`, or `node .spectoflow/dashboard/server.js`, unref'd/backgrounded so it doesn't block you),
-then share the URL. Always be able to answer "is the dashboard running?" — check, don't assume.
+dashboard`, unref'd/backgrounded so it doesn't block you), then share the URL. Always be able to
+answer "is the dashboard running?" — check (`spectoflow dashboard status`), don't assume.

package/templates/README.md

@@ -20,10 +20,12 @@ sit at the project root and just point back here.
   (skill `clarify`, wired into the agent's memory in `AGENTS.md`).
 - **Watch it live** in the dashboard (it starts in the background and hands the prompt back):
   ```
-  spectoflow dashboard          # → http://localhost:4319   (or: node .spectoflow/dashboard/server.js)
+  spectoflow dashboard          # → http://localhost:4319
   spectoflow dashboard status   # is it running? (url + pid)
   spectoflow dashboard stop     # stop it        (alias: spectoflow stop)
   spectoflow dashboard restart  # stop then start
+  spectoflow dashboard init --path <dir>   # move the dashboard workspace (default ~/.spectoflow/dashboard)
+  spectoflow config             # global defaults + dashboard URL/path
   spectoflow status             # progress + whether the dashboard is running
   ```
 - **See what you got:** `spectoflow list` (agents, skills & workflow at a glance), or `spectoflow
@@ -63,11 +65,10 @@ Your **artifacts are markdown, and they live at the project root, not in here**:
 | `config.json` | Your settings: `mode`, `language`, active `agent`, `runners`, `design`, plans/specs dir. **Yours to edit** — `update` never overwrites it. |
 | `agents/` | **Stable team personas** (product-manager, developer, qa-engineer, code-reviewer, spec-source-guardian…) — the *who*. |
 | `skills/` | **Evolving procedures** (clarify, brainstorm, write-spec, write-plan, implement, write-e2e-tests, code-review, audit-source…) — the *how*. A workflow step → a capability → its agent → runs a skill. |
-| `dashboard/` | The zero-dependency control plane: `server.js` (SSE + file-watch), `runner.js`, `orchestrator.js`, `public/` (the UI, charts, designs, fonts), and `custom/` (your generated dashboards, one JSON spec per file). |
+| `dashboards/` | Your generated custom dashboards, one JSON spec per file — the *only* dashboard-related thing that lives in a project; the dashboard's own code is part of the spectoflow package, not vendored here. |
 | `lib/` | The markdown storage engine (`store.js`) and helpers (e.g. `spec-drift.js` for the spec-source-guardian). |
 | `hooks/` | Optional Claude Code hooks you can wire in yourself (e.g. `spec-drift.js`, a `Stop` hook that surfaces source-of-truth drift to the Attention tab). |
 | `runtime.json` | **Volatile execution state** (running agents, orchestration, group-chat messages, attention items, history). Gitignored — safe to delete; it's rebuilt. |
-| `.dashboard.lock` | Ephemeral pidfile so `spectoflow stop` can find the running dashboard. Gitignored. |
 | `.manifest.json` | Hashes of the framework files at install time, so `update` can tell an untouched file from one you edited. |
 
 ## Principles (why it's shaped this way)