@xdelivered/emberflow 0.2.0 → 0.5.0

package/src/components/AgentStream.tsx

@@ -0,0 +1,303 @@
+import { useMemo, useState } from 'react';
+import { ChevronRightIcon, TerminalIcon, ZapIcon } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import type { AgentEvent } from '../store/agentClient';
+import { renderAgentMarkdown } from './agentMarkdown';
+
+/** A command's status → a small glyph colour. */
+const cmdDot: Record<string, string> = {
+  in_progress: 'bg-highlight animate-pulse',
+  completed: 'bg-success/70',
+  failed: 'bg-destructive',
+};
+
+/** The `emberflow` CLI operation commands the agent uses (run/inspect/delete). */
+const EMBERFLOW_OPS = [
+  'run', 'get-workflow', 'list-workflows', 'list-nodes', 'node-schema', 'list-environments',
+  'create', 'delete', 'rename', 'validate', 'publish', 'save',
+];
+
+/** If a shell command invokes the emberflow CLI bin with an operation command,
+ *  pull out the operation + its target id so it can render as a distinct step. */
+function parseEmberflowOp(command?: string): { op: string; target?: string } | null {
+  if (!command || !/emberflow\.mjs\b/.test(command)) return null;
+  const after = command.split(/emberflow\.mjs\b/)[1] ?? '';
+  const toks = after.trim().split(/\s+/).filter(Boolean);
+  const op = toks.find((t) => EMBERFLOW_OPS.includes(t));
+  if (!op) return null;
+  const target = toks.slice(toks.indexOf(op) + 1).find((t) => !t.startsWith('-'));
+  return { op, target };
+}
+
+/**
+ * A run of consecutive shell commands, collapsed to a single quiet line
+ * ("Ran N commands") that expands to the individual commands + their output.
+ * A failed command in the group tints the header destructive but stays
+ * COLLAPSED — the failure signal is visible, the raw output dump is a click
+ * away. This is the big de-noiser: a single edit can run 30 inspection
+ * commands — nobody wants 30 rows, they want the reasoning with the
+ * mechanics tucked underneath.
+ */
+function CommandGroup({ commands }: { commands: AgentEvent[] }) {
+  const anyFailed = commands.some((c) => c.commandStatus === 'failed');
+  const [open, setOpen] = useState(false);
+  const running = commands.some((c) => c.commandStatus === 'in_progress');
+  const label = commands.length === 1 ? '1 command' : `${commands.length} commands`;
+  return (
+    <div className="my-0.5">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className="group flex w-full items-center gap-1.5 rounded px-1 py-0.5 text-left transition-colors hover:bg-secondary/50"
+      >
+        <ChevronRightIcon
+          className={cn('size-3 shrink-0 text-muted-foreground/50 transition-transform', open && 'rotate-90')}
+        />
+        <span
+          className={cn(
+            'size-1.5 shrink-0 rounded-full',
+            running ? cmdDot.in_progress : anyFailed ? cmdDot.failed : cmdDot.completed,
+          )}
+        />
+        <span className={cn('text-[11px]', anyFailed ? 'text-destructive/90' : 'text-muted-foreground/70')}>
+          {running ? 'Running' : 'Ran'} {label}
+        </span>
+      </button>
+      {open && (
+        <div className="ml-[18px] mt-0.5 space-y-0.5 border-l border-border/50 pl-2">
+          {commands.map((c, k) => (
+            <div key={k}>
+              <div className="flex items-center gap-1.5">
+                <span className={cn('size-1 shrink-0 rounded-full', cmdDot[c.commandStatus ?? 'in_progress'])} />
+                <span className="min-w-0 truncate font-mono text-[10.5px] text-muted-foreground/80">{c.command}</span>
+                {c.commandStatus === 'failed' && c.exitCode != null && (
+                  <span className="ml-auto shrink-0 font-mono text-[9px] text-destructive">exit {c.exitCode}</span>
+                )}
+              </div>
+              {(c.commandStatus === 'failed' || open) && c.output && c.output.trim() && (
+                <pre className="mt-0.5 ml-3 max-h-32 overflow-auto rounded border border-border/50 bg-background/40 p-1.5 font-mono text-[10px] leading-relaxed whitespace-pre-wrap text-muted-foreground/70">
+                  {c.output}
+                </pre>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** An MCP tool call the agent made against the runner (run/list/delete/etc.) —
+ *  visually distinct from a shell command (MCP-blue, a "MCP" chip), expandable
+ *  to its result. This is the operational channel: files for edits, MCP for
+ *  actions like running the operation or deleting it. */
+function McpCall({ e }: { e: AgentEvent }) {
+  const [open, setOpen] = useState(false);
+  const status = e.mcpStatus ?? 'completed';
+  const failed = status === 'failed';
+  const running = status === 'in_progress';
+  return (
+    <div className="my-0.5">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className="group flex w-full items-center gap-1.5 rounded px-1 py-0.5 text-left transition-colors hover:bg-secondary/50"
+      >
+        <ChevronRightIcon
+          className={cn('size-3 shrink-0 text-muted-foreground/50 transition-transform', open && 'rotate-90')}
+        />
+        <span className={cn('size-1.5 shrink-0 rounded-full', running ? 'animate-pulse bg-highlight' : failed ? 'bg-destructive' : 'bg-[#8fb8d8]')} />
+        <ZapIcon className="size-3 shrink-0 text-[#8fb8d8]" />
+        <span className="shrink-0 rounded border border-[#8fb8d8]/40 px-1 font-mono text-[8.5px] uppercase tracking-wide text-[#8fb8d8]">
+          MCP
+        </span>
+        <span className={cn('min-w-0 truncate font-mono text-[11px]', failed ? 'text-destructive/90' : 'text-foreground/85')}>
+          {e.mcpServer}·{e.mcpTool}
+        </span>
+        <span className="ml-auto shrink-0 text-[9.5px] text-muted-foreground/60">{running ? '…' : status}</span>
+      </button>
+      {open && e.output && e.output.trim() && (
+        <pre className="ml-[18px] mt-0.5 max-h-40 overflow-auto rounded border border-border/50 bg-background/40 p-1.5 font-mono text-[10px] leading-relaxed whitespace-pre-wrap text-muted-foreground/75">
+          {e.output}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+/** An `emberflow` CLI operation the agent ran (run/inspect/delete against the
+ *  live runner) — surfaced as a distinct operation step, expandable to its
+ *  output. This is the agent's operational channel: files for edits, CLI ops
+ *  for running/inspecting/removing. */
+function OpCall({ op, target, e }: { op: string; target?: string; e: AgentEvent }) {
+  const [open, setOpen] = useState(false);
+  const status = e.commandStatus ?? 'completed';
+  const failed = status === 'failed' || (e.exitCode != null && e.exitCode !== 0);
+  const running = status === 'in_progress';
+  return (
+    <div className="my-0.5">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className="group flex w-full items-center gap-1.5 rounded px-1 py-0.5 text-left transition-colors hover:bg-secondary/50"
+      >
+        <ChevronRightIcon className={cn('size-3 shrink-0 text-muted-foreground/50 transition-transform', open && 'rotate-90')} />
+        <span className={cn('size-1.5 shrink-0 rounded-full', running ? 'animate-pulse bg-highlight' : failed ? 'bg-destructive' : 'bg-[#8fb8d8]')} />
+        <ZapIcon className="size-3 shrink-0 text-[#8fb8d8]" />
+        <span className="shrink-0 rounded border border-[#8fb8d8]/40 px-1 font-mono text-[8.5px] uppercase tracking-wide text-[#8fb8d8]">
+          OP
+        </span>
+        <span className={cn('min-w-0 truncate font-mono text-[11px]', failed ? 'text-destructive/90' : 'text-foreground/85')}>
+          {op}{target ? ` · ${target}` : ''}
+        </span>
+        <span className="ml-auto shrink-0 text-[9.5px] text-muted-foreground/60">{running ? '…' : failed ? 'failed' : 'ok'}</span>
+      </button>
+      {open && e.output && e.output.trim() && (
+        <pre className="ml-[18px] mt-0.5 max-h-40 overflow-auto rounded border border-border/50 bg-background/40 p-1.5 font-mono text-[10px] leading-relaxed whitespace-pre-wrap text-muted-foreground/75">
+          {e.output}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+type Block =
+  | { kind: 'message' | 'error' | 'approval' | 'mcp'; e: AgentEvent }
+  | { kind: 'op'; e: AgentEvent; op: string; target?: string }
+  | { kind: 'commands'; commands: AgentEvent[] };
+
+/**
+ * Fold a raw agent event stream into display blocks. Reasoning prose and error
+ * lines stand alone; consecutive shell commands collapse into one CommandGroup;
+ * emberflow CLI ops + MCP calls render as their own steps; `started`/`done` are
+ * structural and `⚠` diagnostics are folded into a noise count. Exported so both
+ * the console and the component test can assert the partitioning directly.
+ */
+export function partitionAgentEvents(events: AgentEvent[]): { blocks: Block[]; noiseCount: number } {
+  const blocks: Block[] = [];
+  let noiseCount = 0;
+  let group: AgentEvent[] | null = null;
+  const flush = (): void => {
+    if (group && group.length) blocks.push({ kind: 'commands', commands: group });
+    group = null;
+  };
+  for (const e of events) {
+    // An `emberflow` CLI operation (run/inspect/delete) — surface it as a
+    // distinct "operation" step, not a generic shell command.
+    const opInfo = e.type === 'command' ? parseEmberflowOp(e.command) : null;
+    if (e.type === 'command' && opInfo) {
+      flush();
+      const last = blocks[blocks.length - 1];
+      if (last && last.kind === 'op' && last.e.command === e.command && last.e.commandStatus === 'in_progress') {
+        last.e = e;
+      } else {
+        blocks.push({ kind: 'op', e, op: opInfo.op, target: opInfo.target });
+      }
+      continue;
+    }
+    if (e.type === 'command') {
+      group ??= [];
+      // Each command streams as a start (in_progress) then a complete
+      // (completed/failed) event with the same text — collapse the pair into
+      // one entry carrying the final status + output, so counts are accurate.
+      const last = group[group.length - 1];
+      if (last && last.command === e.command && last.commandStatus === 'in_progress') {
+        group[group.length - 1] = e;
+      } else {
+        group.push(e);
+      }
+      continue;
+    }
+    flush();
+    if (e.type === 'mcp') {
+      // MCP calls stream in_progress → completed for the same tool; collapse
+      // the pair so the completed status/result replaces the pending one.
+      const last = blocks[blocks.length - 1];
+      if (last && last.kind === 'mcp' && last.e.mcpTool === e.mcpTool && last.e.mcpStatus === 'in_progress') {
+        last.e = e;
+      } else {
+        blocks.push({ kind: 'mcp', e });
+      }
+      continue;
+    }
+    if (e.type === 'started' || e.type === 'done') continue;
+    if (e.type === 'message' && e.text?.startsWith('⚠')) {
+      noiseCount += 1;
+      continue;
+    }
+    if (e.type === 'message') blocks.push({ kind: 'message', e });
+    else if (e.type === 'error') blocks.push({ kind: 'error', e });
+    else if (e.type === 'approval-request') blocks.push({ kind: 'approval', e });
+  }
+  flush();
+  return { blocks, noiseCount };
+}
+
+/**
+ * Presentational render of a coding-agent event stream: the agent's reasoning
+ * as comfortable markdown prose, shell commands collapsed to quiet expandable
+ * one-liners, emberflow CLI ops + MCP calls as their own steps, error/approval
+ * rows, and background `⚠` diagnostics tucked into a count. Pure over its props
+ * — the AgentConsole (docked panel) and the WelcomeDialog (guided setup) both
+ * embed it. `running` drives the "Thinking…"/"Working…" live indicators.
+ */
+export function AgentStream({ events, running }: { events: AgentEvent[]; running: boolean }) {
+  // Partition the raw stream into what's worth showing vs. noise. The agent's
+  // ⚠ diagnostics (an MCP server failing to auth, a hook firing) are real but
+  // not what the user is watching for — collapse them to a count.
+  const { blocks, noiseCount } = useMemo(() => partitionAgentEvents(events), [events]);
+
+  return (
+    <>
+      {blocks.length === 0 && running && (
+        <div className="flex items-center gap-2 text-[12px] text-muted-foreground/70">
+          <span className="size-1.5 animate-pulse rounded-full bg-highlight" />
+          Thinking…
+        </div>
+      )}
+      {blocks.map((b, i) => {
+        if (b.kind === 'commands') return <CommandGroup key={i} commands={b.commands} />;
+        if (b.kind === 'op') return <OpCall key={i} op={b.op} target={b.target} e={b.e} />;
+        if (b.kind === 'mcp') return <McpCall key={i} e={b.e} />;
+        if (b.kind === 'message') {
+          // The reasoning: the star of the panel — comfortable, readable prose.
+          // Render the markdown subset (bold/code/lists/headings). The renderer
+          // owns block structure, so whitespace-pre-wrap stays OFF here.
+          return (
+            <div key={i} className="space-y-1.5">
+              {renderAgentMarkdown(b.e.text ?? '')}
+            </div>
+          );
+        }
+        if (b.kind === 'error') {
+          return (
+            <p key={i} className="text-[12px] leading-relaxed text-destructive">
+              {b.e.text ?? 'The agent run failed.'}
+            </p>
+          );
+        }
+        return (
+          <p key={i} className="text-[12px] text-yellow-500">
+            Approval requested{b.e.text ? `: ${b.e.text}` : ''}
+          </p>
+        );
+      })}
+
+      {/* Live working indicator once there's content but the run's still going. */}
+      {running && blocks.length > 0 && (
+        <div className="flex items-center gap-2 pt-1 text-[11px] text-muted-foreground/60">
+          <span className="size-1.5 animate-pulse rounded-full bg-highlight" />
+          Working…
+        </div>
+      )}
+
+      {/* Background diagnostics, tucked away — acknowledged, not shouting. */}
+      {noiseCount > 0 && (
+        <div className="flex items-center gap-1.5 pt-1 text-[10.5px] text-muted-foreground/45">
+          <TerminalIcon className="size-3" />
+          {noiseCount} background {noiseCount === 1 ? 'diagnostic' : 'diagnostics'} hidden
+        </div>
+      )}
+    </>
+  );
+}

package/src/components/CreateModal.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { FolderIcon, SparklesIcon } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -6,8 +6,12 @@ import { Command, CommandEmpty, CommandGroup, CommandItem, CommandList } from '@
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { Dialog, DialogContent, DialogTitle } from '@/components/ui/dialog';
 import { useBuilderStore } from '../store/builderStore';
+import type { CreateModalState } from '../store/builderStore';
+import { buildApiTree, flattenLocations } from '../store/apiTree';
 import { cn } from '@/lib/utils';
 
+export type { CreateModalState };
+
 /** lowercase, spaces -> '-', strip anything not URL-safe (matches builderStore.slug). */
 function slug(name: string): string {
   return name.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
@@ -39,11 +43,6 @@ function deriveOperation(goal: string, location: string): { name: string; method
   return { name, method, httpPath: `/${location}/${opSlug}` };
 }
 
-/** Configures the two entry points that share this modal. */
-export type CreateModalState =
-  | { mode: 'api' }
-  | { mode: 'operation'; location?: string }; // location preset scopes it to an API (from the + hover)
-
 const OPERATION_EXAMPLES = [
   'List overdue invoices for a customer',
   'Charge a saved card and return the receipt',
@@ -55,6 +54,39 @@ const API_EXAMPLES = [
   'Start a background export job',
 ];
 
+/**
+ * Store-connected host for the ONE create modal — mounted once in App so any
+ * surface (the Sidebar's New API / + buttons, the canvas empty state) opens it
+ * via `setCreateModal`, sidebar open or not. Locations for the operation-mode
+ * picker are derived from the live workflow list.
+ */
+export function CreateModalHost() {
+  const workflows = useBuilderStore((s) => s.workflows);
+  const state = useBuilderStore((s) => s.createModal);
+  const setCreateModal = useBuilderStore((s) => s.setCreateModal);
+  const locations = useMemo(
+    () =>
+      flattenLocations(
+        buildApiTree(
+          workflows.map((w) => ({
+            id: w.id,
+            name: w.name,
+            path: w.path ?? `default/${w.id}`,
+            http: w.http,
+          })),
+        ),
+      ),
+    [workflows],
+  );
+  return (
+    <CreateModal
+      state={state}
+      onOpenChange={(open) => !open && setCreateModal(null)}
+      locations={locations}
+    />
+  );
+}
+
 /**
  * The agentic create surface — one centered modal for both "New API" (name +
  * its first operation) and "New operation" (scoped to an API, or with a
@@ -82,18 +114,20 @@ export function CreateModal({
   const open = state !== null;
   const mode = state?.mode ?? 'operation';
   const presetLocation = state?.mode === 'operation' ? state.location : undefined;
+  const initialGoal = state?.mode === 'api' ? state.initialGoal : undefined;
   const examples = mode === 'api' ? API_EXAMPLES : OPERATION_EXAMPLES;
 
-  // Reset fields each time the modal opens; seed the location from the preset.
+  // Reset fields each time the modal opens; seed the location + goal from the
+  // preset (the goal arrives pre-filled from onboarding's first-build answer).
   useEffect(() => {
     if (!open) return;
     setApiName('');
-    setGoal('');
+    setGoal(initialGoal ?? '');
     setLocation(presetLocation ?? '');
     setLocationPickerOpen(false);
     const t = setTimeout(() => goalRef.current?.focus(), 60);
     return () => clearTimeout(t);
-  }, [open, presetLocation]);
+  }, [open, presetLocation, initialGoal]);
 
   const apiSlug = slug(apiName);
   const targetLocation = mode === 'api' ? apiSlug : location.trim() || 'default';

package/src/components/Dock.tsx

@@ -349,7 +349,7 @@ export function InfraTab() {
   return (
     <InfraPanel
       data={data}
-      onScout={beginInfrastructureScout}
+      onScout={() => beginInfrastructureScout()}
       scouting={agentRunStatus === 'running'}
       canScout={hasAgent}
       canScoutReason={NO_AGENT_REASON}

package/src/components/EmptyState.test.tsx

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { EmptyState } from './EmptyState';
+import type { SetupStatus } from '../store/setupClient';
+
+/** A project that finished onboarding but still has only the hello example. */
+const ONLY_HELLO: SetupStatus = {
+  agents: [{ kind: 'claude', version: '2.1.0' }],
+  git: { repo: true },
+  environments: { configured: true, count: 2, protectedCount: 1, anyAuthConfigured: true },
+  skills: { claude: true, codex: false },
+  language: 'typescript',
+  ops: { count: 1, onlyHello: true },
+  servingMode: 'mock',
+  infrastructure: { present: true, itemCount: 2 },
+};
+
+const html = (status: SetupStatus | null, dismissed = false): string =>
+  renderToStaticMarkup(
+    <EmptyState status={status} dismissed={dismissed} onCreate={() => {}} onExplore={() => {}} />,
+  );
+
+describe('EmptyState', () => {
+  it('renders when the project has only the hello example and is not dismissed', () => {
+    const out = html(ONLY_HELLO);
+    expect(out).toContain('Build your first API');
+    expect(out).toContain('Describe what you want and the agent builds it');
+    expect(out).toContain('Create your first API');
+    expect(out).toContain('Explore the hello example');
+  });
+
+  it('hidden once dismissed', () => {
+    expect(html(ONLY_HELLO, true)).toBe('');
+  });
+
+  it('hidden once the project has more than the hello op (condition stops matching)', () => {
+    expect(html({ ...ONLY_HELLO, ops: { count: 3, onlyHello: false } })).toBe('');
+  });
+
+  it('hidden with no setup status yet', () => {
+    expect(html(null)).toBe('');
+  });
+
+  it('the template button is disabled and marked coming soon', () => {
+    const out = html(ONLY_HELLO);
+    expect(out).toMatch(/disabled=""[^>]*title="Coming soon"|title="Coming soon"[^>]*disabled=""/);
+    expect(out).toContain('Start from a template');
+  });
+});

package/src/components/EmptyState.tsx

@@ -0,0 +1,61 @@
+import { SparklesIcon } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import type { SetupStatus } from '../store/setupClient';
+
+/** Set once the user takes the "explore the example" path — the empty state
+ *  never returns. Building a second op dismisses it implicitly (onlyHello
+ *  flips false), so no key write is needed on the create path. */
+export const EMPTY_STATE_DISMISSED_KEY = 'emberflow.emptyState.dismissed';
+
+/**
+ * Post-onboarding empty state: a fresh project with only the hello example
+ * shouldn't greet the user with someone else's op. Rendered centered in the
+ * canvas INSTEAD of the runbook (see CenterView) while the project has only
+ * the hello example and the user hasn't dismissed it. Prop-driven — the
+ * component test drives it across states without a live store; CenterView
+ * owns the store wiring and the welcome-dialog gate.
+ */
+export function EmptyState({
+  status,
+  dismissed,
+  onCreate,
+  onExplore,
+}: {
+  status: SetupStatus | null;
+  dismissed: boolean;
+  /** Opens the same New API modal as the sidebar's button (store's createModal). */
+  onCreate: () => void;
+  /** Records the dismissal and opens the hello example. */
+  onExplore: () => void;
+}) {
+  if (!status?.ops.onlyHello || dismissed) return null;
+  return (
+    <div className="flex h-full min-h-0 items-center justify-center p-8">
+      <div className="flex max-w-md flex-col items-center gap-3 text-center">
+        <span className="flex size-9 shrink-0 items-center justify-center rounded-full bg-highlight/15 text-highlight">
+          <SparklesIcon className="size-4" />
+        </span>
+        <h2 className="text-[15px] font-semibold tracking-tight">Build your first API</h2>
+        <p className="text-[13px] leading-relaxed text-muted-foreground">
+          Describe what you want and the agent builds it — or explore the example first.
+        </p>
+        <div className="mt-1 flex items-center gap-2">
+          <Button size="sm" onClick={onCreate}>
+            <SparklesIcon className="size-3.5" />
+            Create your first API
+          </Button>
+          <Button size="sm" variant="outline" disabled title="Coming soon">
+            Start from a template
+          </Button>
+        </div>
+        <button
+          type="button"
+          onClick={onExplore}
+          className="mt-1 text-[11px] text-muted-foreground underline-offset-2 hover:text-foreground hover:underline"
+        >
+          Explore the hello example
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/EnvironmentDialog.tsx

@@ -542,7 +542,10 @@ export function EnvironmentDialog({
         <DialogTitle className="flex items-center gap-2">
           {env.name}
           {env.protected && (
-            <span className="flex items-center gap-1 text-[10.5px] font-normal uppercase tracking-wide text-destructive-foreground/80">
+            <span
+              title="Protected — runs ask for confirmation before touching this environment."
+              className="flex items-center gap-1 text-[10.5px] font-normal uppercase tracking-wide text-destructive-foreground/80"
+            >
               <ShieldIcon className="size-3" /> protected
             </span>
           )}

package/src/components/EnvironmentPicker.tsx

@@ -46,7 +46,9 @@ export function EnvironmentPicker() {
   const offline = environments.length === 0;
   // The unmissable state: writes will execute against a protected environment.
   const live = protectedEnv && !safeMode;
-  const label = selected || 'browser';
+  // Runs are always server-side; with the runner down there is no environment
+  // to point at, so the picker says so plainly rather than naming a fallback.
+  const label = runnerOnline === false ? 'Runner offline' : selected || 'default';
 
   const toggleSafe = () => {
     if (safeMode) {
@@ -174,7 +176,7 @@ export function EnvironmentPicker() {
             ) : (
               <div className="px-2.5 py-3 text-[12px] text-muted-foreground">
                 {runnerOnline === false
-                  ? 'Runner offline — runs execute in the browser as environment "browser".'
+                  ? 'Runner offline — start it with `npx emberflow dev` to run and pick environments.'
                   : 'Loading environments…'}
               </div>
             )
@@ -199,7 +201,10 @@ export function EnvironmentPicker() {
                     {env.protected && <span className="size-1.5 rounded-full bg-destructive" />}
                     <span className="text-[12.5px] font-medium">{env.name}</span>
                     {env.protected && (
-                      <span className="ml-auto text-[10.5px] uppercase tracking-wide text-destructive-foreground/80">
+                      <span
+                        title="Protected — runs ask for confirmation before touching this environment."
+                        className="ml-auto text-[10.5px] uppercase tracking-wide text-destructive-foreground/80"
+                      >
                         protected
                       </span>
                     )}

package/src/components/EnvironmentsDialog.tsx

@@ -98,7 +98,10 @@ export function EnvironmentsDialog({
                       </span>
                     )}
                     {env.protected && (
-                      <span className="text-[10px] uppercase tracking-wide text-destructive-foreground/80">
+                      <span
+                        title="Protected — runs ask for confirmation before touching this environment."
+                        className="text-[10px] uppercase tracking-wide text-destructive-foreground/80"
+                      >
                         protected
                       </span>
                     )}

package/src/components/InfraPanel.tsx

@@ -26,6 +26,25 @@ const KIND_COLOR: Record<InfrastructureKind, string> = {
   other: 'text-muted-foreground',
 };
 
+/**
+ * Plain-words gloss per kind, ≤1 line each. Surfaced (muted) under the card when
+ * `explainKinds` is set — the modal wants to teach what each kind MEANS to the
+ * agent; the Dock tab (dense, familiar) leaves it off. One source of truth so
+ * both renders share the same vocabulary.
+ */
+export const KIND_EXPLANATION: Record<InfrastructureKind, string> = {
+  database: 'A data store the project reads and writes — operations can query it through registered nodes.',
+  'http-api': 'An external service reached over HTTP — operations call it with the named secret.',
+  queue: 'A job queue the project enqueues into or consumes.',
+  cache: 'A fast key/value store for transient or hot data.',
+  email: 'A transactional email provider.',
+  llm: 'A language-model API the project calls.',
+  auth: 'An identity/auth provider or token flow.',
+  framework: "The app's own serving framework — context, not a callable dependency.",
+  storage: 'Object or file storage the project reads and writes.',
+  other: "Infrastructure that doesn't fit the other kinds.",
+};
+
 function KindChip({ kind }: { kind: InfrastructureKind }) {
   return (
     <Badge variant="mono" className="uppercase tracking-wider">
@@ -35,7 +54,7 @@ function KindChip({ kind }: { kind: InfrastructureKind }) {
   );
 }
 
-function InfraCard({ item }: { item: InfrastructureItem }) {
+function InfraCard({ item, explainKinds = false }: { item: InfrastructureItem; explainKinds?: boolean }) {
   return (
     <div className="flex flex-col gap-2 rounded-md border border-border/70 bg-card px-3 py-2.5">
       <div className="flex items-center justify-between gap-2">
@@ -43,6 +62,12 @@ function InfraCard({ item }: { item: InfrastructureItem }) {
         <KindChip kind={item.kind} />
       </div>
 
+      {explainKinds && (
+        <p className="text-[10.5px] leading-snug text-muted-foreground/80">
+          {KIND_EXPLANATION[item.kind] ?? KIND_EXPLANATION.other}
+        </p>
+      )}
+
       {item.evidence.length > 0 && (
         <ul className="flex flex-col gap-0.5">
           {item.evidence.map((e, i) => (
@@ -118,12 +143,15 @@ export function InfraPanel({
   scouting = false,
   canScout = true,
   canScoutReason,
+  explainKinds = false,
 }: {
   data: InfrastructureResponse | null;
   onScout?: () => void;
   scouting?: boolean;
   canScout?: boolean;
   canScoutReason?: string;
+  /** Render the plain-words per-kind gloss under each card (used by the modal). */
+  explainKinds?: boolean;
 }) {
   if (!data || data.present === false) {
     return (
@@ -163,7 +191,7 @@ export function InfraPanel({
       )}
       <div className="grid grid-cols-[repeat(auto-fill,minmax(240px,1fr))] gap-2.5">
         {manifest.items.map((item) => (
-          <InfraCard key={item.id} item={item} />
+          <InfraCard key={item.id} item={item} explainKinds={explainKinds} />
         ))}
       </div>
     </div>