spectoflow 0.12.1 → 0.13.1

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,26 @@ 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.
 
 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 +150,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

@@ -2,6 +2,7 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
+const http = require('http');
 const { spawn } = require('child_process');
 const store = require('../templates/lib/store');
 const adapters = require('../lib/adapters');
@@ -15,6 +16,30 @@ 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) {
+  const arg = (args.find((a) => a.startsWith('--port=')) || '').split('=')[1];
+  return Number(arg || process.env.SPECTOFLOW_PORT || 4319);
+}
+
+// Native http probe, ~500ms timeout, never throws — resolves true/false.
+function probeDashboard(port, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: 'localhost', port, path: '/api/project', timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(res.statusCode < 500);
+    });
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.on('error', () => resolve(false));
+  });
+}
+
 function copyDir(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
   for (const e of fs.readdirSync(src, { withFileTypes: true })) {
@@ -26,8 +51,9 @@ function copyDir(src, dst) {
 
 // Existing project: give id-less checkbox tasks a stable id, in place.
 const ID_RE = /^[A-Za-z]{1,5}-?\d+[A-Za-z]?$/;
-function normalizePlans(root) {
-  const dir = path.join(root, 'plans');
+function normalizePlans(root, config) {
+  const dirName = store.resolvePlansDir(root, config || store.readConfig(root));
+  const dir = path.join(root, dirName);
   if (!fs.existsSync(dir)) return 0;
   let added = 0, seq = 1;
   for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
@@ -90,12 +116,18 @@ function init() {
   cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
   fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
 
-  // artifact folders
-  fs.mkdirSync(path.join(target, 'specs'), { recursive: true });
-  fs.mkdirSync(path.join(target, 'plans'), { recursive: true });
+  // artifact folders — reuse an existing differently-named folder (e.g. a project that already
+  // keeps its plans in `plan/`, singular) instead of always forcing the plans/specs convention;
+  // mkdir is a no-op when the resolved folder already exists.
+  const plansDirName = store.resolvePlansDir(target, cfg);
+  const specsDirName = store.resolveSpecsDir(target, cfg);
+  fs.mkdirSync(path.join(target, specsDirName), { recursive: true });
+  fs.mkdirSync(path.join(target, plansDirName), { recursive: true });
+  if (plansDirName !== 'plans') notes.push(`Using existing '${plansDirName}/' as the plans folder (set plansDir in config.json to override).`);
+  if (specsDirName !== 'specs') notes.push(`Using existing '${specsDirName}/' as the specs folder (set specsDir in config.json to override).`);
 
   // existing project: id-normalize any plans already there
-  const added = normalizePlans(target);
+  const added = normalizePlans(target, cfg);
   if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
 
   // per-agent shims
@@ -113,10 +145,11 @@ function init() {
   console.log('  specs/ plans/  markdown artifacts (your source of truth)');
   written.forEach((w) => console.log('  + ' + w));
   notes.forEach((n) => console.log('  ! ' + n));
+  const port = resolvePort(argv);
   console.log('\nNext:');
-  console.log('  1) Open your agent here (Claude Code loads CLAUDE.md; Codex loads AGENTS.md).');
-  console.log('  2) Run /spectoflow init — or just say what you want to build.');
-  console.log('  3) Watch: node .spectoflow/dashboard/server.js → http://localhost:4319');
+  console.log('  1) Open your agent here — or just say what you want to build.');
+  console.log('  2) spectoflow dashboard');
+  console.log(`     → http://localhost:${port}`);
 }
 
 function update() {
@@ -128,29 +161,50 @@ 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('');
 }
 
-function dashboard() {
+// THE launch command — prints the URL clearly and won't crash on EADDRINUSE: it probes first
+// and, if a dashboard is already up on that port, just reports it instead of spawning a second one.
+async function dashboard() {
+  const port = resolvePort(argv);
+  const url = `http://localhost:${port}`;
+  if (await probeDashboard(port)) {
+    console.log(`spectoflow dashboard already running → ${url}`);
+    return;
+  }
   const local = path.resolve('.spectoflow', 'dashboard', 'server.js');
   const bundled = path.join(TPL, 'dashboard', 'server.js');
-  spawn('node', [fs.existsSync(local) ? local : bundled], { stdio: 'inherit' });
+  const env = Object.assign({}, process.env, { SPECTOFLOW_PORT: String(port) });
+  spawn('node', [fs.existsSync(local) ? local : bundled], { stdio: 'inherit', env });
+  console.log(`spectoflow dashboard → ${url}`);
 }
 
-function status() {
+async function status() {
   const root = process.cwd();
-  if (!fs.existsSync(path.join(root, 'plans')) && !fs.existsSync(path.join(root, '.spectoflow'))) {
+  const cfg = store.readConfig(root);
+  const plansDirName = store.resolvePlansDir(root, cfg);
+  if (!fs.existsSync(path.join(root, plansDirName)) && !fs.existsSync(path.join(root, '.spectoflow'))) {
     return console.log('No spectoflow project here. Run: spectoflow init');
   }
   const p = store.readProject(root);
@@ -159,12 +213,31 @@ 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 port = resolvePort(argv);
+  const running = await probeDashboard(port);
+  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                           run the local control plane
-  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`);
 
-({ init, update, dashboard, status, help })[cmd] ? ({ init, update, dashboard, status, help })[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.12.1",
+  "version": "0.13.1",
   "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

@@ -17,6 +17,12 @@ specs, plans, comments, and **code comments**. English is the default standard.
 
 - **Artifacts (markdown, versioned, source of truth):** `specs/*.md` (specifications), `plans/*.md`
   (plans whose tasks are checkbox lines). These are what humans read and git tracks.
+- **Broaden the search before concluding "no plans exist".** The plans/specs folder name is
+  configurable: check `.spectoflow/config.json` → `plansDir`/`specsDir` first (if set, that folder
+  is authoritative); otherwise look for `plans/` then the singular `plan/` (same for `specs/`/`spec/`).
+  If you find tasks sitting in a differently-named folder (e.g. `plan/`), use them — and tell the
+  user they can pin it permanently by setting `plansDir` (or `specsDir`) in `.spectoflow/config.json`,
+  or by just telling you the folder name. Only treat the project as empty once you've checked both.
 - **Task line convention** in `plans/*.md`:
   `- [ ] T-012 Add login form @owner ~level %status`
   `[x]` = done · `~level` = quick|standard|major · `%status` = in_progress|to_validate|to_analyze|blocked
@@ -43,9 +49,14 @@ whole file. This lets the dashboard and you co-edit without clobbering. Reflect
 
 ## New / empty project → Intake
 
-If `plans/` and `specs/` are empty: greet the user, state the mode, and **ask what they want to build**.
-Then run **brainstorm → analysis → spec → plan** (write `specs/*.md`, then `plans/*.md` with tasks)
-before any implementation.
+If `plans/` and `specs/` are empty (after broadening the search above): greet the user, state the
+mode, and **ask what they want to build**. Then run **brainstorm → analysis → spec → plan** (write
+`specs/*.md`, then `plans/*.md` with tasks) before any implementation.
+
+**Right after `init`, or on your very first reply in a fresh project, give a short next-steps hint —
+don't leave the user unsure what to do.** Keep it to a few lines:
+1. Say what you want to build (plain language — no ceremonial command needed).
+2. The dashboard: tell them it's at its URL (see Dashboard below), and whether it's already running.
 
 ## Workflow, capabilities, agents, skills
 
@@ -63,4 +74,12 @@ destructive migration, security). Mode sets routine friction; policy is non-nego
 
 ## Dashboard
 
-`node .spectoflow/dashboard/server.js` → http://localhost:4319 (zero deps, live via SSE).
+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.
+
+**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.

package/templates/config.json

@@ -3,6 +3,9 @@
   "language": "en",
   "agent": "claude",
   "projectType": "app",
+  "plansDir": null,
+  "specsDir": null,
+  "dashboard": { "autostart": true },
   "runners": {
     "claude": "claude -p --permission-mode acceptEdits",
     "codex": "codex exec"

package/templates/dashboard/orchestrator.js

@@ -87,7 +87,9 @@ function defaultRunStep({ root, step, agent, skill, request }, emit) {
   return new Promise((resolve) => {
     const prompt = buildPrompt({ step, agent, skill, request });
     const tool = store.readConfig(root).agent;
-    const r = startRun(root, { prompt, agent: tool }, (e) => { emit(e); if (e.type === 'run-end') resolve(e.code); });
+    // logPrompt:false — the orchestrator already posts a clean "→ step (agent)" line; the raw
+    // priming prompt would otherwise show as a noisy user bubble.
+    const r = startRun(root, { prompt, agent: tool, logPrompt: false }, (e) => { emit(e); if (e.type === 'run-end') resolve(e.code); });
     if (r.error) { emit({ type: 'message', message: { role: 'orchestrator', kind: 'status', text: r.error } }); resolve(1); }
   });
 }

package/templates/dashboard/public/app.js

@@ -2,8 +2,10 @@
 const STATUS = { todo:'To do', in_progress:'In progress', to_validate:'To validate', to_analyze:'To analyze', done:'Done', blocked:'Blocked' };
 let P = null, openTaskId = null;
 let filter = { status: 'all', q: '' }; // board filter state — client-side only, read-only
-let backlogFilter = { status: 'all', q: '' }; // backlog filter state — independent from the board's
+let backlogFilter = { status: 'open', q: '' }; // backlog defaults to open (not-done) tasks
 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
 
 const $ = (s,r=document)=>r.querySelector(s);
 const $$ = (s,r=document)=>[...r.querySelectorAll(s)];
@@ -15,12 +17,16 @@ async function load(){
   const r = await fetch('/api/project'); P = await r.json(); render();
   if(openTaskId) openDrawer(openTaskId,true);
 }
+// Coalesce bursts of SSE 'change'/'message' events into one reload so the board doesn't
+// re-render (and flash) several times for a single agent action.
+let loadTimer=null;
+function scheduleLoad(){ clearTimeout(loadTimer); loadTimer=setTimeout(load,180); }
 function connect(){
   const es = new EventSource('/api/events');
   es.onopen = ()=>{ $('#sync').classList.remove('offline'); $('#syncLabel').textContent='live'; };
   es.onmessage = (ev)=>{
     let m; try{ m=JSON.parse(ev.data); }catch{ return; }
-    if(m.type==='change'||m.type==='message') return load();   // messages live from runtime.messages
+    if(m.type==='change'||m.type==='message') return scheduleLoad(); // messages live from runtime.messages
     if(m.type==='run-start'||m.type==='run-end') { chatState.forEach(st=>{ st.rawBlock=null; }); return; }
     if(m.type==='run-line') return appendRaw(m.chunk);          // raw output is ephemeral (not logged)
   };
@@ -127,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(); renderInfo();
+  renderSidebar(); renderRequests(); renderAttention(); renderInfo();
   applyActiveTab(); // re-apply the current tab so an SSE-driven re-render never resets to Board
 }
 
@@ -332,7 +338,8 @@ function backlogRows(){
   return rows;
 }
 function backlogMatches(r){
-  if(backlogFilter.status!=='all' && r.status!==backlogFilter.status) return false;
+  if(backlogFilter.status==='open'){ if(r.status==='done') return false; }       // "open" = every not-done task
+  else if(backlogFilter.status!=='all' && r.status!==backlogFilter.status) return false;
   const q=backlogFilter.q.trim().toLowerCase();
   if(q && !((r.id+' '+r.title).toLowerCase().includes(q))) return false;
   return true;
@@ -365,10 +372,25 @@ function renderBacklog(){
   const all=backlogRows();
   const cnt=$('#backlogCount'); if(cnt) cnt.textContent=all.length;
   const filtered=sortBacklogRows(all.filter(backlogMatches));
+  const pages=Math.max(1,Math.ceil(filtered.length/BACKLOG_PAGE));
+  if(backlogPage>pages) backlogPage=pages;
+  if(backlogPage<1) backlogPage=1;
   body.innerHTML='';
-  if(!all.length){ body.append(backlogEmptyRow('No plans yet. Ask your agent to build something — it will run Intake and write plans/*.md.')); return; }
-  if(!filtered.length){ body.append(backlogEmptyRow('No tasks match this filter.')); return; }
-  filtered.forEach(r=> body.append(backlogRow(r)));
+  if(!all.length){ body.append(backlogEmptyRow('No plans yet. Ask your agent to build something — it will run Intake and write plans/*.md.')); return renderBacklogPager(0,1); }
+  if(!filtered.length){ body.append(backlogEmptyRow('No tasks match this filter.')); return renderBacklogPager(0,1); }
+  const start=(backlogPage-1)*BACKLOG_PAGE;
+  filtered.slice(start,start+BACKLOG_PAGE).forEach(r=> body.append(backlogRow(r)));
+  renderBacklogPager(filtered.length,pages);
+}
+function renderBacklogPager(total,pages){
+  const pager=$('#backlogPager'); if(!pager) return; pager.innerHTML='';
+  if(total<=BACKLOG_PAGE){ if(total) pager.append(el('span','pager-info',`${total} task${total>1?'s':''}`)); return; }
+  const prev=el('button','pager-btn','‹ Prev'); prev.disabled=backlogPage<=1;
+  prev.addEventListener('click',()=>{ backlogPage--; renderBacklog(); });
+  const next=el('button','pager-btn','Next ›'); next.disabled=backlogPage>=pages;
+  next.addEventListener('click',()=>{ backlogPage++; renderBacklog(); });
+  const from=(backlogPage-1)*BACKLOG_PAGE+1, to=Math.min(total,backlogPage*BACKLOG_PAGE);
+  pager.append(prev, el('span','pager-info',`${from}–${to} of ${total} · page ${backlogPage}/${pages}`), next);
 }
 function backlogEmptyRow(txt){
   const tr=el('tr','backlog-empty-row'); const td=el('td',null,txt); td.colSpan=7; tr.append(td); return tr;
@@ -450,18 +472,108 @@ function renderTask(t){
 function renderWorkflow(){
   const box=$('#wfDiagram'); box.innerHTML='';
   const steps=P.workflow||[];
+  if(!steps.length){ box.append(el('div','empty','No workflow defined.')); 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`));
+  box.append(legend);
+  const track=el('div','wf-track');
   steps.forEach((s,i)=>{
-    const step=el('div','wf-step');
-    const node=el('div','wf-node'+(s.enabled?'':' off'));
-    node.append(el('span','dot'));
-    node.append(el('span','nm',s.name));
-    if(s.optional) node.append(el('span','opt','opt'));
-    node.addEventListener('click',()=>toggleStep(s.name));
-    step.append(node);
-    if(i<steps.length-1){ const a=el('div','wf-arrow'+(s.enabled&&steps[i+1].enabled?'':' off')); step.append(a); }
-    box.append(step);
+    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')));
   });
-  if(!steps.length) box.append(el('div','empty','No workflow defined.'));
+  box.append(track);
+}
+
+// ---- Attention tab: agent/user-raised points; validate → real task ----------
+function attnItems(){ return (P.runtime&&P.runtime.attention)||[]; }
+function renderAttention(){
+  const list=$('#attnList'); if(!list) return;
+  const items=attnItems();
+  const openN=items.filter(i=>i.status!=='resolved').length;
+  const badge=$('#attnBadge'); if(badge){ badge.textContent=openN; badge.hidden=openN===0; }
+  const count=$('#attnCount'); if(count) count.textContent=items.length;
+  $$('.attn-filters .fchip').forEach(b=> b.classList.toggle('active', b.dataset.attn===attnFilter));
+  const shown=items.filter(i=> attnFilter==='all' ? true : attnFilter==='resolved' ? i.status==='resolved' : i.status!=='resolved');
+  list.innerHTML='';
+  if(!shown.length){ list.append(el('div','empty', attnFilter==='resolved'?'Nothing resolved yet.':'No points of attention. The agent surfaces them here as it works — or add your own note above.')); return; }
+  shown.forEach(it=> list.append(attnRow(it)));
+}
+function attnRow(it){
+  const row=el('div','attn-row'+(it.status==='resolved'?' is-resolved':'')+(it.source==='agent'?' from-agent':''));
+  const head=el('div','attn-head');
+  head.append(el('span','attn-src '+(it.source==='agent'?'is-agent':'is-user'), it.source==='agent'?('⚑ '+(it.by||'agent')):'✎ you'));
+  if(it.at) head.append(el('span','attn-time',(String(it.at).replace('T',' ')).slice(0,16)));
+  if(it.status==='resolved') head.append(el('span','chip s-done', it.promotedTo?('→ '+it.promotedTo):'resolved'));
+  row.append(head);
+  const txt=el('div','attn-text', it.text); row.append(txt);
+  const acts=el('div','attn-actions');
+  if(it.status!=='resolved'){
+    const val=el('button','btn primary','Validate → task'); val.addEventListener('click',()=>promoteAttn(it.id));
+    const res=el('button','btn','Resolve'); res.addEventListener('click',()=>patchAttn(it.id,{status:'resolved'}));
+    const edit=el('button','btn','Edit'); edit.addEventListener('click',()=>editAttn(it,txt));
+    acts.append(val,res,edit);
+  }else{
+    const re=el('button','btn','Reopen'); re.addEventListener('click',()=>patchAttn(it.id,{status:'open'})); acts.append(re);
+  }
+  const del=el('button','btn danger','Delete'); del.addEventListener('click',()=>deleteAttn(it.id));
+  acts.append(del); row.append(acts);
+  return row;
+}
+function editAttn(it,txtNode){
+  const ta=el('textarea','attn-edit'); ta.value=it.text; txtNode.replaceWith(ta); ta.focus();
+  let done=false;
+  const save=()=>{ if(done) return; done=true; const v=ta.value.trim(); if(v&&v!==it.text) patchAttn(it.id,{text:v}); else renderAttention(); };
+  ta.addEventListener('blur',save);
+  ta.addEventListener('keydown',e=>{ if((e.metaKey||e.ctrlKey)&&e.key==='Enter'){ e.preventDefault(); save(); } if(e.key==='Escape'){ done=true; renderAttention(); } });
+}
+async function addAttn(text){ flash(); await fetch('/api/attention',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({text})}); }
+async function patchAttn(id,patch){ flash(); await fetch('/api/attention/'+encodeURIComponent(id),{method:'PATCH',headers:{'Content-Type':'application/json'},body:JSON.stringify(patch)}); }
+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;
+}
+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})}); }
+
+// ---- client-side routing: /<tab>[/<taskId>] via the History API ------------
+const ROUTES=['board','requests','attention','backlog','workflow','team','chat','info'];
+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();
 }
 
 // chip row: a small uppercase kicker label followed by one chip per item — used for
@@ -643,6 +755,7 @@ function renderInfo(){
 function openDrawer(id,keep){
   const t=allTasks().find(x=>x.id===id); if(!t) return;
   openTaskId=id;
+  if(!keep && taskFromPath()!==id) history.pushState(null,'','/'+activeTab+'/'+encodeURIComponent(id));
   const b=$('#drawerBody'); const prev=keep?$('.drawer-panel').scrollTop:0; b.innerHTML='';
   b.append(el('div','d-id',t.id+' · '+(t.level||'standard')+' · '+t.file));
   b.append(el('div','d-title',t.title));
@@ -676,36 +789,50 @@ function openDrawer(id,keep){
   $('#drawer').setAttribute('aria-hidden','false');
   if(keep) $('.drawer-panel').scrollTop=prev;
 }
-function closeDrawer(){ openTaskId=null; $('#drawer').setAttribute('aria-hidden','true'); }
+function closeDrawer(){ if(taskFromPath()) history.pushState(null,'','/'+activeTab); openTaskId=null; $('#drawer').setAttribute('aria-hidden','true'); }
 const cssv=(v)=> getComputedStyle(document.documentElement).getPropertyValue(v).trim()||'#888';
 
 // tabs — activeTab is the single source of truth (persisted), so a click sets it and applies it,
 // and render()'s SSE-driven re-render (triggered by the snapshot write / polling) re-applies it
 // too instead of ever resetting to Board; this is what keeps a tab selected across a race with a
 // 'change'/'message' event that lands right after a click.
-let activeTab = (()=>{ try{ return localStorage.getItem('spf-tab')||'board'; }catch{ return 'board'; } })();
+// initial tab: the URL path wins (deep-link / refresh), else the persisted tab, else board
+let activeTab = tabFromPath() || (()=>{ try{ return localStorage.getItem('spf-tab')||'board'; }catch{ return 'board'; } })();
+openTaskId = taskFromPath(); // deep-link straight to a task drawer
 function applyActiveTab(){
   $$('#tabs .tab').forEach(t=> t.classList.toggle('is-active', t.dataset.tab===activeTab));
   $$('.panel').forEach(p=> p.classList.toggle('is-active', p.dataset.panel===activeTab));
 }
-$$('#tabs .tab').forEach(tab=> tab.addEventListener('click',()=>{
-  activeTab=tab.dataset.tab;
-  try{ localStorage.setItem('spf-tab',activeTab); }catch{}
-  applyActiveTab();
-}));
-applyActiveTab(); // sync to any persisted tab before the first render
+$$('#tabs .tab').forEach(tab=> tab.addEventListener('click',()=> navigateTab(tab.dataset.tab)));
+// keep the URL and the path in sync when the user uses the browser back/forward buttons
+window.addEventListener('popstate',()=>{
+  activeTab = tabFromPath() || 'board'; applyActiveTab();
+  const id=taskFromPath(); if(id) openDrawer(id); else closeDrawer();
+});
+// brand logo → Board (SPA nav, no full reload)
+const brandLogo=$('.brand-logo'); if(brandLogo) brandLogo.addEventListener('click',e=>{ e.preventDefault(); navigateTab('board'); });
+applyActiveTab(); // sync to the resolved tab before the first render
 // filters (status chips + search) — client-side only, does not write anything
 $$('#statusChips .fchip').forEach(b=> b.addEventListener('click', ()=>{ filter.status=b.dataset.status; renderBoard(); }));
 $('#search').addEventListener('input', e=>{ filter.q=e.target.value; renderBoard(); });
-// backlog: independent filters + sortable column headers — client-side only
-$$('#backlogStatusChips .fchip').forEach(b=> b.addEventListener('click', ()=>{ backlogFilter.status=b.dataset.status; renderBacklog(); }));
-$('#backlogSearch').addEventListener('input', e=>{ backlogFilter.q=e.target.value; renderBacklog(); });
+// backlog: independent filters + sortable column headers — client-side only (reset to page 1 on change)
+$$('#backlogStatusChips .fchip').forEach(b=> b.addEventListener('click', ()=>{ backlogFilter.status=b.dataset.status; backlogPage=1; renderBacklog(); }));
+$('#backlogSearch').addEventListener('input', e=>{ backlogFilter.q=e.target.value; backlogPage=1; renderBacklog(); });
 $$('#backlogTable thead th').forEach(th=> th.addEventListener('click', ()=>{
   const col=th.dataset.col;
   if(backlogSort.col===col) backlogSort.dir = backlogSort.dir==='asc'?'desc':'asc';
   else { backlogSort.col=col; backlogSort.dir='asc'; }
-  renderBacklog();
+  backlogPage=1; renderBacklog();
 }));
+// attention tab: add a note + filter chips
+$('#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); });
+$('#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); });
 // 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); }); })();
@@ -744,4 +871,8 @@ $('#tabRunPrompt').addEventListener('keydown',e=>{ if((e.metaKey||e.ctrlKey)&&e.
 $('#drawerClose').addEventListener('click',closeDrawer);
 $('#drawerScrim').addEventListener('click',closeDrawer);
 document.addEventListener('keydown',e=>{ if(e.key==='Escape')closeDrawer(); });
+// entry animations play only during the initial boot window; after that, live SSE re-renders
+// don't replay them (kills the flicker). CSS scopes @keyframes to body.booting.
+document.body.classList.add('booting');
+setTimeout(()=>document.body.classList.remove('booting'),1400);
 load(); connect();

package/templates/dashboard/public/icons.js

@@ -21,6 +21,10 @@
     info: wrap('<circle cx="9" cy="9" r="6.4"/><line x1="9" y1="8.3" x2="9" y2="12.2"/><circle cx="9" cy="5.7" r="0.9" fill="currentColor" stroke="none"/>'),
     // play triangle — run
     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"/>'),
   };
 
   if (typeof module !== 'undefined' && module.exports) module.exports = ICON;

package/templates/dashboard/public/index.html

@@ -4,12 +4,16 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>spectoflow · control</title>
+  <link rel="icon" type="image/png" href="logo-white.png" />
   <link rel="stylesheet" href="styles.css" />
 </head>
 <body>
   <header class="topbar">
     <div class="brand">
-      <span class="brand-mark" aria-hidden="true"></span>
+      <a class="brand-logo" href="/board" data-route="board" aria-label="spectoflow home">
+        <img class="brand-logo-img is-dark" src="logo-white.png" alt="spectoflow" />
+        <img class="brand-logo-img is-light" src="logo-dark.png" alt="spectoflow" />
+      </a>
       <div class="brand-text">
         <div class="brand-line">
           <span class="brand-name">spectoflow</span>
@@ -25,6 +29,7 @@
     <nav class="tabs" id="tabs">
       <button class="tab is-active" data-tab="board"><span class="tab-ico" data-icon="board"></span><span class="tab-label">Board</span></button>
       <button class="tab" data-tab="requests"><span class="tab-ico" data-icon="requests"></span><span class="tab-label">Requests</span></button>
+      <button class="tab" data-tab="attention"><span class="tab-ico" data-icon="attention"></span><span class="tab-label">Attention</span><span class="tab-badge" id="attnBadge" hidden>0</span></button>
       <button class="tab" data-tab="backlog"><span class="tab-ico" data-icon="backlog"></span><span class="tab-label">Backlog</span></button>
       <button class="tab" data-tab="workflow"><span class="tab-ico" data-icon="workflow"></span><span class="tab-label">Workflow</span></button>
       <button class="tab" data-tab="team"><span class="tab-ico" data-icon="agents"></span><span class="tab-label">Agents &amp; Skills</span></button>
@@ -37,8 +42,32 @@
       <span class="mode-chip" id="modeChip" title="Autonomy mode">semi</span>
       <span class="sync" id="sync"><span class="sync-dot"></span><span id="syncLabel">live</span></span>
       <button class="btn primary run-btn" id="runQuickBtn" title="Open the run chat"><span class="tab-ico" data-icon="run"></span><span>Run</span></button>
+      <button class="icon-btn" id="settingsBtn" aria-label="Settings" title="Settings"><span class="tab-ico" data-icon="settings"></span></button>
       <button class="theme-toggle" id="themeToggle" aria-label="Toggle theme"><span class="theme-ico"></span></button>
     </div>
+
+    <!-- settings popover (mode + language) -->
+    <div class="settings-pop" id="settingsPop" hidden role="dialog" aria-label="Settings">
+      <div class="settings-head">Settings</div>
+      <label class="settings-row"><span>Autonomy mode</span>
+        <select id="setMode">
+          <option value="autopilot">autopilot</option>
+          <option value="semi">semi</option>
+          <option value="manual">manual</option>
+        </select>
+      </label>
+      <label class="settings-row"><span>Output language</span>
+        <select id="setLang">
+          <option value="en">en · English</option>
+          <option value="fr">fr · Français</option>
+          <option value="es">es · Español</option>
+          <option value="de">de · Deutsch</option>
+          <option value="pt">pt · Português</option>
+          <option value="it">it · Italiano</option>
+        </select>
+      </label>
+      <p class="settings-note">Writes <code>.spectoflow/config.json</code> — the agent picks it up on its next run.</p>
+    </div>
   </header>
 
   <main class="stage">
@@ -85,6 +114,24 @@
       </div>
     </section>
 
+    <!-- ATTENTION (points raised by the agent or by you; validate → task) -->
+    <section class="panel" data-panel="attention">
+      <div class="attn-wrap">
+        <h2 class="panel-title">Points of attention <span class="count" id="attnCount">0</span></h2>
+        <p class="panel-sub">Things the agent flagged during work — or you noted — that deserve a look. <em>Validate</em> one to turn it into a task.</p>
+        <div class="attn-add">
+          <textarea id="attnInput" class="chat-ta" placeholder="Note something to keep an eye on…"></textarea>
+          <button id="attnAddBtn" class="btn primary">Add note</button>
+        </div>
+        <div class="attn-filters">
+          <button class="fchip active" data-attn="open">Open</button>
+          <button class="fchip" data-attn="all">All</button>
+          <button class="fchip" data-attn="resolved">Resolved</button>
+        </div>
+        <div class="attn-list" id="attnList"></div>
+      </div>
+    </section>
+
     <!-- BACKLOG (flat, sortable, filterable table of every task) -->
     <section class="panel" data-panel="backlog">
       <div class="backlog-wrap">
@@ -92,7 +139,8 @@
         <p class="panel-sub">Every task, across every plan, in one flat table.</p>
         <div class="filters" id="backlogFilters">
           <div class="chip-list" id="backlogStatusChips">
-            <button class="fchip active" data-status="all">All</button>
+            <button class="fchip active" data-status="open">Open</button>
+            <button class="fchip" data-status="all">All</button>
             <button class="fchip" data-status="todo">To do</button>
             <button class="fchip" data-status="in_progress">In progress</button>
             <button class="fchip" data-status="to_validate">To validate</button>
@@ -118,6 +166,7 @@
             <tbody id="backlogBody"></tbody>
           </table>
         </div>
+        <div class="pager" id="backlogPager"></div>
       </div>
     </section>
 

package/templates/dashboard/public/styles.css

@@ -390,29 +390,32 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 @media (max-width:640px){ .chat-tab-input { flex-direction:column; } .chat-tab-actions { flex-direction:row; } }
 
 /* ---- chart & panel motion --------------------------------------------- */
+/* Entry animations are scoped to body.booting so they play once on initial load; live SSE
+   re-renders (which rebuild these nodes) then don't replay them — this is what stops the
+   dashboard from flickering on every agent action. */
 /* cards/panels rise in on render */
 @keyframes rise { from{ opacity:0; transform:translateY(8px);} to{ opacity:1; transform:translateY(0);} }
-.kpi,.ocard,.card { animation:rise .4s cubic-bezier(.2,.8,.2,1) both; }
-.kpi-row .kpi:nth-child(1){ animation-delay:.02s; } .kpi-row .kpi:nth-child(2){ animation-delay:.06s; }
-.kpi-row .kpi:nth-child(3){ animation-delay:.1s; } .kpi-row .kpi:nth-child(4){ animation-delay:.14s; }
+body.booting .kpi, body.booting .ocard, body.booting .card { animation:rise .4s cubic-bezier(.2,.8,.2,1) both; }
+body.booting .kpi-row .kpi:nth-child(1){ animation-delay:.02s; } body.booting .kpi-row .kpi:nth-child(2){ animation-delay:.06s; }
+body.booting .kpi-row .kpi:nth-child(3){ animation-delay:.1s; } body.booting .kpi-row .kpi:nth-child(4){ animation-delay:.14s; }
 
 /* area curve draws itself — pathLength="1" makes stroke-dash* fraction-based */
 @keyframes draw { to{ stroke-dashoffset:0; } }
-.area-line { stroke-dasharray:1; stroke-dashoffset:1; animation:draw 1.1s cubic-bezier(.2,.8,.2,1) forwards; animation-delay:calc(var(--i,0)*.12s); }
-.area-fill { opacity:0; animation:fadein .6s ease forwards; animation-delay:calc(.4s + var(--i,0)*.12s); }
-.area-dot,.area-value { opacity:0; animation:fadein .3s ease forwards; animation-delay:calc(1s + var(--i,0)*.12s); }
+body.booting .area-line { stroke-dasharray:1; stroke-dashoffset:1; animation:draw 1.1s cubic-bezier(.2,.8,.2,1) forwards; animation-delay:calc(var(--i,0)*.12s); }
+body.booting .area-fill { opacity:0; animation:fadein .6s ease forwards; animation-delay:calc(.4s + var(--i,0)*.12s); }
+body.booting .area-dot, body.booting .area-value { opacity:0; animation:fadein .3s ease forwards; animation-delay:calc(1s + var(--i,0)*.12s); }
 @keyframes fadein { to{ opacity:1; } }
 
 /* donut arcs pop in, staggered by --i */
 @keyframes pop { from{ opacity:0; transform:scale(.85); } to{ opacity:1; transform:scale(1); } }
-.seg-anim { transform-origin:center; transform-box:fill-box; opacity:0; animation:pop .45s cubic-bezier(.2,.8,.2,1) forwards; animation-delay:calc(var(--i,0)*.08s); }
+body.booting .seg-anim { transform-origin:center; transform-box:fill-box; opacity:0; animation:pop .45s cubic-bezier(.2,.8,.2,1) forwards; animation-delay:calc(var(--i,0)*.08s); }
 
 /* phase bars grow + the count-up badge is driven from JS (countUp in app.js) */
-.bar-fill { animation:grow .6s cubic-bezier(.2,.8,.2,1) both; animation-delay:calc(var(--i,0)*.07s); }
+body.booting .bar-fill { animation:grow .6s cubic-bezier(.2,.8,.2,1) both; animation-delay:calc(var(--i,0)*.07s); }
 @keyframes grow { from{ width:0; } }
 
 /* gradient ring (stroke="url(#grad)") fades/scales in */
-.ring-svg circle:last-of-type { transform-origin:center; animation:pop .5s cubic-bezier(.2,.8,.2,1) both; }
+body.booting .ring-svg circle:last-of-type { transform-origin:center; animation:pop .5s cubic-bezier(.2,.8,.2,1) both; }
 
 @media (prefers-reduced-motion: reduce){
   *{ animation:none!important; transition:none!important; }
@@ -424,3 +427,82 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .tooltip { position:fixed; z-index:30; pointer-events:none; background:var(--surface); border:1px solid var(--line); border-radius:8px; padding:6px 10px; font-size:11.5px; line-height:1.4; color:var(--ink); box-shadow:var(--shadow); max-width:220px; }
 .tooltip[hidden] { display:none; }
 .tooltip b { color:var(--ink); }
+
+/* ================= v0.13 additions ================= */
+.topbar { position:relative; }
+
+/* brand logo (replaces the conic mark) — theme-swapped image */
+.brand-logo { display:inline-flex; align-items:center; height:26px; flex-shrink:0; text-decoration:none; }
+.brand-logo-img { height:26px; width:auto; display:block; }
+.brand-logo-img.is-light { display:none; }
+.brand-logo-img.is-dark { display:block; }
+:root[data-theme="light"] .brand-logo-img.is-dark { display:none; }
+:root[data-theme="light"] .brand-logo-img.is-light { display:block; }
+
+/* header icon button (settings gear) */
+.icon-btn { width:30px; height:30px; border:1px solid var(--line); border-radius:8px; background:var(--surface-2); color:var(--muted); cursor:pointer; display:grid; place-items:center; flex-shrink:0; }
+.icon-btn:hover { color:var(--ink); border-color:var(--cool); }
+
+/* settings popover */
+.settings-pop { position:absolute; top:58px; right:16px; z-index:60; width:250px; background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); box-shadow:var(--shadow); padding:14px; display:flex; flex-direction:column; gap:12px; }
+.settings-pop[hidden] { display:none; }
+.settings-head { font-weight:700; font-size:13px; }
+.settings-row { display:flex; flex-direction:column; gap:5px; font-size:10.5px; text-transform:uppercase; letter-spacing:.05em; color:var(--muted); }
+.settings-row select { font-family:inherit; font-size:13px; text-transform:none; letter-spacing:0; padding:6px 8px; border:1px solid var(--line); border-radius:8px; background:var(--surface-2); color:var(--ink); cursor:pointer; }
+.settings-note { font-size:10.5px; color:var(--faint); margin:0; line-height:1.4; }
+
+/* tab badge (open attention count) */
+.tab-badge { display:inline-grid; place-items:center; min-width:16px; height:16px; padding:0 4px; margin-left:5px; border-radius:999px; background:var(--signal); color:#241705; font-size:10px; font-weight:700; }
+.tab-badge[hidden] { display:none; }
+
+/* attention tab */
+.attn-wrap { max-width:860px; margin:0 auto; padding:20px 22px; }
+.attn-add { display:flex; gap:8px; margin:14px 0 10px; align-items:flex-start; }
+.attn-add textarea { flex:1; min-height:44px; resize:vertical; }
+.attn-filters { display:flex; gap:8px; margin-bottom:16px; }
+.attn-list { display:flex; flex-direction:column; gap:10px; }
+.attn-row { border:1px solid var(--line); border-left:3px solid var(--faint); border-radius:var(--radius); background:var(--surface); padding:12px 14px; }
+.attn-row.from-agent { border-left-color:var(--signal); }
+.attn-row.is-resolved { opacity:.62; }
+.attn-head { display:flex; align-items:center; gap:10px; margin-bottom:6px; }
+.attn-src { font-family:var(--mono); font-size:10.5px; text-transform:uppercase; letter-spacing:.05em; }
+.attn-src.is-agent { color:var(--signal); }
+.attn-src.is-user { color:var(--cool); }
+.attn-time { font-family:var(--mono); font-size:10.5px; color:var(--faint); }
+.attn-text { font-size:14px; line-height:1.5; white-space:pre-wrap; }
+.attn-edit { width:100%; min-height:64px; font-family:inherit; font-size:14px; padding:8px; border:1px solid var(--cool); border-radius:8px; background:var(--surface-2); color:var(--ink); box-sizing:border-box; }
+.attn-actions { display:flex; flex-wrap:wrap; gap:8px; margin-top:11px; }
+.btn.danger { color:var(--s-blocked); border-color:color-mix(in srgb,var(--s-blocked) 40%,var(--line)); }
+.btn.danger:hover { border-color:var(--s-blocked); }
+
+/* backlog pager */
+.pager { display:flex; align-items:center; justify-content:center; gap:12px; padding:14px 0 4px; }
+.pager-info { font-family:var(--mono); font-size:11.5px; color:var(--muted); }
+.pager-btn { font-family:var(--mono); font-size:12px; padding:5px 12px; border:1px solid var(--line); border-radius:8px; background:var(--surface); color:var(--ink); cursor:pointer; }
+.pager-btn:hover:not(:disabled) { border-color:var(--cool); }
+.pager-btn:disabled { opacity:.4; cursor:default; }
+
+/* workflow redesign — a wrapping pipeline of step cards with connectors */
+.wf-legend { margin-bottom:14px; }
+.wf-legend-txt { font-family:var(--mono); font-size:11.5px; color:var(--muted); }
+.wf-track { display:flex; flex-wrap:wrap; align-items:stretch; gap:0; }
+.wf-card { position:relative; min-width:152px; flex:0 0 auto; border:1px solid var(--line); border-radius:var(--radius); background:var(--surface); padding:12px 14px; cursor:pointer; transition:border-color .15s, transform .15s, box-shadow .15s; display:flex; flex-direction:column; gap:9px; }
+.wf-card:hover { border-color:var(--cool); transform:translateY(-1px); box-shadow:var(--shadow); }
+.wf-card:focus-visible { outline:2px solid var(--cool); outline-offset:2px; }
+.wf-card.off { opacity:.5; }
+.wf-card-head { display:flex; align-items:center; gap:8px; }
+.wf-num { display:grid; place-items:center; width:20px; height:20px; border-radius:999px; background:var(--surface-2); color:var(--muted); font-family:var(--mono); font-size:11px; flex-shrink:0; }
+.wf-card:not(.off) .wf-num { background:var(--signal); color:#241705; }
+.wf-card-name { font-weight:600; font-size:13.5px; }
+.wf-opt { font-family:var(--mono); font-size:9px; text-transform:uppercase; letter-spacing:.05em; color:var(--faint); border:1px solid var(--line); border-radius:4px; padding:1px 4px; }
+.wf-card-meta { display:flex; flex-wrap:wrap; gap:6px; }
+.wf-cap,.wf-skill { font-family:var(--mono); font-size:10px; border-radius:999px; padding:2px 8px; }
+.wf-cap { color:var(--cool); border:1px solid color-mix(in srgb,var(--cool) 40%,var(--line)); }
+.wf-skill { color:var(--muted); border:1px solid var(--line); }
+.wf-toggle { display:flex; align-items:center; gap:6px; }
+.wf-toggle-dot { width:8px; height:8px; border-radius:50%; background:var(--faint); }
+.wf-card:not(.off) .wf-toggle-dot { background:var(--s-done); }
+.wf-toggle-label { font-family:var(--mono); font-size:10px; text-transform:uppercase; letter-spacing:.05em; color:var(--muted); }
+.wf-conn { flex:0 0 auto; align-self:center; width:26px; height:2px; background:linear-gradient(90deg,var(--cool),var(--signal)); margin:0 2px; border-radius:2px; }
+.wf-conn.off { background:var(--line); }
+@media (max-width:720px){ .wf-track { flex-direction:column; align-items:stretch; } .wf-conn { width:2px; height:18px; margin:2px 0 2px 19px; } }

package/templates/dashboard/runner.js

@@ -27,8 +27,27 @@ function makeFeeder(onLine) {
   };
 }
 
+// Detect an attention sentinel: `::spectoflow attention msg=<text>` (kind=… optional).
+// Agents raise points that deserve the user's eye; they surface in the Attention tab.
+function parseAttentionLine(line) {
+  const m = /^::spectoflow\s+attention\b(.*)$/.exec(String(line).trim());
+  if (!m) return null;
+  const rest = m[1];
+  const msg = (/\bmsg=([\s\S]+)$/.exec(rest) || [])[1];
+  if (!msg || !msg.trim()) return null;
+  return msg.trim();
+}
+function pushAttention(root, text, by) {
+  const rt = store.readRuntime(root); rt.attention = rt.attention || [];
+  const item = { id: 'att' + Date.now().toString(36) + Math.floor(Math.random() * 1e3).toString(36), at: new Date().toISOString(), by: by || 'agent', source: 'agent', status: 'open', text };
+  rt.attention.unshift(item); store.writeRuntime(root, rt);
+  return item;
+}
+
 // Start an agent run. Returns { runId, child } or { error } if no runner is configured.
-function startRun(root, { prompt, agent }, emit) {
+// logPrompt:false suppresses echoing the prompt as a user bubble — used by the orchestrator,
+// whose priming prompt ("You are the …") is machinery the user shouldn't have to read.
+function startRun(root, { prompt, agent, logPrompt = true }, emit) {
   const cfg = store.readConfig(root);
   const which = agent || cfg.agent || 'claude';
   const cmdStr = cfg.runners && cfg.runners[which];
@@ -37,8 +56,10 @@ function startRun(root, { prompt, agent }, emit) {
   const runId = 'r' + Date.now().toString(36);
   const p = String(prompt).trim();
 
-  const um = store.appendMessage(root, { role: 'user', kind: 'message', text: p, agent: which, runId });
-  emit({ type: 'message', message: um });
+  if (logPrompt) {
+    const um = store.appendMessage(root, { role: 'user', kind: 'message', text: p, agent: which, runId });
+    emit({ type: 'message', message: um });
+  }
 
   const run = { id: runId, tool: which, prompt: p, status: 'running', startedAt: new Date().toISOString() };
   runStart(root, run); emit({ type: 'run-start', run }); emit({ type: 'change' });
@@ -56,6 +77,8 @@ function startRun(root, { prompt, agent }, emit) {
   try { child.stdin && child.stdin.end(); } catch {}
 
   const onLine = (line) => {
+    const att = parseAttentionLine(line);
+    if (att) { pushAttention(root, att, which); emit({ type: 'change' }); return; }
     const m = store.parseAgentLine(line);
     if (m) { const full = store.appendMessage(root, { ...m, agent: which, runId }); emit({ type: 'message', message: full }); }
     else emit({ type: 'run-line', runId, chunk: line + '\n' });

package/templates/dashboard/server.js

@@ -15,7 +15,7 @@ const orchestrator = require('./orchestrator');
 const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : 4319;
 const PUBLIC = path.join(__dirname, 'public');
 const ROOT = process.env.SPECTOFLOW_ROOT || path.resolve(__dirname, '..', '..');
-const MIME = { '.html':'text/html; charset=utf-8', '.css':'text/css; charset=utf-8', '.js':'application/javascript; charset=utf-8' };
+const MIME = { '.html':'text/html; charset=utf-8', '.css':'text/css; charset=utf-8', '.js':'application/javascript; charset=utf-8', '.png':'image/png', '.svg':'image/svg+xml', '.ico':'image/x-icon' };
 const clients = new Set();
 
 function project(){ return store.readProject(ROOT); }
@@ -24,6 +24,37 @@ function body(req){ return new Promise(r=>{ let b=''; req.on('data',c=>b+=c); re
 function emit(obj){ const line='data: '+JSON.stringify(obj)+'\n\n'; for(const res of clients) res.write(line); }
 function findPlanFileForTask(id){ for(const pl of store.readPlans(ROOT)) for(const ph of pl.phases) if(ph.tasks.find(t=>t.id===id)) return pl.file; return null; }
 
+// ---- helpers for settings + attention points -----------------------------
+const configPath = () => path.join(ROOT, '.spectoflow', 'config.json');
+function writeConfig(patch){
+  const cp = configPath(); const cfg = JSON.parse(fs.readFileSync(cp, 'utf8'));
+  if (patch.mode && ['autopilot','semi','manual'].includes(patch.mode)) cfg.mode = patch.mode;
+  if (typeof patch.language === 'string' && patch.language.trim()) cfg.language = patch.language.trim();
+  fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
+  return cfg;
+}
+// Next free T-### id across every plan file (absolute paths from store.readPlans).
+function nextTaskId(){
+  let max = 0;
+  for (const pl of store.readPlans(ROOT)) {
+    try { const t = fs.readFileSync(pl.file, 'utf8'); const re = /\bT-(\d+)/g; let m; while ((m = re.exec(t))) max = Math.max(max, Number(m[1])); } catch {}
+  }
+  return 'T-' + String(max + 1).padStart(3, '0');
+}
+// Promote an attention item into a real checkbox task under an `## Attention` phase.
+function promoteAttention(item){
+  const plans = store.readPlans(ROOT);
+  let file = plans[0] && plans[0].file;
+  if (!file) { file = path.join(ROOT, 'plans', 'inbox.md'); fs.mkdirSync(path.dirname(file), { recursive: true }); if (!fs.existsSync(file)) fs.writeFileSync(file, '# Inbox\n'); }
+  const id = nextTaskId();
+  let text = fs.readFileSync(file, 'utf8');
+  const line = `- [ ] ${id} ${String(item.text).replace(/\s+/g, ' ').trim()} @user ~standard`;
+  if (/^##\s+Attention\s*$/m.test(text)) text = text.replace(/^(##\s+Attention\s*)$/m, `$1\n${line}`);
+  else { if (!text.endsWith('\n')) text += '\n'; text += `\n## Attention\n${line}\n`; }
+  fs.writeFileSync(file, text);
+  return { id, file };
+}
+
 function watch(dir){ try{ fs.watch(dir,{recursive:false},()=>emit({type:'change'})); }catch(_){} }
 ['plans','specs','.spectoflow'].forEach(d=>{ const p=path.join(ROOT,d); if(fs.existsSync(p)) watch(p); });
 
@@ -113,11 +144,64 @@ const server = http.createServer(async (req,res)=>{
       return sendJSON(res, ok ? 200 : 409, ok ? { ok: true } : { error: 'No pending approval.' });
     }
 
+    // ---- settings: change autonomy mode + output language (writes config.json) ----
+    if (p === '/api/settings' && req.method === 'POST') {
+      const patch = await body(req);
+      try { const cfg = writeConfig(patch); emit({ type: 'change' }); return sendJSON(res, 200, { config: cfg }); }
+      catch (e) { return sendJSON(res, 400, { error: String(e && e.message || e) }); }
+    }
+
+    // ---- attention points: agent- or user-raised notes; validate → real task ----
+    if (p === '/api/attention' && req.method === 'POST') {
+      const { text } = await body(req);
+      if (!text || !String(text).trim()) return sendJSON(res, 400, { error: 'Empty note.' });
+      const rt = store.readRuntime(ROOT); rt.attention = rt.attention || [];
+      const item = { id: 'att' + Date.now().toString(36), at: new Date().toISOString(), by: 'me', source: 'user', status: 'open', text: String(text).trim() };
+      rt.attention.unshift(item); store.writeRuntime(ROOT, rt); emit({ type: 'change' });
+      return sendJSON(res, 200, { item });
+    }
+    if (/^\/api\/attention\/[^/]+\/promote$/.test(p) && req.method === 'POST') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const rt = store.readRuntime(ROOT); const it = (rt.attention || []).find((x) => x.id === id);
+      if (!it) return sendJSON(res, 404, { error: 'Note not found.' });
+      const t = promoteAttention(it); it.status = 'resolved'; it.promotedTo = t.id;
+      store.writeRuntime(ROOT, rt); emit({ type: 'change' });
+      return sendJSON(res, 200, { task: t });
+    }
+    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'PATCH') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const patch = await body(req);
+      const rt = store.readRuntime(ROOT); const it = (rt.attention || []).find((x) => x.id === id);
+      if (!it) return sendJSON(res, 404, { error: 'Note not found.' });
+      if (typeof patch.text === 'string' && patch.text.trim()) it.text = patch.text.trim();
+      if (patch.status && ['open', 'resolved'].includes(patch.status)) it.status = patch.status;
+      store.writeRuntime(ROOT, rt); emit({ type: 'change' });
+      return sendJSON(res, 200, { item: it });
+    }
+    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'DELETE') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const rt = store.readRuntime(ROOT); rt.attention = (rt.attention || []).filter((x) => x.id !== id);
+      store.writeRuntime(ROOT, rt); emit({ type: 'change' });
+      return sendJSON(res, 200, { ok: true });
+    }
+
+    // ---- static files, with SPA fallback: a route like /backlog (no file extension)
+    //      that isn't a real asset serves index.html so client-side routing can take over ----
     let file=p==='/'?'/index.html':p;
     const full=path.join(PUBLIC,path.normalize(file).replace(/^(\.\.[/\\])+/,''));
     if(!full.startsWith(PUBLIC)){ res.writeHead(403); return res.end('Forbidden'); }
-    fs.readFile(full,(err,data)=>{ if(err){res.writeHead(404); return res.end('Not found');}
-      res.writeHead(200,{'Content-Type':MIME[path.extname(full)]||'application/octet-stream'}); res.end(data); });
+    fs.readFile(full,(err,data)=>{
+      if(err){
+        if(req.method==='GET' && !path.extname(p) && !p.startsWith('/api/')){
+          return fs.readFile(path.join(PUBLIC,'index.html'),(e2,d2)=>{
+            if(e2){ res.writeHead(404); return res.end('Not found'); }
+            res.writeHead(200,{'Content-Type':MIME['.html']}); res.end(d2);
+          });
+        }
+        res.writeHead(404); return res.end('Not found');
+      }
+      res.writeHead(200,{'Content-Type':MIME[path.extname(full)]||'application/octet-stream'}); res.end(data);
+    });
   }catch(e){ sendJSON(res,500,{error:String(e&&e.message||e)}); }
 });
 server.listen(PORT,()=>{ console.log(`spectoflow · dashboard → http://localhost:${PORT}`); console.log(`project root: ${ROOT}`); });

package/templates/lib/store.js

@@ -63,8 +63,26 @@ function parsePlan(text) {
   return phases;
 }
 
+// ---- directory resolution (plans/specs may live under a differently-named folder) --------------
+// Pure: no writes, cheap fs.existsSync probes only. Returns a directory NAME (not a full path):
+// an explicit config override wins if that folder actually exists under root; otherwise the first
+// existing candidate wins (so a project using the singular `plan/` just works); otherwise the
+// conventional default (candidates[0]) is returned even if it doesn't exist yet — callers that
+// need existence keep checking it themselves, same as before.
+function resolveDir(root, config, key, candidates) {
+  const override = config && config[key];
+  if (override && fs.existsSync(path.join(root, override))) return override;
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(root, c))) return c;
+  }
+  return candidates[0];
+}
+function resolvePlansDir(root, config) { return resolveDir(root, config || {}, 'plansDir', ['plans', 'plan']); }
+function resolveSpecsDir(root, config) { return resolveDir(root, config || {}, 'specsDir', ['specs', 'spec']); }
+
 function readPlans(projectRoot) {
-  const dir = path.join(projectRoot, 'plans');
+  const dirName = resolvePlansDir(projectRoot, readConfig(projectRoot));
+  const dir = path.join(projectRoot, dirName);
   if (!fs.existsSync(dir)) return [];
   const out = [];
   for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md')).sort()) {
@@ -74,10 +92,17 @@ function readPlans(projectRoot) {
   return out;
 }
 
+function readSpecs(projectRoot) {
+  const dirName = resolveSpecsDir(projectRoot, readConfig(projectRoot));
+  const d = path.join(projectRoot, dirName);
+  return fs.existsSync(d) ? fs.readdirSync(d).filter((x) => x.endsWith('.md')) : [];
+}
+
 // ---- granular writes ---------------------------------------------------------
 // Rewrite only the line whose task id matches, preserving everything else.
 function updateTaskLine(projectRoot, file, id, patch) {
-  const fp = path.join(projectRoot, 'plans', file);
+  const dirName = resolvePlansDir(projectRoot, readConfig(projectRoot));
+  const fp = path.join(projectRoot, dirName, file);
   const lines = fs.readFileSync(fp, 'utf8').split('\n');
   let changed = false;
   for (let i = 0; i < lines.length; i++) {
@@ -94,7 +119,8 @@ function updateTaskLine(projectRoot, file, id, patch) {
 }
 
 function addTaskComment(projectRoot, file, id, text, author) {
-  const fp = path.join(projectRoot, 'plans', file);
+  const dirName = resolvePlansDir(projectRoot, readConfig(projectRoot));
+  const fp = path.join(projectRoot, dirName, file);
   const lines = fs.readFileSync(fp, 'utf8').split('\n');
   for (let i = 0; i < lines.length; i++) {
     const t = parseTaskLine(lines[i]);
@@ -206,10 +232,7 @@ function readProject(projectRoot) {
   const plans = readPlans(projectRoot);
   let runtime = readRuntime(projectRoot);
   const workflow = readWorkflow(projectRoot);
-  const specs = (() => {
-    const d = path.join(projectRoot, 'specs');
-    return fs.existsSync(d) ? fs.readdirSync(d).filter((x) => x.endsWith('.md')) : [];
-  })();
+  const specs = readSpecs(projectRoot);
   const agents = listMd(path.join(projectRoot, '.spectoflow', 'agents'));
   const skills = listSkills(path.join(projectRoot, '.spectoflow', 'skills'));
 
@@ -283,7 +306,7 @@ function readSkills(projectRoot) {
 }
 
 module.exports = {
-  parseTaskLine, buildTaskLine, parsePlan, readPlans, updateTaskLine, addTaskComment,
+  parseTaskLine, buildTaskLine, parsePlan, readPlans, readSpecs, updateTaskLine, addTaskComment,
   readRuntime, writeRuntime, parseAgentLine, appendMessage, readConfig, readWorkflow, readProject,
-  readAgents, readSkills, recordSnapshot,
+  readAgents, readSkills, recordSnapshot, resolvePlansDir, resolveSpecsDir,
 };