@contractspec/bundle.library 3.10.1 → 3.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/bundle.library",
-  "version": "3.10.1",
+  "version": "3.10.2",
   "type": "module",
   "scripts": {
     "clean": "rm -rf dist",
@@ -534,6 +534,12 @@
       "node": "./dist/node/components/docs/guides/GuideNextjsOneEndpointPage.js",
       "default": "./dist/components/docs/guides/GuideNextjsOneEndpointPage.js"
     },
+    "./components/docs/guides/GuideProviderBackedKnowledgePage": {
+      "types": "./dist/components/docs/guides/GuideProviderBackedKnowledgePage.d.ts",
+      "bun": "./dist/components/docs/guides/GuideProviderBackedKnowledgePage.js",
+      "node": "./dist/node/components/docs/guides/GuideProviderBackedKnowledgePage.js",
+      "default": "./dist/components/docs/guides/GuideProviderBackedKnowledgePage.js"
+    },
     "./components/docs/guides/GuideReleaseCapsulesPage": {
       "types": "./dist/components/docs/guides/GuideReleaseCapsulesPage.d.ts",
       "bun": "./dist/components/docs/guides/GuideReleaseCapsulesPage.js",
@@ -594,6 +600,12 @@
       "node": "./dist/node/components/docs/integrations/IntegrationsGoogleCalendarPage.js",
       "default": "./dist/components/docs/integrations/IntegrationsGoogleCalendarPage.js"
     },
+    "./components/docs/integrations/IntegrationsGoogleDrivePage": {
+      "types": "./dist/components/docs/integrations/IntegrationsGoogleDrivePage.d.ts",
+      "bun": "./dist/components/docs/integrations/IntegrationsGoogleDrivePage.js",
+      "node": "./dist/node/components/docs/integrations/IntegrationsGoogleDrivePage.js",
+      "default": "./dist/components/docs/integrations/IntegrationsGoogleDrivePage.js"
+    },
     "./components/docs/integrations/IntegrationsHealthRoutingPage": {
       "types": "./dist/components/docs/integrations/IntegrationsHealthRoutingPage.d.ts",
       "bun": "./dist/components/docs/integrations/IntegrationsHealthRoutingPage.js",
@@ -750,6 +762,12 @@
       "node": "./dist/node/components/docs/knowledge/KnowledgeExamplesPage.js",
       "default": "./dist/components/docs/knowledge/KnowledgeExamplesPage.js"
     },
+    "./components/docs/knowledge/KnowledgeGovernancePage": {
+      "types": "./dist/components/docs/knowledge/KnowledgeGovernancePage.d.ts",
+      "bun": "./dist/components/docs/knowledge/KnowledgeGovernancePage.js",
+      "node": "./dist/node/components/docs/knowledge/KnowledgeGovernancePage.js",
+      "default": "./dist/components/docs/knowledge/KnowledgeGovernancePage.js"
+    },
     "./components/docs/knowledge/KnowledgeOverviewPage": {
       "types": "./dist/components/docs/knowledge/KnowledgeOverviewPage.d.ts",
       "bun": "./dist/components/docs/knowledge/KnowledgeOverviewPage.js",
@@ -2028,27 +2046,27 @@
     "react": "19.2.0"
   },
   "dependencies": {
-    "@contractspec/bundle.workspace": "4.7.0",
+    "@contractspec/bundle.workspace": "4.7.1",
     "@apollo/client": "^4.1.7",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@contractspec/example.data-grid-showcase": "3.8.24",
-    "@contractspec/lib.ai-providers": "3.7.21",
-    "@contractspec/lib.contracts-spec": "6.3.0",
-    "@contractspec/lib.contracts-library": "3.7.28",
-    "@contractspec/lib.content-gen": "3.7.28",
-    "@contractspec/lib.contracts-runtime-server-mcp": "3.8.8",
-    "@contractspec/lib.design-system": "4.4.3",
-    "@contractspec/lib.surface-runtime": "0.5.28",
-    "@contractspec/lib.provider-ranking": "0.7.21",
-    "@contractspec/lib.example-shared-ui": "7.0.9",
-    "@contractspec/lib.knowledge": "3.8.4",
-    "@contractspec/lib.logger": "3.7.21",
-    "@contractspec/lib.runtime-sandbox": "3.0.7",
+    "@contractspec/example.data-grid-showcase": "3.8.25",
+    "@contractspec/lib.ai-providers": "3.7.22",
+    "@contractspec/lib.contracts-spec": "6.4.0",
+    "@contractspec/lib.contracts-library": "3.7.29",
+    "@contractspec/lib.content-gen": "3.7.29",
+    "@contractspec/lib.contracts-runtime-server-mcp": "3.8.9",
+    "@contractspec/lib.design-system": "4.4.4",
+    "@contractspec/lib.surface-runtime": "0.5.29",
+    "@contractspec/lib.provider-ranking": "0.7.22",
+    "@contractspec/lib.example-shared-ui": "7.0.10",
+    "@contractspec/lib.knowledge": "3.9.0",
+    "@contractspec/lib.logger": "3.7.22",
+    "@contractspec/lib.runtime-sandbox": "3.0.8",
     "@contractspec/lib.schema": "3.7.14",
-    "@contractspec/lib.ui-kit-web": "3.13.3",
-    "@contractspec/lib.ui-link": "3.7.23",
-    "@contractspec/module.context-storage": "0.7.27",
-    "@contractspec/module.examples": "4.0.9",
+    "@contractspec/lib.ui-kit-web": "3.13.4",
+    "@contractspec/lib.ui-link": "3.7.24",
+    "@contractspec/module.context-storage": "0.7.28",
+    "@contractspec/module.examples": "4.0.10",
     "@dnd-kit/core": "^6.1.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -2064,10 +2082,10 @@
     "posthog-react-native": "^4.43.10",
     "react-hook-form": "^7.74.0",
     "zod": "^4.3.5",
-    "@contractspec/lib.contracts-integrations": "3.9.0",
-    "@contractspec/lib.contracts-runtime-server-rest": "3.9.1",
-    "@contractspec/lib.contracts-runtime-server-graphql": "3.8.7",
-    "@contractspec/lib.contracts-runtime-client-react": "3.14.1"
+    "@contractspec/lib.contracts-integrations": "3.10.0",
+    "@contractspec/lib.contracts-runtime-server-rest": "3.9.2",
+    "@contractspec/lib.contracts-runtime-server-graphql": "3.8.8",
+    "@contractspec/lib.contracts-runtime-client-react": "3.14.2"
   },
   "devDependencies": {
     "@types/react": "~19.2.14",
@@ -2601,6 +2619,12 @@
         "node": "./dist/node/components/docs/guides/GuideNextjsOneEndpointPage.js",
         "default": "./dist/components/docs/guides/GuideNextjsOneEndpointPage.js"
       },
+      "./components/docs/guides/GuideProviderBackedKnowledgePage": {
+        "types": "./dist/components/docs/guides/GuideProviderBackedKnowledgePage.d.ts",
+        "bun": "./dist/components/docs/guides/GuideProviderBackedKnowledgePage.js",
+        "node": "./dist/node/components/docs/guides/GuideProviderBackedKnowledgePage.js",
+        "default": "./dist/components/docs/guides/GuideProviderBackedKnowledgePage.js"
+      },
       "./components/docs/guides/GuideReleaseCapsulesPage": {
         "types": "./dist/components/docs/guides/GuideReleaseCapsulesPage.d.ts",
         "bun": "./dist/components/docs/guides/GuideReleaseCapsulesPage.js",
@@ -2661,6 +2685,12 @@
         "node": "./dist/node/components/docs/integrations/IntegrationsGoogleCalendarPage.js",
         "default": "./dist/components/docs/integrations/IntegrationsGoogleCalendarPage.js"
       },
+      "./components/docs/integrations/IntegrationsGoogleDrivePage": {
+        "types": "./dist/components/docs/integrations/IntegrationsGoogleDrivePage.d.ts",
+        "bun": "./dist/components/docs/integrations/IntegrationsGoogleDrivePage.js",
+        "node": "./dist/node/components/docs/integrations/IntegrationsGoogleDrivePage.js",
+        "default": "./dist/components/docs/integrations/IntegrationsGoogleDrivePage.js"
+      },
       "./components/docs/integrations/IntegrationsHealthRoutingPage": {
         "types": "./dist/components/docs/integrations/IntegrationsHealthRoutingPage.d.ts",
         "bun": "./dist/components/docs/integrations/IntegrationsHealthRoutingPage.js",
@@ -2817,6 +2847,12 @@
         "node": "./dist/node/components/docs/knowledge/KnowledgeExamplesPage.js",
         "default": "./dist/components/docs/knowledge/KnowledgeExamplesPage.js"
       },
+      "./components/docs/knowledge/KnowledgeGovernancePage": {
+        "types": "./dist/components/docs/knowledge/KnowledgeGovernancePage.d.ts",
+        "bun": "./dist/components/docs/knowledge/KnowledgeGovernancePage.js",
+        "node": "./dist/node/components/docs/knowledge/KnowledgeGovernancePage.js",
+        "default": "./dist/components/docs/knowledge/KnowledgeGovernancePage.js"
+      },
       "./components/docs/knowledge/KnowledgeOverviewPage": {
         "types": "./dist/components/docs/knowledge/KnowledgeOverviewPage.d.ts",
         "bun": "./dist/components/docs/knowledge/KnowledgeOverviewPage.js",

package/src/components/docs/docsManifest.ts

@@ -411,6 +411,23 @@ export const DOCS_PAGES: readonly DocsPageEntry[] = [
 		audience: 'operator',
 		ctaMode: 'oss-next',
 	},
+	{
+		href: '/docs/guides/provider-backed-knowledge',
+		title: 'Adopt provider-backed knowledge',
+		description:
+			'Ingest Gmail and Google Drive into governed knowledge spaces with persisted provider deltas and mutation gates.',
+		section: 'build',
+		order: 68,
+		navTitle: 'Provider-backed knowledge',
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'oss-next',
+		aliases: [
+			'Gmail knowledge ingestion',
+			'Google Drive knowledge ingestion',
+			'ProviderDeltaSyncState',
+		],
+	},
 	{
 		href: '/docs/libraries',
 		title: 'Libraries overview',
@@ -604,6 +621,23 @@ export const DOCS_PAGES: readonly DocsPageEntry[] = [
 		audience: 'operator',
 		ctaMode: 'oss-next',
 	},
+	{
+		href: '/docs/knowledge/governance',
+		title: 'Knowledge mutation governance',
+		description:
+			'Gate provider-backed knowledge mutations with dry-runs, approvals, idempotency, audit evidence, and outbound-send policy.',
+		section: 'operate',
+		order: 72,
+		navTitle: 'Knowledge governance',
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'oss-next',
+		aliases: [
+			'knowledge.mutation.evaluateGovernance',
+			'KnowledgeMutationGovernance',
+			'outbound-send gates',
+		],
+	},
 	{
 		href: '/docs/advanced/telemetry',
 		title: 'Telemetry',
@@ -692,6 +726,34 @@ export const DOCS_PAGES: readonly DocsPageEntry[] = [
 		audience: 'operator',
 		ctaMode: 'oss-next',
 	},
+	{
+		href: '/docs/integrations/gmail',
+		title: 'Gmail integration',
+		description:
+			'Ingest email threads through delta-aware provider contracts and governed outbound-send mutations.',
+		section: 'integrations',
+		order: 55,
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'oss-next',
+		aliases: ['email knowledge ingestion', 'Gmail delta sync'],
+	},
+	{
+		href: '/docs/integrations/google-drive',
+		title: 'Google Drive integration',
+		description:
+			'Ingest Drive files and watches through explicit cursor, webhook, replay, dedupe, and tombstone contracts.',
+		section: 'integrations',
+		order: 56,
+		primaryNav: true,
+		audience: 'operator',
+		ctaMode: 'oss-next',
+		aliases: [
+			'Drive knowledge ingestion',
+			'Google Drive watchChanges',
+			'ProviderDeltaSyncState',
+		],
+	},
 	{
 		href: '/docs/integrations/stripe',
 		title: 'Stripe integration',

package/src/components/docs/generated/docs-index._common.json

@@ -1392,6 +1392,22 @@
     "kind": "reference",
     "visibility": "public"
   },
+  {
+    "id": "docs.tech.contracts.knowledge-provider-backed",
+    "title": "Provider-backed knowledge",
+    "summary": "Provider-backed knowledge syncs Gmail and Google Drive through explicit provider delta and mutation governance evidence.",
+    "route": "/docs/tech/contracts/knowledge-provider-backed",
+    "source": "docblock",
+    "contentPath": "docblocks/docs/tech/contracts/knowledge-provider-backed.md",
+    "tags": [
+      "tech",
+      "contracts",
+      "knowledge",
+      "integrations"
+    ],
+    "kind": "reference",
+    "visibility": "public"
+  },
   {
     "id": "docs.tech.contracts.migrations",
     "title": "MigrationSpec Overview",
@@ -1482,6 +1498,22 @@
     "kind": "reference",
     "visibility": "public"
   },
+  {
+    "id": "docs.tech.contracts.pwa-updates",
+    "title": "PWA update management",
+    "summary": "Configure frontend update checks with app defaults and release overrides.",
+    "route": "/docs/tech/contracts/pwa-updates",
+    "source": "docblock",
+    "contentPath": "docblocks/docs/tech/contracts/pwa-updates.md",
+    "tags": [
+      "tech",
+      "contracts",
+      "pwa",
+      "updates"
+    ],
+    "kind": "reference",
+    "visibility": "public"
+  },
   {
     "id": "docs.tech.contracts.README",
     "title": "Contracts: Specs, Registry, Handlers, Adapters",

package/src/components/docs/generated/docs-index.manifest.json

@@ -1,13 +1,13 @@
 {
 	"generatedAt": "1970-01-01T00:00:00.000Z",
-	"total": 1143,
+	"total": 1145,
 	"version": null,
 	"contentRoot": "../../../../../../../generated/docs",
 	"chunks": [
 		{
 			"key": "_common",
 			"file": "docs-index._common.json",
-			"total": 181
+			"total": 183
 		},
 		{
 			"key": "agent-console",

package/src/components/docs/generated/docs-index.notifications.json

@@ -10,7 +10,7 @@
   {
     "id": "notifications/notifications.delete",
     "title": "notifications.delete",
-    "summary": "Delete a notification.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, delete\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "Delete a notification.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, delete\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.delete",
     "source": "generated",
     "contentPath": "notifications/notifications.delete.md"
@@ -18,7 +18,7 @@
   {
     "id": "notifications/notifications.list",
     "title": "notifications.list",
-    "summary": "List notifications for the current user.\n- **Type**: operation (query)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, list\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "List notifications for the current user.\n- **Type**: operation (query)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, list\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.list",
     "source": "generated",
     "contentPath": "notifications/notifications.list.md"
@@ -26,7 +26,7 @@
   {
     "id": "notifications/notifications.markAllRead",
     "title": "notifications.markAllRead",
-    "summary": "Mark all notifications as read.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, read\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "Mark all notifications as read.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, read\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.markAllRead",
     "source": "generated",
     "contentPath": "notifications/notifications.markAllRead.md"
@@ -34,7 +34,7 @@
   {
     "id": "notifications/notifications.markRead",
     "title": "notifications.markRead",
-    "summary": "Mark a notification as read.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, read\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "Mark a notification as read.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, read\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.markRead",
     "source": "generated",
     "contentPath": "notifications/notifications.markRead.md"
@@ -42,7 +42,7 @@
   {
     "id": "notifications/notifications.preferences.get",
     "title": "notifications.preferences.get",
-    "summary": "Get notification preferences for current user.\n- **Type**: operation (query)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, preferences, get\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "Get notification preferences for current user.\n- **Type**: operation (query)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, preferences, get\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.preferences.get",
     "source": "generated",
     "contentPath": "notifications/notifications.preferences.get.md"
@@ -50,7 +50,7 @@
   {
     "id": "notifications/notifications.preferences.update",
     "title": "notifications.preferences.update",
-    "summary": "Update notification preferences.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, preferences, update\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "Update notification preferences.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, preferences, update\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.preferences.update",
     "source": "generated",
     "contentPath": "notifications/notifications.preferences.update.md"
@@ -58,7 +58,7 @@
   {
     "id": "notifications/notifications.send",
     "title": "notifications.send",
-    "summary": "Send a notification to a user.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, send\n- **File**: `packages/libs/contracts-spec/src/notifications/contracts.ts`",
+    "summary": "Send a notification to a user.\n- **Type**: operation (command)\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: platform.notifications\n- **Tags**: notifications, send\n- **File**: `packages/modules/notifications/src/contracts/index.ts`",
     "route": "/docs/reference/notifications/notifications.send",
     "source": "generated",
     "contentPath": "notifications/notifications.send.md"

package/src/components/docs/guides/GuideProviderBackedKnowledgePage.tsx

@@ -0,0 +1,191 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+const evidenceChecklist = [
+	'ProviderDeltaSyncState persisted for each source after sync or watch renewal.',
+	'Tombstoned provider records are skipped before indexing or mutation.',
+	'Outbound mutations carry dry-run, approval, idempotency, audit, and send-gate evidence.',
+	'Connect adoption resolves existing knowledge and integration surfaces before new runtime code is added.',
+];
+
+export function GuideProviderBackedKnowledgePage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-3">
+				<h1 className="font-bold text-4xl">Adopt provider-backed knowledge</h1>
+				<p className="text-lg text-muted-foreground">
+					Turn Gmail and Google Drive into queryable knowledge without hiding
+					provider state, webhook expiry, or mutation risk in background jobs.
+					The contract layer models the source, the integration layer models
+					provider deltas, and the knowledge runtime owns ingestion/query
+					orchestration.
+				</p>
+			</div>
+
+			<div className="card-subtle space-y-4 p-6">
+				<h2 className="font-bold text-2xl">What you&apos;ll build</h2>
+				<ul className="space-y-2 text-muted-foreground text-sm">
+					<li>Gmail and Drive sources bound to explicit knowledge spaces.</li>
+					<li>
+						A checkpoint store for leases, cursors, webhook channel expiry, and
+						replay evidence.
+					</li>
+					<li>
+						A mutation gate that blocks unsafe external sends or provider
+						writes.
+					</li>
+					<li>
+						Connect adoption evidence proving you reused the existing
+						ContractSpec surfaces before adding custom provider code.
+					</li>
+				</ul>
+			</div>
+
+			<div className="space-y-6">
+				<section className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						1) Start from specs and sources
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						Define the knowledge space and source binding before runtime sync.
+						Provider credentials stay in integration connections; source config
+						stores only identity, scope, and replayable sync state.
+					</p>
+					<CodeBlock
+						language="typescript"
+						filename="knowledge-source.ts"
+						code={`const source = {
+  meta: {
+    id: "src_drive_support",
+    tenantId: "tenant-acme",
+    integrationConnectionId: "conn_google_drive",
+    spaceKey: "knowledge.support-faq",
+    spaceVersion: "1.0.0",
+    label: "Support Drive",
+    sourceType: "google_drive",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  },
+  syncState: {
+    cursorId: "drive-start-page-token",
+    watermarkVersion: "drive-v1",
+    lease: {
+      holder: "knowledge-sync-worker",
+      expiresAt: new Date(Date.now() + 5 * 60_000),
+      renewalWindowMs: 60_000,
+    },
+  },
+  config: {
+    query: "mimeType = 'text/plain' and trashed = false",
+  },
+};`}
+					/>
+				</section>
+
+				<section className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						2) Sync with checkpoints, not blind polling
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						`KnowledgeRuntime` can load a stored provider delta before listing
+						Gmail or Drive, then save the next checkpoint after indexing. The
+						store can be a database table, workflow state, or Connect-backed
+						replay artifact.
+					</p>
+					<CodeBlock
+						language="typescript"
+						filename="knowledge-runtime.ts"
+						code={`const knowledge = createKnowledgeRuntime({
+  collection: "knowledge-support",
+  namespace: "tenant-acme",
+  embeddings,
+  vectorStore,
+  gmail,
+  drive,
+  deltaCheckpointStore,
+});
+
+await knowledge.syncGmail(
+  { label: "support" },
+  { sourceId: "src_gmail_support", evidenceRef: "audit://sync/gmail" },
+);
+
+await knowledge.syncDriveFiles(
+  { query: "mimeType = 'text/plain' and trashed = false" },
+  { sourceId: "src_drive_support", evidenceRef: "audit://sync/drive" },
+);
+
+await knowledge.watchDriveChanges(
+  {
+    channelId: "drive-watch-support",
+    webhookUrl: "https://app.example.com/webhooks/google-drive",
+  },
+  { sourceId: "src_drive_support" },
+);`}
+					/>
+				</section>
+
+				<section className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						3) Gate mutations before provider writes
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						External sends and provider mutations should produce a decision
+						envelope whether they execute, block, or run as dry-run. Persist
+						that envelope with the same audit trail as the provider checkpoint.
+					</p>
+					<CodeBlock
+						language="typescript"
+						filename="governed-mutation.ts"
+						code={`const result = await knowledge.runGovernedMutation(
+  {
+    operation: "gmail.message.send",
+    sourceId: "src_gmail_support",
+    requiresApproval: true,
+    outboundSend: true,
+    governance: {
+      idempotencyKey: "tenant:gmail-send:123",
+      auditEvidence: { evidenceRef: "audit://gmail-send/123" },
+      approvalRefs: [{ id: "approval-123" }],
+      outboundSendGate: {
+        status: "approved",
+        evidenceRef: "gate://gmail-send/123",
+      },
+    },
+  },
+  () => gmail.sendEmail(message),
+  { audit: (envelope) => auditTrail.write(envelope) },
+);`}
+					/>
+				</section>
+
+				<section className="card-subtle space-y-3 p-6">
+					<h2 className="font-bold text-2xl">4) Adoption evidence</h2>
+					<ul className="space-y-2 text-muted-foreground text-sm">
+						{evidenceChecklist.map((item) => (
+							<li key={item}>{item}</li>
+						))}
+					</ul>
+					<CodeBlock
+						language="bash"
+						filename="connect-adoption"
+						code={`contractspec connect adoption sync --json
+
+printf '{"goal":"Wire provider-backed knowledge for Gmail and Drive"}' | \\
+  contractspec connect adoption resolve --family knowledge --stdin --json`}
+					/>
+				</section>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/knowledge/sources" className="btn-ghost">
+					Knowledge sources
+				</Link>
+				<Link href="/docs/integrations/google-drive" className="btn-primary">
+					Google Drive integration <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
+}

package/src/components/docs/guides/GuidesIndexPage.tsx

@@ -76,6 +76,13 @@ const guides = [
 		href: '/docs/guides/connect-in-a-repo',
 		time: '15 min',
 	},
+	{
+		title: 'Adopt provider-backed knowledge',
+		description:
+			'Sync Gmail and Google Drive into governed knowledge spaces with provider checkpoints, tombstones, and mutation gates.',
+		href: '/docs/guides/provider-backed-knowledge',
+		time: '30 min',
+	},
 	{
 		title: 'Author release capsules',
 		description:

package/src/components/docs/guides/guides.docblocks.ts

@@ -120,6 +120,26 @@ Use the generated manifest and chunks under \`docs-index.manifest.json\` and \`d
 
 Run ContractSpec CI checks to detect drift and breaking changes before merge.`,
 	},
+	{
+		id: 'docs.guides.provider-backed-knowledge',
+		title: 'Adopt provider-backed knowledge',
+		summary:
+			'Ingest Gmail and Google Drive with persisted deltas, replay checkpoints, tombstones, and mutation governance.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/provider-backed-knowledge',
+		tags: ['guides', 'knowledge', 'integrations', 'governance'],
+		body: `# Adopt provider-backed knowledge
+
+Use \`@contractspec/lib.knowledge\` with Gmail and Google Drive providers to sync external knowledge through explicit \`ProviderDeltaSyncState\` checkpoints.
+
+## Production baseline
+
+- Persist provider cursor, watermark, webhook, replay, dedupe, idempotency, and tombstone state per source.
+- Register \`knowledge.mutation.evaluateGovernance\` for mutation approval and audit evidence.
+- Gate outbound sends and provider mutations through dry-run, approval, idempotency, and audit checks.
+- Keep Connect review packets tied to the provider source and mutation evidence refs.`,
+	},
 ];
 
 registerDocBlocks(guideDocBlocks);

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

@@ -11,6 +11,7 @@ export { GuideGenerateDocsClientsSchemasPage } from './GuideGenerateDocsClientsS
 export { GuideHostBuilderWorkbenchPage } from './GuideHostBuilderWorkbenchPage';
 export { GuideImportExistingCodebasesPage } from './GuideImportExistingCodebasesPage';
 export { GuideNextjsOneEndpointPage } from './GuideNextjsOneEndpointPage';
+export { GuideProviderBackedKnowledgePage } from './GuideProviderBackedKnowledgePage';
 export { GuideReleaseCapsulesPage } from './GuideReleaseCapsulesPage';
 export { GuideSpecValidationTypingPage } from './GuideSpecValidationTypingPage';
 export { GuidesIndexPage } from './GuidesIndexPage';

package/src/components/docs/integrations/IntegrationsGmailPage.tsx

@@ -67,15 +67,36 @@ outputs:
 					<li>Extract attachments and process them</li>
 					<li>Build email-to-task workflows</li>
 					<li>Monitor specific email threads</li>
+					<li>Sync threads into governed knowledge spaces with checkpointed deltas</li>
 				</ul>
 			</div>
 
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Knowledge sync and mutation gates</h2>
+				<p className="text-muted-foreground">
+					Gmail supports the shared <code>provider.delta.watch</code>{' '}
+					capability. Knowledge runtimes should persist provider cursor,
+					watermark, dedupe, idempotency, replay, and tombstone state before
+					acknowledging sync work. Outbound email sends should pass through
+					knowledge mutation governance so dry-runs, approvals, audit evidence,
+					and outbound-send gates are recorded.
+				</p>
+				<div className="flex flex-wrap gap-3">
+					<Link href="/docs/guides/provider-backed-knowledge" className="btn-ghost">
+						Provider-backed knowledge guide
+					</Link>
+					<Link href="/docs/knowledge/governance" className="btn-ghost">
+						Mutation governance
+					</Link>
+				</div>
+			</div>
+
 			<div className="flex items-center gap-4 pt-4">
 				<Link href="/docs/integrations/resend" className="btn-ghost">
 					Previous: Resend
 				</Link>
-				<Link href="/docs/integrations/google-calendar" className="btn-primary">
-					Next: Google Calendar <ChevronRight size={16} />
+				<Link href="/docs/integrations/google-drive" className="btn-primary">
+					Next: Google Drive <ChevronRight size={16} />
 				</Link>
 			</div>
 		</div>

package/src/components/docs/integrations/IntegrationsGoogleCalendarPage.tsx

@@ -60,8 +60,8 @@ outputs:
 			</div>
 
 			<div className="flex items-center gap-4 pt-4">
-				<Link href="/docs/integrations/gmail" className="btn-ghost">
-					Previous: Gmail API
+				<Link href="/docs/integrations/google-drive" className="btn-ghost">
+					Previous: Google Drive
 				</Link>
 				<Link href="/docs/integrations/openai" className="btn-primary">
 					Next: OpenAI <ChevronRight size={16} />