spectoflow 0.23.5 → 0.24.0

package/README.md

@@ -87,6 +87,9 @@ spectoflow dashboard status                    is it running? (url + pid)
 spectoflow dashboard stop   (or: stop)         stop the running dashboard
 spectoflow dashboard restart                   stop then start
 spectoflow dashboard create "..." | --auto     generate a custom dashboard
+spectoflow dashboard init [--path=<dir>]       create/move the dashboard workspace (default ~/.spectoflow/dashboard)
+spectoflow dashboard validate <file>           check a custom-view JSON against the block schema
+spectoflow config [get|set <key> [<value>]]    global defaults + dashboard URL/path (~/.spectoflow/config.json)
 
 spectoflow skill create "..." | --auto         generate a project skill
 spectoflow agent create "..." | --auto         generate a project agent
@@ -101,7 +104,7 @@ spectoflow --help      (-h)                    show help   (append -h to any com
 ```
 
 `init` scaffolds:
-- `.spectoflow/` — the framework (brain, `workflow.md`, `agents/`, `skills/`, `policy.md`, `config.json`, dashboard, engine).
+- `.spectoflow/` — the framework (brain, `workflow.md`, `agents/`, `skills/`, `policy.md`, `config.json`, engine). The dashboard itself ships in the spectoflow package, not in your project.
 - `specs/` and `plans/` — **markdown artifacts**, your versioned source of truth.
 - per-agent shims: `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex/Cursor), `GEMINI.md` (Gemini),
   `.claude/commands/spectoflow.md`.
@@ -119,8 +122,9 @@ existing `plans/*.md` tasks are given stable ids.
 ## Update
 
 `init` is idempotent (it never overwrites), so it can't refresh an installed project. `spectoflow
-update` refreshes **framework-owned** files (engine, dashboard, `AGENTS.md`, `capabilities.md`,
-`policy.md`, default agents & skills) to the CLI's version, while **preserving your work** —
+update` refreshes **framework-owned** files (engine, `AGENTS.md`, `capabilities.md`, `policy.md`,
+default agents & skills) to the CLI's version — retiring the project's own vendored dashboard folder
+along the way for anyone updating from before v0.24 — while **preserving your work** —
 `config.json`, `workflow.md`, `specs/`, `plans/`, and any agent/skill you created or edited are never
 touched. A file you edited is preserved and its new version is written next to it as `<file>.new`
 for you to merge by hand. Add `--dry-run` to preview, or `--force`/`-f` to overwrite a diverged file
@@ -128,6 +132,14 @@ in place instead of dropping a `.new` — use it once you're sure you have no lo
 in that file (e.g. it's been stuck diverged since an earlier update); it still never touches
 `config.json`, `workflow.md`, `specs/` or `plans/`.
 
+**Coming from before v0.24?** The dashboard used to be vendored into every project; now it ships once
+in the package. `npm install -g spectoflow@0.24`, then `spectoflow dashboard` anywhere — the dashboard
+workspace is created automatically and any project you'd already registered is carried over. Your
+project already opens in the new dashboard at this point, whether or not you've run `update` in it
+yet; running `spectoflow update` inside it retires its now-obsolete `.spectoflow/dashboard/` folder
+(only if you never edited anything in it — an edited file is kept and reported, never deleted) and
+moves any custom dashboard views you generated to `.spectoflow/dashboards/`.
+
 First refresh the kit, then run update from your project — the flow is the same whichever way you
 installed:
 
@@ -167,13 +179,12 @@ agent never clobber each other.
 
 ```bash
 spectoflow dashboard                     # → http://localhost:4319 (or --port=NNNN)
-# manual (no global install): node .spectoflow/dashboard/server.js
+# manual (no global install): node /path/to/spectoflow/bin/spectoflow.js dashboard
 ```
 
 `spectoflow dashboard` is the simple way — it prints the URL and won't double-start (it detects a
-dashboard already running on the port). `spectoflow status` tells you whether one is up. Running the
-`server.js` directly still works for a manual/embedded setup. Zero dependencies, updates live via SSE
-+ file watching.
+dashboard already running on the port). `spectoflow status` tells you whether one is up. Zero
+dependencies, updates live via SSE + file watching.
 
 The header bar always shows the brand, the **active agent**, autonomy mode, language, a global-progress
 meter, a sync dot, and a **Run** quick-action. Ten tabs:
@@ -195,7 +206,7 @@ meter, a sync dot, and a **Run** quick-action. Ten tabs:
   *Customize* below).
 
 URLs are real routes (`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in
-`dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
+`lib/dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
 every aggregate is computed client-side.
 
 ### Designs & theme
@@ -205,8 +216,8 @@ The dashboard ships **switchable designs** (Personalize → *Dashboard design*):
 (violet), **Obsidian Ops** (near-black lime/cyan, mono), **Neon Command** (glassmorphism aurora), and
 **Mission Control** (indigo control panel). Each works in light and dark (the moon toggle). A design
 is a `data-design` skin — a scoped CSS token block plus a one-line entry in
-`dashboard/public/designs.js`, so adding one is trivial. Fonts are **self-hosted**
-(`dashboard/public/fonts/*.woff2`), keeping the dashboard fully offline and dependency-free. Your
+`lib/dashboard/public/designs.js`, so adding one is trivial. Fonts are **self-hosted**
+(`lib/dashboard/public/fonts/*.woff2`), keeping the dashboard fully offline and dependency-free. Your
 choice persists per viewer (localStorage) and as the project default (`config.design`).
 
 ### Chat

package/bin/postinstall.js

@@ -8,6 +8,7 @@
  */
 try {
   if (process.env.npm_config_global === 'true' && process.stdout.isTTY) {
+    try { require('../lib/global-config').ensure(); } catch {}
     const brand = require('../lib/brand');
     const version = require('../package.json').version;
     const useColor = !process.env.NO_COLOR;

package/bin/spectoflow.js

@@ -3,23 +3,29 @@
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
+const readline = require('readline');
 const { spawn } = require('child_process');
-const store = require('../templates/lib/store');
+const store = require('../lib/store');
 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 workspace = require('../lib/workspace');
 const initLib = require('../lib/init');
+const globalConfig = require('../lib/global-config');
 const mcp = require('../lib/mcp');
-const { startRun } = require('../templates/dashboard/runner');
-const { buildCustomizePrompt } = require('../templates/lib/customize-prompts');
+const { startRun } = require('../lib/dashboard/runner');
+const { buildCustomizePrompt } = require('../lib/customize-prompts');
 
 const KIT = path.resolve(__dirname, '..');
 const TPL = path.join(KIT, 'templates');
 const VERSION = require('../package.json').version;
 const argv = process.argv.slice(2);
 const cmd = argv[0] || 'help';
+// `--name=value` flag reader — joins remaining `=`-split parts back (a URL's own query string may
+// contain one), returns undefined when absent so callers can tell "not passed" from an empty string.
+const flag = (name) => (argv.find((a) => a.startsWith(`--${name}=`)) || '').split('=').slice(1).join('=') || undefined;
 
 // Tiny ANSI colouriser — no dependency; disabled when not a TTY or NO_COLOR is set.
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -77,10 +83,13 @@ function readWorkflowSteps(dir) {
 }
 
 // ---- dashboard port + running-state probe ------------------------------------
-// Precedence: --port=NNNN > SPECTOFLOW_PORT env > 4319 (matches templates/dashboard/server.js).
+// Precedence: --port=NNNN > SPECTOFLOW_PORT env > the workspace's own port (matches
+// lib/dashboard/hub-server.js).
 function resolvePort(args) {
   const arg = (args.find((a) => a.startsWith('--port=')) || '').split('=')[1];
-  return Number(arg || process.env.SPECTOFLOW_PORT || 4319);
+  if (arg) return Number(arg);
+  if (process.env.SPECTOFLOW_PORT) return Number(process.env.SPECTOFLOW_PORT);
+  try { return workspace.settings().port; } catch { return 4319; }
 }
 
 // Native http probe, ~500ms timeout, never throws — resolves true/false.
@@ -101,7 +110,7 @@ function init() {
   const r = initLib.runInit({ target, templatesDir: TPL, version: VERSION, agentsArg });
   console.log(logo());
   console.log(`${c.g('✓')} installed in ${c.bold(r.target)}`);
-  console.log(`  ${c.dim('.spectoflow/')}   framework — brain, workflow, agents, skills, policy, dashboard, config`);
+  console.log(`  ${c.dim('.spectoflow/')}   framework — brain, workflow, agents, skills, policy, config`);
   console.log(`  ${c.dim('specs/ plans/')}  markdown artifacts (your source of truth)`);
   r.written.forEach((w) => console.log(`  ${c.cy('+')} ${w}`));
   r.notes.forEach((n) => console.log(`  ${c.y('!')} ${c.dim(n)}`));
@@ -123,7 +132,7 @@ async function update() {
   const r = require('../lib/update').runUpdate({ projectRoot: root, templatesDir: TPL, version: VERSION, dryRun, force });
 
   const from = r.fromVersion || 'unknown';
-  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length + r.forced.length;
+  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length + r.forced.length + r.removed.length + r.migration.movedViews.length;
   const row = (sym, label, list, painter, note) => {
     if (!list.length) return;
     const n = c.dim(String(list.length).padStart(2));
@@ -138,6 +147,11 @@ async function update() {
   row(c.b('~'), 'adopted', r.adopted, c.b);
   row(c.y('!'), 'forced', r.forced, c.y, 'overwrote a diverged file — its previous content is gone');
   row(c.y('!'), '.new', r.newSidecar, c.y, 'you edited these — new version saved as *.new, merge by hand (or re-run with --force)');
+  row(c.dim('−'), 'removed', r.removed, c.dim, 'no longer part of the kit (the dashboard lives in the spectoflow package now)');
+  row(c.y('!'), 'kept', r.kept, c.y, 'you modified these and they are no longer part of the kit — delete them yourself when ready');
+  if (r.migration.movedViews.length) console.log(`  ${c.cy('→')}  ${c.cy('views'.padEnd(9))} ${c.dim(String(r.migration.movedViews.length).padStart(2))}   ${c.dim('custom views moved to .spectoflow/dashboards/')}`);
+  r.migration.conflicts.forEach((f) => console.log(`  ${c.y('!')}  ${c.y('conflict'.padEnd(9))}      ${c.dim(`dashboards/${f} already exists — the old copy stays in dashboard/custom/ for you to merge`)}`));
+  if (r.legacyLeftovers.length) console.log(`  ${c.y('!')}  ${c.dim('this project has no install manifest, so nothing was deleted. Safe to remove by hand: ' + r.legacyLeftovers.map((p) => '.spectoflow/' + p).join(', '))}`);
   if (r.unchanged.length) console.log(`  ${c.dim('·')}  ${c.dim('unchanged'.padEnd(9))} ${c.dim(String(r.unchanged.length).padStart(2))}`);
   console.log(`  ${c.dim('=')}  ${c.dim('preserved'.padEnd(9))}      ${c.dim('config.json · workflow.md · specs/ · plans/ · your custom agents & skills')}`);
   console.log('');
@@ -151,9 +165,7 @@ async function update() {
   // is invalidated. Do that via a surgical per-project reload so an update always actually takes
   // effect, without restarting the whole hub (which would disturb every other project open in it).
   if (!dryRun && changed) {
-    const lockPath = registry.hubLockPath();
-    let info = null;
-    try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+    const info = workspace.readLock();
     if (info && info.port && (await probeDashboard(info.port, 2000))) {
       const entry = registry.findByPath(root);
       if (entry) {
@@ -161,7 +173,7 @@ async function update() {
           const res = await fetch(`http://localhost:${info.port}/api/hub/reload/${entry.id}`, { method: 'POST' });
           const body = await res.json().catch(() => ({}));
           console.log(`  ${c.dim(body.reloaded
-            ? 'Hub is running — reloaded this project\'s server code (other open projects unaffected).'
+            ? 'Hub is running — reloaded this project (other open projects unaffected).'
             : 'Hub is running, but this project wasn\'t loaded in it yet — nothing to reload.')}`);
         } catch {
           console.log(`  ${c.y('!')} Hub is running on port ${info.port} but the reload request failed — restart it yourself if changes don't seem to take effect: ${c.g('spectoflow dashboard restart')}`);
@@ -171,18 +183,83 @@ async function update() {
   }
 }
 
+// `spectoflow dashboard validate <file>` — the generate-dashboard skill's verification step (it used
+// to require() a lib file vendored in the project; the validator lives in this package now).
+function validateDashboardFile(file) {
+  if (!file) { console.log('Usage: spectoflow dashboard validate <file.json>'); process.exitCode = 1; return; }
+  let spec;
+  try { spec = JSON.parse(fs.readFileSync(path.resolve(file), 'utf8')); }
+  catch (e) { console.log(`${c.y('invalid')} — cannot read/parse ${file}: ${e.message}`); process.exitCode = 1; return; }
+  const r = require('../lib/custom-dashboard').validateSpec(spec);
+  if (r.valid) { console.log(`${c.g('valid')} — ${spec.id} (${(spec.blocks || []).length} block(s))`); return; }
+  console.log(`${c.y('invalid')} — ${file}`);
+  (r.errors || []).forEach((e) => console.log(`  ${c.y('!')} ${e}`));
+  process.exitCode = 1;
+}
+
+// `spectoflow dashboard init [--path <dir>] [--port N] [--name "…"] [--design <id>]` — create (or
+// move) the dashboard workspace from the command line, mirroring what `startDashboard()` does lazily
+// on first `spectoflow dashboard`, but explicit and inspectable.
+function dashboardInit() {
+  try {
+    const r = workspace.init({ path: flag('path'), port: flag('port'), name: flag('name'), design: flag('design') });
+    console.log(logo());
+    console.log(`${c.g('✓')} dashboard workspace ${r.created ? 'created' : 'updated'} at ${c.bold(r.dir)}`);
+    if (r.registryCarried) console.log(`  ${c.dim('your project list was carried over from the previous workspace')}`);
+    const s = workspace.settings();
+    console.log(`  ${c.dim('name')} ${s.name}   ${c.dim('port')} ${s.port}   ${c.dim('design')} ${s.design}`);
+    console.log(`\n  start it:  ${c.g('spectoflow dashboard')}\n`);
+  } catch (e) { console.log(`${c.y('!')} ${e.message}`); process.exitCode = 1; }
+}
+
+const REMOTE_NOTE = 'This version manages local dashboards. Remote dashboards (login with a token) come in a later release — continuing with your local dashboard.';
+function isLocalUrl(u) { try { return ['localhost', '127.0.0.1', '::1'].includes(new URL(u).hostname); } catch { return true; } }
+// The one-time question every dashboard-starting command answers before doing anything else: which
+// dashboard should this project talk to? `--url` answers it without prompting. Otherwise, only when
+// dashboard.url has never been set AND both stdin/stdout are a real TTY do we ask (Enter keeps the
+// local default) — any non-interactive invocation (tests spawn with stdio:'pipe', CI, scripts) must
+// never block waiting on stdin that will never arrive, so it silently keeps the local default instead.
+// The answer (typed, defaulted, or flagged) is saved via globalConfig.set so it is asked at most once.
+// Returns the resolved URL on success, or null on validation error (error message already printed).
+async function resolveDashboardUrl() {
+  const fromFlag = flag('url');
+  if (fromFlag) {
+    try {
+      globalConfig.set('dashboard.url', fromFlag);
+    } catch (e) {
+      console.log(`${c.y('!')} ${e.message}`);
+      process.exitCode = 1;
+      return null;
+    }
+  }
+  else if (globalConfig.get('dashboard.url').source === 'default') {
+    let answer = '';
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      answer = await new Promise((r) => rl.question(`Dashboard URL [${globalConfig.get('dashboard.url').value}]: `, (a) => { rl.close(); r(a.trim()); }));
+    }
+    globalConfig.set('dashboard.url', answer || globalConfig.get('dashboard.url').value);
+  }
+  const url = globalConfig.get('dashboard.url').value;
+  if (!isLocalUrl(url)) console.log(`${c.y('!')} ${REMOTE_NOTE}`);
+  return url;
+}
+
 // THE launch command — routes the subcommands, then starts. Starting spawns the server DETACHED and
 // hands the prompt straight back (no foreground blocking), then prints the commands to drive it.
 async function dashboard() {
   const sub = argv[1];
+  if (sub === 'init') return dashboardInit();
+  if (sub === 'login') { console.log(REMOTE_NOTE); return; }
   if (sub === 'stop') return stopDashboard();
   if (sub === 'status') return dashboardStatus();
   if (sub === 'restart') return restartDashboard();
   if (sub === 'create') return runCustomize('dashboard');
+  if (sub === 'validate') return validateDashboardFile(argv[2]);
   return startDashboard();
 }
 
-// ---- projects: the multi-project registry's CLI surface (~/.spectoflow/projects.json) ----
+// ---- projects: the multi-project registry's CLI surface (the workspace's projects.json) ----
 function projectsCmd() {
   const sub = argv[1];
   if (sub === 'remove') return projectsRemove(argv[2]);
@@ -204,6 +281,20 @@ function projectsRemove(id) {
   console.log(ok ? `${c.g('✓')} removed ${id}` : `${c.y('!')} no project registered with id ${id}`);
 }
 
+// ---- config: global settings (~/.spectoflow/config.json), editable from anywhere ----
+function configCmd() {
+  const sub = argv[1];
+  try {
+    if (sub === 'get') { if (!argv[2]) throw new Error('Usage: spectoflow config get <key>'); console.log(globalConfig.get(argv[2]).value); return; }
+    if (sub === 'set') { if (!argv[2] || argv[3] === undefined) throw new Error('Usage: spectoflow config set <key> <value>'); const v = globalConfig.set(argv[2], argv[3]); console.log(`${c.g('✓')} ${argv[2]} = ${v}`); return; }
+    console.log(wordmark());
+    const rows = globalConfig.list();
+    const w = Math.max(...rows.map((r) => r.key.length));
+    rows.forEach((r) => console.log(`  ${c.g(r.key.padEnd(w))}  ${String(r.value).padEnd(28)}  ${c.dim('(' + r.source + ')')}`));
+    console.log(c.dim(`\n  file: ${globalConfig.configPath()}   ·   spectoflow config set <key> <value>`));
+  } catch (e) { console.log(`${c.y('!')} ${e.message}`); process.exitCode = 1; }
+}
+
 // ---- 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),
@@ -260,18 +351,20 @@ async function runCustomize(kind) {
 // global registry first, then either joins an already-running hub or spawns a new one — probing first
 // so a second start just reports the running one instead of spawning a duplicate.
 async function startDashboard() {
+  if (!(await resolveDashboardUrl())) return;
   const root = process.cwd();
-  const entry = registry.addProject(root);
-  const boardUrl = (p) => `http://localhost:${p}/p/${entry.id}/board`;
-  const lockPath = registry.hubLockPath();
-  let info = null;
-  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  workspace.migrateLegacyHome();
+  if (!workspace.exists()) workspace.init({});
+  const hasProject = fs.existsSync(path.join(root, '.spectoflow'));
+  const entry = hasProject ? workspace.registerProject(root) : null;
+  const boardUrl = (p) => (entry ? `http://localhost:${p}/p/${entry.id}/board` : `http://localhost:${p}/`);
+  const info = workspace.readLock();
   if (info && info.port && await probeDashboard(info.port)) {
     console.log(`${c.g('●')} hub already running → ${c.bold(boardUrl(info.port))}`);
     return printDashboardCommands();
   }
   const port = resolvePort(argv);
-  const hubPath = path.join(KIT, 'lib', 'hub-server.js');
+  const hubPath = path.join(KIT, 'lib', 'dashboard', 'hub-server.js');
   const env = Object.assign({}, process.env, { SPECTOFLOW_PORT: String(port) });
   const child = spawn('node', [hubPath], { detached: true, stdio: 'ignore', env });
   child.unref();                                   // let this CLI exit while the hub keeps running
@@ -293,9 +386,8 @@ function printDashboardCommands() {
 }
 
 async function dashboardStatus() {
-  const lockPath = registry.hubLockPath();
-  let info = null;
-  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  if (!(await resolveDashboardUrl())) return;
+  const info = workspace.readLock();
   const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   if (running) console.log(`${c.g('●')} hub running → ${c.bold('http://localhost:' + port)}${info && info.pid ? c.dim(' (pid ' + info.pid + ')') : ''}`);
@@ -303,6 +395,7 @@ async function dashboardStatus() {
 }
 
 async function restartDashboard() {
+  if (!(await resolveDashboardUrl())) return;
   await stopDashboard();
   // Windows doesn't deliver real signals — process.kill() returns once the request is issued, not
   // once the process (and the port it held) is actually gone. A short gap here, plus startDashboard()
@@ -315,20 +408,23 @@ async function restartDashboard() {
 // Stop the running hub: read the global lock it wrote, verify it's actually up, then terminate it
 // and clear the lock. Safe against a stale lock (a recycled pid) because it only kills when the port
 // still responds.
+function unlinkLocks() {
+  try { fs.unlinkSync(workspace.lockPath()); } catch {}
+  try { fs.unlinkSync(path.join(globalConfig.homeDir(), 'hub.lock')); } catch {}
+}
 async function stopDashboard() {
-  const lockPath = registry.hubLockPath();
-  let info = null;
-  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  if (!(await resolveDashboardUrl())) return;
+  const info = workspace.readLock();
   const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   if (!running) {
-    if (info) { try { fs.unlinkSync(lockPath); } catch {} }   // stale lock
+    if (info) unlinkLocks();   // stale lock
     return console.log('No spectoflow hub is running.');
   }
   if (info && info.pid) {
     try {
       process.kill(info.pid);                  // SIGTERM → hub clears its own lock (POSIX)
-      try { fs.unlinkSync(lockPath); } catch {}     // and we clear it too (Windows has no real signals)
+      unlinkLocks();     // and we clear it too (Windows has no real signals)
       return console.log(`spectoflow hub stopped (pid ${info.pid}, was on http://localhost:${port}).`);
     } catch {}
   }
@@ -348,9 +444,7 @@ async function status() {
   console.log(`${(p.config && p.config.projectType) || 'project'} — mode ${p.config.mode} · lang ${p.config.language}`);
   console.log(`${done}/${tasks.length} tasks done · ${p.specs.length} spec(s) · ${p.agents.length} agents · ${p.skills.length} skills`);
   tasks.filter((t) => t.status === 'in_progress').forEach((t) => console.log(`  > in progress: ${t.id} ${t.title}`));
-  const lockPath = registry.hubLockPath();
-  let info = null;
-  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  const info = workspace.readLock();
   const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   console.log(`dashboard: ${running ? `running → http://localhost:${port}` : 'not running'}`);
@@ -402,13 +496,16 @@ ${c.bold('Project')}
   ${c.g('init')} ${c.dim('[dir] [--agent=a,b]')}    scaffold a project (auto-detects agents; wires Playwright MCP)
   ${c.g('update')} ${c.dim('[--dry-run|--force]')}  refresh framework files to this kit version
   ${c.g('status')}                      progress + whether the dashboard is running
+  ${c.g('config')} ${c.dim('[get <key>|set <key> <value>]')}  global settings for every project (~/.spectoflow/config.json)
 
 ${c.bold('Dashboard')}
   ${c.g('dashboard')} ${c.dim('[--port=NNNN]')}     start the control plane in the background (default 4319)
+  ${c.g('dashboard init')} ${c.dim('[--path=<dir>] [--port=N] [--name=…]')}  create/move the dashboard workspace ${c.dim('(default ~/.spectoflow/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.g('dashboard login')}               connect to a remote dashboard ${c.dim('(coming in a later release)')}
+  ${c.g('projects')} ${c.dim('[remove <id>]')}     list every project seen so far
 
 ${c.bold('Customize')} ${c.dim('— same as Settings → Customize, from the terminal')}
   ${c.g('skill create')} ${c.dim('"<description>" | --auto')}      generate a project skill
@@ -438,22 +535,27 @@ const HELP = {
   ${c.dim('An existing CLAUDE.md is preserved as CLAUDE.md.tomerge for you to merge on first run.')}
   ${c.dim('Full list with docs links: the dashboard\'s Documentation tab, or the README.')}`,
   update: `${c.bold('spectoflow update')} ${c.dim('[--dry-run] [--force|-f]')}\n
-  Refresh framework-owned files (engine, dashboard, default agents & skills, AGENTS.md, policy…)
+  Refresh framework-owned files (engine, default agents & skills, AGENTS.md, policy…)
   to this CLI's version, ${c.bold('preserving your work')}: config.json, workflow.md, specs/, plans/
   and any agent/skill you edited are never overwritten (an edited file's new version lands as
   ${c.dim('*.new')} for you to merge). ${c.g('--dry-run')} previews without writing.
   ${c.g('--force')} (${c.g('-f')}) overwrites a diverged file in place instead of dropping a ${c.dim('*.new')}
   — use it when you know you have no local edits worth keeping (e.g. a file stuck diverged from an
   earlier update). It never touches config.json, workflow.md, specs/ or plans/.`,
-  dashboard: `${c.bold('spectoflow dashboard')} ${c.dim('[--port=NNNN] [status|stop|restart|create]')}\n
+  dashboard: `${c.bold('spectoflow dashboard')} ${c.dim('[--port=NNNN] [--url=<u>] [init|status|stop|restart|create|validate|login]')}\n
   Start the local control plane in the ${c.bold('background')} (default ${c.dim('4319')} or
-  ${c.dim('$SPECTOFLOW_PORT')}) and hand the prompt back. Subcommands:
+  ${c.dim('$SPECTOFLOW_PORT')}) and hand the prompt back. ${c.g('--url=<u>')} sets which dashboard this
+  project talks to (${c.dim('~/.spectoflow/config.json → dashboard.url')}) — asked once, interactively,
+  the first time you ever run a dashboard command; answer it up front with this flag instead. Subcommands:
+    ${c.g('init')}      create/move the dashboard workspace: ${c.dim('[--path=<dir>] [--port=N] [--name=…] [--design=<id>]')}
     ${c.g('status')}    is it running? (url + pid)
     ${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')}`,
+    ${c.g('create')}    generate a custom dashboard, e.g. ${c.dim('spectoflow dashboard create "..." --auto')}
+    ${c.g('validate <file>')}  check a custom-view JSON against the block schema
+    ${c.g('login')}     connect to a remote dashboard ${c.dim('(coming in a later release)')}`,
   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
+  List every registered project in the global registry (the dashboard workspace's 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
@@ -475,6 +577,12 @@ const HELP = {
   skills: `${c.bold('spectoflow skills')}\n  List the evolving procedures (name · capability · what it does).`,
   workflow: `${c.bold('spectoflow workflow')}\n  Show the pipeline steps, marking which are enabled (●) or disabled (○).`,
   stop: `${c.bold('spectoflow stop')}\n  Stop the running dashboard (alias for ${c.g('spectoflow dashboard stop')}).`,
+  config: `${c.bold('spectoflow config')} ${c.dim('[get <key> | set <key> <value>]')}\n
+  Global settings that apply to every project on this machine, stored in ${c.dim('~/.spectoflow/config.json')}:
+    ${c.g('dashboard.url')}     the dashboard projects talk to (default http://localhost:4319)
+    ${c.g('dashboard.path')}    where the dashboard workspace lives (default ~/.spectoflow/dashboard)
+    ${c.g('defaults.agent')}    ${c.g('defaults.language')}  ${c.g('defaults.mode')}  ${c.g('defaults.design')}   seeds for ${c.g('spectoflow init')}
+  A project's own .spectoflow/config.json always wins over these defaults.`,
 };
 const showHelp = (name) => console.log('\n' + HELP[name].trim() + '\n');
 
@@ -482,6 +590,7 @@ const showHelp = (name) => console.log('\n' + HELP[name].trim() + '\n');
 const fns = {
   init, update, dashboard, stop: stopDashboard, status, list: listAll, help, version,
   projects: projectsCmd,
+  config: configCmd,
   agents: () => { console.log(wordmark()); printAgents(false); },
   skills: () => { console.log(wordmark()); printSkills(false); },
   workflow: () => { console.log(wordmark()); printWorkflow(false); },

package/lib/adapters.js

@@ -26,7 +26,7 @@ reflect it back and ask **one targeted question at a time** (each with a recomme
 is clear — then execute. See the Clarify reflex in \`.spectoflow/AGENTS.md\`.
 
 - Command: \`/spectoflow\` (\`init\` / \`status\` / or just a request).
-- Dashboard: \`node .spectoflow/dashboard/server.js\` → http://localhost:4319
+- Dashboard: \`spectoflow dashboard\` → http://localhost:4319
 - Artifacts are markdown in \`specs/\` and \`plans/\`; volatile state in \`.spectoflow/runtime.json\`.
 `;
 
@@ -254,4 +254,10 @@ function defaultRunners(agents) {
   return out;
 }
 
-module.exports = { generate, defaultRunners, REGISTRY };
+// The dashboard's flat view of REGISTRY (id/label/bin/dirs/runner/headless/docsUrl) — one roster for
+// the CLI and the dashboard, now that the dashboard ships in this package (D64).
+function knownAgents() {
+  return REGISTRY.map((a) => ({ id: a.id, label: a.label, bin: a.detect.bin, dirs: a.detect.dirs || [], runner: a.runner, headless: a.headless, docsUrl: a.docsUrl }));
+}
+
+module.exports = { generate, defaultRunners, REGISTRY, knownAgents };

package/{templates/lib → lib}/custom-dashboard.js

@@ -1,6 +1,6 @@
 'use strict';
 /*
- * Pure helpers for user-generated custom dashboards (.spectoflow/dashboard/custom/<id>.json).
+ * Pure helpers for user-generated custom dashboards (.spectoflow/dashboards/<id>.json).
  *
  * A custom dashboard is a DECLARATIVE block spec, never raw HTML/CSS/JS: the generating agent picks
  * blocks from a fixed vocabulary (BLOCK_TYPES) that the dashboard already knows how to render, using
@@ -9,7 +9,7 @@
  * the user switches to later — with zero per-dashboard styling to keep in sync, and no arbitrary code
  * ever running in the dashboard.
  *
- * Zero dependency; consumed by templates/dashboard/server.js (Node) via readCustomDashboards() in
+ * Zero dependency; consumed by lib/dashboard/handlers.js (Node) via readCustomDashboards() in
  * store.js. The browser-side renderer (dashboard/public/app.js) re-implements the tiny `resolveBind`
  * walk independently — sharing code across the Node/browser boundary would need a build step, which
  * this project avoids on purpose (see CLAUDE.md's zero-runtime-dependency invariant).

package/{templates/lib → lib}/customize-prompts.js

@@ -1,6 +1,6 @@
 'use strict';
 // Builds the exact natural-language prompts the dashboard's Settings → Customize UI posts to
-// /api/run (see templates/dashboard/public/app.js's CZ_KINDS) — the single source of truth so the
+// /api/run (see lib/dashboard/public/app.js's CZ_KINDS) — the single source of truth so the
 // CLI (`spectoflow skill/agent/dashboard create`) and the dashboard button never drift apart. The
 // browser side can't require this Node module (no build step), so its literal strings are mirrored
 // there by hand; test/customize-prompts.test.js guards against the two falling out of sync.

package/lib/dashboard/handlers.js

@@ -0,0 +1,78 @@
+'use strict';
+/*
+ * HTTP glue for one project: parse the request, pick the op, call it, serialize. Every operation
+ * lives in ops.js (pure, transport-agnostic) — nothing here decides anything about the project.
+ *
+ * createHandlers(root) returns what a listener-owning process (hub-server.js) needs:
+ *   - handleApi(req, res, u, emit): Promise<boolean> — true if this was an API route (handled).
+ *     Excludes /api/events: SSE registration stays with whoever owns the HTTP listener.
+ *   - watchDirs: dirs (relative to root) whose changes should emit {type:'change'}.
+ *   - onBoot(): once per project per process (creates the custom-views dir, clears a stale
+ *     in-flight orchestration).
+ */
+const fs = require('fs');
+const path = require('path');
+const { ops, OpError } = require('./ops');
+const orchestrator = require('./orchestrator');
+
+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({}); } }); }); }
+
+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/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));
+
+function createHandlers(root) {
+  async function handleApi(req, res, u, emit) {
+    const p = u.pathname;
+    const route = ROUTES.find(([method, m]) => method === req.method && matches(m, p));
+    if (!route) return false;
+    const [, , opName, args] = route;
+    const b = req.method === 'GET' ? {} : await body(req);
+    try {
+      const result = await ops[opName](root, args(u, b, p), { emit });
+      sendJSON(res, 200, result);
+    } catch (e) {
+      if (e instanceof OpError) sendJSON(res, e.status, { error: e.message });
+      else sendJSON(res, 500, { error: String(e && e.message || e) });
+    }
+    return true;
+  }
+  function onBoot() {
+    try { fs.mkdirSync(path.join(root, '.spectoflow', 'dashboards'), { recursive: true }); } catch (_) {}
+    // A process restart loses any in-flight orchestration; clear a stale 'running'/'awaiting_approval'
+    // so the 409 guard in orchestrate.start can't wedge forever. Not a resume — just un-wedging.
+    try { orchestrator.reconcileOnBoot(root); } catch (_) {}
+  }
+  return {
+    handleApi,
+    // The legacy custom-views dir is watched too, until `spectoflow update` migrates it (Task 4/8).
+    watchDirs: ['plans', 'specs', '.spectoflow', '.spectoflow/dashboards', '.spectoflow/dashboard/custom'],
+    onBoot,
+  };
+}
+
+module.exports = { createHandlers, ROUTES };