@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/knowledge/KnowledgeSourcesPage.tsx

@@ -0,0 +1,263 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Knowledge Sources: ContractSpec Docs',
+//   description:
+//     'Learn about KnowledgeSourceConfig and how to connect tenant data sources to knowledge spaces.',
+// };
+
+export function KnowledgeSourcesPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Knowledge Sources</h1>
+        <p className="text-muted-foreground">
+          A <strong>KnowledgeSourceConfig</strong> 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.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">KnowledgeSourceConfig</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`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;
+};`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Source types</h2>
+        <div className="space-y-6">
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Uploaded Documents</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  kind: "uploaded-document",
+  location: "s3://bucket/tenant-123/docs/product-spec.pdf",
+  syncPolicy: { manual: true }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              PDFs, Word docs, presentations uploaded by users
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Notion</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  kind: "notion",
+  location: "https://notion.so/workspace/product-docs",
+  syncPolicy: { interval: "1h", webhook: true }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Notion pages and databases with real-time webhook updates
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Gmail / Email</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  kind: "email",
+  location: "support@company.com",
+  syncPolicy: { webhook: true }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Email threads from Gmail or other providers
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Database Query</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  kind: "database-query",
+  location: "SELECT * FROM products WHERE active = true",
+  syncPolicy: { interval: "24h" }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Structured data from application databases
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">URL / Web Scraping</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  kind: "url",
+  location: "https://stripe.com/docs",
+  syncPolicy: { interval: "24h" }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              External documentation and web content
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Sync strategies</h2>
+        <div className="border-border/50 overflow-x-auto rounded-lg border">
+          <table className="w-full text-left text-sm">
+            <thead className="bg-card/50">
+              <tr className="border-border/50 border-b">
+                <th className="px-4 py-3 font-semibold">Strategy</th>
+                <th className="px-4 py-3 font-semibold">When to Use</th>
+                <th className="px-4 py-3 font-semibold">Latency</th>
+              </tr>
+            </thead>
+            <tbody className="divide-border/50 divide-y">
+              <tr>
+                <td className="px-4 py-3 font-mono text-xs">webhook</td>
+                <td className="px-4 py-3">
+                  Real-time updates (Notion, Gmail, Slack)
+                </td>
+                <td className="px-4 py-3">Seconds</td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 font-mono text-xs">interval</td>
+                <td className="px-4 py-3">Periodic sync (databases, URLs)</td>
+                <td className="px-4 py-3">Minutes to hours</td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 font-mono text-xs">manual</td>
+                <td className="px-4 py-3">
+                  User-triggered (uploads, one-time imports)
+                </td>
+                <td className="px-4 py-3">On-demand</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Example: Multi-source space</h2>
+        <p className="text-muted-foreground">
+          A single knowledge space can be fed by multiple sources:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`// 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 }
+    }
+  ]
+}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Processing pipeline</h2>
+        <p className="text-muted-foreground">
+          When a source is synced, ContractSpec processes it through several
+          stages:
+        </p>
+        <ol className="text-muted-foreground list-inside list-decimal space-y-3">
+          <li>
+            <strong>Fetch</strong> - Retrieve content from source (API,
+            database, file)
+          </li>
+          <li>
+            <strong>Parse</strong> - Extract text from documents (PDF, Word,
+            HTML)
+          </li>
+          <li>
+            <strong>Chunk</strong> - Split into semantic chunks (paragraphs,
+            sections)
+          </li>
+          <li>
+            <strong>Embed</strong> - Generate vector embeddings (OpenAI, Cohere)
+          </li>
+          <li>
+            <strong>Index</strong> - Store in vector database (Qdrant) or search
+            engine
+          </li>
+          <li>
+            <strong>Audit</strong> - Log sync operation and results
+          </li>
+        </ol>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Use webhooks for real-time sources (Notion, Gmail) to minimize
+            latency
+          </li>
+          <li>
+            Set appropriate sync intervals - hourly for active docs, daily for
+            stable content
+          </li>
+          <li>Monitor sync failures and set up alerts for critical sources</li>
+          <li>Test sources in sandbox before enabling in production</li>
+          <li>
+            Document the purpose and ownership of each source for your team
+          </li>
+          <li>Use manual sync for sensitive or infrequently updated content</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/knowledge/spaces" className="btn-ghost">
+          Previous: Spaces
+        </Link>
+        <Link href="/docs/knowledge/examples" className="btn-primary">
+          Examples <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/knowledge/KnowledgeSpacesPage.tsx

@@ -0,0 +1,215 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Knowledge Spaces: ContractSpec Docs',
+//   description:
+//     'Learn about KnowledgeSpaceSpec and how to define logical knowledge domains in ContractSpec.',
+// };
+
+export function KnowledgeSpacesPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Knowledge Spaces</h1>
+        <p className="text-muted-foreground">
+          A <strong>KnowledgeSpaceSpec</strong> 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.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">KnowledgeSpaceSpec</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`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;
+};`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Common knowledge spaces</h2>
+        <div className="space-y-6">
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Product Canon</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  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 }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Use cases:</strong> Invoice generation, quote creation,
+              product recommendations, schema validation
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Support History</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  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 }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Use cases:</strong> Customer support, troubleshooting,
+              similar issue detection
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">
+              External Provider Docs
+            </h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  id: "provider-docs",
+  label: "External Provider Docs",
+  description: "Third-party integration documentation",
+  category: "external",
+  intendedAudience: "agents",
+  storageStrategy: "search",
+  indexProvider: "elasticsearch",
+  retentionPolicy: { days: 90 }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Use cases:</strong> Integration help, API reference,
+              troubleshooting external services
+            </p>
+          </div>
+
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 text-lg font-semibold">Agent Scratchpad</h3>
+            <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded border p-3 font-mono text-xs">
+              <pre>{`{
+  id: "agent-scratchpad",
+  label: "Agent Scratchpad",
+  description: "Temporary agent working memory",
+  category: "ephemeral",
+  intendedAudience: "agents",
+  storageStrategy: "vector",
+  indexProvider: "qdrant",
+  vectorDimensions: 1536,
+  retentionPolicy: { days: 1 }
+}`}</pre>
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Use cases:</strong> Conversation continuity, intermediate
+              calculations, session state
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Storage strategies</h2>
+        <div className="border-border/50 overflow-x-auto rounded-lg border">
+          <table className="w-full text-left text-sm">
+            <thead className="bg-card/50">
+              <tr className="border-border/50 border-b">
+                <th className="px-4 py-3 font-semibold">Strategy</th>
+                <th className="px-4 py-3 font-semibold">Best For</th>
+                <th className="px-4 py-3 font-semibold">Providers</th>
+              </tr>
+            </thead>
+            <tbody className="divide-border/50 divide-y">
+              <tr>
+                <td className="px-4 py-3 font-mono text-xs">vector</td>
+                <td className="px-4 py-3">
+                  Semantic search, RAG, similarity matching
+                </td>
+                <td className="px-4 py-3">Qdrant, Pinecone, Weaviate</td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 font-mono text-xs">search</td>
+                <td className="px-4 py-3">
+                  Keyword search, exact matching, filtering
+                </td>
+                <td className="px-4 py-3">Elasticsearch, Algolia</td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 font-mono text-xs">hybrid</td>
+                <td className="px-4 py-3">
+                  Combined semantic + keyword search
+                </td>
+                <td className="px-4 py-3">Qdrant + Elasticsearch</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Choose storage strategy based on query patterns - use vector for
+            semantic, search for exact
+          </li>
+          <li>
+            Set appropriate retention policies - canonical is permanent,
+            ephemeral is short-lived
+          </li>
+          <li>
+            Use consistent vector dimensions across spaces that will be queried
+            together
+          </li>
+          <li>Document the intended audience and use cases for each space</li>
+          <li>
+            Monitor space size and query performance - add sharding if needed
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/knowledge/categories" className="btn-ghost">
+          Previous: Categories
+        </Link>
+        <Link href="/docs/knowledge/sources" className="btn-primary">
+          Knowledge Sources <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/knowledge/index.ts

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

package/src/components/docs/libraries/LibrariesAccessibilityPage.tsx

@@ -0,0 +1,137 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+
+export function LibrariesAccessibilityPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">@contractspec/lib.accessibility</h1>
+        <p className="text-muted-foreground">
+          Stable exports of accessibility primitives for LSSM web apps, ensuring
+          WCAG compliance and inclusive design.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.accessibility" />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Exports</h2>
+        <ul className="text-muted-foreground space-y-2">
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">SkipLink</code>
+            : A link to skip navigation, visible on focus
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              VisuallyHidden
+            </code>
+            : Hide content visually but keep it for screen readers
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              SRLiveRegionProvider
+            </code>
+            ,{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              useSRLiveRegion
+            </code>
+            : Manage live region announcements
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              RouteAnnouncer
+            </code>
+            : Announce page title/path changes on navigation
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              FocusOnRouteChange
+            </code>
+            : Reset focus to body or main content on navigation
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              useReducedMotion
+            </code>
+            : Detect if the user prefers reduced motion
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Example: App Setup</h2>
+        <CodeBlock
+          language="tsx"
+          code={`import {
+  SRLiveRegionProvider,
+  RouteAnnouncer,
+  SkipLink
+} from '@contractspec/lib.accessibility';
+
+export function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <SRLiveRegionProvider>
+          <SkipLink />
+          <RouteAnnouncer />
+          <main id="main-content">
+            {children}
+          </main>
+        </SRLiveRegionProvider>
+      </body>
+    </html>
+  );
+}`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Example: Live Announcements</h2>
+        <CodeBlock
+          language="tsx"
+          code={`import { useSRLiveRegion } from '@contractspec/lib.accessibility';
+
+export function TodoList() {
+  const { announce } = useSRLiveRegion();
+
+  const addTodo = () => {
+    // ... add logic
+    announce('Todo added successfully', 'polite');
+  };
+
+  return <button onClick={addTodo}>Add Todo</button>;
+}`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">WCAG Compliance</h2>
+        <p className="text-muted-foreground">
+          These components map directly to WCAG 2.1 Level AA requirements
+          documented in <code>docs/accessibility_wcag_compliance_specs.md</code>
+          :
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>2.4.1 Bypass Blocks (SkipLink)</li>
+          <li>4.1.3 Status Messages (LiveRegion)</li>
+          <li>2.4.3 Focus Order (FocusOnRouteChange)</li>
+          <li>2.3.3 Animation from Interactions (useReducedMotion)</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries/design-system" className="btn-ghost">
+          Previous: Design System
+        </Link>
+        <Link href="/docs/libraries" className="btn-primary">
+          Back to Libraries <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}