@checkstack/ai-frontend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# @checkstack/ai-frontend
+
+## 0.1.0
+
+### Minor Changes
+
+- 9dcc848: AI chat UX: ordered turns, readable diffs, persistent errors, auto-titles, decision acknowledgments, and a smarter topical guard.
+
+  - Turns render as ordered parts (text / tool-call status / confirm card) in chronological order, with inline tool-error lines and a mid-turn "Thinking..." indicator, instead of one text blob plus a flat tool list. The confirm card and tool-step parts no longer vanish after a turn finishes (hydration seeds once per conversation id via `useInitOnceForKey`, so background refetches are no-ops).
+  - Errors persist: in-stream provider errors are lifted into the chat hook's durable error state and shown in a dismissible banner with selectable text and a Copy button (single-line digest, full text on hover); it clears on send / open / new chat. The backend installs an `onError` handler that logs the provider's full HTTP response and returns a readable message, and normalizes the model message history (drop empty rows, merge consecutive same-role rows, strip a leading non-user row) so a single provider hiccup can no longer brick a conversation.
+  - Confirm/applied card diffs render as a GitHub-style split diff (line-number gutters, per-line tint, word-level highlighting, an "Expand" pop-out). `computeFieldDiff` recurses into arrays element-wise so a single changed leaf is pinpointed instead of dumping whole serialized arrays.
+  - Conversations auto-title after the first user message (cheap `generateText` reusing the turn's model, fire-and-forget, heuristic fallback). "New chat" opens immediately and reuses an empty untitled draft instead of spawning duplicates; "Delete" is a soft archive (`archived_at` on `ai_conversations`, data retained). A clean model picker always renders a `Select` of `[defaultModel, ...availableModels]` de-duplicated.
+  - The assistant acknowledges a confirm-card decision (a new `decision` mode -> `streamDecision`) instead of going silent after an apply/decline; the decision note is derived server-side from the stored proposal and is ephemeral.
+  - A cheap topical pre-classifier short-circuits off-topic turns with a canned refusal (fail-open, spend recorded). It marks meta/capability/greeting/how-to questions as ON_TOPIC; only clearly unrelated requests (coding help, creative writing, trivia) are refused.
+  - The chat agent no longer emits duplicate proposals for one request: propose/auto-apply results carry an explicit model-facing "stop and wait" note, and a per-turn `<tool>:<argsHash>` dedupe short-circuits repeated identical mutating calls.
+  - Assistant messages render through the shared `<MarkdownBlock>`: it now parses a SAFE subset of raw HTML (`rehype-raw` + `rehype-sanitize`) so native `<details>`/`<summary>` widgets render, and enables `remark-gfm` so GFM tables, strikethrough, and autolinks render (the assistant often summarizes drafts as tables).
+
+  State and scale: the archive marker, titles, and permission mode all live in the shared `ai_conversations` table, read identically on every pod; the classifier holds no state and its spend is recorded in the shared `ai_spend` ledger. No new pod-local state.
+
+  This is a beta minor.
+
+- 9dcc848: Add the AI platform: a transport-agnostic tool spine, an OAuth Authorization Server + read-only MCP server, a propose/apply flow with audit log, a streaming in-app chat agent, per-conversation permission modes, per-integration spend caps, and user-scoped tool authorization.
+
+  Two new packages, `@checkstack/ai-common` (the `AiTool` contract, `read`/`mutate`/`destructive` effect classification, the `ai.*` access rules, the OpenAI-compatible connection shape, and the wire contracts) and `@checkstack/ai-backend` (the tool registry, extension points, principal-to-tool resolver, shared zod-to-JSON-Schema serializer, and all transports). The OpenAI-compatible integration provider registers through the existing integration provider extension point, so its API key is stored in the Secrets Vault and configured in the generic Connections UI.
+
+  What ships:
+
+  - Tool spine and extension points: `aiToolExtensionPoint.registerTool` (hand-authored composite tools) and `aiToolProjectionExtensionPoint.expose` (opt-in projections of existing oRPC procedures). Authorization mirrors `autoAuthMiddleware` exactly - a tool is surfaced only when every `requiredAccessRules` entry is satisfied, so a scope-narrowed principal can only ever see fewer tools.
+  - OAuth + MCP: Checkstack can act as its own OAuth 2.1 Authorization Server (authorization code + PKCE, consent screen, Dynamic Client Registration) and expose a read-only MCP server over Streamable HTTP at `/api/ai/mcp`. Off by default, enabled by the admin `ai.mcp-oauth` setting. A Bearer OAuth-token branch is added to the auth strategy; token scopes are intersected live with the bound user's access rules on every call. A shared-Postgres rate limiter throttles the DCR endpoint per client IP. `getMcpOAuthSettings` / `setMcpOAuthSettings` contracts added to `@checkstack/auth-common`. A minimal OAuth consent page (`/auth/oauth-consent`) renders the requesting client and scopes.
+  - Propose/apply + audit: a transport-agnostic two-step service - `propose` re-checks authz, runs the tool's `dryRun` without mutating, and returns a single-use proposal token (the `proposed` audit row IS the token store, 10-minute TTL, atomic single-use); `apply` re-parses the server-stored payload, re-checks authz, and atomically commits. The `ai_tool_calls` audit table records every call across both transports with a SHA-256 args hash (never raw arguments) and stamps who proposed and who applied. An `ai.toolCalled` event carries metadata only.
+  - In-app chat: a server-side, provider-agnostic Vercel AI SDK agent loop (OpenAI, Azure, OpenRouter, Ollama, vLLM, LM Studio, ...). The model provider is built on the backend from the integration credentials, so the API key never leaves the backend. The loop offers only resolver-allowed tools, auto-runs read tools (re-entering the live router as the logged-in user) and routes mutating / destructive tools through propose/apply. Durable conversation persistence (`ai_conversations`, `ai_messages`, owner-scoped RPCs) plus a streaming chat UI with a confirm-card component and per-integration model picker.
+  - Per-conversation permission mode (Claude-Code-style approve/auto), a durable `permission_mode` column on `ai_conversations` (default `approve`). `read` always auto-runs in both modes; `mutate` inherits the mode (auto-applies server-side in `auto`, confirm-carded in `approve`); `destructive` ALWAYS requires the human `applyTool` in both modes. Security invariant (structural + tested): the mode is consulted only on the `mutate` branch, so no `(effect, mode)` pair routes a destructive tool to auto-apply.
+  - Per-integration LLM spend cap (optional `spendCap` = `tokenBudget` + `windowMinutes`, default OFF). Spend is tracked in a shared-Postgres `ai_spend` ledger; enforcement is a rolling-window SUM run before each turn (HTTP 429 over budget). Per-principal tool rate-limit budgets are a rolling COUNT over `ai_tool_calls`, enforced on both transports. An absent / empty / incomplete `spendCap` is treated as "no cap" rather than rejected.
+  - Full tool-call replay: `ai_messages.model_messages` (jsonb) persists the canonical AI-SDK `ResponseMessage[]` per turn and replays them verbatim on the next turn; legacy rows fall back to text-only replay.
+  - Enforced no-secret-leak scrubbing: `appendMessage` runs `scrubContent` on every write, redacting credential-shaped keys and high-confidence credential values; a canary regression test asserts injected secrets are stripped. A hardening test suite asserts no secret appears in any AI-surface DTO and that handler-side authz holds when the model misbehaves.
+  - Provider correctness: the chat provider uses `@ai-sdk/openai-compatible`'s `chatModel` (plain `/chat/completions`), so OpenAI-compatible gateways (OpenRouter, DeepSeek, Ollama, vLLM) no longer reject turns with `invalid_prompt`; `@ai-sdk/openai` is removed.
+
+  BREAKING CHANGES:
+
+  - The `AiTool` contract (`@checkstack/ai-common`) gained a `TRpc` type parameter, and both `dryRun` and `execute` now receive a USER-SCOPED `rpcClient` arg bound to the originating user. Every plugin procedure a tool calls re-enters the live router AS THAT USER, so handler-side authorization (access rules AND per-resource/team scope) is enforced exactly as a direct UI/RPC call - closing a prior privilege-escalation where tools captured a trusted service client at construction. A hand-authored tool MUST resolve its plugin client from this per-call arg and MUST NOT capture a trusted service client at factory scope. Tool factories that previously took `{ rpcClient }` should drop that parameter.
+  - `AiToolProjectionExtensionPoint.expose` no longer takes a second `pluginMetadata` argument; the owning metadata lives on `input.sourcePluginMetadata`. Callers must drop the second argument.
+
+  State and scale: conversations, messages, the audit log, proposal tokens, the rate-limit counter, and the spend ledger all live in shared Postgres, so every pod answers identically and the agent loop is resumable on any pod. The only pod-local state is the live MCP connection registry (bookkeeping, never a source of truth). Cross-pod conversation readback, the spend cap, and the tool budget are verified by env-gated two-pod integration tests.
+
+  This is a beta minor.
+
+### Patch Changes
+
+- 9dcc848: Move primary navigation into a left sidebar, and serve the user guide in-app.
+
+  Feature navigation (a ~20-item user-menu dropdown) now lives in a persistent left sidebar (a slide-over drawer on mobile), grouped by section with the active route highlighted; the user menu keeps only account actions. A route opts into the sidebar with new `nav` metadata (`{ group, icon, label?, order?, accessRule? }`) on its registration, co-located with path + access + title. The sidebar filters entries with the same access check as page guards. `@checkstack/common` gains `isAccessRuleSatisfied` and a centralized set of in-app doc slugs (`APP_DOC_SLUGS` + `docsPath`, with a test asserting each resolves to a real docs page); `@checkstack/auth-frontend` exports `useAccessRules`.
+
+  The backend now serves the Astro Starlight docs build same-origin at `/checkstack/*` (the same artifact deployed to GitHub Pages), so the user guide is available inside the app including for self-hosted / air-gapped installs (served verbatim, no rebuild, no link rewriting; from `CHECKSTACK_DOCS_DIST`, before the SPA catch-all, degrading gracefully when absent; the Docker image builds and ships `docs/dist`; Vite proxies `/checkstack` in dev). The "Docs" link is a shell-owned external sidebar entry under the Documentation group (book icon), opening `/checkstack/user-guide/` in a new tab; the group renders even when no plugin route contributes to it.
+
+  BREAKING (plugin authors): `UserMenuItemsSlot` is no longer the way to add navigation - registering a top user-menu item no longer surfaces it anywhere. Add `nav` to the page's route instead. `UserMenuItemsBottomSlot` (account items) is unchanged. All bundled plugins have been migrated.
+
+  This is a beta minor.
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/ai-common@0.1.0
+  - @checkstack/ui@1.13.0
+  - @checkstack/common@0.13.0
+  - @checkstack/frontend-api@0.7.0
+  - @checkstack/integration-common@0.7.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@checkstack/ai-frontend",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.tsx",
+  "checkstack": {
+    "type": "frontend"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/ai-common": "0.0.0",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/frontend-api": "0.6.0",
+    "@checkstack/integration-common": "0.6.0",
+    "@checkstack/ui": "1.12.0",
+    "lucide-react": "^1.17.0",
+    "react": "^18.3.1",
+    "react-router-dom": "^7.16.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^18.2.0",
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.4"
+  }
+}

package/src/components/AppliedCardView.tsx

@@ -0,0 +1,36 @@
+import { Card, CardHeader, CardTitle, CardContent, Badge } from "@checkstack/ui";
+import { CheckCircle2 } from "lucide-react";
+import type { AppliedCard } from "../lib/stream-parser";
+import { DiffView } from "./DiffView";
+
+/**
+ * Read-only card for a change the assistant AUTO-APPLIED (auto mode). The change
+ * already took effect, so there are no Apply/Decline buttons - this exists so the
+ * operator ALWAYS sees what was changed or created, even when no confirmation was
+ * required. For an update it shows the before -> after diff; for a create it shows
+ * the created object.
+ */
+export function AppliedCardView({ card }: { card: AppliedCard }) {
+  const hasDiff = card.diff && card.diff.length > 0;
+  return (
+    <Card className="border-primary/40">
+      <CardHeader className="flex flex-row items-center gap-2">
+        <CheckCircle2 className="w-4 h-4 text-primary" />
+        <CardTitle className="text-sm">Applied: {card.toolName}</CardTitle>
+        <Badge variant="secondary">applied</Badge>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <p className="text-sm text-muted-foreground">{card.summary}</p>
+        {hasDiff ? (
+          <div className="rounded bg-muted p-2">
+            <DiffView diff={card.diff ?? []} />
+          </div>
+        ) : card.result !== undefined && card.result !== null ? (
+          <pre className="text-xs bg-muted rounded p-2 overflow-auto max-h-48">
+            {JSON.stringify(card.result, null, 2)}
+          </pre>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/ConfirmCardView.tsx

@@ -0,0 +1,117 @@
+import { useState } from "react";
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardContent,
+  Button,
+  Badge,
+} from "@checkstack/ui";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { AiApi } from "@checkstack/ai-common";
+import { extractErrorMessage } from "@checkstack/common";
+import { ShieldAlert, Check, X } from "lucide-react";
+import type { ConfirmCard } from "../lib/stream-parser";
+import { DiffView } from "./DiffView";
+
+/**
+ * Renders a CONFIRM CARD for a mutate/destructive tool the model proposed. The
+ * model never silently mutates: nothing happens until the operator clicks
+ * Apply, which consumes the single-use proposal token via `applyTool`.
+ *
+ * After the operator applies OR declines, `onDecision` is fired so the page can
+ * stream the model's acknowledgment of the outcome (the conversation continues
+ * instead of dead-ending on "waiting for your confirmation").
+ */
+export function ConfirmCardView({
+  card,
+  onDecision,
+}: {
+  card: ConfirmCard;
+  onDecision?: (decision: {
+    token: string;
+    decision: "apply" | "decline";
+  }) => void;
+}) {
+  const ai = usePluginClient(AiApi);
+  const [state, setState] = useState<"pending" | "applied" | "declined">(
+    "pending",
+  );
+  const [error, setError] = useState<string | undefined>();
+
+  const applyMutation = ai.applyTool.useMutation({
+    onSuccess: () => {
+      setState("applied");
+      // Apply committed server-side; now have the model acknowledge it.
+      onDecision?.({ token: card.token, decision: "apply" });
+    },
+    onError: (error_: unknown) =>
+      setError(extractErrorMessage(error_, "Apply failed")),
+  });
+
+  const onDecline = () => {
+    setState("declined");
+    onDecision?.({ token: card.token, decision: "decline" });
+  };
+
+  const destructive = card.effect === "destructive";
+
+  return (
+    <Card className={destructive ? "border-destructive/50" : "border-primary/40"}>
+      <CardHeader className="flex flex-row items-center gap-2">
+        <ShieldAlert
+          className={`w-4 h-4 ${destructive ? "text-destructive" : "text-primary"}`}
+        />
+        <CardTitle className="text-sm">
+          Confirm: {card.toolName}
+        </CardTitle>
+        <Badge variant={destructive ? "destructive" : "secondary"}>
+          {card.effect}
+        </Badge>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <p className="text-sm text-muted-foreground">{card.summary}</p>
+        {/* For an update we show the before -> after diff (what changes);
+            otherwise the full ready-to-apply payload (what will be created). */}
+        {card.diff && card.diff.length > 0 ? (
+          <div className="max-h-72 overflow-auto rounded bg-muted p-2">
+            <DiffView diff={card.diff} />
+          </div>
+        ) : (
+          <pre className="text-xs bg-muted rounded p-2 overflow-auto max-h-48">
+            {JSON.stringify(card.payload, null, 2)}
+          </pre>
+        )}
+        {error ? (
+          <p className="text-xs text-destructive">{error}</p>
+        ) : null}
+        {state === "pending" ? (
+          <div className="flex gap-2">
+            <Button
+              size="sm"
+              variant={destructive ? "destructive" : "primary"}
+              disabled={applyMutation.isPending}
+              onClick={() => applyMutation.mutate({ token: card.token })}
+            >
+              <Check className="w-3.5 h-3.5 mr-1" />
+              {applyMutation.isPending ? "Applying..." : "Apply"}
+            </Button>
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={applyMutation.isPending}
+              onClick={onDecline}
+            >
+              <X className="w-3.5 h-3.5 mr-1" />
+              Decline
+            </Button>
+          </div>
+        ) : (
+          <p className="text-xs font-medium">
+            {state === "applied" ? "Applied." : "Declined."}
+          </p>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/DiffView.tsx

@@ -0,0 +1,84 @@
+import { useState } from "react";
+import { Maximize2 } from "lucide-react";
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@checkstack/ui";
+import type { FieldDiff } from "../lib/stream-parser";
+import { SideBySideDiff } from "./SideBySideDiff";
+
+/**
+ * Format a diff value as text for the side-by-side view. Strings render as-is (so
+ * a script keeps its line breaks); objects/arrays are pretty-printed multi-line
+ * JSON. A missing side (added or removed field) becomes an empty document so the
+ * other column shows the whole value as added/removed.
+ */
+function formatValue(value: unknown): string {
+  if (value === undefined) return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value, null, 2);
+}
+
+/** The list of per-field side-by-side diffs (shared by the inline + popout view). */
+function DiffBody({ diff }: { diff: FieldDiff[] }) {
+  return (
+    <div className="space-y-3">
+      {diff.map((entry) => (
+        <div key={entry.path} className="space-y-1">
+          <div className="break-all font-mono text-xs font-medium text-foreground">
+            {entry.path}
+          </div>
+          <SideBySideDiff
+            before={formatValue(entry.before)}
+            after={formatValue(entry.after)}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Render a before -> after field diff so the operator always sees exactly what an
+ * update changes, on both the confirm card (approve mode) and the applied card
+ * (auto mode). Each changed field renders a GitHub-style split diff (see
+ * {@link SideBySideDiff}). A small "Expand" control pops the full diff into a
+ * large dialog, since the inline chat bubble is narrow.
+ */
+export function DiffView({ diff }: { diff: FieldDiff[] }) {
+  const [expanded, setExpanded] = useState(false);
+  if (diff.length === 0) return null;
+  return (
+    <div className="space-y-1">
+      <div className="flex justify-end">
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className="h-6 gap-1 px-2 text-xs text-muted-foreground"
+          onClick={() => setExpanded(true)}
+        >
+          <Maximize2 className="h-3.5 w-3.5" />
+          Expand
+        </Button>
+      </div>
+      <DiffBody diff={diff} />
+      <Dialog open={expanded} onOpenChange={setExpanded}>
+        <DialogContent
+          size="full"
+          className="flex max-h-[85dvh] flex-col overflow-hidden"
+        >
+          <DialogHeader>
+            <DialogTitle>Proposed changes</DialogTitle>
+          </DialogHeader>
+          <div className="flex-1 overflow-auto pr-1">
+            <DiffBody diff={diff} />
+          </div>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}

package/src/components/SideBySideDiff.tsx

@@ -0,0 +1,120 @@
+import { Fragment } from "react";
+import { computeLineDiff, type DiffLine, type DiffSegment } from "../lib/line-diff";
+
+type Side = "left" | "right";
+type Kind = DiffLine["kind"];
+
+/** Line-level background tint for one side, GitHub-style (red left, green right). */
+function lineBg({ side, kind }: { side: Side; kind: Kind }): string {
+  if (kind === "equal") return "";
+  if (side === "left") {
+    return kind === "added" ? "bg-muted/30" : "bg-destructive/10";
+  }
+  return kind === "removed" ? "bg-muted/30" : "bg-success/10";
+}
+
+/** Line-number gutter text colour, matching the line tint. */
+function gutterText({ side, kind }: { side: Side; kind: Kind }): string {
+  if (kind === "equal") return "text-muted-foreground/70";
+  if (side === "left") {
+    return kind === "added" ? "text-muted-foreground/30" : "text-destructive/70";
+  }
+  return kind === "removed" ? "text-muted-foreground/30" : "text-success/80";
+}
+
+/** The `+` / `-` change marker for one side. */
+function marker({ side, kind }: { side: Side; kind: Kind }): string {
+  if (kind === "equal") return "";
+  if (side === "left") return kind === "added" ? "" : "-";
+  return kind === "removed" ? "" : "+";
+}
+
+/** Render a side's segments, strongly highlighting the changed tokens. */
+function Segments({
+  segments,
+  side,
+}: {
+  segments: DiffSegment[] | null;
+  side: Side;
+}) {
+  if (!segments) return null;
+  const strong = side === "left" ? "bg-destructive/30" : "bg-success/40";
+  return (
+    <>
+      {segments.map((segment, index) =>
+        segment.emphasis ? (
+          <span key={index} className={`rounded-sm ${strong}`}>
+            {segment.text}
+          </span>
+        ) : (
+          <Fragment key={index}>{segment.text}</Fragment>
+        ),
+      )}
+    </>
+  );
+}
+
+function Gutter({ no, side, kind }: { no: number | null; side: Side; kind: Kind }) {
+  return (
+    <div
+      className={`select-none px-2 text-right tabular-nums ${gutterText({
+        side,
+        kind,
+      })} ${lineBg({ side, kind })} ${side === "right" ? "border-l border-border" : ""}`}
+    >
+      {no ?? ""}
+    </div>
+  );
+}
+
+function Code({
+  segments,
+  side,
+  kind,
+}: {
+  segments: DiffSegment[] | null;
+  side: Side;
+  kind: Kind;
+}) {
+  return (
+    <div className={`flex gap-1 px-1 ${lineBg({ side, kind })}`}>
+      <span aria-hidden className="w-2 shrink-0 select-none text-center opacity-70">
+        {marker({ side, kind })}
+      </span>
+      <pre className="m-0 min-w-0 flex-1 whitespace-pre-wrap break-words">
+        <Segments segments={segments} side={side} />
+      </pre>
+    </div>
+  );
+}
+
+/**
+ * Render a before -> after change as a GitHub-style SPLIT diff: old text in the
+ * left column, new on the right, line-number gutters, `+`/`-` markers, per-line
+ * red/green tint, and word-level highlight of the exact changed tokens (via
+ * {@link computeLineDiff}). Lightweight - no editor stack. Long lines wrap; the
+ * columns share the available width.
+ */
+export function SideBySideDiff({
+  before,
+  after,
+}: {
+  before: string;
+  after: string;
+}) {
+  const rows = computeLineDiff({ before, after });
+  return (
+    <div className="overflow-hidden rounded-md border border-border bg-card">
+      <div className="grid grid-cols-[auto_1fr_auto_1fr] font-mono text-xs leading-relaxed">
+        {rows.map((row, index) => (
+          <Fragment key={index}>
+            <Gutter no={row.leftNo} side="left" kind={row.kind} />
+            <Code segments={row.left} side="left" kind={row.kind} />
+            <Gutter no={row.rightNo} side="right" kind={row.kind} />
+            <Code segments={row.right} side="right" kind={row.kind} />
+          </Fragment>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/index.tsx

@@ -0,0 +1,22 @@
+import { createFrontendPlugin } from "@checkstack/frontend-api";
+import { aiRoutes, pluginMetadata, aiAccess } from "@checkstack/ai-common";
+import { Sparkles } from "lucide-react";
+
+export default createFrontendPlugin({
+  metadata: pluginMetadata,
+  routes: [
+    {
+      route: aiRoutes.routes.chat,
+      load: () =>
+        import("./pages/ChatPage").then((m) => ({ default: m.ChatPage })),
+      title: "AI assistant",
+      accessRule: aiAccess.chatUse,
+      nav: {
+        group: "Workspace",
+        icon: Sparkles,
+      },
+    },
+  ],
+  apis: [],
+  extensions: [],
+});