spectoflow 0.23.4 → 0.24.0

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,84 @@
+'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'));
+}
+
+module.exports = { dir, exists, settings, settingsPath, lockPath, projectDir, init, registerProject, migrateLegacyHome, readLock };

package/package.json

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

package/templates/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)

package/templates/agents/framework-curator.md

@@ -28,11 +28,10 @@ project's own team will use to build product features.
 ## Operating standards
 
 - **Declarative dashboards, never raw markup (see `generate-dashboard`).** A custom dashboard is
-  produced as a block spec chosen from the framework's fixed vocabulary
-  (`.spectoflow/lib/custom-dashboard.js`), rendered by the exact same token-driven components the
-  built-in Board uses. Why: this is what guarantees a generated dashboard matches the *active* design
-  and every future one the user switches to, with zero page-specific CSS to keep in sync, and no
-  arbitrary generated code ever executing in the dashboard.
+  produced as a block spec chosen from the framework's fixed vocabulary, rendered by the exact same
+  token-driven components the built-in Board uses. Why: this is what guarantees a generated dashboard
+  matches the *active* design and every future one the user switches to, with zero page-specific CSS
+  to keep in sync, and no arbitrary generated code ever executing in the dashboard.
 - **Gold-standard shape for skills and agents (`docs/agents-skills-standard.md`).** A generated
   `SKILL.md` or agent `.md` follows the exact same front-matter and heading structure as every
   shipped one — `## When to use` / `## Method` / `## Output contract` / `## Quality bar` /
@@ -61,19 +60,19 @@ A generated dashboard renders correctly in every shipped design (light and dark)
 hardcoded color or manual style — verified by construction, since only the declarative block
 vocabulary was used. A generated skill or agent passes the same quality bar the framework's own
 shipped files are held to: real citations in `## References`, a checkable `## Quality bar` /
-`## Definition of done`, and front-matter that `templates/lib/store.js`'s flat parser can read
+`## Definition of done`, and front-matter that the dashboard's flat parser can read
 unchanged. The new dashboard tab, skill, or agent is visible in the dashboard (Board's nav / Agents &
 Skills tab) on the very next SSE tick — no manual refresh, no extra registration step.
 
 ## Handoff
 
-Writes the generated file(s) directly (`.spectoflow/dashboard/custom/<id>.json`,
+Writes the generated file(s) directly (`.spectoflow/dashboards/<id>.json`,
 `.spectoflow/skills/<slug>/SKILL.md`, or `.spectoflow/agents/<slug>.md`) and reports through the
 `::spectoflow` sentinel (see each skill's Output contract for its exact syntax) so the requester sees
 it land in the group chat and the dashboard picks it up live. A dashboard spec that fails
-`.spectoflow/lib/custom-dashboard.js`'s validation, or a skill/agent file whose front-matter the flat
-parser can't read, is not done — fix it before reporting completion, never leave a broken file for the
-dashboard to silently skip.
+`spectoflow dashboard validate`, or a skill/agent file whose front-matter the flat parser can't read,
+is not done — fix it before reporting completion, never leave a broken file for the dashboard to
+silently skip.
 
 ## Guardrails
 
@@ -90,5 +89,6 @@ dashboard to silently skip.
 ## References
 
 - `docs/agents-skills-standard.md` — the gold-standard shape this role's output must match.
-- `.spectoflow/lib/custom-dashboard.js` — the declarative block vocabulary and its validator.
+- `spectoflow dashboard validate <file>` — the declarative block vocabulary's validator (in the
+  spectoflow package).
 - `.spectoflow/skills/clarify` — the reflex this role leans on before generating from an ambiguous ask.

package/templates/capabilities.md

@@ -17,7 +17,7 @@ the Clarify step in `AGENTS.md`.
 `customization` is also **not a workflow step** — it is triggered explicitly, either from the
 dashboard's Settings → Customize page or by a direct request ("add a dashboard for…", "create a skill
 for…", "create an agent for…"). The `framework-curator` agent owns it, running one of four skills:
-`generate-dashboard` (a declarative block-spec page — see `templates/lib/custom-dashboard.js`),
+`generate-dashboard` (a declarative block-spec page — validated by `spectoflow dashboard validate`),
 `generate-skill`, `generate-agent` (both follow `docs/agents-skills-standard.md`'s gold-standard
 shape, grounded in real, cited domain standards), and `propose-customizations` (the "Auto" mode:
 analyzes the project and proposes candidates instead of taking a description). Still gated by mode

package/templates/skills/generate-dashboard/SKILL.md

@@ -3,7 +3,7 @@ name: generate-dashboard
 description: Turn a description (or an auto-analysis) into a new custom dashboard page, as a declarative block spec that automatically matches every design the dashboard ships.
 capability: customization
 inputs: A description of what the dashboard should show (from the Customize page or chat), or a chosen candidate from propose-customizations; the project's specs/plans/code as source material.
-outputs: A validated block-spec JSON file at .spectoflow/dashboard/custom/<id>.json, live in the dashboard's nav on the next tick.
+outputs: A validated block-spec JSON file at .spectoflow/dashboards/<id>.json, live in the dashboard's nav on the next tick.
 standard: declarative UI generation; Few's dashboard design principles
 ---
 # Generate dashboard
@@ -67,8 +67,8 @@ computed stats the Board already uses (see step 5).
 
 ### 4. Choose blocks — the vocabulary
 
-Pick from exactly these block types (anything else is invisible to the renderer — see
-`.spectoflow/lib/custom-dashboard.js` for the enforced schema):
+Pick from exactly these block types (anything else is invisible to the renderer — the block schema
+documented below is enforced by `spectoflow dashboard validate`):
 
 | `type` | Shape | Use for |
 |---|---|---|
@@ -102,7 +102,7 @@ in one screen — 4-8 blocks is a healthy page, not 20.
 ### 6. Pick an id, a title, an icon
 
 - `id`: lowercase kebab-case, unique among existing custom dashboards (list
-  `.spectoflow/dashboard/custom/*.json` first) — this becomes the URL segment and the file name.
+  `.spectoflow/dashboards/*.json` first) — this becomes the URL segment and the file name.
 - `title`: short, a few words, shown as the nav tab label.
 - `icon`: one of `board`, `requests`, `backlog`, `workflow`, `agents`, `chat`, `info`, `attention`,
   `settings` (the same set the rest of the dashboard uses — pick the closest match; default to `info`
@@ -110,19 +110,21 @@ in one screen — 4-8 blocks is a healthy page, not 20.
 
 ### 7. Write and verify
 
-Write the spec to `.spectoflow/dashboard/custom/<id>.json` (pretty-printed, 2-space indent). Then
+Write the spec to `.spectoflow/dashboards/<id>.json` (pretty-printed, 2-space indent). Then
 **verify it, don't assume it's valid** — run:
 ```
-node -e "console.log(JSON.stringify(require('./.spectoflow/lib/custom-dashboard').validateSpec(JSON.parse(require('fs').readFileSync('./.spectoflow/dashboard/custom/<id>.json','utf8')))))"
+spectoflow dashboard validate .spectoflow/dashboards/<id>.json
 ```
-If `valid` is `false`, fix the reported errors and re-run before reporting done — a spec the
-dashboard's own validator rejects is never a finished deliverable, it would simply be skipped and the
-user would see nothing.
+(use `npx spectoflow …` if spectoflow isn't on PATH)
+
+If the output shows errors, fix them and re-run before reporting done — a spec the dashboard's own
+validator rejects is never a finished deliverable, it would simply be skipped and the user would see
+nothing.
 
 ## Output contract
 
-- One file: `.spectoflow/dashboard/custom/<id>.json`, valid against
-  `.spectoflow/lib/custom-dashboard.js`'s `validateSpec` (verified per step 7, not assumed).
+- One file: `.spectoflow/dashboards/<id>.json`, valid against the block schema
+  (verified per step 7 with `spectoflow dashboard validate`, not assumed).
 - Progress and completion reported to the orchestrator and group chat:
 
 ```
@@ -147,6 +149,6 @@ user would see nothing.
 - Stephen Few, *Information Dashboard Design* (O'Reilly/Analytics Press) — one purpose per dashboard,
   the plainest chart that carries the point, single-screen legibility.
   https://www.perceptualedge.com/library.php
-- `.spectoflow/lib/custom-dashboard.js` — the enforced block schema and bind allow-list (source of
-  truth; this document summarizes it, the code is authoritative).
+- `spectoflow dashboard validate <file>` — the declarative block vocabulary's validator (in the
+  spectoflow package; enforces the block schema and bind allow-list).
 - `dashboard/public/stats.js` — the exact shape of the live stats object bindable via `bind`.

package/templates/dashboard/custom/.gitkeep

@@ -1,3 +0,0 @@
-# This directory holds user-generated custom dashboard specs (created via the Customize page in
-# Settings, or written directly by the `generate-dashboard` skill). Empty on a fresh install.
-# Schema: templates/lib/custom-dashboard.js