@graph8/sdk 0.370.0 → 0.374.0

package/blocks/agents/components/knowledge-browser.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * KnowledgeBrowser: the company knowledge agents draw on. A status strip (entries, how many are draft, stable or deprecated, sync state),
+ * search (meaning-based, with an excerpt) or browse (filter by type and lifecycle), the list, and the open entry in a side panel
+ * (KnowledgeDetail, deep link ?concept=). "New entry" writes one (KnowledgeForm). "Export" downloads everything as a single archive.
+ * The list loads 25 at a time and "Load more" asks the API for more, up to its maximum of 100; at the maximum it says so.
+ *
+ * SDK operations, in order:
+ *   1. getKnowledgeStatus  GET /knowledge/status                        (read)
+ *   2. listKnowledge       GET /knowledge?concept_type&lifecycle&limit   (read)
+ *   3. searchKnowledge     GET /knowledge/search?query&limit=50          (read)  when the search box has text
+ *   4. exportKnowledge     GET /knowledge/export                         (read)  a link to the archive (opened in a new tab)
+ *   5. KnowledgeDetail / KnowledgeForm  see their files (get, history, sources, related, author, verify, deprecate)
+ */
+import { useMemo, useState } from "react";
+import { BookOpen, Plus } from "lucide-react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { LIFECYCLES } from "../lib/knowledge-utils";
+import type { KnowledgeSummary } from "../lib/knowledge-utils";
+import { LoadMore, useGrowingList } from "../lib/load-more";
+import { KnowledgeDetail } from "./knowledge-detail";
+import { KnowledgeForm } from "./knowledge-form";
+
+export interface KnowledgeBrowserProps {
+  className?: string;
+}
+
+interface Hit { summary?: KnowledgeSummary; excerpt?: string }
+interface Status { concept_count?: number; counts_by_lifecycle?: Record<string, number>; sync_state?: string; capabilities?: Record<string, boolean> }
+
+// A constant: the form resets its draft when `mode` changes identity, so it must not be rebuilt on every render.
+const NEW_MODE = { kind: "new" } as const;
+
+export function KnowledgeBrowser({ className }: KnowledgeBrowserProps) {
+  const [open, setOpen] = useUrlState("concept", "");
+  const [view, setView] = useUrlState("view", "");
+  const [search, setSearch] = useState("");
+  const [type, setType] = useState("");
+  const [lifecycle, setLifecycle] = useState("");
+  const [creating, setCreating] = useState(false);
+  const q = search.trim();
+  const status = useG8Query((signal) => g8Get("/knowledge/status", undefined, { signal }), []);
+  const list = useGrowingList<KnowledgeSummary>(async (limit, signal) => listOf<KnowledgeSummary>(await g8Get("/knowledge", { concept_type: type.trim() || undefined, lifecycle: lifecycle || undefined, limit }, { signal }), "items", "concepts"), [type, lifecycle], { pageSize: 25, max: 100, enabled: !q });
+  const hits = useG8Query((signal) => g8Get("/knowledge/search", { query: q, limit: 50 }, { signal }), [q], { enabled: Boolean(q) });
+  const st = bodyOf<Status>(status.data);
+  const lc = st.counts_by_lifecycle ?? {};
+  const rows: Array<{ s: KnowledgeSummary; excerpt?: string }> = useMemo(() => q
+    ? listOf<Hit>(hits.data).filter((h) => h.summary).map((h) => ({ s: h.summary as KnowledgeSummary, excerpt: h.excerpt }))
+    : list.items.map((s) => ({ s })), [q, hits.data, list.items]);
+  const types = useMemo(() => [...new Set(list.items.map((s) => s.concept_type).filter(Boolean))], [list.items]);
+  const loading = q ? hits.loading && !hits.data : list.loading;
+  const error = q ? hits.error : list.error;
+  const expanded = view === "full" && Boolean(open);
+  const refresh = () => { void status.refetch(); list.reload(); };
+
+  const listing = (
+    <div className="flex flex-col gap-3">
+      <Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search company knowledge" }}
+        filters={q ? undefined : <><Input aria-label="Filter by type" placeholder="Any type" list="kn-filter-types" className="h-8 w-36" value={type} onChange={(e) => setType(e.target.value)} />
+          <datalist id="kn-filter-types">{types.map((t) => <option key={t} value={t} />)}</datalist>
+          <select aria-label="Lifecycle" className="h-8 rounded-md border bg-background px-2 text-sm" value={lifecycle} onChange={(e) => setLifecycle(e.target.value)}><option value="">Any state</option>{LIFECYCLES.map((l) => <option key={l} value={l}>{l}</option>)}</select></>}
+        actions={<><Button size="sm" variant="outline" asChild><a href="/api/g8/knowledge/export" target="_blank" rel="noreferrer">Export</a></Button><Button size="sm" onClick={() => setCreating(true)}><Plus className="mr-1 size-4" />New entry</Button></>} />
+      {error ? <ApiError error={error} title="Could not load company knowledge" onRetry={() => (q ? void hits.refetch() : list.reload())} /> : null}
+      {loading ? <p className="text-sm text-muted-foreground" aria-busy="true">Loading knowledge...</p> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map(({ s, excerpt }) => (
+          <li key={s.concept_id} className={open === s.concept_id ? "bg-accent" : ""}>
+            <button type="button" data-testid={`concept-${s.concept_id}`} className="flex w-full items-start justify-between gap-3 px-3 py-2 text-left text-sm" onClick={() => setOpen(s.concept_id)}>
+              <span className="min-w-0"><span className="block truncate font-medium">{s.title}</span><span className="block truncate text-xs text-muted-foreground">{excerpt || s.logical_path || s.concept_type}</span></span>
+              <span className="flex shrink-0 items-center gap-1.5"><span className="text-xs text-muted-foreground">{s.concept_type}</span><StatusPill tone={toneForStatus(s.knowledge_status)} dot>{s.knowledge_status ?? "unknown"}</StatusPill></span>
+            </button>
+          </li>
+        ))}
+      </ul>
+      {!loading && !error && rows.length === 0 ? <EmptyState icon={<BookOpen strokeWidth={1.5} />} title={q ? "Nothing matches" : "No knowledge yet"} description={q ? "Try other words." : "Write down how your company sells, prices and supports, so agents can use it."} action={q ? undefined : <Button onClick={() => setCreating(true)}>New entry</Button>} /> : null}
+      {q && rows.length >= 50 ? <p className="text-center text-xs text-muted-foreground">Showing the 50 best matches. Narrow the search to see others.</p> : null}
+      {!q ? <LoadMore list={list} noun="entries" /> : null}
+    </div>
+  );
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <StatStrip loading={status.loading && !status.data} items={status.error ? [] : [
+        { label: "Entries", value: String(st.concept_count ?? 0) },
+        { label: "Stable", value: String(lc.stable ?? 0), tone: "positive" },
+        { label: "Draft", value: String(lc.draft ?? 0), tone: "warning" },
+        { label: "Deprecated", value: String(lc.deprecated ?? 0) },
+        { label: "Sync", value: st.sync_state ?? "unknown" },
+      ]} />
+      {status.error ? <ApiError compact error={status.error} title="Could not load the knowledge status" onRetry={() => void status.refetch()} /> : null}
+      <SplitView list={listing} detailOpen={Boolean(open)} onCloseDetail={() => { setOpen(""); setView(""); }} expanded={expanded} onExpandedChange={(e) => setView(e ? "full" : "")} detailWidth="xl"
+        detail={open ? <KnowledgeDetail key={open} conceptId={open} onClose={() => { setOpen(""); setView(""); }} onExpand={expanded ? undefined : () => setView("full")} onCollapse={expanded ? () => setView("") : undefined} onOpenConcept={setOpen} onChanged={refresh} /> : null} />
+      <KnowledgeForm mode={creating ? NEW_MODE : null} typeSuggestions={types} onClose={() => setCreating(false)} onSaved={(id) => { refresh(); if (id) setOpen(id); }} />
+    </div>
+  );
+}

package/blocks/agents/components/knowledge-detail.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * KnowledgeDetail: one company knowledge entry in full. Tabs: Content (the Markdown, warnings), History (every version and amendment, newest
+ * first, "Load more" follows the cursor), Sources (what it was written from) and Related (linked entries, which open in place).
+ * Actions for authored entries (generated ones come from your CRM and campaigns and are read only):
+ *   Edit draft / Propose new version (KnowledgeForm), Verify (approve or reject, with the authority that signs off), Deprecate (a reason, optionally
+ *   the entry that replaces it; destructive, confirmed).
+ *
+ * SDK operations, in order:
+ *   1. getKnowledge                 GET  /knowledge/{concept_id}                 (read)
+ *   2. getKnowledgeHistory          GET  /knowledge/{concept_id}/history?cursor&limit   (read)
+ *   3. knowledgeSources             GET  /knowledge/{concept_id}/sources          (read)
+ *   4. relatedKnowledge             GET  /knowledge/{concept_id}/related?depth=1&limit=20   (read)
+ *   5. verifyAuthoredKnowledge      POST /knowledge/authored/{concept_id}/verify { approve, authority }   (write)
+ *   6. deprecateAuthoredKnowledge   POST /knowledge/authored/{concept_id}/deprecate { reason, superseded_by? }   (destructive, ConfirmSpendDialog)
+ *   7. KnowledgeForm: create/update draft/amend (see knowledge-form.tsx)
+ */
+import { useEffect, useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { bodyFromMarkdown, conceptOf, isAuthored } from "../lib/knowledge-utils";
+import { KnowledgeForm } from "./knowledge-form";
+import type { KnowledgeFormMode } from "./knowledge-form";
+
+export interface KnowledgeDetailProps {
+  conceptId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Open another entry (from Related). */
+  onOpenConcept?: (conceptId: string) => void;
+  /** After any change, so the host can refresh its list. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Row = Record<string, unknown>;
+const str = (v: unknown): string => (typeof v === "string" ? v : typeof v === "number" ? String(v) : "");
+
+function History({ conceptId }: { conceptId: string }) {
+  const [rows, setRows] = useState<Row[]>([]);
+  const [cursor, setCursor] = useState<string | undefined>();
+  const [next, setNext] = useState<string | undefined>();
+  const q = useG8Query((signal) => g8Get(`/knowledge/${encodeURIComponent(conceptId)}/history`, { limit: 25, cursor }, { signal }), [conceptId, cursor]);
+  useEffect(() => { setRows([]); setCursor(undefined); setNext(undefined); }, [conceptId]);
+  useEffect(() => {
+    if (!q.data) return;
+    const page = listOf<Row>(q.data, "items", "versions", "revisions", "history");
+    setRows((prev) => (cursor ? [...prev, ...page] : page));
+    const body = bodyOf<{ next_cursor?: string | null }>(q.data);
+    setNext(body.next_cursor ?? (q.data as { pagination?: { next_cursor?: string | null } }).pagination?.next_cursor ?? undefined);
+  }, [q.data]); // eslint-disable-line react-hooks/exhaustive-deps
+  if (q.error) return <ApiError error={q.error} title="Could not load the history" onRetry={() => void q.refetch()} />;
+  if (q.loading && rows.length === 0) return <Skeleton className="h-16 w-full" />;
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No revisions recorded.</p>;
+  return (
+    <div className="flex flex-col gap-2">
+      <ul className="divide-y rounded-md border" aria-label="Revisions">
+        {rows.map((r, i) => (
+          <li key={i} className="flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-sm">
+            <span>{str(r.summary ?? r.title ?? r.change ?? r.action ?? r.version ?? r.revision) || `Revision ${rows.length - i}`}<span className="block text-xs text-muted-foreground">{str(r.actor ?? r.author ?? r.actor_id)}</span></span>
+            <span className="flex items-center gap-2">{str(r.knowledge_status ?? r.status) ? <StatusPill tone={toneForStatus(str(r.knowledge_status ?? r.status))}>{str(r.knowledge_status ?? r.status)}</StatusPill> : null}<span className="text-xs text-muted-foreground">{str(r.created_at ?? r.at ?? r.recorded_at) ? new Date(str(r.created_at ?? r.at ?? r.recorded_at)).toLocaleString() : ""}</span></span>
+          </li>
+        ))}
+      </ul>
+      {next ? <Button size="sm" variant="outline" className="self-center" loading={q.loading} onClick={() => setCursor(next)}>Load more revisions</Button> : null}
+    </div>
+  );
+}
+
+export function KnowledgeDetail({ conceptId, onClose, onExpand, onCollapse, onOpenConcept, onChanged, className }: KnowledgeDetailProps) {
+  const [form, setForm] = useState<KnowledgeFormMode | null>(null);
+  const [verifying, setVerifying] = useState<{ approve: boolean; authority: string } | null>(null);
+  const [deprecating, setDeprecating] = useState<{ reason: string; superseded_by: string } | null>(null);
+  const [confirmDeprecate, setConfirmDeprecate] = useState(false);
+  useEffect(() => { setForm(null); setVerifying(null); setDeprecating(null); setConfirmDeprecate(false); }, [conceptId]);
+  const enc = encodeURIComponent(conceptId);
+  const concept = useG8Query((signal) => g8Get(`/knowledge/${enc}`, undefined, { signal }), [conceptId]);
+  const sources = useG8Query((signal) => g8Get(`/knowledge/${enc}/sources`, undefined, { signal }), [conceptId]);
+  const related = useG8Query((signal) => g8Get(`/knowledge/${enc}/related`, { depth: 1, limit: 20 }, { signal }), [conceptId]);
+  const c = conceptOf(concept.data);
+  const done = () => { void concept.refetch(); onChanged?.(); };
+  const verify = useG8Mutation((v: { approve: boolean; authority: string }) => g8Post(`/knowledge/authored/${enc}/verify`, v), { onSuccess: () => { setVerifying(null); done(); } });
+  const deprecate = useG8Mutation((v: { reason: string; superseded_by: string }) => g8Post(`/knowledge/authored/${enc}/deprecate`, { reason: v.reason, ...(v.superseded_by ? { superseded_by: v.superseded_by } : {}) }), { onSuccess: () => { setConfirmDeprecate(false); setDeprecating(null); done(); }, onError: () => setConfirmDeprecate(false) });
+
+  if (concept.error) return <ApiError error={concept.error} title="Could not load the entry" onRetry={() => void concept.refetch()} />;
+  if (!c) return <Skeleton className="h-40 w-full" aria-label="Loading entry" />;
+  const s = c.summary;
+  const authored = isAuthored(s);
+  const status = s.knowledge_status ?? "";
+  const loaded = { title: s.title, concept_type: s.concept_type, body: bodyFromMarkdown(c.markdown) };
+  const srcRows = listOf<{ resource?: string; title?: string | null; locator?: string | null }>(sources.data);
+  const relRows = listOf<{ concept_id?: string; title?: string; concept_type?: string; summary?: { concept_id?: string; title?: string } }>(related.data);
+
+  const actions = authored ? (
+    <>
+      {status === "draft" ? <Button size="sm" variant="outline" onClick={() => setForm({ kind: "edit", conceptId, loaded })}>Edit draft</Button> : null}
+      {status === "stable" ? <Button size="sm" variant="outline" onClick={() => setForm({ kind: "amend", conceptId, loaded })}>Propose new version</Button> : null}
+      {status !== "deprecated" ? <Button size="sm" variant="outline" onClick={() => setVerifying({ approve: true, authority: "" })}>Verify</Button> : null}
+      {status !== "deprecated" ? <Button size="sm" variant="ghost" onClick={() => setDeprecating({ reason: "", superseded_by: "" })}>Deprecate</Button> : null}
+    </>
+  ) : undefined;
+
+  return (
+    <>
+      <DetailPanel className={className} title={s.title} subtitle={s.logical_path ?? s.concept_type} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} actions={actions}
+        badges={<><StatusPill tone={toneForStatus(status)} dot>{status || "unknown"}</StatusPill>{s.trust_tier ? <StatusPill tone="neutral">{s.trust_tier.replace(/_/g, " ")}</StatusPill> : null}{s.stale ? <StatusPill tone="warning">stale</StatusPill> : null}{!authored ? <StatusPill tone="info" title="Built from your records; change the source, not the entry">generated</StatusPill> : null}</>}
+        tabs={[
+          { id: "content", label: "Content", content: (
+            <div className="flex flex-col gap-3">
+              {(c.warnings ?? []).map((w) => <p key={w} role="status" className="rounded-md border border-warning-foreground/25 bg-warning p-2 text-sm text-warning-foreground">{w}</p>)}
+              <pre className="whitespace-pre-wrap text-sm">{bodyFromMarkdown(c.markdown) || "This entry has no content."}</pre>
+            </div>) },
+          { id: "history", label: "History", content: <History conceptId={conceptId} /> },
+          { id: "sources", label: "Sources", count: srcRows.length, content: sources.error ? <ApiError error={sources.error} title="Could not load the sources" onRetry={() => void sources.refetch()} /> : srcRows.length === 0 ? <p className="text-sm text-muted-foreground">No sources recorded.</p> : (
+            <ul className="divide-y rounded-md border">{srcRows.map((r, i) => <li key={i} className="px-3 py-2 text-sm">{r.title || r.resource}{r.locator ? <span className="block text-xs text-muted-foreground">{r.locator}</span> : null}</li>)}</ul>) },
+          { id: "related", label: "Related", count: relRows.length, content: related.error ? <ApiError error={related.error} title="Could not load related entries" onRetry={() => void related.refetch()} /> : relRows.length === 0 ? <p className="text-sm text-muted-foreground">Nothing linked yet.</p> : (
+            <ul className="divide-y rounded-md border">{relRows.map((r, i) => { const id = r.concept_id ?? r.summary?.concept_id ?? ""; const title = r.title ?? r.summary?.title ?? id; return <li key={id || i}><button type="button" className="w-full px-3 py-2 text-left text-sm hover:bg-accent" disabled={!id || !onOpenConcept} onClick={() => onOpenConcept?.(id)}>{title}{r.concept_type ? <span className="ml-2 text-xs text-muted-foreground">{r.concept_type}</span> : null}</button></li>; })}</ul>) },
+        ]}>
+        {null}
+      </DetailPanel>
+      <KnowledgeForm mode={form} onClose={() => setForm(null)} onSaved={() => done()} />
+      <Dialog open={verifying != null} onOpenChange={(o) => !o && setVerifying(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Verify this entry</DialogTitle><DialogDescription>Say who signs it off. Approved entries are trusted more by agents.</DialogDescription></DialogHeader>
+          <div className="flex flex-col gap-1"><Label htmlFor="kn-authority">Authority</Label><Input id="kn-authority" placeholder="Head of Sales" value={verifying?.authority ?? ""} onChange={(e) => setVerifying((v) => v && { ...v, authority: e.target.value })} /></div>
+          {verify.error ? <ApiError error={verify.error} title="Could not record the decision" /> : null}
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setVerifying(null)}>Cancel</Button>
+            <Button variant="outline" loading={verify.loading} disabled={!verifying?.authority.trim()} onClick={() => verifying && void verify.mutate({ approve: false, authority: verifying.authority.trim() })}>Reject</Button>
+            <Button loading={verify.loading} disabled={!verifying?.authority.trim()} onClick={() => verifying && void verify.mutate({ approve: true, authority: verifying.authority.trim() })}>Approve</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <Dialog open={deprecating != null && !confirmDeprecate} onOpenChange={(o) => !o && setDeprecating(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Deprecate this entry</DialogTitle><DialogDescription>Agents stop relying on it. The history is kept.</DialogDescription></DialogHeader>
+          <div className="flex flex-col gap-1"><Label htmlFor="kn-reason">Reason</Label><Input id="kn-reason" value={deprecating?.reason ?? ""} onChange={(e) => setDeprecating((v) => v && { ...v, reason: e.target.value })} /></div>
+          <div className="flex flex-col gap-1"><Label htmlFor="kn-superseded">Replaced by (entry id, optional)</Label><Input id="kn-superseded" value={deprecating?.superseded_by ?? ""} onChange={(e) => setDeprecating((v) => v && { ...v, superseded_by: e.target.value })} /></div>
+          {deprecate.error ? <ApiError error={deprecate.error} title="Could not deprecate the entry" /> : null}
+          <DialogFooter><Button variant="ghost" onClick={() => setDeprecating(null)}>Cancel</Button><Button disabled={!deprecating?.reason.trim()} onClick={() => setConfirmDeprecate(true)}>Continue</Button></DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog open={confirmDeprecate} tier="destructive" title={`Deprecate "${s.title}"`} description="Agents stop relying on this entry. It stays in the history, but cannot be made current again." affected={1}
+        confirmLabel="Deprecate" confirming={deprecate.loading} onConfirm={() => deprecating && void deprecate.mutate(deprecating)} onCancel={() => setConfirmDeprecate(false)} />
+    </>
+  );
+}

package/blocks/agents/components/knowledge-form.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+/**
+ * KnowledgeForm: write a company knowledge entry in a side sheet.
+ *   mode "new"    a new draft entry (createAuthoredKnowledge).
+ *   mode "edit"   change a DRAFT entry in place (updateAuthoredKnowledgeDraft).
+ *   mode "amend"  propose a new version of a published entry (createAuthoredKnowledgeAmendment); it is reviewed before it replaces the old one.
+ * The API takes the whole entry, so edit and amend start from the LOADED entry and stay disabled until it has loaded; Save is only
+ * enabled when something changed. Nothing here spends credits or reaches outside the workspace.
+ *
+ * SDK operations:
+ *   createAuthoredKnowledge            POST  /knowledge/authored { title, concept_type, body }                    (write)
+ *   updateAuthoredKnowledgeDraft       PATCH /knowledge/authored/{concept_id} { title, concept_type, body }       (write)
+ *   createAuthoredKnowledgeAmendment   POST  /knowledge/authored/{concept_id}/amendments { title, concept_type, body }   (write)
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf } from "../lib/agent-types";
+import type { KnowledgeInput } from "../lib/knowledge-utils";
+
+export type KnowledgeFormMode = { kind: "new" } | { kind: "edit"; conceptId: string; loaded: KnowledgeInput } | { kind: "amend"; conceptId: string; loaded: KnowledgeInput };
+
+export interface KnowledgeFormProps {
+  mode: KnowledgeFormMode | null;
+  /** Types already in use, offered as suggestions. */
+  typeSuggestions?: string[];
+  onClose: () => void;
+  onSaved?: (conceptId: string | undefined) => void;
+}
+
+const BLANK: KnowledgeInput = { title: "", concept_type: "", body: "" };
+const COPY = { new: ["New knowledge entry", "Create entry"], edit: ["Edit draft", "Save draft"], amend: ["Propose a new version", "Propose version"] } as const;
+
+export function KnowledgeForm({ mode, typeSuggestions = [], onClose, onSaved }: KnowledgeFormProps) {
+  const [d, setD] = useState<KnowledgeInput>(BLANK);
+  const seed = mode && mode.kind !== "new" ? mode.loaded : BLANK;
+  useEffect(() => { setD(mode && mode.kind !== "new" ? mode.loaded : BLANK); }, [mode]);
+  const save = useG8Mutation(async () => {
+    if (!mode) return undefined;
+    const res = mode.kind === "new" ? await g8Post("/knowledge/authored", d)
+      : mode.kind === "edit" ? await g8Patch(`/knowledge/authored/${encodeURIComponent(mode.conceptId)}`, d)
+      : await g8Post(`/knowledge/authored/${encodeURIComponent(mode.conceptId)}/amendments`, d);
+    return bodyOf<{ concept_id?: string }>(res).concept_id;
+  }, { onSuccess: (id) => { onSaved?.(id); onClose(); } });
+  const set = (patch: Partial<KnowledgeInput>) => setD((x) => ({ ...x, ...patch }));
+  const changed = d.title !== seed.title || d.concept_type !== seed.concept_type || d.body !== seed.body;
+  const valid = d.title.trim() && d.concept_type.trim() && d.body.trim();
+  const [title, cta] = COPY[mode?.kind ?? "new"];
+  return (
+    <FormSheet open={mode != null} onOpenChange={(o) => !o && onClose()} title={title} width="xl"
+      description={mode?.kind === "amend" ? "The new version is reviewed before it replaces the published one." : "Written in Markdown. Agents can draw on it once it is published."}
+      footer={<><Button variant="ghost" onClick={onClose}>Cancel</Button><Button loading={save.loading} disabled={!valid || !changed} onClick={() => void save.mutate(undefined)}>{cta}</Button></>}>
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-1"><Label htmlFor="kn-title">Title</Label><Input id="kn-title" value={d.title} onChange={(e) => set({ title: e.target.value })} /></div>
+        <div className="flex flex-col gap-1">
+          <Label htmlFor="kn-type">Type</Label>
+          <Input id="kn-type" list="kn-types" placeholder="playbook, policy, faq" value={d.concept_type} onChange={(e) => set({ concept_type: e.target.value })} />
+          <datalist id="kn-types">{typeSuggestions.map((t) => <option key={t} value={t} />)}</datalist>
+        </div>
+        <div className="flex flex-col gap-1"><Label htmlFor="kn-body">Content (Markdown)</Label><Textarea id="kn-body" rows={14} className="font-mono text-xs" value={d.body} onChange={(e) => set({ body: e.target.value })} /></div>
+        {save.error ? <ApiError error={save.error} title="Could not save the entry" /> : null}
+      </div>
+    </FormSheet>
+  );
+}

package/blocks/agents/components/name-dialog.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+/** NameDialog: a small dialog that asks for one name (the copy of an agent, a template). Used by the duplicate and save-as-template buttons. SDK operations: none. */
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+
+export interface NameDialogProps {
+  open: boolean;
+  title: string;
+  description: string;
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  confirm: string;
+  busy: boolean;
+  error: unknown;
+  onCancel: () => void;
+  onConfirm: () => void;
+}
+
+export function NameDialog({ open, title, description, label, value, onChange, confirm, busy, error, onCancel, onConfirm }: NameDialogProps) {
+  return (
+    <Dialog open={open} onOpenChange={(o) => !o && !busy && onCancel()}>
+      <DialogContent>
+        <DialogHeader><DialogTitle>{title}</DialogTitle><DialogDescription>{description}</DialogDescription></DialogHeader>
+        <div className="flex flex-col gap-1"><Label htmlFor="agent-action-name">{label}</Label><Input id="agent-action-name" value={value} onChange={(e) => onChange(e.target.value)} /></div>
+        {error ? <ApiError error={error} title="That did not work" /> : null}
+        <DialogFooter><Button variant="ghost" disabled={busy} onClick={onCancel}>Cancel</Button><Button loading={busy} disabled={!value.trim()} onClick={onConfirm}>{confirm}</Button></DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/blocks/agents/components/receptionist-button.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+/**
+ * ReceptionistButton: set up the workspace receptionist (an agent that answers inbound calls) and switch it on or off. There is no call that
+ * reads whether it is on, so Turn on and Turn off are explicit and safe to repeat. Turning it on lets it answer real callers, so on and off
+ * go through ConfirmSpendDialog (external).
+ *
+ * SDK operations, in order:
+ *   1. ensureReceptionistAgent   POST  /voice/agents/receptionist                    (write)  creates it when missing
+ *   2. toggleReceptionistAgent   PATCH /voice/agents/receptionist?enabled             (write, confirmed as external)
+ */
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+
+export function ReceptionistButton() {
+  const [open, setOpen] = useState(false);
+  const [pending, setPending] = useState<boolean | null>(null);
+  const [result, setResult] = useState<string | null>(null);
+  const ensure = useG8Mutation(() => g8Post("/voice/agents/receptionist", {}), { onSuccess: () => setResult("The receptionist is set up. Turn it on when it is ready to take calls.") });
+  const toggle = useG8Mutation((enabled: boolean) => g8Patch("/voice/agents/receptionist", {}, { query: { enabled } }), { onSuccess: (_r, on) => { setPending(null); setResult(on ? "The receptionist is on." : "The receptionist is off.") }, onError: () => setPending(null) });
+  return (
+    <>
+      <Button variant="outline" onClick={() => { setResult(null); ensure.reset(); toggle.reset(); setOpen(true); }}>Receptionist</Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Receptionist</DialogTitle><DialogDescription>An agent that answers your inbound calls and routes them. Set it up once, then switch it on or off.</DialogDescription></DialogHeader>
+          {result ? <p role="status" className="text-sm">{result}</p> : null}
+          {ensure.error ? <ApiError error={ensure.error} title="Could not set up the receptionist" /> : null}
+          {toggle.error ? <ApiError error={toggle.error} title="Could not change the receptionist" /> : null}
+          <DialogFooter className="gap-2">
+            <Button variant="outline" loading={ensure.loading} onClick={() => void ensure.mutate(undefined)}>Set up</Button>
+            <Button variant="outline" onClick={() => setPending(false)}>Turn off</Button>
+            <Button onClick={() => setPending(true)}>Turn on</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog open={pending != null} tier="external" title={pending ? "Turn the receptionist on" : "Turn the receptionist off"}
+        description={pending ? "The receptionist starts answering real callers on your numbers." : "Inbound calls stop going to the receptionist."}
+        confirmLabel={pending ? "Turn on" : "Turn off"} confirming={toggle.loading} onConfirm={() => pending != null && void toggle.mutate(pending)} onCancel={() => setPending(null)} />
+    </>
+  );
+}

package/blocks/agents/components/save-as-template-button.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+/**
+ * SaveAsTemplateButton: keep an agent as a reusable template of this workspace; anyone can start a new agent from it (FromTemplateButton).
+ *
+ * SDK operations:
+ *   saveAgentAsTemplate   POST /voice/agents/{agent_id}/save-as-template?template_name   (write)
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import type { AgentSummary } from "../lib/agent-types";
+import { NameDialog } from "./name-dialog";
+
+export interface SaveAsTemplateButtonProps {
+  agent: Pick<AgentSummary, "agent_id" | "agent_name">;
+  variant?: "outline" | "ghost";
+}
+
+export function SaveAsTemplateButton({ agent, variant = "outline" }: SaveAsTemplateButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState("");
+  const save = useG8Mutation((n: string) => g8Post(`/voice/agents/${encodeURIComponent(agent.agent_id)}/save-as-template`, {}, { query: { template_name: n } }), { onSuccess: () => setOpen(false) });
+  return (
+    <>
+      <Button size="sm" variant={variant} onClick={() => { save.reset(); setName(agent.agent_name); setOpen(true); }}>Save as template</Button>
+      <NameDialog open={open} title={`Save ${agent.agent_name} as a template`} description="Anyone in the workspace can start a new agent from it." label="Template name"
+        value={name} onChange={setName} confirm="Save template" busy={save.loading} error={save.error} onCancel={() => setOpen(false)} onConfirm={() => void save.mutate(name.trim())} />
+    </>
+  );
+}

package/blocks/agents/components/skill-editor.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+/**
+ * SkillEditor: create or edit one skill (a single-purpose action an agent can run) in a side sheet.
+ *   Edit:   the skill is loaded first and the form stays disabled until it has loaded (a blank form never overwrites the real skill);
+ *           Save sends only the fields you changed (a runtime config goes whole, because voice validates it as a unit).
+ *           Also: enable or disable, see the {placeholders} the skill asks for, check a template, delete.
+ *   Create: an LLM skill (model + prompt) or an API skill (endpoint, method, headers, body).
+ * Deleting a skill removes it from every agent that uses it, so it is destructive and confirmed.
+ *
+ * SDK operations, in order:
+ *   1. getSkill         GET    /skills/{action_id}                (read)
+ *   2. extractVariables GET    /skills/{action_id}/variables      (read)
+ *   3. listModels       GET    /skills/models                     (read)  LLM model choices
+ *   4. validateTemplate POST   /skills/validate { template | runtime_type + config }   (write, free: warns about double braces)
+ *   5. createSkill      POST   /skills { name, runtime_type, llm_config | api_config }  (write)
+ *   6. updateSkill      PUT    /skills/{action_id} { changed fields }                  (write)
+ *   7. deleteSkill      DELETE /skills/{action_id}                (destructive, ConfirmSpendDialog)
+ */
+import { useEffect, useRef, useState } from "react";
+import { Button, Input, Label, Skeleton, Switch, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { BLANK_DRAFT, HTTP_METHODS, draftOf, newSkillBody, parseHeaders, skillOf, skillPatch } from "../lib/skill-utils";
+import type { SkillDraft } from "../lib/skill-utils";
+
+export type SkillEditorTarget = { kind: "edit"; id: string } | { kind: "new"; runtime: "llm" | "api" };
+
+export interface SkillEditorProps {
+  /** The skill to edit or the kind to create; null closes the sheet. */
+  target: SkillEditorTarget | null;
+  onClose: () => void;
+  /** After a create, save or delete. */
+  onChanged?: (event: "created" | "updated" | "deleted", id?: string) => void;
+}
+
+export function SkillEditor({ target, onClose, onChanged }: SkillEditorProps) {
+  const editId = target?.kind === "edit" ? target.id : "";
+  const runtime = target?.kind === "new" ? target.runtime : undefined;
+  const [d, setD] = useState<SkillDraft>(BLANK_DRAFT);
+  const [deleting, setDeleting] = useState(false);
+  const seeded = useRef<string>("");
+  const loaded = useG8Query((signal) => g8Get(`/skills/${encodeURIComponent(editId)}`, undefined, { signal }), [editId], { enabled: Boolean(editId) });
+  // useG8Query keeps the previous skill's data while the next loads: only the skill fetched for THIS id counts as loaded.
+  const got = editId ? skillOf(loaded.data) : undefined;
+  const skill = got && got.action_id === editId ? got : undefined;
+  const vars = useG8Query((signal) => g8Get(`/skills/${encodeURIComponent(editId)}/variables`, undefined, { signal }), [editId], { enabled: Boolean(editId) && Boolean(skill) });
+  const kind = skill?.runtime_type ?? runtime;
+  const models = useG8Query((signal) => g8Get("/skills/models", undefined, { signal }), [], { enabled: kind === "llm" });
+  const set = (patch: Partial<SkillDraft>) => setD((x) => ({ ...x, ...patch }));
+
+  // Seed the form from the LOADED skill, once per skill (a refetch must not overwrite what the person is typing).
+  useEffect(() => {
+    if (target?.kind === "new") { seeded.current = "new"; setD(BLANK_DRAFT); setDeleting(false); return; }
+    if (skill && seeded.current !== skill.action_id) { seeded.current = skill.action_id; setD(draftOf(skill)); }
+  }, [target, skill]);
+  useEffect(() => { if (!target) { seeded.current = ""; } }, [target]);
+
+  const patch = skill ? skillPatch(skill, d) : {};
+  const headersOk = d.headers.trim() === "" || parseHeaders(d.headers) != null;
+  const numbersOk = kind !== "llm" || (Number.isFinite(Number(d.temperature)) && Number(d.max_tokens) > 0);
+  const filled = d.name.trim() && (kind === "llm" ? d.model && d.prompt_template.trim() : d.endpoint.trim());
+  const valid = Boolean(filled) && headersOk && numbersOk;
+
+  const create = useG8Mutation(async () => {
+    const res = await g8Post("/skills", newSkillBody(kind as "llm" | "api", d));
+    return skillOf(res)?.action_id;
+  }, { onSuccess: (id) => { onChanged?.("created", id); onClose(); } });
+  const save = useG8Mutation(() => g8Put(`/skills/${encodeURIComponent(editId)}`, patch), { onSuccess: () => { seeded.current = ""; void loaded.refetch(); void vars.refetch(); onChanged?.("updated", editId); } });
+  const remove = useG8Mutation(() => g8Delete(`/skills/${encodeURIComponent(editId)}`), { onSuccess: () => { setDeleting(false); onChanged?.("deleted", editId); onClose(); }, onError: () => setDeleting(false) });
+  const check = useG8Mutation(() => g8Post("/skills/validate", kind === "llm" ? { template: d.prompt_template } : { runtime_type: "api", api_config: { endpoint: d.endpoint, body_template: d.body_template, headers: parseHeaders(d.headers) ?? {} } }));
+
+  const modelRows = listOf<{ id: string; label?: string }>(models.data, "models");
+  const checked = bodyOf<{ variables?: string[]; warnings?: string[] }>(check.data);
+  const names = (bodyOf<{ variables?: string[] }>(vars.data).variables ?? []) as string[];
+  const waiting = Boolean(editId) && !skill;
+  const title = target?.kind === "new" ? (runtime === "api" ? "New API skill" : "New LLM skill") : skill?.name ?? "Skill";
+
+  return (
+    <>
+      <FormSheet open={target != null} onOpenChange={(o) => !o && onClose()} title={title} width="lg"
+        description={target?.kind === "new" ? "Use {variable} placeholders for values the agent fills in when it runs the skill." : "Changes apply to every agent that uses this skill."}
+        footer={<>
+          {editId ? <Button variant="ghost" className="mr-auto" disabled={!skill} onClick={() => setDeleting(true)}>Delete</Button> : null}
+          <Button variant="ghost" onClick={onClose}>Cancel</Button>
+          {target?.kind === "new" ? <Button loading={create.loading} disabled={!valid} onClick={() => void create.mutate(undefined)}>Create skill</Button>
+            : <Button loading={save.loading} disabled={!skill || Object.keys(patch).length === 0 || !valid} onClick={() => void save.mutate(undefined)}>Save changes</Button>}
+        </>}>
+        {loaded.error ? <ApiError error={loaded.error} title="Could not load the skill" onRetry={() => void loaded.refetch()} /> : null}
+        {waiting && !loaded.error ? <Skeleton className="h-40 w-full" aria-label="Loading skill" /> : null}
+        {!waiting ? (
+          <fieldset className="flex flex-col gap-3 border-0 p-0" disabled={save.loading || create.loading}>
+            <div className="flex flex-col gap-1"><Label htmlFor="sk-name">Name</Label><Input id="sk-name" value={d.name} onChange={(e) => set({ name: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="sk-desc">What it does</Label><Input id="sk-desc" value={d.description} onChange={(e) => set({ description: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="sk-cat">Category</Label><Input id="sk-cat" value={d.category} onChange={(e) => set({ category: e.target.value })} /></div>
+            {editId ? <label className="flex items-center gap-2 text-sm"><Switch checked={d.enabled} onCheckedChange={(v) => set({ enabled: v })} aria-label="Enabled" />Enabled</label> : null}
+            {kind === "llm" ? (
+              <>
+                <div className="flex flex-col gap-1">
+                  <Label htmlFor="sk-model">Model</Label>
+                  <select id="sk-model" className="h-9 rounded-md border bg-background px-2 text-sm" value={d.model} onChange={(e) => set({ model: e.target.value })}>
+                    <option value="">Choose a model</option>
+                    {d.model && !modelRows.some((m) => m.id === d.model) ? <option value={d.model}>{d.model}</option> : null}
+                    {modelRows.map((m) => <option key={m.id} value={m.id}>{m.label ?? m.id}</option>)}
+                  </select>
+                </div>
+                <div className="flex flex-col gap-1"><Label htmlFor="sk-prompt">Prompt</Label><Textarea id="sk-prompt" rows={8} value={d.prompt_template} onChange={(e) => set({ prompt_template: e.target.value })} /></div>
+                <div className="grid grid-cols-2 gap-3">
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-temp">Temperature (0 to 2)</Label><Input id="sk-temp" inputMode="decimal" value={d.temperature} onChange={(e) => set({ temperature: e.target.value })} /></div>
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-max">Max tokens</Label><Input id="sk-max" inputMode="numeric" value={d.max_tokens} onChange={(e) => set({ max_tokens: e.target.value })} /></div>
+                </div>
+              </>
+            ) : (
+              <>
+                <div className="grid grid-cols-[7rem_1fr] gap-3">
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-method">Method</Label>
+                    <select id="sk-method" className="h-9 rounded-md border bg-background px-2 text-sm" value={d.method} onChange={(e) => set({ method: e.target.value })}>{HTTP_METHODS.map((m) => <option key={m} value={m}>{m}</option>)}</select></div>
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-endpoint">Endpoint</Label><Input id="sk-endpoint" placeholder="https://api.example.com/items/{item_id}" value={d.endpoint} onChange={(e) => set({ endpoint: e.target.value })} /></div>
+                </div>
+                <div className="flex flex-col gap-1"><Label htmlFor="sk-headers">Headers (JSON)</Label><Textarea id="sk-headers" rows={3} className="font-mono text-xs" value={d.headers} onChange={(e) => set({ headers: e.target.value })} /></div>
+                {!headersOk ? <p role="alert" className="text-sm text-error-foreground">Headers must be a JSON object of text values.</p> : null}
+                <div className="flex flex-col gap-1"><Label htmlFor="sk-body">Body template</Label><Textarea id="sk-body" rows={4} className="font-mono text-xs" value={d.body_template} onChange={(e) => set({ body_template: e.target.value })} /></div>
+                <label className="flex items-center gap-2 text-sm"><Switch checked={d.requires_auth} onCheckedChange={(v) => set({ requires_auth: v })} aria-label="Requires auth" />Requires authentication</label>
+              </>
+            )}
+            {names.length ? <p className="text-xs text-muted-foreground">Asks for: {names.map((n) => `{${n}}`).join(", ")}</p> : null}
+            <div className="flex items-center gap-2">
+              <Button size="sm" variant="outline" loading={check.loading} disabled={kind === "llm" ? !d.prompt_template.trim() : !d.endpoint.trim()} onClick={() => void check.mutate(undefined)}>Check placeholders</Button>
+              {check.data !== undefined ? <span role="status" className="text-xs text-muted-foreground">{(checked.variables ?? []).length} placeholders{(checked.warnings ?? []).length ? `, ${(checked.warnings ?? []).join(" ")}` : ", no warnings"}</span> : null}
+            </div>
+            {check.error ? <ApiError error={check.error} title="Could not check the template" /> : null}
+            {create.error ? <ApiError error={create.error} title="Could not create the skill" /> : null}
+            {save.error ? <ApiError error={save.error} title="Could not save the skill" /> : null}
+            {remove.error ? <ApiError error={remove.error} title="Could not delete the skill" /> : null}
+          </fieldset>
+        ) : null}
+      </FormSheet>
+      <ConfirmSpendDialog open={deleting} tier="destructive" title={`Delete "${skill?.name ?? "this skill"}"`} description="Every agent that uses it loses it, and workflows that call it stop working." affected={1}
+        confirmLabel="Delete" confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setDeleting(false)} />
+    </>
+  );
+}