@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/pages/ServicePage.tsx

@@ -10,11 +10,18 @@ import {
   technologiesOf,
 } from "../catalog";
 import { flowRoles } from "../lib/derive";
+import { bridges } from "../lib/centrality";
 import { treeHref } from "../lib/source-link";
 import { flowHealth } from "../lib/flow-tree";
 import { adrsForService, isCurrent } from "../lib/adr";
 import { ADR_ROW_COLUMNS, AdrRow } from "../components/AdrRow";
-import { EVENT_ANCHOR, SERVICE_ANCHOR, aggregatePath, paths } from "../routes";
+import {
+  EVENT_ANCHOR,
+  OVERVIEW_ANCHOR,
+  SERVICE_ANCHOR,
+  aggregatePath,
+  paths,
+} from "../routes";
 import { Markdown } from "../components/Markdown";
 import { middleTruncate, plural } from "../lib/format";
 import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
@@ -31,6 +38,8 @@ import {
   hasAsyncSpec,
 } from "../components/AsyncApiReference";
 import { ChannelRows } from "../components/ChannelRows";
+import { DocsLinks } from "../components/DocsLinks";
+import { DeploymentRows } from "../components/DeploymentRows";
 import { CommandRows } from "../components/CommandRows";
 import { ModuleSpec } from "../components/SourceDoc";
 import { hasSchema, SchemaDocument } from "../components/SchemaDocument";
@@ -45,7 +54,11 @@ import { NotFound } from "./NotFound";
 import { C4View } from "../likec4/C4View";
 import { LevelSwitch } from "../likec4/levels";
 import type { C4Level } from "../likec4/levels";
-import { serviceInsideViewId, serviceViewId } from "../likec4/ids";
+import {
+  serviceDeployViewId,
+  serviceInsideViewId,
+  serviceViewId,
+} from "../likec4/ids";
 import { index } from "../data";
 import { storesOfService } from "../lib/data-model";
 import { ErCanvas } from "../er/ErCanvas";
@@ -112,6 +125,11 @@ export function ServicePage() {
   const flows = flowRoles(catalog, service.id);
   const tree = treeHref(service.path, service, allRepos(catalog));
   const owners = ownersOf(service);
+  const deployments = index.deploymentsByService.get(service.id) ?? [];
+  // The service as a road: the pairs of contexts it stands between, if any.
+  // Derived from the whole estate, so it is computed here and not carried
+  // on the service, which knows only its own edges.
+  const road = bridges(catalog).find((b) => b.id === service.id) ?? null;
   const adrs = adrsForService(catalog, service.id, context.id);
   const current = adrs.filter(isCurrent);
   const retired = adrs.filter((a) => !isCurrent(a));
@@ -168,6 +186,17 @@ export function ServicePage() {
         right={
           <>
             <span className="chip-lg">{componentKind(service)}</span>
+            {road ? (
+              <Link
+                to={`${paths.overview()}#${OVERVIEW_ANCHOR.bridges}`}
+                className="chip-lg border-line text-muted hover:text-ink"
+                title={`${Math.round(road.betweenness * 100)}% of the shortest paths between other services run through this one — see the bridges on the overview`}
+              >
+                bridge
+                <span className="text-muted">·</span>
+                {road.between.map((pair) => `${pair.a} ↔ ${pair.b}`).join(", ")}
+              </Link>
+            ) : null}
             <ContextPill id={context.id} name={context.name} />
           </>
         }
@@ -186,6 +215,7 @@ export function ServicePage() {
               open ↗
             </a>
           ) : null}
+          <DocsLinks name={service.name} />
           {/* Who to ask, read out of CODEOWNERS. A handle is copied rather
               than linked: it is what a reviewer types into a request, and a
               link to a team page is a page most readers cannot open. */}
@@ -307,6 +337,32 @@ export function ServicePage() {
                 />
               </section>
             ) : null}
+            {/* Where it runs, read from the deployer's snapshot. Beside the
+                commands because it answers the next question after "how do
+                I build it": which commit stands where. Absent entirely when
+                no snapshot places it - a heading over an empty list would
+                claim the service runs nowhere, and nobody made that claim. */}
+            {deployments.length > 0 ? (
+              <section
+                id={SERVICE_ANCHOR.deployments}
+                className="mt-section max-w-table"
+              >
+                <SectionTitle anchor={SERVICE_ANCHOR.deployments}>
+                  Where it runs
+                </SectionTitle>
+                <DeploymentRows deployments={deployments} />
+                {/* The same rows as a picture: the service's instances with
+                    the environment, cluster and namespace drawn as the
+                    frames they are. Under the rows, because the rows carry
+                    the commit and the images and the picture carries where. */}
+                <div className="mt-3">
+                  <C4View
+                    viewId={serviceDeployViewId(service)}
+                    height={220}
+                  />
+                </div>
+              </section>
+            ) : null}
             {showDomain ? (
               <section
                 id={SERVICE_ANCHOR.aggregates}

package/src/pages/Settings.tsx

@@ -48,12 +48,16 @@ import {
 import type { Discovery, ProjectDraft, ProjectPlan, RunEvent } from "../lib/local-api";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { localKeys, localStatusQuery } from "../lib/queries";
+import { pluginByName, pluginIcon } from "../lib/plugins";
+import { PluginIcon } from "../components/PluginIcon";
 import { bare, sourceHref, treeHref } from "../lib/source-link";
 import { paths } from "../routes";
 import { CapabilityEmpty, Empty, SectionTitle } from "../components/PageHeader";
 import { Modal } from "../components/Overlay";
 import { MachineDocs } from "../components/MachineDocs";
 import { DeliverySettings } from "./settings/DeliverySettings";
+import { RecordingSettings } from "./settings/RecordingSettings";
+import { RulesSettings } from "./settings/RulesSettings";
 import { PreferencesSettings } from "./settings/PreferencesSettings";
 import { AboutSettings } from "./settings/AboutSettings";
 import { IntegrationsSettings } from "./settings/IntegrationsSettings";
@@ -518,10 +522,15 @@ function PluginsList() {
             const runSteps = setupInfo.run?.steps.filter((step) => step.plugin === plugin.name) ?? [];
             const health = plugin.stepCount === 0 ? "unchecked" : healthFor(runSteps, declared.length, setupInfo);
             const outputs = [...new Set(runSteps.flatMap((step) => step.files))];
+            // What the plugin says of itself, when it is one the package ships.
+            // A plugin the manifest declares by its own `process` is not on the
+            // index, and the row says nothing rather than something made up.
+            const shipped = pluginByName(plugin.name);
             return (
               <details key={plugin.name} id={`plugin-${plugin.name}`} className="group scroll-mt-4 border-t border-line">
                 <summary className="flex cursor-pointer list-none items-center gap-2.5 px-3 py-1.5 hover:bg-surface/60">
                   {health === "healthy" ? <HealthDot health={health} /> : null}
+                  <PluginIcon icon={pluginIcon(plugin.name, shipped?.category)} className="text-muted" />
                   <span className="mono truncate text-ink" title={plugin.name}>{plugin.name}</span>
                   <Runtime plugin={plugin} icon />
                   {health === "healthy" ? null : <HealthBadge health={health} />}
@@ -538,6 +547,7 @@ function PluginsList() {
                   <div className="grid gap-5 lg:grid-cols-[minmax(0,1.4fr)_minmax(14rem,1fr)]">
                     <div><div className="label mb-2">last run</div><PipelineSteps steps={runSteps} /></div>
                     <div className="space-y-4">
+                      {shipped ? <div><div className="label mb-2">what it reads</div><p className="text-muted">{shipped.summary}</p><Link to={paths.plugin(plugin.name)} className="mono mt-1 inline-block text-accent hover:underline">options and source →</Link></div> : null}
                       <div><div className="label mb-2">runtime</div><p className="mono"><Runtime plugin={plugin} /></p></div>
                       <div><div className="label mb-2">used by</div>{plugin.projectIds.length > 0 ? <div className="flex flex-wrap gap-1.5">{plugin.projectIds.map((id) => <Link key={id} to={`${paths.settingsProjects()}#project-${id}`} className="chip border-line-strong hover:border-accent hover:text-accent">{projectNames.get(id) ?? id}</Link>)}</div> : <p className="mono text-muted">{plugin.stepCount > 0 ? "Estate-wide catalog" : "No pipeline step uses this plugin."}</p>}</div>
                       {outputs.length > 0 ? <div><div className="label mb-2">outputs</div><ul className="mono space-y-1 text-muted">{outputs.map((output) => <li key={output} className="truncate"><FileLink path={output} /></li>)}</ul></div> : null}
@@ -642,6 +652,8 @@ const CAPABILITIES: Record<string, { title: string; summary: string }> = {
   "rust-domain": { title: "Rust domain model", summary: "Aggregates, entities, value objects and domain events." },
   "java-domain": { title: "Java domain model", summary: "Aggregates, entities, value objects and domain events." },
   "django-domain": { title: "Django data model", summary: "Models and their relationships." },
+  "laravel-domain": { title: "Laravel data model", summary: "Eloquent models, events and listeners, routes and controllers." },
+  "php-ddd": { title: "PHP DDD model", summary: "Bounded contexts laid out by module and hexagonal layer: aggregates, value objects, domain events, commands, queries, subscribers, Doctrine mappings." },
   openapi: { title: "HTTP API contract", summary: "Operations and messages declared by OpenAPI or Swagger." },
   wsdl: { title: "SOAP contract", summary: "Services, operations and messages declared by WSDL." },
   "http-clients": { title: "Outbound integrations", summary: "HTTP and SOAP calls, provider branches and code flows." },
@@ -773,7 +785,7 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
   function configure(found: Discovery, commit: string, selectedSourcePath: string, projectId?: string) {
     setDiscovery(found);
     const plugins = found.detections.filter((item) => item.selected).map((item) => item.plugin);
-    const domainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin));
+    const domainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain", "php-ddd"].includes(plugin));
     setDraft({ source, root: found.root, repository, ref, commit, sourcePath: selectedSourcePath, ...found.defaults, ...(projectId ? { id: projectId } : {}), contextName: found.defaults.group ? found.defaults.group.replace(/(^|-)([a-z])/g, (_, gap, letter) => `${gap ? " " : ""}${letter.toUpperCase()}`) : "", contextSummary: "", classification: "supporting", groupKind: domainModel ? "bounded-context" : "system", componentKind: domainModel ? "service" : "application", replaceStarter: Boolean(starter), plugins });
     setStage("configure");
   }
@@ -1020,11 +1032,23 @@ const SETTINGS_LINKS = [
   ["Projects", paths.settingsProjects()],
   ["Pipeline", paths.settingsPipeline()],
   ["Delivery", paths.settingsDelivery()],
+  ["Recordings", paths.settingsRecordings()],
+  ["Rules", paths.settingsRules()],
   ["Integrations", paths.settingsIntegrations()],
   ["Preferences", paths.settingsPreferences()],
   ["About", paths.settingsAbout()],
 ] as const;
 
+function RecordingsRoute({ local }: { local: boolean }) {
+  const setupInfo = useSetup();
+  return (
+    <section>
+      <SectionTitle right={local ? "reviewed before writing" : "local mode required"}>Recordings</SectionTitle>
+      <RecordingSettings local={local} projects={setupInfo.projects} />
+    </section>
+  );
+}
+
 function SettingsNav() {
   return (
     <nav className="mt-5 border-b border-line" aria-label="Settings sections">
@@ -1159,7 +1183,7 @@ function PipelineSettings() {
         ) : (
           <>
             <PluginsList />
-            <p className="mono mt-2 text-muted">WASM runs without network or environment access, and a generator without a filesystem. A host process runs with the permissions of the build; a plugin in the host is Portolan's own code doing what needs a socket, such as fetching another repository.</p>
+            <p className="mono mt-2 text-muted">WASM runs without network or environment access, and a generator without a filesystem. A host process runs with the permissions of the build; a plugin in the host is Portolan's own code doing what needs a socket, such as fetching another repository. Every plugin the package ships, with what it reads and the options it takes, is on the <Link to={paths.plugins()} className="text-accent hover:underline">plugin reference</Link>.</p>
           </>
         )}
       </section>
@@ -1201,6 +1225,8 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
             <Route path="projects" element={<ProjectsSettings local={local} onAdd={onAdd} onRemove={onRemove} />} />
             <Route path="pipeline" element={<PipelineSettings />} />
             <Route path="delivery" element={<section><SectionTitle right={local ? "preview before writing" : "local mode required"}>Delivery presets</SectionTitle><DeliverySettings local={local} /></section>} />
+            <Route path="recordings" element={<RecordingsRoute local={local} />} />
+            <Route path="rules" element={<RulesSettings local={local} />} />
             <Route path="integrations" element={<IntegrationsSettings />} />
             <Route path="preferences" element={<PreferencesSettings />} />
             <Route path="about" element={<AboutSettings />} />

package/src/pages/settings/AboutSettings.tsx

@@ -1,4 +1,4 @@
-import { ArrowRight, BookOpen, CircleDot, GitBranch, ShieldCheck } from "lucide-react";
+import { ArrowRight, BookOpen, CircleDot, GitBranch, Puzzle, ShieldCheck } from "lucide-react";
 import type { Variants } from "motion/react";
 import { Link } from "react-router";
 
@@ -94,6 +94,13 @@ export function AboutSettings() {
         >
           <div className="label mb-2">resources</div>
           <div className="divide-y divide-line">
+            <Link
+              to={paths.plugins()}
+              className="flex items-center gap-2 py-2.5 text-muted transition-colors hover:text-ink"
+            >
+              <Puzzle size={15} aria-hidden className="shrink-0" />
+              Plugin reference
+            </Link>
             <a
               href={PRODUCT_README}
               target="_blank"

package/src/pages/settings/IntegrationsSettings.tsx

@@ -1,21 +1,45 @@
 import { ExternalLink, Save, Trash2 } from "lucide-react";
 import { useState } from "react";
+import type { StoreApi, UseBoundStore } from "zustand";
 import { SectionTitle } from "../../components/PageHeader";
 import { TechIcon } from "../../components/TechIcon";
-import { normalizeKafkaUiUrl, useKafkaUi } from "../../lib/kafka-ui";
+import { useConfluence } from "../../lib/confluence";
+import { normalizeIntegrationUrl } from "../../lib/integration-url";
+import type { IntegrationState } from "../../lib/integration-url";
+import { useKafkaUi } from "../../lib/kafka-ui";
+import { useNotion } from "../../lib/notion";
 import { techGlyph } from "../../lib/tech";
 
 const FIELD =
   "mono w-full rounded-control border border-line bg-canvas px-3 py-2 text-ink outline-none focus:border-accent";
 
-function KafkaUiCard() {
-  const configured = useKafkaUi((state) => state.url);
-  const setUrl = useKafkaUi((state) => state.setUrl);
+function IntegrationCard({
+  name,
+  brand,
+  summary,
+  label,
+  placeholder,
+  hint,
+  store,
+}: {
+  /** The heading, and what the open button says. */
+  name: string;
+  /** The brand whose mark sits beside the heading. */
+  brand: string;
+  summary: string;
+  label: string;
+  placeholder: string;
+  /** What a valid URL means: shown under the field. */
+  hint: string;
+  store: UseBoundStore<StoreApi<IntegrationState>>;
+}) {
+  const configured = store((state) => state.url);
+  const setUrl = store((state) => state.setUrl);
   const [draft, setDraft] = useState(configured);
-  const normalized = normalizeKafkaUiUrl(draft);
+  const normalized = normalizeIntegrationUrl(draft);
   const valid = normalized !== null;
   const dirty = valid && normalized !== configured;
-  const glyph = techGlyph("Kafka");
+  const glyph = techGlyph(brand);
 
   const save = () => {
     if (normalized === null) return;
@@ -36,19 +60,17 @@ function KafkaUiCard() {
         </span>
         <div className="min-w-0 flex-1">
           <div className="flex flex-wrap items-center gap-2">
-            <h2 className="font-semibold text-ink">Kafka UI</h2>
+            <h2 className="font-semibold text-ink">{name}</h2>
             <span className={`chip ${configured ? "status-verified" : "text-muted"}`}>
               {configured ? "configured" : "not configured"}
             </span>
           </div>
-          <p className="mt-1 text-muted">
-            Opens catalogued Kafka topics in your Kafbat Kafka UI installation.
-          </p>
+          <p className="mt-1 text-muted">{summary}</p>
         </div>
       </div>
 
       <label className="mt-4 block">
-        <span className="label mb-1.5 block">Kafka UI cluster URL</span>
+        <span className="label mb-1.5 block">{label}</span>
         <input
           type="url"
           value={draft}
@@ -56,7 +78,7 @@ function KafkaUiCard() {
           onKeyDown={(event) => {
             if (event.key === "Enter" && dirty) save();
           }}
-          placeholder="https://kafka.example/ui/clusters/production"
+          placeholder={placeholder}
           spellCheck={false}
           autoComplete="off"
           aria-invalid={!valid}
@@ -64,9 +86,7 @@ function KafkaUiCard() {
         />
       </label>
       <p className={`mono mt-2 ${valid ? "text-muted" : "text-unresolved"}`}>
-        {valid
-          ? "Use a cluster or topics URL to open the exact topic. A plain installation URL opens Kafka UI itself."
-          : "Enter an http:// or https:// URL."}
+        {valid ? hint : "Enter an http:// or https:// URL."}
       </p>
 
       <div className="mt-4 flex flex-wrap items-center gap-2 border-t border-line pt-4">
@@ -87,7 +107,7 @@ function KafkaUiCard() {
               rel="noreferrer"
               className="tbtn px-3 py-1.5 text-ink"
             >
-              Open Kafka UI
+              Open {name}
               <ExternalLink size={14} aria-hidden />
             </a>
             <button
@@ -110,7 +130,33 @@ export function IntegrationsSettings() {
     <section>
       <SectionTitle right="stored in this browser">Integrations</SectionTitle>
       <div className="grid gap-grid lg:grid-cols-2">
-        <KafkaUiCard />
+        <IntegrationCard
+          name="Kafka UI"
+          brand="Kafka"
+          summary="Opens catalogued Kafka topics in your Kafbat Kafka UI installation."
+          label="Kafka UI cluster URL"
+          placeholder="https://kafka.example/ui/clusters/production"
+          hint="Use a cluster or topics URL to open the exact topic. A plain installation URL opens Kafka UI itself."
+          store={useKafkaUi}
+        />
+        <IntegrationCard
+          name="Confluence"
+          brand="Confluence"
+          summary="Searches your wiki for a service or context by name, from its page."
+          label="Confluence site or space URL"
+          placeholder="https://acme.atlassian.net/wiki/spaces/ARCH"
+          hint="A space URL searches that space only. A site URL searches the whole wiki. Cloud and Server are both understood."
+          store={useConfluence}
+        />
+        <IntegrationCard
+          name="Notion"
+          brand="Notion"
+          summary="Opens the Notion workspace where the documentation lives, from a service or context page."
+          label="Notion workspace or teamspace URL"
+          placeholder="https://www.notion.so/acme"
+          hint="Notion has no search address, so every page opens this URL as it is."
+          store={useNotion}
+        />
       </div>
     </section>
   );

package/src/pages/settings/RecordingSettings.tsx

@@ -0,0 +1,138 @@
+// Recordings, for the whole estate: what the catalog was verified against,
+// and a place to add one without first finding the flow it shows.
+//
+// A recording added here goes to the project the reader names. The trial
+// then says which flows it showed - which is how a reader with an export
+// from the collector and no idea which flow it is finds out.
+
+import { useMemo, useRef, useState } from "react";
+import { Disc3, Upload } from "lucide-react";
+import { Link } from "react-router";
+import { catalog } from "../../data";
+import { useToastStore } from "../../app/toast";
+import { TraceTrialPanel } from "../../flow/TraceTrial";
+import { forgetTraceTrial, recallTraceTrial, rememberTraceTrial, sessionStore } from "../../flow/trace-trial-resume";
+import { plural } from "../../lib/format";
+import { startTraceTrial } from "../../lib/local-api";
+import type { SetupProject } from "../../lib/setup-info";
+import { paths } from "../../routes";
+
+const FIELD = "w-full rounded-control border border-line bg-canvas px-2.5 py-1.5 text-ink";
+const SCOPE = "settings";
+
+/** Every recording the catalog names, with the flows it is an example of. */
+function recordingsInCatalog() {
+  const byFile = new Map<string, { traces: Set<string>; flows: Map<string, string> }>();
+  for (const flow of catalog.flows) {
+    for (const example of flow.examples ?? []) {
+      const entry = byFile.get(example.recording) ?? { traces: new Set(), flows: new Map() };
+      entry.traces.add(example.traceId);
+      entry.flows.set(flow.slug, flow.name);
+      byFile.set(example.recording, entry);
+    }
+  }
+  return [...byFile.entries()]
+    .map(([recording, entry]) => ({ recording, traces: entry.traces.size, flows: [...entry.flows.entries()] }))
+    .sort((a, b) => a.recording.localeCompare(b.recording));
+}
+
+export function RecordingSettings({ local, projects }: { local: boolean; projects: readonly SetupProject[] }) {
+  const say = useToastStore((s) => s.say);
+  const input = useRef<HTMLInputElement | null>(null);
+  const [projectId, setProjectId] = useState(projects[0]?.id ?? "");
+  // Picked back up from before a reload: keeping a recording reloads the
+  // page twice, and the panel outlives it.
+  const [resumed] = useState(() => recallTraceTrial(sessionStore(), SCOPE));
+  const [runId, setRunId] = useState<string | null>(resumed?.runId ?? null);
+  const [busy, setBusy] = useState(false);
+  const known = useMemo(recordingsInCatalog, []);
+
+  async function upload(file: File) {
+    if (!projectId) return;
+    setBusy(true);
+    try {
+      const started = await startTraceTrial(file, projectId);
+      rememberTraceTrial(sessionStore(), SCOPE, { runId: started.runId, writeRunId: null });
+      setRunId(started.runId);
+    } catch (cause) {
+      say(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setBusy(false);
+      if (input.current) input.current.value = "";
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-5">
+      <div className="rounded-card border border-line p-card shadow-xs">
+        <div className="flex items-center gap-2 font-semibold text-ink">
+          <Disc3 size={16} className="text-accent" /> Add a recording
+        </div>
+        <p className="mt-1 max-w-prose text-muted">
+          An OTLP JSON export - one batch per file or one per line, as a collector's file exporter writes it. The generator runs over a copy of the workspace with it in place and shows which flows it verified, what it added to them and which names it could not place, before the recording is kept beside the project.
+        </p>
+        {local ? (
+          <div className="mt-3 flex flex-wrap items-end gap-3">
+            <label className="min-w-56">
+              <span className="label mb-1.5 block">project</span>
+              <select className={FIELD} value={projectId} onChange={(e) => setProjectId(e.target.value)}>
+                {projects.length ? null : <option value="">no projects in portolan.json</option>}
+                {projects.map((p) => <option key={p.id} value={p.id}>{p.name} · {p.root}</option>)}
+              </select>
+            </label>
+            <button type="button" className="product-primary" disabled={busy || !projectId || runId !== null} onClick={() => input.current?.click()}>
+              <Upload size={14} /> Choose a file
+            </button>
+            <input
+              ref={input}
+              type="file"
+              accept=".jsonl,.json,.ndjson,application/json"
+              className="hidden"
+              onChange={(e) => { const file = e.target.files?.[0]; if (file) void upload(file); }}
+            />
+          </div>
+        ) : (
+          <div className="empty mt-3">
+            Start <code>portolan dev</code> to add recordings in this repository.
+          </div>
+        )}
+        {runId ? (
+          <div className="mt-4 border-t border-line pt-4">
+            <TraceTrialPanel
+              key={runId}
+              runId={runId}
+              initialWriteRunId={resumed?.runId === runId ? resumed.writeRunId : null}
+              onWriteStarted={(writeRunId) => rememberTraceTrial(sessionStore(), SCOPE, { runId, writeRunId })}
+              onDone={() => { forgetTraceTrial(sessionStore()); setRunId(null); }}
+            />
+          </div>
+        ) : null}
+      </div>
+
+      <section>
+        <div className="label mb-2">recordings the catalog was verified against · {known.length}</div>
+        {known.length ? (
+          <div className="divide-y divide-line rounded-control border border-line">
+            {known.map((entry) => (
+              <div key={entry.recording} className="grid gap-1 px-3 py-2 sm:grid-cols-[1fr_auto]">
+                <div className="min-w-0">
+                  <div className="mono truncate text-ink" title={entry.recording}>{entry.recording}</div>
+                  <div className="mt-0.5 flex flex-wrap gap-x-2 text-muted">
+                    {entry.flows.map(([slug, name]) => (
+                      <Link key={slug} to={paths.flow(slug)} className="hover:underline">{name}</Link>
+                    ))}
+                  </div>
+                </div>
+                <span className="mono text-muted sm:text-right">{entry.traces} {plural(entry.traces, "trace")} kept as {plural(entry.traces, "an example", "examples")}</span>
+              </div>
+            ))}
+          </div>
+        ) : (
+          <div className="rounded-control border border-line bg-surface px-3 py-3 text-muted">
+            No flow in this catalog carries a recording yet. A verify step with the otel plugin reads them; adding one above writes that step for you.
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}