@contractspec/bundle.library 3.7.6 → 3.8.2

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

@@ -1,461 +1,113 @@
 // @bun
 // src/components/docs/knowledge/KnowledgeOverviewPage.tsx
 import Link from "@contractspec/lib.ui-link";
-import { ChevronRight } from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
+var knowledgeTracks = [
+  {
+    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 KnowledgeOverviewPage() {
   return /* @__PURE__ */ jsxs("div", {
-    className: "space-y-8",
+    className: "space-y-10",
     children: [
       /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
+        className: "space-y-3",
         children: [
-          /* @__PURE__ */ jsx("h1", {
-            className: "text-4xl font-bold",
-            children: "Knowledge & Context"
-          }),
           /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "ContractSpec provides first-class support for knowledge management, enabling semantic search, RAG (Retrieval-Augmented Generation), and context-aware decision-making. Knowledge is organized into typed spaces with different trust levels and access controls."
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Why knowledge matters"
+            className: "editorial-kicker",
+            children: "Operate"
           }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "Modern applications need to:"
+          /* @__PURE__ */ jsx("h1", {
+            className: "font-serif text-4xl tracking-[-0.04em] md:text-5xl",
+            children: "Knowledge is part of the runtime, not a sidecar prompt hack."
           }),
-          /* @__PURE__ */ jsxs("ul", {
-            className: "text-muted-foreground list-inside list-disc space-y-2",
-            children: [
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Understand context"
-                  }),
-                  " - Access relevant information to make informed decisions"
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Learn from history"
-                  }),
-                  " - Use past interactions to improve future responses"
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Trust sources"
-                  }),
-                  " - Distinguish between authoritative and reference information"
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Scale knowledge"
-                  }),
-                  " - Handle growing amounts of documentation and data"
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Maintain privacy"
-                  }),
-                  " - Keep tenant knowledge isolated and secure"
-                ]
-              })
-            ]
+          /* @__PURE__ */ jsx("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."
           })
         ]
       }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Knowledge architecture"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "ContractSpec's knowledge system has three main components:"
-          }),
-          /* @__PURE__ */ jsxs("div", {
-            className: "space-y-6",
-            children: [
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 text-lg font-semibold",
-                    children: "1. Knowledge Categories"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground mb-3 text-sm",
-                    children: "Four trust levels that determine how knowledge is used:"
-                  }),
-                  /* @__PURE__ */ jsxs("div", {
-                    className: "space-y-2 text-sm",
-                    children: [
-                      /* @__PURE__ */ jsxs("div", {
-                        className: "flex items-start gap-3",
-                        children: [
-                          /* @__PURE__ */ jsx("code", {
-                            className: "bg-background/50 rounded px-2 py-1 text-xs",
-                            children: "canonical"
-                          }),
-                          /* @__PURE__ */ jsx("span", {
-                            className: "text-muted-foreground",
-                            children: "Ground truth - product specs, schemas, official policies"
-                          })
-                        ]
-                      }),
-                      /* @__PURE__ */ jsxs("div", {
-                        className: "flex items-start gap-3",
-                        children: [
-                          /* @__PURE__ */ jsx("code", {
-                            className: "bg-background/50 rounded px-2 py-1 text-xs",
-                            children: "operational"
-                          }),
-                          /* @__PURE__ */ jsx("span", {
-                            className: "text-muted-foreground",
-                            children: "Internal docs - support tickets, runbooks, sales materials"
-                          })
-                        ]
-                      }),
-                      /* @__PURE__ */ jsxs("div", {
-                        className: "flex items-start gap-3",
-                        children: [
-                          /* @__PURE__ */ jsx("code", {
-                            className: "bg-background/50 rounded px-2 py-1 text-xs",
-                            children: "external"
-                          }),
-                          /* @__PURE__ */ jsx("span", {
-                            className: "text-muted-foreground",
-                            children: "Third-party - PSP docs, regulations, integration guides"
-                          })
-                        ]
-                      }),
-                      /* @__PURE__ */ jsxs("div", {
-                        className: "flex items-start gap-3",
-                        children: [
-                          /* @__PURE__ */ jsx("code", {
-                            className: "bg-background/50 rounded px-2 py-1 text-xs",
-                            children: "ephemeral"
-                          }),
-                          /* @__PURE__ */ jsx("span", {
-                            className: "text-muted-foreground",
-                            children: "Temporary - agent scratchpads, session context, drafts"
-                          })
-                        ]
-                      })
-                    ]
-                  }),
-                  /* @__PURE__ */ jsx(Link, {
-                    href: "/docs/knowledge/categories",
-                    className: "mt-3 inline-block text-sm text-violet-400 hover:text-violet-300",
-                    children: "Learn more about categories \u2192"
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 text-lg font-semibold",
-                    children: "2. Knowledge Spaces"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground mb-3 text-sm",
-                    children: "Logical domains of knowledge defined globally:"
-                  }),
-                  /* @__PURE__ */ jsx("div", {
-                    className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs",
-                    children: /* @__PURE__ */ jsx("pre", {
-                      children: `type KnowledgeSpaceSpec = {
-  id: string;
-  label: string;
-  category: KnowledgeCategory;
-  storageStrategy: "vector" | "search" | "hybrid";
-  indexProvider: string;  // e.g., "qdrant"
-  retentionPolicy: { days?: number };
-  intendedAudience: "agents" | "humans" | "admin-only";
-};`
+      /* @__PURE__ */ jsx("section", {
+        className: "editorial-panel space-y-5",
+        children: /* @__PURE__ */ jsxs("div", {
+          className: "space-y-2",
+          children: [
+            /* @__PURE__ */ jsx("h2", {
+              className: "font-serif text-3xl tracking-[-0.03em]",
+              children: "How knowledge enters the system"
+            }),
+            /* @__PURE__ */ jsxs("ul", {
+              className: "editorial-list",
+              children: [
+                /* @__PURE__ */ jsxs("li", {
+                  children: [
+                    /* @__PURE__ */ jsx("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx("span", {
+                      children: "Define the trust category and retrieval expectations first."
                     })
-                  }),
-                  /* @__PURE__ */ jsx(Link, {
-                    href: "/docs/knowledge/spaces",
-                    className: "mt-3 inline-block text-sm text-violet-400 hover:text-violet-300",
-                    children: "Learn more about spaces \u2192"
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 text-lg font-semibold",
-                    children: "3. Knowledge Sources"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground mb-3 text-sm",
-                    children: "Per-tenant data sources that feed knowledge spaces:"
-                  }),
-                  /* @__PURE__ */ jsx("div", {
-                    className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs",
-                    children: /* @__PURE__ */ jsx("pre", {
-                      children: `type KnowledgeSourceConfig = {
-  id: string;
-  tenantId: string;
-  spaceId: string;
-  kind: "uploaded-document" | "url" | "email" 
-        | "notion" | "database-query" | "raw-text";
-  location: string;
-  syncPolicy: { interval?: string; webhook?: boolean };
-  lastSyncedAt?: string;
-};`
+                  ]
+                }),
+                /* @__PURE__ */ jsxs("li", {
+                  children: [
+                    /* @__PURE__ */ jsx("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx("span", {
+                      children: "Bind tenant-owned sources explicitly to those knowledge spaces."
                     })
-                  }),
-                  /* @__PURE__ */ jsx(Link, {
-                    href: "/docs/knowledge/sources",
-                    className: "mt-3 inline-block text-sm text-violet-400 hover:text-violet-300",
-                    children: "Learn more about sources \u2192"
-                  })
-                ]
-              })
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "How it works"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "Knowledge flows through ContractSpec in four stages:"
-          }),
-          /* @__PURE__ */ jsxs("ol", {
-            className: "text-muted-foreground list-inside list-decimal space-y-3",
-            children: [
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Define spaces"
-                  }),
-                  ' - Create KnowledgeSpaceSpec for each logical domain (e.g., "Product Canon", "Support FAQ")'
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Configure sources"
-                  }),
-                  " - Tenants connect their data sources (Notion, Gmail, uploads, etc.)"
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Sync & index"
-                  }),
-                  " - Sources are synced, chunked, and indexed in vector databases"
-                ]
-              }),
-              /* @__PURE__ */ jsxs("li", {
-                children: [
-                  /* @__PURE__ */ jsx("strong", {
-                    children: "Query & retrieve"
-                  }),
-                  " - Workflows and agents perform semantic search to find relevant context"
-                ]
-              })
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Use cases"
-          }),
-          /* @__PURE__ */ jsxs("div", {
-            className: "grid gap-4 md:grid-cols-2",
-            children: [
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 font-semibold",
-                    children: "Support Agents"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground text-sm",
-                    children: "Answer customer questions using product documentation (canonical) and past support tickets (operational)."
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 font-semibold",
-                    children: "Invoice Generation"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground text-sm",
-                    children: "Generate invoices using product catalog (canonical) and pricing rules (operational)."
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 font-semibold",
-                    children: "Compliance Checking"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground text-sm",
-                    children: "Validate operations against regulatory requirements (external) and internal policies (canonical)."
-                  })
-                ]
-              }),
-              /* @__PURE__ */ jsxs("div", {
-                className: "card-subtle p-4",
-                children: [
-                  /* @__PURE__ */ jsx("h3", {
-                    className: "mb-2 font-semibold",
-                    children: "Semantic Search"
-                  }),
-                  /* @__PURE__ */ jsx("p", {
-                    className: "text-muted-foreground text-sm",
-                    children: "Find relevant documents, tickets, or records using natural language queries."
-                  })
-                ]
-              })
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Integration with workflows"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "Knowledge spaces are consumed by workflows through standard capabilities:"
-          }),
-          /* @__PURE__ */ jsx("div", {
-            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
-            children: /* @__PURE__ */ jsx("pre", {
-              children: `import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow';
-import { OpenAIEmbeddings, VectorSearch, OpenAIChat } from './specs';
-
-export const AnswerSupportQuestion = defineWorkflow({
-  meta: {
-    key: 'support.answerQuestion',
-    version: '1.0.0',
-    description: 'Answer support questions using RAG',
-    owners: ['team-support'],
-    tags: ['ai', 'support'],
-    stability: 'stable',
-  },
-  steps: [
-    {
-      id: 'embed-question',
-      operation: OpenAIEmbeddings,
-      inputs: (ctx, input) => ({
-        text: input.question,
-      }),
-    },
-    {
-      id: 'search-knowledge',
-      operation: VectorSearch,
-      inputs: (ctx, input, steps) => ({
-        collection: 'product-canon', // KnowledgeSpace
-        vector: steps['embed-question'].output.embedding,
-        limit: 5,
-      }),
-    },
-    {
-      id: 'generate-answer',
-      operation: OpenAIChat,
-      inputs: (ctx, input, steps) => ({
-        messages: [
-          { role: 'system', content: 'Answer using the provided context' },
-          { 
-            role: 'user', 
-            content: \`Context: \${steps['search-knowledge'].output.results}\\nQuestion: \${input.question}\`
-          },
-        ],
-      }),
-    },
-  ],
-});`
+                  ]
+                }),
+                /* @__PURE__ */ jsxs("li", {
+                  children: [
+                    /* @__PURE__ */ jsx("span", {
+                      className: "editorial-list-marker"
+                    }),
+                    /* @__PURE__ */ jsx("span", {
+                      children: "Consume knowledge through capabilities and workflows, not through invisible prompt assumptions."
+                    })
+                  ]
+                })
+              ]
             })
-          })
-        ]
+          ]
+        })
       }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "space-y-4",
-        children: [
-          /* @__PURE__ */ jsx("h2", {
-            className: "text-2xl font-bold",
-            children: "Real-world examples"
-          }),
-          /* @__PURE__ */ jsx("p", {
-            className: "text-muted-foreground",
-            children: "See how different applications use knowledge spaces:"
-          }),
-          /* @__PURE__ */ jsxs(Link, {
-            href: "/docs/knowledge/examples",
-            className: "btn-primary inline-flex items-center gap-2",
-            children: [
-              "View Examples ",
-              /* @__PURE__ */ jsx(ChevronRight, {
-                size: 16
-              })
-            ]
-          })
-        ]
-      }),
-      /* @__PURE__ */ jsxs("div", {
-        className: "flex items-center gap-4 pt-4",
-        children: [
-          /* @__PURE__ */ jsxs(Link, {
-            href: "/docs/knowledge/categories",
-            className: "btn-primary",
-            children: [
-              "Knowledge Categories ",
-              /* @__PURE__ */ jsx(ChevronRight, {
-                size: 16
-              })
-            ]
-          }),
-          /* @__PURE__ */ jsx(Link, {
-            href: "/docs/knowledge/spaces",
-            className: "btn-ghost",
-            children: "Knowledge Spaces"
-          })
-        ]
+      /* @__PURE__ */ jsx("div", {
+        className: "grid gap-4 md:grid-cols-2",
+        children: knowledgeTracks.map((item) => /* @__PURE__ */ jsxs(Link, {
+          href: item.href,
+          className: "editorial-panel",
+          children: [
+            /* @__PURE__ */ jsx("h2", {
+              className: "font-semibold text-xl",
+              children: item.title
+            }),
+            /* @__PURE__ */ jsx("p", {
+              className: "mt-2 text-muted-foreground text-sm leading-7",
+              children: item.body
+            })
+          ]
+        }, item.href))
       })
     ]
   });