@cordfuse/crosstalk 8.0.0-alpha.1 → 8.1.0

package/lib/nativeServer.js

@@ -77,9 +77,18 @@ export function startEngine(name, opts = {}) {
     CROSSTALK_API_PORT: port,
     TRANSPORT_DIR: transportDir,
   };
+  // Default state to per-instance (keyed by name). Without this the
+  // dispatcher falls back to stateDir()'s default, keyed on
+  // basename(transportRoot) — always "transport" for a local-fs transport —
+  // so every named local instance would share one cursor/heartbeat/errors
+  // dir and clobber each other. Honor an explicit CROSSTALK_STATE_DIR if the
+  // caller already set one (the MC harness pins its heartbeat/cursor/errors
+  // there to isolate its run) — only fill in the default when it's absent.
+  if (!env.CROSSTALK_STATE_DIR) {
+    env.CROSSTALK_STATE_DIR = paths.crosstalkState;
+  }
   if (opts.transportPath) {
     env.CROSSTALK_TRANSPORT_PATH = transportDir;
-    env.CROSSTALK_STATE_DIR = paths.crosstalkState;
   }
 
   const logFd = openSync(paths.logFile, 'a');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "8.0.0-alpha.1",
+  "version": "8.1.0",
   "description": "Crosstalk — agent-agnostic swarm communication protocol over a shared directory (git or filesystem transport). Operator CLI + daemon in one binary.",
   "type": "module",
   "license": "MIT",

package/src/api.ts

@@ -39,8 +39,10 @@ import {
 import { sendWakeSignal, readHeartbeat, readCursor, countErrors } from './state.js';
 import { reList } from './activation.js';
 import { isOnPath, type ModelEntry, type ModelsRegistry } from './models.js';
+import { AGENT_CATALOG, connectAgent } from './onboarding.js';
 import { resolveToField } from './resolve.js';
 import { dashboardPage } from './web/dashboard.js';
+import { wizardPage } from './web/wizard.js';
 import { channelListPage, channelViewPage, agentsPage, type BusMessage } from './web/channels.js';
 import { workflowsListPage, workflowDetailPage, type WorkflowSummary } from './web/workflows.js';
 import { setupPage as authSetupPage, loginPage as authLoginPage } from './web/auth-pages.js';
@@ -664,7 +666,7 @@ async function tryWebAuthFlow(ctx: ApiContext, req: IncomingMessage, res: Server
   // setup/api-setup path, redirect to /setup so the first browser visit
   // bootstraps the admin account.
   const HTML_GATED_PATHS = new Set([
-    '/', '/agents', '/chat',
+    '/', '/welcome', '/agents', '/chat',
     '/tokens', '/logs', '/settings', '/account', '/users', '/about',
   ]);
   if (method === 'GET' && (HTML_GATED_PATHS.has(path) || path.startsWith('/c') || path.startsWith('/w'))) {
@@ -714,6 +716,7 @@ async function tryWebApiRoute(ctx: ApiContext, req: IncomingMessage, res: Server
     path === '/api/account' || path === '/api/account/passphrase' ||
     path === '/api/users' || path.startsWith('/api/users/') ||
     path === '/api/workflows' || path.startsWith('/api/workflows/') ||
+    path === '/api/onboarding/agents' || path === '/api/onboarding/connect' ||
     path === '/api/logs' || path === '/api/logs/stream' ||
     path === '/api/settings';
   if (!isApiPath) return false;
@@ -785,6 +788,41 @@ async function tryWebApiRoute(ctx: ApiContext, req: IncomingMessage, res: Server
     }
   }
 
+  // ── Onboarding wizard ────────────────────────────────────────────
+  // GET /api/onboarding/agents → catalog entries annotated with whether
+  // each CLI is installed on this engine's PATH and already claimed.
+  if (method === 'GET' && path === '/api/onboarding/agents') {
+    const agents = Object.values(AGENT_CATALOG).map((e) => ({
+      cli: e.cli, label: e.label, provider: e.provider, model: e.model,
+      installed: isOnPath(e.cli),
+      claimed: ctx.registry.claimed.has(`${e.provider}/${e.model}`),
+      needsKey: e.keyEnv !== null, keyHint: e.keyHint,
+    }));
+    writeJson(res, 200, { agents }, ctx.version);
+    return true;
+  }
+  // POST /api/onboarding/connect {cli, apiKey?} → admin: write the provider
+  // block (+ optional key file) and SIGHUP so the dispatcher claims it live.
+  if (method === 'POST' && path === '/api/onboarding/connect') {
+    if (!me.admin) { writeJson(res, 403, { error: 'admin only' }, ctx.version); return true; }
+    const body = await readJson<{ cli?: string; apiKey?: string }>(req);
+    const cli = (body.cli ?? '').trim();
+    if (!AGENT_CATALOG[cli]) { writeJson(res, 400, { error: `unknown agent CLI '${cli}'` }, ctx.version); return true; }
+    if (!isOnPath(cli)) { writeJson(res, 400, { error: `'${cli}' is not installed on this engine's PATH` }, ctx.version); return true; }
+    let result;
+    try {
+      result = connectAgent(ctx.transportRoot, cli, body.apiKey);
+    } catch (err) {
+      writeJson(res, 500, { error: `failed to write config: ${(err as Error).message}` }, ctx.version);
+      return true;
+    }
+    // Reload the registry live — the API runs in the dispatcher process, so
+    // SIGHUP to self triggers the registry hot-reload (see src/dispatch.ts).
+    try { process.kill(process.pid, 'SIGHUP'); } catch { /* best-effort */ }
+    writeJson(res, 200, { ok: true, ...result }, ctx.version);
+    return true;
+  }
+
   // ── Account: change passphrase ───────────────────────────────────
   if (method === 'POST' && path === '/api/account/passphrase') {
     const body = await readJson<{ oldPassphrase?: string; newPassphrase?: string }>(req);
@@ -1099,6 +1137,11 @@ async function tryHtmlRoute(ctx: ApiContext, req: IncomingMessage, res: ServerRe
     return true;
   }
 
+  if (path === '/welcome') {
+    writeHtml(res, 200, wizardPage({ host, alias: ctx.alias }), ctx.version);
+    return true;
+  }
+
   if (path === '/c') {
     const channels = allChannelMeta(ctx.transportRoot);
     writeHtml(res, 200, channelListPage({

package/src/dispatch.ts

@@ -504,6 +504,35 @@ async function main(): Promise<void> {
     );
   }
 
+  // Hot-reload the model registry on SIGHUP, no restart. The dispatcher
+  // loads crosstalk.yaml once at startup; the onboarding wizard (and any
+  // operator who edits the yaml) raises SIGHUP so newly-added providers/
+  // models are claimed live. Mutate the EXISTING registry maps in place —
+  // the running API context captured these map references at startApi(), so
+  // reassigning `registry` would leave /status + the dashboard stale.
+  process.on('SIGHUP', () => {
+    try {
+      const fresh = loadRegistry(transportRoot);
+      registry.all.clear();
+      for (const [k, v] of fresh.all) registry.all.set(k, v);
+      registry.byBareName.clear();
+      for (const [k, v] of fresh.byBareName) registry.byBareName.set(k, v);
+      registry.claimed.clear();
+      for (const [k, v] of fresh.claimed) registry.claimed.set(k, v);
+      writeRegistryEntry(transportRoot, alias!, [...registry.claimed.keys()], RUNTIME_VERSION);
+      const push = transport.publish(`dispatch(${alias}): reload registry (SIGHUP)`);
+      if (!push.ok && push.error) {
+        logError(transportRoot, `registry publish after reload failed: ${push.error}`, 'warn');
+      }
+      log('registry_reloaded', {
+        claimed_models: [...registry.claimed.keys()],
+        total_models: registry.all.size,
+      });
+    } catch (err) {
+      logError(transportRoot, `registry reload (SIGHUP) failed — keeping current set: ${(err as Error).message}`, 'warn');
+    }
+  });
+
   if (onceMode) {
     await dispatchTick(registry, protocolPrompt);
     process.exit(0);

package/src/onboarding.ts

@@ -0,0 +1,136 @@
+// onboarding.ts — agent catalog + config writers backing the first-run
+// wizard. The wizard turns "0 agents connected" into a working agent by
+// writing a provider block to data/crosstalk.yaml (and, optionally, an API
+// key to auth/<provider>.env) and raising SIGHUP so the dispatcher claims
+// the new model live. See src/dispatch.ts SIGHUP handler + src/web/wizard.ts.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { parseDocument, YAMLMap } from 'yaml';
+import { crosstalkYamlPath } from './models.js';
+
+export interface AgentCatalogEntry {
+  cli: string;            // binary name (matches KNOWN_AGENT_BINARIES in api.ts)
+  label: string;          // display name for the wizard
+  provider: string;       // provider key written to the yaml
+  model: string;          // model name written under the provider
+  command: string;        // command string the dispatcher runs
+  keyEnv: string | null;  // env var the key goes in, or null if host-authed
+  keyHint: string;        // guidance shown next to the (optional) key field
+}
+
+// Default command strings mirror the documented examples in the template
+// crosstalk.yaml. Most of these CLIs authenticate via their own host
+// credential store (codex ~/.codex/auth.json, claude/gemini interactive
+// login), so the key field is optional — on a host where the CLI is already
+// logged in, just writing the model entry yields a working agent.
+export const AGENT_CATALOG: Record<string, AgentCatalogEntry> = {
+  claude: {
+    cli: 'claude', label: 'Claude (Anthropic)', provider: 'anthropic', model: 'sonnet',
+    command: 'claude --print --dangerously-skip-permissions --model sonnet',
+    keyEnv: 'ANTHROPIC_API_KEY',
+    keyHint: 'Leave blank if `claude` is already logged in on this host; otherwise paste an Anthropic API key.',
+  },
+  codex: {
+    cli: 'codex', label: 'Codex (OpenAI)', provider: 'openai-codex', model: 'codex',
+    command: 'codex --skip-git-repo-check',
+    keyEnv: null,
+    keyHint: 'Codex uses its own login (`codex login`) — no key needed here.',
+  },
+  gemini: {
+    cli: 'gemini', label: 'Gemini (Google)', provider: 'google', model: 'gemini',
+    command: 'gemini --skip-trust --yolo -p',
+    keyEnv: 'GEMINI_API_KEY',
+    keyHint: 'Leave blank if `gemini` is already logged in; otherwise paste a Google AI Studio key.',
+  },
+  agy: {
+    cli: 'agy', label: 'Antigravity (Google)', provider: 'google-agy', model: 'agy',
+    command: 'agy --print',
+    keyEnv: 'GEMINI_API_KEY',
+    keyHint: 'Leave blank if already authenticated; otherwise paste a Google AI Studio key.',
+  },
+  qwen: {
+    cli: 'qwen', label: 'Qwen', provider: 'qwen', model: 'qwen',
+    command: 'qwen --yolo -p',
+    keyEnv: null,
+    keyHint: 'Qwen uses its own login — no key needed here.',
+  },
+  opencode: {
+    cli: 'opencode', label: 'OpenCode', provider: 'opencode', model: 'opencode',
+    command: 'opencode run',
+    keyEnv: null,
+    keyHint: 'OpenCode uses its own provider config — no key needed here.',
+  },
+};
+
+export interface ConnectResult {
+  provider: string;
+  model: string;
+  qualified: string;
+  wroteKey: boolean;
+}
+
+/**
+ * Write a provider/model block to data/crosstalk.yaml (preserving the file's
+ * comments via the YAML Document API) and, when an apiKey is supplied for a
+ * key-based provider, an auth/<provider>.env file (0600). Idempotent: adding
+ * a provider/model that already exists just overwrites that leaf.
+ *
+ * Does NOT reload the dispatcher — the caller raises SIGHUP after this returns.
+ */
+export function connectAgent(transportRoot: string, cli: string, apiKey?: string): ConnectResult {
+  const entry = AGENT_CATALOG[cli];
+  if (!entry) throw new Error(`unknown agent CLI '${cli}'`);
+
+  let envFile: string | null = null;
+  const key = (apiKey ?? '').trim();
+  if (entry.keyEnv && key.length > 0) {
+    envFile = `auth/${entry.provider}.env`;
+    const envPath = join(transportRoot, envFile);
+    mkdirSync(dirname(envPath), { recursive: true });
+    // 0600 — secrets file, owner-only. env_file (a relpath) is what lands in
+    // the committable yaml; the raw key stays out of it.
+    writeFileSync(envPath, `${entry.keyEnv}=${key}\n`, { mode: 0o600 });
+  }
+
+  const yamlPath = crosstalkYamlPath(transportRoot);
+  const raw = readFileSync(yamlPath, 'utf-8');
+  const doc = parseDocument(raw);
+  const providers = doc.get('providers');
+  const provExists = providers instanceof YAMLMap && providers.has(entry.provider);
+
+  if (provExists) {
+    // Provider already present (re-run, or adding a second model) — merge
+    // via the Document API so the existing structure's comments survive.
+    const prov = (providers as YAMLMap).get(entry.provider) as YAMLMap;
+    let models = prov.get('models');
+    if (!(models instanceof YAMLMap)) { models = new YAMLMap(); prov.set('models', models); }
+    (models as YAMLMap).set(entry.model, entry.command);
+    if (envFile) prov.set('env_file', envFile);
+    writeFileSync(yamlPath, doc.toString());
+  } else {
+    // New provider — append as text rather than restructuring, so the
+    // template's commented schema docs + example blocks are preserved
+    // verbatim (rewriting the Document drops comments attached to the empty
+    // `providers:` node). The file ends inside the `providers:` mapping, so
+    // a two-space-indented block becomes its child.
+    const block = envFile
+      ? `  ${entry.provider}:\n    env_file: ${envFile}\n    models:\n      ${entry.model}: ${entry.command}\n`
+      : `  ${entry.provider}:\n    models:\n      ${entry.model}: ${entry.command}\n`;
+    // Only synthesize a top-level `providers:` if the file genuinely lacks
+    // one — checked against the raw text so a present-but-null `providers:`
+    // (the template default) doesn't get a duplicate key appended.
+    const hasProvidersKey = /^providers\s*:/m.test(raw);
+    let out = raw.replace(/\s*$/, '') + '\n';
+    if (!hasProvidersKey) out += '\nproviders:\n';
+    out += block;
+    writeFileSync(yamlPath, out);
+  }
+
+  return {
+    provider: entry.provider,
+    model: entry.model,
+    qualified: `${entry.provider}/${entry.model}`,
+    wroteKey: envFile !== null,
+  };
+}

package/src/web/channels.ts

@@ -21,7 +21,7 @@ export function channelListPage(d: ChannelListData): string {
     <span>Channels (${d.channels.length})</span>
     <button id="open-new-channel" class="primary" type="button" style="font-size:11px;font-weight:600">+ new channel</button>
   </h3>
-  <p class="sub">Each channel is a directory under <code>data/channels/&lt;uuid&gt;/</code>. Messages and replies live as committed markdown files.</p>
+  <p class="sub">A channel is a conversation thread. Post a message addressed to an agent and the dispatcher delivers its reply here. (Under the hood, each channel is a folder of markdown files on the bus.)</p>
   <div id="new-channel-form" style="display:none;background:#0b0c10;border:1px solid #1f2329;border-radius:6px;padding:12px;margin-bottom:14px">
     <div class="field" style="margin-bottom:8px">
       <label for="new-channel-name">Channel name</label>
@@ -352,36 +352,38 @@ export interface AgentsPageData {
 }
 
 export function agentsPage(d: AgentsPageData): string {
-  function chips(list: string[], highlightedList: string[], emptyMsg: string): string {
-    if (list.length === 0) return `<p class="empty">${escapeHtml(emptyMsg)}</p>`;
-    return list.map(a => {
-      const cls = highlightedList.includes(a) ? 'chip brand' : 'chip';
-      return `<span class="${cls}">${escapeHtml(a)}</span>`;
-    }).join('');
+  // One row per supported CLI with its resolved status, rather than four
+  // cards of look-alike chips (the catalog and the installed list were
+  // identical whenever every supported CLI happened to be on PATH, and the
+  // chips read as tappable buttons when they're just labels). Iterate the
+  // union of the catalog + anything the yaml references, so a stray
+  // reference to an unknown CLI still surfaces.
+  const allClis = Array.from(new Set([...d.known, ...d.yamlReferenced, ...d.installed])).sort();
+  function statusFor(cli: string): { label: string; cls: string } {
+    const installed = d.installed.includes(cli);
+    const referenced = d.yamlReferenced.includes(cli);
+    const claimed = d.claimed.includes(cli);
+    if (claimed) return { label: 'claimed · ready to dispatch', cls: 'ok' };
+    if (installed && referenced) return { label: 'configured · restart engine to claim', cls: 'warn' };
+    if (installed) return { label: 'installed · add to crosstalk.yaml to use', cls: 'warn' };
+    if (referenced) return { label: 'in crosstalk.yaml · binary not on PATH', cls: 'warn' };
+    return { label: 'not installed', cls: 'dim' };
   }
+  const rows = allClis.length === 0
+    ? '<p class="empty">No supported agent CLIs found.</p>'
+    : allClis.map(cli => {
+        const s = statusFor(cli);
+        return `<div class="kv"><span class="key">${escapeHtml(cli)}</span><span class="val ${s.cls}">${s.label}</span></div>`;
+      }).join('');
+  const cta = d.claimed.length === 0
+    ? '<section class="card" style="border-left:3px solid #d29922"><h3 style="color:#d29922">Nothing connected yet</h3><p class="sub" style="margin-bottom:0">Run the guided setup to wire one of these up — Crosstalk writes the config and claims it live. <a href="/welcome"><strong>Set up an agent →</strong></a></p></section>'
+    : '';
   const body = `
+${cta}
 <section class="card">
-  <h3>Installed agent CLIs</h3>
-  <p class="sub">CLI binaries crosstalk knows how to PTY-wrap, detected on this engine's PATH.</p>
-  ${chips(d.installed, d.claimed, 'No supported agent CLIs found on PATH.')}
-</section>
-
-<section class="card">
-  <h3>Referenced in data/crosstalk.yaml</h3>
-  <p class="sub">CLIs that have at least one model entry in this transport's registry (whether claimed or not).</p>
-  ${chips(d.yamlReferenced, d.claimed, 'No model entries reference any known agent CLI yet.')}
-</section>
-
-<section class="card">
-  <h3>Claimed by this dispatcher</h3>
-  <p class="sub">CLIs with at least one entry whose binary was on PATH at dispatcher startup. Restart after installing a new CLI to claim its models.</p>
-  ${chips(d.claimed, d.claimed, 'No CLIs claimed yet — restart the engine after installing.')}
-</section>
-
-<section class="card">
-  <h3>Supported (catalog)</h3>
-  <p class="sub">The full set of agent CLIs crosstalk has built-in support for.</p>
-  ${chips(d.known, d.installed, '')}
+  <h3>Agent CLIs</h3>
+  <p class="sub">Every agent CLI crosstalk supports and its status on this engine. The <a href="/welcome">guided setup</a> wires one up live; to do it by hand, add a model entry under <code>providers:</code> in <code>data/crosstalk.yaml</code> and restart the engine.</p>
+  ${rows}
 </section>
 `;
   return page({

package/src/web/chat-page.ts

@@ -155,7 +155,7 @@ export function chatPage(d: ChatPageData): string {
 
 <section class="card picker-card">
   <h3>Interactive chat</h3>
-  <p class="sub">Spawns a fresh agent process on the host attached to your browser via WebSocket. Close the tab, hit the back arrow, or type <code>/exit</code> to terminate gracefully. Hit the red <code>×</code> in the topbar for an immediate SIGKILL when an agent is wedged. Async-by-design: no persistent sessions — for durable work, use the orch bus.</p>
+  <p class="sub">Opens a live terminal session with an agent, right in your browser. Type to interact; close the tab or type <code>/exit</code> to end it. Sessions aren't saved — for work you want to keep, send a message on a channel and let the dispatcher reply. (To force-stop a stuck agent, the red <code>×</code> in the top bar kills it immediately.)</p>
 
   <div class="pick-row">
     <label for="chat-agent">agent</label>

package/src/web/chat-pty.ts

@@ -17,7 +17,7 @@
 //
 // Async-by-design contract: NO persistent session. Each WS attach
 // spawns a fresh agent. There's no detach + reattach. If you want
-// durable state, send messages through the orch bus.
+// durable state, send messages on a channel (the dispatcher replies).
 
 import type { Server as HttpServer } from 'http';
 import type { Duplex } from 'stream';

package/src/web/dashboard.ts

@@ -29,13 +29,46 @@ export function dashboardPage(d: DashboardData): string {
   const namedChannels = d.channels.filter(c => c.name).map(c => c.name as string);
   const cursorShort = d.cursor ? d.cursor.slice(0, 8) + '…' : '—';
 
+  // Plain-language status banner so the first thing a newcomer reads is
+  // "what state am I in / what do I do next", not raw telemetry. Derived
+  // entirely from existing fields — no new backend.
+  const claimed = d.claimedModels.length;
+  const pendingTotal = d.pendingWork.reduce((sum, p) => sum + p.count, 0);
+  const hbStale = hbAge === null || hbAge >= 300_000;
+  let stColor: string, stLabel: string, stHint: string;
+  if (hbStale) {
+    stColor = '#f85149';
+    stLabel = 'Dispatcher not running';
+    stHint = 'No recent heartbeat — the engine isn\'t processing the bus. Start it with <code>crosstalk server start</code>.';
+  } else if (claimed === 0) {
+    stColor = '#d29922';
+    stLabel = 'No agents connected yet';
+    stHint = 'Connect your first agent in a guided setup — Crosstalk detects your installed CLIs and wires one up live. <a href="/welcome"><strong>Set up an agent →</strong></a>';
+  } else if (d.channels.length === 0) {
+    stColor = '#7ee787';
+    stLabel = `Ready · ${claimed} agent${claimed === 1 ? '' : 's'} connected`;
+    stHint = 'Create a channel to start a conversation, or open an interactive <a href="/chat">Chat</a>.';
+  } else {
+    stColor = '#7ee787';
+    stLabel = `Live · ${claimed} agent${claimed === 1 ? '' : 's'}, ${d.channels.length} channel${d.channels.length === 1 ? '' : 's'}`;
+    stHint = pendingTotal > 0
+      ? `${pendingTotal} message${pendingTotal === 1 ? '' : 's'} awaiting a reply — the dispatcher picks them up on its next tick.`
+      : 'Every message on the bus has a reply.';
+  }
+
   const body = `
+<section class="card" style="border-left:3px solid ${stColor}">
+  <h3 style="color:${stColor}">${escapeHtml(stLabel)}</h3>
+  <p class="sub" style="margin-bottom:0">${stHint}</p>
+</section>
+
 <div class="grid cols-2">
   <section class="card">
     <h3>Engine</h3>
     <div class="kv"><span class="key">alias</span><span class="val brand">${escapeHtml(d.alias)}</span></div>
     <div class="kv"><span class="key">version</span><span class="val">${escapeHtml(d.version)}</span></div>
-    <div class="kv"><span class="key">transport</span><span class="val">${escapeHtml(d.transportKind)}<span class="dim"> · ${escapeHtml(d.transportRoot)}</span></span></div>
+    <div class="kv"><span class="key">transport</span><span class="val">${escapeHtml(d.transportKind)}</span></div>
+    <div style="font-size:11px;color:#7a7f87;word-break:break-all;margin:-2px 0 10px">${escapeHtml(d.transportRoot)}</div>
     <div class="kv"><span class="key">cursor</span><span class="val">${escapeHtml(cursorShort)}</span></div>
   </section>
 

package/src/web/layout.ts

@@ -154,6 +154,15 @@ function commonStyles(): string {
   .toast.show{opacity:1;transform:translateX(-50%) translateY(0)}
   .toast.ok{color:#7ee787;border-color:#1f4528}
   .toast.err{color:#f85149;border-color:#4a2329}
+  /* Persistent sidebar on wide screens: the drawer is always open and the
+     content is inset to the right of it, so every nav item is visible
+     without opening the hamburger. Phones keep the slide-in drawer. */
+  @media (min-width:1024px){
+    body{margin-left:300px;max-width:1180px}
+    #nav-drawer{left:0;transition:none;box-shadow:none}
+    #nav-backdrop{display:none}
+    #nav-toggle{display:none}
+  }
   `;
 }
 

package/src/web/stubs.ts

@@ -475,8 +475,8 @@ export function settingsPage(d: SettingsPageData): string {
     host: d.host, alias: d.alias, activeNav: 'settings', pageTitle: 'Settings',
     body: `
 <section class="card">
-  <h3>Engine settings <span class="chip">read-only — backlog</span></h3>
-  <p class="sub">Snapshot of the running engine. Editable settings are on the backlog — for now, restart the engine with different flags / env vars.</p>
+  <h3>Engine settings</h3>
+  <p class="sub">The running engine's configuration. Settings come from <code>data/crosstalk.yaml</code>, CLI flags, and environment variables — edit those and restart the engine to change them. This page reflects what's currently live.</p>
   <div class="kv"><span class="key">alias</span><span class="val brand">${escapeHtml(d.alias)}</span></div>
   <div class="kv"><span class="key">version</span><span class="val">${escapeHtml(d.version)}</span></div>
   <div class="kv"><span class="key">transport root</span><span class="val dim" style="font-size:11px">${escapeHtml(d.transportRoot)}</span></div>
@@ -497,7 +497,7 @@ export function aboutPage(opts: CommonOpts & { version: string; transportRoot: s
     body: `
 <section class="card">
   <h3>Crosstalk</h3>
-  <p class="sub">Async git-backed message bus + dispatcher for AI agent CLIs. Sibling product to <a href="https://github.com/cordfuse/llmux">@cordfuse/llmux</a> (interactive tmux-based session mux).</p>
+  <p class="sub">Async message bus + dispatcher for AI agent CLIs, carried by git or a plain (incl. shared) filesystem. Sibling product to <a href="https://github.com/cordfuse/llmux">@cordfuse/llmux</a> (interactive tmux-based session mux).</p>
   <div class="kv"><span class="key">engine version</span><span class="val brand">${escapeHtml(opts.version)}</span></div>
   <div class="kv"><span class="key">alias</span><span class="val">${escapeHtml(opts.alias)}</span></div>
   <div class="kv"><span class="key">host</span><span class="val">${escapeHtml(opts.host)}</span></div>

package/src/web/wizard.ts

@@ -0,0 +1,172 @@
+// wizard.ts — first-run onboarding, served at GET /welcome and linked from
+// the dashboard when no agent is claimed yet. Three steps:
+//   1. Connect an agent  — POST /api/onboarding/connect (writes crosstalk.yaml
+//      + optional key, SIGHUPs the dispatcher so the model is claimed live).
+//   2. Create a channel  — POST /channels.
+//   3. Send a message    — POST /messages, then hand off to the channel view
+//      where the dispatcher's reply lands.
+//
+// The client JS builds DOM with string concatenation (no client-side template
+// literals) so it nests cleanly inside this module's template string.
+
+import { page, escapeHtml, TOAST_HELPER } from './layout.js';
+
+export interface WizardPageData {
+  host: string;
+  alias: string;
+}
+
+export function wizardPage(d: WizardPageData): string {
+  const body = `
+<section class="card">
+  <h3>Welcome to Crosstalk</h3>
+  <p class="sub">Crosstalk is a message bus where AI agent CLIs talk to each other and to you. Three quick steps to your first conversation.</p>
+  <div class="wiz-steps">
+    <span class="wiz-step active" data-step="1">1 · Connect an agent</span>
+    <span class="wiz-step" data-step="2">2 · Create a channel</span>
+    <span class="wiz-step" data-step="3">3 · Send a message</span>
+  </div>
+</section>
+
+<section class="card wiz-panel" id="panel-1">
+  <h3>Connect an agent</h3>
+  <p class="sub">These agent CLIs are installed on this engine. Pick one — Crosstalk writes the config and claims it live, no restart.</p>
+  <div id="agent-list"><p class="empty">Detecting installed agents…</p></div>
+</section>
+
+<section class="card wiz-panel" id="panel-2" style="display:none">
+  <h3>Create your first channel</h3>
+  <p class="sub">A channel is a conversation thread. Name it anything lowercase (e.g. <code>general</code>).</p>
+  <div class="field"><label for="ch-name">channel name</label><input id="ch-name" value="general" autocomplete="off"></div>
+  <div class="actions"><button id="ch-back" type="button">← back</button><button class="primary" id="ch-create" type="button">Create channel</button></div>
+</section>
+
+<section class="card wiz-panel" id="panel-3" style="display:none">
+  <h3>Send your first message</h3>
+  <p class="sub">Addressed to <span id="m-model" class="chip brand"></span> on <span id="m-channel" class="chip"></span>. The dispatcher delivers the reply to the channel.</p>
+  <div class="field"><label for="m-body">message</label><textarea id="m-body">Say hello and tell me one thing you can help with.</textarea></div>
+  <div class="actions"><button id="m-back" type="button">← back</button><button class="primary" id="m-send" type="button">Send message</button></div>
+</section>
+
+<section class="card wiz-panel" id="panel-done" style="display:none">
+  <h3>You're set up</h3>
+  <p class="sub">Your message is on the bus. Open the channel to watch your agent reply.</p>
+  <div class="actions"><a id="done-link" class="chip brand" href="/">View the conversation →</a></div>
+</section>
+`;
+
+  const js = `
+${TOAST_HELPER}
+var state = { model: null, channel: null };
+function show(step){
+  var panels = document.querySelectorAll('.wiz-panel');
+  for (var i=0;i<panels.length;i++) panels[i].style.display = 'none';
+  document.getElementById('panel-'+step).style.display = '';
+  var steps = document.querySelectorAll('.wiz-step');
+  for (var j=0;j<steps.length;j++){
+    var n = steps[j].getAttribute('data-step');
+    steps[j].classList.toggle('active', String(step) === 'done' || n <= String(step));
+  }
+}
+function esc(s){ var d = document.createElement('div'); d.textContent = s == null ? '' : String(s); return d.innerHTML; }
+async function loadAgents(){
+  var list = document.getElementById('agent-list');
+  try{
+    var r = await fetch('/api/onboarding/agents');
+    var data = await r.json();
+    var installed = (data.agents || []).filter(function(a){ return a.installed; });
+    if (!installed.length){ list.innerHTML = '<p class="empty">No supported agent CLIs found on this engine PATH. Install one (claude, codex, gemini, …) and reload.</p>'; return; }
+    list.innerHTML = installed.map(function(a){
+      var badge = a.claimed ? '<span class="chip" style="color:#7ee787">connected</span>' : '';
+      var key = (a.needsKey && !a.claimed) ? '<input class="agent-key" placeholder="API key — optional, blank if already logged in" style="margin-top:8px" autocomplete="off">' : '';
+      // Already claimed (revisit, or claimed outside the wizard): nothing to
+      // POST — just let the row advance the wizard with this model, rather
+      // than stranding the user behind a disabled "done" button.
+      var btn = '<button class="primary use-btn" type="button">' + (a.claimed ? 'Continue →' : 'Use this') + '</button>';
+      return '<div class="agent-row" data-cli="' + esc(a.cli) + '" data-qualified="' + esc(a.provider + '/' + a.model) + '" data-claimed="' + (a.claimed ? '1' : '0') + '">' +
+        '<div style="flex:1 1 auto;min-width:0">' +
+          '<div><span class="chip brand">' + esc(a.label) + '</span> ' + badge + '</div>' + key +
+          '<div style="font-size:11px;color:#7a7f87;margin-top:4px">' + esc(a.keyHint) + '</div>' +
+        '</div>' + btn + '</div>';
+    }).join('');
+    var rows = list.querySelectorAll('.agent-row');
+    for (var i=0;i<rows.length;i++){
+      (function(row){
+        row.querySelector('.use-btn').addEventListener('click', function(){
+          if (row.getAttribute('data-claimed') === '1'){
+            state.model = row.getAttribute('data-qualified');
+            document.getElementById('m-model').textContent = state.model;
+            show(2);
+          } else {
+            connect(row);
+          }
+        });
+      })(rows[i]);
+    }
+  }catch(e){ list.innerHTML = '<p class="empty">Failed to load agents: ' + esc(e.message) + '</p>'; }
+}
+async function connect(row){
+  var cli = row.getAttribute('data-cli');
+  var keyEl = row.querySelector('.agent-key');
+  var btn = row.querySelector('.use-btn');
+  btn.disabled = true; btn.textContent = 'Connecting…';
+  try{
+    var r = await fetch('/api/onboarding/connect', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ cli: cli, apiKey: keyEl ? keyEl.value : undefined }) });
+    var data = await r.json();
+    if (!r.ok) throw new Error(data.error || 'connect failed');
+    state.model = data.qualified;
+    document.getElementById('m-model').textContent = data.qualified;
+    showToast(data.qualified + ' connected', 'ok');
+    show(2);
+  }catch(e){ showToast(e.message, 'err'); btn.disabled = false; btn.textContent = 'Use this'; }
+}
+document.getElementById('ch-back').addEventListener('click', function(){ show(1); });
+document.getElementById('m-back').addEventListener('click', function(){ show(2); });
+async function createChannel(){
+  var name = document.getElementById('ch-name').value.trim();
+  if (!name){ showToast('channel name required', 'err'); return; }
+  try{
+    var r = await fetch('/channels', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ name: name }) });
+    var data = await r.json();
+    if (!r.ok) throw new Error(data.error || 'create failed');
+    state.channel = name;
+    document.getElementById('m-channel').textContent = name;
+    show(3);
+  }catch(e){ showToast(e.message, 'err'); }
+}
+document.getElementById('ch-create').addEventListener('click', createChannel);
+document.getElementById('ch-name').addEventListener('keydown', function(e){ if (e.key === 'Enter') { e.preventDefault(); createChannel(); } });
+document.getElementById('m-send').addEventListener('click', async function(){
+  var text = document.getElementById('m-body').value.trim();
+  if (!text){ showToast('message required', 'err'); return; }
+  var btn = document.getElementById('m-send'); btn.disabled = true; btn.textContent = 'Sending…';
+  try{
+    var r = await fetch('/messages', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ type:'primitive', channel: state.channel, to: state.model, body: text }) });
+    var data = await r.json();
+    if (!r.ok) throw new Error(data.error || 'send failed');
+    document.getElementById('done-link').href = '/c/' + encodeURIComponent(state.channel);
+    show('done');
+  }catch(e){ showToast(e.message, 'err'); btn.disabled = false; btn.textContent = 'Send message'; }
+});
+loadAgents();
+`;
+
+  const css = `
+  .wiz-steps{display:flex;gap:8px;flex-wrap:wrap;margin-top:10px}
+  .wiz-step{font-size:11px;color:#7a7f87;border:1px solid #1f2329;border-radius:12px;padding:4px 10px}
+  .wiz-step.active{color:#7cc4ff;border-color:#2d4a66}
+  .agent-row{display:flex;gap:12px;align-items:flex-start;padding:12px 0;border-bottom:1px solid #1f2329}
+  .agent-row:last-child{border-bottom:none}
+  .agent-key{width:100%}
+  `;
+
+  return page({
+    title: `crosstalk on ${escapeHtml(d.host)} · Welcome`,
+    host: d.host,
+    alias: d.alias,
+    pageTitle: 'Welcome',
+    extraCss: css,
+    body,
+    inlineScript: js,
+  });
+}

package/src/web/workflows.ts

@@ -100,7 +100,7 @@ export function workflowsListPage(d: WorkflowsListData): string {
   <div id="compose-step-prompt">
     <div class="field">
       <label for="cw-prompt">prompt</label>
-      <textarea id="cw-prompt" rows="4" placeholder="e.g. compare how claude, codex, and gemini would refactor src/auth/users.ts to use bun's built-in crypto instead of node:crypto"></textarea>
+      <textarea id="cw-prompt" rows="4" placeholder="e.g. ask claude, codex, and gemini to each review README.md for unclear setup steps, then synthesize their notes into one list"></textarea>
     </div>
     <div class="field">
       <label for="cw-compiler">compiler agent</label>