@12-apps/mcp 1.0.0 → 1.3.0

package/src/openapi/generate.ts

@@ -3,6 +3,7 @@ import type {
   GenerateOptions,
   JsonSchema,
   ParameterLocation,
+  ToolAnnotations,
   ToolParameter,
 } from "../types";
 
@@ -18,6 +19,10 @@ export interface OpenApiOperation {
   summary?: string;
   description?: string;
   tags?: string[];
+  /** Paladira's required projection of MCP tool annotations into OpenAPI. */
+  "x-mcp-tool-annotations"?: ToolAnnotations;
+  /** Dotted response paths stripped from the result before the agent sees it. */
+  "x-mcp-redact-response"?: readonly string[];
   parameters?: OpenApiParameter[];
   requestBody?: OpenApiRequestBody;
   responses?: Record<string, OpenApiResponse>;
@@ -45,7 +50,15 @@ export interface OpenApiDocument {
   security?: Array<Record<string, string[]>>;
 }
 
-const HTTP_METHODS = ["get", "put", "post", "delete", "patch", "options", "head"] as const;
+const HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "patch",
+  "options",
+  "head",
+] as const;
 const MUTATING = new Set(["post", "put", "patch", "delete"]);
 const PARAM_LOCATIONS = new Set<ParameterLocation>(["path", "query", "header"]);
 
@@ -63,7 +76,9 @@ function slugify(method: string, path: string): string {
 
 function securityNames(op: OpenApiOperation, doc: OpenApiDocument): string[] {
   const requirements = op.security ?? doc.security ?? [];
-  return [...new Set(requirements.flatMap((requirement) => Object.keys(requirement)))];
+  return [
+    ...new Set(requirements.flatMap((requirement) => Object.keys(requirement))),
+  ];
 }
 
 function bodySchema(op: OpenApiOperation): JsonSchema | undefined {
@@ -72,12 +87,37 @@ function bodySchema(op: OpenApiOperation): JsonSchema | undefined {
 
 function responseSchema(op: OpenApiOperation): JsonSchema | undefined {
   const responses = op.responses ?? {};
-  const code = ["200", "201", "2XX", "default"].find((c) => responses[c]?.content?.[JSON_CONTENT]?.schema);
+  const code = ["200", "201", "2XX", "default"].find(
+    (c) => responses[c]?.content?.[JSON_CONTENT]?.schema,
+  );
   return code ? responses[code]?.content?.[JSON_CONTENT]?.schema : undefined;
 }
 
+function annotations(op: OpenApiOperation, name: string): ToolAnnotations {
+  const value = op["x-mcp-tool-annotations"];
+  if (
+    !value ||
+    typeof value.readOnlyHint !== "boolean" ||
+    typeof value.openWorldHint !== "boolean" ||
+    typeof value.destructiveHint !== "boolean"
+  ) {
+    throw new Error(
+      `OpenAPI operation "${name}" must explicitly set readOnlyHint, openWorldHint, and destructiveHint`,
+    );
+  }
+  if (typeof value.title !== "string" || !value.title.trim()) {
+    throw new Error(
+      `OpenAPI operation "${name}" must set a human-readable annotations.title`,
+    );
+  }
+  return value;
+}
+
 /** Path params are always required regardless of how the spec marks them. */
-function paramRequired(location: ParameterLocation, raw: OpenApiParameter): boolean {
+function paramRequired(
+  location: ParameterLocation,
+  raw: OpenApiParameter,
+): boolean {
   return location === "path" ? true : Boolean(raw.required);
 }
 
@@ -111,11 +151,19 @@ interface BodyContribution {
  */
 function bodyContribution(op: OpenApiOperation): BodyContribution {
   const body = bodySchema(op);
-  if (!body) return { properties: {}, bodyProps: [], requiredProps: [], bodyIsWhole: false };
+  if (!body)
+    return {
+      properties: {},
+      bodyProps: [],
+      requiredProps: [],
+      bodyIsWhole: false,
+    };
 
   const propSchemas = body.properties as Record<string, JsonSchema> | undefined;
   if (body.type === "object" && propSchemas) {
-    const bodyRequired = new Set(Array.isArray(body.required) ? (body.required as string[]) : []);
+    const bodyRequired = new Set(
+      Array.isArray(body.required) ? (body.required as string[]) : [],
+    );
     const bodyProps = Object.keys(propSchemas);
     return {
       properties: propSchemas,
@@ -162,7 +210,12 @@ function buildInput(op: OpenApiOperation): BuiltInput {
     properties,
     ...(allRequired.length ? { required: allRequired } : {}),
   };
-  return { inputSchema, parameters, bodyProps: body.bodyProps, bodyIsWhole: body.bodyIsWhole };
+  return {
+    inputSchema,
+    parameters,
+    bodyProps: body.bodyProps,
+    bodyIsWhole: body.bodyIsWhole,
+  };
 }
 
 /** The declared operations of a path item, as (method, operation) pairs. */
@@ -189,11 +242,16 @@ function buildTool(
   const { inputSchema, parameters, bodyProps, bodyIsWhole } = buildInput(op);
   return {
     name,
-    description: op.summary ?? op.description ?? `${method.toUpperCase()} ${path}`,
+    description:
+      op.summary ?? op.description ?? `${method.toUpperCase()} ${path}`,
     method: method.toUpperCase(),
     path,
     inputSchema,
     outputSchema: responseSchema(op),
+    annotations: annotations(op, name),
+    ...(op["x-mcp-redact-response"]?.length
+      ? { redactResponse: op["x-mcp-redact-response"] }
+      : {}),
     parameters,
     bodyProps,
     bodyIsWhole,

package/src/react/ai-capabilities.tsx

@@ -0,0 +1,99 @@
+import { Box } from "@12-apps/ui/mui/Box";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import { AI_CAPABILITIES, type AiCapability } from "../guide";
+import { CapabilityIcon } from "./ai-icons";
+
+/** One marketing card: an icon, a headline and an example prompt (as a bubble). */
+function CapabilityCard({ capability }: { capability: AiCapability }): React.JSX.Element {
+  return (
+    <Box
+      data-testid={`ai-capability-${capability.id}`}
+      sx={{
+        p: 2.5,
+        borderRadius: 3,
+        border: 1,
+        borderColor: "divider",
+        bgcolor: "background.paper",
+        height: "100%",
+        // Static transition string: safe to cross the server→client boundary.
+        transition: "border-color 200ms, box-shadow 200ms, transform 200ms",
+        "&:hover": { borderColor: "primary.main", boxShadow: 3, transform: "translateY(-3px)" },
+      }}
+    >
+      <Box
+        sx={{
+          width: 44,
+          height: 44,
+          borderRadius: 2,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          bgcolor: "primary.main",
+          color: "primary.contrastText",
+          mb: 1.5,
+        }}
+      >
+        <CapabilityIcon id={capability.id} fontSize={26} />
+      </Box>
+      <Text variant="body" weight="bold" as="h3">
+        {capability.title}
+      </Text>
+      <Box
+        data-testid={`ai-capability-prompt-${capability.id}`}
+        sx={{
+          mt: 1,
+          px: 1.5,
+          py: 1,
+          borderRadius: 2,
+          borderBottomLeftRadius: 4,
+          bgcolor: "action.hover",
+          border: 1,
+          borderColor: "divider",
+        }}
+      >
+        <Text variant="body" size="sm" as="p" color="secondary">
+          {capability.detail}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * Marketing block for the AI integration: a headline + a responsive grid of
+ * capability cards. Shown on the onboarding landing (before the owner starts) to
+ * sell the feature — "here's what the assistant does for you". `capabilities`
+ * defaults to the shared set; apps can pass their own.
+ */
+export function AiCapabilities({
+  capabilities = AI_CAPABILITIES,
+}: {
+  capabilities?: readonly AiCapability[];
+}): React.JSX.Element {
+  return (
+    <Box data-testid="ai-capability-examples" sx={{ width: "100%" }}>
+      <Box sx={{ mb: 3 }}>
+        <Text variant="heading" size="sm" as="h2">
+          O que o assistente faz por você
+        </Text>
+        <Box sx={{ mt: 0.5 }}>
+          <Text variant="body" size="sm" as="p" color="secondary">
+            Sem planilhas, sem cliques — é só perguntar na conversa.
+          </Text>
+        </Box>
+      </Box>
+      <Box
+        sx={{
+          display: "grid",
+          gap: 3,
+          gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr", md: "repeat(4, 1fr)" },
+        }}
+      >
+        {capabilities.map((capability) => (
+          <CapabilityCard key={capability.id} capability={capability} />
+        ))}
+      </Box>
+    </Box>
+  );
+}

package/src/react/ai-connection-utils.ts

@@ -0,0 +1,96 @@
+import { providerForHostId, type AiHostGuide, type AiProvider } from "../guide";
+
+/**
+ * Pure helpers + the connection type shared by the AI-onboarding flow steps
+ * (`ai-flow-steps.tsx`) and the orchestration/status board (`ai-steps.tsx`),
+ * kept here so neither JSX module has to import the other (no import cycle).
+ */
+
+/** The live connection surfaced from the server (empty list when none). */
+export interface AiConnection {
+  clientName: string | null;
+  /**
+   * The provider this connection is attributed to (derived server-side from the
+   * OAuth client's redirect URIs / confirmed by `announceAiConnection`). `null`
+   * for a legacy connection recorded before attribution existed — matched
+   * best-effort to whichever host the owner is connecting.
+   */
+  host: AiProvider | null;
+  lastActiveAt: Date;
+}
+
+/** Friendly provider names for the connected-state title ("Claude Conectado"). */
+const PROVIDER_LABEL: Record<AiProvider, string> = {
+  claude: "Claude",
+  chatgpt: "ChatGPT",
+  codex: "Codex",
+};
+
+/** Resolve a persisted host id to its guide (falls back to the first host). */
+export function resolveHost(hosts: readonly AiHostGuide[], hostId: unknown): AiHostGuide {
+  const found = hosts.find((h) => h.id === hostId) ?? hosts[0];
+  if (!found) throw new Error("resolveHost: hosts array must not be empty");
+  return found;
+}
+
+/** Friendly label for a persisted host id (falls back to a generic word). */
+export function hostLabel(hosts: readonly AiHostGuide[], hostId: unknown): string {
+  return hosts.find((h) => h.id === hostId)?.label ?? "seu assistente";
+}
+
+/**
+ * The live connection for a given host, or null. A connection is matched by its
+ * derived provider; a legacy `null`-host connection matches best-effort (so the
+ * pre-attribution single-connection behavior still works).
+ */
+export function connectionForHost(
+  connections: readonly AiConnection[],
+  hostId: unknown,
+): AiConnection | null {
+  const provider = typeof hostId === "string" ? providerForHostId(hostId) : null;
+  if (!provider) return connections.find((c) => c.host === null) ?? connections[0] ?? null;
+  return (
+    connections.find((c) => c.host === provider) ?? connections.find((c) => c.host === null) ?? null
+  );
+}
+
+/** Short pt-BR "ativo há X" from a timestamp (agora / min / h / dias). */
+export function activeAgo(date: Date): string {
+  const minutes = Math.max(0, Math.floor((Date.now() - date.getTime()) / 60_000));
+  if (minutes < 1) return "ativo agora";
+  if (minutes < 60) return `ativo há ${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `ativo há ${hours} h`;
+  return `ativo há ${Math.floor(hours / 24)} dias`;
+}
+
+/** The most-recently-active connection across all providers (null when none). */
+function mostRecent(connections: readonly AiConnection[]): AiConnection | null {
+  return connections.reduce<AiConnection | null>(
+    (best, c) => (!best || c.lastActiveAt.getTime() > best.lastActiveAt.getTime() ? c : best),
+    null,
+  );
+}
+
+/** The configured-state TITLE, naming the connected assistant(s) — FUT req (F). */
+export function connectedTitle(
+  connections: readonly AiConnection[],
+  hosts: readonly AiHostGuide[],
+  connectedHostId: string | undefined,
+): string {
+  const providers = [...new Set(connections.map((c) => c.host).filter((h): h is AiProvider => h !== null))];
+  if (providers.length === 1) return `${PROVIDER_LABEL[providers[0]!]} Conectado`;
+  if (providers.length > 1) {
+    return `${providers.map((p) => PROVIDER_LABEL[p]).join(", ")} conectados`;
+  }
+  // Legacy connection with no attributed provider — name the completed host.
+  if (connections.length > 0) return `${hostLabel(hosts, connectedHostId)} Conectado`;
+  return "IA conectada";
+}
+
+/** The completed summary line (second line) for the configured-state header. */
+export function connectedSummary(connections: readonly AiConnection[]): string {
+  const recent = mostRecent(connections);
+  if (!recent) return "Integração configurada";
+  return activeAgo(recent.lastActiveAt);
+}

package/src/react/ai-flow-steps.tsx

@@ -0,0 +1,290 @@
+"use client";
+
+import CheckCircleIcon from "@mui/icons-material/CheckCircle";
+import OpenInNewIcon from "@mui/icons-material/OpenInNew";
+import { useEffect, useState } from "react";
+
+import { type GuidedNav } from "@12-apps/onboarding";
+import { Progress } from "@12-apps/ui/data-display/Progress";
+import { Button } from "@12-apps/ui/form/Button";
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import type { AiHostConfigureStage, AiHostGuide } from "../guide";
+import { activeAgo, connectionForHost, hostLabel, type AiConnection } from "./ai-connection-utils";
+import {
+  EndpointCopyBlock,
+  HostConnectHeader,
+  HostDocsLink,
+  HostOpenButton,
+  HostStepList,
+  PromptCopyBlock,
+} from "./host-connect-guide";
+
+/** The host's connect steps split across the Configurar / Conectar stages. */
+const CONFIGURE_STEP_COUNT = 3;
+
+/** How often the Confirmar step re-checks the live connection while waiting. */
+const POLL_INTERVAL_MS = 3000;
+
+/** A step's continue/back controls (Voltar left, primary next right). */
+function StepNav({
+  nav,
+  onNext,
+  nextLabel = "Próximo",
+  nextDisabled = false,
+  nextTestId,
+}: {
+  nav: GuidedNav;
+  onNext: () => void;
+  nextLabel?: string;
+  nextDisabled?: boolean;
+  nextTestId?: string;
+}): React.JSX.Element {
+  return (
+    <Stack direction="row" spacing={1} alignItems="center" justifyContent="space-between">
+      <Button variant="ghost" onClick={() => nav.back()} data-testid="ai-step-back">
+        Voltar
+      </Button>
+      <Button onClick={onNext} disabled={nextDisabled} data-testid={nextTestId}>
+        {nextLabel}
+      </Button>
+    </Stack>
+  );
+}
+
+/** Step 2 — copy the store URL; copying is the action that advances the wizard. */
+export function CopyUrlStep({ nav, endpointUrl }: { nav: GuidedNav; endpointUrl: string }): React.JSX.Element {
+  return (
+    <Stack spacing={3} data-testid="ai-copy-step">
+      <Box>
+        <Text variant="heading" size="sm" as="h2">
+          Copie a URL da sua loja
+        </Text>
+        <Text variant="caption" as="p" color="secondary">
+          É o único dado que você cola no assistente — ao copiar, seguimos para o próximo passo.
+        </Text>
+      </Box>
+      <EndpointCopyBlock endpointUrl={endpointUrl} copied={false} onCopy={() => nav.next()} />
+      <Box>
+        <Button variant="ghost" onClick={() => nav.back()} data-testid="ai-step-back">
+          Voltar
+        </Button>
+      </Box>
+    </Stack>
+  );
+}
+
+/** Step 3 — open the host's connectors and add + configure the custom connector. */
+export function ConfigureStep({ nav, host }: { nav: GuidedNav; host: AiHostGuide }): React.JSX.Element {
+  // Hosts with no direct link (e.g. Claude Desktop) have nothing to open, so
+  // "Próximo" is available immediately; otherwise it unlocks on the open click.
+  const [opened, setOpened] = useState(!host.link);
+  return (
+    <Stack spacing={2.5} data-testid="ai-configure-step">
+      <HostConnectHeader host={host} />
+      <HostOpenButton host={host} onOpen={() => setOpened(true)} />
+      <HostStepList steps={host.steps.slice(0, CONFIGURE_STEP_COUNT)} start={1} />
+      <HostDocsLink host={host} />
+      <StepNav nav={nav} onNext={() => nav.next()} nextDisabled={!opened} nextTestId="ai-configure-next" />
+    </Stack>
+  );
+}
+
+/**
+ * One stage of a host's per-stage configuration (e.g. ChatGPT's "enable
+ * developer mode" then "configurar"). Each stage has its OWN deep link — opening
+ * it unlocks "Próximo" — and its own instructions.
+ */
+export function ConfigureStageStep({
+  nav,
+  host,
+  stage,
+}: {
+  nav: GuidedNav;
+  host: AiHostGuide;
+  stage: AiHostConfigureStage;
+}): React.JSX.Element {
+  const [opened, setOpened] = useState(!stage.link);
+  return (
+    <Stack spacing={2.5} data-testid={`ai-stage-${stage.id}`}>
+      <HostConnectHeader host={host} />
+      {stage.link && (
+        <Box>
+          <Button
+            onClick={() => {
+              window.open(stage.link!.url, "_blank", "noopener,noreferrer");
+              setOpened(true);
+            }}
+            data-testid={`ai-stage-link-${stage.id}`}
+          >
+            {stage.link.label}
+            <OpenInNewIcon sx={{ fontSize: 16, ml: 0.5 }} />
+          </Button>
+        </Box>
+      )}
+      <HostStepList steps={stage.steps} start={1} />
+      <HostDocsLink host={host} />
+      <StepNav
+        nav={nav}
+        onNext={() => nav.next()}
+        nextDisabled={!opened}
+        nextTestId={`ai-stage-next-${stage.id}`}
+      />
+    </Stack>
+  );
+}
+
+/** Step 4 — connect: log in, authorize and activate the connector. */
+export function ConnectStep({
+  nav,
+  host,
+  connectPrompt,
+}: {
+  nav: GuidedNav;
+  host: AiHostGuide;
+  connectPrompt: string;
+}): React.JSX.Element {
+  return (
+    <Stack spacing={2.5} data-testid="ai-connect-step">
+      <HostConnectHeader host={host} />
+      <HostStepList steps={host.steps.slice(CONFIGURE_STEP_COUNT)} start={CONFIGURE_STEP_COUNT + 1} />
+      <PromptCopyBlock
+        title="Cole esta mensagem no assistente"
+        caption="Assim ele se conecta, se identifica (Claude, ChatGPT…) e registramos a conexão."
+        message={connectPrompt}
+      />
+      <HostDocsLink host={host} />
+      <StepNav nav={nav} onNext={() => nav.next()} nextLabel="Continuar" nextTestId="ai-connect-done" />
+    </Stack>
+  );
+}
+
+/**
+ * Simplified-flow step (host has a published `pluginUrl`): open the one-click
+ * plugin (install + authorize), then paste the prompt asking the assistant to
+ * connect. No URL to copy, no manual connector. The next step (Confirmar) waits.
+ */
+export function InstallStep({
+  nav,
+  host,
+  connectPrompt,
+}: {
+  nav: GuidedNav;
+  host: AiHostGuide;
+  connectPrompt: string;
+}): React.JSX.Element {
+  const [opened, setOpened] = useState(false);
+  return (
+    <Stack spacing={2.5} data-testid="ai-install-step">
+      <HostConnectHeader host={host} />
+      <Text variant="body" as="p" color="secondary">
+        Abra o plugin da sua loja, clique em Instalar e autorize o acesso — sem copiar URL nem gerar
+        credenciais.
+      </Text>
+      {host.pluginUrl && (
+        <Box>
+          <Button
+            onClick={() => {
+              window.open(host.pluginUrl!, "_blank", "noopener,noreferrer");
+              setOpened(true);
+            }}
+            data-testid="ai-install-open"
+          >
+            Instalar o plugin da loja
+            <OpenInNewIcon sx={{ fontSize: 16, ml: 0.5 }} />
+          </Button>
+        </Box>
+      )}
+      <PromptCopyBlock
+        title="Peça ao assistente para conectar"
+        caption="Cole no assistente para ele se conectar, se identificar e confirmar o acesso."
+        message={connectPrompt}
+      />
+      <HostDocsLink host={host} />
+      <StepNav
+        nav={nav}
+        onNext={() => nav.next()}
+        nextLabel="Continuar"
+        nextDisabled={!opened}
+        nextTestId="ai-install-done"
+      />
+    </Stack>
+  );
+}
+
+/**
+ * Step 5: auto-detect the live connection. While waiting it polls the server
+ * (the sign-in / `announceAiConnection` tool call registers the connection
+ * server-side), showing a spinner — the owner never clicks "verify". Completes
+ * when the selected host's connection appears.
+ */
+export function ConfirmStep({
+  nav,
+  connections,
+  hosts,
+  onRetest,
+}: {
+  nav: GuidedNav;
+  connections: readonly AiConnection[];
+  hosts: readonly AiHostGuide[];
+  onRetest: () => void;
+}): React.JSX.Element {
+  const selectedHostId = nav.data.selectedHost as string | undefined;
+  const connection = connectionForHost(connections, selectedHostId);
+  const label = connection?.clientName ?? hostLabel(hosts, selectedHostId);
+
+  // Auto-detect: re-check on an interval until the connection shows up. The
+  // interval is cleared as soon as `connection` is non-null (and on unmount).
+  useEffect(() => {
+    if (connection) return undefined;
+    const id = setInterval(() => onRetest(), POLL_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, [connection, onRetest]);
+
+  if (connection) {
+    return (
+      <Stack spacing={2} data-testid="ai-confirm-connected">
+        <Stack direction="row" spacing={1.5} alignItems="center">
+          <CheckCircleIcon sx={{ color: "success.main" }} />
+          <Box>
+            <Text variant="body" weight="bold" as="p">
+              {label} está conectado à sua loja.
+            </Text>
+            <Text variant="caption" as="p" color="secondary">
+              {activeAgo(connection.lastActiveAt)}
+            </Text>
+          </Box>
+        </Stack>
+        <Box>
+          <Button onClick={() => nav.complete({ connectedHost: selectedHostId })}>Concluir</Button>
+        </Box>
+      </Stack>
+    );
+  }
+
+  return (
+    <Stack spacing={2.5} data-testid="ai-confirm-waiting">
+      <Stack direction="row" spacing={1.5} alignItems="center">
+        <Progress variant="circular" circularSize={22} thickness={4} dataTestId="ai-confirm-spinner" />
+        <Box>
+          <Text variant="body" weight="bold" as="p">
+            Esperando conexão
+          </Text>
+          <Text variant="caption" as="p" color="secondary">
+            Assim que você autorizar o acesso no {label}, ela aparece aqui automaticamente.
+          </Text>
+        </Box>
+      </Stack>
+      <Stack direction="row" spacing={1}>
+        <Button variant="ghost" size="sm" onClick={onRetest} data-testid="ai-confirm-retest">
+          Testar agora
+        </Button>
+        <Button variant="ghost" size="sm" onClick={() => nav.back()}>
+          Voltar
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}

package/src/react/ai-icons.tsx

@@ -0,0 +1,70 @@
+import AutoAwesomeIcon from "@mui/icons-material/AutoAwesome";
+import CategoryIcon from "@mui/icons-material/Category";
+import HubIcon from "@mui/icons-material/Hub";
+import Inventory2Icon from "@mui/icons-material/Inventory2";
+import QueryStatsIcon from "@mui/icons-material/QueryStats";
+import ReceiptLongIcon from "@mui/icons-material/ReceiptLong";
+
+import { Box } from "@12-apps/ui/mui/Box";
+
+import type { AiHostBrand } from "../guide";
+
+/**
+ * Brand accents for the host avatars. These are deliberately hardcoded (not
+ * theme tokens): they are BRAND marks whose recognizability depends on the
+ * vendor's own accent colour, so the "always semantic colours" rule doesn't
+ * apply here. The glyphs are simple, original stand-ins — not the vendors'
+ * proprietary logo artwork.
+ */
+const BRAND: Record<AiHostBrand, { bg: string; Icon: typeof AutoAwesomeIcon; label: string }> = {
+  claude: { bg: "#D97757", Icon: AutoAwesomeIcon, label: "Claude (Anthropic)" },
+  openai: { bg: "#10A37F", Icon: HubIcon, label: "OpenAI" },
+};
+
+/** A round brand chip: the vendor accent + a simple glyph. */
+export function HostBrandAvatar({
+  brand,
+  size = 40,
+}: {
+  brand: AiHostBrand;
+  size?: number;
+}): React.JSX.Element {
+  const { bg, Icon, label } = BRAND[brand];
+  return (
+    <Box
+      aria-label={label}
+      sx={{
+        width: size,
+        height: size,
+        borderRadius: "50%",
+        bgcolor: bg,
+        color: "#fff",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        flexShrink: 0,
+      }}
+    >
+      <Icon sx={{ fontSize: size * 0.55 }} />
+    </Box>
+  );
+}
+
+const CAPABILITY_ICON: Record<string, typeof AutoAwesomeIcon> = {
+  orders: ReceiptLongIcon,
+  inventory: Inventory2Icon,
+  catalog: CategoryIcon,
+  sales: QueryStatsIcon,
+};
+
+/** The icon for a capability card, by capability id (falls back to a sparkle). */
+export function CapabilityIcon({
+  id,
+  fontSize = 24,
+}: {
+  id: string;
+  fontSize?: number;
+}): React.JSX.Element {
+  const Icon = CAPABILITY_ICON[id] ?? AutoAwesomeIcon;
+  return <Icon sx={{ fontSize }} />;
+}