@contractspec/bundle.library 3.8.9 → 3.8.11

package/src/components/docs/generated/docs-index.platform-provider-ranking.json

@@ -1,8 +1,96 @@
 [
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.custom.completed",
+		"title": "provider-ranking.benchmark.custom.completed",
+		"summary": "Emitted when a custom evaluation run completes execution.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.benchmark.custom.completed",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.custom.completed.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.ingest",
+		"title": "provider-ranking.benchmark.ingest",
+		"summary": "Imports and normalizes benchmark scores from external leaderboards.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.benchmark.ingest",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.ingest.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.ingested",
+		"title": "provider-ranking.benchmark.ingested",
+		"summary": "Emitted when external benchmark data is successfully imported and stored.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.benchmark.ingested",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.ingested.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.results.list",
+		"title": "provider-ranking.benchmark.results.list",
+		"summary": "Returns individual benchmark data points filterable by source, model, and dimension.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.benchmark.results.list",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.results.list.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.run-custom",
+		"title": "provider-ranking.benchmark.run-custom",
+		"summary": "Evaluates model performance using internal eval suites with configurable parameters.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.benchmark.run-custom",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.benchmark.run-custom.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.model.comparison",
+		"title": "provider-ranking.model.comparison",
+		"summary": "Presentation surface for comparing two or more models across all ranking dimensions.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.model.comparison",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.model.comparison.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.model.profile.get",
+		"title": "provider-ranking.model.profile.get",
+		"summary": "Returns comprehensive model information including scores, metadata, cost, context window, and capabilities.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.model.profile.get",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.model.profile.get.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.ranking.get",
+		"title": "provider-ranking.ranking.get",
+		"summary": "Returns a paginated, filterable leaderboard of AI models ranked by composite or per-dimension scores.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.ranking.get",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.ranking.get.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.ranking.refresh",
+		"title": "provider-ranking.ranking.refresh",
+		"summary": "Recomputes weighted composite scores across all dimensions and updates the leaderboard.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.ranking.refresh",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.ranking.refresh.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.ranking.updated",
+		"title": "provider-ranking.ranking.updated",
+		"summary": "Emitted when the leaderboard is refreshed with new composite scores.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.ranking.updated",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.ranking.updated.md"
+	},
+	{
+		"id": "platform.provider-ranking/docs.tech.provider-ranking.system",
+		"title": "AI Provider Ranking",
+		"summary": "Defines the core operations, events, and UI surfaces for ingesting benchmark data, computing composite rankings, and comparing AI models across dimensions.",
+		"route": "/docs/reference/platform.provider-ranking/docs.tech.provider-ranking.system",
+		"source": "generated",
+		"contentPath": "platform.provider-ranking/docs.tech.provider-ranking.system.md"
+	},
 	{
 		"id": "platform.provider-ranking/platform.provider-ranking",
 		"title": "platform.provider-ranking",
-		"summary": "Benchmark ingestion, custom benchmark runs, and AI model ranking with leaderboards\n- **Type**: feature\n- **Version**: 1.0.0\n- **File**: `packages/libs/contracts-spec/src/provider-ranking/provider-ranking.feature.ts`",
+		"summary": "Benchmark ingestion, custom benchmark runs, and AI model ranking with leaderboards\n- **Type**: feature\n- **Version**: 1.0.0\n- **Tags**: ai, ranking, benchmark\n- **File**: `packages/libs/contracts-spec/src/provider-ranking/provider-ranking.feature.ts`",
 		"route": "/docs/reference/platform.provider-ranking/platform.provider-ranking",
 		"source": "generated",
 		"contentPath": "platform.provider-ranking/platform.provider-ranking.md"

package/src/components/docs/generated/docs-index.pocket-family-office.json

@@ -1,4 +1,12 @@
 [
+	{
+		"id": "pocket-family-office/docs.tech.contracts.vertical-pocket-family-office",
+		"title": "Pocket Family Office Vertical",
+		"summary": "Pocket Family Office is a ContractSpec reference vertical that\ndemonstrates finance automation atop the integration and knowledge\nlayers. It is optimised for the hackathon stack (Google Cloud, Mistral,\nQdrant, ElevenLabs) while remaining provider-agnostic.",
+		"route": "/docs/reference/pocket-family-office/docs.tech.contracts.vertical-pocket-family-office",
+		"source": "generated",
+		"contentPath": "pocket-family-office/docs.tech.contracts.vertical-pocket-family-office.md"
+	},
 	{
 		"id": "pocket-family-office/pfo.documents.upload",
 		"title": "pfo.documents.upload",

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

@@ -159,6 +159,14 @@
 		"source": "generated",
 		"contentPath": "unknown/docs.system.md"
 	},
+	{
+		"id": "unknown/docs.tech.contracts.ops-to-presentation-linking",
+		"title": "unknown/docs.tech.contracts.ops-to-presentation-linking",
+		"summary": "This document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.\n- Location: `@contractspec/lib.contracts-spec/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`",
+		"route": "/docs/reference/unknown/docs.tech.contracts.ops-to-presentation-linking",
+		"source": "generated",
+		"contentPath": "unknown/docs.tech.contracts.ops-to-presentation-linking.md"
+	},
 	{
 		"id": "unknown/email.gmail",
 		"title": "email.gmail",

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

@@ -0,0 +1,184 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+const artifactPaths = [
+	'.contractspec/connect/context-pack.json',
+	'.contractspec/connect/plan-packet.json',
+	'.contractspec/connect/patch-verdict.json',
+	'.contractspec/connect/audit.ndjson',
+	'.contractspec/connect/decisions/<decisionId>/',
+];
+
+export function GuideConnectInRepoPage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-3">
+				<h1 className="font-bold text-4xl">Use Connect in a repo</h1>
+				<p className="text-lg text-muted-foreground">
+					Put coding-agent edits and shell commands behind task-scoped context,
+					plan compilation, verification, and local review evidence without
+					introducing a second control plane.
+				</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>A workspace-level Connect config in `.contractsrc.json`.</li>
+					<li>A context and plan flow for one task.</li>
+					<li>
+						Verified file and shell mutations with local review/replay evidence.
+					</li>
+				</ul>
+			</div>
+
+			<div className="space-y-6">
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">1) Enable Connect</h2>
+					<p className="text-muted-foreground text-sm">
+						Start by making the safety policy explicit. Protected paths,
+						generated paths, review thresholds, and command rules live in the
+						workspace config, not in editor-specific hooks.
+					</p>
+					<CodeBlock
+						language="json"
+						filename=".contractsrc.json"
+						code={`{
+  "connect": {
+    "enabled": true,
+    "storage": {
+      "root": ".contractspec/connect",
+      "contextPack": ".contractspec/connect/context-pack.json",
+      "planPacket": ".contractspec/connect/plan-packet.json",
+      "patchVerdict": ".contractspec/connect/patch-verdict.json",
+      "auditFile": ".contractspec/connect/audit.ndjson",
+      "reviewPacketsDir": ".contractspec/connect/review-packets"
+    },
+    "policy": {
+      "protectedPaths": ["packages/libs/contracts-spec/**"],
+      "generatedPaths": ["generated/**"],
+      "smokeChecks": ["bun run typecheck"],
+      "reviewThresholds": {
+        "protectedPathWrite": "require_review",
+        "breakingChange": "require_review",
+        "destructiveCommand": "deny"
+      }
+    },
+    "commands": {
+      "allow": ["bun run typecheck"],
+      "review": ["git push"],
+      "deny": ["git reset --hard", "git push --force", "rm -rf"]
+    }
+  }
+}`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: Connect has enough policy to classify writes,
+						commands, drift, and review thresholds deterministically.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">2) Initialize storage</h2>
+					<CodeBlock
+						language="bash"
+						filename="connect-init"
+						code={`contractspec connect init --scope workspace`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: `.contractsrc.json` is updated if needed and
+						`.contractspec/connect/` is created.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						3) Project context and compile a plan
+					</h2>
+					<p className="text-muted-foreground text-sm">
+						Use the task id as the thread that connects context, plan, verdict,
+						and replay artifacts.
+					</p>
+					<CodeBlock
+						language="bash"
+						filename="connect-plan"
+						code={`contractspec connect context \\
+  --task docs-connect \\
+  --paths packages/libs/contracts-spec/src/control-plane/contracts.ts \\
+  --json
+
+printf '{"objective":"Document the control-plane contract surface","commands":["bun run typecheck"]}' | \\
+  contractspec connect plan --task docs-connect --stdin --json`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: a `ContextPack` and `PlanPacket` that point back to
+						`controlPlane.intent.submit`, `controlPlane.plan.compile`, and
+						`controlPlane.plan.verify`.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						4) Verify file and shell mutations
+					</h2>
+					<CodeBlock
+						language="bash"
+						filename="connect-verify"
+						code={`printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | \\
+  contractspec connect verify --task docs-connect --tool acp.fs.access --stdin --json
+
+printf 'bun run typecheck' | \\
+  contractspec connect verify --task docs-connect --tool acp.terminal.exec --stdin --json`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: a `PatchVerdict` with `permit`, `rewrite`,
+						`require_review`, or `deny`, plus a runtime-linked control-plane
+						state when that linkage is available.
+					</p>
+				</div>
+
+				<div className="card-subtle space-y-3 p-6">
+					<h3 className="font-semibold text-lg">Artifacts to inspect</h3>
+					<ul className="space-y-2 text-muted-foreground text-sm">
+						{artifactPaths.map((path) => (
+							<li key={path}>
+								<code>{path}</code>
+							</li>
+						))}
+					</ul>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">
+						5) Review, replay, and optional Studio sync
+					</h2>
+					<CodeBlock
+						language="bash"
+						filename="connect-review-replay"
+						code={`contractspec connect review list --json
+contractspec connect replay <decisionId> --json
+contractspec connect eval <decisionId> --registry ./harness-registry.ts --scenario connect.safe-refactor --json
+
+# Optional when Studio review-bridge mode is enabled
+contractspec connect review sync --decision <decisionId> --json`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Local review packets remain authoritative. Studio sync is an
+						operator convenience layer, not a requirement for baseline OSS
+						safety.
+					</p>
+				</div>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/specs/connect" className="btn-primary">
+					Back to Connect spec <ChevronRight size={16} />
+				</Link>
+				<Link href="/docs/architecture/control-plane" className="btn-ghost">
+					Control-plane runtime
+				</Link>
+			</div>
+		</div>
+	);
+}

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

@@ -0,0 +1,182 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function GuideFirstModuleBundlePage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-3">
+				<h1 className="font-bold text-4xl">Build a first module bundle</h1>
+				<p className="text-lg text-muted-foreground">
+					Define one bundle spec, resolve it for a real route and preference
+					profile, then render the resulting surface plan through the React host
+					layer.
+				</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>One `ModuleBundleSpec` with a route and workbench surface.</li>
+					<li>One `ResolvedSurfacePlan` from `resolveBundle`.</li>
+					<li>One React host using `BundleProvider` and `BundleRenderer`.</li>
+				</ul>
+			</div>
+
+			<div className="space-y-6">
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">1) Define the bundle spec</h2>
+					<p className="text-muted-foreground text-sm">
+						The bundle spec is the durable contract. It owns route selection,
+						surface shape, layouts, data recipes, and verification coverage for
+						all seven preference dimensions.
+					</p>
+					<CodeBlock
+						language="typescript"
+						filename="src/bundles/support.workbench.bundle.ts"
+						code={`import { defineModuleBundle } from "@contractspec/lib.surface-runtime/spec/define-module-bundle";
+
+export const SupportWorkbenchBundle = defineModuleBundle({
+  meta: {
+    key: "support.workbench",
+    version: "0.1.0",
+    title: "Support Workbench",
+  },
+  routes: [
+    {
+      routeId: "support-ticket",
+      path: "/operate/support/tickets/:ticketId",
+      defaultSurface: "ticket-workbench",
+    },
+  ],
+  surfaces: {
+    "ticket-workbench": {
+      surfaceId: "ticket-workbench",
+      kind: "workbench",
+      slots: [
+        { slotId: "primary", role: "primary", accepts: ["entity-section"], cardinality: "many" },
+        { slotId: "assistant", role: "assistant", accepts: ["assistant-panel"], cardinality: "many", mutableByAi: true, mutableByUser: true },
+      ],
+      layouts: [
+        { layoutId: "balanced", title: "Balanced", root: { type: "slot", slotId: "primary" } },
+      ],
+      data: [
+        { recipeId: "ticket-core", source: { kind: "entity", entityType: "support.ticket" }, hydrateInto: "ticket" },
+      ],
+      verification: {
+        dimensions: {
+          guidance: "Surface can reveal walkthrough or inline help states.",
+          density: "Layout supports compact and balanced detail modes.",
+          dataDepth: "Resolver can hydrate summary or detailed ticket context.",
+          control: "Advanced actions stay policy-gated.",
+          media: "Surface supports text-first and hybrid assist modes.",
+          pace: "Transitions and confirmations adapt to operator pace.",
+          narrative: "Summary and evidence ordering stay explicit.",
+        },
+      },
+    },
+  },
+});`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: `defineModuleBundle` validates the route, surface,
+						and verification dimensions at runtime.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">2) Resolve the plan</h2>
+					<p className="text-muted-foreground text-sm">
+						Resolve against a real route, device, and preference profile. This
+						is where the runtime chooses the surface, layout, bindings, and
+						audit reasons.
+					</p>
+					<CodeBlock
+						language="typescript"
+						filename="src/runtime/resolve-support-workbench.ts"
+						code={`import { resolveBundle } from "@contractspec/lib.surface-runtime/runtime/resolve-bundle";
+
+export const supportWorkbenchPlan = await resolveBundle(
+  SupportWorkbenchBundle,
+  {
+    tenantId: "tenant_demo",
+    workspaceId: "workspace_ops",
+    actorId: "user_42",
+    route: "/operate/support/tickets/123",
+    params: { ticketId: "123" },
+    query: {},
+    device: "desktop",
+    locale: "en",
+    preferences: {
+      guidance: "hints",
+      density: "compact",
+      dataDepth: "detailed",
+      control: "advanced",
+      media: "hybrid",
+      pace: "balanced",
+      narrative: "top-down",
+    },
+    capabilities: ["tickets.read", "tickets.update"],
+  }
+);`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: a `ResolvedSurfacePlan` with `bundleKey`,
+						`surfaceId`, `layoutId`, `bindings`, `adaptation`, and audit
+						reasons.
+					</p>
+				</div>
+
+				<div className="space-y-3">
+					<h2 className="font-bold text-2xl">3) Render the plan</h2>
+					<p className="text-muted-foreground text-sm">
+						The host app renders the resolved plan, not the raw spec. That keeps
+						layout selection, overlays, and AI proposals downstream of the
+						declared bundle contract.
+					</p>
+					<CodeBlock
+						language="tsx"
+						filename="src/app/support/SurfaceHost.tsx"
+						code={`import { BundleProvider, BundleRenderer } from "@contractspec/lib.surface-runtime/react";
+
+export function SurfaceHost() {
+  return (
+    <BundleProvider plan={supportWorkbenchPlan}>
+      <BundleRenderer assistantSlotId="assistant" />
+    </BundleProvider>
+  );
+}`}
+					/>
+					<p className="text-muted-foreground text-sm">
+						Expected output: the route renders according to the resolved layout
+						root and slot plan instead of bespoke page assembly.
+					</p>
+				</div>
+
+				<div className="card-subtle space-y-3 p-6">
+					<h3 className="font-semibold text-lg">Verification checks</h3>
+					<ul className="space-y-2 text-muted-foreground text-sm">
+						<li>The resolved `surfaceId` matches the route you expected.</li>
+						<li>
+							The `layoutId` is stable for the active view and preferences.
+						</li>
+						<li>
+							The plan carries audit reasons and all seven adaptation
+							dimensions.
+						</li>
+						<li>Assistant or overlay work stays within declared slots.</li>
+					</ul>
+				</div>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/specs/module-bundles" className="btn-primary">
+					Back to module bundles <ChevronRight size={16} />
+				</Link>
+				<Link href="/docs/specs/overlays" className="btn-ghost">
+					Next: overlays
+				</Link>
+			</div>
+		</div>
+	);
+}