From ce602ad5a98fe409b7ba93c0bdece9f41824afe3 Mon Sep 17 00:00:00 2001
From: Patryk Lewczuk <patryk.lewczuk@hotmail.com>
Date: Sun, 24 May 2026 02:44:30 +0200
Subject: [PATCH 1/2] perf(runner): collapse heartbeat + events hot paths to
 single RPCs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /api/runner/heartbeat and /api/runner/runs/:id/events endpoints were
firing 4 and ~30-60 sequential Postgres statements per call respectively.
Under multi-runner load this saturated the PgBouncer pool, producing the
bimodal 200ms / 10-16s tail latency we hit on dev (and would hit harder
in prod). Both paths now do a single round-trip:

  * runner_heartbeat(p_runner_id, p_status) — one CTE pipeline: bump
    last_heartbeat_at/status + return cancel_job_ids/pause_run_ids.
    Replaces 4 sequential statements.
  * ingest_runner_events(p_run_id, p_workspace_id, p_events jsonb) —
    one set-based insert opens agent_runs rows from step-start, one
    upsert closes them from step-end (needs the new
    agent_runs_run_step_iter_uniq constraint), one insert appends every
    event to agent_run_events, one atomic UPDATE rolls up tokens_used
    + current_step_id on workflow_runs. The tokens_used roll-up is now
    `tokens_used = tokens_used + delta`, fixing a read-modify-write
    race on concurrent batches.

Also drops the duplicate touch_runner_heartbeat from /api/runner/jobs —
the daemon's dedicated heartbeat is the single source of truth now.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../gui/src/app/api/runner/heartbeat/route.ts |  47 ++--
 packages/gui/src/app/api/runner/jobs/route.ts |   8 +-
 .../api/runner/runs/[runId]/events/route.ts   |  98 ++-------
 .../supabase/migrations/0020_runner_perf.sql  | 201 ++++++++++++++++++
 4 files changed, 238 insertions(+), 116 deletions(-)
 create mode 100644 packages/gui/supabase/migrations/0020_runner_perf.sql

diff --git a/packages/gui/src/app/api/runner/heartbeat/route.ts b/packages/gui/src/app/api/runner/heartbeat/route.ts
index fb0ed58..4524346 100644
--- a/packages/gui/src/app/api/runner/heartbeat/route.ts
+++ b/packages/gui/src/app/api/runner/heartbeat/route.ts
@@ -10,12 +10,21 @@ interface HeartbeatBody {
   currentJobIds?: string[];
 }
 
+interface HeartbeatRpcRow {
+  cancel_job_ids: string[] | null;
+  pause_run_ids: string[] | null;
+}
+
 /**
  * POST /api/runner/heartbeat  { status?, currentJobIds? }
  *
  * Refreshes the runner's `last_heartbeat_at`/`status` and tells it which of its
  * jobs/runs the operator has asked to cancel/pause (the runner has no other
  * channel for that).
+ *
+ * Implemented as a single `runner_heartbeat` RPC (migration 0020) — previously
+ * this was four sequential statements, which caused the bimodal 200ms / 10-16s
+ * tail latency we hit at multi-runner scale.
  */
 export async function POST(req: Request) {
   const auth = await authRunner(req);
@@ -26,34 +35,16 @@ export async function POST(req: Request) {
   try { body = await req.json(); } catch { /* empty body is fine */ }
   const status: RunnerStatus = body.status ?? 'online';
 
-  await admin.from('runners').update({ last_heartbeat_at: new Date().toISOString(), status, updated_at: new Date().toISOString() }).eq('id', runner.id);
-
-  // Jobs this runner holds that have been cancelled.
-  const { data: cancelledJobs } = await admin
-    .from('jobs')
-    .select('id')
-    .eq('claimed_by_runner', runner.id)
-    .in('status', ['cancelled']);
-  const cancelJobIds = (cancelledJobs ?? []).map((j) => j.id);
-
-  // Workflow runs driven by this runner's jobs with pause_requested set.
-  let pauseRunIds: string[] = [];
-  {
-    const { data: activeJobs } = await admin
-      .from('jobs')
-      .select('id')
-      .eq('claimed_by_runner', runner.id)
-      .in('status', ['claimed', 'running']);
-    const jobIds = (activeJobs ?? []).map((j) => j.id);
-    if (jobIds.length > 0) {
-      const { data: runs } = await admin
-        .from('workflow_runs')
-        .select('id')
-        .in('job_id', jobIds)
-        .eq('pause_requested', true);
-      pauseRunIds = (runs ?? []).map((r) => r.id);
-    }
-  }
+  const { data, error } = await admin.rpc('runner_heartbeat', {
+    p_runner_id: runner.id,
+    p_status: status,
+  });
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+
+  // PostgREST returns `setof record` functions as an array of rows.
+  const row = (Array.isArray(data) ? data[0] : data) as HeartbeatRpcRow | null | undefined;
+  const cancelJobIds = row?.cancel_job_ids ?? [];
+  const pauseRunIds  = row?.pause_run_ids  ?? [];
 
   return NextResponse.json({ ok: true, cancelJobIds, pauseRunIds });
 }
diff --git a/packages/gui/src/app/api/runner/jobs/route.ts b/packages/gui/src/app/api/runner/jobs/route.ts
index 0d6e4df..51cccec 100644
--- a/packages/gui/src/app/api/runner/jobs/route.ts
+++ b/packages/gui/src/app/api/runner/jobs/route.ts
@@ -28,11 +28,9 @@ export async function GET(req: Request) {
   if (auth instanceof NextResponse) return auth;
   const { runner, admin } = auth;
 
-  // Heartbeat-on-poll (best-effort).
-  await admin.rpc('touch_runner_heartbeat', { p_runner_id: runner.id, p_status: 'online' }).then(
-    () => {},
-    () => admin.from('runners').update({ last_heartbeat_at: new Date().toISOString(), status: 'online' }).eq('id', runner.id),
-  );
+  // No heartbeat-on-poll: the daemon's dedicated `/api/runner/heartbeat` (now
+  // a single RPC, migration 0020) is the single source of truth. The previous
+  // double-write here was pure overhead per claim tick.
 
   const url = new URL(req.url);
   const requested = (url.searchParams.get('backends') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
diff --git a/packages/gui/src/app/api/runner/runs/[runId]/events/route.ts b/packages/gui/src/app/api/runner/runs/[runId]/events/route.ts
index a667170..de5a2c4 100644
--- a/packages/gui/src/app/api/runner/runs/[runId]/events/route.ts
+++ b/packages/gui/src/app/api/runner/runs/[runId]/events/route.ts
@@ -1,12 +1,10 @@
 import { NextResponse } from 'next/server';
 import { authRunner, runnerScopesWorkspace } from '../../../_auth';
-import type { Database, AgentRunEventType, AgentRunStatus, AgentRunStepKind } from '@/lib/supabase/types';
+import type { AgentRunEventType } from '@/lib/supabase/types';
 
 export const dynamic = 'force-dynamic';
 export const runtime = 'nodejs';
 
-type AgentRunsRow = Database['public']['Tables']['agent_runs']['Row'];
-
 interface IncomingEvent {
   type: AgentRunEventType | string;
   payload?: unknown;
@@ -27,10 +25,13 @@ interface IncomingEvent {
 /**
  * POST /api/runner/runs/:runId/events  { events: IncomingEvent[] }
  *
- * The runner batches events here. For step lifecycle events we upsert an
- * `agent_runs` row (insert on `step-start`, update on `step-end`) and advance
- * `workflow_runs.current_step_id`; every event is also recorded in
- * `agent_run_events`. `tokensUsed` accumulates into `workflow_runs.tokens_used`.
+ * The runner batches events here. The entire batch is processed by a single
+ * `ingest_runner_events` RPC (migration 0020): one set-based insert opens
+ * agent_runs rows from step-start, one upsert closes them from step-end, one
+ * insert appends every event to agent_run_events, and one atomic UPDATE rolls
+ * up `tokens_used` + `current_step_id` on workflow_runs. Previously this loop
+ * fired ~30-60 sequential statements per 25-event batch, which was the main
+ * driver of the 10-16s tail latency under multi-runner load.
  */
 export async function POST(req: Request, { params }: { params: Promise<{ runId: string }> }) {
   const auth = await authRunner(req);
@@ -45,83 +46,14 @@ export async function POST(req: Request, { params }: { params: Promise<{ runId:
   let body: { events?: IncomingEvent[] };
   try { body = await req.json(); } catch { return NextResponse.json({ error: 'invalid json' }, { status: 400 }); }
   const events = Array.isArray(body.events) ? body.events : [];
+  if (events.length === 0) return NextResponse.json({ ok: true });
 
-  // Resolve a step's agent_runs row id within this batch (step-start creates it).
-  const stepRunIds = new Map<string, string>(); // `${stepId}#${iteration}` -> agent_runs.id
-  const stepKey = (e: IncomingEvent) => `${e.stepId}#${e.iteration ?? 1}`;
-  let tokenDelta = 0;
-  let lastStepId: string | null = null;
-
-  for (const e of events) {
-    if (typeof e.tokensUsed === 'number') tokenDelta += e.tokensUsed;
-
-    let agentRunId: string | null = e.agentRunId ?? null;
-
-    if (e.stepId && e.type === 'step-start') {
-      const { data, error } = await admin
-        .from('agent_runs')
-        .insert({
-          workspace_id: run.workspace_id,
-          workflow_run_id: runId,
-          step_id: e.stepId,
-          iteration: e.iteration ?? 1,
-          kind: (e.kind ?? null) as AgentRunStepKind | null,
-          backend: e.backend ?? null,
-          model: e.model ?? null,
-          status: 'running',
-          started_at: e.startedAt ?? new Date().toISOString(),
-        })
-        .select('id')
-        .single();
-      if (!error && data) { stepRunIds.set(stepKey(e), data.id); agentRunId = data.id; }
-      lastStepId = e.stepId;
-      await admin.from('workflow_runs').update({ current_step_id: e.stepId }).eq('id', runId);
-    } else if (e.stepId && e.type === 'step-end') {
-      const existing = stepRunIds.get(stepKey(e));
-      const dbStatus: AgentRunStatus =
-        e.status === 'succeeded' ? 'succeeded' : e.status === 'skipped' ? 'skipped' : e.status === 'running' ? 'running' : 'failed';
-      if (existing) {
-        await admin.from('agent_runs').update({
-          status: dbStatus, finished_at: e.finishedAt ?? new Date().toISOString(),
-          tokens_used: e.tokensUsed ?? 0, summary: e.summary ?? null, error: e.error ?? null,
-          kind: (e.kind ?? undefined) as AgentRunsRow['kind'] | undefined,
-        }).eq('id', existing);
-        agentRunId = existing;
-      } else {
-        // No matching step-start in this/an earlier batch — insert a closed row.
-        const { data } = await admin.from('agent_runs').insert({
-          workspace_id: run.workspace_id, workflow_run_id: runId, step_id: e.stepId, iteration: e.iteration ?? 1,
-          kind: (e.kind ?? null) as AgentRunStepKind | null, backend: e.backend ?? null, model: e.model ?? null,
-          status: dbStatus, started_at: e.startedAt ?? new Date().toISOString(), finished_at: e.finishedAt ?? new Date().toISOString(),
-          tokens_used: e.tokensUsed ?? 0, summary: e.summary ?? null, error: e.error ?? null,
-        }).select('id').single();
-        agentRunId = data?.id ?? null;
-      }
-      lastStepId = e.stepId;
-    }
-
-    await admin.from('agent_run_events').insert({
-      workspace_id: run.workspace_id,
-      workflow_run_id: runId,
-      agent_run_id: agentRunId,
-      type: (isKnownEventType(e.type) ? e.type : 'note') as AgentRunEventType,
-      payload: (e.payload ?? {}) as Database['public']['Tables']['agent_run_events']['Row']['payload'],
-    });
-  }
-
-  if (tokenDelta > 0) {
-    const { data: cur } = await admin.from('workflow_runs').select('tokens_used').eq('id', runId).single();
-    await admin.from('workflow_runs').update({ tokens_used: (cur?.tokens_used ?? 0) + tokenDelta }).eq('id', runId);
-  }
-  if (lastStepId) {
-    // (current_step_id already set on step-start; this keeps it fresh for batches
-    // that only carried step-end events.)
-    await admin.from('workflow_runs').update({ current_step_id: lastStepId }).eq('id', runId);
-  }
+  const { error } = await admin.rpc('ingest_runner_events', {
+    p_run_id: runId,
+    p_workspace_id: run.workspace_id,
+    p_events: events,
+  });
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
 
   return NextResponse.json({ ok: true });
 }
-
-function isKnownEventType(t: string): t is AgentRunEventType {
-  return ['lifecycle', 'agent-text', 'tool-call', 'tool-result', 'note', 'step-start', 'step-end'].includes(t);
-}
diff --git a/packages/gui/supabase/migrations/0020_runner_perf.sql b/packages/gui/supabase/migrations/0020_runner_perf.sql
new file mode 100644
index 0000000..b30d088
--- /dev/null
+++ b/packages/gui/supabase/migrations/0020_runner_perf.sql
@@ -0,0 +1,201 @@
+-- Runner hot-path collapse: 4-query heartbeat → 1 RPC, N+2-query event ingest
+-- → 1 RPC. Production symptom was bimodal 200ms / 10-16s tail latency on
+-- /api/runner/heartbeat and /api/runner/runs/:id/events under multi-runner
+-- load — caused by PgBouncer pool starvation from chatty per-request
+-- pipelines (heartbeat = 4 sequential statements, a 25-event batch = 30-60
+-- sequential statements). Both endpoints now do a single RPC round-trip.
+
+-- ─── agent_runs unique key ─────────────────────────────────────────────
+-- Required by ingest_runner_events' `on conflict` upsert: a step's
+-- (workflow_run_id, step_id, iteration) is logically unique already, the
+-- constraint just makes it enforceable so the RPC can be set-based.
+alter table agent_runs
+  add constraint agent_runs_run_step_iter_uniq
+  unique (workflow_run_id, step_id, iteration);
+
+-- ─── runner_heartbeat ──────────────────────────────────────────────────
+-- Replaces the per-heartbeat sequence:
+--   UPDATE runners …
+--   SELECT cancelled jobs claimed by this runner
+--   SELECT this runner's active jobs
+--   SELECT workflow_runs.pause_requested for those jobs
+-- with a single CTE pipeline that runs in one round-trip and returns
+-- (cancel_job_ids, pause_run_ids).
+create or replace function runner_heartbeat(
+  p_runner_id uuid,
+  p_status    text default 'online'
+) returns table (cancel_job_ids uuid[], pause_run_ids uuid[])
+language sql
+as $$
+  with hb as (
+    update runners
+       set last_heartbeat_at = now(),
+           status            = coalesce(p_status, status),
+           updated_at        = now()
+     where id = p_runner_id
+     returning id
+  ),
+  -- Single pass over `jobs` partitioned by status: cancellations + the set of
+  -- active jobs whose workflow_runs we'll check for pause_requested.
+  runner_jobs as (
+    select id, status
+      from jobs
+     where claimed_by_runner = p_runner_id
+       and status in ('claimed', 'running', 'cancelled')
+  ),
+  cancels as (
+    select coalesce(array_agg(id), '{}'::uuid[]) as ids
+      from runner_jobs
+     where status = 'cancelled'
+  ),
+  pauses as (
+    select coalesce(array_agg(wr.id), '{}'::uuid[]) as ids
+      from workflow_runs wr
+      join runner_jobs rj on rj.id = wr.job_id
+     where wr.pause_requested = true
+       and rj.status in ('claimed', 'running')
+  )
+  select cancels.ids, pauses.ids
+    from hb, cancels, pauses;
+$$;
+
+-- ─── ingest_runner_events ──────────────────────────────────────────────
+-- Replaces the per-batch loop in /api/runner/runs/:id/events. A 25-event
+-- batch previously generated ~30-60 statements (insert agent_runs per
+-- step-start, update agent_runs per step-end, insert agent_run_events per
+-- event, select-then-update workflow_runs.tokens_used). This function runs
+-- the whole batch in three set-based statements + one workflow_runs update,
+-- all in a single round-trip, and makes the token rollup atomic
+-- (`tokens_used = tokens_used + delta`).
+--
+-- The event payload shape mirrors `RunnerEvent` (packages/runner/src/runner-client.ts):
+--   { type, payload, stepId?, iteration?, kind?, backend?, model?, status?,
+--     summary?, error?, tokensUsed?, startedAt?, finishedAt? }
+--
+-- Caller guarantees: p_run_id is a real workflow_runs.id whose workspace
+-- equals p_workspace_id (the route does this check before calling).
+create or replace function ingest_runner_events(
+  p_run_id       uuid,
+  p_workspace_id uuid,
+  p_events       jsonb
+) returns void
+language plpgsql
+as $$
+declare
+  v_token_delta int;
+  v_last_step   text;
+begin
+  if p_events is null or jsonb_typeof(p_events) <> 'array' or jsonb_array_length(p_events) = 0 then
+    return;
+  end if;
+
+  -- 1. step-start: open an agent_runs row per step. Idempotent on the unique
+  --    key so a re-delivered batch doesn't double-insert; the running row
+  --    stays in place until step-end (#2) closes it.
+  insert into agent_runs (
+    workspace_id, workflow_run_id, step_id, iteration, kind, backend, model,
+    status, started_at
+  )
+  select
+    p_workspace_id,
+    p_run_id,
+    e->>'stepId',
+    coalesce((e->>'iteration')::int, 1),
+    e->>'kind',
+    e->>'backend',
+    e->>'model',
+    'running',
+    coalesce((e->>'startedAt')::timestamptz, now())
+  from jsonb_array_elements(p_events) as e
+  where e->>'type' = 'step-start'
+    and e->>'stepId' is not null
+  on conflict (workflow_run_id, step_id, iteration) do nothing;
+
+  -- 2. step-end: close the matching row (or insert a closed row if step-start
+  --    was never delivered for it — the route's previous fallback path).
+  insert into agent_runs (
+    workspace_id, workflow_run_id, step_id, iteration, kind, backend, model,
+    status, started_at, finished_at, tokens_used, summary, error
+  )
+  select
+    p_workspace_id,
+    p_run_id,
+    e->>'stepId',
+    coalesce((e->>'iteration')::int, 1),
+    e->>'kind',
+    e->>'backend',
+    e->>'model',
+    case e->>'status'
+      when 'succeeded' then 'succeeded'
+      when 'skipped'   then 'skipped'
+      when 'running'   then 'running'
+      else 'failed'
+    end,
+    coalesce((e->>'startedAt')::timestamptz, now()),
+    coalesce((e->>'finishedAt')::timestamptz, now()),
+    coalesce((e->>'tokensUsed')::int, 0),
+    e->>'summary',
+    e->>'error'
+  from jsonb_array_elements(p_events) as e
+  where e->>'type' = 'step-end'
+    and e->>'stepId' is not null
+  on conflict (workflow_run_id, step_id, iteration) do update set
+    status      = excluded.status,
+    finished_at = excluded.finished_at,
+    tokens_used = excluded.tokens_used,
+    summary     = excluded.summary,
+    error       = excluded.error,
+    kind        = coalesce(agent_runs.kind, excluded.kind);
+
+  -- 3. agent_run_events: one insert for the whole batch. agent_run_id is
+  --    resolved via join (NULL for events with no stepId, e.g. lifecycle).
+  --    `with ordinality` + ORDER BY preserves the runner's emission order so
+  --    the auto-assigned identity values are stable for the cockpit's
+  --    chronological view.
+  insert into agent_run_events (workspace_id, workflow_run_id, agent_run_id, type, payload)
+  select
+    p_workspace_id,
+    p_run_id,
+    ar.id,
+    case
+      when ev.e->>'type' in ('lifecycle','agent-text','tool-call','tool-result','note','step-start','step-end')
+        then ev.e->>'type'
+      else 'note'
+    end,
+    coalesce(ev.e->'payload', '{}'::jsonb)
+  from jsonb_array_elements(p_events) with ordinality as ev(e, ord)
+  left join agent_runs ar
+    on ar.workflow_run_id = p_run_id
+   and ar.step_id         = ev.e->>'stepId'
+   and ar.iteration       = coalesce((ev.e->>'iteration')::int, 1)
+  order by ev.ord;
+
+  -- 4. workflow_runs roll-up. Tokens go through `tokens_used = tokens_used +
+  --    delta` so concurrent batches can't lose increments. current_step_id
+  --    is updated to the last step touched in this batch.
+  select
+    coalesce(sum( (e->>'tokensUsed')::int ) filter (where (e->>'tokensUsed') is not null), 0),
+    (
+      select e2->>'stepId'
+        from jsonb_array_elements(p_events) with ordinality as t2(e2, ord)
+       where e2->>'stepId' is not null
+       order by t2.ord desc
+       limit 1
+    )
+  into v_token_delta, v_last_step
+  from jsonb_array_elements(p_events) as e;
+
+  if v_token_delta > 0 or v_last_step is not null then
+    update workflow_runs
+       set tokens_used     = tokens_used + coalesce(v_token_delta, 0),
+           current_step_id = coalesce(v_last_step, current_step_id)
+     where id = p_run_id;
+  end if;
+end;
+$$;
+
+-- Runner API routes call these via the service-role key (bypasses RLS); the
+-- function bodies are the trust boundary, not who may invoke them. Same
+-- pattern as 0010_runner_api.sql.
+grant execute on function runner_heartbeat(uuid, text)                       to anon, authenticated, service_role;
+grant execute on function ingest_runner_events(uuid, uuid, jsonb)            to anon, authenticated, service_role;

From dd099b67a5f28b838c44f0a8ec77a826d503c04d Mon Sep 17 00:00:00 2001
From: Patryk Lewczuk <patryk.lewczuk@hotmail.com>
Date: Sun, 24 May 2026 21:58:29 +0200
Subject: [PATCH 2/2] feat(flows): user-defined skill chains end-to-end
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lands the in-flight "flows" feature — a UI for declarative skill chains
(name + ordered { skill, argsTemplate, stopChainIfContains } steps) that
run through the existing workflow engine and surface in the cockpit.

Includes:
- migration 0021_flows: flows table + auto-triggers
- core/workflows/flow-runner: turns a FlowRow into a Workflow<FlowBlackboard>;
  threads {{input}} / {{previousTaskId}} / {{previousPullRequest*}} into each
  step's user prompt; parses PR_URL= / PR_NUMBER= markers between steps
- core/workflows: new unparsedCommentSection callback fires on the
  onNoParse success path so flow steps actually populate the living
  comment (fixes "(no sections yet)" / "Done." bug observed on the
  first end-to-end run on issue #2034)
- gui/app/workflows: /workflows page + flow card editor + starter
  templates dropdown; the autofix template is decomposed into 5 focused
  steps (verify-in-repo → root-cause → fix → open-pr → review) so each
  step gets its own token budget instead of one mega-step blowing past
  the 2.5M cap
- gui/app/issues: "Run flow for issue" modal entry point
- webhook + dispatch + runner: route incoming flow runs through the
  engine
- docs: open-mercato ephemeral integration guide for downstream verify

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cezar-ephemeral-guide.md                      |  267 +++++
 packages/core/src/index.ts                    |   27 +
 packages/core/src/workflows/flow-runner.ts    |  342 ++++++
 .../core/src/workflows/workflow-engine.ts     |    4 +
 packages/core/src/workflows/workflow.ts       |   15 +-
 .../gui/src/app/api/github/webhook/route.ts   |  147 ++-
 packages/gui/src/app/api/runner/jobs/route.ts |   52 +-
 .../gui/src/app/issues/issue-row-menu.tsx     |   16 +
 .../app/issues/run-flow-for-issue-modal.tsx   |  192 +++
 packages/gui/src/app/workflows/actions.ts     |  511 ++++++++
 packages/gui/src/app/workflows/flow-card.tsx  | 1054 +++++++++++++++++
 packages/gui/src/app/workflows/page.tsx       |   22 +
 packages/gui/src/app/workflows/templates.ts   |  144 +++
 .../src/app/workflows/workflows-client.tsx    |  320 +++++
 packages/gui/src/components/sidebar.tsx       |    2 +
 packages/gui/src/lib/execute-workflow-job.ts  |   54 +-
 packages/gui/src/lib/persist-workflow-run.ts  |    7 +-
 .../gui/src/lib/scheduler/run-dispatch.ts     |    4 +-
 packages/gui/src/lib/supabase/types.ts        |   25 +-
 .../gui/supabase/migrations/0021_flows.sql    |   69 ++
 packages/runner/src/execute-job-locally.ts    |   36 +-
 packages/runner/src/runner-client.ts          |    6 +-
 22 files changed, 3285 insertions(+), 31 deletions(-)
 create mode 100644 cezar-ephemeral-guide.md
 create mode 100644 packages/core/src/workflows/flow-runner.ts
 create mode 100644 packages/gui/src/app/issues/run-flow-for-issue-modal.tsx
 create mode 100644 packages/gui/src/app/workflows/actions.ts
 create mode 100644 packages/gui/src/app/workflows/flow-card.tsx
 create mode 100644 packages/gui/src/app/workflows/page.tsx
 create mode 100644 packages/gui/src/app/workflows/templates.ts
 create mode 100644 packages/gui/src/app/workflows/workflows-client.tsx
 create mode 100644 packages/gui/supabase/migrations/0021_flows.sql

diff --git a/cezar-ephemeral-guide.md b/cezar-ephemeral-guide.md
new file mode 100644
index 0000000..309e4d6
--- /dev/null
+++ b/cezar-ephemeral-guide.md
@@ -0,0 +1,267 @@
+# Open-Mercato Ephemeral Environments — Integration Guide for Cezar
+
+Open-mercato ships two flavors of ephemeral runtime that fit cezar's "spin up an isolated instance per agent run, apply a fix, verify, tear down" loop. Pick by where you want the stack to live.
+
+## TL;DR — Which to pick
+
+| Use case | Runtime | How |
+|---|---|---|
+| Run a fix branch *inside* the open-mercato repo checkout, fast, with HMR, isolated DB | **Local dev ephemeral** | `yarn dev:ephemeral` |
+| Test the agent's fix as an end-user against a built production-like image, throwaway, no host coupling | **Docker preview stack** | `yarn docker:ephemeral` |
+| Verify the fix automatically with Playwright (recommended for cezar's autoverify step) | **Integration ephemeral** (built on top of the local dev flavor) | `yarn test:integration:ephemeral` |
+| Want a Node-level API rather than CLI orchestration | **Programmatic** | Import from `@open-mercato/cli` → `packages/cli/src/lib/testing/integration.ts` |
+
+All three keep their state in well-known JSON files that cezar can read to discover `baseUrl`, port, and DB URL — so you do not need to parse stdout.
+
+---
+
+## 1. Local dev ephemeral — `yarn dev:ephemeral`
+
+Implementation: `scripts/dev-ephemeral.ts` (~1200 lines).
+
+What it does, per invocation:
+1. Provisions a throwaway Postgres via `docker run` (image `postgres:16`, container `open-mercato-dev-ephemeral-<ts>-<rand>`, database `om_dev_ephemeral_<ts>_<rand>`, random host port, `--rm`).
+2. Runs `yarn initialize -- --reinstall` against that DB (migrations, generated artifacts, seed defaults).
+3. Boots a Next.js dev server on a free port (default search range starts at 5000).
+4. Waits for `GET /backend/login` to respond (180 s startup budget, 1 s poll, 1.5 s probe timeout).
+5. Registers the running instance into `.ai/dev-ephemeral-envs.json`.
+
+### CLI flags
+
+- `--classic` — disable the splash UI, plain Next.js dev output
+- `--verbose` — raw passthrough of all child-process logs
+
+### State file (always check this first)
+
+`.ai/dev-ephemeral-envs.json`:
+
+```json
+{
+  "version": 1,
+  "instances": [
+    {
+      "id": "<pid>:<ISO8601>",
+      "pid": 12345,
+      "port": 5000,
+      "baseUrl": "http://127.0.0.1:5000",
+      "backendUrl": "http://127.0.0.1:5000/backend",
+      "cwd": "/path/to/open-mercato",
+      "startedAt": "2026-05-23T10:00:00.000Z",
+      "postgresContainerId": "abc123…",
+      "postgresPort": 54321,
+      "databaseUrlRedacted": "postgres://***@127.0.0.1:54321/om_dev_ephemeral_..."
+    }
+  ]
+}
+```
+
+Multiple instances are supported concurrently — each gets a unique port, container, and DB name.
+
+On startup the script also prunes stale entries (dead PIDs or unresponsive endpoints), so leaked rows from a previous SIGKILL self-heal on the next launch.
+
+### Environment variables
+
+| Var | Default | Effect |
+|---|---|---|
+| `DEV_EPHEMERAL_PREFERRED_PORT` | — | Try this app port first; fall back to free port |
+| `DEV_EPHEMERAL_POSTGRES_IMAGE` | `postgres:16` | Override Postgres image |
+| `DEV_EPHEMERAL_POSTGRES_USER` | `postgres` | DB user |
+| `DEV_EPHEMERAL_POSTGRES_PASSWORD` | `postgres` | DB password |
+| `OM_DEV_SPLASH_PORT` | `auto` | Splash UI port; `disabled`/`false`/`off` to skip |
+| `OM_DEV_AUTO_OPEN` | unset | Set to `0` to suppress browser auto-open |
+| `CI` | unset | When `true`, suppresses splash auto-open |
+| `OM_DEV_CLASSIC` | unset | Same as `--classic` |
+| `MERCATO_DEV_OUTPUT` | unset | Set `verbose` for verbose output |
+
+### Readiness signaling
+
+No dedicated `/api/health` endpoint exists. Two equivalent ready signals:
+
+1. **HTTP probe (recommended for cezar):** `GET http://127.0.0.1:<port>/backend/login` returns any 2xx/3xx → ready.
+2. **Splash status:** `GET http://127.0.0.1:<splash-port>/status` returns `{ ready, readyUrl, loginUrl, failed }`.
+
+### Lifecycle
+
+- **Start:** `yarn dev:ephemeral` (foreground, attaches stdio).
+- **Stop:** send `SIGINT` or `SIGTERM` to the script PID. Both signals are forwarded; the Postgres container is removed in the shutdown handler.
+- **No `yarn dev:ephemeral:down`** — there's nothing to call out-of-band. Cleanup is process-scoped.
+- **Crash safety:** the Postgres container is started with `--rm`, so Docker auto-deletes it when the container exits even if the parent process is `SIGKILL`'d. The orphan row in the state file is cleaned by the next ephemeral startup's pruner.
+
+### Auth bootstrap (already done for you)
+
+`yarn initialize -- --reinstall` (called automatically inside the ephemeral flow) seeds default users:
+
+| Role | Email | Password |
+|---|---|---|
+| Superadmin | `superadmin@acme.com` (override via `OM_INIT_SUPERADMIN_EMAIL`) | `secret` |
+| Admin | `admin@acme.com` | `secret` |
+| Employee | `employee@acme.com` | `secret` |
+
+These come from `packages/core/src/helpers/integration/auth.ts:DEFAULT_CREDENTIALS`. No manual `auth:create-user` step required.
+
+---
+
+## 2. Integration ephemeral — `yarn test:integration:ephemeral`
+
+This is the same dev-ephemeral runtime, wrapped by a richer harness that adds build caching, environment reuse, locking, and Playwright orchestration. **For cezar's auto-verify step this is usually the right entry point — it gives you the same instance the integration tests run against.**
+
+Implementation: `packages/cli/src/lib/testing/integration.ts` (~3200 lines).
+
+### CLI flavors
+
+| Command | Use |
+|---|---|
+| `yarn test:integration:ephemeral` | Spins up ephemeral env, runs the full Playwright suite, tears down |
+| `yarn test:integration:ephemeral:start` | **Spins up ephemeral env and leaves it running** — what cezar should call when it wants a long-lived target to throw verification at |
+| `yarn test:integration:ephemeral:interactive` | Same as `:start` but with a menu (human use) |
+| `yarn test:integration:ephemeral:start:verbose` | Verbose variant of `:start` |
+
+### State file
+
+`.ai/qa/ephemeral-env.json` (different path from the dev flow above):
+
+```json
+{
+  "status": "running",
+  "baseUrl": "http://127.0.0.1:5001",
+  "port": 5001,
+  "databaseUrl": "postgresql://...",
+  "queueBaseDir": "/path/to/apps/mercato/.mercato/queue",
+  "source": "<source fingerprint>",
+  "captureScreenshots": false,
+  "startedAt": "2026-05-23T10:00:00.000Z"
+}
+```
+
+- Default port: **5001** (falls back to a free port if busy).
+- File is **cleared automatically** when the env stops, so its presence is a reliable "is one running?" check.
+- Lock file: `.ai/qa/ephemeral-env.lock` (5 min timeout, 500 ms poll) — prevents race when two callers try to spawn at once.
+
+### Environment variables (integration flavor)
+
+| Var | Default | Effect |
+|---|---|---|
+| `OM_INTEGRATION_APP_READY_TIMEOUT_SECONDS` | `90` | App-ready probe timeout |
+| `OM_INTEGRATION_BUILD_CACHE_TTL_SECONDS` | `600` | Reuse build artifacts within this window |
+| `ENABLE_CRUD_API_CACHE` | unset | The npm scripts set this to `true` |
+| `OM_INTEGRATION_TEST` | set by harness | Signals integration mode to the app |
+
+### Programmatic API (recommended for cezar's runner)
+
+`packages/cli/src/lib/testing/integration.ts` exports a Node-callable surface. **You can import this from `@open-mercato/cli` and orchestrate ephemerals without shelling out.** The relevant exports:
+
+```typescript
+export type EphemeralEnvironmentHandle = {
+  baseUrl: string                       // e.g. "http://127.0.0.1:5001"
+  port: number
+  databaseUrl: string
+  commandEnvironment: NodeJS.ProcessEnv // env to inherit into your verification subprocess
+  ownedByCurrentProcess: boolean        // true if you can call stop()
+  stop: () => Promise<void>
+}
+
+// Primary entry points
+export async function startEphemeralEnvironment(opts: EphemeralRuntimeOptions): Promise<EphemeralEnvironmentHandle>
+export async function tryReuseExistingEnvironment(opts: EphemeralRuntimeOptions): Promise<EphemeralEnvironmentHandle | null>
+
+// State helpers
+export async function readEphemeralEnvironmentState(): Promise<EphemeralEnvironmentState | null>
+export async function writeEphemeralEnvironmentState(input): Promise<void>
+export async function clearEphemeralEnvironmentState(): Promise<void>
+
+// Coordination
+export async function acquireEphemeralRuntimeLock(opts): Promise<Release>
+export async function shouldReuseBuildArtifacts(ttlSeconds: number): Promise<boolean>
+```
+
+`EphemeralRuntimeOptions`:
+
+```typescript
+type EphemeralRuntimeOptions = {
+  verbose: boolean
+  captureScreenshots: boolean
+  logPrefix: string
+  forceRebuild?: boolean
+  reuseExisting?: boolean
+  requiredExistingSource?: string         // pin to a specific source fingerprint
+  environmentOverrides?: NodeJS.ProcessEnv
+}
+```
+
+### Reusable test helpers (for cezar's verify step)
+
+Published from `@open-mercato/core/helpers/integration/*` — usable from any Node process, including from cezar's own repo (it does not need to live inside open-mercato):
+
+| Import | What it gives you |
+|---|---|
+| `…/auth` | `login`, `DEFAULT_CREDENTIALS` |
+| `…/api` | `getAuthToken`, `apiRequest` (token-authenticated API calls) |
+| `…/crmFixtures` | `createCompanyFixture`, `createPersonFixture`, `deleteEntityIfExists`, `readJsonSafe` |
+| `…/catalogFixtures`, `…/salesFixtures`, `…/authFixtures`, `…/dictionariesFixtures` | Domain-specific fixture lifecycle |
+| `…/queue` | `drainIntegrationQueue(queueName)` — runs pending jobs deterministically |
+
+Barrel: `@open-mercato/core/testing/integration` re-exports the common subset.
+
+---
+
+## 3. Docker preview stack — `yarn docker:ephemeral`
+
+For verifying a fix against a **built production-like image** without involving the host Node toolchain at all.
+
+Implementation: `docker/preview/Dockerfile` + `docker/preview/preview-entrypoint.sh` + `docker-compose.preview.yaml`.
+
+- Base image: `node:24-alpine`, multi-stage build.
+- Entrypoint internally calls `yarn test:integration:ephemeral:start` — so what runs inside the container is the same integration ephemeral as flavor 2.
+- Port mapping: host **5000** → container 5001.
+- Fresh DB on **every** `up` (no persistent volume).
+- Mounts `/var/run/docker.sock` so the in-container ephemeral can spawn its Postgres on the host's Docker.
+
+Commands:
+
+```bash
+yarn docker:ephemeral         # build + start, blocks attached to logs
+yarn docker:ephemeral:down    # full teardown
+```
+
+Discovery from the host: the app is unconditionally at `http://localhost:5000`. There is no state file written to the host filesystem for this flavor — port is fixed in the compose file.
+
+---
+
+## Recommended integration shape for cezar
+
+Per agent run:
+
+1. **Reserve the runtime.** Call `tryReuseExistingEnvironment({ reuseExisting: true, requiredExistingSource: <commit-sha>, … })`. If it returns a handle, you've got a warm env matching your source — use it. If null, fall through.
+2. **Start fresh.** `startEphemeralEnvironment({ … })`. Acquire `acquireEphemeralRuntimeLock` first so two concurrent agents don't race on the same checkout.
+3. **Apply the fix** in a worktree on the same checkout the ephemeral env was built from (the env auto-reloads via Turbopack on edits).
+4. **Verify** by:
+   - Hitting `${handle.baseUrl}/backend/login` to confirm reachable.
+   - Logging in via `@open-mercato/core/helpers/integration/auth` → `login('admin')` or `getAuthToken('admin')`.
+   - Running module-scoped Playwright specs or your own targeted API calls.
+5. **Stop** with `await handle.stop()` *if `handle.ownedByCurrentProcess === true`*. Otherwise leave the env running for the next agent run.
+
+For parallel agent runs on the **same host**, use flavor 1 (`yarn dev:ephemeral`) — every invocation gets its own port, DB, container, and entry in `.ai/dev-ephemeral-envs.json`. For agent runs on **separate hosts/CI runners**, flavor 3 (`yarn docker:ephemeral`) is cleaner because it has zero host coupling.
+
+---
+
+## Gotchas to surface to the cezar team
+
+- **Node 24 required** by both flavors. The CLI bin asserts this and exits non-zero on older runtimes.
+- **Docker daemon required** by all three flavors (yes, even local dev-ephemeral — Postgres runs in a container).
+- **First-run cost.** Cold start is ~1–3 minutes (install + build + generate + DB init + dev boot). The integration flavor caches build artifacts for `OM_INTEGRATION_BUILD_CACHE_TTL_SECONDS` (default 600 s) so subsequent starts in the same checkout are much faster — set this higher for an agent fleet.
+- **There is no `/api/health`.** Probe `/backend/login` or the splash `/status`.
+- **No SIGKILL safety story for the state file** — the orphan row will sit in `.ai/dev-ephemeral-envs.json` until the next launch, which prunes it. Cezar workers that SIGKILL their own ephemeral should call `clearEphemeralEnvironmentState()` (integration flavor) or accept the next-launch self-heal (dev flavor).
+- **Default seed users are static across runs.** If a fix depends on auth edge cases, cezar's verify step can create scoped users via `createUserFixture` from `@open-mercato/core/helpers/integration/authFixtures`.
+
+---
+
+## Authoritative source files
+
+If the cezar team wants to read the implementations directly:
+
+- `scripts/dev-ephemeral.ts` — dev flavor entrypoint
+- `packages/cli/src/lib/testing/integration.ts` — integration flavor, programmatic API, exported types
+- `packages/cli/src/lib/testing/runtime-utils.ts` — port/host/probe helpers
+- `docker/preview/Dockerfile`, `docker/preview/preview-entrypoint.sh`, `docker-compose.preview.yaml` — preview container
+- `.ai/qa/AGENTS.md` — internal QA workflow doc (the closest existing prose to this guide)
+- `packages/core/src/helpers/integration/*` — npm-published test helpers
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 3fa11bb..b771093 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -196,3 +196,30 @@ export {
   type CiFollowupBlackboard,
   type CiFollowupSeed,
 } from './workflows/definitions/ci-followup.workflow.js';
+
+// Worktree helpers — exported so the GUI's flow runner can prep a worktree
+// before calling `runWorkflow` (same as the autofix path does internally).
+export {
+  createWorktree,
+  commitAll,
+  getDiffAgainstBase,
+  fetchRemoteBranch,
+  type WorktreeHandle,
+} from './actions/autofix/worktree.js';
+
+// Flow runner — runtime for the simple "flows" feature (workspace-defined
+// chains of skill steps). Used both by the GUI dispatcher (cron-based) and
+// the self-hosted runner daemon.
+export {
+  runFlow,
+  extractPrMarkers,
+  renderTemplate,
+  effectiveStepNotes,
+  composeStepSystemPrompt,
+  FLOW_STEP_SCAFFOLDING,
+  DEFAULT_STEP_NOTES,
+  FLOW_STEP_SYSTEM_PROMPT,
+  type FlowStep,
+  type FlowRow,
+  type RunFlowParams,
+} from './workflows/flow-runner.js';
diff --git a/packages/core/src/workflows/flow-runner.ts b/packages/core/src/workflows/flow-runner.ts
new file mode 100644
index 0000000..fcdd569
--- /dev/null
+++ b/packages/core/src/workflows/flow-runner.ts
@@ -0,0 +1,342 @@
+import { z } from 'zod';
+import type { AgentEvent as RunnerAgentEvent } from '../agents/agent-runner.js';
+import type { Config } from '../config/config.model.js';
+import type { GitHubService } from '../services/github.service.js';
+import type { IssueStore } from '../store/store.js';
+import { discoverSkills } from '../skills/skill-catalog.js';
+import { createWorktree } from '../actions/autofix/worktree.js';
+import {
+  agentStep,
+  type AgentRunRecord,
+  type Workflow,
+  type WorkflowRunResult,
+  type WorkflowStep,
+} from './workflow.js';
+import { runWorkflow } from './workflow-engine.js';
+
+/**
+ * Runtime for the simple "flows" UI (migration 0021). A flow is a named chain
+ * of `{ skill, argsTemplate }` steps. This module turns one into a multi-step
+ * `Workflow<FlowBlackboard>` and runs it through the existing engine.
+ *
+ *   - The skill body (from `<repo>/.ai/skills/<name>.md`) is appended to the
+ *     step's system prompt via `resolveStepConfig` (existing path).
+ *   - The args template is rendered against a fixed scope:
+ *       {{input}}                  — passed by the caller (typically the issue number)
+ *       {{previousTaskId}}         — the previous step's `agent_runs.id`
+ *       {{previousPullRequestUrl}} — `PR_URL=…` parsed from the previous agent's text
+ *       {{previousPullRequestNumber}} — `PR_NUMBER=…` parsed from the same
+ *   - PR markers are a soft contract: skills that create PRs should emit
+ *     `PR_URL=https://github.com/...` and `PR_NUMBER=42` in their final text
+ *     so the next step can reference them.
+ */
+
+export interface FlowStep {
+  skill: string;
+  argsTemplate: string;
+  /**
+   * When set, if the step's text output contains this substring the chain
+   * stops cleanly (status succeeded, reason "stopped at step N…"). Simple
+   * short-circuit for skills that legitimately decide "no action needed".
+   */
+  stopChainIfContains?: string;
+  /**
+   * Extra system-prompt content for this step, prepended to the skill body.
+   * When unset (or empty/whitespace-only), `DEFAULT_STEP_NOTES` is used —
+   * the marker contract reminder so the chain works even if the skill body
+   * doesn't itself document `PR_URL=` / `PR_NUMBER=`.
+   */
+  systemNotes?: string;
+}
+
+export interface FlowRow {
+  name: string;
+  steps: FlowStep[];
+}
+
+export interface RunFlowParams {
+  flow: FlowRow;
+  input: string;
+  store: IssueStore;
+  config: Config;
+  github: GitHubService;
+  issueNumber: number;
+  onEvent: (msg: string) => void;
+  onAgentEvent: (e: { type: string; [k: string]: unknown }) => void;
+  onRunRecord: (r: AgentRunRecord) => void;
+  pauseRequested?: () => boolean | Promise<boolean>;
+  cancelRequested?: () => boolean | Promise<boolean>;
+}
+
+interface FlowBlackboard extends Record<string, unknown> {
+  input: string;
+  previousTaskId: string;
+  previousPullRequestUrl: string;
+  previousPullRequestNumber: string;
+}
+
+export async function runFlow(params: RunFlowParams): Promise<WorkflowRunResult<FlowBlackboard>> {
+  if (params.flow.steps.length === 0) {
+    throw new Error(`flow '${params.flow.name}' has no steps`);
+  }
+
+  // Discover skills so resolveStepConfig (called by the engine) can find each
+  // step's skill body and append it to the system prompt.
+  const repoRoot = params.config.autofix?.repoRoot;
+  const skills = repoRoot
+    ? await discoverSkills(repoRoot, params.config.autofix?.skillsDir ?? '.ai/skills').catch((err: Error) => {
+        params.onEvent(`[flow] skill discovery failed: ${err.message}`);
+        return [];
+      })
+    : [];
+
+  // Closure-captured state the engine updates between steps. We need this so
+  // each step's `buildUserPrompt` sees the freshest `previousTaskId` (which
+  // the engine doesn't expose through the step context directly).
+  let lastAgentRunId = '';
+
+  const workflow: Workflow<FlowBlackboard> = {
+    id: `flow:${params.flow.name}`,
+    title: params.flow.name,
+    commentTargetOrder: ['issue', 'pr'],
+    initialBlackboard: () => ({
+      input: params.input,
+      previousTaskId: '',
+      previousPullRequestUrl: '',
+      previousPullRequestNumber: '',
+    }),
+    steps: params.flow.steps.map((step, idx) => makeAgentStepForFlowStep(step, idx, params.config)),
+  };
+
+  return runWorkflow(workflow, {
+    store: params.store,
+    config: params.config,
+    github: params.github,
+    issueNumber: params.issueNumber,
+    apply: true,
+    skills,
+    // Bindings: per-step, set the skillName so resolveStepConfig appends the
+    // skill body to the system prompt. The engine reads these from `bindings`.
+    bindings: params.flow.steps.map((step, idx) => ({
+      stepId: stepIdFor(idx),
+      skillName: step.skill,
+      backend: null,
+      model: null,
+      extraTools: [],
+    })),
+    prepareWorktree: repoRoot
+      ? async () => {
+          const wt = await createWorktree({
+            repoRoot,
+            branch: (params.config.autofix?.branchPrefix ?? 'autofix/cezar-issue-') + params.issueNumber,
+            baseBranch: params.config.autofix?.baseBranch ?? 'main',
+            remote: params.config.autofix?.remote ?? 'origin',
+            fetchRemote: params.config.autofix?.fetchBeforeAttempt ?? true,
+            onWarn: (m: string) => params.onEvent(m),
+          });
+          return { path: wt.path, dispose: wt.dispose };
+        }
+      : undefined,
+    onEvent: params.onEvent,
+    onAgentEvent: (e: RunnerAgentEvent) => params.onAgentEvent(e as unknown as { type: string; [k: string]: unknown }),
+    onRunRecord: (r: AgentRunRecord) => {
+      lastAgentRunId = r.id;
+      params.onRunRecord(r);
+    },
+    pauseRequested: params.pauseRequested,
+    cancelRequested: params.cancelRequested,
+  });
+
+  // ─── Helpers ──────────────────────────────────────────────────────────────
+
+  function stepIdFor(idx: number): string {
+    return `step-${idx + 1}`;
+  }
+
+  function makeAgentStepForFlowStep(
+    step: FlowStep,
+    idx: number,
+    cfg: Config,
+  ): WorkflowStep<FlowBlackboard> {
+    const autofix = cfg.autofix;
+    const builtinTools = autofix?.allowedTools ?? ['Read', 'Edit', 'Write', 'Grep', 'Glob', 'Bash'];
+    const bashAllowlist = autofix?.bashAllowlist;
+    const maxTurns = autofix?.maxTurns?.fixer ?? 30;
+    const model = autofix?.models?.fixer ?? 'claude-sonnet-4-6';
+
+    return agentStep<FlowBlackboard, unknown>({
+      id: stepIdFor(idx),
+      kind: 'agent',
+      builtinSkillId: step.skill,
+      builtinSystemPrompt: composeStepSystemPrompt(step),
+      builtinModel: model,
+      builtinTools,
+      bashAllowlist,
+      maxTurns,
+      cwdRequired: true,
+      // Free-form output. We don't enforce JSON; we parse PR_URL/PR_NUMBER
+      // markers from the text in onNoParse below.
+      responseSchema: z.never() as unknown as z.ZodSchema<unknown>,
+      buildUserPrompt: (ctx) => {
+        // Refresh `previousTaskId` from the closure right before render — it's
+        // updated by `onRunRecord` between steps.
+        const scope: FlowBlackboard = {
+          ...ctx.blackboard,
+          previousTaskId: lastAgentRunId,
+        };
+        return renderTemplate(step.argsTemplate, scope);
+      },
+      // If the agent emitted JSON that happened to validate, we still want
+      // to chain — but `z.never()` ensures this branch never fires.
+      onResult: () => ({ kind: 'continue' as const }),
+      onNoParse: (rawText, _ctx) => {
+        const { url, number } = extractPrMarkers(rawText);
+        const patch: Partial<FlowBlackboard> = {
+          previousPullRequestUrl: url ?? '',
+          previousPullRequestNumber: number != null ? String(number) : '',
+        };
+        // Stop-chain: cleanly end the workflow when the agent's output
+        // contains the configured marker. We rely on `skip-run` rather than
+        // a hard fail so the cockpit shows it as `succeeded (with reason)`.
+        if (step.stopChainIfContains && rawText.includes(step.stopChainIfContains)) {
+          return {
+            kind: 'skip-run',
+            reason: `stopped at step ${idx + 1}: output matched "${step.stopChainIfContains}"`,
+          };
+        }
+        return { kind: 'continue', blackboardPatch: patch };
+      },
+      // Render the agent's actual output into the living comment. The flow
+      // runtime never enforces a JSON schema, so the engine takes the
+      // `unparsedCommentSection` path (not `commentSection`).
+      unparsedCommentSection: (rawText) => ({
+        heading: flowStepHeading(idx, step, rawText),
+        body: flowStepBody(rawText),
+      }),
+      failCommentSection: (reason) => ({
+        heading: `Step ${idx + 1} — \`${step.skill}\` (failed)`,
+        body: reason,
+      }),
+    });
+  }
+}
+
+// ─── Living-comment rendering helpers ──────────────────────────────────────
+
+const STOP_MARKER_RE = /^NO_ACTION_NEEDED\b/m;
+const MAX_BODY_CHARS = 1500;
+
+function flowStepHeading(idx: number, step: FlowStep, rawText: string): string {
+  const base = `Step ${idx + 1} — \`${step.skill}\``;
+  if (step.stopChainIfContains && rawText.includes(step.stopChainIfContains)) {
+    return `${base} (stopped: \`${step.stopChainIfContains}\`)`;
+  }
+  if (STOP_MARKER_RE.test(rawText)) return `${base} (stopped: \`NO_ACTION_NEEDED\`)`;
+  const { url, number } = extractPrMarkers(rawText);
+  if (url && number != null) return `${base} → PR [#${number}](${url})`;
+  return base;
+}
+
+/**
+ * Render the most useful tail of the agent's output. Most skills end with a
+ * structured summary block (Status/Files changed/Summary/…); the last ~1500
+ * chars reliably capture that without flooding the GitHub comment with full
+ * tool-call transcripts.
+ */
+function flowStepBody(rawText: string): string {
+  const trimmed = (rawText ?? '').trim();
+  if (!trimmed) return '_(no output)_';
+  if (trimmed.length <= MAX_BODY_CHARS) return trimmed;
+  const tail = trimmed.slice(-MAX_BODY_CHARS).trimStart();
+  return `_… (truncated; showing last ${MAX_BODY_CHARS} chars)_\n\n${tail}`;
+}
+
+// ─── PR marker extraction ──────────────────────────────────────────────────
+
+/**
+ * Extracts `PR_URL=...` and `PR_NUMBER=...` markers from a step's text output.
+ * Soft contract: skills that create PRs should print these lines (anywhere in
+ * the response) so the next step can reference them via `{{previousPullRequest*}}`.
+ * Also tries common URL patterns as a fallback.
+ */
+export function extractPrMarkers(text: string): { url: string | null; number: number | null } {
+  let url: string | null = null;
+  let number: number | null = null;
+
+  const urlMatch = text.match(/PR_URL\s*=\s*(\S+)/);
+  if (urlMatch) url = urlMatch[1];
+  const numMatch = text.match(/PR_NUMBER\s*=\s*(\d+)/);
+  if (numMatch) number = Number(numMatch[1]);
+
+  // Fallback: scrape any GitHub PR URL.
+  if (!url) {
+    const fall = text.match(/https?:\/\/[\w./-]*github\.com\/[\w-]+\/[\w.-]+\/pull\/(\d+)/);
+    if (fall) {
+      url = fall[0];
+      if (number == null) number = Number(fall[1]);
+    }
+  }
+  return { url, number };
+}
+
+// ─── Template rendering ────────────────────────────────────────────────────
+
+const TEMPLATE_RE = /\{\{\s*([\w.]+)\s*\}\}/g;
+
+/** Render `{{path}}` references against a flat scope. Missing → empty string. */
+export function renderTemplate(tpl: string, scope: Record<string, unknown>): string {
+  return tpl.replace(TEMPLATE_RE, (_, path: string) => {
+    const v = lookupDotPath(scope, path);
+    if (v == null) return '';
+    if (typeof v === 'string') return v;
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    return JSON.stringify(v);
+  });
+}
+
+function lookupDotPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let cur: unknown = obj;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return cur;
+}
+
+// ─── Per-step scaffolding system prompt ────────────────────────────────────
+
+/**
+ * Minimal scaffolding shipped to every flow step. Generic — describes that
+ * this is one step of a workflow and that the skill body holds the actual
+ * instructions. The marker contract lives in `DEFAULT_STEP_NOTES` so users
+ * can edit/override it per step (see `step.systemNotes`).
+ */
+export const FLOW_STEP_SCAFFOLDING = `You are an agent executing one step of a user-defined workflow. Follow the SKILL instructions appended below to complete the task described in the user message.
+
+When the task is done, respond with a short plain-text summary (no JSON).`;
+
+/**
+ * Default notes prepended to the skill body when `step.systemNotes` is unset.
+ * Documents the marker contract that lets the next step reference the PR via
+ * `{{previousPullRequestUrl}}` / `{{previousPullRequestNumber}}` templates.
+ * Users override this per step via the pencil/notes panel in the editor.
+ */
+export const DEFAULT_STEP_NOTES = `If you open a pull request, end your response with two lines on separate lines:
+  PR_URL=<the PR url>
+  PR_NUMBER=<the PR number>
+so the next step in the workflow can reference it via {{previousPullRequestUrl}} / {{previousPullRequestNumber}}.`;
+
+/** Back-compat alias — kept temporarily for any out-of-tree code. */
+export const FLOW_STEP_SYSTEM_PROMPT = FLOW_STEP_SCAFFOLDING + '\n\n' + DEFAULT_STEP_NOTES;
+
+/** What the scaffolding+notes actually compose to at run time. */
+export function effectiveStepNotes(step: FlowStep): string {
+  const trimmed = (step.systemNotes ?? '').trim();
+  return trimmed.length > 0 ? step.systemNotes! : DEFAULT_STEP_NOTES;
+}
+
+/** The system prompt the engine actually sends (before the skill body is appended). */
+export function composeStepSystemPrompt(step: FlowStep): string {
+  return `${FLOW_STEP_SCAFFOLDING}\n\n${effectiveStepNotes(step)}`;
+}
diff --git a/packages/core/src/workflows/workflow-engine.ts b/packages/core/src/workflows/workflow-engine.ts
index f2f3c80..3619d1d 100644
--- a/packages/core/src/workflows/workflow-engine.ts
+++ b/packages/core/src/workflows/workflow-engine.ts
@@ -777,6 +777,10 @@ export class WorkflowEngine {
         if (outcome.kind === 'fail') record.error = outcome.reason;
         if (step.failCommentSection && outcome.kind === 'fail') {
           await args.living.appendSection(step.id, step.failCommentSection(outcome.reason, stepCtx));
+        } else if (step.unparsedCommentSection && outcome.kind !== 'fail') {
+          // Flows runtime path: agent emitted free text and onNoParse said go.
+          // Surface what the agent actually produced in the living comment.
+          await args.living.appendSection(step.id, step.unparsedCommentSection(result.text, stepCtx));
         }
         return { outcome, record };
       }
diff --git a/packages/core/src/workflows/workflow.ts b/packages/core/src/workflows/workflow.ts
index 8ee329f..81b00b2 100644
--- a/packages/core/src/workflows/workflow.ts
+++ b/packages/core/src/workflows/workflow.ts
@@ -137,6 +137,13 @@ export interface AgentStepDef<W, T> extends BaseStepDef {
   onNoParse?: (rawText: string, ctx: WorkflowStepContext<W>) => StepOutcome<W>;
   /** Render this step's section of the living comment from the parsed output. */
   commentSection?: (parsed: T, ctx: WorkflowStepContext<W>) => CommentSection;
+  /**
+   * Render this step's section when the agent emitted free text (no JSON parse)
+   * and `onNoParse` returned a success outcome (`continue` / `skip-run`). Used
+   * by the flows runtime, whose steps don't enforce a response schema. Built-in
+   * workflow steps that always produce parseable JSON can ignore this.
+   */
+  unparsedCommentSection?: (rawText: string, ctx: WorkflowStepContext<W>) => CommentSection;
   /** Render a section when the step failed (no parse / outcome=fail). */
   failCommentSection?: (reason: string, ctx: WorkflowStepContext<W>) => CommentSection;
   /** True ⇒ the engine refuses to run this step without a `worktreePath`. */
@@ -245,7 +252,13 @@ export interface WorkflowLoop<W> {
 }
 
 export interface Workflow<W> {
-  id: 'triage' | 'autofix' | 'ci-followup';
+  /**
+   * Workflow identifier. The three built-ins are `'triage' | 'autofix' | 'ci-followup'`;
+   * custom workflows compiled from `WorkflowDescriptor` (see `./compiler.ts`) carry
+   * their own string ids. The engine treats this as opaque except for the autofix
+   * unified-session gate, which compares against the literal `'autofix'`.
+   */
+  id: string;
   title: string;
   /** Pre-PR steps edit the issue comment; once a PR exists, post-PR steps edit a PR comment (docs §3.6). */
   commentTargetOrder: CommentTarget[];
diff --git a/packages/gui/src/app/api/github/webhook/route.ts b/packages/gui/src/app/api/github/webhook/route.ts
index dd54ff2..40f16fc 100644
--- a/packages/gui/src/app/api/github/webhook/route.ts
+++ b/packages/gui/src/app/api/github/webhook/route.ts
@@ -100,6 +100,8 @@ interface WebhookPayload {
   changes?: { title?: unknown; body?: unknown };
   issue?: WebhookIssue;
   pull_request?: WebhookPullRequest;
+  /** Present on `issues.labeled` — the label that was just added. */
+  label?: { name?: string };
   repository?: { name: string; owner: { login: string } };
   installation?: { id: number };
   check_run?: {
@@ -133,10 +135,13 @@ const TRIAGE_ACTIONS = new Set(['opened', 'reopened']);
 
 async function handleIssues(admin: SupabaseAdmin, payload: WebhookPayload): Promise<NextResponse> {
   const action = payload.action ?? '';
-  const relevant =
+  const isTriageRelevant =
     TRIAGE_ACTIONS.has(action) ||
     (action === 'edited' && !!payload.changes && ('title' in payload.changes || 'body' in payload.changes));
-  if (!relevant) return NextResponse.json({ ok: true, ignored: `issues.${action}` });
+  const isFlowRelevant = action === 'opened' || action === 'labeled';
+  if (!isTriageRelevant && !isFlowRelevant) {
+    return NextResponse.json({ ok: true, ignored: `issues.${action}` });
+  }
 
   const issue = payload.issue;
   const repo = payload.repository;
@@ -146,43 +151,147 @@ async function handleIssues(admin: SupabaseAdmin, payload: WebhookPayload): Prom
   if (workspaces.length === 0) return NextResponse.json({ ok: true, ignored: 'no matching workspace' });
 
   const repoSlug = `${repo.owner.login}/${repo.name}`;
-  let enqueued = 0;
+  // GitHub puts the just-added label on `payload.label` for issues.labeled.
+  const justLabeled =
+    action === 'labeled' && payload.label && typeof payload.label.name === 'string'
+      ? payload.label.name
+      : null;
+
+  let triageEnqueued = 0;
+  let flowsEnqueued = 0;
   for (const ws of workspaces) {
-    if (!ws.auto_triage_enabled) continue;
+    // Upsert the issue once per workspace either way so the issues table stays
+    // current even for flow-only triggers.
     try {
       await upsertIssueFromWebhook(admin, ws.id, issue);
     } catch (err) {
       console.error(`[github-webhook] issue upsert failed for ws ${ws.id}:`, err instanceof Error ? err.message : err);
       continue;
     }
-    // dedupe: skip if a triage job for this issue is already in flight.
+
+    // Triage path (existing behavior).
+    if (isTriageRelevant && ws.auto_triage_enabled) {
+      const { data: open } = await admin
+        .from('jobs')
+        .select('id')
+        .eq('workspace_id', ws.id)
+        .eq('kind', 'triage')
+        .eq('issue_number', issue.number)
+        .in('status', ['queued', 'claimed', 'running'])
+        .limit(1);
+      if (!open || open.length === 0) {
+        const { error } = await admin.from('jobs').insert({
+          workspace_id: ws.id,
+          repo: repoSlug,
+          kind: 'triage',
+          issue_number: issue.number,
+          pr_number: null,
+          priority: 5,
+          status: 'queued',
+          max_attempts: 1,
+          payload: { trigger: 'webhook', action },
+        });
+        if (error) {
+          console.error(`[github-webhook] triage enqueue failed for ws ${ws.id}:`, error.message);
+        } else {
+          triageEnqueued++;
+        }
+      }
+    }
+
+    // Flow auto-trigger path. Match flows whose `triggers` include
+    // `issue.opened` (on opened) or `issue.labeled` with the right label.
+    if (isFlowRelevant) {
+      flowsEnqueued += await enqueueFlowsForIssueEvent(admin, {
+        workspaceId: ws.id,
+        repoSlug,
+        issueNumber: issue.number,
+        action,
+        labelName: justLabeled,
+      });
+    }
+  }
+  return NextResponse.json({
+    ok: true,
+    triageEnqueued,
+    flowsEnqueued,
+    workspaces: workspaces.length,
+  });
+}
+
+/**
+ * For a `issues.opened` / `issues.labeled` event, find flows in `workspaceId`
+ * whose `triggers` match and enqueue one `kind='flow'` job per match. Skips
+ * flows that already have an in-flight job for this issue (dedupe).
+ */
+async function enqueueFlowsForIssueEvent(
+  admin: SupabaseAdmin,
+  args: {
+    workspaceId: string;
+    repoSlug: string;
+    issueNumber: number;
+    action: string;
+    labelName: string | null;
+  },
+): Promise<number> {
+  const { data: flows } = await admin
+    .from('flows')
+    .select('id, name, triggers, paused')
+    .eq('workspace_id', args.workspaceId)
+    .eq('paused', false);
+  if (!flows || flows.length === 0) return 0;
+
+  let enqueued = 0;
+  for (const flow of flows) {
+    const triggers = Array.isArray(flow.triggers) ? (flow.triggers as Array<Record<string, unknown>>) : [];
+    const matches = triggers.some((t) => {
+      if (!t || typeof t !== 'object') return false;
+      if (args.action === 'opened' && t.kind === 'issue.opened') return true;
+      if (args.action === 'labeled' && t.kind === 'issue.labeled') {
+        return typeof t.label === 'string' && t.label === args.labelName;
+      }
+      return false;
+    });
+    if (!matches) continue;
+
+    // Dedupe: don't double-enqueue a flow for the same issue while one's
+    // already in flight (e.g. label added, then issue edited later).
     const { data: open } = await admin
       .from('jobs')
-      .select('id')
-      .eq('workspace_id', ws.id)
-      .eq('kind', 'triage')
-      .eq('issue_number', issue.number)
-      .in('status', ['queued', 'claimed', 'running'])
-      .limit(1);
-    if (open && open.length > 0) continue;
+      .select('id, payload')
+      .eq('workspace_id', args.workspaceId)
+      .eq('kind', 'flow')
+      .eq('issue_number', args.issueNumber)
+      .in('status', ['queued', 'claimed', 'running']);
+    const alreadyForThisFlow = (open ?? []).some((row) => {
+      const p = (row.payload ?? {}) as { flowId?: string };
+      return p.flowId === flow.id;
+    });
+    if (alreadyForThisFlow) continue;
+
     const { error } = await admin.from('jobs').insert({
-      workspace_id: ws.id,
-      repo: repoSlug,
-      kind: 'triage',
-      issue_number: issue.number,
+      workspace_id: args.workspaceId,
+      repo: args.repoSlug,
+      kind: 'flow',
+      issue_number: args.issueNumber,
       pr_number: null,
       priority: 5,
       status: 'queued',
       max_attempts: 1,
-      payload: { trigger: 'webhook', action },
+      payload: {
+        trigger: 'webhook',
+        action: args.action,
+        flowId: flow.id,
+        flowInput: String(args.issueNumber),
+      },
     });
     if (error) {
-      console.error(`[github-webhook] triage enqueue failed for ws ${ws.id}:`, error.message);
+      console.error(`[github-webhook] flow '${flow.name}' enqueue failed:`, error.message);
       continue;
     }
     enqueued++;
   }
-  return NextResponse.json({ ok: true, enqueued, workspaces: workspaces.length });
+  return enqueued;
 }
 
 // ─── check_run ──────────────────────────────────────────────────────────────
diff --git a/packages/gui/src/app/api/runner/jobs/route.ts b/packages/gui/src/app/api/runner/jobs/route.ts
index 51cccec..e09255f 100644
--- a/packages/gui/src/app/api/runner/jobs/route.ts
+++ b/packages/gui/src/app/api/runner/jobs/route.ts
@@ -83,6 +83,33 @@ export async function GET(req: Request) {
       ? ((job.payload as { ciFollowup?: { issueNumber?: number } })?.ciFollowup?.issueNumber ?? job.issue_number)
       : job.issue_number;
 
+    // ── flow lookup ── For `kind='flow'` jobs the runner needs the flow's
+    //   name + steps so it can build a Workflow and call runFlow. Load the
+    //   row by `payload.flowId` here so the runner doesn't need DB access.
+    //   `workflow_runs.workflow` becomes `flow:<name>` so the cockpit labels
+    //   runner-driven flow runs the same way cron-driven ones look.
+    type FlowPayload = { flowId?: string; flowInput?: string };
+    let flowOut: { name: string; steps: import('@cezar/core').FlowStep[]; input: string } | null = null;
+    let workflowLabel: string = job.kind;
+    if (job.kind === 'flow') {
+      const payload = (job.payload ?? {}) as FlowPayload;
+      if (!payload.flowId) throw new Error('flow job missing payload.flowId');
+      const { data: flowRow, error: fErr } = await admin
+        .from('flows')
+        .select('name, steps, paused')
+        .eq('id', payload.flowId)
+        .eq('workspace_id', job.workspace_id)
+        .single();
+      if (fErr || !flowRow) throw new Error(`flow ${payload.flowId} not found: ${fErr?.message ?? 'no row'}`);
+      const parsedSteps = parseFlowSteps(flowRow.steps);
+      flowOut = {
+        name: flowRow.name,
+        steps: parsedSteps,
+        input: payload.flowInput ?? (runIssueNumber != null ? String(runIssueNumber) : ''),
+      };
+      workflowLabel = `flow:${flowRow.name}`;
+    }
+
     // ── workflow_runs row ──
     const repoSlug = owner && repo ? `${owner}/${repo}` : job.repo;
     const { data: runRow, error: runErr } = await admin
@@ -90,7 +117,7 @@ export async function GET(req: Request) {
       .insert({
         workspace_id: job.workspace_id,
         job_id: job.id,
-        workflow: job.kind,
+        workflow: workflowLabel,
         repo: repoSlug,
         issue_number: runIssueNumber ?? null,
         pr_number: job.pr_number ?? null,
@@ -125,6 +152,7 @@ export async function GET(req: Request) {
       githubToken,
       store: storeSnapshot,
       ciFollowupSeed,
+      flow: flowOut,
     });
   } catch (err) {
     await releaseJob().catch(() => {});
@@ -134,6 +162,28 @@ export async function GET(req: Request) {
   }
 }
 
+/**
+ * Defensive parser for the `flows.steps` JSONB column — keeps the runner-API
+ * contract clean even if a row was inserted by an older client. Mirrors the
+ * GUI-side `parseSteps` in `app/workflows/actions.ts`.
+ */
+function parseFlowSteps(raw: unknown): import('@cezar/core').FlowStep[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((s) => {
+      if (!s || typeof s !== 'object') return null;
+      const obj = s as Record<string, unknown>;
+      const step: import('@cezar/core').FlowStep = {
+        skill: typeof obj.skill === 'string' ? obj.skill : '',
+        argsTemplate: typeof obj.argsTemplate === 'string' ? obj.argsTemplate : '',
+      };
+      if (typeof obj.stopChainIfContains === 'string' && obj.stopChainIfContains) step.stopChainIfContains = obj.stopChainIfContains;
+      if (typeof obj.systemNotes === 'string' && obj.systemNotes) step.systemNotes = obj.systemNotes;
+      return step;
+    })
+    .filter((x): x is import('@cezar/core').FlowStep => x !== null);
+}
+
 /** Mirrors the per-workspace token lookup in the crons (`execute-workflow-job.ts`). */
 async function resolveWorkspaceToken(
   workspaceId: string,
diff --git a/packages/gui/src/app/issues/issue-row-menu.tsx b/packages/gui/src/app/issues/issue-row-menu.tsx
index 92fe6bb..a094101 100644
--- a/packages/gui/src/app/issues/issue-row-menu.tsx
+++ b/packages/gui/src/app/issues/issue-row-menu.tsx
@@ -6,6 +6,7 @@ import { MoreVerticalIcon } from '@/components/icons';
 import { RowMenuPortal } from '@/components/row-menu-portal';
 import { startAutofix } from './autofix-actions';
 import { RunActionForIssueModal } from './run-action-for-issue-modal';
+import { RunFlowForIssueModal } from './run-flow-for-issue-modal';
 
 export interface IssueRowMenuProps {
   issueNumber: number;
@@ -35,6 +36,7 @@ export function IssueRowMenu({
 }: IssueRowMenuProps) {
   const [open, setOpen] = useState(false);
   const [runActionOpen, setRunActionOpen] = useState(false);
+  const [runFlowOpen, setRunFlowOpen] = useState(false);
   const [pending, startTransition] = useTransition();
   const triggerRef = useRef<HTMLButtonElement>(null);
   const popoverRef = useRef<HTMLDivElement>(null);
@@ -99,6 +101,13 @@ export function IssueRowMenu({
       disabled: readOnly,
       group: 1,
     },
+    {
+      id: 'run-flow',
+      label: 'Run flow…',
+      onSelect: () => setRunFlowOpen(true),
+      disabled: readOnly,
+      group: 1,
+    },
     {
       id: 'open',
       label: 'Open on GitHub',
@@ -208,6 +217,13 @@ export function IssueRowMenu({
           onClose={() => setRunActionOpen(false)}
         />
       )}
+      {runFlowOpen && (
+        <RunFlowForIssueModal
+          issueNumber={issueNumber}
+          issueTitle={issueTitle}
+          onClose={() => setRunFlowOpen(false)}
+        />
+      )}
     </>
   );
 }
diff --git a/packages/gui/src/app/issues/run-flow-for-issue-modal.tsx b/packages/gui/src/app/issues/run-flow-for-issue-modal.tsx
new file mode 100644
index 0000000..535cd2d
--- /dev/null
+++ b/packages/gui/src/app/issues/run-flow-for-issue-modal.tsx
@@ -0,0 +1,192 @@
+'use client';
+
+import { useEffect, useRef, useState, useTransition } from 'react';
+import { useRouter } from 'next/navigation';
+import { cn } from '@/components/ui/cn';
+import { listFlows, runFlowOnIssue, type FlowSummary } from '@/app/workflows/actions';
+
+export interface RunFlowForIssueModalProps {
+  issueNumber: number;
+  issueTitle: string;
+  onClose: () => void;
+}
+
+/**
+ * Companion to `RunActionForIssueModal` but for flows (migration 0021). The
+ * user picks a saved flow and we queue it as a `kind='flow'` job pinned to
+ * this issue. On success we redirect to /cockpit so the user sees the run
+ * appear — matching `startAutofix`'s "redirect to /cockpit" pattern.
+ */
+export function RunFlowForIssueModal({ issueNumber, issueTitle, onClose }: RunFlowForIssueModalProps) {
+  const router = useRouter();
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const lastFocused = useRef<HTMLElement | null>(null);
+  const [flows, setFlows] = useState<FlowSummary[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [selectedId, setSelectedId] = useState<string>('');
+  const [error, setError] = useState<string | null>(null);
+  const [pending, startTransition] = useTransition();
+
+  useEffect(() => {
+    lastFocused.current = document.activeElement as HTMLElement | null;
+    const node = dialogRef.current;
+    const focusables = node?.querySelectorAll<HTMLElement>(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+    );
+    focusables?.[0]?.focus();
+
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      const items = Array.from(
+        node?.querySelectorAll<HTMLElement>(
+          'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+        ) ?? [],
+      );
+      if (items.length === 0) return;
+      const first = items[0];
+      const last = items[items.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      lastFocused.current?.focus?.();
+    };
+  }, [onClose]);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      const rows = await listFlows();
+      if (cancelled) return;
+      // Hide paused flows + ones with no steps — can't run them anyway.
+      const runnable = rows.filter((f) => !f.paused && f.steps.length > 0);
+      setFlows(runnable);
+      setLoading(false);
+      if (runnable.length > 0) setSelectedId(runnable[0].id);
+    })().catch(() => setLoading(false));
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  function handleRun() {
+    setError(null);
+    if (!selectedId) {
+      setError('Pick a flow');
+      return;
+    }
+    startTransition(async () => {
+      const r = await runFlowOnIssue({ flowId: selectedId, issueNumber });
+      if (!r.ok) {
+        setError(r.error ?? 'Run failed');
+        return;
+      }
+      onClose();
+      router.push('/cockpit');
+    });
+  }
+
+  const selected = flows.find((f) => f.id === selectedId);
+
+  return (
+    <div
+      role="presentation"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
+    >
+      <div
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="run-flow-title"
+        className="w-full max-w-lg rounded-lg border border-outline-variant bg-surface-container-low p-5 shadow-xl"
+      >
+        <h2 id="run-flow-title" className="text-base font-semibold text-on-surface">
+          Run flow on #{issueNumber}
+        </h2>
+        <p className="mt-1 truncate text-xs text-on-surface-variant">{issueTitle}</p>
+
+        <div className="mt-4 space-y-2">
+          <label className="block text-[11px] font-medium uppercase tracking-wide text-on-surface-variant">
+            Flow
+          </label>
+          {loading ? (
+            <p className="text-xs text-on-surface-variant">Loading flows…</p>
+          ) : flows.length === 0 ? (
+            <p className="text-xs text-on-surface-variant">
+              No runnable flows. Visit{' '}
+              <a className="text-primary hover:underline" href="/workflows">/workflows</a>{' '}
+              to create one.
+            </p>
+          ) : (
+            <select
+              value={selectedId}
+              onChange={(e) => setSelectedId(e.target.value)}
+              className="block w-full rounded-md border border-outline-variant bg-surface-container px-2 py-1.5 text-sm text-on-surface focus:border-primary/50 focus:outline-none"
+            >
+              {flows.map((f) => (
+                <option key={f.id} value={f.id}>
+                  {f.name} ({f.steps.length} step{f.steps.length === 1 ? '' : 's'})
+                </option>
+              ))}
+            </select>
+          )}
+          {selected && selected.steps.length > 0 && (
+            <div className="mt-2 rounded-md border border-outline-variant/60 bg-surface-container/60 p-2">
+              <div className="text-[11px] uppercase tracking-wide text-on-surface-variant">Steps</div>
+              <ol className="mt-1 list-decimal pl-5 text-xs text-on-surface space-y-0.5">
+                {selected.steps.map((s, i) => (
+                  <li key={i}>
+                    <span className="font-mono">{s.skill || '(no skill)'}</span>{' '}
+                    <span className="text-on-surface-variant">→ {s.argsTemplate}</span>
+                  </li>
+                ))}
+              </ol>
+            </div>
+          )}
+        </div>
+
+        {error && (
+          <div className="mt-3 rounded-md border border-rose-500/30 bg-rose-500/10 px-2 py-1.5 text-xs text-rose-300">
+            {error}
+          </div>
+        )}
+
+        <div className="mt-5 flex justify-end gap-2">
+          <button
+            type="button"
+            onClick={onClose}
+            className="rounded-md border border-outline-variant bg-surface-container px-3 py-1.5 text-sm text-on-surface hover:bg-surface-container-high"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleRun}
+            disabled={pending || !selectedId || flows.length === 0}
+            className={cn(
+              'rounded-md border border-primary/50 bg-primary/10 px-3 py-1.5 text-sm font-medium text-on-surface',
+              'hover:bg-primary/20 disabled:cursor-not-allowed disabled:opacity-50',
+            )}
+          >
+            {pending ? 'Queueing…' : 'Run on this issue'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/gui/src/app/workflows/actions.ts b/packages/gui/src/app/workflows/actions.ts
new file mode 100644
index 0000000..fea69aa
--- /dev/null
+++ b/packages/gui/src/app/workflows/actions.ts
@@ -0,0 +1,511 @@
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import {
+  discoverSkills,
+  renderTemplate,
+  FLOW_STEP_SCAFFOLDING,
+  DEFAULT_STEP_NOTES,
+  effectiveStepNotes,
+} from '@cezar/core';
+import { createSupabaseAdminClient } from '@/lib/supabase/server';
+import { getActiveWorkspace } from '@/lib/workspace';
+import { loadWorkspaceConfig } from '@/lib/load-workspace-config';
+import { ensureRepoClone } from '@/lib/repo-clone';
+import type { Database } from '@/lib/supabase/types';
+
+/**
+ * Server actions backing the `/workflows` page — CRUD for the simple `flows`
+ * table (migration 0021) + the auto-triggers (migration 0022) + the
+ * "Run on issue #" entry point + a server-side prompt preview helper.
+ */
+
+export type ActionResult<T = {}> = (T & { ok: true }) | { ok: false; error: string };
+
+export interface FlowStep {
+  skill: string;
+  argsTemplate: string;
+  /**
+   * When set, after the step runs the engine checks if its text output
+   * contains this substring; if it does, the chain stops cleanly with status
+   * `succeeded` and reason "stopped at step N". A simple short-circuit for
+   * skills that legitimately decide "no action needed".
+   */
+  stopChainIfContains?: string;
+  /**
+   * Extra system-prompt content prepended to the skill body. When unset
+   * (or whitespace-only), a built-in default explaining the `PR_URL=` /
+   * `PR_NUMBER=` marker contract is used. Set to override per step.
+   */
+  systemNotes?: string;
+}
+
+export type FlowTrigger =
+  | { kind: 'issue.opened' }
+  | { kind: 'issue.labeled'; label: string };
+
+export interface SkillSummary {
+  name: string;
+  /** First line of the skill's frontmatter `description` field; empty when none. */
+  description: string;
+}
+
+export interface FlowStepOutcome {
+  stepId: string;
+  status: string;
+  iteration: number;
+  /** Best-effort: error, summary, or tail of the agent's text output. */
+  output: string;
+}
+
+export interface FlowRecentRun {
+  id: string;
+  status: string;
+  issueNumber: number | null;
+  startedAt: string;
+}
+
+export interface FlowStats {
+  /** Total runs in the last 7 days. */
+  totalLast7d: number;
+  /** Runs whose status is 'succeeded' in the last 7 days. */
+  succeededLast7d: number;
+  /** Average cost-weighted tokens per run over the last 7 days (0 when no runs). */
+  avgTokens: number;
+}
+
+export interface FlowSummary {
+  id: string;
+  name: string;
+  steps: FlowStep[];
+  triggers: FlowTrigger[];
+  paused: boolean;
+  updatedAt: string;
+  /** Most recent workflow_runs row whose `workflow` matches `flow:<name>` — with per-step output snippets. */
+  lastRun?: {
+    id: string;
+    status: string;
+    issueNumber: number | null;
+    startedAt: string;
+    finishedAt: string | null;
+    reason: string | null;
+    steps: FlowStepOutcome[];
+  };
+  /** Lightweight pills for the at-a-glance history strip (up to 5, newest first). */
+  recentRuns: FlowRecentRun[];
+  /** 7-day stats — success rate + avg tokens. */
+  stats: FlowStats;
+}
+
+// ─── Read ────────────────────────────────────────────────────────────────────
+
+export async function listFlows(): Promise<FlowSummary[]> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return [];
+  const supabase = createSupabaseAdminClient();
+
+  const { data: rows, error } = await supabase
+    .from('flows')
+    .select('id, name, steps, triggers, paused, updated_at')
+    .eq('workspace_id', workspace.id)
+    .order('updated_at', { ascending: false });
+  if (error || !rows) return [];
+
+  const workflowKeys = rows.map((r) => `flow:${r.name}`);
+  const lastRuns = new Map<string, FlowSummary['lastRun']>();
+  const recentByWorkflow = new Map<string, FlowRecentRun[]>();
+  const statsByWorkflow = new Map<string, FlowStats>();
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+  if (workflowKeys.length > 0) {
+    const { data: runs } = await supabase
+      .from('workflow_runs')
+      .select('id, workflow, status, issue_number, started_at, finished_at, reason, tokens_used')
+      .eq('workspace_id', workspace.id)
+      .in('workflow', workflowKeys)
+      .order('started_at', { ascending: false });
+    if (runs) {
+      // Group runs by workflow (descending), and tally stats over the 7-day window.
+      const seenLatest = new Set<string>();
+      const latestRunIds: string[] = []; // for the per-step output query (only the most-recent per workflow)
+      for (const run of runs) {
+        const key = run.workflow;
+        const list = recentByWorkflow.get(key) ?? [];
+        if (list.length < 5) list.push({
+          id: run.id,
+          status: run.status,
+          issueNumber: run.issue_number,
+          startedAt: run.started_at,
+        });
+        recentByWorkflow.set(key, list);
+        if (!seenLatest.has(key)) {
+          seenLatest.add(key);
+          latestRunIds.push(run.id);
+        }
+        if (run.started_at >= sevenDaysAgo) {
+          const cur = statsByWorkflow.get(key) ?? { totalLast7d: 0, succeededLast7d: 0, avgTokens: 0 };
+          cur.totalLast7d += 1;
+          if (run.status === 'succeeded') cur.succeededLast7d += 1;
+          // running average — we'll finalize by dividing once at the end.
+          cur.avgTokens += run.tokens_used ?? 0;
+          statsByWorkflow.set(key, cur);
+        }
+      }
+      for (const [, s] of statsByWorkflow) {
+        s.avgTokens = s.totalLast7d > 0 ? Math.round(s.avgTokens / s.totalLast7d) : 0;
+      }
+
+      // Per-step output snippet — only fetched for the most-recent run per
+      // workflow (everything else is "open in cockpit"). Keeps this query tight.
+      const stepRowsByRun = new Map<string, Array<{ id: string; stepId: string; status: string; iteration: number; summary: string | null; error: string | null }>>();
+      const stepIdsForEventQuery: string[] = [];
+      if (latestRunIds.length > 0) {
+        const { data: ar } = await supabase
+          .from('agent_runs')
+          .select('id, workflow_run_id, step_id, status, iteration, started_at, summary, error')
+          .in('workflow_run_id', latestRunIds)
+          .order('started_at', { ascending: true });
+        for (const row of ar ?? []) {
+          const list = stepRowsByRun.get(row.workflow_run_id) ?? [];
+          list.push({ id: row.id, stepId: row.step_id, status: row.status, iteration: row.iteration, summary: row.summary, error: row.error });
+          stepRowsByRun.set(row.workflow_run_id, list);
+          stepIdsForEventQuery.push(row.id);
+        }
+      }
+
+      const textByAgentRun = new Map<string, string>();
+      if (stepIdsForEventQuery.length > 0) {
+        const { data: events } = await supabase
+          .from('agent_run_events')
+          .select('agent_run_id, payload, type, created_at')
+          .in('agent_run_id', stepIdsForEventQuery)
+          .eq('type', 'agent-text')
+          .order('created_at', { ascending: true });
+        for (const ev of events ?? []) {
+          const payload = (ev.payload ?? {}) as { text?: unknown };
+          if (typeof payload.text !== 'string' || !ev.agent_run_id) continue;
+          textByAgentRun.set(ev.agent_run_id, (textByAgentRun.get(ev.agent_run_id) ?? '') + payload.text);
+        }
+      }
+
+      for (const run of runs) {
+        if (lastRuns.has(run.workflow)) continue;
+        const steps = (stepRowsByRun.get(run.id) ?? []).map<FlowStepOutcome>((s) => {
+          let output = '';
+          if (s.status === 'failed' && s.error) output = s.error;
+          else if (s.status === 'skipped' && s.summary) output = s.summary;
+          else {
+            const text = textByAgentRun.get(s.id) ?? '';
+            output = text.length > 240 ? '…' + text.slice(-240) : text;
+          }
+          return { stepId: s.stepId, status: s.status, iteration: s.iteration, output };
+        });
+        lastRuns.set(run.workflow, {
+          id: run.id,
+          status: run.status,
+          issueNumber: run.issue_number,
+          startedAt: run.started_at,
+          finishedAt: run.finished_at,
+          reason: run.reason,
+          steps,
+        });
+      }
+    }
+  }
+
+  return rows.map((row) => {
+    const key = `flow:${row.name}`;
+    return {
+      id: row.id,
+      name: row.name,
+      steps: parseSteps(row.steps),
+      triggers: parseTriggers(row.triggers),
+      paused: row.paused,
+      updatedAt: row.updated_at,
+      lastRun: lastRuns.get(key),
+      recentRuns: recentByWorkflow.get(key) ?? [],
+      stats: statsByWorkflow.get(key) ?? { totalLast7d: 0, succeededLast7d: 0, avgTokens: 0 },
+    };
+  });
+}
+
+function parseSteps(raw: unknown): FlowStep[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((s) => {
+      if (!s || typeof s !== 'object') return null;
+      const obj = s as Record<string, unknown>;
+      const step: FlowStep = {
+        skill: typeof obj.skill === 'string' ? obj.skill : '',
+        argsTemplate: typeof obj.argsTemplate === 'string' ? obj.argsTemplate : '',
+      };
+      if (typeof obj.stopChainIfContains === 'string' && obj.stopChainIfContains) {
+        step.stopChainIfContains = obj.stopChainIfContains;
+      }
+      if (typeof obj.systemNotes === 'string' && obj.systemNotes) {
+        step.systemNotes = obj.systemNotes;
+      }
+      return step;
+    })
+    .filter((x): x is FlowStep => x !== null);
+}
+
+function parseTriggers(raw: unknown): FlowTrigger[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((t): FlowTrigger | null => {
+      if (!t || typeof t !== 'object') return null;
+      const obj = t as Record<string, unknown>;
+      if (obj.kind === 'issue.opened') return { kind: 'issue.opened' };
+      if (obj.kind === 'issue.labeled' && typeof obj.label === 'string') {
+        return { kind: 'issue.labeled', label: obj.label };
+      }
+      return null;
+    })
+    .filter((x): x is FlowTrigger => x !== null);
+}
+
+// ─── Write ──────────────────────────────────────────────────────────────────
+
+export async function upsertFlow(params: {
+  id?: string;
+  name: string;
+  steps: FlowStep[];
+  triggers: FlowTrigger[];
+  paused?: boolean;
+}): Promise<ActionResult<{ id: string }>> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return { ok: false, error: 'no active workspace' };
+  if (workspace.role === 'viewer') return { ok: false, error: 'viewers cannot edit flows' };
+  if (!params.name.trim()) return { ok: false, error: 'name is required' };
+
+  const supabase = createSupabaseAdminClient();
+  const row: Database['public']['Tables']['flows']['Insert'] = {
+    workspace_id: workspace.id,
+    name: params.name.trim(),
+    steps: params.steps as unknown as Database['public']['Tables']['flows']['Insert']['steps'],
+    triggers: params.triggers as unknown as Database['public']['Tables']['flows']['Insert']['triggers'],
+  };
+  if (params.paused !== undefined) row.paused = params.paused;
+
+  if (params.id) {
+    const { error } = await supabase
+      .from('flows')
+      .update({ ...row, updated_at: new Date().toISOString() })
+      .eq('id', params.id)
+      .eq('workspace_id', workspace.id);
+    if (error) return { ok: false, error: error.message };
+    revalidatePath('/workflows');
+    return { ok: true, id: params.id };
+  }
+
+  const { data, error } = await supabase
+    .from('flows')
+    .insert(row)
+    .select('id')
+    .single();
+  if (error || !data) return { ok: false, error: error?.message ?? 'insert failed' };
+  revalidatePath('/workflows');
+  return { ok: true, id: data.id };
+}
+
+export async function setFlowPaused(id: string, paused: boolean): Promise<ActionResult> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return { ok: false, error: 'no active workspace' };
+  if (workspace.role === 'viewer') return { ok: false, error: 'viewers cannot pause flows' };
+  const supabase = createSupabaseAdminClient();
+  const { error } = await supabase
+    .from('flows')
+    .update({ paused, updated_at: new Date().toISOString() })
+    .eq('id', id)
+    .eq('workspace_id', workspace.id);
+  if (error) return { ok: false, error: error.message };
+  revalidatePath('/workflows');
+  return { ok: true };
+}
+
+export async function deleteFlow(id: string): Promise<ActionResult> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return { ok: false, error: 'no active workspace' };
+  if (workspace.role === 'viewer') return { ok: false, error: 'viewers cannot delete flows' };
+  const supabase = createSupabaseAdminClient();
+  const { error } = await supabase
+    .from('flows')
+    .delete()
+    .eq('id', id)
+    .eq('workspace_id', workspace.id);
+  if (error) return { ok: false, error: error.message };
+  revalidatePath('/workflows');
+  return { ok: true };
+}
+
+export async function runFlowOnIssue(params: {
+  flowId: string;
+  issueNumber: number;
+}): Promise<ActionResult<{ jobId: string }>> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return { ok: false, error: 'no active workspace' };
+  if (workspace.role === 'viewer') return { ok: false, error: 'viewers cannot start runs' };
+  if (!Number.isInteger(params.issueNumber) || params.issueNumber <= 0) {
+    return { ok: false, error: 'issue number must be a positive integer' };
+  }
+
+  const supabase = createSupabaseAdminClient();
+  const { data: flow } = await supabase
+    .from('flows')
+    .select('id')
+    .eq('id', params.flowId)
+    .eq('workspace_id', workspace.id)
+    .single();
+  if (!flow) return { ok: false, error: 'flow not found' };
+
+  const repo = workspace.repoOwner && workspace.repoName
+    ? `${workspace.repoOwner}/${workspace.repoName}`
+    : null;
+
+  const { data: job, error } = await supabase
+    .from('jobs')
+    .insert({
+      workspace_id: workspace.id,
+      repo,
+      kind: 'flow',
+      issue_number: params.issueNumber,
+      pr_number: null,
+      priority: 10,
+      status: 'queued',
+      max_attempts: 1,
+      payload: {
+        trigger: 'manual',
+        flowId: params.flowId,
+        flowInput: String(params.issueNumber),
+      },
+    })
+    .select('id')
+    .single();
+  if (error || !job) return { ok: false, error: error?.message ?? 'enqueue failed' };
+
+  revalidatePath('/workflows');
+  revalidatePath('/cockpit');
+  return { ok: true, jobId: job.id };
+}
+
+// ─── Skill catalog with descriptions ────────────────────────────────────────
+
+export async function listAvailableSkills(): Promise<SkillSummary[]> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return [];
+  const supabase = createSupabaseAdminClient();
+  const { data } = await supabase
+    .from('repo_skills')
+    .select('skills')
+    .eq('workspace_id', workspace.id);
+  if (!data) return [];
+  const byName = new Map<string, SkillSummary>();
+  for (const row of data) {
+    const arr = (row.skills as Array<Record<string, unknown>> | null) ?? [];
+    for (const s of arr) {
+      if (!s || typeof s.name !== 'string' || !s.name.trim()) continue;
+      const description =
+        typeof s.description === 'string'
+          ? s.description.split('\n')[0].trim().slice(0, 240)
+          : '';
+      // First write wins (repo_skills is one row per repo; for multi-repo
+      // workspaces, skills across repos with the same name are de-duped here).
+      if (!byName.has(s.name)) byName.set(s.name, { name: s.name, description });
+    }
+  }
+  return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ─── Prompt preview ─────────────────────────────────────────────────────────
+
+export interface PreviewResult {
+  stepNumber: number;
+  skill: string;
+  /** Generic flow-step scaffolding (constant). */
+  scaffoldingSystemPrompt: string;
+  /** Effective step notes — either the user's override or DEFAULT_STEP_NOTES. */
+  stepNotes: string;
+  /** True when `stepNotes` came from the built-in default (user hasn't overridden). */
+  stepNotesIsDefault: boolean;
+  /** The default text — useful for the editor's placeholder. */
+  defaultStepNotes: string;
+  /** Just the skill body — UI appends this to scaffolding for the "what the agent sees" view. */
+  skillBody: string;
+  /** Empty when the skill couldn't be found in the workspace's repo. */
+  skillBodyMissing: boolean;
+  userPrompt: string;
+}
+
+export async function renderStepPreview(params: {
+  flowId: string;
+  stepIdx: number;
+  sampleInput: string;
+  samplePrevTaskId: string;
+  samplePrevPrUrl: string;
+  samplePrevPrNumber: string;
+}): Promise<ActionResult<PreviewResult>> {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) return { ok: false, error: 'no active workspace' };
+  const supabase = createSupabaseAdminClient();
+
+  const { data: flow, error } = await supabase
+    .from('flows')
+    .select('steps')
+    .eq('id', params.flowId)
+    .eq('workspace_id', workspace.id)
+    .single();
+  if (error || !flow) return { ok: false, error: 'flow not found' };
+
+  const steps = parseSteps(flow.steps);
+  const step = steps[params.stepIdx];
+  if (!step) return { ok: false, error: `step ${params.stepIdx + 1} not found` };
+
+  const userPrompt = renderTemplate(step.argsTemplate, {
+    input: params.sampleInput,
+    previousTaskId: params.samplePrevTaskId,
+    previousPullRequestUrl: params.samplePrevPrUrl,
+    previousPullRequestNumber: params.samplePrevPrNumber,
+  });
+
+  // Try to read the skill body from the workspace's cloned repo. Best-effort —
+  // when the clone isn't materialized yet, we still return the rendered user
+  // prompt so the UI shows the args part of the preview.
+  let skillBody = '';
+  let skillBodyMissing = true;
+  try {
+    const config = await loadWorkspaceConfig(workspace.id, supabase, {});
+    if (!config.autofix.repoRoot && config.github.owner && config.github.repo) {
+      config.autofix.repoRoot = await ensureRepoClone(
+        config.github.owner,
+        config.github.repo,
+        config.github.token,
+        config.autofix.baseBranch,
+      );
+    }
+    if (config.autofix.repoRoot) {
+      const skills = await discoverSkills(config.autofix.repoRoot, config.autofix.skillsDir ?? '.ai/skills');
+      const hit = skills.find((s) => s.name === step.skill);
+      if (hit) {
+        skillBody = hit.body;
+        skillBodyMissing = false;
+      }
+    }
+  } catch {
+    // swallow — surface as `skillBodyMissing` and let the UI degrade gracefully.
+  }
+
+  const trimmed = (step.systemNotes ?? '').trim();
+  const stepNotes = effectiveStepNotes(step);
+  return {
+    ok: true,
+    stepNumber: params.stepIdx + 1,
+    skill: step.skill,
+    scaffoldingSystemPrompt: FLOW_STEP_SCAFFOLDING,
+    stepNotes,
+    stepNotesIsDefault: trimmed.length === 0,
+    defaultStepNotes: DEFAULT_STEP_NOTES,
+    skillBody,
+    skillBodyMissing,
+    userPrompt,
+  };
+}
diff --git a/packages/gui/src/app/workflows/flow-card.tsx b/packages/gui/src/app/workflows/flow-card.tsx
new file mode 100644
index 0000000..dd8e891
--- /dev/null
+++ b/packages/gui/src/app/workflows/flow-card.tsx
@@ -0,0 +1,1054 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState, useTransition, type KeyboardEvent } from 'react';
+import {
+  renderStepPreview,
+  type FlowStep,
+  type FlowStepOutcome,
+  type FlowSummary,
+  type FlowTrigger,
+  type PreviewResult,
+} from './actions';
+
+/**
+ * Mirrors `DEFAULT_STEP_NOTES` in `@/lib/flow-runner` — kept here as a literal
+ * so the client bundle doesn't pull node-only deps. Update both together.
+ */
+const DEFAULT_STEP_NOTES_TEXT = `If you open a pull request, end your response with two lines on separate lines:
+  PR_URL=<the PR url>
+  PR_NUMBER=<the PR number>
+so the next step in the workflow can reference it via {{previousPullRequestUrl}} / {{previousPullRequestNumber}}.`;
+
+export interface SkillOption {
+  name: string;
+  description: string;
+}
+
+export interface FlowCardProps {
+  flow: FlowSummary;
+  canWrite: boolean;
+  availableSkills: SkillOption[];
+  onNameChange: (name: string) => void;
+  onStepChange: (idx: number, patch: Partial<FlowStep>) => void;
+  onAddStep: () => void;
+  onRemoveStep: (idx: number) => void;
+  onMoveStepDown: (idx: number) => void;
+  onTriggersChange: (triggers: FlowTrigger[]) => void;
+  onPausedChange: (paused: boolean) => void;
+  onDelete: () => void;
+  onRun: (issue: number) => void;
+  onOpenRun: () => void;
+}
+
+const TEMPLATE_VARS = [
+  { name: 'input', label: '{{input}}', hint: 'value passed when the flow runs' },
+  { name: 'previousTaskId', label: '{{previousTaskId}}', hint: 'previous step\'s agent_runs.id' },
+  { name: 'previousPullRequestUrl', label: '{{previousPullRequestUrl}}', hint: 'PR url from previous step (if any)' },
+  { name: 'previousPullRequestNumber', label: '{{previousPullRequestNumber}}', hint: 'PR number from previous step (if any)' },
+] as const;
+
+const PR_CREATING_PATTERN = /(fix|open|create|pr|pull|merge|raise)/i;
+
+export function FlowCard(props: FlowCardProps) {
+  const { flow } = props;
+
+  return (
+    <div
+      className={
+        'rounded-lg border bg-bg-elevated p-4 ' +
+        (flow.paused ? 'border-border/60 opacity-90' : 'border-border')
+      }
+    >
+      {/* Name + pause toggle + flow actions */}
+      <div className="flex items-end gap-3">
+        <div className="flex-1">
+          <label className="block text-[11px] font-medium uppercase tracking-wide text-fg-muted">
+            Name
+          </label>
+          <input
+            type="text"
+            value={flow.name}
+            onChange={(e) => props.onNameChange(e.target.value)}
+            disabled={!props.canWrite}
+            className="mt-1 w-full rounded-md border border-border bg-bg-subtle px-3 py-2 text-sm text-fg focus:border-accent/50 focus:outline-none"
+            placeholder="fix github issue"
+          />
+        </div>
+        {props.canWrite && (
+          <>
+            <PauseToggle
+              paused={flow.paused}
+              onChange={props.onPausedChange}
+            />
+            <button
+              onClick={props.onAddStep}
+              className="inline-flex items-center gap-1 rounded-md border border-border bg-bg-subtle px-3 py-2 text-sm text-fg hover:bg-bg"
+            >
+              <PlusIcon /> Step
+            </button>
+            <button
+              onClick={props.onDelete}
+              aria-label="Delete flow"
+              className="rounded-md border border-border bg-bg-subtle px-2 py-2 text-rose-400 hover:bg-rose-500/10"
+            >
+              <TrashIcon />
+            </button>
+          </>
+        )}
+      </div>
+
+      {/* Stats + history strip */}
+      {!flow.id.startsWith('__new__') && (flow.recentRuns.length > 0 || flow.stats.totalLast7d > 0) && (
+        <div className="mt-3 flex flex-wrap items-center gap-2">
+          {flow.stats.totalLast7d > 0 && (
+            <span
+              className="rounded bg-bg-subtle px-1.5 py-0.5 text-[11px] text-fg-muted"
+              title="Successful runs in the last 7 days"
+            >
+              ✓ <span className="text-fg">{flow.stats.succeededLast7d}/{flow.stats.totalLast7d}</span>{' '}
+              <span className="text-fg-muted/60">(7d)</span>
+            </span>
+          )}
+          {flow.stats.avgTokens > 0 && (
+            <span
+              className="rounded bg-bg-subtle px-1.5 py-0.5 text-[11px] text-fg-muted"
+              title="Average cost-weighted tokens per run, last 7 days"
+            >
+              ~<span className="text-fg">{formatTokens(flow.stats.avgTokens)}</span> tokens/run
+            </span>
+          )}
+          {flow.recentRuns.length > 0 && (
+            <span className="ml-1 flex items-center gap-1">
+              <span className="text-[10px] uppercase tracking-wide text-fg-muted/60">recent</span>
+              {flow.recentRuns.map((r) => (
+                <a
+                  key={r.id}
+                  href={`/cockpit/${r.id}`}
+                  title={`${r.status}${r.issueNumber != null ? ` · #${r.issueNumber}` : ''} · ${new Date(r.startedAt).toLocaleString()}`}
+                  className={`inline-block h-3 w-3 rounded-sm ${historyDotClass(r.status)}`}
+                />
+              ))}
+            </span>
+          )}
+          {flow.paused && (
+            <span className="ml-auto rounded bg-amber-500/15 px-1.5 py-0.5 text-[11px] font-medium text-amber-300">
+              paused
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Triggers panel */}
+      <TriggersPanel
+        triggers={flow.triggers}
+        canWrite={props.canWrite}
+        onChange={props.onTriggersChange}
+      />
+
+      {/* Steps */}
+      <div className="mt-4 space-y-2">
+        {flow.steps.length === 0 ? (
+          <p className="text-xs text-fg-muted">
+            No steps yet. {props.canWrite && 'Click "+ Step" to add one.'}
+          </p>
+        ) : (
+          <div className="space-y-2">
+            <div className="grid grid-cols-[auto_minmax(220px,1fr)_minmax(220px,2fr)_auto_auto] gap-3 px-1 text-[11px] font-medium uppercase tracking-wide text-fg-muted">
+              <div>Step</div>
+              <div>Skill</div>
+              <div>Args template</div>
+              <div></div>
+              <div></div>
+            </div>
+            {flow.steps.map((step, idx) => (
+              <StepRow
+                key={idx}
+                step={step}
+                idx={idx}
+                steps={flow.steps}
+                flowId={flow.id}
+                canWrite={props.canWrite}
+                availableSkills={props.availableSkills}
+                stepOutcome={flow.lastRun?.steps.find((s) => s.stepId === `step-${idx + 1}`)}
+                onChange={(patch) => props.onStepChange(idx, patch)}
+                onRemove={() => props.onRemoveStep(idx)}
+                onMoveDown={() => props.onMoveStepDown(idx)}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Run on issue + most-recent run summary */}
+      {!flow.id.startsWith('__new__') && (
+        <div className="mt-4 flex flex-wrap items-center justify-between gap-3 border-t border-border pt-3">
+          {props.canWrite ? (
+            <RunOnIssue onRun={props.onRun} />
+          ) : (
+            <span className="text-xs text-fg-muted">Viewers can&apos;t start runs.</span>
+          )}
+          {flow.lastRun && (
+            <div className="flex items-center gap-2 text-xs">
+              <StatusBadge status={flow.lastRun.status} />
+              <span className="text-fg-muted">
+                {flow.lastRun.issueNumber != null ? `#${flow.lastRun.issueNumber}` : ''}
+                {' · '}
+                {new Date(flow.lastRun.startedAt).toLocaleString()}
+              </span>
+              {flow.lastRun.reason && (
+                <span className="text-fg-muted" title={flow.lastRun.reason}>
+                  · {flow.lastRun.reason.slice(0, 80)}
+                  {flow.lastRun.reason.length > 80 ? '…' : ''}
+                </span>
+              )}
+              <button onClick={props.onOpenRun} className="text-accent hover:underline">
+                Open →
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ─── Pause toggle ───────────────────────────────────────────────────────────
+
+function PauseToggle({ paused, onChange }: { paused: boolean; onChange: (v: boolean) => void }) {
+  return (
+    <button
+      type="button"
+      onClick={() => onChange(!paused)}
+      aria-pressed={!paused}
+      title={paused ? 'Resume auto-triggers' : 'Pause auto-triggers'}
+      className={
+        'inline-flex items-center gap-1.5 rounded-md border px-2.5 py-2 text-xs font-medium transition ' +
+        (paused
+          ? 'border-amber-500/40 bg-amber-500/10 text-amber-300 hover:bg-amber-500/15'
+          : 'border-emerald-500/40 bg-emerald-500/10 text-emerald-400 hover:bg-emerald-500/15')
+      }
+    >
+      <span className={`inline-block h-2 w-2 rounded-full ${paused ? 'bg-amber-400' : 'bg-emerald-400'}`} />
+      {paused ? 'Paused' : 'Active'}
+    </button>
+  );
+}
+
+// ─── Step notes (pencil disclosure) ────────────────────────────────────────
+
+function StepNotesPanel({
+  value,
+  disabled,
+  onChange,
+}: {
+  value: string;
+  disabled: boolean;
+  onChange: (v: string) => void;
+}) {
+  const overriding = value.trim().length > 0;
+  return (
+    <div className="mt-2 rounded-md border border-border bg-bg p-3">
+      <div className="mb-1 flex items-center justify-between text-[10px] uppercase tracking-wide">
+        <span className="text-fg-muted">Step notes — extra system-prompt content</span>
+        <span className={overriding ? 'text-accent' : 'text-fg-muted/70'}>
+          {overriding ? 'overriding default' : 'using default'}
+        </span>
+      </div>
+      <textarea
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        placeholder={DEFAULT_STEP_NOTES_TEXT}
+        spellCheck={false}
+        rows={6}
+        className="block w-full resize-y rounded-md border border-border/60 bg-bg-subtle px-2 py-1.5 font-mono text-[11px] leading-relaxed text-fg placeholder:text-fg-muted/60 focus:border-accent/50 focus:outline-none"
+      />
+      <p className="mt-1 text-[10px] text-fg-muted/80">
+        Prepended to the skill body at run time. Leave empty to use the default (the `PR_URL=` / `PR_NUMBER=` marker contract).
+      </p>
+    </div>
+  );
+}
+
+// ─── Stop-chain input ───────────────────────────────────────────────────────
+
+function StopChainInput({
+  value,
+  disabled,
+  onChange,
+}: {
+  value: string;
+  disabled: boolean;
+  onChange: (v: string) => void;
+}) {
+  const empty = !value;
+  return (
+    <div className="mt-1 flex items-center gap-1.5 px-1">
+      <span className={`text-[10px] uppercase tracking-wide ${empty ? 'text-fg-muted/60' : 'text-amber-300/80'}`}>
+        Stop chain if output contains
+      </span>
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        placeholder="NO_ACTION_NEEDED"
+        className={
+          'flex-1 rounded border border-border bg-bg-subtle px-1.5 py-0.5 font-mono text-[11px] text-fg focus:border-accent/50 focus:outline-none ' +
+          (empty ? 'opacity-60 focus:opacity-100' : '')
+        }
+      />
+    </div>
+  );
+}
+
+// ─── Helpers (formatting + history dots) ────────────────────────────────────
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+function historyDotClass(status: string): string {
+  if (status === 'succeeded') return 'bg-emerald-500/70';
+  if (status === 'failed') return 'bg-rose-500/70';
+  if (status === 'running') return 'bg-amber-400/80';
+  if (status === 'cancelled') return 'bg-fg-muted/40';
+  if (status === 'paused') return 'bg-amber-300/60';
+  return 'bg-fg-muted/40';
+}
+
+// ─── Step row (with autocomplete, lint, preview, output) ────────────────────
+
+function StepRow(props: {
+  step: FlowStep;
+  idx: number;
+  steps: FlowStep[];
+  flowId: string;
+  canWrite: boolean;
+  availableSkills: SkillOption[];
+  stepOutcome?: FlowStepOutcome;
+  onChange: (patch: Partial<FlowStep>) => void;
+  onRemove: () => void;
+  onMoveDown: () => void;
+}) {
+  const { step, idx } = props;
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const [outputOpen, setOutputOpen] = useState(false);
+  const [notesOpen, setNotesOpen] = useState(false);
+
+  const skillDescription = useMemo(
+    () => props.availableSkills.find((s) => s.name === step.skill)?.description ?? '',
+    [props.availableSkills, step.skill],
+  );
+
+  const lintWarnings = useMemo(
+    () => lintArgsTemplate(step.argsTemplate, idx, props.steps),
+    [step.argsTemplate, idx, props.steps],
+  );
+
+  return (
+    <div className="rounded-md border border-border/60 bg-bg-subtle/40 p-2">
+      <div className="grid grid-cols-[auto_minmax(220px,1fr)_minmax(220px,2fr)_auto_auto] items-start gap-3">
+        <div className="rounded-md border border-border bg-bg-subtle px-3 py-2 text-sm text-fg-muted">
+          Step {idx + 1}
+        </div>
+        <div>
+          <SkillPicker
+            value={step.skill}
+            options={props.availableSkills}
+            onChange={(skill) => props.onChange({ skill })}
+            disabled={!props.canWrite}
+          />
+          {step.skill && skillDescription && (
+            <p className="mt-1 px-1 text-[11px] text-fg-muted/80 leading-snug">
+              {skillDescription}
+            </p>
+          )}
+          {step.skill && !skillDescription && (
+            <p className="mt-1 px-1 text-[11px] text-fg-muted/50">
+              (no description — add one in the skill\'s frontmatter)
+            </p>
+          )}
+        </div>
+        <div>
+          <ArgsTemplateInput
+            value={step.argsTemplate}
+            disabled={!props.canWrite}
+            onChange={(argsTemplate) => props.onChange({ argsTemplate })}
+          />
+          <StopChainInput
+            value={step.stopChainIfContains ?? ''}
+            disabled={!props.canWrite}
+            onChange={(v) =>
+              props.onChange({ stopChainIfContains: v ? v : undefined })
+            }
+          />
+          {lintWarnings.length > 0 && (
+            <ul className="mt-1 space-y-0.5 px-1">
+              {lintWarnings.map((w, i) => (
+                <li key={i} className="text-[11px] text-amber-300/90 leading-snug">
+                  ⚠ {w}
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+        <div className="flex flex-col gap-1">
+          <IconButton
+            disabled={!props.canWrite || idx === props.steps.length - 1}
+            ariaLabel="Move step down"
+            onClick={props.onMoveDown}
+          >
+            <ArrowDownIcon />
+          </IconButton>
+          {!props.flowId.startsWith('__new__') && (
+            <IconButton
+              ariaLabel="Toggle preview"
+              onClick={() => setPreviewOpen((v) => !v)}
+              tone={previewOpen ? 'accent' : 'neutral'}
+            >
+              <EyeIcon />
+            </IconButton>
+          )}
+          <IconButton
+            ariaLabel={
+              step.systemNotes && step.systemNotes.trim()
+                ? 'Edit step notes (overrides default)'
+                : 'Edit step notes (using default marker contract)'
+            }
+            onClick={() => setNotesOpen((v) => !v)}
+            tone={notesOpen ? 'accent' : step.systemNotes && step.systemNotes.trim() ? 'accent' : 'neutral'}
+          >
+            <PencilIcon />
+          </IconButton>
+        </div>
+        <div className="flex flex-col gap-1">
+          <IconButton
+            disabled={!props.canWrite}
+            ariaLabel="Remove step"
+            tone="danger"
+            onClick={props.onRemove}
+          >
+            <TrashIcon />
+          </IconButton>
+          {props.stepOutcome && (
+            <IconButton
+              ariaLabel="Toggle output"
+              onClick={() => setOutputOpen((v) => !v)}
+              tone={outputOpen ? 'accent' : 'neutral'}
+            >
+              <ChatIcon />
+            </IconButton>
+          )}
+        </div>
+      </div>
+
+      {notesOpen && (
+        <StepNotesPanel
+          value={step.systemNotes ?? ''}
+          disabled={!props.canWrite}
+          onChange={(systemNotes) =>
+            props.onChange({ systemNotes: systemNotes ? systemNotes : undefined })
+          }
+        />
+      )}
+
+      {previewOpen && !props.flowId.startsWith('__new__') && (
+        <StepPreview flowId={props.flowId} stepIdx={idx} />
+      )}
+
+      {outputOpen && props.stepOutcome && (
+        <div className="mt-2 rounded-md border border-border bg-bg p-3">
+          <div className="mb-1 flex items-center justify-between text-[10px] uppercase tracking-wide text-fg-muted">
+            <span>Last run · {props.stepOutcome.stepId}</span>
+            <StatusBadge status={props.stepOutcome.status} />
+          </div>
+          {props.stepOutcome.output ? (
+            <pre className="max-h-48 overflow-auto whitespace-pre-wrap font-mono text-[11px] leading-relaxed text-fg/90">
+              {props.stepOutcome.output}
+            </pre>
+          ) : (
+            <p className="text-[11px] text-fg-muted">(no captured output)</p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ─── Skill picker with description hint ─────────────────────────────────────
+
+function SkillPicker({
+  value,
+  options,
+  onChange,
+  disabled,
+}: {
+  value: string;
+  options: SkillOption[];
+  onChange: (v: string) => void;
+  disabled: boolean;
+}) {
+  if (options.length === 0) {
+    return (
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        placeholder="auto-fix-github"
+        className="w-full rounded-md border border-border bg-bg-subtle px-3 py-2 font-mono text-xs text-fg focus:border-accent/50 focus:outline-none"
+      />
+    );
+  }
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={disabled}
+      className="w-full rounded-md border border-border bg-bg-subtle px-3 py-2 font-mono text-xs text-fg focus:border-accent/50 focus:outline-none"
+    >
+      <option value="">— pick a skill —</option>
+      {!options.find((o) => o.name === value) && value && (
+        <option value={value}>{value} (custom)</option>
+      )}
+      {options.map((o) => (
+        <option key={o.name} value={o.name}>
+          {o.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+// ─── Args template input with autocomplete ──────────────────────────────────
+
+function ArgsTemplateInput({
+  value,
+  disabled,
+  onChange,
+}: {
+  value: string;
+  disabled: boolean;
+  onChange: (v: string) => void;
+}) {
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const [showAutocomplete, setShowAutocomplete] = useState(false);
+  const [highlight, setHighlight] = useState(0);
+
+  // Show autocomplete when the cursor sits just after `{{` with no `}}` yet.
+  const updateAutocompleteState = () => {
+    const input = inputRef.current;
+    if (!input) return;
+    const pos = input.selectionStart ?? 0;
+    const before = input.value.slice(0, pos);
+    const after = input.value.slice(pos);
+    const openIdx = before.lastIndexOf('{{');
+    const closeIdx = before.lastIndexOf('}}');
+    const open = openIdx > closeIdx;
+    const hasCloser = open && after.indexOf('}}') !== -1 && after.indexOf('}}') < (after.indexOf('{{') === -1 ? Infinity : after.indexOf('{{'));
+    setShowAutocomplete(open && !hasCloser);
+    setHighlight(0);
+  };
+
+  const insertVariable = (varName: string) => {
+    const input = inputRef.current;
+    if (!input) return;
+    const pos = input.selectionStart ?? value.length;
+    const before = value.slice(0, pos);
+    const after = value.slice(pos);
+    const openIdx = before.lastIndexOf('{{');
+    const newBefore = before.slice(0, openIdx) + '{{' + varName + '}}';
+    const newValue = newBefore + after;
+    onChange(newValue);
+    setShowAutocomplete(false);
+    // Restore focus + cursor after React commits the new value.
+    window.setTimeout(() => {
+      input.focus();
+      const cursor = newBefore.length;
+      input.setSelectionRange(cursor, cursor);
+    }, 0);
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (!showAutocomplete) return;
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setHighlight((h) => (h + 1) % TEMPLATE_VARS.length);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setHighlight((h) => (h - 1 + TEMPLATE_VARS.length) % TEMPLATE_VARS.length);
+    } else if (e.key === 'Enter' || e.key === 'Tab') {
+      e.preventDefault();
+      insertVariable(TEMPLATE_VARS[highlight].name);
+    } else if (e.key === 'Escape') {
+      setShowAutocomplete(false);
+    }
+  };
+
+  return (
+    <div className="relative">
+      <input
+        ref={inputRef}
+        type="text"
+        value={value}
+        onChange={(e) => {
+          onChange(e.target.value);
+          // Defer so selectionStart reflects the post-change state.
+          window.setTimeout(updateAutocompleteState, 0);
+        }}
+        onKeyDown={onKeyDown}
+        onKeyUp={updateAutocompleteState}
+        onClick={updateAutocompleteState}
+        onBlur={() => window.setTimeout(() => setShowAutocomplete(false), 100)}
+        disabled={disabled}
+        placeholder="{{input}}"
+        className="w-full rounded-md border border-border bg-bg-subtle px-3 py-2 font-mono text-xs text-fg focus:border-accent/50 focus:outline-none"
+      />
+      {showAutocomplete && (
+        <div className="absolute left-0 top-full z-20 mt-1 w-full rounded-md border border-border bg-bg-elevated shadow-lg">
+          {TEMPLATE_VARS.map((v, i) => (
+            <button
+              key={v.name}
+              type="button"
+              onMouseDown={(e) => {
+                e.preventDefault();
+                insertVariable(v.name);
+              }}
+              className={
+                'block w-full px-3 py-1.5 text-left text-xs ' +
+                (i === highlight ? 'bg-accent/15 text-fg' : 'text-fg-muted hover:bg-bg-subtle')
+              }
+            >
+              <span className="font-mono">{v.label}</span>
+              <span className="ml-2 text-[10px] text-fg-muted/80">— {v.hint}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ─── Lint heuristics ────────────────────────────────────────────────────────
+
+/**
+ * Static checks for an args template:
+ *   - `{{previous*}}` used in step 1 → no previous step yet
+ *   - PR vars used after a step whose skill name doesn't look PR-creating
+ *   - Unknown `{{vars}}` (not in TEMPLATE_VARS)
+ */
+function lintArgsTemplate(tpl: string, stepIdx: number, allSteps: FlowStep[]): string[] {
+  const out: string[] = [];
+  const refs = new Set<string>();
+  const re = /\{\{\s*([\w.]+)\s*\}\}/g;
+  for (const m of tpl.matchAll(re)) refs.add(m[1]);
+
+  const known = new Set<string>(TEMPLATE_VARS.map((v) => v.name));
+
+  for (const ref of refs) {
+    if (!known.has(ref)) {
+      out.push(`unknown template var '{{${ref}}}'`);
+    }
+  }
+
+  const usesAnyPrevious =
+    refs.has('previousTaskId') || refs.has('previousPullRequestUrl') || refs.has('previousPullRequestNumber');
+  if (usesAnyPrevious && stepIdx === 0) {
+    out.push("'previous*' references have no value in the first step");
+  }
+
+  const usesPrevPr = refs.has('previousPullRequestUrl') || refs.has('previousPullRequestNumber');
+  if (usesPrevPr && stepIdx > 0) {
+    const prev = allSteps[stepIdx - 1];
+    if (prev && prev.skill && !PR_CREATING_PATTERN.test(prev.skill)) {
+      out.push(
+        `previous step '${prev.skill}' may not open a PR — '{{previousPullRequest*}}' could be empty`,
+      );
+    }
+  }
+
+  return out;
+}
+
+// ─── Triggers panel ─────────────────────────────────────────────────────────
+
+function TriggersPanel({
+  triggers,
+  canWrite,
+  onChange,
+}: {
+  triggers: FlowTrigger[];
+  canWrite: boolean;
+  onChange: (next: FlowTrigger[]) => void;
+}) {
+  const openedOn = triggers.some((t) => t.kind === 'issue.opened');
+  const labelTriggers = triggers.filter((t): t is { kind: 'issue.labeled'; label: string } => t.kind === 'issue.labeled');
+  const [draftLabel, setDraftLabel] = useState('');
+
+  const setOpenedOn = (on: boolean) => {
+    if (on === openedOn) return;
+    const next: FlowTrigger[] = triggers.filter((t) => t.kind !== 'issue.opened');
+    if (on) next.push({ kind: 'issue.opened' });
+    onChange(next);
+  };
+
+  const addLabel = () => {
+    const t = draftLabel.trim();
+    if (!t) return;
+    if (labelTriggers.some((lt) => lt.label === t)) {
+      setDraftLabel('');
+      return;
+    }
+    onChange([...triggers, { kind: 'issue.labeled', label: t }]);
+    setDraftLabel('');
+  };
+
+  const removeLabel = (label: string) => {
+    onChange(triggers.filter((t) => !(t.kind === 'issue.labeled' && t.label === label)));
+  };
+
+  return (
+    <details className="mt-3 rounded-md border border-border/60 bg-bg-subtle/40">
+      <summary className="cursor-pointer select-none px-3 py-2 text-[11px] font-medium uppercase tracking-wide text-fg-muted">
+        Run automatically when…{' '}
+        <span className="text-fg-muted/60 normal-case">
+          ({triggers.length === 0 ? 'manual only' : describeTriggers(triggers)})
+        </span>
+      </summary>
+      <div className="space-y-2 border-t border-border/60 p-3">
+        <label className="flex items-center gap-2 text-sm text-fg">
+          <input
+            type="checkbox"
+            checked={openedOn}
+            onChange={(e) => setOpenedOn(e.target.checked)}
+            disabled={!canWrite}
+            className="h-4 w-4 rounded border-border bg-bg-subtle accent-accent"
+          />
+          An issue is <strong className="font-semibold">opened</strong>
+        </label>
+        <div>
+          <div className="text-sm text-fg">A label is added:</div>
+          <div className="mt-1 flex flex-wrap items-center gap-1.5">
+            {labelTriggers.map((lt) => (
+              <span
+                key={lt.label}
+                className="inline-flex items-center gap-1 rounded bg-bg px-2 py-0.5 font-mono text-[11px] text-fg"
+              >
+                {lt.label}
+                {canWrite && (
+                  <button
+                    type="button"
+                    onClick={() => removeLabel(lt.label)}
+                    aria-label={`remove ${lt.label}`}
+                    className="text-fg-muted hover:text-rose-400"
+                  >
+                    ×
+                  </button>
+                )}
+              </span>
+            ))}
+            {canWrite && (
+              <span className="inline-flex items-center gap-1">
+                <input
+                  type="text"
+                  value={draftLabel}
+                  onChange={(e) => setDraftLabel(e.target.value)}
+                  onKeyDown={(e) => {
+                    if (e.key === 'Enter' || e.key === ',') {
+                      e.preventDefault();
+                      addLabel();
+                    }
+                  }}
+                  placeholder="auto-fix"
+                  className="w-32 rounded-md border border-border bg-bg-subtle px-2 py-1 font-mono text-[11px] text-fg focus:border-accent/50 focus:outline-none"
+                />
+                <button
+                  type="button"
+                  onClick={addLabel}
+                  disabled={!draftLabel.trim()}
+                  className="rounded-md border border-border bg-bg-subtle px-2 py-1 text-[11px] text-fg hover:bg-bg disabled:opacity-50"
+                >
+                  Add
+                </button>
+              </span>
+            )}
+          </div>
+        </div>
+        <p className="text-[11px] text-fg-muted">
+          Triggers fire via the GitHub App webhook. The dispatcher dedupes against in-flight jobs for the same flow+issue.
+        </p>
+      </div>
+    </details>
+  );
+}
+
+function describeTriggers(triggers: FlowTrigger[]): string {
+  const parts: string[] = [];
+  if (triggers.some((t) => t.kind === 'issue.opened')) parts.push('issue opened');
+  const labels = triggers
+    .filter((t): t is { kind: 'issue.labeled'; label: string } => t.kind === 'issue.labeled')
+    .map((t) => `:${t.label}`);
+  if (labels.length > 0) parts.push(`label ${labels.join(', ')}`);
+  return parts.join(' · ');
+}
+
+// ─── Preview pane ───────────────────────────────────────────────────────────
+
+function StepPreview({ flowId, stepIdx }: { flowId: string; stepIdx: number }) {
+  const [sampleInput, setSampleInput] = useState('42');
+  const [samplePrev, setSamplePrev] = useState({ taskId: '', prUrl: '', prNumber: '' });
+  const [preview, setPreview] = useState<PreviewResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, startTransition] = useTransition();
+
+  const run = () => {
+    setError(null);
+    startTransition(async () => {
+      const result = await renderStepPreview({
+        flowId,
+        stepIdx,
+        sampleInput,
+        samplePrevTaskId: samplePrev.taskId,
+        samplePrevPrUrl: samplePrev.prUrl,
+        samplePrevPrNumber: samplePrev.prNumber,
+      });
+      if (!result.ok) {
+        setError(result.error);
+        return;
+      }
+      setPreview(result);
+    });
+  };
+
+  // Auto-render on open with default sample.
+  useEffect(() => {
+    run();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <div className="mt-2 rounded-md border border-border bg-bg p-3 space-y-2">
+      <div className="flex flex-wrap items-center gap-2 text-[11px]">
+        <span className="uppercase tracking-wide text-fg-muted">Preview · sample:</span>
+        <label className="inline-flex items-center gap-1">
+          <span className="text-fg-muted">input</span>
+          <input
+            type="text"
+            value={sampleInput}
+            onChange={(e) => setSampleInput(e.target.value)}
+            className="w-20 rounded border border-border bg-bg-subtle px-1.5 py-0.5 text-xs text-fg"
+          />
+        </label>
+        {stepIdx > 0 && (
+          <>
+            <label className="inline-flex items-center gap-1">
+              <span className="text-fg-muted">prev PR #</span>
+              <input
+                type="text"
+                value={samplePrev.prNumber}
+                onChange={(e) => setSamplePrev((s) => ({ ...s, prNumber: e.target.value }))}
+                placeholder="7"
+                className="w-12 rounded border border-border bg-bg-subtle px-1.5 py-0.5 text-xs text-fg"
+              />
+            </label>
+            <label className="inline-flex items-center gap-1">
+              <span className="text-fg-muted">prev task</span>
+              <input
+                type="text"
+                value={samplePrev.taskId}
+                onChange={(e) => setSamplePrev((s) => ({ ...s, taskId: e.target.value }))}
+                placeholder="uuid"
+                className="w-32 rounded border border-border bg-bg-subtle px-1.5 py-0.5 text-xs text-fg"
+              />
+            </label>
+          </>
+        )}
+        <button
+          onClick={run}
+          disabled={loading}
+          className="ml-auto rounded-md border border-border bg-bg-subtle px-2 py-0.5 text-[11px] text-fg hover:bg-bg disabled:opacity-50"
+        >
+          {loading ? 'Rendering…' : 'Refresh'}
+        </button>
+      </div>
+      {error && <p className="text-[11px] text-rose-400">{error}</p>}
+      {preview && (
+        <>
+          <div>
+            <div className="text-[10px] uppercase tracking-wide text-fg-muted">User prompt sent to agent</div>
+            <pre className="mt-1 max-h-32 overflow-auto whitespace-pre-wrap rounded border border-border/60 bg-bg-subtle p-2 font-mono text-[11px] text-fg">
+              {preview.userPrompt || '(empty)'}
+            </pre>
+          </div>
+          <div>
+            <div className="text-[10px] uppercase tracking-wide text-fg-muted">System prompt scaffolding</div>
+            <pre className="mt-1 max-h-24 overflow-auto whitespace-pre-wrap rounded border border-border/60 bg-bg-subtle p-2 font-mono text-[11px] text-fg-muted">
+              {preview.scaffoldingSystemPrompt}
+            </pre>
+          </div>
+          <div>
+            <div className="text-[10px] uppercase tracking-wide text-fg-muted">
+              Step notes
+              {' '}
+              <span className={preview.stepNotesIsDefault ? 'normal-case text-fg-muted/70' : 'normal-case text-accent'}>
+                — {preview.stepNotesIsDefault ? 'default (the marker contract)' : 'user override'}
+              </span>
+            </div>
+            <pre className="mt-1 max-h-32 overflow-auto whitespace-pre-wrap rounded border border-border/60 bg-bg-subtle p-2 font-mono text-[11px] text-fg/80">
+              {preview.stepNotes}
+            </pre>
+          </div>
+          <div>
+            <div className="text-[10px] uppercase tracking-wide text-fg-muted">
+              Skill body ({preview.skill || '—'})
+              {preview.skillBodyMissing && (
+                <span className="ml-2 normal-case text-amber-300/90">
+                  ⚠ couldn\'t read skill body from the repo clone
+                </span>
+              )}
+            </div>
+            <pre className="mt-1 max-h-40 overflow-auto whitespace-pre-wrap rounded border border-border/60 bg-bg-subtle p-2 font-mono text-[11px] text-fg/80">
+              {preview.skillBody || '(skill body unavailable — appended at runtime from .ai/skills/)'}
+            </pre>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+// ─── Bottom strip: Run on issue ────────────────────────────────────────────
+
+function RunOnIssue({ onRun }: { onRun: (issue: number) => void }) {
+  const [issueInput, setIssueInput] = useState('');
+  const [running, startTransition] = useTransition();
+  return (
+    <div className="flex items-center gap-2">
+      <label className="text-xs text-fg-muted">Run on issue</label>
+      <span className="text-xs text-fg-muted">#</span>
+      <input
+        type="number"
+        min={1}
+        value={issueInput}
+        onChange={(e) => setIssueInput(e.target.value)}
+        placeholder="42"
+        className="w-20 rounded-md border border-border bg-bg-subtle px-2 py-1 text-xs text-fg"
+      />
+      <button
+        disabled={running || !issueInput.trim()}
+        onClick={() => {
+          const n = Number(issueInput);
+          if (!Number.isInteger(n) || n <= 0) {
+            alert('issue number must be a positive integer');
+            return;
+          }
+          startTransition(() => {
+            onRun(n);
+            setIssueInput('');
+          });
+        }}
+        className="rounded-md border border-accent/50 bg-accent/10 px-2.5 py-1 text-xs font-medium text-fg hover:bg-accent/20 disabled:opacity-50"
+      >
+        {running ? 'Queueing…' : 'Run'}
+      </button>
+    </div>
+  );
+}
+
+// ─── Small UI primitives ───────────────────────────────────────────────────
+
+function StatusBadge({ status }: { status: string }) {
+  const cls =
+    status === 'succeeded' ? 'text-emerald-400 bg-emerald-500/15'
+    : status === 'failed' ? 'text-rose-400 bg-rose-500/15'
+    : status === 'running' ? 'text-amber-300 bg-amber-500/15'
+    : status === 'cancelled' ? 'text-fg-muted bg-bg-subtle'
+    : status === 'skipped' ? 'text-fg-muted bg-bg-subtle'
+    : 'text-fg-muted bg-bg-subtle';
+  return <span className={`rounded px-1.5 py-0.5 text-[11px] font-medium ${cls}`}>{status}</span>;
+}
+
+function IconButton({
+  children,
+  onClick,
+  disabled,
+  ariaLabel,
+  tone = 'neutral',
+}: {
+  children: React.ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+  ariaLabel: string;
+  tone?: 'neutral' | 'danger' | 'accent';
+}) {
+  const cls =
+    tone === 'danger'
+      ? 'border-border bg-bg-subtle text-rose-400 hover:bg-rose-500/10'
+      : tone === 'accent'
+        ? 'border-accent/50 bg-accent/10 text-fg hover:bg-accent/20'
+        : 'border-border bg-bg-subtle text-fg-muted hover:text-fg hover:bg-bg';
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      className={`rounded-md border px-2 py-1.5 disabled:opacity-30 ${cls}`}
+    >
+      {children}
+    </button>
+  );
+}
+
+function PlusIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M12 5v14M5 12h14" />
+    </svg>
+  );
+}
+
+function TrashIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6" />
+    </svg>
+  );
+}
+
+function ArrowDownIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M12 5v14M5 12l7 7 7-7" />
+    </svg>
+  );
+}
+
+function EyeIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" />
+      <circle cx="12" cy="12" r="3" />
+    </svg>
+  );
+}
+
+function PencilIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M12 20h9" />
+      <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4z" />
+    </svg>
+  );
+}
+
+function ChatIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+    </svg>
+  );
+}
diff --git a/packages/gui/src/app/workflows/page.tsx b/packages/gui/src/app/workflows/page.tsx
new file mode 100644
index 0000000..7decde5
--- /dev/null
+++ b/packages/gui/src/app/workflows/page.tsx
@@ -0,0 +1,22 @@
+import { redirect } from 'next/navigation';
+import { getActiveWorkspace } from '@/lib/workspace';
+import { listFlows, listAvailableSkills } from './actions';
+import { WorkflowsClient } from './workflows-client';
+
+export const dynamic = 'force-dynamic';
+
+export default async function WorkflowsPage() {
+  const workspace = await getActiveWorkspace();
+  if (!workspace) redirect('/workspaces');
+
+  const [flows, skills] = await Promise.all([listFlows(), listAvailableSkills()]);
+
+  return (
+    <WorkflowsClient
+      workspaceName={workspace.name}
+      workspaceRole={workspace.role}
+      initialFlows={flows}
+      availableSkills={skills.map((s) => ({ name: s.name, description: s.description }))}
+    />
+  );
+}
diff --git a/packages/gui/src/app/workflows/templates.ts b/packages/gui/src/app/workflows/templates.ts
new file mode 100644
index 0000000..940b7d6
--- /dev/null
+++ b/packages/gui/src/app/workflows/templates.ts
@@ -0,0 +1,144 @@
+import type { FlowStep, FlowTrigger } from './actions';
+
+/**
+ * Starter templates shown in the "+ Flow" dropdown. Picking one prefills the
+ * editor with a working starting point — beats staring at a blank flow.
+ *
+ * Templates are pure data. Skills referenced here must exist (or be added)
+ * in the workspace's repo under `.ai/skills/<name>.md`; we list common ones
+ * by convention but the user can edit any step before running.
+ *
+ * Decomposition matters: each step gets its own fresh token budget
+ * (`autofix.tokenBudgetPerAttempt`, default 250k). A single mega-step that
+ * tries to triage + analyze + fix + push + open PR will blow the budget on
+ * anything non-trivial. The autofix template below mirrors the built-in
+ * `autofixWorkflow` (packages/core/src/workflows/definitions/autofix.workflow.ts)
+ * — five focused steps, each with a narrow read-only or write scope.
+ */
+
+/**
+ * Shared step list for any flow that fixes a GitHub issue. Steps:
+ *   1. verify-in-repo — read-only gate; stops cleanly on NO_ACTION_NEEDED
+ *   2. root-cause     — read-only analysis
+ *   3. fix            — edits files in the worktree
+ *   4. open-pr        — commits, pushes, opens draft PR (emits PR_URL/PR_NUMBER markers)
+ *   5. review-pr      — second agent comments on the resulting PR
+ *
+ * Each step references a skill that must exist at `.ai/skills/<name>.md` in the
+ * workspace's repo. The skill body provides the actual instructions; the
+ * `systemNotes` here is a per-step scaffolding hint (read-only vs write, what
+ * the next step expects). Edit any step in the GUI before running.
+ */
+function autofixSteps(): FlowStep[] {
+  return [
+    {
+      skill: 'verify-in-repo',
+      argsTemplate: 'Issue #{{input}} — verify whether this is a real, still-unfixed defect.',
+      stopChainIfContains: 'NO_ACTION_NEEDED',
+      systemNotes:
+        'This is the VERIFY gate. Read-only: do NOT edit files. Use only Read/Grep/Glob ' +
+        'and read-only `git log`/`git diff`/`git show`/`git status`.\n\n' +
+        'Decide quickly whether the issue describes a real, still-unfixed defect on the current ' +
+        'branch — as opposed to expected behavior, something already fixed, or a usage error.\n\n' +
+        'If no action is needed (already fixed / not a bug / out of scope), write `NO_ACTION_NEEDED` ' +
+        'on a line by itself with a one-paragraph reason. The chain will stop cleanly.\n\n' +
+        'Otherwise, write a short paragraph confirming it is a real defect with file/commit evidence.',
+    },
+    {
+      skill: 'root-cause',
+      argsTemplate:
+        'Issue #{{input}} — find the root cause and propose the minimal fix.\n' +
+        'Previous verify task: {{previousTaskId}}.',
+      systemNotes:
+        'This is the ANALYZE step. Read-only: do NOT edit files.\n\n' +
+        'Produce: (1) a one-paragraph summary of the bug, (2) the file(s) that need to change, ' +
+        '(3) the proposed minimal change. Keep it tight — the next step implements it.',
+    },
+    {
+      skill: 'fix',
+      argsTemplate:
+        'Issue #{{input}} — implement the fix from the analyzer (previous task {{previousTaskId}}).',
+      systemNotes:
+        'This is the FIX step. Implement the minimal change identified by the analyzer. ' +
+        'Use Edit/Write to change files; run tests with Bash if needed to verify the change holds.\n\n' +
+        'Do NOT commit, push, or open a PR — the next step handles that.\n\n' +
+        'When done, write a one-paragraph summary of what you changed and which files were touched.',
+    },
+    {
+      skill: 'open-pr',
+      argsTemplate:
+        'Issue #{{input}} — commit, push, and open a draft PR for the fix from previous task {{previousTaskId}}.',
+      // Default systemNotes (DEFAULT_STEP_NOTES) documents the PR_URL=/PR_NUMBER= marker
+      // contract that the review-pr step needs — leave systemNotes unset to inherit it.
+    },
+    {
+      skill: 'auto-review-pr',
+      argsTemplate:
+        'Review PR #{{previousPullRequestNumber}} at {{previousPullRequestUrl}}.',
+      systemNotes:
+        'This is the REVIEW step. Read the PR diff and post a review comment on the PR. ' +
+        'Be specific about blockers vs nits. Read-only: do NOT push further commits.',
+    },
+  ];
+}
+
+export interface FlowTemplate {
+  id: string;
+  label: string;
+  /** One-line description shown next to the label in the dropdown. */
+  description: string;
+  build: () => {
+    name: string;
+    steps: FlowStep[];
+    triggers: FlowTrigger[];
+  };
+}
+
+export const FLOW_TEMPLATES: FlowTemplate[] = [
+  {
+    id: 'blank',
+    label: 'Blank flow',
+    description: 'Start from scratch.',
+    build: () => ({
+      name: 'new flow',
+      steps: [{ skill: '', argsTemplate: '{{input}}' }],
+      triggers: [],
+    }),
+  },
+  {
+    id: 'fix-and-review',
+    label: 'Fix → Review PR (5 steps)',
+    description: 'Decomposed autofix: verify → analyze → fix → open PR → review. Each step gets its own token budget.',
+    build: () => ({
+      name: 'fix github issue',
+      steps: autofixSteps(),
+      triggers: [],
+    }),
+  },
+  {
+    id: 'triage-and-label',
+    label: 'Triage → Label',
+    description: 'Read an incoming issue and apply triage labels. Stops cleanly if no action is needed.',
+    build: () => ({
+      name: 'triage incoming',
+      steps: [
+        {
+          skill: 'auto-triage',
+          argsTemplate: 'Triage issue #{{input}}',
+          stopChainIfContains: 'NO_ACTION_NEEDED',
+        },
+      ],
+      triggers: [{ kind: 'issue.opened' }],
+    }),
+  },
+  {
+    id: 'on-label-fix',
+    label: 'Label trigger → Fix (5 steps)',
+    description: 'Auto-fix any issue that gets the `auto-fix` label, using the decomposed verify → analyze → fix → open PR → review pipeline.',
+    build: () => ({
+      name: 'fix on label',
+      steps: autofixSteps(),
+      triggers: [{ kind: 'issue.labeled', label: 'auto-fix' }],
+    }),
+  },
+];
diff --git a/packages/gui/src/app/workflows/workflows-client.tsx b/packages/gui/src/app/workflows/workflows-client.tsx
new file mode 100644
index 0000000..cdaee66
--- /dev/null
+++ b/packages/gui/src/app/workflows/workflows-client.tsx
@@ -0,0 +1,320 @@
+'use client';
+
+import { useEffect, useState, useTransition } from 'react';
+import { useRouter } from 'next/navigation';
+import type { WorkspaceRole } from '@/lib/supabase/types';
+import {
+  deleteFlow,
+  listFlows,
+  runFlowOnIssue,
+  setFlowPaused,
+  upsertFlow,
+  type FlowStep,
+  type FlowSummary,
+  type FlowTrigger,
+} from './actions';
+import { FlowCard, type SkillOption } from './flow-card';
+import { FLOW_TEMPLATES, type FlowTemplate } from './templates';
+
+interface Props {
+  workspaceName: string;
+  workspaceRole: WorkspaceRole;
+  initialFlows: FlowSummary[];
+  availableSkills: SkillOption[];
+}
+
+/**
+ * The /workflows page. Matches the design in the screenshot, extended with:
+ *   1. skill descriptions inline next to the picker
+ *   2. auto-trigger panel (issue.opened, issue.labeled)
+ *   3. template variable autocomplete + static lint on args templates
+ *   4. per-step preview ("what will the agent see?") via server action
+ *   5. inline last-run output snippet
+ *
+ * Save batches all dirty flows + the pending-new flow in one click.
+ */
+export function WorkflowsClient({ workspaceName, workspaceRole, initialFlows, availableSkills }: Props) {
+  const router = useRouter();
+  const [flows, setFlows] = useState<FlowSummary[]>(initialFlows);
+  const [dirty, setDirty] = useState<Set<string>>(new Set());
+  const [pendingNew, setPendingNew] = useState<FlowSummary | null>(null);
+  const [savingState, setSavingState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle');
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const canWrite = workspaceRole !== 'viewer';
+
+  useEffect(() => {
+    if (dirty.size > 0 || pendingNew) return;
+    const i = window.setInterval(async () => {
+      const next = await listFlows();
+      setFlows(next);
+    }, 4000);
+    return () => window.clearInterval(i);
+  }, [dirty.size, pendingNew]);
+
+  const markDirty = (id: string) => setDirty((prev) => new Set(prev).add(id));
+
+  const updateFlow = (id: string, patch: (f: FlowSummary) => FlowSummary) => {
+    if (id === pendingNew?.id) {
+      setPendingNew((cur) => (cur ? patch(cur) : cur));
+      return;
+    }
+    setFlows((cur) => cur.map((f) => (f.id === id ? patch(f) : f)));
+    markDirty(id);
+  };
+
+  const newFlowFromTemplate = (template: FlowTemplate) => {
+    const tempId = `__new__${Date.now()}`;
+    const built = template.build();
+    setPendingNew({
+      id: tempId,
+      name: built.name,
+      steps: built.steps,
+      triggers: built.triggers,
+      paused: false,
+      updatedAt: new Date().toISOString(),
+      recentRuns: [],
+      stats: { totalLast7d: 0, succeededLast7d: 0, avgTokens: 0 },
+    });
+  };
+
+  const deleteOne = async (id: string) => {
+    if (id === pendingNew?.id) {
+      setPendingNew(null);
+      return;
+    }
+    if (!confirm('Delete this flow?')) return;
+    const result = await deleteFlow(id);
+    if (!result.ok) {
+      alert(`Delete failed: ${result.error}`);
+      return;
+    }
+    setFlows((cur) => cur.filter((f) => f.id !== id));
+    setDirty((cur) => {
+      const next = new Set(cur);
+      next.delete(id);
+      return next;
+    });
+  };
+
+  const saveAll = async () => {
+    setSaveError(null);
+    setSavingState('saving');
+    const ops: Array<Promise<{ ok: boolean; error?: string }>> = [];
+
+    if (pendingNew) {
+      ops.push(
+        upsertFlow({
+          name: pendingNew.name,
+          steps: pendingNew.steps,
+          triggers: pendingNew.triggers,
+          paused: pendingNew.paused,
+        }).then((r) => (r.ok ? { ok: true } : { ok: false, error: r.error })),
+      );
+    }
+    for (const id of dirty) {
+      const flow = flows.find((f) => f.id === id);
+      if (!flow) continue;
+      ops.push(
+        upsertFlow({
+          id: flow.id,
+          name: flow.name,
+          steps: flow.steps,
+          triggers: flow.triggers,
+          paused: flow.paused,
+        }).then((r) => (r.ok ? { ok: true } : { ok: false, error: r.error })),
+      );
+    }
+
+    const results = await Promise.all(ops);
+    const firstErr = results.find((r) => !r.ok);
+    if (firstErr) {
+      setSaveError(firstErr.error ?? 'save failed');
+      setSavingState('error');
+      return;
+    }
+    const next = await listFlows();
+    setFlows(next);
+    setDirty(new Set());
+    setPendingNew(null);
+    setSavingState('saved');
+    window.setTimeout(() => setSavingState('idle'), 2000);
+  };
+
+  const allFlows: FlowSummary[] = pendingNew ? [...flows, pendingNew] : flows;
+  const isDirty = dirty.size > 0 || pendingNew !== null;
+
+  return (
+    <div className="px-8 py-6">
+      <header className="mb-6 border-b border-border pb-5">
+        <div className="flex items-start justify-between gap-4">
+          <div>
+            <h1 className="text-2xl font-semibold tracking-tight">Workflows</h1>
+            <p className="mt-1 text-sm text-fg-muted">
+              Chain named skill steps. Args can use{' '}
+              <code>{'{{input}}'}</code>,{' '}
+              <code>{'{{previousTaskId}}'}</code>,{' '}
+              <code>{'{{previousPullRequestUrl}}'}</code>, and{' '}
+              <code>{'{{previousPullRequestNumber}}'}</code>.
+              <span className="ml-2 text-fg-muted/60">— workspace: <span className="text-fg">{workspaceName}</span></span>
+            </p>
+          </div>
+          {canWrite && <NewFlowMenu onPick={newFlowFromTemplate} />}
+        </div>
+      </header>
+
+      {allFlows.length === 0 && (
+        <div className="rounded-lg border border-dashed border-border bg-bg-subtle p-8 text-center text-sm text-fg-muted">
+          No flows yet. {canWrite ? 'Click "+ Flow" to create one.' : ''}
+        </div>
+      )}
+
+      <div className="space-y-4">
+        {allFlows.map((flow) => (
+          <FlowCard
+            key={flow.id}
+            flow={flow}
+            canWrite={canWrite}
+            availableSkills={availableSkills}
+            onNameChange={(name) => updateFlow(flow.id, (f) => ({ ...f, name }))}
+            onStepChange={(idx, patch) =>
+              updateFlow(flow.id, (f) => ({
+                ...f,
+                steps: f.steps.map((s, i) => (i === idx ? { ...s, ...patch } : s)),
+              }))
+            }
+            onAddStep={() =>
+              updateFlow(flow.id, (f) => ({
+                ...f,
+                steps: [...f.steps, { skill: '', argsTemplate: '{{input}}' }],
+              }))
+            }
+            onRemoveStep={(idx) =>
+              updateFlow(flow.id, (f) => ({ ...f, steps: f.steps.filter((_, i) => i !== idx) }))
+            }
+            onMoveStepDown={(idx) =>
+              updateFlow(flow.id, (f) => {
+                if (idx >= f.steps.length - 1) return f;
+                const next = [...f.steps];
+                [next[idx], next[idx + 1]] = [next[idx + 1], next[idx]];
+                return { ...f, steps: next };
+              })
+            }
+            onTriggersChange={(triggers: FlowTrigger[]) =>
+              updateFlow(flow.id, (f) => ({ ...f, triggers }))
+            }
+            onPausedChange={async (paused) => {
+              // Pause is a server-side toggle even for clean (non-dirty)
+              // rows — we want it to take effect immediately, not wait
+              // for the "Save workflows" click.
+              if (flow.id.startsWith('__new__')) {
+                updateFlow(flow.id, (f) => ({ ...f, paused }));
+                return;
+              }
+              setFlows((cur) => cur.map((f) => (f.id === flow.id ? { ...f, paused } : f)));
+              const result = await setFlowPaused(flow.id, paused);
+              if (!result.ok) {
+                alert(`Pause failed: ${result.error}`);
+                // revert
+                const next = await listFlows();
+                setFlows(next);
+              }
+            }}
+            onDelete={() => deleteOne(flow.id)}
+            onRun={async (issue) => {
+              if (flow.id.startsWith('__new__')) {
+                alert('Save the flow before running it.');
+                return;
+              }
+              const result = await runFlowOnIssue({ flowId: flow.id, issueNumber: issue });
+              if (!result.ok) {
+                alert(`Run failed: ${result.error}`);
+                return;
+              }
+              const next = await listFlows();
+              setFlows(next);
+            }}
+            onOpenRun={() => flow.lastRun && router.push(`/cockpit/${flow.lastRun.id}`)}
+          />
+        ))}
+      </div>
+
+      {canWrite && (
+        <div className="mt-6 flex items-center gap-3">
+          <button
+            onClick={saveAll}
+            disabled={!isDirty || savingState === 'saving'}
+            className="inline-flex items-center gap-2 rounded-md border border-accent/50 bg-accent/15 px-3 py-1.5 text-sm font-medium text-fg hover:bg-accent/25 disabled:opacity-50"
+          >
+            <SaveIcon />
+            {savingState === 'saving' ? 'Saving…' : 'Save workflows'}
+          </button>
+          <span className="text-xs text-fg-muted">
+            {savingState === 'saved' && 'Saved'}
+            {savingState === 'error' && saveError && <span className="text-rose-400">{saveError}</span>}
+            {savingState === 'idle' && (isDirty ? 'Unsaved changes' : 'Saved')}
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function NewFlowMenu({ onPick }: { onPick: (t: FlowTemplate) => void }) {
+  const [open, setOpen] = useState(false);
+  // Close when clicking outside or hitting escape.
+  useEffect(() => {
+    if (!open) return;
+    const onDoc = (e: MouseEvent) => {
+      const t = e.target as HTMLElement;
+      if (!t.closest('[data-newflow-menu]')) setOpen(false);
+    };
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') setOpen(false); };
+    document.addEventListener('mousedown', onDoc);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDoc);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="relative" data-newflow-menu>
+      <button
+        onClick={() => setOpen((v) => !v)}
+        className="rounded-md border border-accent/50 bg-accent/10 px-3 py-1.5 text-sm font-medium text-fg hover:bg-accent/20"
+      >
+        + Flow ▾
+      </button>
+      {open && (
+        <div className="absolute right-0 top-full z-30 mt-1 w-80 rounded-md border border-border bg-bg-elevated shadow-xl">
+          <div className="border-b border-border px-3 py-2 text-[11px] uppercase tracking-wide text-fg-muted">
+            Start from a template
+          </div>
+          {FLOW_TEMPLATES.map((t) => (
+            <button
+              key={t.id}
+              type="button"
+              onClick={() => {
+                onPick(t);
+                setOpen(false);
+              }}
+              className="block w-full border-b border-border/50 px-3 py-2 text-left last:border-b-0 hover:bg-bg-subtle"
+            >
+              <div className="text-sm font-medium text-fg">{t.label}</div>
+              <div className="text-[11px] text-fg-muted leading-snug">{t.description}</div>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function SaveIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z" />
+      <path d="M17 21v-8H7v8M7 3v5h8" />
+    </svg>
+  );
+}
diff --git a/packages/gui/src/components/sidebar.tsx b/packages/gui/src/components/sidebar.tsx
index 5fcf502..202381d 100644
--- a/packages/gui/src/components/sidebar.tsx
+++ b/packages/gui/src/components/sidebar.tsx
@@ -11,6 +11,7 @@ import {
   TerminalIcon,
   ClockIcon,
   SettingsIcon,
+  PlayIcon,
 } from './icons';
 import type { SessionUser } from '@/lib/auth';
 import type { ActiveWorkspace, WorkspaceListItem } from '@/lib/workspace';
@@ -23,6 +24,7 @@ const NAV = [
   { href: '/skills',    label: 'Skills',   icon: <SparkleIcon className="h-5 w-5" /> },
   { href: '/actions',   label: 'Actions',  icon: <BoltIcon className="h-5 w-5" /> },
   { href: '/cockpit',   label: 'Runs',     icon: <TerminalIcon className="h-5 w-5" /> },
+  { href: '/workflows', label: 'Workflows', icon: <PlayIcon className="h-5 w-5" /> },
   { href: '/activity',  label: 'Activity', icon: <ClockIcon className="h-5 w-5" /> },
   { href: '/settings',  label: 'Settings', icon: <SettingsIcon className="h-5 w-5" /> },
 ] as const;
diff --git a/packages/gui/src/lib/execute-workflow-job.ts b/packages/gui/src/lib/execute-workflow-job.ts
index 68e570e..8ec5af9 100644
--- a/packages/gui/src/lib/execute-workflow-job.ts
+++ b/packages/gui/src/lib/execute-workflow-job.ts
@@ -7,7 +7,7 @@ import { ensureRepoClone } from './repo-clone';
 import { runTriagePassJob } from './run-triage-pass-job';
 import type { Database } from './supabase/types';
 
-type WorkflowKind = 'autofix' | 'ci-followup' | 'triage';
+type WorkflowKind = 'autofix' | 'ci-followup' | 'triage' | 'flow';
 
 export interface ExecuteWorkflowJobParams {
   workspaceId: string;
@@ -20,6 +20,10 @@ export interface ExecuteWorkflowJobParams {
   jobId?: string | null;
   /** For `ci-followup` jobs — the seed lifted off `jobs.payload.ciFollowup` (a `CiFollowupInput`). */
   ciFollowupSeed?: CiFollowupInput;
+  /** For `flow` jobs — the `flows.id` (uuid) whose `steps` to walk. */
+  flowId?: string;
+  /** For `flow` jobs — the `{{input}}` value passed to the first step (typically the issue number as a string). */
+  flowInput?: string;
 }
 
 /**
@@ -42,7 +46,7 @@ export async function executeWorkflowJob(
   adminSupabase: SupabaseClient<Database>,
   params: ExecuteWorkflowJobParams,
 ): Promise<void> {
-  const { workspaceId, workflow, issueNumber, prNumber, jobId, ciFollowupSeed } = params;
+  const { workspaceId, workflow, issueNumber, prNumber, jobId, ciFollowupSeed, flowId, flowInput } = params;
   let persister: WorkflowRunPersister | null = null;
 
   const finishJob = async (status: Database['public']['Tables']['jobs']['Row']['status']): Promise<void> => {
@@ -97,11 +101,27 @@ export async function executeWorkflowJob(
     const runIssueNumber = workflow === 'ci-followup' ? ciFollowupSeed?.issueNumber ?? issueNumber : issueNumber;
     if (runIssueNumber == null) throw new Error(`workflow '${workflow}' job has no issue_number`);
 
+    // ── flow workflow: load the flow row up-front so the `workflow_runs.workflow`
+    //    column gets the flow's name (e.g. 'fix-github-issue') instead of the
+    //    opaque 'flow' kind. Surfaces in the cockpit alongside the built-ins.
+    let flowRow: { name: string; steps: Array<{ skill: string; argsTemplate: string }> } | null = null;
+    if (workflow === 'flow') {
+      if (!flowId) throw new Error('flow job missing payload.flowId');
+      const { data, error: fErr } = await adminSupabase
+        .from('flows')
+        .select('name, steps')
+        .eq('id', flowId)
+        .eq('workspace_id', workspaceId)
+        .single();
+      if (fErr || !data) throw new Error(`flow ${flowId} not found: ${fErr?.message ?? 'no row'}`);
+      flowRow = { name: data.name, steps: data.steps as Array<{ skill: string; argsTemplate: string }> };
+    }
+
     // ── workflow_runs row + persistence (the shared persister) ──
     persister = await createWorkflowRunPersister(adminSupabase, {
       workspaceId,
       jobId,
-      workflow,
+      workflow: flowRow ? `flow:${flowRow.name}` : workflow,
       repo: repoSlug,
       issueNumber: runIssueNumber,
       prNumber: prNumber ?? ciFollowupSeed?.prNumber ?? null,
@@ -135,7 +155,33 @@ export async function executeWorkflowJob(
     let tokensUsed = 0;
     let outcomeJson: unknown = null;
 
-    if (workflow === 'autofix') {
+    if (workflow === 'flow') {
+      if (!flowRow) throw new Error('flow not loaded (internal error)');
+      const result = await core.runFlow({
+        flow: flowRow,
+        input: flowInput ?? String(runIssueNumber),
+        store,
+        config,
+        github,
+        issueNumber: runIssueNumber,
+        onEvent,
+        onAgentEvent,
+        onRunRecord,
+        pauseRequested,
+        cancelRequested,
+      });
+      outcomeJson = result;
+      runStatus = result.status === 'succeeded' ? 'succeeded'
+        : result.status === 'paused' ? 'paused'
+        : result.status === 'cancelled' ? 'cancelled'
+        : 'failed';
+      reason = result.reason;
+      prUrl = result.prUrl ?? null;
+      outPrNumber = result.prNumber ?? outPrNumber;
+      branch = result.branch ?? null;
+      headSha = result.headSha ?? null;
+      tokensUsed = result.tokensUsed;
+    } else if (workflow === 'autofix') {
       const orch = new core.AutofixOrchestrator(store, config, github);
       const outcome = await orch.processIssue(runIssueNumber, {
         apply: true,
diff --git a/packages/gui/src/lib/persist-workflow-run.ts b/packages/gui/src/lib/persist-workflow-run.ts
index 7e82d43..53d266f 100644
--- a/packages/gui/src/lib/persist-workflow-run.ts
+++ b/packages/gui/src/lib/persist-workflow-run.ts
@@ -7,7 +7,12 @@ type AgentRunsRow = Database['public']['Tables']['agent_runs']['Row'];
 export interface CreateWorkflowRunOpts {
   workspaceId: string;
   jobId?: string | null;
-  workflow: 'autofix' | 'ci-followup' | 'triage' | 'single-action';
+  /**
+   * The `workflow_runs.workflow` column — plain text. Built-ins are 'autofix',
+   * 'ci-followup', 'triage'; the legacy single-action path uses 'single-action';
+   * custom data-driven workflows carry their descriptor id (e.g. 'autofix-lite').
+   */
+  workflow: string;
   repo: string | null;
   issueNumber: number | null;
   prNumber?: number | null;
diff --git a/packages/gui/src/lib/scheduler/run-dispatch.ts b/packages/gui/src/lib/scheduler/run-dispatch.ts
index 59b2c6f..17ff9af 100644
--- a/packages/gui/src/lib/scheduler/run-dispatch.ts
+++ b/packages/gui/src/lib/scheduler/run-dispatch.ts
@@ -55,7 +55,7 @@ export async function runDispatch(supabase: SupabaseClient<Database>): Promise<D
       continue;
     }
 
-    const payload = (job.payload ?? {}) as { ciFollowup?: CiFollowupInput };
+    const payload = (job.payload ?? {}) as { ciFollowup?: CiFollowupInput; flowId?: string; flowInput?: string };
     void executeWorkflowJob(supabase, {
       workspaceId: job.workspace_id,
       repo: job.repo,
@@ -64,6 +64,8 @@ export async function runDispatch(supabase: SupabaseClient<Database>): Promise<D
       prNumber: job.pr_number ?? undefined,
       jobId: job.id,
       ciFollowupSeed: payload.ciFollowup,
+      flowId: payload.flowId,
+      flowInput: payload.flowInput,
     }).catch((err) => {
       console.error(`[dispatch] job ${job.id} crashed:`, err);
     });
diff --git a/packages/gui/src/lib/supabase/types.ts b/packages/gui/src/lib/supabase/types.ts
index 995a545..e1063d5 100644
--- a/packages/gui/src/lib/supabase/types.ts
+++ b/packages/gui/src/lib/supabase/types.ts
@@ -18,7 +18,7 @@ export type WorkflowBackend = 'anthropic-api' | 'claude-cli' | 'codex-cli';
 // Note: `@cezar/core` also exports a `WorkflowRunStatus` (the in-process engine
 // state). These are the *DB* string sets — kept local + named distinctly to
 // avoid confusing the two.
-export type JobKind = 'triage' | 'autofix' | 'ci-followup';
+export type JobKind = 'triage' | 'autofix' | 'ci-followup' | 'flow';
 export type JobStatus = 'queued' | 'claimed' | 'running' | 'done' | 'failed' | 'cancelled';
 export type DbWorkflowRunStatus = 'queued' | 'running' | 'paused' | 'succeeded' | 'failed' | 'cancelled';
 export type AgentRunStatus = 'running' | 'succeeded' | 'failed' | 'skipped';
@@ -155,6 +155,29 @@ export interface Database {
         };
         Update: Partial<Database['public']['Tables']['user_github_tokens']['Insert']>;
       };
+      flows: {
+        Row: {
+          id: string;
+          workspace_id: string;
+          name: string;
+          /** Array of `{ skill: string; argsTemplate: string; stopChainIfContains?: string }`. */
+          steps: Json;
+          /** Array of trigger objects — `{ kind: 'issue.opened' } | { kind: 'issue.labeled', label: string }`. */
+          triggers: Json;
+          /** Paused flows skip webhook auto-triggers but stay manually runnable. */
+          paused: boolean;
+          created_at: string;
+          updated_at: string;
+        };
+        Insert: Omit<Database['public']['Tables']['flows']['Row'], 'id' | 'triggers' | 'paused' | 'created_at' | 'updated_at'> & {
+          id?: string;
+          triggers?: Json;
+          paused?: boolean;
+          created_at?: string;
+          updated_at?: string;
+        };
+        Update: Partial<Database['public']['Tables']['flows']['Insert']>;
+      };
       workflow_bindings: {
         Row: {
           id: string;
diff --git a/packages/gui/supabase/migrations/0021_flows.sql b/packages/gui/supabase/migrations/0021_flows.sql
new file mode 100644
index 0000000..379c63e
--- /dev/null
+++ b/packages/gui/supabase/migrations/0021_flows.sql
@@ -0,0 +1,69 @@
+-- Simple workflow chains — one row per "flow" (a named chain of skill steps).
+--
+--   * Each flow has a name (e.g. "fix github issue") and an ordered list of
+--     `{ skill, argsTemplate, stopChainIfContains? }` pairs. The skill is
+--     the markdown file name under `<repo>/.ai/skills/` (no extension),
+--     discovered via `repo_skills` (migration 0007).
+--   * The args template renders against a fixed scope:
+--       {{input}}                  — the value passed when the flow is run
+--       {{previousTaskId}}         — id of the previous step's agent_run
+--       {{previousPullRequestUrl}} — url of any PR opened during the previous step
+--       {{previousPullRequestNumber}}
+--     PR variables are extracted from `PR_URL=…` / `PR_NUMBER=…` markers in
+--     the previous step's agent text output (soft contract with the skill body).
+--   * `stopChainIfContains` (optional, per-step) — when the step's text output
+--     contains this substring, the chain ends cleanly with status `succeeded`
+--     and reason "stopped at step N…". Lets gating skills short-circuit
+--     without a JSON contract.
+--   * `triggers` — array of trigger objects matched by the GitHub App webhook.
+--     Today's shapes:
+--       { "kind": "issue.opened" }
+--       { "kind": "issue.labeled", "label": "auto-fix" }
+--     The dispatcher dedupes against in-flight (workspace, flow, issue) jobs.
+--   * `paused` — operational kill switch. Paused flows skip auto-triggers
+--     but stay editable + manually runnable.
+--
+-- The dispatcher (execute-workflow-job.ts) handles `kind='flow'` by loading
+-- the row, building an in-memory `Workflow` (one agent step per flow step),
+-- and running it through the existing engine.
+
+create table flows (
+  id            uuid primary key default gen_random_uuid(),
+  workspace_id  uuid not null references workspaces(id) on delete cascade,
+  name          text not null,
+  -- Array of `{ skill: text, argsTemplate: text, stopChainIfContains?: text }`.
+  -- Empty steps array is allowed (save a flow before adding steps); the
+  -- dispatcher rejects empty steps at run time.
+  steps         jsonb not null default '[]'::jsonb,
+  -- Array of trigger objects matched by the webhook receiver.
+  triggers      jsonb not null default '[]'::jsonb,
+  -- Operational kill switch — paused flows skip webhook auto-triggers but
+  -- remain editable and manually runnable.
+  paused        boolean not null default false,
+  created_at    timestamptz not null default now(),
+  updated_at    timestamptz not null default now()
+);
+
+create unique index flows_workspace_name_unique on flows (workspace_id, name);
+create index flows_workspace_idx on flows(workspace_id);
+
+-- Speeds up the webhook trigger lookup (rare but bursty traffic — every
+-- issues event against any installed repo). GIN over the JSONB array makes
+-- the trigger search index-eligible without a separate row-per-trigger table.
+create index flows_triggers_gin on flows using gin (triggers);
+
+-- Allow `jobs.kind = 'flow'` so the dispatcher can claim flow runs.
+alter table jobs drop constraint jobs_kind_check;
+alter table jobs add constraint jobs_kind_check
+  check (kind in ('triage','autofix','ci-followup','flow'));
+
+-- ─── RLS ────────────────────────────────────────────────────────────────
+alter table flows enable row level security;
+create policy "flows_member_select" on flows
+  for select using (is_workspace_member(workspace_id));
+create policy "flows_admin_write" on flows
+  for all using (is_workspace_admin(workspace_id)) with check (is_workspace_admin(workspace_id));
+
+-- ─── updated_at trigger ─────────────────────────────────────────────────
+create trigger flows_touch before update on flows
+  for each row execute function touch_updated_at();
diff --git a/packages/runner/src/execute-job-locally.ts b/packages/runner/src/execute-job-locally.ts
index f1c7ab6..6f11d23 100644
--- a/packages/runner/src/execute-job-locally.ts
+++ b/packages/runner/src/execute-job-locally.ts
@@ -25,7 +25,7 @@ export async function executeJobLocally(
   claimed: ClaimedJob,
   controls: ExecuteJobControls,
 ): Promise<void> {
-  const { workflowRunId, job, workspace, githubToken, ciFollowupSeed } = claimed;
+  const { workflowRunId, job, workspace, githubToken, ciFollowupSeed, flow } = claimed;
 
   // ── event buffer ──────────────────────────────────────────────────────
   const buffer: RunnerEvent[] = [];
@@ -152,6 +152,40 @@ export async function executeJobLocally(
           tokensUsed,
         },
       };
+    } else if (job.kind === 'flow') {
+      if (!flow) throw new Error('flow job is missing payload.flowId / claim payload');
+      if (job.issueNumber == null) throw new Error('flow job has no issue_number');
+      const flowOutcome = await core.runFlow({
+        flow: { name: flow.name, steps: flow.steps },
+        input: flow.input || String(job.issueNumber),
+        store, config, github,
+        issueNumber: job.issueNumber,
+        onEvent, onAgentEvent, onRunRecord,
+        pauseRequested, cancelRequested,
+      });
+      const status = flowOutcome.status === 'succeeded' ? 'succeeded'
+        : flowOutcome.status === 'paused' ? 'paused'
+        : flowOutcome.status === 'cancelled' ? 'cancelled'
+        : 'failed';
+      // FinalizeRunBody.status is a narrow union — map our workflow status onto
+      // it. The cockpit uses `outcome` for the rich detail anyway.
+      const finalizeStatus = status === 'succeeded' ? 'succeeded'
+        : status === 'paused' ? 'paused'
+        : status === 'cancelled' ? 'cancelled'
+        : 'failed';
+      result = {
+        status,
+        finalize: {
+          status: finalizeStatus,
+          outcome: flowOutcome,
+          reason: flowOutcome.reason ?? null,
+          prUrl: flowOutcome.prUrl ?? null,
+          prNumber: flowOutcome.prNumber ?? (job.prNumber ?? null),
+          branch: flowOutcome.branch ?? null,
+          headSha: flowOutcome.headSha ?? null,
+          tokensUsed,
+        },
+      };
     } else {
       // TODO(2b3+): wire the data-driven `runTriagePass` for the self-hosted
       // runner. Triage is repo-less and rare on self-hosted runners; until the
diff --git a/packages/runner/src/runner-client.ts b/packages/runner/src/runner-client.ts
index 7513399..c65591c 100644
--- a/packages/runner/src/runner-client.ts
+++ b/packages/runner/src/runner-client.ts
@@ -1,4 +1,4 @@
-import type { Config, Store, CiFollowupInput } from '@cezar/core';
+import type { Config, Store, CiFollowupInput, FlowStep } from '@cezar/core';
 
 // ─── wire shapes ────────────────────────────────────────────────────────
 // What `GET /api/runner/jobs` returns when there's work. The SaaS has already
@@ -9,7 +9,7 @@ export interface ClaimedJob {
     id: string;
     workspaceId: string;
     repo: string | null;
-    kind: 'triage' | 'autofix' | 'ci-followup';
+    kind: 'triage' | 'autofix' | 'ci-followup' | 'flow';
     issueNumber: number | null;
     prNumber: number | null;
     requiredBackend: string | null;
@@ -24,6 +24,8 @@ export interface ClaimedJob {
   store: Store;
   /** For `ci-followup` jobs only — lifted off `jobs.payload.ciFollowup`. */
   ciFollowupSeed: CiFollowupInput | null;
+  /** For `flow` jobs only — the `flows` row referenced by `jobs.payload.flowId`. */
+  flow: { name: string; steps: FlowStep[]; input: string } | null;
 }
 
 /** One streamed event the runner POSTs back to `/api/runner/runs/:id/events`. */