spectoflow 0.20.0 → 0.21.0

package/README.md

@@ -20,11 +20,39 @@ An **agent-agnostic** spec-driven development framework with a **real-time local
 You speak in plain language; the framework classifies your intent and runs the right workflow. No
 ceremonial command to start.
 
-**Works with whichever coding agent you have** — Claude Code, Codex, Cursor, Gemini CLI, OpenCode,
-Kiro CLI, and Antigravity are auto-detected at `init`. The dashboard's topbar always shows the
-**active agent**, front and center, with a switcher: pick another and it's verified as genuinely
-installed before activating (a red **"No agent found"** if none is) — it never silently activates
-something that isn't there.
+**Works with whichever coding agent you have.** `init` auto-detects what's installed; the dashboard's
+topbar always shows the **active agent**, front and center, with a switcher — pick another and it's
+verified as genuinely installed before activating (a red **"No agent found"** if none is), never
+silently activating something that isn't there.
+
+> Note the terminology: "agent" is overloaded here on purpose, matching how the ecosystem uses the
+> word. The table below is about **coding-agent CLIs** — the tool you already run in your terminal
+> (Claude Code, Copilot CLI, …). spectoflow's own **team personas** (developer, qa-engineer, …) are a
+> different, unrelated use of "agent" — see [Agents vs skills](#agents-vs-skills) further down.
+
+| Coding agent | Headless run | Docs |
+|---|---|---|
+| Claude Code | ✓ | [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) |
+| Codex | ✓ | [developers.openai.com/codex/cli/reference](https://developers.openai.com/codex/cli/reference) |
+| Cursor CLI | ✓ | [cursor.com/docs/cli/overview](https://cursor.com/docs/cli/overview) |
+| Gemini CLI | ✓ | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
+| OpenCode | ✓ | [opencode.ai/docs/cli](https://opencode.ai/docs/cli/) |
+| Kiro CLI | ✓ | [kiro.dev/docs/cli/headless](https://kiro.dev/docs/cli/headless/) |
+| Antigravity | ✓ | [antigravity.google/docs/cli/headless](https://antigravity.google/docs/cli/headless/) |
+| GitHub Copilot CLI | ✓ | [docs.github.com/copilot/…/about-copilot-cli](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) |
+| Amazon Q Developer CLI | ✓ | [docs.aws.amazon.com/amazonq/…/command-line-chat](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-chat.html) |
+| Factory Droid CLI | ✓ | [docs.factory.ai/droid-exec/overview](https://docs.factory.ai/droid-exec/overview) |
+| Auggie CLI (Augment Code) | ✓ | [docs.augmentcode.com/cli/overview](https://docs.augmentcode.com/cli/overview) |
+| Goose CLI (Block) | ✓ | [block.github.io/goose](https://block.github.io/goose/) |
+| Kimi CLI | detectable, manual only | [github.com/MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) |
+
+"Headless run" means spectoflow can actually spawn it non-interactively (`Run`/`Orchestrate`/
+`Summarize` work). Kimi CLI has no confirmed one-shot mode as of this writing — spectoflow still
+detects it and lets you set it as the active agent, it just won't try to spawn it (the pickers that
+launch a run grey it out rather than hide it); drive it yourself in its own terminal meanwhile. The
+same live table, with your own install status, is in the dashboard's **Documentation** tab. Missing
+one you use? `config.json → runners` still takes any custom command by hand — see
+[`templates/README.md`](templates/README.md) — or open an issue.
 
 ## Install
 
@@ -139,16 +167,19 @@ spectoflow dashboard                     # → http://localhost:4319 (or --port=
 `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
+file watching. Ten tabs behind a dense icon-tab header (brand logo · subtitle · **active agent** ·
+autonomy mode · language · a slim global-progress meter · a sync dot · a **Run** quick-action): **Board**
+(the control-room Overview — compact KPI cards, a status donut, a **scope-vs-delivered area curve**, a
 workflow-at-a-glance strip, per-phase progress bars, filter chips + search — plus the phase board),
-**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
+**Chat** (a full-height group-chat panel with **Summarize**/**Clear**), **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), **Info** (a project-at-a-glance
+summary), **Documentation** (the supported-agents table above, live with your own install status and
+links, plus the CLI command reference), and **Personalize** (autonomy mode, language, design, the
+active agent, and **Extend spectoflow** — described under *Customize* below). URLs are real routes
 (`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in `dashboard/public/charts.js`
 (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and every aggregate is computed
 client-side.
@@ -173,7 +204,8 @@ read-only endpoint, `GET /api/agentfile?path=` (scoped to `.spectoflow/agents/**
 `.spectoflow/skills/**`, path-traversal-safe) — the framework's only other server surface is
 unchanged.
 
-**Customize.** Settings → **Customize** lets you extend the project's own spectoflow install: add a
+**Customize.** Personalize → **Extend spectoflow** lets you extend the project's own spectoflow
+install: add a
 dashboard, a skill, or an agent by describing what you want (or hit **Auto** to have the agent survey
 the project and propose candidates), and it clarifies first if the ask is ambiguous. Dashboards are
 never raw HTML — they're a small **declarative block spec** (`markdown`, `kpi-row`, `chart-bars`,

package/bin/spectoflow.js

@@ -474,10 +474,12 @@ ${c.dim('Docs:')} https://github.com/georgesmomo/spectoflow`);
 const HELP = {
   init: `${c.bold('spectoflow init')} ${c.dim('[dir] [--agent=a,b]')}\n
   Scaffold spectoflow into <dir> (default: current directory).
-  Auto-detects installed agents (${c.dim('claude, codex, cursor, gemini')}) and writes their entry
-  shims; override with ${c.g('--agent=claude,codex')}. Also wires ${c.bold('Playwright MCP')} into the
-  project's ${c.dim('.mcp.json')} (idempotent — never touches an existing entry).
-  ${c.dim('An existing CLAUDE.md is preserved as CLAUDE.md.tomerge for you to merge on first run.')}`,
+  Auto-detects installed agents (${c.dim('claude, codex, cursor, gemini, opencode, kiro, antigravity,')}
+  ${c.dim('copilot, amazon-q, droid, auggie, goose, kimi')}) and writes their entry shims; override
+  with ${c.g('--agent=claude,codex')}. Also wires ${c.bold('Playwright MCP')} into the project's
+  ${c.dim('.mcp.json')} (idempotent — never touches an existing entry).
+  ${c.dim('An existing CLAUDE.md is preserved as CLAUDE.md.tomerge for you to merge on first run.')}
+  ${c.dim('Full list with docs links: the dashboard\'s Documentation tab, or the README.')}`,
   update: `${c.bold('spectoflow update')} ${c.dim('[--dry-run] [--force|-f]')}\n
   Refresh framework-owned files (engine, dashboard, default agents & skills, AGENTS.md, policy…)
   to this CLI's version, ${c.bold('preserving your work')}: config.json, workflow.md, specs/, plans/

package/lib/adapters.js

@@ -68,56 +68,157 @@ Argument: \`$ARGUMENTS\`
 
 // Priority order = which agent becomes the default when several are detected.
 //
-// Considered and left out (researched, not re-added on a whim): Kimi Code CLI (MoonshotAI/kimi-cli)
-// and DeepSeek Harness (deepseek-ai/deepseek-harness) — as of Sept 2026 neither ships a genuine
-// non-interactive one-shot mode (prompt-as-trailing-arg, stdout, exit) that runner.js's spawn model
-// needs; Kimi is interactive/ACP-only, DeepSeek Harness is a local web-app framework. Revisit if
-// either ships a headless flag — a fabricated runner command would just fail silently for real users.
+// `docsUrl` points at that agent's own official CLI docs — cited from the research pass that set
+// `runner`/`headless`, never guessed; it's surfaced verbatim in the dashboard's Documentation tab so
+// "which agent is this and where do I read about it" has a real answer, not just an id.
+//
+// `headless: false` marks an agent spectoflow can DETECT and let you set as active, but never spawn
+// itself — no confirmed non-interactive one-shot mode (prompt as trailing arg → stdout → exit) as of
+// this research pass, so `runner` is null on purpose (a fabricated command would just fail silently
+// for real users). The dashboard still lists it and shows why Run/Orchestrate/Summarize are disabled
+// for it, rather than hiding it — you can drive it yourself in its own terminal meanwhile, and
+// `config.json → runners` is still yours to hand-wire a command into if one ships later.
+//
+// A runner string with more than one flag deliberately puts the trailing prompt right after whichever
+// flag takes a value (e.g. `copilot -s --allow-all-tools -p`, not `copilot -p --allow-all-tools`) —
+// runner.js spawns `[...parts.slice(1), prompt]`, appending the prompt as the LAST token, so a
+// value-taking flag must be the last one in the string or the prompt lands on the wrong flag.
+//
+// Researched against both github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md and
+// github.github.io/spec-kit/reference/integrations.html (broad agent-compatibility lists) — those
+// pages document IDE/slash-command integration, not headless CLI support, so every entry below was
+// independently verified against that tool's own primary docs regardless of appearing there.
+//
+// Left out of KNOWN_AGENTS entirely (not even headless:false) — researched, not re-added on a whim:
+// DeepSeek Harness (deepseek-ai/deepseek-harness). It has no single installable binary to detect —
+// it's invoked as `npx @deepseek-ai/dsh <subcommand>`, is explicitly a local WEB-APP framework (not a
+// terminal chat/prompt tool like the others), and ships as an August-2026 "developer preview" whose
+// APIs the project itself says will change. Detecting "is npx present" would not mean deepseek-harness
+// is; it doesn't fit this registry's detection model. Revisit once it (or Kimi) publishes a real
+// one-shot flag, or wire a custom command into config.json → runners by hand in the meantime.
 const REGISTRY = [
   {
     id: 'claude',
+    label: 'Claude Code',
     entries: [
       { path: 'CLAUDE.md', content: CLAUDE_MD },
       { path: '.claude/commands/spectoflow.md', content: SLASH_CMD },
     ],
     runner: 'claude -p --permission-mode acceptEdits',
+    headless: true,
+    docsUrl: 'https://code.claude.com/docs/en/cli-reference',
     detect: { bin: 'claude', dirs: ['.claude'] },
   },
   {
     id: 'codex',
+    label: 'Codex',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'codex exec',
+    headless: true,
+    docsUrl: 'https://developers.openai.com/codex/cli/reference',
     detect: { bin: 'codex', dirs: ['.codex'] },
   },
   {
     id: 'cursor',
+    label: 'Cursor',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'cursor-agent -p',
+    headless: true,
+    docsUrl: 'https://cursor.com/docs/cli/overview',
     detect: { bin: 'cursor-agent', dirs: ['.cursor'] },
   },
   {
     id: 'gemini',
+    label: 'Gemini CLI',
     entries: [{ path: 'GEMINI.md', content: GEMINI_MD }],
     runner: 'gemini -p',
+    headless: true,
+    docsUrl: 'https://github.com/google-gemini/gemini-cli',
     detect: { bin: 'gemini', dirs: ['.gemini'] },
   },
   {
     id: 'opencode',
+    label: 'OpenCode',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'opencode run --quiet',
+    headless: true,
+    docsUrl: 'https://opencode.ai/docs/cli/',
     detect: { bin: 'opencode', dirs: ['.opencode'] },
   },
   {
     id: 'kiro',
+    label: 'Kiro CLI',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'kiro-cli chat --no-interactive --trust-all-tools',
+    headless: true,
+    docsUrl: 'https://kiro.dev/docs/cli/headless/',
     detect: { bin: 'kiro-cli', dirs: ['.kiro'] },
   },
   {
     id: 'antigravity',
+    label: 'Antigravity',
     entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
     runner: 'agy -p',
-    detect: { bin: 'agy' },
+    headless: true,
+    docsUrl: 'https://antigravity.google/docs/cli/headless/',
+    detect: { bin: 'agy', dirs: [] },
+  },
+  {
+    id: 'kimi',
+    label: 'Kimi CLI',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
+    runner: null, // no confirmed non-interactive one-shot mode — see the note above REGISTRY
+    headless: false,
+    docsUrl: 'https://github.com/MoonshotAI/kimi-cli',
+    detect: { bin: 'kimi', dirs: [] },
+  },
+  {
+    id: 'copilot',
+    label: 'GitHub Copilot CLI',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }], // also reads CLAUDE.md/GEMINI.md and its own .github/copilot-instructions.md natively
+    runner: 'copilot -s --allow-all-tools -p',
+    headless: true,
+    docsUrl: 'https://docs.github.com/copilot/concepts/agents/about-copilot-cli',
+    // No detect.dirs on purpose: `.github/` is common on any project with GitHub Actions, whether or
+    // not Copilot CLI is set up — using it as a signal would falsely mark Copilot "installed" on
+    // countless unrelated projects. PATH detection (the bin) only.
+    detect: { bin: 'copilot', dirs: [] },
+  },
+  {
+    id: 'amazon-q',
+    label: 'Amazon Q Developer CLI',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }], // NOT confirmed native — Q wires memory via `.amazonq/rules/**/*.md` referenced in its own agent config; this pointer is a harmless, forward-compatible default in the meantime
+    runner: 'q chat --no-interactive --trust-all-tools',
+    headless: true,
+    docsUrl: 'https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-chat.html',
+    detect: { bin: 'q', dirs: ['.amazonq'] },
+  },
+  {
+    id: 'droid',
+    label: 'Factory Droid CLI',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
+    runner: 'droid exec',
+    headless: true,
+    docsUrl: 'https://docs.factory.ai/droid-exec/overview',
+    detect: { bin: 'droid', dirs: ['.factory'] },
+  },
+  {
+    id: 'auggie',
+    label: 'Auggie CLI',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
+    runner: 'auggie --quiet --print',
+    headless: true,
+    docsUrl: 'https://docs.augmentcode.com/cli/overview',
+    detect: { bin: 'auggie', dirs: ['.augment'] },
+  },
+  {
+    id: 'goose',
+    label: 'Goose CLI',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }], // memory-file convention not confirmed AGENTS.md-native — same harmless-default treatment as amazon-q
+    runner: 'goose run -t',
+    headless: true,
+    docsUrl: 'https://block.github.io/goose/',
+    detect: { bin: 'goose', dirs: ['.goose'] },
   },
 ];
 
@@ -148,7 +249,7 @@ function defaultRunners(agents) {
   const out = {};
   for (const id of agents) {
     const a = byId(id);
-    if (a) out[id] = a.runner;
+    if (a && a.runner) out[id] = a.runner; // headless:false agents (e.g. kimi) have no runner to seed
   }
   return out;
 }

package/package.json

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

package/templates/README.md

@@ -28,6 +28,8 @@ sit at the project root and just point back here.
   ```
 - **See what you got:** `spectoflow list` (agents, skills & workflow at a glance), or `spectoflow
   agents` / `spectoflow skills` / `spectoflow workflow`. Append `-h` to any command for its help.
+  (These "agents" are spectoflow's own team personas below, not the coding-agent CLI you're typing
+  into — see the dashboard's **Documentation** tab for which coding-agent CLIs spectoflow can drive.)
 - **Change how it runs** in the dashboard's **Personalize** tab (the **active agent**, always shown
   in the topbar too — switching is verified against what's actually installed before it activates —
   plus autonomy mode, output language, and the dashboard **design**), or by editing `config.json`.

package/templates/dashboard/public/app.js

@@ -95,7 +95,8 @@ function setChat(open){
   $('#chat').setAttribute('aria-hidden', open?'false':'true');
   $('#chatFab').classList.toggle('is-open',open);
   try{ localStorage.setItem('spf-chat', open?'1':'0'); }catch{}
-  if(open) setTimeout(()=>$('#runPrompt').focus(),60);
+  // Land where you can actually type, not wherever the log happened to be scrolled last.
+  if(open) setTimeout(()=>{ scrollChat($('#chatLog')); $('#runPrompt').focus(); },60);
 }
 // doRun/doOrchestrate default to the floating widget's textarea/select; the Chat tab has its own
 // #tabRunPrompt/#tabRunAgent (an id can't be shared by two elements) and passes them explicitly —
@@ -139,11 +140,10 @@ function render(){
   // in renderSettings() below (called on every render tick) and saved via saveSettings().
   // 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.
-  const runners=Object.keys((c.runners)||{claude:1});
-  [$('#runAgent'),$('#tabRunAgent')].forEach(sel=>{
-    if(!sel) return;
-    if(sel.options.length!==runners.length){ sel.innerHTML=''; runners.forEach(k=>{ const o=document.createElement('option'); o.value=k; o.textContent=k; sel.append(o); }); if(c.agent) sel.value=c.agent; }
-  });
+  // Shows every known agent (not just ones already in config.json → runners — a freshly-installed
+  // agent works the first time, runner.js falls back to the registry default), disabling any that
+  // isn't genuinely installed or can't run headless (e.g. kimi).
+  [$('#runAgent'),$('#tabRunAgent')].forEach(sel=>fillAgentSelect(sel,P.knownAgents||[],runnableAgentIds(),c.agent));
   const s=SpectoStats.stats(P);
   const meterFill=$('#globalMeterFill');
   if(meterFill) meterFill.style.width=(s.pct||0)+'%';
@@ -151,7 +151,7 @@ function render(){
   if(meter) meter.title=`${t('kpi.globalProgress')}: ${s.pct}% (${s.done}/${s.total} ${t('kpi.tasksLabel')})`;
   renderOverview(); renderBoard(); renderBacklog(); renderWorkflow(); renderTeam();
   renderChatLog($('#chatLog')); renderChatLog($('#chatTabLog'));
-  renderSidebar(); renderRequests(); renderAttention(); renderInfo(); renderSettings();
+  renderSidebar(); renderRequests(); renderAttention(); renderInfo(); renderDocs(); renderSettings();
   renderCustomDashboards(); // adds/removes nav tabs + panels before applyActiveTab() below reads them
   applyActiveTab(); // re-apply the current tab so an SSE-driven re-render never resets to Board
   applyI18nStatic(); // re-translate the static markup (nav, headers, placeholders…) for this tick's language
@@ -264,7 +264,7 @@ function renderOverview(){
 
   // KPI row
   const kpis=el('div','kpi-row');
-  kpis.append(kpiCard(t('kpi.globalProgress'), ring(s.pct,72), `${s.done}/${s.total} ${t('kpi.tasksLabel')}`, cssv('--s-done')));
+  kpis.append(kpiCard(t('kpi.globalProgress'), ring(s.pct,52), `${s.done}/${s.total} ${t('kpi.tasksLabel')}`, cssv('--s-done')));
   kpis.append(kpiCard(t('status.in_progress'), numBlock(s.byStatus.in_progress||0,'var(--s-in_progress)'), t('kpi.tasksLabel'), cssv('--s-in_progress')));
   kpis.append(kpiCard(t('status.to_validate'), numBlock(s.byStatus.to_validate||0,'var(--s-to_validate)'), t('kpi.awaitingReview'), cssv('--s-to_validate')));
   const r=s.running||{};
@@ -717,6 +717,12 @@ function setModeSelects(mode){ [$('#setMode'),$('#topMode')].forEach(s=>{ if(s)
 // the user activate an agent that isn't actually installed — options for a not-installed known agent
 // are present but disabled, and P.installedAgents itself comes from the server testing each agent's
 // real CLI (bin on PATH, or the project's own config dir), not a guess.
+// ids that can actually be SPAWNED right now: installed AND headless-capable (a known agent like
+// kimi can be "installed" and even the active agent, but nothing can run it non-interactively).
+function runnableAgentIds(){
+  const installed=P.installedAgents||[];
+  return (P.knownAgents||[]).filter(a=>a.headless&&installed.includes(a.id)).map(a=>a.id);
+}
 function fillAgentSelect(sel,known,installed,active){
   if(!sel) return;
   const empty=!installed.length;
@@ -936,9 +942,7 @@ function renderCustomize(){
       const form=el('div','cz-form');
       const ta=el('textarea','chat-ta'); ta.placeholder=t('customize.describePh');
       const sel=el('select','chat-agent');
-      const runners=Object.keys((P.config&&P.config.runners)||{claude:1});
-      runners.forEach((k)=>{ const o=document.createElement('option'); o.value=k; o.textContent=k; sel.append(o); });
-      if(P.config&&P.config.agent) sel.value=P.config.agent;
+      fillAgentSelect(sel,P.knownAgents||[],runnableAgentIds(),P.config&&P.config.agent);
       const actions=el('div','cz-form-actions');
       const autoBtn=el('button','btn',t('customize.auto'));
       const goBtn=el('button','btn primary',t('customize.generate'));
@@ -963,7 +967,7 @@ async function czSubmit(kind,description,agent){
 // A custom dashboard (Customize page) gets its own tab id "custom:<id>" and its own URL shape
 // /custom/<id> — kept out of ROUTES (a fixed list) since the set of custom ids is dynamic; recognized
 // by a dedicated branch in tabFromPath()/navigateTab() instead.
-const ROUTES=['board','requests','attention','backlog','workflow','team','chat','info','settings'];
+const ROUTES=['board','requests','attention','backlog','workflow','team','chat','info','docs','settings'];
 function tabFromPath(){
   const s=location.pathname.split('/').filter(Boolean);
   if(s[0]==='custom'&&s[1]) return 'custom:'+decodeURIComponent(s[1]);
@@ -978,6 +982,10 @@ function navigateTab(tabId,push){
   }
   applyActiveTab();
   closeNav(); // a tab pick closes the mobile menu
+  // Landing on Chat: go straight to where you can read the latest and type, not wherever the log
+  // was scrolled to last (only on an actual switch INTO the tab — applyActiveTab() alone runs on
+  // every SSE render tick too, and re-scrolling/re-focusing there would fight the user's typing).
+  if(tabId==='chat') setTimeout(()=>{ scrollChat($('#chatTabLog')); $('#tabRunPrompt').focus(); },60);
 }
 function closeNav(){ document.body.classList.remove('nav-open'); const nt=$('#navToggle'); if(nt) nt.setAttribute('aria-expanded','false'); }
 
@@ -1038,7 +1046,11 @@ function mdLite(raw){
   // 2) escape HTML — everything below builds markup only from this escaped text
   text=escHtml(text);
   // 3) convert a small markdown subset to HTML
-  const inline=s=> s.replace(/`([^`]+)`/g,'<code>$1</code>').replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>');
+  const inline=s=> s
+    .replace(/`([^`]+)`/g,'<code>$1</code>')
+    .replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>')
+    .replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g,'<a href="$2" target="_blank" rel="noopener">$1</a>') // [text](url)
+    .replace(/(^|[^"'>])(https?:\/\/[^\s<]+)/g,'$1<a href="$2" target="_blank" rel="noopener">$2</a>'); // bare https://… URLs, skipping ones already inside an href/text we just built
   const lines=text.split('\n');
   let html='', inCode=false, codeBuf=[], listBuf=[], paraBuf=[];
   const flushPara=()=>{ if(paraBuf.length){ html+='<p>'+paraBuf.join(' ')+'</p>'; paraBuf=[]; } };
@@ -1157,6 +1169,73 @@ function renderInfo(){
   box.append(infoSection(t('info.workflowLabel'),'workflow',wfList));
 }
 
+// ---- Documentation tab: which coding agents spectoflow can drive (with links to each one's own
+// docs, sourced from the same registry the topbar switcher reads) + the CLI command reference.
+// Never build this table from anything but P.knownAgents/P.installedAgents — that data comes from a
+// real PATH/config-dir test on the server, never a guess spectoflow hasn't verified. ----
+function linkEl(text,url){ const a=document.createElement('a'); a.href=url; a.target='_blank'; a.rel='noopener'; a.textContent=text; return a; }
+function docsAgentsTable(){
+  const known=P.knownAgents||[], installed=P.installedAgents||[];
+  const wrap=el('div','table-scroll'); const tbl=el('table','backlog-table');
+  const thead=el('thead'); const htr=el('tr');
+  [t('docs.colAgent'),t('docs.colStatus'),t('docs.colDocs')].forEach(c=>htr.append(el('th',null,c)));
+  thead.append(htr); tbl.append(thead);
+  const tbody=el('tbody');
+  known.forEach(a=>{
+    const tr=el('tr');
+    tr.append(el('td',null,a.label));
+    const statusTd=el('td');
+    const isInstalled=installed.includes(a.id);
+    const chip=el('span','chip s-'+(isInstalled?'done':'todo'), isInstalled?t('docs.installed'):t('docs.notInstalled'));
+    statusTd.append(chip);
+    if(!a.headless){ statusTd.append(document.createTextNode(' ')); statusTd.append(el('span','docs-manual-badge',t('docs.manualOnly'))); }
+    tr.append(statusTd);
+    const docsTd=el('td');
+    if(a.docsUrl) docsTd.append(linkEl(t('docs.officialDocs'),a.docsUrl));
+    tr.append(docsTd);
+    tbody.append(tr);
+  });
+  tbl.append(tbody); wrap.append(tbl);
+  return wrap;
+}
+function docsCommandsTable(){
+  const rows=[
+    ['spectoflow init [dir] [--agent=a,b]', t('docs.cmd.init')],
+    ['spectoflow update [--dry-run] [--force|-f]', t('docs.cmd.update')],
+    ['spectoflow status', t('docs.cmd.status')],
+    ['spectoflow dashboard [--port=NNNN]', t('docs.cmd.dashboard')],
+    ['spectoflow dashboard status|stop|restart', t('docs.cmd.dashboardSub')],
+    ['spectoflow dashboard create "…" | --auto', t('docs.cmd.dashboardCreate')],
+    ['spectoflow skill create "…" | --auto', t('docs.cmd.skillCreate')],
+    ['spectoflow agent create "…" | --auto', t('docs.cmd.agentCreate')],
+    ['spectoflow list', t('docs.cmd.list')],
+    ['spectoflow agents · skills · workflow', t('docs.cmd.explore')],
+  ];
+  const wrap=el('div','table-scroll'); const tbl=el('table','backlog-table');
+  const thead=el('thead'); const htr=el('tr');
+  [t('docs.colCommand'),t('docs.colWhatItDoes')].forEach(c=>htr.append(el('th',null,c)));
+  thead.append(htr); tbl.append(thead);
+  const tbody=el('tbody');
+  rows.forEach(([cmd,desc])=>{
+    const tr=el('tr');
+    const cmdTd=el('td'); const code=el('code',null,cmd); cmdTd.append(code); tr.append(cmdTd);
+    tr.append(el('td',null,desc));
+    tbody.append(tr);
+  });
+  tbl.append(tbody); wrap.append(tbl);
+  return wrap;
+}
+function renderDocs(){
+  const box=$('#docsBody'); if(!box) return;
+  box.innerHTML='';
+  box.append(infoSection(t('docs.agentsTitle'),'agents',docsAgentsTable()));
+  box.append(infoSection(t('docs.commandsTitle'),'run',docsCommandsTable()));
+  const note=el('p','docs-note');
+  note.append(document.createTextNode(t('docs.moreNote')+' '));
+  note.append(linkEl('github.com/georgesmomo/spectoflow','https://github.com/georgesmomo/spectoflow'));
+  box.append(note);
+}
+
 function openDrawer(id,keep){
   // named `task`, not `t` — `t` is the global translation function (see i18n.js) and this whole
   // function calls it repeatedly below; shadowing it with a task variable would break every call.
@@ -1297,6 +1376,8 @@ $('#chatClose').addEventListener('click',()=> setChat(false));
 try{ if(localStorage.getItem('spf-chat')==='1') setChat(true); }catch{}
 $('#runBtn').addEventListener('click',()=>doRun());
 $('#orchBtn').addEventListener('click',()=>doOrchestrate());
+$('#widgetSummarizeBtn').addEventListener('click',()=>summarizeChat($('#runAgent')));
+$('#widgetClearBtn').addEventListener('click',clearChat);
 $('#runPrompt').addEventListener('keydown',e=>{ if((e.metaKey||e.ctrlKey)&&e.key==='Enter')doRun(); });
 // Chat tab — same doRun/doOrchestrate/approve, its own textarea/select (#tabRunPrompt/#tabRunAgent)
 $('#tabRunBtn').addEventListener('click',()=>doRun($('#tabRunPrompt'),$('#tabRunAgent')));

package/templates/dashboard/public/i18n.js

@@ -20,7 +20,7 @@
 const I18N = {
 en: {
   'nav.board':'Board','nav.requests':'Requests','nav.attention':'Attention','nav.backlog':'Backlog',
-  'nav.workflow':'Workflow','nav.team':'Agents & Skills','nav.chat':'Chat','nav.info':'Info','nav.settings':'Personalize',
+  'nav.workflow':'Workflow','nav.team':'Agents & Skills','nav.chat':'Chat','nav.info':'Info','nav.docs':'Documentation','nav.settings':'Personalize',
   'status.todo':'To do','status.in_progress':'In progress','status.to_validate':'To validate',
   'status.to_analyze':'To analyze','status.done':'Done','status.blocked':'Blocked',
   'filter.all':'All','filter.open':'Open','filter.resolved':'Resolved',
@@ -114,10 +114,25 @@ en: {
   'customize.add.dashboard':'Add dashboard','customize.add.skill':'Add skill','customize.add.agent':'Add agent',
   'customize.empty.dashboard':'No custom dashboards yet.','customize.empty.skill':'No custom skills yet.','customize.empty.agent':'No custom agents yet.',
   'customize.describePh':'Describe what you want…','customize.auto':'Auto','customize.generate':'Generate','customize.blocksSub':'block(s)',
+  'docs.title':'Documentation','docs.sub':'Which coding agents spectoflow can drive, and the commands that drive them.',
+  'docs.agentsTitle':'Supported agents','docs.commandsTitle':'Commands',
+  'docs.colAgent':'Agent','docs.colStatus':'Status','docs.colDocs':'Docs','docs.colCommand':'Command','docs.colWhatItDoes':'What it does',
+  'docs.installed':'Installed','docs.notInstalled':'Not installed','docs.manualOnly':'Manual only','docs.officialDocs':'Official docs ↗',
+  'docs.moreNote':'Full reference, source and license on GitHub:',
+  'docs.cmd.init':'Scaffold a project (auto-detects agents; wires Playwright MCP).',
+  'docs.cmd.update':'Refresh framework files to this kit version, preserving your work.',
+  'docs.cmd.status':'Progress + whether the dashboard is running.',
+  'docs.cmd.dashboard':'Start the control plane in the background.',
+  'docs.cmd.dashboardSub':'Check, stop, or restart the running dashboard.',
+  'docs.cmd.dashboardCreate':'Generate a custom dashboard from the terminal.',
+  'docs.cmd.skillCreate':'Generate a project-specific skill from the terminal.',
+  'docs.cmd.agentCreate':'Generate a project-specific agent persona from the terminal.',
+  'docs.cmd.list':'Agents, skills and the workflow at a glance.',
+  'docs.cmd.explore':'List the team personas, the procedures, or the pipeline steps.',
 },
 fr: {
   'nav.board':'Tableau','nav.requests':'Demandes','nav.attention':'Attention','nav.backlog':'Backlog',
-  'nav.workflow':'Workflow','nav.team':'Agents et compétences','nav.chat':'Chat','nav.info':'Infos','nav.settings':'Personnalisation',
+  'nav.workflow':'Workflow','nav.team':'Agents et compétences','nav.chat':'Chat','nav.info':'Infos','nav.docs':'Documentation','nav.settings':'Personnalisation',
   'status.todo':'À faire','status.in_progress':'En cours','status.to_validate':'À valider',
   'status.to_analyze':'À analyser','status.done':'Terminé','status.blocked':'Bloqué',
   'filter.all':'Tous','filter.open':'Ouverts','filter.resolved':'Résolus',
@@ -211,10 +226,25 @@ fr: {
   'customize.add.dashboard':'Ajouter un dashboard','customize.add.skill':'Ajouter une compétence','customize.add.agent':'Ajouter un agent',
   'customize.empty.dashboard':'Aucun dashboard personnalisé pour l’instant.','customize.empty.skill':'Aucune compétence personnalisée pour l’instant.','customize.empty.agent':'Aucun agent personnalisé pour l’instant.',
   'customize.describePh':'Décrivez ce que vous voulez…','customize.auto':'Auto','customize.generate':'Générer','customize.blocksSub':'bloc(s)',
+  'docs.title':'Documentation','docs.sub':'Les agents de code que spectoflow peut piloter, et les commandes qui les pilotent.',
+  'docs.agentsTitle':'Agents pris en charge','docs.commandsTitle':'Commandes',
+  'docs.colAgent':'Agent','docs.colStatus':'Statut','docs.colDocs':'Docs','docs.colCommand':'Commande','docs.colWhatItDoes':'Ce que ça fait',
+  'docs.installed':'Installé','docs.notInstalled':'Non installé','docs.manualOnly':'Manuel uniquement','docs.officialDocs':'Doc officielle ↗',
+  'docs.moreNote':'Référence complète, source et licence sur GitHub :',
+  'docs.cmd.init':'Initialise un projet (détecte les agents automatiquement ; câble Playwright MCP).',
+  'docs.cmd.update':'Met à jour les fichiers du framework vers cette version, en préservant vos modifications.',
+  'docs.cmd.status':'Progression + si le dashboard tourne.',
+  'docs.cmd.dashboard':'Démarre le plan de contrôle en arrière-plan.',
+  'docs.cmd.dashboardSub':'Vérifie, arrête ou redémarre le dashboard en cours.',
+  'docs.cmd.dashboardCreate':'Génère un dashboard personnalisé depuis le terminal.',
+  'docs.cmd.skillCreate':'Génère une compétence propre au projet depuis le terminal.',
+  'docs.cmd.agentCreate':'Génère un agent (persona) propre au projet depuis le terminal.',
+  'docs.cmd.list':'Agents, compétences et workflow en un coup d’œil.',
+  'docs.cmd.explore':'Liste les personas de l’équipe, les procédures ou les étapes du pipeline.',
 },
 es: {
   'nav.board':'Tablero','nav.requests':'Solicitudes','nav.attention':'Atención','nav.backlog':'Backlog',
-  'nav.workflow':'Workflow','nav.team':'Agentes y habilidades','nav.chat':'Chat','nav.info':'Info','nav.settings':'Personalizar',
+  'nav.workflow':'Workflow','nav.team':'Agentes y habilidades','nav.chat':'Chat','nav.info':'Info','nav.docs':'Documentación','nav.settings':'Personalizar',
   'status.todo':'Por hacer','status.in_progress':'En curso','status.to_validate':'Por validar',
   'status.to_analyze':'Por analizar','status.done':'Hecho','status.blocked':'Bloqueado',
   'filter.all':'Todos','filter.open':'Abiertos','filter.resolved':'Resueltos',
@@ -308,10 +338,25 @@ es: {
   'customize.add.dashboard':'Añadir dashboard','customize.add.skill':'Añadir habilidad','customize.add.agent':'Añadir agente',
   'customize.empty.dashboard':'Aún no hay dashboards personalizados.','customize.empty.skill':'Aún no hay habilidades personalizadas.','customize.empty.agent':'Aún no hay agentes personalizados.',
   'customize.describePh':'Describe lo que quieres…','customize.auto':'Auto','customize.generate':'Generar','customize.blocksSub':'bloque(s)',
+  'docs.title':'Documentación','docs.sub':'Qué agentes de código puede pilotar spectoflow, y los comandos que los pilotan.',
+  'docs.agentsTitle':'Agentes compatibles','docs.commandsTitle':'Comandos',
+  'docs.colAgent':'Agente','docs.colStatus':'Estado','docs.colDocs':'Docs','docs.colCommand':'Comando','docs.colWhatItDoes':'Qué hace',
+  'docs.installed':'Instalado','docs.notInstalled':'No instalado','docs.manualOnly':'Solo manual','docs.officialDocs':'Docs oficial ↗',
+  'docs.moreNote':'Referencia completa, código fuente y licencia en GitHub:',
+  'docs.cmd.init':'Crea un proyecto (detecta agentes automáticamente; conecta Playwright MCP).',
+  'docs.cmd.update':'Actualiza los archivos del framework a esta versión, preservando tu trabajo.',
+  'docs.cmd.status':'Progreso + si el dashboard está en ejecución.',
+  'docs.cmd.dashboard':'Inicia el panel de control en segundo plano.',
+  'docs.cmd.dashboardSub':'Consulta, detiene o reinicia el dashboard en ejecución.',
+  'docs.cmd.dashboardCreate':'Genera un dashboard personalizado desde la terminal.',
+  'docs.cmd.skillCreate':'Genera una habilidad propia del proyecto desde la terminal.',
+  'docs.cmd.agentCreate':'Genera un agente (persona) propio del proyecto desde la terminal.',
+  'docs.cmd.list':'Agentes, habilidades y workflow de un vistazo.',
+  'docs.cmd.explore':'Lista los personas del equipo, los procedimientos o los pasos del pipeline.',
 },
 de: {
   'nav.board':'Board','nav.requests':'Anfragen','nav.attention':'Hinweise','nav.backlog':'Backlog',
-  'nav.workflow':'Workflow','nav.team':'Agenten & Skills','nav.chat':'Chat','nav.info':'Info','nav.settings':'Personalisieren',
+  'nav.workflow':'Workflow','nav.team':'Agenten & Skills','nav.chat':'Chat','nav.info':'Info','nav.docs':'Dokumentation','nav.settings':'Personalisieren',
   'status.todo':'Offen','status.in_progress':'In Arbeit','status.to_validate':'Zu prüfen',
   'status.to_analyze':'Zu analysieren','status.done':'Erledigt','status.blocked':'Blockiert',
   'filter.all':'Alle','filter.open':'Offen','filter.resolved':'Erledigt',
@@ -405,10 +450,25 @@ de: {
   'customize.add.dashboard':'Dashboard hinzufügen','customize.add.skill':'Skill hinzufügen','customize.add.agent':'Agent hinzufügen',
   'customize.empty.dashboard':'Noch keine eigenen Dashboards.','customize.empty.skill':'Noch keine eigenen Skills.','customize.empty.agent':'Noch keine eigenen Agenten.',
   'customize.describePh':'Beschreiben Sie, was Sie wollen…','customize.auto':'Auto','customize.generate':'Generieren','customize.blocksSub':'Block/Blöcke',
+  'docs.title':'Dokumentation','docs.sub':'Welche Coding-Agenten spectoflow steuern kann, und die Befehle dafür.',
+  'docs.agentsTitle':'Unterstützte Agenten','docs.commandsTitle':'Befehle',
+  'docs.colAgent':'Agent','docs.colStatus':'Status','docs.colDocs':'Docs','docs.colCommand':'Befehl','docs.colWhatItDoes':'Was er macht',
+  'docs.installed':'Installiert','docs.notInstalled':'Nicht installiert','docs.manualOnly':'Nur manuell','docs.officialDocs':'Offizielle Docs ↗',
+  'docs.moreNote':'Vollständige Referenz, Quellcode und Lizenz auf GitHub:',
+  'docs.cmd.init':'Projekt aufsetzen (erkennt Agenten automatisch; verdrahtet Playwright MCP).',
+  'docs.cmd.update':'Framework-Dateien auf diese Version aktualisieren, eigene Änderungen bleiben erhalten.',
+  'docs.cmd.status':'Fortschritt + ob das Dashboard läuft.',
+  'docs.cmd.dashboard':'Startet die Kontrollzentrale im Hintergrund.',
+  'docs.cmd.dashboardSub':'Prüft, stoppt oder startet das laufende Dashboard neu.',
+  'docs.cmd.dashboardCreate':'Erzeugt ein individuelles Dashboard über das Terminal.',
+  'docs.cmd.skillCreate':'Erzeugt einen projektspezifischen Skill über das Terminal.',
+  'docs.cmd.agentCreate':'Erzeugt eine projektspezifische Agenten-Persona über das Terminal.',
+  'docs.cmd.list':'Agenten, Skills und Workflow auf einen Blick.',
+  'docs.cmd.explore':'Listet die Team-Personas, die Verfahren oder die Pipeline-Schritte.',
 },
 pt: {
   'nav.board':'Painel','nav.requests':'Pedidos','nav.attention':'Atenção','nav.backlog':'Backlog',
-  'nav.workflow':'Workflow','nav.team':'Agentes e habilidades','nav.chat':'Chat','nav.info':'Info','nav.settings':'Personalizar',
+  'nav.workflow':'Workflow','nav.team':'Agentes e habilidades','nav.chat':'Chat','nav.info':'Info','nav.docs':'Documentação','nav.settings':'Personalizar',
   'status.todo':'A fazer','status.in_progress':'Em curso','status.to_validate':'Por validar',
   'status.to_analyze':'Por analisar','status.done':'Concluído','status.blocked':'Bloqueado',
   'filter.all':'Todos','filter.open':'Abertos','filter.resolved':'Resolvidos',
@@ -502,10 +562,25 @@ pt: {
   'customize.add.dashboard':'Adicionar dashboard','customize.add.skill':'Adicionar habilidade','customize.add.agent':'Adicionar agente',
   'customize.empty.dashboard':'Ainda sem dashboards personalizados.','customize.empty.skill':'Ainda sem habilidades personalizadas.','customize.empty.agent':'Ainda sem agentes personalizados.',
   'customize.describePh':'Descreva o que quer…','customize.auto':'Auto','customize.generate':'Gerar','customize.blocksSub':'bloco(s)',
+  'docs.title':'Documentação','docs.sub':'Quais agentes de código o spectoflow consegue conduzir, e os comandos que os conduzem.',
+  'docs.agentsTitle':'Agentes suportados','docs.commandsTitle':'Comandos',
+  'docs.colAgent':'Agente','docs.colStatus':'Estado','docs.colDocs':'Docs','docs.colCommand':'Comando','docs.colWhatItDoes':'O que faz',
+  'docs.installed':'Instalado','docs.notInstalled':'Não instalado','docs.manualOnly':'Só manual','docs.officialDocs':'Docs oficial ↗',
+  'docs.moreNote':'Referência completa, código-fonte e licença no GitHub:',
+  'docs.cmd.init':'Cria um projeto (deteta agentes automaticamente; liga o Playwright MCP).',
+  'docs.cmd.update':'Atualiza os ficheiros do framework para esta versão, preservando o seu trabalho.',
+  'docs.cmd.status':'Progresso + se o dashboard está em execução.',
+  'docs.cmd.dashboard':'Inicia o painel de controlo em segundo plano.',
+  'docs.cmd.dashboardSub':'Verifica, para ou reinicia o dashboard em execução.',
+  'docs.cmd.dashboardCreate':'Gera um dashboard personalizado a partir do terminal.',
+  'docs.cmd.skillCreate':'Gera uma competência própria do projeto a partir do terminal.',
+  'docs.cmd.agentCreate':'Gera um agente (persona) próprio do projeto a partir do terminal.',
+  'docs.cmd.list':'Agentes, competências e workflow de relance.',
+  'docs.cmd.explore':'Lista os personas da equipa, os procedimentos ou os passos do pipeline.',
 },
 it: {
   'nav.board':'Bacheca','nav.requests':'Richieste','nav.attention':'Attenzione','nav.backlog':'Backlog',
-  'nav.workflow':'Workflow','nav.team':'Agenti e competenze','nav.chat':'Chat','nav.info':'Info','nav.settings':'Personalizza',
+  'nav.workflow':'Workflow','nav.team':'Agenti e competenze','nav.chat':'Chat','nav.info':'Info','nav.docs':'Documentazione','nav.settings':'Personalizza',
   'status.todo':'Da fare','status.in_progress':'In corso','status.to_validate':'Da convalidare',
   'status.to_analyze':'Da analizzare','status.done':'Fatto','status.blocked':'Bloccato',
   'filter.all':'Tutti','filter.open':'Aperti','filter.resolved':'Risolti',
@@ -599,6 +674,21 @@ it: {
   'customize.add.dashboard':'Aggiungi dashboard','customize.add.skill':'Aggiungi skill','customize.add.agent':'Aggiungi agente',
   'customize.empty.dashboard':'Ancora nessuna dashboard personalizzata.','customize.empty.skill':'Ancora nessuna skill personalizzata.','customize.empty.agent':'Ancora nessun agente personalizzato.',
   'customize.describePh':'Descrivi cosa vuoi…','customize.auto':'Auto','customize.generate':'Genera','customize.blocksSub':'blocco/i',
+  'docs.title':'Documentazione','docs.sub':'Quali agenti di codice spectoflow può guidare, e i comandi che li guidano.',
+  'docs.agentsTitle':'Agenti supportati','docs.commandsTitle':'Comandi',
+  'docs.colAgent':'Agente','docs.colStatus':'Stato','docs.colDocs':'Docs','docs.colCommand':'Comando','docs.colWhatItDoes':'Cosa fa',
+  'docs.installed':'Installato','docs.notInstalled':'Non installato','docs.manualOnly':'Solo manuale','docs.officialDocs':'Docs ufficiale ↗',
+  'docs.moreNote':'Riferimento completo, codice sorgente e licenza su GitHub:',
+  'docs.cmd.init':'Crea un progetto (rileva gli agenti automaticamente; collega Playwright MCP).',
+  'docs.cmd.update':'Aggiorna i file del framework a questa versione, preservando il tuo lavoro.',
+  'docs.cmd.status':'Avanzamento + se il dashboard è in esecuzione.',
+  'docs.cmd.dashboard':'Avvia il pannello di controllo in background.',
+  'docs.cmd.dashboardSub':'Controlla, ferma o riavvia il dashboard in esecuzione.',
+  'docs.cmd.dashboardCreate':'Genera una dashboard personalizzata dal terminale.',
+  'docs.cmd.skillCreate':'Genera una skill specifica del progetto dal terminale.',
+  'docs.cmd.agentCreate':'Genera un agente (persona) specifico del progetto dal terminale.',
+  'docs.cmd.list':'Agenti, skill e workflow a colpo d’occhio.',
+  'docs.cmd.explore':'Elenca le persona del team, le procedure o i passaggi della pipeline.',
 },
 };
 

package/templates/dashboard/public/icons.js

@@ -25,6 +25,8 @@
     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 (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"/>'),
+    // open book — documentation
+    docs: wrap('<path d="M9 5.4C7.4 4.2 5.2 3.7 2.8 4v9c2.4-.3 4.6.2 6.2 1.4 1.6-1.2 3.8-1.7 6.2-1.4V4c-2.4-.3-4.6.2-6.2 1.4z"/><line x1="9" y1="5.4" x2="9" y2="14.4"/>'),
     // 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"/>'),
   };

package/templates/dashboard/public/index.html

@@ -57,6 +57,7 @@
       <button class="tab" data-tab="workflow" data-i18n-title="nav.workflow" title="Workflow"><span class="tab-ico" data-icon="workflow"></span><span class="tab-label" data-i18n="nav.workflow">Workflow</span></button>
       <button class="tab" data-tab="team" data-i18n-title="nav.team" title="Agents &amp; Skills"><span class="tab-ico" data-icon="agents"></span><span class="tab-label" data-i18n="nav.team">Agents &amp; Skills</span></button>
       <button class="tab" data-tab="info" data-i18n-title="nav.info" title="Info"><span class="tab-ico" data-icon="info"></span><span class="tab-label" data-i18n="nav.info">Info</span></button>
+      <button class="tab" data-tab="docs" data-i18n-title="nav.docs" title="Documentation"><span class="tab-ico" data-icon="docs"></span><span class="tab-label" data-i18n="nav.docs">Documentation</span></button>
       <button class="tab" data-tab="settings" data-i18n-title="nav.settings" title="Personalize"><span class="tab-ico" data-icon="settings"></span><span class="tab-label" data-i18n="nav.settings">Personalize</span></button>
     </nav>
     <div class="top-right">
@@ -201,16 +202,18 @@
             <h2 class="panel-title" data-i18n="nav.chat">Chat</h2>
             <p class="panel-sub" data-i18n="chat.tabSub">Full conversation with the runner — the same run as the widget, more room to read it.</p>
           </div>
-          <div class="chat-tab-head-actions">
-            <button id="tabSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>
-            <button id="tabClearBtn" class="mini-btn" data-i18n-title="chat.clearTitle" data-i18n="action.clear" title="Clear the chat log">Clear</button>
-            <select id="tabRunAgent" class="chat-agent" title="Agent"></select>
-          </div>
         </div>
         <div class="chat-tab-log" id="chatTabLog">
           <div class="chat-idle" data-i18n-html="chat.idle">Type a request — the agent runs headless in this project with full memory
             (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.</div>
         </div>
+        <!-- Toolbar right above the input, not up in the header — this is where you're looking
+             when you reach for Summarize/Clear or switch which agent the next message runs on. -->
+        <div class="chat-tab-toolbar">
+          <button id="tabSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>
+          <button id="tabClearBtn" class="mini-btn" data-i18n-title="chat.clearTitle" data-i18n="action.clear" title="Clear the chat log">Clear</button>
+          <select id="tabRunAgent" class="chat-agent" title="Agent"></select>
+        </div>
         <div class="chat-tab-input">
           <textarea id="tabRunPrompt" class="chat-ta" data-i18n-ph="chat.inputPlaceholder" placeholder="e.g. Add a login feature with email + password"></textarea>
           <div class="chat-tab-actions">
@@ -231,6 +234,15 @@
       </div>
     </section>
 
+    <!-- DOCUMENTATION (agent compatibility + CLI command reference — filled by renderDocs() in app.js) -->
+    <section class="panel" data-panel="docs">
+      <div class="info-wrap">
+        <h2 class="panel-title" data-i18n="docs.title">Documentation</h2>
+        <p class="panel-sub" data-i18n="docs.sub">Which coding agents spectoflow can drive, and the commands that drive them.</p>
+        <div class="info-grid docs-grid" id="docsBody"></div>
+      </div>
+    </section>
+
     <!-- SETTINGS (change autonomy mode + output language → config.json) -->
     <section class="panel" data-panel="settings">
       <div class="settings-wrap">
@@ -306,13 +318,17 @@
         <span class="chat-title" data-i18n="chat.widgetTitle">Run an agent</span>
         <span class="chat-sub" data-i18n="chat.widgetSub">Quick access · full view in the Chat tab</span>
       </div>
-      <select id="runAgent" class="chat-agent" title="Agent"></select>
       <button class="chat-close" id="chatClose" aria-label="Close">×</button>
     </div>
     <div class="chat-log" id="chatLog">
       <div class="chat-idle" data-i18n-html="chat.idle">Type a request — the agent runs headless in this project with full memory
         (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.</div>
     </div>
+    <div class="chat-toolbar">
+      <button id="widgetSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>
+      <button id="widgetClearBtn" class="mini-btn" data-i18n-title="chat.clearTitle" data-i18n="action.clear" title="Clear the chat log">Clear</button>
+      <select id="runAgent" class="chat-agent" title="Agent"></select>
+    </div>
     <div class="chat-input">
       <textarea id="runPrompt" class="chat-ta" data-i18n-ph="chat.inputPlaceholder" placeholder="e.g. Add a login feature with email + password"></textarea>
       <button id="runBtn" class="btn primary chat-send" data-i18n="action.send">Send</button>

package/templates/dashboard/public/styles.css

@@ -97,17 +97,17 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 
 /* overview: KPI cards + status donut + workflow strip + phase bars */
 .overview { padding:22px 24px 6px; display:flex; flex-direction:column; gap:14px; }
-.kpi-row { display:grid; grid-template-columns:repeat(4,1fr); gap:12px; }
-.kpi { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:14px 16px; display:flex; flex-direction:column; gap:8px; transition:box-shadow .15s; }
+.kpi-row { display:grid; grid-template-columns:repeat(4,1fr); gap:9px; }
+.kpi { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:10px 13px; display:flex; flex-direction:column; gap:4px; transition:box-shadow .15s; }
 .kpi:hover { box-shadow:var(--shadow); }
-.kpi-label { font-size:11px; text-transform:uppercase; letter-spacing:.08em; color:var(--faint); font-weight:700; }
+.kpi-label { font-size:10px; text-transform:uppercase; letter-spacing:.07em; color:var(--faint); font-weight:700; }
 .kpi-body { display:flex; align-items:center; }
-.kpi-num { font-family:var(--mono); font-size:30px; font-weight:700; line-height:1; color:var(--ink); }
-.kpi-num.is-text { font-size:17px; text-transform:capitalize; }
-.kpi-sub { font-size:11.5px; color:var(--muted); }
+.kpi-num { font-family:var(--mono); font-size:23px; font-weight:700; line-height:1; color:var(--ink); }
+.kpi-num.is-text { font-size:14px; text-transform:capitalize; }
+.kpi-sub { font-size:10.5px; color:var(--muted); }
 
 .ring-wrap { position:relative; display:inline-flex; align-items:center; justify-content:center; }
-.ring-wrap .ring-label { position:absolute; font-family:var(--mono); font-size:13px; font-weight:700; color:var(--ink); }
+.ring-wrap .ring-label { position:absolute; font-family:var(--mono); font-size:10.5px; font-weight:700; color:var(--ink); }
 .ring-svg circle { transition:stroke-dashoffset .5s ease; }
 
 .ocard { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:16px 18px; }
@@ -378,7 +378,8 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .chat-title { font-weight:700; font-size:15px; }
 .chat-sub { font-size:10px; color:var(--faint); text-transform:uppercase; letter-spacing:.04em; }
 .chat-agent { margin-left:auto; flex-shrink:0; font:inherit; font-size:12px; background:var(--surface); color:var(--ink); border:1px solid var(--line); border-radius:7px; padding:5px 8px; }
-.chat-close { width:28px; height:28px; flex-shrink:0; border:1px solid var(--line); background:var(--surface-2); color:var(--muted); border-radius:8px; font-size:17px; cursor:pointer; transition:border-color .15s,color .15s; }
+.chat-toolbar { display:flex; align-items:center; gap:8px; padding:8px 14px; border-top:1px solid var(--line); flex-wrap:wrap; }
+.chat-close { width:28px; height:28px; flex-shrink:0; margin-left:auto; border:1px solid var(--line); background:var(--surface-2); color:var(--muted); border-radius:8px; font-size:17px; cursor:pointer; transition:border-color .15s,color .15s; }
 .chat-close:hover { border-color:color-mix(in srgb,var(--s-blocked) 45%,var(--line)); color:var(--ink); }
 .chat-log { flex:1; overflow-y:auto; padding:16px; display:flex; flex-direction:column; gap:11px; }
 .chat-idle { color:var(--faint); font-style:italic; font-size:12.5px; }
@@ -414,10 +415,10 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .chat-tab-head { display:flex; align-items:flex-start; gap:14px; margin-bottom:14px; }
 .chat-tab-head .panel-title { margin:0; }
 .chat-tab-head .panel-sub { margin:2px 0 0; }
-.chat-tab-head-actions { display:flex; align-items:center; gap:8px; margin-left:auto; flex-shrink:0; flex-wrap:wrap; }
-.chat-tab-head .chat-agent { flex-shrink:0; }
 .chat-tab-log { flex:1; min-height:220px; overflow-y:auto; display:flex; flex-direction:column; gap:12px; background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:20px; box-shadow:var(--shadow); }
-.chat-tab-input { display:flex; gap:10px; margin-top:14px; }
+.chat-tab-toolbar { display:flex; align-items:center; gap:8px; margin-top:10px; flex-wrap:wrap; }
+.chat-tab-toolbar .chat-agent { margin-left:auto; flex-shrink:0; }
+.chat-tab-input { display:flex; gap:10px; margin-top:10px; }
 .chat-tab-input .chat-ta { flex:1; min-height:56px; max-height:180px; }
 .chat-tab-actions { display:flex; flex-direction:column; gap:8px; flex-shrink:0; }
 .chat-tab-wrap .chat-warn { margin:8px 0 0; }
@@ -555,6 +556,14 @@ body.booting .ring-svg circle:last-of-type { transform-origin:center; animation:
 .settings-select:focus { outline:2px solid var(--signal); outline-offset:1px; }
 .settings-field-hint { font-size:12px; }
 .settings-field-hint.is-empty { color:var(--s-blocked); }
+.docs-grid { grid-template-columns:1fr; } /* the built-in tables are wide — full width beats 2-up */
+.docs-grid .backlog-table a { color:var(--signal); text-decoration:none; }
+.docs-grid .backlog-table a:hover { text-decoration:underline; }
+.docs-grid .backlog-table code { font-family:var(--mono); font-size:12px; }
+.docs-manual-badge { font-size:10px; text-transform:uppercase; letter-spacing:.05em; color:var(--muted); border:1px solid var(--line); border-radius:999px; padding:2px 7px; }
+.docs-note { margin:14px 2px 0; font-size:12.5px; color:var(--muted); }
+.docs-note a { color:var(--signal); text-decoration:none; }
+.docs-note a:hover { text-decoration:underline; }
 .settings-saved { align-self:flex-start; font-size:12px; color:var(--s-done); font-family:var(--mono); }
 .settings-saved[hidden] { display:none; }
 .settings-readonly { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); overflow:hidden; }

package/templates/dashboard/runner.js

@@ -9,6 +9,18 @@
  */
 const { spawn } = require('child_process');
 const store = require('../lib/store');
+const agentsRegistry = require('../lib/agents-registry');
+
+// The command to run `which`: config.json's own runners map first (an explicit user choice always
+// wins), falling back to the registry's default for a known, headless-capable, genuinely-installed
+// agent — so picking one from a per-message agent list works the first time, before it's ever been
+// the project's "active agent" and had a runner seeded into config.json for it.
+function resolveRunnerCommand(root, cfg, which, opts) {
+  if (cfg.runners && cfg.runners[which]) return cfg.runners[which];
+  const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === which);
+  if (known && known.runner && agentsRegistry.isAgentInstalled(which, root, opts)) return known.runner;
+  return null;
+}
 
 function runStart(root, run) {
   const rt = store.readRuntime(root); rt.agents = rt.agents || []; rt.agents.push(run); store.writeRuntime(root, rt);
@@ -50,7 +62,7 @@ function pushAttention(root, text, by) {
 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];
+  const cmdStr = resolveRunnerCommand(root, cfg, which);
   if (!cmdStr) return { error: `No runner configured for "${which}".` };
   const parts = cmdStr.split(/\s+/).filter(Boolean);
   const runId = 'r' + Date.now().toString(36);
@@ -97,4 +109,4 @@ function startRun(root, { prompt, agent, logPrompt = true }, emit) {
   return { runId, child };
 }
 
-module.exports = { startRun };
+module.exports = { startRun, resolveRunnerCommand };

package/templates/dashboard/server.js

@@ -35,7 +35,7 @@ function project(){
   // Known vs. actually-installed agents — the topbar switcher needs both: the full list to offer,
   // and which ones are real (bin on PATH, or the project already has that agent's config dir) so it
   // can refuse to activate one that isn't there.
-  p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label }));
+  p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label, headless: a.headless, docsUrl: a.docsUrl }));
   p.installedAgents = agentsRegistry.installedAgents(ROOT);
   return p;
 }
@@ -62,8 +62,11 @@ function writeConfig(patch){
     }
     cfg.agent = id;
     // Seed a default runner if this agent was never configured (e.g. installed after init/update).
+    // A headless:false agent (e.g. kimi) has no runner to seed — it can still be the active agent,
+    // it just can't be spawned by Run/Orchestrate/Summarize (disabled client-side; runner.js and
+    // summarize.js also refuse server-side either way).
     const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
-    if (known) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
+    if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
   }
   fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
   return cfg;

package/templates/dashboard/summarize.js

@@ -6,6 +6,7 @@
  */
 const { spawn } = require('child_process');
 const store = require('../lib/store');
+const { resolveRunnerCommand } = require('./runner');
 
 const DEFAULT_LIMIT = 40;
 
@@ -20,7 +21,7 @@ function formatLog(messages, limit = DEFAULT_LIMIT) {
 function runSummarize(root, { agent } = {}, emit) {
   const cfg = store.readConfig(root);
   const which = agent || cfg.agent || 'claude';
-  const cmdStr = cfg.runners && cfg.runners[which];
+  const cmdStr = resolveRunnerCommand(root, cfg, which);
   if (!cmdStr) return { error: `No runner configured for "${which}".` };
 
   const rt = store.readRuntime(root);

package/templates/lib/agents-registry.js

@@ -9,14 +9,27 @@
 const fs = require('fs');
 const path = require('path');
 
+// headless:false = detectable and selectable as the active agent, but spectoflow never spawns it
+// itself (no confirmed non-interactive one-shot mode) — Run/Orchestrate/Summarize stay disabled for
+// it client-side; runner/summarize.js also refuse server-side (defense in depth). `docsUrl` is that
+// agent's own official CLI docs, surfaced verbatim in the dashboard's Documentation tab. See the
+// longer rationale above lib/adapters.js's REGISTRY, the richer install-time twin of this list —
+// including why DeepSeek Harness isn't here at all, and why some runner strings order their flags
+// the way they do (the trailing prompt must land right after whichever flag takes a value).
 const KNOWN_AGENTS = [
-  { id: 'claude', label: 'Claude Code', bin: 'claude', dirs: ['.claude'], runner: 'claude -p --permission-mode acceptEdits' },
-  { id: 'codex', label: 'Codex', bin: 'codex', dirs: ['.codex'], runner: 'codex exec' },
-  { id: 'cursor', label: 'Cursor', bin: 'cursor-agent', dirs: ['.cursor'], runner: 'cursor-agent -p' },
-  { id: 'gemini', label: 'Gemini CLI', bin: 'gemini', dirs: ['.gemini'], runner: 'gemini -p' },
-  { id: 'opencode', label: 'OpenCode', bin: 'opencode', dirs: ['.opencode'], runner: 'opencode run --quiet' },
-  { id: 'kiro', label: 'Kiro CLI', bin: 'kiro-cli', dirs: ['.kiro'], runner: 'kiro-cli chat --no-interactive --trust-all-tools' },
-  { id: 'antigravity', label: 'Antigravity', bin: 'agy', dirs: [], runner: 'agy -p' },
+  { id: 'claude', label: 'Claude Code', bin: 'claude', dirs: ['.claude'], runner: 'claude -p --permission-mode acceptEdits', headless: true, docsUrl: 'https://code.claude.com/docs/en/cli-reference' },
+  { id: 'codex', label: 'Codex', bin: 'codex', dirs: ['.codex'], runner: 'codex exec', headless: true, docsUrl: 'https://developers.openai.com/codex/cli/reference' },
+  { id: 'cursor', label: 'Cursor', bin: 'cursor-agent', dirs: ['.cursor'], runner: 'cursor-agent -p', headless: true, docsUrl: 'https://cursor.com/docs/cli/overview' },
+  { id: 'gemini', label: 'Gemini CLI', bin: 'gemini', dirs: ['.gemini'], runner: 'gemini -p', headless: true, docsUrl: 'https://github.com/google-gemini/gemini-cli' },
+  { id: 'opencode', label: 'OpenCode', bin: 'opencode', dirs: ['.opencode'], runner: 'opencode run --quiet', headless: true, docsUrl: 'https://opencode.ai/docs/cli/' },
+  { id: 'kiro', label: 'Kiro CLI', bin: 'kiro-cli', dirs: ['.kiro'], runner: 'kiro-cli chat --no-interactive --trust-all-tools', headless: true, docsUrl: 'https://kiro.dev/docs/cli/headless/' },
+  { id: 'antigravity', label: 'Antigravity', bin: 'agy', dirs: [], runner: 'agy -p', headless: true, docsUrl: 'https://antigravity.google/docs/cli/headless/' },
+  { id: 'kimi', label: 'Kimi CLI', bin: 'kimi', dirs: [], runner: null, headless: false, docsUrl: 'https://github.com/MoonshotAI/kimi-cli' },
+  { id: 'copilot', label: 'GitHub Copilot CLI', bin: 'copilot', dirs: [], runner: 'copilot -s --allow-all-tools -p', headless: true, docsUrl: 'https://docs.github.com/copilot/concepts/agents/about-copilot-cli' },
+  { id: 'amazon-q', label: 'Amazon Q Developer CLI', bin: 'q', dirs: ['.amazonq'], runner: 'q chat --no-interactive --trust-all-tools', headless: true, docsUrl: 'https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-chat.html' },
+  { id: 'droid', label: 'Factory Droid CLI', bin: 'droid', dirs: ['.factory'], runner: 'droid exec', headless: true, docsUrl: 'https://docs.factory.ai/droid-exec/overview' },
+  { id: 'auggie', label: 'Auggie CLI', bin: 'auggie', dirs: ['.augment'], runner: 'auggie --quiet --print', headless: true, docsUrl: 'https://docs.augmentcode.com/cli/overview' },
+  { id: 'goose', label: 'Goose CLI', bin: 'goose', dirs: ['.goose'], runner: 'goose run -t', headless: true, docsUrl: 'https://block.github.io/goose/' },
 ];
 
 // Is `bin` an executable resolvable on PATH? On win32, an extension from PATHEXT is required, so we