spectoflow 0.13.0 → 0.13.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 G. MOMO
+Copyright (c) 2026 Georges MOMO
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -23,8 +23,27 @@ ceremonial command to start.
 ## Install
 
 ```bash
-npm install -g spectoflow        # (once published)
-spectoflow init /path/to/project # or: node bin/spectoflow.js init .
+# npm (recommended)
+npm install -g spectoflow
+spectoflow init /path/to/project
+
+# or use it straight from a clone, no global install
+git clone https://github.com/georgesmomo/spectoflow
+node spectoflow/bin/spectoflow.js init /path/to/project
+```
+
+Every command works both ways — `spectoflow <cmd>` when installed globally, or `node
+/path/to/spectoflow/bin/spectoflow.js <cmd>` from a clone.
+
+### CLI
+
+```
+spectoflow init [dir] [--agent=claude,codex]   scaffold a project (auto-detects installed agents)
+spectoflow update [--dry-run]                  refresh framework files to this kit version
+spectoflow dashboard [--port=NNNN]             run the local control plane (default 4319)
+spectoflow status                              progress + whether the dashboard is running
+spectoflow --version   (-v)                    print the version
+spectoflow --help      (-h)                    show help
 ```
 
 `init` scaffolds:
@@ -90,20 +109,34 @@ agent never clobber each other.
 ## Dashboard (real-time)
 
 ```bash
-node .spectoflow/dashboard/server.js   # → http://localhost:4319
+spectoflow dashboard                     # → http://localhost:4319 (or --port=NNNN)
+# manual (no global install): node .spectoflow/dashboard/server.js
 ```
 
-Zero dependencies, updates live via SSE + file watching. Seven tabs behind a dense icon-tab header
-(brand · subtitle · a slim global-progress meter · a sync dot · a **Run** quick-action): **Board**
-(the control-room Overview — KPI cards, a status donut, a **scope-vs-delivered area curve**, a
+`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. Eight tabs behind a dense icon-tab header (brand logo · subtitle · a slim
+global-progress meter · a sync dot · a **Run** quick-action · a **settings** gear): **Board** (the
+control-room Overview — 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),
-**Requests** (tasks awaiting you — `to_validate`/`to_analyze`), **Backlog** (a flat sortable/filterable
-table of every task across every plan), **Workflow** (the pipeline as a diagram — click a step to
-enable/disable it, which edits `workflow.md`), **Agents & Skills** (enriched cards — capability,
-standards, uses/inputs/outputs — that open a full-body markdown drawer), **Chat** (a full-height
-group-chat panel), and **Info** (a project-at-a-glance summary). Charts are zero-dep, hand-rolled SVG
-in `dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
-every aggregate is computed client-side.
+**Requests** (tasks awaiting you — `to_validate`/`to_analyze`), **Attention** (points the agent raised
+via a `::spectoflow attention msg=…` sentinel or that you noted — 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), **Chat** (a
+full-height group-chat panel), and **Info** (a project-at-a-glance summary). 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 every aggregate is computed
+client-side.
+
+**Designs & theme.** The dashboard ships **switchable designs** (Settings → *Dashboard design*):
+**Control Room** (violet), **Obsidian Ops** (near-black lime/cyan, mono), and **Neon Command**
+(glassmorphism aurora). 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 choice persists per viewer (localStorage) and as the project
+default (`config.design`).
 
 A floating **💬 chat widget** (bottom-right, redesigned) and the **Chat** tab render the same
 `runtime.messages` log via a shared `renderChatLog()`, so they never drift. A running agent identifies
@@ -125,9 +158,14 @@ INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liner
 
 ## Language
 
-`.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable.
+`.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable from the CLI
+(`config.json`) or the dashboard's **settings** gear (mode + language).
 
 ## Studied, not copied
 
 Structure informed by spec-kit, OpenSpec (markdown + per-agent adapters), and BMAD (agent-personas).
-spectoflow keeps the good ideas, removes the ceremony, and adds a real-time control plane. MIT.
+spectoflow keeps the good ideas, removes the ceremony, and adds a real-time control plane.
+
+## License & author
+
+MIT © 2026 [Georges MOMO](https://github.com/georgesmomo).

package/bin/spectoflow.js

@@ -16,6 +16,11 @@ const VERSION = require('../package.json').version;
 const argv = process.argv.slice(2);
 const cmd = argv[0] || 'help';
 
+// Tiny ANSI colouriser — no dependency; disabled when not a TTY or NO_COLOR is set.
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const c = { g: paint('32'), cy: paint('36'), b: paint('34'), y: paint('33'), dim: paint('2'), bold: paint('1'), amber: paint('38;5;179') };
+
 // ---- dashboard port + running-state probe ------------------------------------
 // Precedence: --port=NNNN > SPECTOFLOW_PORT env > 4319 (matches templates/dashboard/server.js).
 function resolvePort(args) {
@@ -156,18 +161,27 @@ function update() {
   const r = require('../lib/update').runUpdate({ projectRoot: root, templatesDir: TPL, version: VERSION, dryRun });
 
   const from = r.fromVersion || 'unknown';
-  console.log(`spectoflow update — ${from} → ${r.toVersion}${dryRun ? '   (dry-run)' : ''}`);
-  const line = (label, list) => list.length && console.log(`  ${label.padEnd(10)} ${String(list.length).padStart(2)}   ${list.join(', ')}`);
-  line('refreshed', r.refreshed);
-  line('created', r.created);
-  line('adopted', r.adopted);
-  line('.new', r.newSidecar);
-  if (r.unchanged.length) console.log(`  ${'unchanged'.padEnd(10)} ${String(r.unchanged.length).padStart(2)}`);
-  console.log(`  ${'preserved'.padEnd(10)}      config.json, workflow.md, specs/, plans/, your custom agents & skills`);
-  if (r.newSidecar.length) {
-    console.log(`\n${r.newSidecar.length} file(s) you edited have a new version alongside as *.new — compare and merge by hand.`);
-  }
-  if (dryRun) console.log('\n(dry-run — nothing was written)');
+  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length;
+  const row = (sym, label, list, painter, note) => {
+    if (!list.length) return;
+    const n = c.dim(String(list.length).padStart(2));
+    const detail = note ? c.dim(note) : c.dim(list.slice(0, 6).join(', ') + (list.length > 6 ? ` +${list.length - 6} more` : ''));
+    console.log(`  ${sym}  ${painter(label.padEnd(9))} ${n}   ${detail}`);
+  };
+  console.log('');
+  console.log(`  ${c.bold('spectoflow update')}   ${c.dim(from)} ${c.amber('→')} ${c.bold(r.toVersion)}${dryRun ? c.dim('   (dry-run)') : ''}`);
+  console.log('');
+  row(c.g('✓'), 'refreshed', r.refreshed, c.g);
+  row(c.cy('+'), 'created', r.created, c.cy);
+  row(c.b('~'), 'adopted', r.adopted, c.b);
+  row(c.y('!'), '.new', r.newSidecar, c.y, 'you edited these — new version saved as *.new, merge by hand');
+  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('');
+  if (dryRun) console.log(`  ${c.dim('(dry-run — nothing was written)')}`);
+  else console.log(`  ${changed ? c.g('✓ Done') : c.dim('Already up to date')}${changed ? c.dim(` · ${changed} file(s) changed`) : ''}`);
+  if (r.newSidecar.length && !dryRun) console.log(`  ${c.y('→')} ${c.dim(`${r.newSidecar.length} *.new file(s) to review and merge`)}`);
+  console.log('');
 }
 
 // THE launch command — prints the URL clearly and won't crash on EADDRINUSE: it probes first
@@ -204,11 +218,26 @@ async function status() {
   console.log(`dashboard: ${running ? `running → http://localhost:${port}` : 'not running'}`);
 }
 
-const help = () => console.log(`spectoflow — commands:
-  init [dir] [--agent=claude,codex]   install into a project
-  update [--dry-run]                  refresh framework files to this kit version
-  dashboard [--port=NNNN]             run the local control plane (default 4319, or $SPECTOFLOW_PORT)
-  status                              print progress`);
+function version() { console.log(`spectoflow v${VERSION}`); }
+
+const help = () => console.log(`${c.bold('spectoflow')} ${c.amber('v' + VERSION)} — agent-agnostic spec-driven development
+
+${c.dim('Usage:')} spectoflow <command> [options]
+
+${c.bold('Commands:')}
+  ${c.g('init')} [dir] [--agent=claude,codex]   scaffold a project (auto-detects installed agents)
+  ${c.g('update')} [--dry-run]                  refresh framework files to this kit version
+  ${c.g('dashboard')} [--port=NNNN]             run the local control plane (default 4319, or $SPECTOFLOW_PORT)
+  ${c.g('status')}                              print progress + whether the dashboard is running
+
+${c.bold('Options:')}
+  -v, --version                       print the version
+  -h, --help                          show this help
+
+${c.dim('Docs:')} https://github.com/georgesmomo/spectoflow`);
 
-const fns = { init, update, dashboard, status, help };
-fns[cmd] ? fns[cmd]() : help();
+const fns = { init, update, dashboard, status, help, version };
+if (['-v', '-V', '--version', 'version'].includes(cmd)) version();
+else if (['-h', '--help'].includes(cmd)) help();
+else if (fns[cmd]) fns[cmd]();
+else help();

package/package.json

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

package/templates/dashboard/public/app.js

@@ -6,6 +6,8 @@ let backlogFilter = { status: 'open', q: '' }; // backlog defaults to open (not-
 let backlogSort = { col: 'id', dir: 'asc' };   // backlog sort state — client-side only
 let backlogPage = 1; const BACKLOG_PAGE = 25;   // backlog pagination — client-side only
 let attnFilter = 'open';                          // attention tab filter — client-side only
+// apply the persisted design skin as early as possible (before the first paint of app-driven DOM)
+(function(){ try{ const d=localStorage.getItem('spf-design'); if(d) document.documentElement.setAttribute('data-design',d); }catch{} })();
 
 const $ = (s,r=document)=>r.querySelector(s);
 const $$ = (s,r=document)=>[...r.querySelectorAll(s)];
@@ -115,9 +117,7 @@ function flash(){ const s=$('#sync'); s.classList.add('saving'); $('#syncLabel')
 function render(){
   const c = P.config||{};
   $('#projectName').textContent = c.projectType || 'project';
-  $('#agentChip').textContent = c.agent||'claude';
-  $('#langChip').textContent = c.language||'en';
-  $('#modeChip').textContent = c.mode||'semi';
+  const bv=$('#brandVer'); if(bv){ if(P.version){ bv.textContent='v'+P.version; bv.hidden=false; } else { bv.hidden=true; } }
   $('#brandSub').textContent = (c.mode||'semi') + ' · ' + (c.language||'en');
   // agent select — widget (#runAgent) and Chat tab (#tabRunAgent) each get their own populated
   // <select>, since an id can't be shared by two elements; same option list, same source of truth.
@@ -133,7 +133,7 @@ function render(){
   if(meter) meter.title=`Global progress: ${s.pct}% (${s.done}/${s.total} tasks)`;
   renderOverview(); renderBoard(); renderBacklog(); renderWorkflow(); renderTeam();
   renderChatLog($('#chatLog')); renderChatLog($('#chatTabLog'));
-  renderSidebar(); renderRequests(); renderAttention(); renderInfo();
+  renderSidebar(); renderRequests(); renderAttention(); renderInfo(); renderSettings();
   applyActiveTab(); // re-apply the current tab so an SSE-driven re-render never resets to Board
 }
 
@@ -202,8 +202,9 @@ function countUp(node){
   requestAnimationFrame(tick);
 }
 
-function kpiCard(label,visual,sub){
+function kpiCard(label,visual,sub,accent){
   const c=el('div','kpi');
+  if(accent){ c.style.borderLeftColor=accent; c.classList.add('has-accent'); }
   c.append(el('div','kpi-label',label));
   const body=el('div','kpi-body'); body.append(visual); c.append(body);
   if(sub) c.append(el('div','kpi-sub',sub));
@@ -228,15 +229,15 @@ function renderOverview(){
 
   // KPI row
   const kpis=el('div','kpi-row');
-  kpis.append(kpiCard('Global progress', ring(s.pct,72), `${s.done}/${s.total} tasks`));
-  kpis.append(kpiCard('In progress', numBlock(s.byStatus.in_progress||0,'var(--s-in_progress)'), 'tasks'));
-  kpis.append(kpiCard('To validate', numBlock(s.byStatus.to_validate||0,'var(--s-to_validate)'), 'awaiting review'));
+  kpis.append(kpiCard('Global progress', ring(s.pct,72), `${s.done}/${s.total} tasks`, cssv('--s-done')));
+  kpis.append(kpiCard('In progress', numBlock(s.byStatus.in_progress||0,'var(--s-in_progress)'), 'tasks', cssv('--s-in_progress')));
+  kpis.append(kpiCard('To validate', numBlock(s.byStatus.to_validate||0,'var(--s-to_validate)'), 'awaiting review', cssv('--s-to_validate')));
   const r=s.running||{};
   let runVal='—', runSub='no runs yet';
   if(r.agents>0){ runVal=`${r.agents} running`; runSub='agents active'; }
   else if(r.orchestration&&r.orchestration.status){ runVal=r.orchestration.status; runSub='orchestration'; }
   else if(r.lastRun){ runVal=r.lastRun.status||'—'; runSub='last: '+(r.lastRun.tool||'—'); }
-  kpis.append(kpiCard('Running', numBlock(runVal, r.agents>0?'var(--signal)':'var(--muted)', true), runSub));
+  kpis.append(kpiCard('Running', numBlock(runVal, r.agents>0?'var(--signal)':'var(--muted)', true), runSub, cssv('--signal')));
   box.append(kpis);
 
   // Status donut + legend
@@ -469,40 +470,104 @@ function renderTask(t){
   return c;
 }
 
+// Plain-language explanation of what each workflow step does, resolved from the step name — so the
+// detail zone teaches the user what the pipeline is, not just that a step exists.
+function wfDesc(s){
+  const n=String(s.name||'').toLowerCase();
+  if(/brainstorm|idea|intake/.test(n)) return 'Explore the request before committing to it — clarify the goal, constraints and success criteria, and shape a raw idea into something worth building.';
+  if(/analy/.test(n)) return 'Break the idea down: study the existing code and requirements, surface risks and ambiguities, and pin down clear, testable acceptance criteria.';
+  if(/spec/.test(n)) return 'Write the specification — the versioned, plain-markdown source of truth for what to build and why, before any code is written.';
+  if(/plan/.test(n)) return 'Turn the spec into an ordered plan of small, checkbox tasks — each one testable and executable on its own by a developer or an agent.';
+  if(/develop|implement|\bcode\b/.test(n)) return 'Implement the plan task by task, writing the code (and the tests that pin it down) to satisfy each checkbox.';
+  if(/integration/.test(n)) return 'Check that the pieces work together — modules, services and data paths across component boundaries, not just in isolation.';
+  if(/end.?to.?end|e2e/.test(n)) return 'Exercise the whole product the way a real user would, through the actual UI and end-to-end flows.';
+  if(/unit/.test(n)||/\btest/.test(n)) return 'Verify each unit in isolation — fast, focused tests that lock in behaviour and catch regressions early.';
+  if(/review/.test(n)) return 'A final quality pass — correctness, security and standards — before the work is considered done.';
+  if(/deploy|ship|release|publish/.test(n)) return 'Release the delivered work — ship it to its target environment.';
+  return 'A step in the delivery pipeline.';
+}
+let wfPopStep=null; // name of the step whose click-popover is open (null = closed)
+
+// Workflow — a horizontal pipeline of representative icons with directional arrows. Clicking a step
+// opens a floating popover (tooltip-style, anchored to the step) with what it does, its
+// capability/agent/skill, and the enable/disable button. On narrow screens the pipeline reflows into
+// a centered wrap (no horizontal scroll).
 function renderWorkflow(){
   const box=$('#wfDiagram'); box.innerHTML='';
   const steps=P.workflow||[];
-  if(!steps.length){ box.append(el('div','empty','No workflow defined.')); return; }
+  if(!steps.length){ box.append(el('div','empty','No workflow defined.')); closeWfPop(); return; }
   const enabledCount=steps.filter(s=>s.enabled).length;
   const legend=el('div','wf-legend');
-  legend.append(el('span','wf-legend-txt',`${enabledCount}/${steps.length} steps enabled`));
+  legend.append(el('span','wf-legend-dot'));
+  legend.append(el('span','wf-legend-txt',`${enabledCount} of ${steps.length} steps enabled — click a step to see what it does`));
   box.append(legend);
-  const track=el('div','wf-track');
+  const pipe=el('div','wf-pipeline');
   steps.forEach((s,i)=>{
-    const node=el('div','wf-card'+(s.enabled?'':' off')); node.tabIndex=0; node.setAttribute('role','button');
-    node.setAttribute('aria-pressed',String(!!s.enabled));
-    const head=el('div','wf-card-head');
-    head.append(el('span','wf-num',String(i+1)));
-    head.append(el('span','wf-card-name',s.name));
-    if(s.optional) head.append(el('span','wf-opt','optional'));
-    node.append(head);
-    if(s.cap||s.skill){
-      const meta=el('div','wf-card-meta');
-      if(s.cap) meta.append(el('span','wf-cap',s.cap));
-      if(s.skill) meta.append(el('span','wf-skill',s.skill));
-      node.append(meta);
-    }
-    const toggle=el('div','wf-toggle');
-    toggle.append(el('span','wf-toggle-dot'));
-    toggle.append(el('span','wf-toggle-label',s.enabled?'enabled':'disabled'));
-    node.append(toggle);
-    const act=()=>toggleStep(s.name);
-    node.addEventListener('click',act);
-    node.addEventListener('keydown',e=>{ if(e.key==='Enter'||e.key===' '){ e.preventDefault(); act(); } });
-    track.append(node);
-    if(i<steps.length-1) track.append(el('div','wf-conn'+(s.enabled&&steps[i+1].enabled?'':' off')));
+    const step=el('div','wf-step2'+(s.enabled?' on':' off')+(s.name===wfPopStep?' is-selected':'')); step.style.setProperty('--i',i); step.dataset.idx=i;
+    step.tabIndex=0; step.setAttribute('role','button'); step.setAttribute('aria-expanded',String(s.name===wfPopStep));
+    step.title=s.name;
+    const circle=el('div','wf-circle');
+    circle.innerHTML=(typeof ICON!=='undefined'&&ICON.wf)?ICON.wf(s.name):'';
+    step.append(circle);
+    const cap=el('div','wf-caption'); cap.append(document.createTextNode(s.name));
+    if(s.optional) cap.append(el('span','wf-opt2','optional'));
+    step.append(cap);
+    const sel=(e)=>{ if(e) e.stopPropagation(); if(wfPopStep===s.name) closeWfPop(); else openWfPop(s.name); };
+    step.addEventListener('click',sel);
+    step.addEventListener('keydown',e=>{ if(e.key==='Enter'||e.key===' '){ e.preventDefault(); sel(e); } });
+    pipe.append(step);
+    if(i<steps.length-1) pipe.append(el('div','wf-link'+(s.enabled&&steps[i+1].enabled?' on':'')));
   });
-  box.append(track);
+  box.append(pipe);
+  if(wfPopStep) renderWfPop(); // re-anchor / refresh an open popover after a live re-render
+}
+function wfDetailRow(k,v){ const r=el('div','wf-detail-row'); r.append(el('span','wf-detail-k',k), el('span','wf-detail-v',v)); return r; }
+function wfPopFill(pop, s, idx){
+  const skill=(P.skills||[]).find(x=>x.name===s.skill);
+  const agent=(P.agents||[]).find(a=>a.capability===s.cap);
+  pop.innerHTML='';
+  const head=el('div','wf-detail-head');
+  head.append(el('span','wf-detail-num',String(idx+1)));
+  head.append(el('span','wf-detail-name',s.name));
+  head.append(el('span','wf-detail-status '+(s.enabled?'on':'off'), s.enabled?'enabled':'disabled'));
+  if(s.optional) head.append(el('span','wf-opt','optional'));
+  pop.append(head);
+  pop.append(el('p','wf-detail-desc', wfDesc(s)));
+  const grid=el('div','wf-detail-grid');
+  grid.append(wfDetailRow('Capability', s.cap||'—'));
+  grid.append(wfDetailRow('Handled by', agent?(agent.title||agent.name):'—'));
+  grid.append(wfDetailRow('Skill', s.skill||'—'));
+  if(skill&&skill.standard) grid.append(wfDetailRow('Standard', skill.standard));
+  if(skill&&(skill.inputs||skill.outputs)) grid.append(wfDetailRow('Flow', (skill.inputs||'—')+'  →  '+(skill.outputs||'—')));
+  pop.append(grid);
+  if(skill&&skill.description){ const sk=el('div','wf-detail-skill'); sk.append(el('b',null,'The “'+skill.name+'” skill — ')); sk.append(document.createTextNode(skill.description)); pop.append(sk); }
+  const btn=el('button','btn '+(s.enabled?'':'primary')+' wf-detail-btn', s.enabled?'Disable step':'Enable step');
+  btn.addEventListener('click',(e)=>{ e.stopPropagation(); toggleStep(s.name); });
+  const actions=el('div','wf-pop-actions'); actions.append(btn); pop.append(actions);
+}
+function openWfPop(name){ wfPopStep=name; renderWfPop(); }
+function closeWfPop(){ wfPopStep=null; const p=$('#wfPop'); if(p) p.hidden=true; $$('#wfDiagram .wf-step2.is-selected').forEach(x=>x.classList.remove('is-selected')); }
+function renderWfPop(){
+  const p=$('#wfPop'); if(!p) return;
+  const steps=P.workflow||[]; const idx=steps.findIndex(s=>s.name===wfPopStep);
+  if(idx<0){ closeWfPop(); return; }
+  const anchor=$('#wfDiagram .wf-step2[data-idx="'+idx+'"]');
+  if(!anchor){ p.hidden=true; return; }
+  $$('#wfDiagram .wf-step2.is-selected').forEach(x=>x.classList.remove('is-selected')); anchor.classList.add('is-selected');
+  wfPopFill(p, steps[idx], idx);
+  positionWfPop(anchor.querySelector('.wf-circle')||anchor, p);
+}
+function positionWfPop(anchorEl, pop){
+  const r=anchorEl.getBoundingClientRect();
+  pop.style.visibility='hidden'; pop.hidden=false; pop.classList.remove('above');
+  const pw=pop.offsetWidth, ph=pop.offsetHeight;
+  const left=Math.max(10, Math.min(r.left + r.width/2 - pw/2, window.innerWidth-pw-10));
+  let top=r.bottom + 12, above=false;
+  if(top + ph > window.innerHeight-10 && r.top - ph - 12 > 10){ top=r.top - ph - 12; above=true; }
+  pop.style.left=left+'px'; pop.style.top=top+'px';
+  pop.classList.toggle('above',above);
+  pop.style.setProperty('--caret-x', ((r.left + r.width/2) - left)+'px');
+  pop.style.visibility='';
 }
 
 // ---- Attention tab: agent/user-raised points; validate → real task ----------
@@ -552,29 +617,59 @@ async function patchAttn(id,patch){ flash(); await fetch('/api/attention/'+encod
 async function deleteAttn(id){ flash(); await fetch('/api/attention/'+encodeURIComponent(id),{method:'DELETE'}); }
 async function promoteAttn(id){ flash(); await fetch('/api/attention/'+encodeURIComponent(id)+'/promote',{method:'POST'}); }
 
-// ---- Settings popover: change autonomy mode + output language (writes config.json) ----
-function openSettings(open){
-  const pop=$('#settingsPop'); if(!pop) return;
-  if(open){ const c=P&&P.config||{}; if($('#setMode')) $('#setMode').value=c.mode||'semi'; setLangSelect(c.language||'en'); }
-  pop.hidden=!open;
-}
+// ---- Settings tab: change autonomy mode + output language (writes config.json) ----
 function setLangSelect(lang){
   const sel=$('#setLang'); if(!sel) return;
   if(![...sel.options].some(o=>o.value===lang)){ const o=document.createElement('option'); o.value=lang; o.textContent=lang; sel.append(o); }
   sel.value=lang;
 }
-async function saveSettings(){ flash(); const mode=$('#setMode').value, language=$('#setLang').value;
-  await fetch('/api/settings',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({mode,language})}); }
+// ---- design skins (data-design) — switchable, persisted per viewer + as the project default ----
+function currentDesign(){ return document.documentElement.getAttribute('data-design')||'control-room'; }
+function applyDesign(id){ document.documentElement.setAttribute('data-design',id); try{ localStorage.setItem('spf-design',id); }catch{} }
+async function saveDesign(id){ applyDesign(id); if(P) render(); /* re-read token colours into the SVG charts */ flash(); try{ await fetch('/api/settings',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({design:id})}); }catch{} }
+
+function renderSettings(){
+  const c=(P&&P.config)||{};
+  if($('#setMode')) $('#setMode').value=c.mode||'semi';
+  setLangSelect(c.language||'en');
+  // design switcher — options from the DESIGNS registry (designs.js)
+  const dsel=$('#setDesign');
+  if(dsel){
+    const designs=(typeof DESIGNS!=='undefined')?DESIGNS:[{id:'control-room',name:'Control Room'}];
+    if(dsel.options.length!==designs.length){ dsel.innerHTML=''; designs.forEach(d=>{ const o=document.createElement('option'); o.value=d.id; o.textContent=d.name; if(d.desc) o.title=d.desc; dsel.append(o); }); }
+    // reconcile: a per-viewer choice (localStorage) wins; else the project default (config.design)
+    let active; try{ active=localStorage.getItem('spf-design'); }catch{}
+    if(!active && c.design) active=c.design;
+    if(active && active!==currentDesign() && designs.some(d=>d.id===active)) document.documentElement.setAttribute('data-design',active);
+    dsel.value=currentDesign();
+  }
+  const box=$('#settingsReadonly');
+  if(box){
+    box.innerHTML='';
+    const rows=[['Active agent',c.agent||'—'],['Project type',c.projectType||'—'],
+      ['Plans folder',c.plansDir||'plans'],['Specs folder',c.specsDir||'specs'],
+      ['Framework version', P&&P.version?('v'+P.version):'—']];
+    rows.forEach(([k,v])=>{ const r=el('div','settings-ro-row'); r.append(el('span','settings-ro-k',k), el('span','settings-ro-v',String(v))); box.append(r); });
+  }
+  const fv=$('#footerVer'); if(fv) fv.textContent = (P&&P.version) ? ('v'+P.version) : '';
+}
+async function saveSettings(){
+  flash(); const mode=$('#setMode').value, language=$('#setLang').value;
+  await fetch('/api/settings',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({mode,language})});
+  const s=$('#settingsSaved'); if(s){ s.hidden=false; setTimeout(()=>{ s.hidden=true; },1500); }
+}
 
 // ---- client-side routing: /<tab>[/<taskId>] via the History API ------------
-const ROUTES=['board','requests','attention','backlog','workflow','team','chat','info'];
+const ROUTES=['board','requests','attention','backlog','workflow','team','chat','info','settings'];
 function tabFromPath(){ const s=location.pathname.split('/').filter(Boolean); return ROUTES.includes(s[0])?s[0]:null; }
 function taskFromPath(){ const s=location.pathname.split('/').filter(Boolean); return (ROUTES.includes(s[0])&&s[1])?decodeURIComponent(s[1]):null; }
 function navigateTab(t,push){
   activeTab=t; try{ localStorage.setItem('spf-tab',t); }catch{}
   if(push!==false) history.pushState(null,'','/'+t);
   applyActiveTab();
+  closeNav(); // a tab pick closes the mobile menu
 }
+function closeNav(){ document.body.classList.remove('nav-open'); const nt=$('#navToggle'); if(nt) nt.setAttribute('aria-expanded','false'); }
 
 // chip row: a small uppercase kicker label followed by one chip per item — used for
 // agent standards/uses and the skill standard.
@@ -804,6 +899,16 @@ function applyActiveTab(){
   $$('.panel').forEach(p=> p.classList.toggle('is-active', p.dataset.panel===activeTab));
 }
 $$('#tabs .tab').forEach(tab=> tab.addEventListener('click',()=> navigateTab(tab.dataset.tab)));
+// mobile hamburger — toggles the tab dropdown (body.nav-open); closes on tab pick / outside / Esc
+const navToggle=$('#navToggle');
+if(navToggle) navToggle.addEventListener('click',e=>{ e.stopPropagation(); const open=!document.body.classList.contains('nav-open'); document.body.classList.toggle('nav-open',open); navToggle.setAttribute('aria-expanded',String(open)); });
+document.addEventListener('click',e=>{ if(!document.body.classList.contains('nav-open')) return; if(e.target.closest('#tabs')||e.target.closest('#navToggle')) return; closeNav(); });
+document.addEventListener('keydown',e=>{ if(e.key==='Escape') closeNav(); });
+// workflow step popover — close on outside click / scroll / resize / Esc
+document.addEventListener('click',e=>{ if(wfPopStep && !e.target.closest('#wfPop') && !e.target.closest('.wf-step2')) closeWfPop(); });
+document.addEventListener('keydown',e=>{ if(e.key==='Escape') closeWfPop(); });
+window.addEventListener('scroll',()=>{ if(wfPopStep) closeWfPop(); },true);
+window.addEventListener('resize',()=>{ if(wfPopStep) closeWfPop(); });
 // keep the URL and the path in sync when the user uses the browser back/forward buttons
 window.addEventListener('popstate',()=>{
   activeTab = tabFromPath() || 'board'; applyActiveTab();
@@ -828,11 +933,12 @@ $$('#backlogTable thead th').forEach(th=> th.addEventListener('click', ()=>{
 $('#attnAddBtn').addEventListener('click',()=>{ const t=$('#attnInput'); const v=t.value.trim(); if(v){ addAttn(v); t.value=''; } });
 $('#attnInput').addEventListener('keydown',e=>{ if((e.metaKey||e.ctrlKey)&&e.key==='Enter'){ const v=e.target.value.trim(); if(v){ addAttn(v); e.target.value=''; } } });
 $$('.attn-filters .fchip').forEach(b=> b.addEventListener('click',()=>{ attnFilter=b.dataset.attn; renderAttention(); }));
-// settings popover
-$('#settingsBtn').addEventListener('click',e=>{ e.stopPropagation(); openSettings($('#settingsPop').hidden); });
+// settings — the footer link opens the Settings tab; selects save on change
+const footerSettingsBtn=$('#footerSettings'); if(footerSettingsBtn) footerSettingsBtn.addEventListener('click',()=>navigateTab('settings'));
+const footerLogo=$('.footer-logo'); if(footerLogo) footerLogo.addEventListener('click',e=>{ e.preventDefault(); navigateTab('board'); });
 $('#setMode').addEventListener('change',saveSettings);
 $('#setLang').addEventListener('change',saveSettings);
-document.addEventListener('click',e=>{ const pop=$('#settingsPop'); if(!pop||pop.hidden) return; if(!pop.contains(e.target) && !e.target.closest('#settingsBtn')) openSettings(false); });
+const setDesignSel=$('#setDesign'); if(setDesignSel) setDesignSel.addEventListener('change',()=>saveDesign(setDesignSel.value));
 // theme
 (function(){ const s=localStorage.getItem('spf-theme'); if(s)document.documentElement.setAttribute('data-theme',s);
   $('#themeToggle').addEventListener('click',()=>{ const c=document.documentElement.getAttribute('data-theme'); const n=c==='dark'?'light':'dark'; document.documentElement.setAttribute('data-theme',n); localStorage.setItem('spf-theme',n); }); })();

package/templates/dashboard/public/designs.js

@@ -0,0 +1,30 @@
+'use strict';
+/*
+ * Dashboard design registry. Each entry is a selectable visual "skin" applied via the
+ * `data-design="<id>"` attribute on <html>. The switcher in Settings is built from this list.
+ *
+ * TO ADD A DESIGN (3 easy steps, no other code changes needed):
+ *   1. Append an entry here: { id, name, desc }.  The id must be a slug (kebab-case).
+ *   2. In styles.css, add a scoped block that overrides the design tokens (and, if the design
+ *      needs it, component rules) under that id:
+ *          :root[data-design="<id>"]              { --bg:…; --surface:…; --signal:…; … }
+ *          :root[data-design="<id>"][data-theme="light"] { … light-mode overrides … }
+ *          :root[data-design="<id>"] .kpi { … optional component tweaks … }
+ *      Everything is token-driven, so most designs are just a palette override.
+ *   3. That's it — the design shows up in Settings → Dashboard design and can be switched live.
+ *
+ * The active design is persisted per viewer (localStorage 'spf-design') and, when changed, also
+ * written to config.json (config.design) as the project default. Fonts stay system-only (the
+ * dashboard is zero-dependency and offline-capable), so designs express themselves through colour,
+ * surfaces, radius, shadow and spacing rather than web fonts.
+ */
+(function (root) {
+  const DESIGNS = [
+    { id: 'control-room', name: 'Control Room', desc: 'Dark violet engineering control room — the original.' },
+    { id: 'obsidian',     name: 'Obsidian Ops',  desc: 'Near-black mission-control — electric lime + cyan, mono type, Linear/Vercel precision.' },
+    { id: 'neon-command', name: 'Neon Command',  desc: 'Glassmorphism — aurora violet + cyan, Space Grotesk display, control-room ambiance.' },
+    // one more from the design set coming: nord…
+  ];
+  if (typeof module !== 'undefined' && module.exports) module.exports = DESIGNS;
+  else root.DESIGNS = DESIGNS;
+})(typeof window !== 'undefined' ? window : globalThis);

package/templates/dashboard/public/icons.js

@@ -23,8 +23,39 @@
     run: wrap('<path d="M5.4 3.6v10.8l9-5.4z" fill="currentColor" stroke="none"/>'),
     // flag — points needing attention
     attention: wrap('<line x1="4.5" y1="2.4" x2="4.5" y2="15.6"/><path d="M4.5 3.4h8.2l-1.7 2.6 1.7 2.6H4.5z"/>'),
-    // gear — settings
-    settings: wrap('<circle cx="9" cy="9" r="2.3"/><path d="M9 1.8v2M9 14.2v2M16.2 9h-2M3.8 9h-2M14.1 3.9l-1.4 1.4M5.3 12.7l-1.4 1.4M14.1 14.1l-1.4-1.4M5.3 5.3 3.9 3.9"/>'),
+    // gear — settings (proper cog with teeth)
+    settings: wrap('<circle cx="9" cy="9" r="2.4"/><path d="M9 1.6v2.2M9 14.2v2.2M16.4 9h-2.2M3.8 9H1.6M14.2 3.8l-1.55 1.55M5.35 12.65 3.8 14.2M14.2 14.2l-1.55-1.55M5.35 5.35 3.8 3.8"/>'),
+    // crescent moon — theme toggle
+    theme: wrap('<path d="M14.6 10.8A5.6 5.6 0 0 1 7.2 3.4 5.7 5.7 0 1 0 14.6 10.8z"/>'),
+  };
+
+  // Representative icons for workflow pipeline steps, resolved from the step name.
+  const WF = {
+    brainstorm: wrap('<path d="M6.4 12.2a4.3 4.3 0 1 1 5.2 0c-.5.4-.8.9-.9 1.5H7.3c-.1-.6-.4-1.1-.9-1.5z"/><line x1="7.2" y1="15.4" x2="10.8" y2="15.4"/>'),
+    analysis:   wrap('<circle cx="7.8" cy="7.8" r="4"/><line x1="10.8" y1="10.8" x2="15" y2="15"/>'),
+    spec:       wrap('<path d="M5 2.5h5l3 3v10H5z"/><path d="M10 2.5v3h3"/><line x1="6.8" y1="9" x2="11" y2="9"/><line x1="6.8" y1="11.5" x2="11" y2="11.5"/>'),
+    plan:       wrap('<rect x="4" y="3.4" width="10" height="12" rx="1.4"/><path d="M6.8 3.4V3a1.1 1.1 0 0 1 1.1-1.1h2.2A1.1 1.1 0 0 1 11.2 3v.4"/><path d="M6.4 8.2 7.3 9 9 7"/><line x1="10.4" y1="8" x2="11.7" y2="8"/><line x1="6.4" y1="11.6" x2="11.7" y2="11.6"/>'),
+    develop:    wrap('<path d="M6.4 5.6 3 9l3.4 3.4"/><path d="M11.6 5.6 15 9l-3.4 3.4"/>'),
+    unit:       wrap('<circle cx="9" cy="9" r="6.2"/><path d="M6.2 9.2 8 11l3.9-4.1"/>'),
+    integration:wrap('<path d="M7.2 12.1 5.9 13.4a2.4 2.4 0 0 1-3.3-3.3L4 8.7"/><path d="M10.8 5.9 12.1 4.6a2.4 2.4 0 0 1 3.3 3.3L14 9.3"/><line x1="7.4" y1="10.6" x2="10.6" y2="7.4"/>'),
+    e2e:        wrap('<rect x="2.8" y="3.6" width="12.4" height="8.2" rx="1.2"/><line x1="7" y1="15" x2="11" y2="15"/><line x1="9" y1="11.8" x2="9" y2="15"/><line x1="2.8" y1="6.4" x2="15.2" y2="6.4"/>'),
+    review:     wrap('<path d="M2.4 9S5 4.6 9 4.6 15.6 9 15.6 9 13 13.4 9 13.4 2.4 9 2.4 9z"/><circle cx="9" cy="9" r="2.1"/>'),
+    deploy:     wrap('<path d="M15.6 2.4 8.2 9.2"/><path d="M15.6 2.4 11.1 15.6 8.2 9.2 2.4 6.6z"/>'),
+    fallback:   wrap('<circle cx="9" cy="9" r="3.4"/>'),
+  };
+  ICON.wf = function (name) {
+    const n = String(name || '').toLowerCase();
+    if (/brainstorm|idea/.test(n)) return WF.brainstorm;
+    if (/analy/.test(n)) return WF.analysis;
+    if (/spec/.test(n)) return WF.spec;
+    if (/plan/.test(n)) return WF.plan;
+    if (/develop|implement|\bcode\b|build/.test(n)) return WF.develop;
+    if (/integration/.test(n)) return WF.integration;
+    if (/end.?to.?end|e2e/.test(n)) return WF.e2e;
+    if (/unit/.test(n) || /\btest/.test(n)) return WF.unit;
+    if (/review/.test(n)) return WF.review;
+    if (/deploy|ship|release|publish/.test(n)) return WF.deploy;
+    return WF.fallback;
   };
 
   if (typeof module !== 'undefined' && module.exports) module.exports = ICON;