// @bun
import g from"@contractspec/lib.ui-link";import{ChevronRight as w}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";function y(){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 =
  | "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
{
  id: "product-canon",
  category: "canonical",
  sources: [
    "database-schema.sql",
    "product-catalog.yaml",
    "pricing-rules.json"
  ]
}

// Policy Canon space
{
  id: "policy-canon",
  category: "canonical",
  sources: [
    "data-classification.yaml",
    "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
{
  id: "support-history",
  category: "operational",
  sources: [
    "gmail:support@company.com",
    "zendesk:tickets",
    "slack:support-channel"
  ]
}

// Internal Docs space
{
  id: "internal-docs",
  category: "operational",
  sources: [
    "notion:engineering-wiki",
    "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
{
  id: "provider-docs",
  category: "external",
  sources: [
    "url:https://stripe.com/docs",
    "url:https://twilio.com/docs",
    "url:https://openai.com/docs"
  ]
}

// Regulatory Docs space
{
  id: "regulatory-docs",
  category: "external",
  sources: [
    "url:https://gdpr.eu/",
    "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
{
  id: "agent-scratchpad",
  category: "ephemeral",
  retentionPolicy: { days: 1 },
  sources: [
    "session:current-conversation",
    "memory:agent-working-memory"
  ]
}

// User Session space
{
  id: "user-session",
  category: "ephemeral",
  retentionPolicy: { days: 7 },
  sources: [
    "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(g,{href:"/docs/knowledge",className:"btn-ghost",children:"Back to Knowledge"}),a(g,{href:"/docs/knowledge/spaces",className:"btn-primary",children:["Knowledge Spaces ",e(w,{size:16})]})]})]})}import c from"@contractspec/lib.ui-link";import{jsx as d,jsxs as i}from"react/jsx-runtime";function v(){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",
    category: "canonical",
    sources: [
      { kind: "notion", location: "product-docs" },
      { kind: "database-query", location: "SELECT * FROM features" }
    ]
  },
  {
    id: "support-history",
    category: "operational",
    sources: [
      { kind: "email", location: "support@artisanos.com" },
      { kind: "slack", location: "#support-channel" }
    ]
  }
]

// Workflow
workflowId: answer-support-question
steps:
  - id: embed-question
    capability: openai-embeddings
    inputs:
      text: \${input.question}
  
  - id: search-canon
    capability: vector.search
    inputs:
      collection: "product-canon"
      vector: \${steps.embed-question.output.embedding}
      limit: 5
  
  - id: search-history
    capability: vector.search
    inputs:
      collection: "support-history"
      vector: \${steps.embed-question.output.embedding}
      limit: 3
  
  - id: generate-answer
    capability: openai-chat
    inputs:
      messages:
        - role: "system"
          content: |
            Answer using canonical docs as authority.
            Use support history for helpful context.
        - role: "user"
          content: |
            Question: \${input.question}
            Docs: \${steps.search-canon.output.results}
            History: \${steps.search-history.output.results}`})})]}),i("div",{className:"space-y-4",children:[d("h2",{className:"font-bold text-2xl",children:"Example 2: HCircle Invoice Generation"}),i("p",{className:"text-muted-foreground",children:[d("strong",{children:"Context:"})," HCircle needs to generate invoices using house playbook rules and resident service history."]}),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: "house-playbook",
    category: "canonical",
    sources: [
      { kind: "uploaded-document", location: "playbook.pdf" },
      { kind: "database-query", location: "SELECT * FROM pricing_rules" }
    ]
  },
  {
    id: "resident-history",
    category: "operational",
    sources: [
      { kind: "database-query", location: "SELECT * FROM services" },
      { kind: "database-query", location: "SELECT * FROM invoices" }
    ]
  }
]

// Workflow
workflowId: generate-invoice
steps:
  - id: fetch-services
    capability: database.query
    inputs:
      query: "SELECT * FROM services WHERE resident_id = ?"
      params: [\${input.residentId}]
  
  - id: search-pricing-rules
    capability: vector.search
    inputs:
      collection: "house-playbook"
      query: "pricing rules for \${steps.fetch-services.output.serviceType}"
      limit: 3
  
  - id: calculate-total
    capability: calculate
    inputs:
      services: \${steps.fetch-services.output.rows}
      rules: \${steps.search-pricing-rules.output.results}
  
  - id: create-invoice
    capability: database.insert
    inputs:
      table: "invoices"
      data: \${steps.calculate-total.output}`})})]}),i("div",{className:"space-y-4",children:[d("h2",{className:"font-bold text-2xl",children:"Example 3: Multi-tenant SaaS with External Docs"}),i("p",{className:"text-muted-foreground",children:[d("strong",{children:"Context:"})," A SaaS platform needs to help users integrate with Stripe, using both internal guides and Stripe's official documentation."]}),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: "integration-guides",
    category: "canonical",
    sources: [
      { kind: "notion", location: "integration-guides" }
    ]
  },
  {
    id: "stripe-docs",
    category: "external",
    sources: [
      { kind: "url", location: "https://stripe.com/docs" }
    ]
  },
  {
    id: "customer-questions",
    category: "operational",
    sources: [
      { kind: "email", location: "support@saas.com" }
    ]
  }
]

// Workflow
workflowId: answer-integration-question
steps:
  - id: embed-question
    capability: openai-embeddings
    inputs:
      text: \${input.question}
  
  - id: search-internal-guides
    capability: vector.search
    inputs:
      collection: "integration-guides"
      vector: \${steps.embed-question.output.embedding}
      limit: 3
  
  - id: search-stripe-docs
    capability: vector.search
    inputs:
      collection: "stripe-docs"
      vector: \${steps.embed-question.output.embedding}
      limit: 2
  
  - id: search-past-questions
    capability: vector.search
    inputs:
      collection: "customer-questions"
      vector: \${steps.embed-question.output.embedding}
      limit: 2
  
  - id: generate-answer
    capability: openai-chat
    inputs:
      messages:
        - role: "system"
          content: |
            Prioritize internal guides (authoritative).
            Use Stripe docs for API details (reference).
            Use past questions for common issues (context).
        - role: "user"
          content: |
            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(c,{href:"/docs/knowledge/sources",className:"btn-ghost",children:"Previous: Sources"}),d(c,{href:"/docs/architecture/knowledge-binding",className:"btn-ghost",children:"Knowledge Binding"})]})]})}import N from"@contractspec/lib.ui-link";import{jsx as n,jsxs as m}from"react/jsx-runtime";var u=[{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 k(){return m("div",{className:"space-y-10",children:[m("div",{className:"space-y-3",children:[n("p",{className:"editorial-kicker",children:"Operate"}),n("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Knowledge is part of the runtime, not a sidecar prompt hack."}),n("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."})]}),n("section",{className:"editorial-panel space-y-5",children:m("div",{className:"space-y-2",children:[n("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"How knowledge enters the system"}),m("ul",{className:"editorial-list",children:[m("li",{children:[n("span",{className:"editorial-list-marker"}),n("span",{children:"Define the trust category and retrieval expectations first."})]}),m("li",{children:[n("span",{className:"editorial-list-marker"}),n("span",{children:"Bind tenant-owned sources explicitly to those knowledge spaces."})]}),m("li",{children:[n("span",{className:"editorial-list-marker"}),n("span",{children:"Consume knowledge through capabilities and workflows, not through invisible prompt assumptions."})]})]})]})}),n("div",{className:"grid gap-4 md:grid-cols-2",children:u.map((p)=>m(N,{href:p.href,className:"editorial-panel",children:[n("h2",{className:"font-semibold text-xl",children:p.title}),n("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:p.body})]},p.href))})]})}import f from"@contractspec/lib.ui-link";import{ChevronRight as b}from"lucide-react";import{jsx as t,jsxs as l}from"react/jsx-runtime";function P(){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 = {
  id: string;
  tenantId: string;
  spaceId: string;
  
  // Source type and location
  kind: "uploaded-document" | "url" | "email" 
        | "notion" | "database-query" | "raw-text"
        | "slack" | "confluence" | "google-drive";
  location: string;
  
  // Sync configuration
  syncPolicy: {
    interval?: string;  // e.g., "1h", "24h"
    webhook?: boolean;
    manual?: boolean;
  };
  
  // State
  status: "active" | "paused" | "error";
  lastSyncedAt?: string;
  lastErrorMessage?: string;
  
  // Metadata
  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:`{
  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:`{
  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:`{
  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:`{
  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:`{
  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
{
  spaceId: "product-canon",
  sources: [
    {
      id: "src_database_schema",
      kind: "database-query",
      location: "SELECT * FROM schema_definitions",
      syncPolicy: { interval: "1h" }
    },
    {
      id: "src_notion_product_docs",
      kind: "notion",
      location: "https://notion.so/product-docs",
      syncPolicy: { interval: "1h", webhook: true }
    },
    {
      id: "src_uploaded_specs",
      kind: "uploaded-document",
      location: "s3://bucket/specs/",
      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(f,{href:"/docs/knowledge/spaces",className:"btn-ghost",children:"Previous: Spaces"}),l(f,{href:"/docs/knowledge/examples",className:"btn-primary",children:["Examples ",t(b,{size:16})]})]})]})}import h from"@contractspec/lib.ui-link";import{ChevronRight as K}from"lucide-react";import{jsx as o,jsxs as r}from"react/jsx-runtime";function O(){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 = {
  id: string;
  label: string;
  description: string;
  
  // Trust and access
  category: KnowledgeCategory;
  intendedAudience: "agents" | "humans" | "admin-only";
  
  // Storage and indexing
  storageStrategy: "vector" | "search" | "hybrid";
  indexProvider: string;  // e.g., "qdrant", "elasticsearch"
  vectorDimensions?: number;  // For vector storage
  
  // Lifecycle
  retentionPolicy: {
    days?: number;
    versions?: number;
  };
  
  // Metadata
  tags?: string[];
  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:`{
  id: "product-canon",
  label: "Product Canon",
  description: "Official product specifications and schemas",
  category: "canonical",
  intendedAudience: "agents",
  storageStrategy: "hybrid",
  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:`{
  id: "support-history",
  label: "Support History",
  description: "Past support tickets and resolutions",
  category: "operational",
  intendedAudience: "agents",
  storageStrategy: "vector",
  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:`{
  id: "provider-docs",
  label: "External Provider Docs",
  description: "Third-party integration documentation",
  category: "external",
  intendedAudience: "agents",
  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:`{
  id: "agent-scratchpad",
  label: "Agent Scratchpad",
  description: "Temporary agent working memory",
  category: "ephemeral",
  intendedAudience: "agents",
  storageStrategy: "vector",
  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(h,{href:"/docs/knowledge/categories",className:"btn-ghost",children:"Previous: Categories"}),r(h,{href:"/docs/knowledge/sources",className:"btn-primary",children:["Knowledge Sources ",o(K,{size:16})]})]})]})}export{O as KnowledgeSpacesPage,P as KnowledgeSourcesPage,k as KnowledgeOverviewPage,v as KnowledgeExamplesPage,y as KnowledgeCategoriesPage};
