@contractspec/bundle.library 3.10.0 → 3.10.2

package/dist/components/docs/knowledge/KnowledgeGovernancePage.d.ts

@@ -0,0 +1 @@
+export declare function KnowledgeGovernancePage(): import("react/jsx-runtime").JSX.Element;

package/dist/components/docs/knowledge/KnowledgeGovernancePage.js

@@ -0,0 +1,23 @@
+// @bun
+var d=Object.defineProperty;var s=(t)=>t;function c(t,o){this[t]=s.bind(null,o)}var p=(t,o)=>{for(var n in o)d(t,n,{get:o[n],enumerable:!0,configurable:!0,set:c.bind(o,n)})};var m=(t,o)=>()=>(t&&(o=t(t=0)),o);import{CodeBlock as r}from"@contractspec/lib.design-system";import i from"@contractspec/lib.ui-link";import{ChevronRight as l}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";function h(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Knowledge mutation governance"}),e("p",{className:"text-muted-foreground",children:"Provider-backed knowledge is not read-only forever. Email sends, Drive permission changes, tombstone handling, replay repairs, and source metadata updates all need explicit governance before they mutate an external system."})]}),a("div",{className:"grid gap-4 md:grid-cols-2",children:[a("div",{className:"card-subtle space-y-2 p-4",children:[e("h2",{className:"font-semibold text-lg",children:"Fail closed"}),e("p",{className:"text-muted-foreground text-sm",children:"Non-dry-run mutations require an idempotency key and audit evidence. Approval-required operations need approval refs. Outbound sends also need an approved send gate."})]}),a("div",{className:"card-subtle space-y-2 p-4",children:[e("h2",{className:"font-semibold text-lg",children:"Leave evidence"}),e("p",{className:"text-muted-foreground text-sm",children:"Every evaluation returns an audit envelope with status, missing evidence, idempotency, approval refs, and the decision timestamp."})]})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Runtime gate"}),e(r,{language:"typescript",filename:"knowledge-governance.ts",code:`const result = await executeGovernedKnowledgeMutation(
+  {
+    operation: "drive.permission.update",
+    sourceId: "src_drive_support",
+    requiresApproval: true,
+    governance: {
+      idempotencyKey: "tenant:drive-permission:123",
+      auditEvidence: { evidenceRef: "audit://drive/permission/123" },
+      approvalRefs: [{ id: "approval-123" }],
+    },
+  },
+  () => drive.updatePermission(input),
+  { audit: (envelope) => auditTrail.write(envelope) },
+);
+
+if (result.status === "blocked") {
+  return result.auditEnvelope.requiredEvidence;
+}`})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"ContractSpec surface"}),a("p",{className:"text-muted-foreground",children:["Use ",e("code",{children:"knowledge.mutation.evaluateGovernance"})," when an app or control-plane workflow needs to expose mutation decisions as a contracted action. It mirrors the runtime helper and gives Connect, ops tools, and review packets one stable contract to reference."]}),e(r,{language:"typescript",filename:"knowledge-operation.ts",code:`import {
+  EvaluateKnowledgeMutationGovernance,
+} from "@contractspec/lib.contracts-spec/knowledge/operations";
+
+registry.register(EvaluateKnowledgeMutationGovernance);`})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[e(i,{href:"/docs/knowledge/sources",className:"btn-ghost",children:"Knowledge sources"}),a(i,{href:"/docs/guides/provider-backed-knowledge",className:"btn-primary",children:["Adoption guide ",e(l,{size:16})]})]})]})}export{h as KnowledgeGovernancePage};

package/dist/components/docs/knowledge/KnowledgeOverviewPage.js

@@ -1,2 +1,2 @@
 // @bun
-var i=Object.defineProperty;var l=(e)=>e;function s(e,a){this[e]=l.bind(null,a)}var c=(e,a)=>{for(var n in a)i(e,n,{get:a[n],enumerable:!0,configurable:!0,set:s.bind(a,n)})};var p=(e,a)=>()=>(e&&(a=e(e=0)),a);import r from"@contractspec/lib.ui-link";import{jsx as t,jsxs as o}from"react/jsx-runtime";var d=[{title:"Categories",body:"Separate canonical truth from operational notes, external material, and ephemeral working context.",href:"/docs/knowledge/categories"},{title:"Spaces",body:"Define the storage and retrieval boundary for each knowledge domain.",href:"/docs/knowledge/spaces"},{title:"Sources",body:"Connect tenant-owned sources explicitly instead of letting context leak in through prompts alone.",href:"/docs/knowledge/sources"},{title:"Examples",body:"See how support, compliance, and product systems consume trusted knowledge at runtime.",href:"/docs/knowledge/examples"}];function g(){return o("div",{className:"space-y-10",children:[o("div",{className:"space-y-3",children:[t("p",{className:"editorial-kicker",children:"Operate"}),t("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Knowledge is part of the runtime, not a sidecar prompt hack."}),t("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"When AI-native systems depend on external context, the context needs the same discipline as the rest of the stack. ContractSpec treats knowledge as typed, bounded, and governable so teams can reason about trust, isolation, and retrieval behavior."})]}),t("section",{className:"editorial-panel space-y-5",children:o("div",{className:"space-y-2",children:[t("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"How knowledge enters the system"}),o("ul",{className:"editorial-list",children:[o("li",{children:[t("span",{className:"editorial-list-marker"}),t("span",{children:"Define the trust category and retrieval expectations first."})]}),o("li",{children:[t("span",{className:"editorial-list-marker"}),t("span",{children:"Bind tenant-owned sources explicitly to those knowledge spaces."})]}),o("li",{children:[t("span",{className:"editorial-list-marker"}),t("span",{children:"Consume knowledge through capabilities and workflows, not through invisible prompt assumptions."})]})]})]})}),t("div",{className:"grid gap-4 md:grid-cols-2",children:d.map((e)=>o(r,{href:e.href,className:"editorial-panel",children:[t("h2",{className:"font-semibold text-xl",children:e.title}),t("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:e.body})]},e.href))})]})}export{g as KnowledgeOverviewPage};
+var i=Object.defineProperty;var r=(e)=>e;function s(e,a){this[e]=r.bind(null,a)}var c=(e,a)=>{for(var n in a)i(e,n,{get:a[n],enumerable:!0,configurable:!0,set:s.bind(a,n)})};var p=(e,a)=>()=>(e&&(a=e(e=0)),a);import l from"@contractspec/lib.ui-link";import{jsx as t,jsxs as o}from"react/jsx-runtime";var d=[{title:"Categories",body:"Separate canonical truth from operational notes, external material, and ephemeral working context.",href:"/docs/knowledge/categories"},{title:"Spaces",body:"Define the storage and retrieval boundary for each knowledge domain.",href:"/docs/knowledge/spaces"},{title:"Sources",body:"Connect tenant-owned sources explicitly instead of letting context leak in through prompts alone.",href:"/docs/knowledge/sources"},{title:"Governance",body:"Gate provider-backed mutations with dry-runs, approvals, idempotency, audit evidence, and outbound-send policy.",href:"/docs/knowledge/governance"},{title:"Provider-backed adoption",body:"Wire Gmail and Google Drive ingestion through checkpointed deltas, tombstones, watches, and Connect evidence.",href:"/docs/guides/provider-backed-knowledge"},{title:"Examples",body:"See how support, compliance, and product systems consume trusted knowledge at runtime.",href:"/docs/knowledge/examples"}];function g(){return o("div",{className:"space-y-10",children:[o("div",{className:"space-y-3",children:[t("p",{className:"editorial-kicker",children:"Operate"}),t("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Knowledge is part of the runtime, not a sidecar prompt hack."}),t("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"When AI-native systems depend on external context, the context needs the same discipline as the rest of the stack. ContractSpec treats knowledge as typed, bounded, and governable so teams can reason about trust, isolation, and retrieval behavior."})]}),t("section",{className:"editorial-panel space-y-5",children:o("div",{className:"space-y-2",children:[t("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"How knowledge enters the system"}),o("ul",{className:"editorial-list",children:[o("li",{children:[t("span",{className:"editorial-list-marker"}),t("span",{children:"Define the trust category and retrieval expectations first."})]}),o("li",{children:[t("span",{className:"editorial-list-marker"}),t("span",{children:"Bind tenant-owned sources explicitly to those knowledge spaces."})]}),o("li",{children:[t("span",{className:"editorial-list-marker"}),t("span",{children:"Consume knowledge through capabilities and workflows, not through invisible prompt assumptions."})]})]})]})}),t("div",{className:"grid gap-4 md:grid-cols-2",children:d.map((e)=>o(l,{href:e.href,className:"editorial-panel",children:[t("h2",{className:"font-semibold text-xl",children:e.title}),t("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:e.body})]},e.href))})]})}export{g as KnowledgeOverviewPage};

package/dist/components/docs/knowledge/KnowledgeSourcesPage.js

@@ -1,5 +1,5 @@
 // @bun
-var E=Object.defineProperty;var F=(z)=>z;function G(z,A){this[z]=F.bind(null,A)}var I=(z,A)=>{for(var B in A)E(z,B,{get:A[B],enumerable:!0,configurable:!0,set:G.bind(A,B)})};var J=(z,A)=>()=>(z&&(A=z(z=0)),A);import D from"@contractspec/lib.ui-link";import{ChevronRight as H}from"lucide-react";import{jsx as q,jsxs as y}from"react/jsx-runtime";function P(){return y("div",{className:"space-y-8",children:[y("div",{className:"space-y-4",children:[q("h1",{className:"font-bold text-4xl",children:"Knowledge Sources"}),y("p",{className:"text-muted-foreground",children:["A ",q("strong",{children:"KnowledgeSourceConfig"})," connects a tenant's data sources (Notion, Gmail, uploads, databases) to knowledge spaces. Each source is synced, chunked, embedded, and indexed according to the space's configuration."]})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"KnowledgeSourceConfig"}),q("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:q("pre",{children:`type KnowledgeSourceConfig = {
+var E=Object.defineProperty;var F=(z)=>z;function G(z,A){this[z]=F.bind(null,A)}var I=(z,A)=>{for(var D in A)E(z,D,{get:A[D],enumerable:!0,configurable:!0,set:G.bind(A,D)})};var J=(z,A)=>()=>(z&&(A=z(z=0)),A);import B from"@contractspec/lib.ui-link";import{ChevronRight as H}from"lucide-react";import{jsx as q,jsxs as y}from"react/jsx-runtime";function P(){return y("div",{className:"space-y-8",children:[y("div",{className:"space-y-4",children:[q("h1",{className:"font-bold text-4xl",children:"Knowledge Sources"}),y("p",{className:"text-muted-foreground",children:["A ",q("strong",{children:"KnowledgeSourceConfig"})," connects a tenant's data sources (Notion, Gmail, uploads, databases) to knowledge spaces. Each source is synced, chunked, embedded, and indexed according to the space's configuration."]})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"KnowledgeSourceConfig"}),q("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:q("pre",{children:`type KnowledgeSourceConfig = {
   id: string;
   tenantId: string;
   spaceId: string;
@@ -69,4 +69,13 @@ var E=Object.defineProperty;var F=(z)=>z;function G(z,A){this[z]=F.bind(null,A)}
       syncPolicy: { manual: true }
     }
   ]
-}`})})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Processing pipeline"}),q("p",{className:"text-muted-foreground",children:"When a source is synced, ContractSpec processes it through several stages:"}),y("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground",children:[y("li",{children:[q("strong",{children:"Fetch"})," - Retrieve content from source (API, database, file)"]}),y("li",{children:[q("strong",{children:"Parse"})," - Extract text from documents (PDF, Word, HTML)"]}),y("li",{children:[q("strong",{children:"Chunk"})," - Split into semantic chunks (paragraphs, sections)"]}),y("li",{children:[q("strong",{children:"Embed"})," - Generate vector embeddings (OpenAI, Cohere)"]}),y("li",{children:[q("strong",{children:"Index"})," - Store in vector database (Qdrant) or search engine"]}),y("li",{children:[q("strong",{children:"Audit"})," - Log sync operation and results"]})]})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Best practices"}),y("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[q("li",{children:"Use webhooks for real-time sources (Notion, Gmail) to minimize latency"}),q("li",{children:"Set appropriate sync intervals - hourly for active docs, daily for stable content"}),q("li",{children:"Monitor sync failures and set up alerts for critical sources"}),q("li",{children:"Test sources in sandbox before enabling in production"}),q("li",{children:"Document the purpose and ownership of each source for your team"}),q("li",{children:"Use manual sync for sensitive or infrequently updated content"})]})]}),y("div",{className:"flex items-center gap-4 pt-4",children:[q(D,{href:"/docs/knowledge/spaces",className:"btn-ghost",children:"Previous: Spaces"}),y(D,{href:"/docs/knowledge/examples",className:"btn-primary",children:["Examples ",q(H,{size:16})]})]})]})}export{P as KnowledgeSourcesPage};
+}`})})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Processing pipeline"}),q("p",{className:"text-muted-foreground",children:"When a source is synced, ContractSpec processes it through several stages:"}),y("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground",children:[y("li",{children:[q("strong",{children:"Fetch"})," - Retrieve content from source (API, database, file)"]}),y("li",{children:[q("strong",{children:"Parse"})," - Extract text from documents (PDF, Word, HTML)"]}),y("li",{children:[q("strong",{children:"Chunk"})," - Split into semantic chunks (paragraphs, sections)"]}),y("li",{children:[q("strong",{children:"Embed"})," - Generate vector embeddings (OpenAI, Cohere)"]}),y("li",{children:[q("strong",{children:"Index"})," - Store in vector database (Qdrant) or search engine"]}),y("li",{children:[q("strong",{children:"Audit"})," - Log sync operation and results"]})]})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Provider delta state"}),y("p",{className:"text-muted-foreground",children:["Runtime-backed providers should persist a"," ",q("strong",{children:"ProviderDeltaSyncState"})," per source before sync work is acknowledged. Gmail and Google Drive adapters use that checkpoint to resume cursors, renew watches, skip tombstones, dedupe webhook events, and replay from a known point after retries."]}),q("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:q("pre",{children:`type ProviderDeltaSyncState = {
+  lease?: { holder: string; expiresAt: string; renewalWindowMs: number };
+  cursor?: { cursor?: string; watermark?: string; watermarkVersion?: string };
+  webhookChannel?: { channelId: string; resourceId?: string; expiresAt?: string };
+  providerEventId?: string;
+  dedupeKey?: string;
+  idempotencyKey?: string;
+  replayCheckpoint?: { checkpointId: string; sequence?: string | number };
+  tombstone?: { deletedAt: string; reason?: string };
+};`})}),y("div",{className:"flex flex-wrap gap-3",children:[q(B,{href:"/docs/integrations/gmail",className:"btn-ghost",children:"Gmail integration"}),q(B,{href:"/docs/integrations/google-drive",className:"btn-ghost",children:"Google Drive integration"}),q(B,{href:"/docs/guides/provider-backed-knowledge",className:"btn-ghost",children:"Provider-backed guide"})]})]}),y("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Best practices"}),y("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[q("li",{children:"Use webhooks for real-time sources (Notion, Gmail) to minimize latency"}),q("li",{children:"Set appropriate sync intervals - hourly for active docs, daily for stable content"}),q("li",{children:"Monitor sync failures and set up alerts for critical sources"}),q("li",{children:"Test sources in sandbox before enabling in production"}),q("li",{children:"Document the purpose and ownership of each source for your team"}),q("li",{children:"Use manual sync for sensitive or infrequently updated content"}),y("li",{children:["Run external mutations through"," ",q(B,{href:"/docs/knowledge/governance",className:"text-primary",children:"knowledge mutation governance"})," ","before sending email, changing Drive permissions, or repairing replay state."]})]})]}),y("div",{className:"flex items-center gap-4 pt-4",children:[q(B,{href:"/docs/knowledge/spaces",className:"btn-ghost",children:"Previous: Spaces"}),y(B,{href:"/docs/knowledge/examples",className:"btn-primary",children:["Examples ",q(H,{size:16})]})]})]})}export{P as KnowledgeSourcesPage};

package/dist/components/docs/knowledge/index.d.ts

@@ -1,5 +1,6 @@
 export { KnowledgeCategoriesPage } from './KnowledgeCategoriesPage';
 export { KnowledgeExamplesPage } from './KnowledgeExamplesPage';
+export { KnowledgeGovernancePage } from './KnowledgeGovernancePage';
 export { KnowledgeOverviewPage } from './KnowledgeOverviewPage';
 export { KnowledgeSourcesPage } from './KnowledgeSourcesPage';
 export { KnowledgeSpacesPage } from './KnowledgeSpacesPage';

package/dist/components/docs/knowledge/index.js

@@ -1,9 +1,9 @@
 // @bun
-var v=Object.defineProperty;var N=(n)=>n;function u(n,p){this[n]=N.bind(null,p)}var I=(n,p)=>{for(var c in p)v(n,c,{get:p[c],enumerable:!0,configurable:!0,set:u.bind(p,c)})};var S=(n,p)=>()=>(n&&(p=n(n=0)),p);import f from"@contractspec/lib.ui-link";import{ChevronRight as k}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";function b(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Knowledge Categories"}),e("p",{className:"text-muted-foreground",children:"ContractSpec classifies knowledge into four categories based on trust level, source authority, and intended use. This classification determines how knowledge can be used in workflows, policy decisions, and agent responses."})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"The four categories"}),e("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:e("pre",{children:`type KnowledgeCategory =
+var k=Object.defineProperty;var K=(l)=>l;function P(l,v){this[l]=K.bind(null,v)}var W=(l,v)=>{for(var f in v)k(l,f,{get:v[f],enumerable:!0,configurable:!0,set:P.bind(v,f)})};var _=(l,v)=>()=>(l&&(v=l(l=0)),v);import h from"@contractspec/lib.ui-link";import{ChevronRight as G}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";function E(){return t("div",{className:"space-y-8",children:[t("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Knowledge Categories"}),e("p",{className:"text-muted-foreground",children:"ContractSpec classifies knowledge into four categories based on trust level, source authority, and intended use. This classification determines how knowledge can be used in workflows, policy decisions, and agent responses."})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"The four categories"}),e("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:e("pre",{children:`type KnowledgeCategory =
   | "canonical"   // Internal ground truth
   | "operational" // Internal operational docs
   | "external"    // Third-party reference
-  | "ephemeral";  // Temporary context`})})]}),a("div",{className:"space-y-6",children:[a("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"1. Canonical"}),a("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," Highest - Authoritative ground truth"]}),a("div",{className:"space-y-3",children:[a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Official product specifications and schemas"}),e("li",{children:"Company policies and procedures"}),e("li",{children:"Legal terms and compliance requirements"}),e("li",{children:"Pricing rules and business logic"}),e("li",{children:"Data classification and security policies"})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[a("li",{children:[e("strong",{children:"Policy decisions"})," - Can drive PDP decisions"]}),a("li",{children:[e("strong",{children:"Validation"})," - Used to validate user inputs and operations"]}),a("li",{children:[e("strong",{children:"Code generation"})," - Source of truth for generated code"]}),a("li",{children:[e("strong",{children:"Compliance"})," - Reference for audit and regulatory checks"]})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// Product Canon space
+  | "ephemeral";  // Temporary context`})})]}),t("div",{className:"space-y-6",children:[t("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"1. Canonical"}),t("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," Highest - Authoritative ground truth"]}),t("div",{className:"space-y-3",children:[t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Official product specifications and schemas"}),e("li",{children:"Company policies and procedures"}),e("li",{children:"Legal terms and compliance requirements"}),e("li",{children:"Pricing rules and business logic"}),e("li",{children:"Data classification and security policies"})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:[e("strong",{children:"Policy decisions"})," - Can drive PDP decisions"]}),t("li",{children:[e("strong",{children:"Validation"})," - Used to validate user inputs and operations"]}),t("li",{children:[e("strong",{children:"Code generation"})," - Source of truth for generated code"]}),t("li",{children:[e("strong",{children:"Compliance"})," - Reference for audit and regulatory checks"]})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// Product Canon space
 {
   id: "product-canon",
   category: "canonical",
@@ -23,7 +23,7 @@ var v=Object.defineProperty;var N=(n)=>n;function u(n,p){this[n]=N.bind(null,p)}
     "access-policies.rego",
     "compliance-requirements.md"
   ]
-}`})})]}),e("div",{className:"card-subtle border-violet-500/30 bg-violet-500/10 p-3",children:a("p",{className:"text-sm text-violet-300",children:[e("strong",{children:"\u26A0\uFE0F Important:"})," Canonical knowledge is immutable once indexed. Changes require re-sync and versioning."]})})]})]}),a("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"2. Operational"}),a("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," High - Internal but not authoritative"]}),a("div",{className:"space-y-3",children:[a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Support ticket history and resolutions"}),e("li",{children:"Internal runbooks and playbooks"}),e("li",{children:"Sales materials and customer communications"}),e("li",{children:"Product management docs and roadmaps"}),e("li",{children:"Team wikis and knowledge bases"})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[a("li",{children:[e("strong",{children:"Context"})," - Provides helpful context for decisions"]}),a("li",{children:[e("strong",{children:"Suggestions"})," - Informs recommendations, not requirements"]}),a("li",{children:[e("strong",{children:"Learning"})," - Helps agents learn from past interactions"]}),a("li",{children:[e("strong",{children:"Troubleshooting"})," - Guides problem-solving workflows"]})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// Support History space
+}`})})]}),e("div",{className:"card-subtle border-violet-500/30 bg-violet-500/10 p-3",children:t("p",{className:"text-sm text-violet-300",children:[e("strong",{children:"\u26A0\uFE0F Important:"})," Canonical knowledge is immutable once indexed. Changes require re-sync and versioning."]})})]})]}),t("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"2. Operational"}),t("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," High - Internal but not authoritative"]}),t("div",{className:"space-y-3",children:[t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Support ticket history and resolutions"}),e("li",{children:"Internal runbooks and playbooks"}),e("li",{children:"Sales materials and customer communications"}),e("li",{children:"Product management docs and roadmaps"}),e("li",{children:"Team wikis and knowledge bases"})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:[e("strong",{children:"Context"})," - Provides helpful context for decisions"]}),t("li",{children:[e("strong",{children:"Suggestions"})," - Informs recommendations, not requirements"]}),t("li",{children:[e("strong",{children:"Learning"})," - Helps agents learn from past interactions"]}),t("li",{children:[e("strong",{children:"Troubleshooting"})," - Guides problem-solving workflows"]})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// Support History space
 {
   id: "support-history",
   category: "operational",
@@ -43,7 +43,7 @@ var v=Object.defineProperty;var N=(n)=>n;function u(n,p){this[n]=N.bind(null,p)}
     "confluence:product-docs",
     "google-drive:runbooks"
   ]
-}`})})]})]})]}),a("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"3. External"}),a("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," Medium - Reference only"]}),a("div",{className:"space-y-3",children:[a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Third-party integration documentation (Stripe, Twilio)"}),e("li",{children:"Regulatory and compliance documents"}),e("li",{children:"Industry standards and best practices"}),e("li",{children:"Public API documentation"}),e("li",{children:"External knowledge bases"})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[a("li",{children:[e("strong",{children:"Reference"})," - Consulted but not authoritative"]}),a("li",{children:[e("strong",{children:"Integration help"})," - Guides external API usage"]}),a("li",{children:[e("strong",{children:"Compliance context"})," - Provides regulatory background"]}),a("li",{children:[e("strong",{children:"Never for policy"})," - Cannot drive policy decisions"]})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// External Provider Docs space
+}`})})]})]})]}),t("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"3. External"}),t("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," Medium - Reference only"]}),t("div",{className:"space-y-3",children:[t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Third-party integration documentation (Stripe, Twilio)"}),e("li",{children:"Regulatory and compliance documents"}),e("li",{children:"Industry standards and best practices"}),e("li",{children:"Public API documentation"}),e("li",{children:"External knowledge bases"})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:[e("strong",{children:"Reference"})," - Consulted but not authoritative"]}),t("li",{children:[e("strong",{children:"Integration help"})," - Guides external API usage"]}),t("li",{children:[e("strong",{children:"Compliance context"})," - Provides regulatory background"]}),t("li",{children:[e("strong",{children:"Never for policy"})," - Cannot drive policy decisions"]})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// External Provider Docs space
 {
   id: "provider-docs",
   category: "external",
@@ -63,7 +63,7 @@ var v=Object.defineProperty;var N=(n)=>n;function u(n,p){this[n]=N.bind(null,p)}
     "url:https://www.hhs.gov/hipaa",
     "pdf:SOC2-requirements.pdf"
   ]
-}`})})]}),e("div",{className:"card-subtle border-amber-500/30 bg-amber-500/10 p-3",children:a("p",{className:"text-amber-300 text-sm",children:[e("strong",{children:"\u26A0\uFE0F Note:"}),` External knowledge should be clearly marked in agent responses as "according to [source]" to indicate it's not internal authority.`]})})]})]}),a("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"4. Ephemeral"}),a("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," Low - Temporary context only"]}),a("div",{className:"space-y-3",children:[a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Agent conversation history and scratchpads"}),e("li",{children:"Session-specific context and state"}),e("li",{children:"Draft documents and work-in-progress"}),e("li",{children:"Temporary calculations and intermediate results"}),e("li",{children:"User-provided context for current task"})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),a("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[a("li",{children:[e("strong",{children:"Session continuity"})," - Maintains conversation context"]}),a("li",{children:[e("strong",{children:"Working memory"})," - Stores intermediate results"]}),a("li",{children:[e("strong",{children:"Never persisted long-term"})," - Auto-purged after session"]}),a("li",{children:[e("strong",{children:"Never for decisions"})," - Cannot influence policy or validation"]})]})]}),a("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// Agent Scratchpad space
+}`})})]}),e("div",{className:"card-subtle border-amber-500/30 bg-amber-500/10 p-3",children:t("p",{className:"text-amber-300 text-sm",children:[e("strong",{children:"\u26A0\uFE0F Note:"}),` External knowledge should be clearly marked in agent responses as "according to [source]" to indicate it's not internal authority.`]})})]})]}),t("div",{className:"space-y-4",children:[e("h3",{className:"font-semibold text-xl",children:"4. Ephemeral"}),t("p",{className:"text-muted-foreground",children:[e("strong",{children:"Trust level:"})," Low - Temporary context only"]}),t("div",{className:"space-y-3",children:[t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"What it contains:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"Agent conversation history and scratchpads"}),e("li",{children:"Session-specific context and state"}),e("li",{children:"Draft documents and work-in-progress"}),e("li",{children:"Temporary calculations and intermediate results"}),e("li",{children:"User-provided context for current task"})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"How it's used:"}),t("ul",{className:"ml-4 list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:[e("strong",{children:"Session continuity"})," - Maintains conversation context"]}),t("li",{children:[e("strong",{children:"Working memory"})," - Stores intermediate results"]}),t("li",{children:[e("strong",{children:"Never persisted long-term"})," - Auto-purged after session"]}),t("li",{children:[e("strong",{children:"Never for decisions"})," - Cannot influence policy or validation"]})]})]}),t("div",{children:[e("h4",{className:"mb-2 font-semibold text-sm",children:"Examples:"}),e("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:e("pre",{children:`// Agent Scratchpad space
 {
   id: "agent-scratchpad",
   category: "ephemeral",
@@ -83,7 +83,7 @@ var v=Object.defineProperty;var N=(n)=>n;function u(n,p){this[n]=N.bind(null,p)}
     "session:user-uploads",
     "session:form-drafts"
   ]
-}`})})]}),e("div",{className:"card-subtle border-red-500/30 bg-red-500/10 p-3",children:a("p",{className:"text-red-300 text-sm",children:[e("strong",{children:"\u26A0\uFE0F Critical:"})," Ephemeral knowledge is never used for policy decisions, compliance checks, or any authoritative purpose."]})})]})]})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Category comparison"}),e("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:a("table",{className:"w-full text-left text-sm",children:[e("thead",{className:"bg-card/50",children:a("tr",{className:"border-border/50 border-b",children:[e("th",{className:"px-4 py-3 font-semibold",children:"Feature"}),e("th",{className:"px-4 py-3 font-semibold",children:"Canonical"}),e("th",{className:"px-4 py-3 font-semibold",children:"Operational"}),e("th",{className:"px-4 py-3 font-semibold",children:"External"}),e("th",{className:"px-4 py-3 font-semibold",children:"Ephemeral"})]})}),a("tbody",{className:"divide-y divide-border/50",children:[a("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Trust Level"}),e("td",{className:"px-4 py-3",children:"Highest"}),e("td",{className:"px-4 py-3",children:"High"}),e("td",{className:"px-4 py-3",children:"Medium"}),e("td",{className:"px-4 py-3",children:"Low"})]}),a("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Policy Impact"}),e("td",{className:"px-4 py-3",children:"\u2705 Can drive decisions"}),e("td",{className:"px-4 py-3",children:"\u26A0\uFE0F Can inform"}),e("td",{className:"px-4 py-3",children:"\u274C Reference only"}),e("td",{className:"px-4 py-3",children:"\u274C Never used"})]}),a("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Mutability"}),e("td",{className:"px-4 py-3",children:"Immutable"}),e("td",{className:"px-4 py-3",children:"Mutable"}),e("td",{className:"px-4 py-3",children:"Mutable"}),e("td",{className:"px-4 py-3",children:"Temporary"})]}),a("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Retention"}),e("td",{className:"px-4 py-3",children:"Permanent"}),e("td",{className:"px-4 py-3",children:"Long-term"}),e("td",{className:"px-4 py-3",children:"Long-term"}),e("td",{className:"px-4 py-3",children:"Short-term"})]}),a("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Audit Level"}),e("td",{className:"px-4 py-3",children:"Full audit"}),e("td",{className:"px-4 py-3",children:"Full audit"}),e("td",{className:"px-4 py-3",children:"Basic audit"}),e("td",{className:"px-4 py-3",children:"Minimal audit"})]})]})]})})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Use canonical for anything that affects policy, pricing, or compliance"}),e("li",{children:"Use operational for context that helps but doesn't dictate decisions"}),e("li",{children:"Use external for reference material that's helpful but not authoritative"}),e("li",{children:"Use ephemeral for temporary working memory that shouldn't persist"}),e("li",{children:"Never mix categories in a single knowledge space - keep them separate"}),e("li",{children:"Document the category and purpose of each knowledge space clearly"})]})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[e(f,{href:"/docs/knowledge",className:"btn-ghost",children:"Back to Knowledge"}),a(f,{href:"/docs/knowledge/spaces",className:"btn-primary",children:["Knowledge Spaces ",e(k,{size:16})]})]})]})}import h from"@contractspec/lib.ui-link";import{jsx as d,jsxs as i}from"react/jsx-runtime";function P(){return i("div",{className:"space-y-8",children:[i("div",{className:"space-y-4",children:[d("h1",{className:"font-bold text-4xl",children:"Knowledge Examples"}),d("p",{className:"text-muted-foreground",children:"Real-world examples of how different applications use knowledge spaces to power intelligent workflows and agents."})]}),i("div",{className:"space-y-6",children:[i("div",{className:"space-y-4",children:[d("h2",{className:"font-bold text-2xl",children:"Example 1: ArtisanOS Support Agent"}),i("p",{className:"text-muted-foreground",children:[d("strong",{children:"Context:"})," ArtisanOS needs a support agent that can answer product questions using official documentation and learn from past support tickets."]}),d("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:d("pre",{children:`// Knowledge spaces
+}`})})]}),e("div",{className:"card-subtle border-red-500/30 bg-red-500/10 p-3",children:t("p",{className:"text-red-300 text-sm",children:[e("strong",{children:"\u26A0\uFE0F Critical:"})," Ephemeral knowledge is never used for policy decisions, compliance checks, or any authoritative purpose."]})})]})]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Category comparison"}),e("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:t("table",{className:"w-full text-left text-sm",children:[e("thead",{className:"bg-card/50",children:t("tr",{className:"border-border/50 border-b",children:[e("th",{className:"px-4 py-3 font-semibold",children:"Feature"}),e("th",{className:"px-4 py-3 font-semibold",children:"Canonical"}),e("th",{className:"px-4 py-3 font-semibold",children:"Operational"}),e("th",{className:"px-4 py-3 font-semibold",children:"External"}),e("th",{className:"px-4 py-3 font-semibold",children:"Ephemeral"})]})}),t("tbody",{className:"divide-y divide-border/50",children:[t("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Trust Level"}),e("td",{className:"px-4 py-3",children:"Highest"}),e("td",{className:"px-4 py-3",children:"High"}),e("td",{className:"px-4 py-3",children:"Medium"}),e("td",{className:"px-4 py-3",children:"Low"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Policy Impact"}),e("td",{className:"px-4 py-3",children:"\u2705 Can drive decisions"}),e("td",{className:"px-4 py-3",children:"\u26A0\uFE0F Can inform"}),e("td",{className:"px-4 py-3",children:"\u274C Reference only"}),e("td",{className:"px-4 py-3",children:"\u274C Never used"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Mutability"}),e("td",{className:"px-4 py-3",children:"Immutable"}),e("td",{className:"px-4 py-3",children:"Mutable"}),e("td",{className:"px-4 py-3",children:"Mutable"}),e("td",{className:"px-4 py-3",children:"Temporary"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Retention"}),e("td",{className:"px-4 py-3",children:"Permanent"}),e("td",{className:"px-4 py-3",children:"Long-term"}),e("td",{className:"px-4 py-3",children:"Long-term"}),e("td",{className:"px-4 py-3",children:"Short-term"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-semibold",children:"Audit Level"}),e("td",{className:"px-4 py-3",children:"Full audit"}),e("td",{className:"px-4 py-3",children:"Full audit"}),e("td",{className:"px-4 py-3",children:"Basic audit"}),e("td",{className:"px-4 py-3",children:"Minimal audit"})]})]})]})})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),t("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Use canonical for anything that affects policy, pricing, or compliance"}),e("li",{children:"Use operational for context that helps but doesn't dictate decisions"}),e("li",{children:"Use external for reference material that's helpful but not authoritative"}),e("li",{children:"Use ephemeral for temporary working memory that shouldn't persist"}),e("li",{children:"Never mix categories in a single knowledge space - keep them separate"}),e("li",{children:"Document the category and purpose of each knowledge space clearly"})]})]}),t("div",{className:"flex items-center gap-4 pt-4",children:[e(h,{href:"/docs/knowledge",className:"btn-ghost",children:"Back to Knowledge"}),t(h,{href:"/docs/knowledge/spaces",className:"btn-primary",children:["Knowledge Spaces ",e(G,{size:16})]})]})]})}import w from"@contractspec/lib.ui-link";import{jsx as d,jsxs as i}from"react/jsx-runtime";function q(){return i("div",{className:"space-y-8",children:[i("div",{className:"space-y-4",children:[d("h1",{className:"font-bold text-4xl",children:"Knowledge Examples"}),d("p",{className:"text-muted-foreground",children:"Real-world examples of how different applications use knowledge spaces to power intelligent workflows and agents."})]}),i("div",{className:"space-y-6",children:[i("div",{className:"space-y-4",children:[d("h2",{className:"font-bold text-2xl",children:"Example 1: ArtisanOS Support Agent"}),i("p",{className:"text-muted-foreground",children:[d("strong",{children:"Context:"})," ArtisanOS needs a support agent that can answer product questions using official documentation and learn from past support tickets."]}),d("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:d("pre",{children:`// Knowledge spaces
 knowledgeSpaces: [
   {
     id: "product-canon",
@@ -251,7 +251,28 @@ steps:
             Question: \${input.question}
             Internal: \${steps.search-internal-guides.output.results}
             Stripe: \${steps.search-stripe-docs.output.results}
-            Past: \${steps.search-past-questions.output.results}`})})]})]}),i("div",{className:"space-y-4",children:[d("h2",{className:"font-bold text-2xl",children:"Key patterns"}),i("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[i("li",{children:[d("strong",{children:"Canonical first"})," - Always search canonical spaces before operational or external"]}),i("li",{children:[d("strong",{children:"Category-aware prompts"})," - Tell the LLM which sources are authoritative vs reference"]}),i("li",{children:[d("strong",{children:"Multi-space queries"})," - Combine results from multiple spaces for richer context"]}),i("li",{children:[d("strong",{children:"Limit results"})," - Use appropriate limits (3-5) to avoid token overflow"]}),i("li",{children:[d("strong",{children:"Audit everything"})," - Log all knowledge queries for debugging and compliance"]})]})]}),i("div",{className:"flex items-center gap-4 pt-4",children:[d(h,{href:"/docs/knowledge/sources",className:"btn-ghost",children:"Previous: Sources"}),d(h,{href:"/docs/architecture/knowledge-binding",className:"btn-ghost",children:"Knowledge Binding"})]})]})}import K from"@contractspec/lib.ui-link";import{jsx as m,jsxs as g}from"react/jsx-runtime";var O=[{title:"Categories",body:"Separate canonical truth from operational notes, external material, and ephemeral working context.",href:"/docs/knowledge/categories"},{title:"Spaces",body:"Define the storage and retrieval boundary for each knowledge domain.",href:"/docs/knowledge/spaces"},{title:"Sources",body:"Connect tenant-owned sources explicitly instead of letting context leak in through prompts alone.",href:"/docs/knowledge/sources"},{title:"Examples",body:"See how support, compliance, and product systems consume trusted knowledge at runtime.",href:"/docs/knowledge/examples"}];function D(){return g("div",{className:"space-y-10",children:[g("div",{className:"space-y-3",children:[m("p",{className:"editorial-kicker",children:"Operate"}),m("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Knowledge is part of the runtime, not a sidecar prompt hack."}),m("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"When AI-native systems depend on external context, the context needs the same discipline as the rest of the stack. ContractSpec treats knowledge as typed, bounded, and governable so teams can reason about trust, isolation, and retrieval behavior."})]}),m("section",{className:"editorial-panel space-y-5",children:g("div",{className:"space-y-2",children:[m("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"How knowledge enters the system"}),g("ul",{className:"editorial-list",children:[g("li",{children:[m("span",{className:"editorial-list-marker"}),m("span",{children:"Define the trust category and retrieval expectations first."})]}),g("li",{children:[m("span",{className:"editorial-list-marker"}),m("span",{children:"Bind tenant-owned sources explicitly to those knowledge spaces."})]}),g("li",{children:[m("span",{className:"editorial-list-marker"}),m("span",{children:"Consume knowledge through capabilities and workflows, not through invisible prompt assumptions."})]})]})]})}),m("div",{className:"grid gap-4 md:grid-cols-2",children:O.map((n)=>g(K,{href:n.href,className:"editorial-panel",children:[m("h2",{className:"font-semibold text-xl",children:n.title}),m("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:n.body})]},n.href))})]})}import w from"@contractspec/lib.ui-link";import{ChevronRight as E}from"lucide-react";import{jsx as t,jsxs as l}from"react/jsx-runtime";function A(){return l("div",{className:"space-y-8",children:[l("div",{className:"space-y-4",children:[t("h1",{className:"font-bold text-4xl",children:"Knowledge Sources"}),l("p",{className:"text-muted-foreground",children:["A ",t("strong",{children:"KnowledgeSourceConfig"})," connects a tenant's data sources (Notion, Gmail, uploads, databases) to knowledge spaces. Each source is synced, chunked, embedded, and indexed according to the space's configuration."]})]}),l("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"KnowledgeSourceConfig"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`type KnowledgeSourceConfig = {
+            Past: \${steps.search-past-questions.output.results}`})})]})]}),i("div",{className:"space-y-4",children:[d("h2",{className:"font-bold text-2xl",children:"Key patterns"}),i("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[i("li",{children:[d("strong",{children:"Canonical first"})," - Always search canonical spaces before operational or external"]}),i("li",{children:[d("strong",{children:"Category-aware prompts"})," - Tell the LLM which sources are authoritative vs reference"]}),i("li",{children:[d("strong",{children:"Multi-space queries"})," - Combine results from multiple spaces for richer context"]}),i("li",{children:[d("strong",{children:"Limit results"})," - Use appropriate limits (3-5) to avoid token overflow"]}),i("li",{children:[d("strong",{children:"Audit everything"})," - Log all knowledge queries for debugging and compliance"]})]})]}),i("div",{className:"flex items-center gap-4 pt-4",children:[d(w,{href:"/docs/knowledge/sources",className:"btn-ghost",children:"Previous: Sources"}),d(w,{href:"/docs/architecture/knowledge-binding",className:"btn-ghost",children:"Knowledge Binding"})]})]})}import{CodeBlock as y}from"@contractspec/lib.design-system";import N from"@contractspec/lib.ui-link";import{ChevronRight as A}from"lucide-react";import{jsx as c,jsxs as m}from"react/jsx-runtime";function D(){return m("div",{className:"space-y-8",children:[m("div",{className:"space-y-4",children:[c("h1",{className:"font-bold text-4xl",children:"Knowledge mutation governance"}),c("p",{className:"text-muted-foreground",children:"Provider-backed knowledge is not read-only forever. Email sends, Drive permission changes, tombstone handling, replay repairs, and source metadata updates all need explicit governance before they mutate an external system."})]}),m("div",{className:"grid gap-4 md:grid-cols-2",children:[m("div",{className:"card-subtle space-y-2 p-4",children:[c("h2",{className:"font-semibold text-lg",children:"Fail closed"}),c("p",{className:"text-muted-foreground text-sm",children:"Non-dry-run mutations require an idempotency key and audit evidence. Approval-required operations need approval refs. Outbound sends also need an approved send gate."})]}),m("div",{className:"card-subtle space-y-2 p-4",children:[c("h2",{className:"font-semibold text-lg",children:"Leave evidence"}),c("p",{className:"text-muted-foreground text-sm",children:"Every evaluation returns an audit envelope with status, missing evidence, idempotency, approval refs, and the decision timestamp."})]})]}),m("div",{className:"space-y-4",children:[c("h2",{className:"font-bold text-2xl",children:"Runtime gate"}),c(y,{language:"typescript",filename:"knowledge-governance.ts",code:`const result = await executeGovernedKnowledgeMutation(
+  {
+    operation: "drive.permission.update",
+    sourceId: "src_drive_support",
+    requiresApproval: true,
+    governance: {
+      idempotencyKey: "tenant:drive-permission:123",
+      auditEvidence: { evidenceRef: "audit://drive/permission/123" },
+      approvalRefs: [{ id: "approval-123" }],
+    },
+  },
+  () => drive.updatePermission(input),
+  { audit: (envelope) => auditTrail.write(envelope) },
+);
+
+if (result.status === "blocked") {
+  return result.auditEnvelope.requiredEvidence;
+}`})]}),m("div",{className:"space-y-4",children:[c("h2",{className:"font-bold text-2xl",children:"ContractSpec surface"}),m("p",{className:"text-muted-foreground",children:["Use ",c("code",{children:"knowledge.mutation.evaluateGovernance"})," when an app or control-plane workflow needs to expose mutation decisions as a contracted action. It mirrors the runtime helper and gives Connect, ops tools, and review packets one stable contract to reference."]}),c(y,{language:"typescript",filename:"knowledge-operation.ts",code:`import {
+  EvaluateKnowledgeMutationGovernance,
+} from "@contractspec/lib.contracts-spec/knowledge/operations";
+
+registry.register(EvaluateKnowledgeMutationGovernance);`})]}),m("div",{className:"flex items-center gap-4 pt-4",children:[c(N,{href:"/docs/knowledge/sources",className:"btn-ghost",children:"Knowledge sources"}),m(N,{href:"/docs/guides/provider-backed-knowledge",className:"btn-primary",children:["Adoption guide ",c(A,{size:16})]})]})]})}import O from"@contractspec/lib.ui-link";import{jsx as p,jsxs as g}from"react/jsx-runtime";var C=[{title:"Categories",body:"Separate canonical truth from operational notes, external material, and ephemeral working context.",href:"/docs/knowledge/categories"},{title:"Spaces",body:"Define the storage and retrieval boundary for each knowledge domain.",href:"/docs/knowledge/spaces"},{title:"Sources",body:"Connect tenant-owned sources explicitly instead of letting context leak in through prompts alone.",href:"/docs/knowledge/sources"},{title:"Governance",body:"Gate provider-backed mutations with dry-runs, approvals, idempotency, audit evidence, and outbound-send policy.",href:"/docs/knowledge/governance"},{title:"Provider-backed adoption",body:"Wire Gmail and Google Drive ingestion through checkpointed deltas, tombstones, watches, and Connect evidence.",href:"/docs/guides/provider-backed-knowledge"},{title:"Examples",body:"See how support, compliance, and product systems consume trusted knowledge at runtime.",href:"/docs/knowledge/examples"}];function I(){return g("div",{className:"space-y-10",children:[g("div",{className:"space-y-3",children:[p("p",{className:"editorial-kicker",children:"Operate"}),p("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Knowledge is part of the runtime, not a sidecar prompt hack."}),p("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"When AI-native systems depend on external context, the context needs the same discipline as the rest of the stack. ContractSpec treats knowledge as typed, bounded, and governable so teams can reason about trust, isolation, and retrieval behavior."})]}),p("section",{className:"editorial-panel space-y-5",children:g("div",{className:"space-y-2",children:[p("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"How knowledge enters the system"}),g("ul",{className:"editorial-list",children:[g("li",{children:[p("span",{className:"editorial-list-marker"}),p("span",{children:"Define the trust category and retrieval expectations first."})]}),g("li",{children:[p("span",{className:"editorial-list-marker"}),p("span",{children:"Bind tenant-owned sources explicitly to those knowledge spaces."})]}),g("li",{children:[p("span",{className:"editorial-list-marker"}),p("span",{children:"Consume knowledge through capabilities and workflows, not through invisible prompt assumptions."})]})]})]})}),p("div",{className:"grid gap-4 md:grid-cols-2",children:C.map((l)=>g(O,{href:l.href,className:"editorial-panel",children:[p("h2",{className:"font-semibold text-xl",children:l.title}),p("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:l.body})]},l.href))})]})}import u from"@contractspec/lib.ui-link";import{ChevronRight as M}from"lucide-react";import{jsx as a,jsxs as r}from"react/jsx-runtime";function B(){return r("div",{className:"space-y-8",children:[r("div",{className:"space-y-4",children:[a("h1",{className:"font-bold text-4xl",children:"Knowledge Sources"}),r("p",{className:"text-muted-foreground",children:["A ",a("strong",{children:"KnowledgeSourceConfig"})," connects a tenant's data sources (Notion, Gmail, uploads, databases) to knowledge spaces. Each source is synced, chunked, embedded, and indexed according to the space's configuration."]})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"KnowledgeSourceConfig"}),a("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:a("pre",{children:`type KnowledgeSourceConfig = {
   id: string;
   tenantId: string;
   spaceId: string;
@@ -278,27 +299,27 @@ steps:
   metadata?: Record<string, unknown>;
   createdAt: string;
   updatedAt: string;
-};`})})]}),l("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Source types"}),l("div",{className:"space-y-6",children:[l("div",{className:"card-subtle p-4",children:[t("h3",{className:"mb-2 font-semibold text-lg",children:"Uploaded Documents"}),t("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:t("pre",{children:`{
+};`})})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Source types"}),r("div",{className:"space-y-6",children:[r("div",{className:"card-subtle p-4",children:[a("h3",{className:"mb-2 font-semibold text-lg",children:"Uploaded Documents"}),a("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:a("pre",{children:`{
   kind: "uploaded-document",
   location: "s3://bucket/tenant-123/docs/product-spec.pdf",
   syncPolicy: { manual: true }
-}`})}),t("p",{className:"mt-2 text-muted-foreground text-sm",children:"PDFs, Word docs, presentations uploaded by users"})]}),l("div",{className:"card-subtle p-4",children:[t("h3",{className:"mb-2 font-semibold text-lg",children:"Notion"}),t("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:t("pre",{children:`{
+}`})}),a("p",{className:"mt-2 text-muted-foreground text-sm",children:"PDFs, Word docs, presentations uploaded by users"})]}),r("div",{className:"card-subtle p-4",children:[a("h3",{className:"mb-2 font-semibold text-lg",children:"Notion"}),a("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:a("pre",{children:`{
   kind: "notion",
   location: "https://notion.so/workspace/product-docs",
   syncPolicy: { interval: "1h", webhook: true }
-}`})}),t("p",{className:"mt-2 text-muted-foreground text-sm",children:"Notion pages and databases with real-time webhook updates"})]}),l("div",{className:"card-subtle p-4",children:[t("h3",{className:"mb-2 font-semibold text-lg",children:"Gmail / Email"}),t("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:t("pre",{children:`{
+}`})}),a("p",{className:"mt-2 text-muted-foreground text-sm",children:"Notion pages and databases with real-time webhook updates"})]}),r("div",{className:"card-subtle p-4",children:[a("h3",{className:"mb-2 font-semibold text-lg",children:"Gmail / Email"}),a("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:a("pre",{children:`{
   kind: "email",
   location: "support@company.com",
   syncPolicy: { webhook: true }
-}`})}),t("p",{className:"mt-2 text-muted-foreground text-sm",children:"Email threads from Gmail or other providers"})]}),l("div",{className:"card-subtle p-4",children:[t("h3",{className:"mb-2 font-semibold text-lg",children:"Database Query"}),t("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:t("pre",{children:`{
+}`})}),a("p",{className:"mt-2 text-muted-foreground text-sm",children:"Email threads from Gmail or other providers"})]}),r("div",{className:"card-subtle p-4",children:[a("h3",{className:"mb-2 font-semibold text-lg",children:"Database Query"}),a("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:a("pre",{children:`{
   kind: "database-query",
   location: "SELECT * FROM products WHERE active = true",
   syncPolicy: { interval: "24h" }
-}`})}),t("p",{className:"mt-2 text-muted-foreground text-sm",children:"Structured data from application databases"})]}),l("div",{className:"card-subtle p-4",children:[t("h3",{className:"mb-2 font-semibold text-lg",children:"URL / Web Scraping"}),t("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:t("pre",{children:`{
+}`})}),a("p",{className:"mt-2 text-muted-foreground text-sm",children:"Structured data from application databases"})]}),r("div",{className:"card-subtle p-4",children:[a("h3",{className:"mb-2 font-semibold text-lg",children:"URL / Web Scraping"}),a("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:a("pre",{children:`{
   kind: "url",
   location: "https://stripe.com/docs",
   syncPolicy: { interval: "24h" }
-}`})}),t("p",{className:"mt-2 text-muted-foreground text-sm",children:"External documentation and web content"})]})]})]}),l("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Sync strategies"}),t("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:l("table",{className:"w-full text-left text-sm",children:[t("thead",{className:"bg-card/50",children:l("tr",{className:"border-border/50 border-b",children:[t("th",{className:"px-4 py-3 font-semibold",children:"Strategy"}),t("th",{className:"px-4 py-3 font-semibold",children:"When to Use"}),t("th",{className:"px-4 py-3 font-semibold",children:"Latency"})]})}),l("tbody",{className:"divide-y divide-border/50",children:[l("tr",{children:[t("td",{className:"px-4 py-3 font-mono text-xs",children:"webhook"}),t("td",{className:"px-4 py-3",children:"Real-time updates (Notion, Gmail, Slack)"}),t("td",{className:"px-4 py-3",children:"Seconds"})]}),l("tr",{children:[t("td",{className:"px-4 py-3 font-mono text-xs",children:"interval"}),t("td",{className:"px-4 py-3",children:"Periodic sync (databases, URLs)"}),t("td",{className:"px-4 py-3",children:"Minutes to hours"})]}),l("tr",{children:[t("td",{className:"px-4 py-3 font-mono text-xs",children:"manual"}),t("td",{className:"px-4 py-3",children:"User-triggered (uploads, one-time imports)"}),t("td",{className:"px-4 py-3",children:"On-demand"})]})]})]})})]}),l("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Example: Multi-source space"}),t("p",{className:"text-muted-foreground",children:"A single knowledge space can be fed by multiple sources:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`// Product Canon space with multiple sources
+}`})}),a("p",{className:"mt-2 text-muted-foreground text-sm",children:"External documentation and web content"})]})]})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Sync strategies"}),a("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:r("table",{className:"w-full text-left text-sm",children:[a("thead",{className:"bg-card/50",children:r("tr",{className:"border-border/50 border-b",children:[a("th",{className:"px-4 py-3 font-semibold",children:"Strategy"}),a("th",{className:"px-4 py-3 font-semibold",children:"When to Use"}),a("th",{className:"px-4 py-3 font-semibold",children:"Latency"})]})}),r("tbody",{className:"divide-y divide-border/50",children:[r("tr",{children:[a("td",{className:"px-4 py-3 font-mono text-xs",children:"webhook"}),a("td",{className:"px-4 py-3",children:"Real-time updates (Notion, Gmail, Slack)"}),a("td",{className:"px-4 py-3",children:"Seconds"})]}),r("tr",{children:[a("td",{className:"px-4 py-3 font-mono text-xs",children:"interval"}),a("td",{className:"px-4 py-3",children:"Periodic sync (databases, URLs)"}),a("td",{className:"px-4 py-3",children:"Minutes to hours"})]}),r("tr",{children:[a("td",{className:"px-4 py-3 font-mono text-xs",children:"manual"}),a("td",{className:"px-4 py-3",children:"User-triggered (uploads, one-time imports)"}),a("td",{className:"px-4 py-3",children:"On-demand"})]})]})]})})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Example: Multi-source space"}),a("p",{className:"text-muted-foreground",children:"A single knowledge space can be fed by multiple sources:"}),a("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:a("pre",{children:`// Product Canon space with multiple sources
 {
   spaceId: "product-canon",
   sources: [
@@ -321,7 +342,16 @@ steps:
       syncPolicy: { manual: true }
     }
   ]
-}`})})]}),l("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Processing pipeline"}),t("p",{className:"text-muted-foreground",children:"When a source is synced, ContractSpec processes it through several stages:"}),l("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground",children:[l("li",{children:[t("strong",{children:"Fetch"})," - Retrieve content from source (API, database, file)"]}),l("li",{children:[t("strong",{children:"Parse"})," - Extract text from documents (PDF, Word, HTML)"]}),l("li",{children:[t("strong",{children:"Chunk"})," - Split into semantic chunks (paragraphs, sections)"]}),l("li",{children:[t("strong",{children:"Embed"})," - Generate vector embeddings (OpenAI, Cohere)"]}),l("li",{children:[t("strong",{children:"Index"})," - Store in vector database (Qdrant) or search engine"]}),l("li",{children:[t("strong",{children:"Audit"})," - Log sync operation and results"]})]})]}),l("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Best practices"}),l("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Use webhooks for real-time sources (Notion, Gmail) to minimize latency"}),t("li",{children:"Set appropriate sync intervals - hourly for active docs, daily for stable content"}),t("li",{children:"Monitor sync failures and set up alerts for critical sources"}),t("li",{children:"Test sources in sandbox before enabling in production"}),t("li",{children:"Document the purpose and ownership of each source for your team"}),t("li",{children:"Use manual sync for sensitive or infrequently updated content"})]})]}),l("div",{className:"flex items-center gap-4 pt-4",children:[t(w,{href:"/docs/knowledge/spaces",className:"btn-ghost",children:"Previous: Spaces"}),l(w,{href:"/docs/knowledge/examples",className:"btn-primary",children:["Examples ",t(E,{size:16})]})]})]})}import y from"@contractspec/lib.ui-link";import{ChevronRight as B}from"lucide-react";import{jsx as o,jsxs as r}from"react/jsx-runtime";function H(){return r("div",{className:"space-y-8",children:[r("div",{className:"space-y-4",children:[o("h1",{className:"font-bold text-4xl",children:"Knowledge Spaces"}),r("p",{className:"text-muted-foreground",children:["A ",o("strong",{children:"KnowledgeSpaceSpec"})," defines a logical domain of knowledge with a specific category, storage strategy, and intended audience. Spaces are defined globally and populated per-tenant through knowledge sources."]})]}),r("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"KnowledgeSpaceSpec"}),o("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:o("pre",{children:`type KnowledgeSpaceSpec = {
+}`})})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Processing pipeline"}),a("p",{className:"text-muted-foreground",children:"When a source is synced, ContractSpec processes it through several stages:"}),r("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground",children:[r("li",{children:[a("strong",{children:"Fetch"})," - Retrieve content from source (API, database, file)"]}),r("li",{children:[a("strong",{children:"Parse"})," - Extract text from documents (PDF, Word, HTML)"]}),r("li",{children:[a("strong",{children:"Chunk"})," - Split into semantic chunks (paragraphs, sections)"]}),r("li",{children:[a("strong",{children:"Embed"})," - Generate vector embeddings (OpenAI, Cohere)"]}),r("li",{children:[a("strong",{children:"Index"})," - Store in vector database (Qdrant) or search engine"]}),r("li",{children:[a("strong",{children:"Audit"})," - Log sync operation and results"]})]})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Provider delta state"}),r("p",{className:"text-muted-foreground",children:["Runtime-backed providers should persist a"," ",a("strong",{children:"ProviderDeltaSyncState"})," per source before sync work is acknowledged. Gmail and Google Drive adapters use that checkpoint to resume cursors, renew watches, skip tombstones, dedupe webhook events, and replay from a known point after retries."]}),a("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:a("pre",{children:`type ProviderDeltaSyncState = {
+  lease?: { holder: string; expiresAt: string; renewalWindowMs: number };
+  cursor?: { cursor?: string; watermark?: string; watermarkVersion?: string };
+  webhookChannel?: { channelId: string; resourceId?: string; expiresAt?: string };
+  providerEventId?: string;
+  dedupeKey?: string;
+  idempotencyKey?: string;
+  replayCheckpoint?: { checkpointId: string; sequence?: string | number };
+  tombstone?: { deletedAt: string; reason?: string };
+};`})}),r("div",{className:"flex flex-wrap gap-3",children:[a(u,{href:"/docs/integrations/gmail",className:"btn-ghost",children:"Gmail integration"}),a(u,{href:"/docs/integrations/google-drive",className:"btn-ghost",children:"Google Drive integration"}),a(u,{href:"/docs/guides/provider-backed-knowledge",className:"btn-ghost",children:"Provider-backed guide"})]})]}),r("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Best practices"}),r("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[a("li",{children:"Use webhooks for real-time sources (Notion, Gmail) to minimize latency"}),a("li",{children:"Set appropriate sync intervals - hourly for active docs, daily for stable content"}),a("li",{children:"Monitor sync failures and set up alerts for critical sources"}),a("li",{children:"Test sources in sandbox before enabling in production"}),a("li",{children:"Document the purpose and ownership of each source for your team"}),a("li",{children:"Use manual sync for sensitive or infrequently updated content"}),r("li",{children:["Run external mutations through"," ",a(u,{href:"/docs/knowledge/governance",className:"text-primary",children:"knowledge mutation governance"})," ","before sending email, changing Drive permissions, or repairing replay state."]})]})]}),r("div",{className:"flex items-center gap-4 pt-4",children:[a(u,{href:"/docs/knowledge/spaces",className:"btn-ghost",children:"Previous: Spaces"}),r(u,{href:"/docs/knowledge/examples",className:"btn-primary",children:["Examples ",a(M,{size:16})]})]})]})}import b from"@contractspec/lib.ui-link";import{ChevronRight as S}from"lucide-react";import{jsx as o,jsxs as n}from"react/jsx-runtime";function T(){return n("div",{className:"space-y-8",children:[n("div",{className:"space-y-4",children:[o("h1",{className:"font-bold text-4xl",children:"Knowledge Spaces"}),n("p",{className:"text-muted-foreground",children:["A ",o("strong",{children:"KnowledgeSpaceSpec"})," defines a logical domain of knowledge with a specific category, storage strategy, and intended audience. Spaces are defined globally and populated per-tenant through knowledge sources."]})]}),n("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"KnowledgeSpaceSpec"}),o("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:o("pre",{children:`type KnowledgeSpaceSpec = {
   id: string;
   label: string;
   description: string;
@@ -346,7 +376,7 @@ steps:
   owner?: string;
   createdAt: string;
   updatedAt: string;
-};`})})]}),r("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"Common knowledge spaces"}),r("div",{className:"space-y-6",children:[r("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"Product Canon"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
+};`})})]}),n("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"Common knowledge spaces"}),n("div",{className:"space-y-6",children:[n("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"Product Canon"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
   id: "product-canon",
   label: "Product Canon",
   description: "Official product specifications and schemas",
@@ -356,7 +386,7 @@ steps:
   indexProvider: "qdrant",
   vectorDimensions: 1536,
   retentionPolicy: { versions: 10 }
-}`})}),r("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Invoice generation, quote creation, product recommendations, schema validation"]})]}),r("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"Support History"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
+}`})}),n("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Invoice generation, quote creation, product recommendations, schema validation"]})]}),n("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"Support History"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
   id: "support-history",
   label: "Support History",
   description: "Past support tickets and resolutions",
@@ -366,7 +396,7 @@ steps:
   indexProvider: "qdrant",
   vectorDimensions: 1536,
   retentionPolicy: { days: 365 }
-}`})}),r("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Customer support, troubleshooting, similar issue detection"]})]}),r("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"External Provider Docs"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
+}`})}),n("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Customer support, troubleshooting, similar issue detection"]})]}),n("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"External Provider Docs"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
   id: "provider-docs",
   label: "External Provider Docs",
   description: "Third-party integration documentation",
@@ -375,7 +405,7 @@ steps:
   storageStrategy: "search",
   indexProvider: "elasticsearch",
   retentionPolicy: { days: 90 }
-}`})}),r("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Integration help, API reference, troubleshooting external services"]})]}),r("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"Agent Scratchpad"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
+}`})}),n("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Integration help, API reference, troubleshooting external services"]})]}),n("div",{className:"card-subtle p-4",children:[o("h3",{className:"mb-2 font-semibold text-lg",children:"Agent Scratchpad"}),o("div",{className:"overflow-x-auto rounded border border-border bg-background/50 p-3 font-mono text-muted-foreground text-xs",children:o("pre",{children:`{
   id: "agent-scratchpad",
   label: "Agent Scratchpad",
   description: "Temporary agent working memory",
@@ -385,4 +415,4 @@ steps:
   indexProvider: "qdrant",
   vectorDimensions: 1536,
   retentionPolicy: { days: 1 }
-}`})}),r("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Conversation continuity, intermediate calculations, session state"]})]})]})]}),r("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"Storage strategies"}),o("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:r("table",{className:"w-full text-left text-sm",children:[o("thead",{className:"bg-card/50",children:r("tr",{className:"border-border/50 border-b",children:[o("th",{className:"px-4 py-3 font-semibold",children:"Strategy"}),o("th",{className:"px-4 py-3 font-semibold",children:"Best For"}),o("th",{className:"px-4 py-3 font-semibold",children:"Providers"})]})}),r("tbody",{className:"divide-y divide-border/50",children:[r("tr",{children:[o("td",{className:"px-4 py-3 font-mono text-xs",children:"vector"}),o("td",{className:"px-4 py-3",children:"Semantic search, RAG, similarity matching"}),o("td",{className:"px-4 py-3",children:"Qdrant, Pinecone, Weaviate"})]}),r("tr",{children:[o("td",{className:"px-4 py-3 font-mono text-xs",children:"search"}),o("td",{className:"px-4 py-3",children:"Keyword search, exact matching, filtering"}),o("td",{className:"px-4 py-3",children:"Elasticsearch, Algolia"})]}),r("tr",{children:[o("td",{className:"px-4 py-3 font-mono text-xs",children:"hybrid"}),o("td",{className:"px-4 py-3",children:"Combined semantic + keyword search"}),o("td",{className:"px-4 py-3",children:"Qdrant + Elasticsearch"})]})]})]})})]}),r("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"Best practices"}),r("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:"Choose storage strategy based on query patterns - use vector for semantic, search for exact"}),o("li",{children:"Set appropriate retention policies - canonical is permanent, ephemeral is short-lived"}),o("li",{children:"Use consistent vector dimensions across spaces that will be queried together"}),o("li",{children:"Document the intended audience and use cases for each space"}),o("li",{children:"Monitor space size and query performance - add sharding if needed"})]})]}),r("div",{className:"flex items-center gap-4 pt-4",children:[o(y,{href:"/docs/knowledge/categories",className:"btn-ghost",children:"Previous: Categories"}),r(y,{href:"/docs/knowledge/sources",className:"btn-primary",children:["Knowledge Sources ",o(B,{size:16})]})]})]})}export{H as KnowledgeSpacesPage,A as KnowledgeSourcesPage,D as KnowledgeOverviewPage,P as KnowledgeExamplesPage,b as KnowledgeCategoriesPage};
+}`})}),n("p",{className:"mt-2 text-muted-foreground text-sm",children:[o("strong",{children:"Use cases:"})," Conversation continuity, intermediate calculations, session state"]})]})]})]}),n("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"Storage strategies"}),o("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:n("table",{className:"w-full text-left text-sm",children:[o("thead",{className:"bg-card/50",children:n("tr",{className:"border-border/50 border-b",children:[o("th",{className:"px-4 py-3 font-semibold",children:"Strategy"}),o("th",{className:"px-4 py-3 font-semibold",children:"Best For"}),o("th",{className:"px-4 py-3 font-semibold",children:"Providers"})]})}),n("tbody",{className:"divide-y divide-border/50",children:[n("tr",{children:[o("td",{className:"px-4 py-3 font-mono text-xs",children:"vector"}),o("td",{className:"px-4 py-3",children:"Semantic search, RAG, similarity matching"}),o("td",{className:"px-4 py-3",children:"Qdrant, Pinecone, Weaviate"})]}),n("tr",{children:[o("td",{className:"px-4 py-3 font-mono text-xs",children:"search"}),o("td",{className:"px-4 py-3",children:"Keyword search, exact matching, filtering"}),o("td",{className:"px-4 py-3",children:"Elasticsearch, Algolia"})]}),n("tr",{children:[o("td",{className:"px-4 py-3 font-mono text-xs",children:"hybrid"}),o("td",{className:"px-4 py-3",children:"Combined semantic + keyword search"}),o("td",{className:"px-4 py-3",children:"Qdrant + Elasticsearch"})]})]})]})})]}),n("div",{className:"space-y-4",children:[o("h2",{className:"font-bold text-2xl",children:"Best practices"}),n("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:"Choose storage strategy based on query patterns - use vector for semantic, search for exact"}),o("li",{children:"Set appropriate retention policies - canonical is permanent, ephemeral is short-lived"}),o("li",{children:"Use consistent vector dimensions across spaces that will be queried together"}),o("li",{children:"Document the intended audience and use cases for each space"}),o("li",{children:"Monitor space size and query performance - add sharding if needed"})]})]}),n("div",{className:"flex items-center gap-4 pt-4",children:[o(b,{href:"/docs/knowledge/categories",className:"btn-ghost",children:"Previous: Categories"}),n(b,{href:"/docs/knowledge/sources",className:"btn-primary",children:["Knowledge Sources ",o(S,{size:16})]})]})]})}export{T as KnowledgeSpacesPage,B as KnowledgeSourcesPage,I as KnowledgeOverviewPage,D as KnowledgeGovernancePage,q as KnowledgeExamplesPage,E as KnowledgeCategoriesPage};