spectoflow 0.23.5 → 0.27.0

package/README.md

@@ -11,7 +11,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/spectoflow"><img src="https://img.shields.io/npm/v/spectoflow.svg?color=e6a54b" alt="npm version"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D18-5fb2cc" alt="node >= 18">
+  <img src="https://img.shields.io/badge/node-%3E%3D22-5fb2cc" alt="node >= 22">
   <img src="https://img.shields.io/badge/dependencies-0-4caf72" alt="zero dependencies">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
 </p>
@@ -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,35 +179,46 @@ 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.
+
+Want your own hosted, online dashboard instead of (or alongside) the local one? `server/` is a
+separate, self-hostable relay with a ready-made Docker deployment path — see
+[`server/docs/deploy-vps.md`](server/docs/deploy-vps.md).
 
 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:
+meter, a sync dot, and a **Run** quick-action. Thirteen tabs — and **which ones you see, and in what
+order, is up to you** (Personalize → *Navigation tabs*: enable / disable / reorder; two of them ship
+off by default):
 
 - **Board** — the control-room Overview (compact KPI cards, a status donut, a **scope-vs-delivered
   area curve**, a workflow-at-a-glance strip, per-phase progress bars, filter chips + search) plus the
-  phase board.
-- **Chat** — a full-height group-chat panel with **Summarize** / **Clear**.
+  phase board, as a **List** or a **Kanban** whose columns you can show/hide and that pages long
+  columns instead of scrolling them.
+- **Chat** — a full-height group-chat panel with **Summarize** / **Clear** and **slash commands** (see
+  below).
 - **Requests** — tasks awaiting you (`to_validate` / `to_analyze`).
 - **Attention** — points the agent raised (a `::spectoflow attention msg=…` sentinel) or that you
   noted yourself — edit / resolve / delete, or **validate → task**.
 - **Backlog** — a flat sortable/filterable, paginated table of every task, defaulting to open work.
 - **Workflow** — the pipeline as step cards; click one to enable/disable it, which edits `workflow.md`.
 - **Agents & Skills** — enriched cards that open a full-body markdown drawer.
+- **Files** — a project file tree with read / write / create, syntax-highlighted (self-hosted Prism.js).
+- **Bloc note** *(off by default)* — a per-project post-it Markdown scratchpad.
+- **Daily meeting** *(off by default)* — dated notes (`.spectoflow/meetings/<date>.md`), written by
+  hand or generated by the active agent.
 - **Info** — a project-at-a-glance summary.
 - **Documentation** — the live supported-agents table (your own install status + links) plus the CLI
   command reference.
-- **Personalize** — autonomy mode, language, design, the active agent, and **Extend spectoflow** (see
-  *Customize* below).
+- **Personalize** — autonomy mode, language, design, the active agent, **navigation tabs**, **slash
+  commands**, and **Extend spectoflow** (see *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 +228,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
@@ -221,6 +244,16 @@ drawer is served by the one read-only endpoint, `GET /api/agentfile?path=` (scop
 `.spectoflow/agents/**` + `.spectoflow/skills/**`, path-traversal-safe) — the framework's only other
 server surface is unchanged.
 
+### Slash commands
+
+Type `/` in either chat surface to open an autocomplete of reusable **prompt macros** — pick one,
+type your text, send. Five ship built-in (`/spec`, `/plan`, `/revue`, `/resume`, `/rapport_jour`);
+add your own from **Personalize → Commands** (a trigger, a short description, and the instruction the
+agent receives — put `{{input}}` where your text should land, or it's appended). Expansion happens
+**client-side**, so it's fully agent-agnostic: the agent never sees the `/`, it gets the full
+instruction, while the chat log keeps the short `/rapport_jour focus bugs` you typed. Commands persist
+in `config.json` (the DB online), so they survive a refresh and travel with the project.
+
 ### Customize
 
 Personalize → **Extend spectoflow** lets you extend the project's own spectoflow install: add a

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,30 @@
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
+const os = require('os');
+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 +84,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 +111,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 +133,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 +148,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 +166,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 +174,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 +184,158 @@ 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; }
+}
+
+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;
+  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') return dashboardLogin();
+  if (sub === 'logout') return dashboardLogout();
+  if (sub === 'publish') return dashboardPublish(true);
+  if (sub === 'unpublish') return dashboardPublish(false);
   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) ----
+// ---- online dashboard (C1): login / logout / publish / unpublish ----
+// The machine token authenticates this machine to a hosted dashboard (server/). `login` checks it
+// against POST /connector/whoami, stores it in the workspace's remote.json (0600) and points
+// dashboard.url at the server; the hub — running or next started — opens the outbound connection.
+async function fetchJSON(url, init = {}, timeoutMs = 10000) {
+  const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  let data = {}; try { data = await res.json(); } catch {}
+  return { status: res.status, ok: res.ok, data };
+}
+// Best-effort call on the running local hub; null when no hub is up (the caller says "next start will").
+async function hubCall(pathname, payload) {
+  const info = workspace.readLock();
+  if (!info || !info.port || !(await probeDashboard(info.port))) return null;
+  try { return await fetchJSON(`http://localhost:${info.port}${pathname}`, payload === undefined ? {} : { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); }
+  catch { return null; }
+}
+function fail(msg) { console.log(`${c.y('!')} ${msg}`); process.exitCode = 1; }
+async function dashboardLogin() {
+  const url = flag('url'), token = flag('token'), transport = flag('transport') || 'ws';
+  if (!url || !token) { console.log(`Usage: spectoflow dashboard login --url=<https://…> --token=<spf_…> ${c.dim('[--name=<machine name>] [--transport=ws|http]')}`); process.exitCode = 1; return; }
+  let base;
+  try { base = new URL(url); if (!/^https?:$/.test(base.protocol)) throw new Error(); } catch { return fail('--url must be an http(s) URL, e.g. https://dashboard.example.com'); }
+  if (!['ws', 'http'].includes(transport)) return fail('--transport must be ws or http');
+  const clean = base.toString().replace(/\/+$/, '');
+  let who;
+  try { who = await fetchJSON(`${clean}/connector/whoami`, { method: 'POST', headers: { Authorization: `Bearer ${token}` } }); }
+  catch (e) { return fail(`could not reach ${clean} (${e.cause && e.cause.code ? e.cause.code : e.name === 'TimeoutError' ? 'timeout' : e.message})`); }
+  if (who.status === 401) return fail(`${clean} rejected this token — create one on the server: node cli.js token create --name="${os.hostname()}"`);
+  if (!who.ok) return fail(`${clean} answered HTTP ${who.status} — is that the spectoflow server?`);
+  const machineName = flag('name') || os.hostname();
+  workspace.migrateLegacyHome(); if (!workspace.exists()) workspace.init({});
+  workspace.writeRemote({ url: clean, token, machineName, transport });
+  globalConfig.set('dashboard.url', clean);
+  console.log(`${c.g('✓')} logged in to ${c.bold(clean)} as ${c.bold(machineName)} ${c.dim(`(machine ${who.data.machineId || '?'}, ${transport})`)}`);
+  const r = await hubCall('/api/hub/remote/reconnect', {});
+  console.log(`  ${c.dim(r ? 'the running hub is connecting now' : 'the next `spectoflow dashboard` will connect')}`);
+  console.log(`  publish a project from inside it:  ${c.g('spectoflow dashboard publish')}`);
+}
+async function dashboardLogout() {
+  const had = workspace.clearRemote();
+  globalConfig.set('dashboard.url', `http://localhost:${resolvePort(argv)}`);
+  await hubCall('/api/hub/remote/reconnect', {});
+  console.log(had ? `${c.g('✓')} logged out — this machine no longer connects to an online dashboard` : `${c.dim('○')} not logged in to any online dashboard`);
+}
+async function dashboardPublish(published) {
+  let id = flag('id');
+  if (!id) {
+    const entry = registry.findByPath(process.cwd());
+    if (!entry) return fail(`this folder isn't registered in the dashboard yet — run ${c.g('spectoflow dashboard')} here first, or pass --id=<id> (see ${c.g('spectoflow projects')})`);
+    id = entry.id;
+  }
+  const meta = workspace.setPublished(id, published);
+  if (!meta) return fail(`no project registered with id ${id}`);
+  await hubCall(`/api/hub/projects/${encodeURIComponent(id)}/publish`, { published });
+  if (!published) return console.log(`${c.g('✓')} ${id} is no longer published`);
+  console.log(`${c.g('✓')} ${id} is published`);
+  const remote = workspace.readRemote();
+  if (remote) console.log(`  online: ${c.bold(remote.url)}`);
+  else console.log(`  ${c.dim('not logged in yet —')} ${c.g('spectoflow dashboard login --url=… --token=…')}`);
+}
+// The one-line "online" status under the local one — used by `dashboard` and `dashboard status`.
+async function printOnlineLine(port, running) {
+  const remote = workspace.readRemote();
+  if (remote) {
+    let s = null;
+    if (running) { try { s = (await fetchJSON(`http://localhost:${port}/api/hub/remote`)).data; } catch {} }
+    if (s && s.connected) return console.log(`${c.g('●')} online → ${c.bold(remote.url)} ${c.dim(`(connected via ${s.transport}, machine "${remote.machineName}")`)}`);
+    const why = !running ? 'hub not running' : s && s.lastError ? `not connected: ${s.lastError}` : 'connecting…';
+    return console.log(`${c.dim('○')} online → ${c.bold(remote.url)} ${c.dim(`(${why})`)}`);
+  }
+  const url = globalConfig.get('dashboard.url').value;
+  if (!isLocalUrl(url)) console.log(`${c.dim('○')} online → ${url} ${c.dim('— not logged in:')} ${c.g('spectoflow dashboard login --url=… --token=…')}`);
+}
+
+// ---- 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 +357,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 +427,21 @@ 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))}`);
+    await printOnlineLine(info.port, true);
     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
@@ -281,6 +451,7 @@ async function startDashboard() {
   for (let i = 0; i < 20 && !up; i++) { await new Promise((r) => setTimeout(r, 250)); up = await probeDashboard(port, 300); }
   if (up) console.log(`${c.g('✓')} hub started → ${c.bold(boardUrl(port))}  ${c.dim('(pid ' + child.pid + ')')}`);
   else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on http://localhost:${port} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
+  await printOnlineLine(port, up);
   printDashboardCommands();
 }
 
@@ -293,16 +464,17 @@ 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 + ')') : ''}`);
   else console.log(`${c.dim('○')} hub not running`);
+  await printOnlineLine(port, running);
 }
 
 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 +487,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 +523,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 +575,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')} ${c.dim('--url=<u> --token=<t>')}  connect this machine to an online dashboard ${c.dim('(logout · publish · unpublish)')}
+  ${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 +614,30 @@ 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|logout|publish|unpublish]')}\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 this machine to an online dashboard: ${c.dim('--url=<https://…> --token=<spf_…> [--name=<machine>] [--transport=ws|http]')}
+    ${c.g('logout')}    forget it (remote.json removed, dashboard.url back to local)
+    ${c.g('publish')}   make the current project (or ${c.dim('--id=<id>')}) visible online — nothing is published by default
+    ${c.g('unpublish')} take it back offline`,
   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 +659,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 +672,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 };