workflow slug: backfill for existing rows + frontend surfacing

Migration backfill
------------------
The slug migration previously assumed `workflow_lineages` was empty
(`NOT NULL DEFAULT ''` then drop default). On any populated environment
that would either fail when adding the unique index, or collapse every
row to `slug = ''`.

Rewrote the in-place migration to:

  1. Add `slug TEXT` (nullable).
  2. Backfill in SQL: kebab-case the `name` column (lower, replace
     `[^a-z0-9]+` with `-`, trim leading/trailing `-`). Rows whose name
     normalizes to an empty string fall back to `workflow`.
  3. Deduplicate within `group_id` using `row_number()` ordered by
     `created_at, id` -- earliest creator keeps the bare slug, others
     get `-2`, `-3`, ...
  4. SET NOT NULL, then add the unique index `(group_id, slug)`.

Verified locally against synthetic rows: 3 collisions of
"Invoice Workflow" -> {invoice-workflow, invoice-workflow-2,
invoice-workflow-3}; "Invoice Workflow!!! (v2)" -> invoice-workflow-v2;
all-symbol name "   ---   " -> workflow.

Frontend slug surfacing
-----------------------
New shared chip component (Mantine):

  src/components/workflow/SlugChip.tsx
    `<SlugChip slug="..." />` renders the slug as a `<Code>` element
    with a `CopyButton` tooltip ("Copy slug" -> "Copied" on click).

Surfaced in three places:

  * WorkflowListPage: new "Slug" column between Name and Description.
  * WorkflowEditPage: slug shown under the title (slugs are immutable
    once a lineage exists, so it's read-only here -- only a copy
    affordance, no edit).
  * WorkflowPage (create): a small live "API handle (slug): <preview>"
    description under the Name input. `previewSlug()` mirrors the
    backend `slugifyName` so the user can anticipate what they'll
    get; server still has the final say on dedup.

Type plumbing
-------------
`WorkflowInfo` (and the duplicate definition in
`features/benchmarking/hooks/useWorkflows.ts`) gain a `slug: string`
field to match the backend response shape.

Test summary
------------
- Frontend: tsc clean, biome clean, existing test suites unchanged.
- Backend: full Jest run -- 2065 tests pass, 0 regressions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: strukalex

apps/frontend/src/components/workflow/SlugChip.tsx

@@ -0,0 +1,40 @@
+import { ActionIcon, Code, CopyButton, Group, Tooltip } from "@mantine/core";
+import { IconCheck, IconCopy } from "@tabler/icons-react";
+
+type Size = "xs" | "sm";
+
+interface SlugChipProps {
+  slug: string;
+  /** Visual scale of the rendered chip. Defaults to "sm". */
+  size?: Size;
+}
+
+/**
+ * Renders a workflow's slug as a copyable code chip.
+ *
+ * The slug is the stable, URL/CLI-friendly handle used in upload requests
+ * (`workflow_slug`) -- exposed here so operators can copy it without digging
+ * through the API response.
+ */
+export function SlugChip({ slug, size = "sm" }: SlugChipProps) {
+  return (
+    <Group gap={4} wrap="nowrap" align="center">
+      <Code data-testid="workflow-slug">{slug}</Code>
+      <CopyButton value={slug} timeout={1500}>
+        {({ copied, copy }) => (
+          <Tooltip label={copied ? "Copied" : "Copy slug"} withArrow>
+            <ActionIcon
+              size={size}
+              variant="subtle"
+              color={copied ? "green" : "gray"}
+              onClick={copy}
+              aria-label="Copy workflow slug"
+            >
+              {copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
+            </ActionIcon>
+          </Tooltip>
+        )}
+      </CopyButton>
+    </Group>
+  );
+}

apps/frontend/src/data/hooks/useWorkflows.ts

@@ -6,6 +6,8 @@ import { apiService } from "../services/api.service";
 export interface WorkflowInfo {
   id: string;
   workflowVersionId: string;
+  /** Stable, URL/CLI-friendly handle. Unique within a group. */
+  slug: string;
   name: string;
   description: string | null;
   actorId: string;

apps/frontend/src/features/benchmarking/hooks/useWorkflows.ts

@@ -5,6 +5,7 @@ import { apiService } from "@/data/services/api.service";
 interface WorkflowInfo {
   id: string;
   workflowVersionId: string;
+  slug: string;
   name: string;
   version: number;
   description: string | null;

apps/frontend/src/pages/WorkflowEditPage.tsx

@@ -16,6 +16,7 @@ import {
 import { notifications } from "@mantine/notifications";
 import { IconArrowLeft, IconCheck } from "@tabler/icons-react";
 import { useEffect, useState } from "react";
+import { SlugChip } from "../components/workflow/SlugChip";
 import { WorkflowVisualization } from "../components/workflow/WorkflowVisualization";
 import { useUpdateWorkflow, useWorkflow } from "../data/hooks/useWorkflows";
 import { useTemplateModels } from "../features/annotation/template-models/hooks/useTemplateModels";
@@ -334,8 +335,14 @@ export function WorkflowEditPage({
   return (
     <Stack gap="lg">
       <Group justify="space-between">
-        <Stack gap={2}>
+        <Stack gap={4}>
           <Title order={2}>Edit Workflow</Title>
+          <Group gap="xs">
+            <Text c="dimmed" size="sm">
+              Slug:
+            </Text>
+            <SlugChip slug={workflow.slug} />
+          </Group>
           <Text c="dimmed" size="sm">
             Modify workflow configuration and parameters
           </Text>

apps/frontend/src/pages/WorkflowListPage.tsx

@@ -16,6 +16,7 @@ import { notifications } from "@mantine/notifications";
 import { IconEdit, IconFlask, IconPlus, IconTrash } from "@tabler/icons-react";
 import { type ReactNode, useState } from "react";
 import { useNavigate } from "react-router-dom";
+import { SlugChip } from "../components/workflow/SlugChip";
 import { useDeleteWorkflow, useWorkflows } from "../data/hooks/useWorkflows";
 
 export function WorkflowListPage() {
@@ -161,6 +162,7 @@ export function WorkflowListPage() {
             <Table.Thead>
               <Table.Tr>
                 <Table.Th>Name</Table.Th>
+                <Table.Th>Slug</Table.Th>
                 <Table.Th>Description</Table.Th>
                 <Table.Th>Version</Table.Th>
                 <Table.Th>Schema</Table.Th>
@@ -175,6 +177,9 @@ export function WorkflowListPage() {
                   <Table.Td>
                     <Text fw={500}>{workflow.name}</Text>
                   </Table.Td>
+                  <Table.Td>
+                    <SlugChip slug={workflow.slug} />
+                  </Table.Td>
                   <Table.Td>
                     <Text c="dimmed" size="sm" lineClamp={1}>
                       {workflow.description || "—"}

apps/frontend/src/pages/WorkflowPage.tsx

@@ -1,6 +1,7 @@
 import {
   Badge,
   Button,
+  Code,
   Grid,
   Group,
   NumberInput,
@@ -20,6 +21,21 @@ import { useCreateWorkflow } from "../data/hooks/useWorkflows";
 import { useTemplateModels } from "../features/annotation/template-models/hooks/useTemplateModels";
 import type { WorkflowStepsConfig } from "../types/workflow";
 
+/**
+ * Mirrors the backend `slugifyName` so the create form can preview the
+ * handle that will be generated. The server still has the last word --
+ * it deduplicates within the group with `-2`, `-3`, ... suffixes.
+ */
+function previewSlug(name: string): string {
+  const base = name
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return base.length > 0 ? base : "workflow";
+}
+
 interface WorkflowStepConfig {
   enabled: boolean;
   parameters?: Record<string, unknown>;
@@ -272,6 +288,19 @@ export function WorkflowPage() {
                 <TextInput
                   label="Workflow Name"
                   placeholder="e.g., High-Confidence OCR Workflow"
+                  description={
+                    workflowName.trim().length > 0 ? (
+                      <Text size="xs" component="span">
+                        API handle (slug):{" "}
+                        <Code>{previewSlug(workflowName)}</Code>
+                        <Text size="xs" c="dimmed" component="span">
+                          {" "}
+                          — server picks the final value, deduping within the
+                          group if needed.
+                        </Text>
+                      </Text>
+                    ) : undefined
+                  }
                   value={workflowName}
                   onChange={(e) => setWorkflowName(e.target.value)}
                   required

apps/shared/prisma/migrations/20260513174924_add_workflow_slug_and_ocr_content/migration.sql

@@ -2,6 +2,41 @@
 ALTER TABLE "ocr_results" ADD COLUMN "content" JSONB;
 
 -- Add stable, human-friendly slug to workflow lineages, unique within a group.
-ALTER TABLE "workflow_lineages" ADD COLUMN "slug" TEXT NOT NULL DEFAULT '';
-ALTER TABLE "workflow_lineages" ALTER COLUMN "slug" DROP DEFAULT;
+-- Created as nullable, backfilled from `name` (kebab-case, deduped within group),
+-- then made NOT NULL and uniquely indexed.
+ALTER TABLE "workflow_lineages" ADD COLUMN "slug" TEXT;
+
+WITH base AS (
+  SELECT
+    id,
+    group_id,
+    CASE
+      WHEN length(trim(both '-' from
+        regexp_replace(lower(name), '[^a-z0-9]+', '-', 'g'))) > 0
+      THEN trim(both '-' from
+        regexp_replace(lower(name), '[^a-z0-9]+', '-', 'g'))
+      ELSE 'workflow'
+    END AS base_slug,
+    created_at
+  FROM "workflow_lineages"
+),
+ranked AS (
+  SELECT
+    id,
+    base_slug,
+    row_number() OVER (
+      PARTITION BY group_id, base_slug
+      ORDER BY created_at, id
+    ) AS rn
+  FROM base
+)
+UPDATE "workflow_lineages" wl
+SET slug = CASE
+  WHEN r.rn = 1 THEN r.base_slug
+  ELSE r.base_slug || '-' || r.rn
+END
+FROM ranked r
+WHERE r.id = wl.id;
+
+ALTER TABLE "workflow_lineages" ALTER COLUMN "slug" SET NOT NULL;
 CREATE UNIQUE INDEX "workflow_lineages_group_id_slug_key" ON "workflow_lineages"("group_id", "slug");