@contractspec/bundle.library 2.9.1 → 3.1.1

package/src/components/docs/architecture/ArchitectureControlPlanePage.tsx

@@ -0,0 +1,136 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function ArchitectureControlPlanePage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Control Plane Runtime</h1>
+        <p className="text-muted-foreground">
+          The control plane is the governance layer for agentic execution. It
+          turns incoming intent into deterministic plans, enforces risk policy
+          before side effects, and records replayable traces for audits.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Canonical execution loop</h2>
+        <ol className="text-muted-foreground list-inside list-decimal space-y-2">
+          <li>Accept intent and create execution identity + trace context.</li>
+          <li>Compile intent into a typed, deterministic plan DAG.</li>
+          <li>Verify plan against policy and risk rules.</li>
+          <li>Route into autonomous or assist mode based on verdict.</li>
+          <li>Execute steps with idempotent keys and explicit stage events.</li>
+          <li>Persist outcomes for replay, audits, and operator visibility.</li>
+        </ol>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Contract surfaces (v1 baseline)</h2>
+        <p className="text-muted-foreground">
+          The runtime is contract-first. Commands, queries, events, and
+          capabilities are explicit and versioned under
+          <code> @contractspec/lib.contracts-spec</code>.
+        </p>
+        <CodeBlock
+          language="text"
+          code={`Commands
+- controlPlane.intent.submit
+- controlPlane.plan.compile
+- controlPlane.plan.verify
+- controlPlane.execution.start
+- controlPlane.execution.approve
+- controlPlane.execution.reject
+- controlPlane.execution.cancel
+- controlPlane.skill.install
+- controlPlane.skill.disable
+
+Queries
+- controlPlane.execution.get
+- controlPlane.execution.list
+- controlPlane.trace.get
+- controlPlane.policy.explain
+- controlPlane.skill.list
+- controlPlane.skill.verify
+
+Events
+- controlPlane.intent.received
+- controlPlane.plan.compiled
+- controlPlane.plan.rejected
+- controlPlane.execution.step.started
+- controlPlane.execution.step.blocked
+- controlPlane.execution.step.completed
+- controlPlane.execution.completed
+- controlPlane.execution.failed
+- controlPlane.skill.installed
+- controlPlane.skill.rejected
+
+Capabilities
+- control-plane.core
+- control-plane.approval
+- control-plane.audit
+- control-plane.skill-registry
+- control-plane.channel-runtime`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Policy and safety posture</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            No side-effect action executes unless it comes from a compiled plan.
+          </li>
+          <li>High-risk actions are blocked from autonomous mode in v1.</li>
+          <li>
+            Approval commands provide explicit human-in-the-loop transitions.
+          </li>
+          <li>
+            Skill installation is modeled as governance-controlled operations.
+          </li>
+          <li>
+            Trace queries expose policy rationale and step outcomes for replay.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Implementation map</h2>
+        <CodeBlock
+          language="text"
+          code={`packages/libs/contracts-spec/src/control-plane/
+  commands/
+  queries/
+  events/
+  capabilities/
+  contracts.ts
+  contracts.test.ts
+
+packages/apps/web-landing/src/app/docs/architecture/control-plane/page.tsx
+implementation_plan_controle_plane.md`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">What comes next</h2>
+        <p className="text-muted-foreground">
+          WS1 delivers the contract fabric. Next increments add planner/executor
+          split, policy escalation, capability-bound authorization, signed skill
+          compatibility checks, and full replay tooling.
+        </p>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link
+          href="/docs/architecture/integration-binding"
+          className="btn-ghost"
+        >
+          Previous: Integration Binding
+        </Link>
+        <Link href="/docs/safety/auditing" className="btn-primary">
+          Audit Logs <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/architecture/ArchitectureOverviewPage.tsx

@@ -16,7 +16,7 @@ export function ArchitectureOverviewPage() {
           ContractSpec's architecture is built on a foundation of typed
           specifications served by runtime adapters. This section covers the
           core architectural concepts: app configuration, integration binding,
-          and knowledge management.
+          control-plane governance, and knowledge management.
         </p>
       </div>
 
@@ -146,6 +146,15 @@ export function ArchitectureOverviewPage() {
                 <strong>Policy Decision Point (PDP)</strong> - Enforces policies
                 on every operation
               </li>
+              <li>
+                <Link
+                  href="/docs/architecture/control-plane"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  Control Plane Runtime
+                </Link>{' '}
+                - Deterministic intent to plan to policy to execution loop
+              </li>
               <li>
                 <strong>Presentation Runtime</strong> - React and React Native
                 renderers
@@ -256,6 +265,9 @@ export function ArchitectureOverviewPage() {
         <Link href="/docs/architecture/app-config" className="btn-primary">
           App Configuration <ChevronRight size={16} />
         </Link>
+        <Link href="/docs/architecture/control-plane" className="btn-ghost">
+          Control Plane Runtime
+        </Link>
         <Link href="/docs/integrations" className="btn-ghost">
           Integrations
         </Link>

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

@@ -3,3 +3,4 @@ export { ArchitectureAppConfigPage } from './ArchitectureAppConfigPage';
 export { ArchitectureMultiTenancyPage } from './ArchitectureMultiTenancyPage';
 export { ArchitectureIntegrationBindingPage } from './ArchitectureIntegrationBindingPage';
 export { ArchitectureKnowledgeBindingPage } from './ArchitectureKnowledgeBindingPage';
+export { ArchitectureControlPlanePage } from './ArchitectureControlPlanePage';

package/src/components/docs/ecosystem/IntegrationsPage.tsx

@@ -34,7 +34,8 @@ bun add -D @contractspec/lib.plugin.example-generator`}
         <ul className="text-muted-foreground space-y-2 text-sm">
           <li>Payments: Stripe</li>
           <li>Email: Postmark, Gmail</li>
-          <li>Voice: ElevenLabs</li>
+          <li>AI: OpenAI, Mistral</li>
+          <li>Voice: ElevenLabs, Mistral</li>
           <li>Vector DB: Qdrant</li>
           <li>Storage: GCS</li>
         </ul>
@@ -45,10 +46,10 @@ bun add -D @contractspec/lib.plugin.example-generator`}
 
       <div className="flex items-center gap-4 pt-4">
         <Link href="/docs/ecosystem/registry" className="btn-primary">
-          Registry resolution <ChevronRight size={16} />
+          Marketplace manifest <ChevronRight size={16} />
         </Link>
         <Link href="/docs/ecosystem/templates" className="btn-ghost">
-          Plugin templates
+          Authoring templates
         </Link>
       </div>
     </div>

package/src/components/docs/ecosystem/PluginsPage.tsx

@@ -6,128 +6,109 @@ export function EcosystemPluginsPage() {
   return (
     <div className="space-y-8">
       <div className="space-y-3">
-        <h1 className="text-4xl font-bold">Plugin API</h1>
+        <h1 className="text-4xl font-bold">Cursor marketplace plugins</h1>
         <p className="text-muted-foreground text-lg">
-          Extend ContractSpec with generators, validators, adapters, formatters,
-          and registry resolvers.
+          ContractSpec ships a focused Cursor marketplace catalog for the
+          product and key libraries.
         </p>
       </div>
 
       <div className="card-subtle space-y-4 p-6">
-        <h2 className="text-2xl font-bold">Core capabilities</h2>
+        <h2 className="text-2xl font-bold">Catalog at a glance</h2>
         <ul className="text-muted-foreground space-y-2 text-sm">
-          <li>Generators for code, docs, and schemas.</li>
-          <li>Validators for policy checks and compliance gates.</li>
-          <li>Adapters for framework and runtime integration.</li>
-          <li>Formatters and diff renderers for deterministic output.</li>
-          <li>Registry resolvers for local and remote plugin discovery.</li>
+          <li>
+            <code>contractspec</code> - Product-level workflow and release
+            guardrails.
+          </li>
+          <li>
+            <code>contractspec-contracts-spec</code> -
+            <code>@contractspec/lib.contracts-spec</code> governance.
+          </li>
+          <li>
+            <code>contractspec-contracts-integrations</code> -
+            <code>@contractspec/lib.contracts-integrations</code> governance.
+          </li>
+          <li>
+            <code>contractspec-ai-agent</code> -
+            <code>@contractspec/lib.ai-agent</code> orchestration guardrails.
+          </li>
         </ul>
       </div>
 
       <div className="space-y-6">
         <div className="space-y-3">
-          <h2 className="text-2xl font-bold">Plugin interface</h2>
+          <h2 className="text-2xl font-bold">Where plugin sources live</h2>
           <p className="text-muted-foreground text-sm">
-            Define capabilities and lifecycle hooks in a single plugin
-            entrypoint.
+            Marketplace plugin sources are kept in a dedicated package so they
+            can evolve with the monorepo safely.
           </p>
           <CodeBlock
-            language="typescript"
-            filename="plugin.ts"
-            code={`import type {
-  ContractSpecPlugin,
-  PluginContext,
-  GeneratorCapability,
-} from "@contractspec/lib.plugins";
-
-export const MarkdownGeneratorPlugin: ContractSpecPlugin = {
-  meta: {
-    id: "markdown-generator",
-    version: "1.0.0",
-    type: "generator",
-    provides: ["docs"],
-  },
-  register(context: PluginContext) {
-    const generator: GeneratorCapability = {
-      id: "markdown",
-      description: "Generate Markdown docs",
-      generate: async (specs) => {
-        // Implementation...
-      },
-    };
-
-    context.generators.register(generator);
-  },
-};`}
-          />
-        </div>
-
-        <div className="space-y-3">
-          <h2 className="text-2xl font-bold">Lifecycle hooks</h2>
-          <p className="text-muted-foreground text-sm">
-            Use lifecycle hooks to configure, validate, and dispose resources.
-          </p>
-          <CodeBlock
-            language="typescript"
-            filename="lifecycle.ts"
-            code={`export const MarkdownGeneratorPlugin: ContractSpecPlugin = {
-  meta: {
-    id: "markdown-generator",
-    version: "1.0.0",
-    type: "generator",
-    provides: ["docs"],
-  },
-  register(context) {
-    // Register capabilities
-  },
-  configure(options, context) {
-    // Optional: apply workspace configuration
-  },
-  validate(specs, context) {
-    // Optional: add validation checks
-  },
-  generate(specs, context) {
-    // Required: emit outputs
-  },
-  dispose() {
-    // Optional: cleanup
-  },
-};`}
+            language="text"
+            filename="catalog-layout"
+            code={`packages/apps-registry/cursor-marketplace/
+  plugins/
+    contractspec/
+    contractspec-contracts-spec/
+    contractspec-contracts-integrations/
+    contractspec-ai-agent/`}
           />
         </div>
 
         <div className="space-y-3">
-          <h2 className="text-2xl font-bold">Register a plugin</h2>
+          <h2 className="text-2xl font-bold">Root marketplace manifest</h2>
           <p className="text-muted-foreground text-sm">
-            Configure plugins in <code>.contractsrc.json</code> to load them in
-            the CLI and runtime.
+            Cursor submission reads <code>.cursor-plugin/marketplace.json</code>{' '}
+            at repository root and resolves each plugin source path.
           </p>
           <CodeBlock
             language="json"
-            filename=".contractsrc.json"
+            filename=".cursor-plugin/marketplace.json"
             code={`{
+  "name": "contractspec-marketplace",
   "plugins": [
     {
-      "id": "markdown-generator",
-      "package": "@contractspec/plugin.markdown",
-      "capabilities": ["generator"],
-      "options": {
-        "outputDir": "./docs/generated",
-        "format": "table"
-      }
+      "name": "contractspec",
+      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec"
+    },
+    {
+      "name": "contractspec-contracts-spec",
+      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-contracts-spec"
+    },
+    {
+      "name": "contractspec-contracts-integrations",
+      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-contracts-integrations"
+    },
+    {
+      "name": "contractspec-ai-agent",
+      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-ai-agent"
     }
   ]
 }`}
           />
         </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Validation gate</h2>
+          <p className="text-muted-foreground text-sm">
+            Validate all marketplace plugins before publishing.
+          </p>
+          <CodeBlock
+            language="bash"
+            filename="validate-marketplace"
+            code={`bun run plugin:contractspec:validate
+
+# Optional when offline
+SKIP_PLUGIN_NETWORK_CHECK=1 bun run plugin:contractspec:validate`}
+          />
+        </div>
       </div>
 
       <div className="flex items-center gap-4 pt-4">
         <Link href="/docs/ecosystem/templates" className="btn-primary">
-          Plugin templates <ChevronRight size={16} />
+          Author a plugin <ChevronRight size={16} />
         </Link>
-        <Link href="/docs/ecosystem/integrations" className="btn-ghost">
-          Integrations
+        <Link href="/docs/ecosystem/registry" className="btn-ghost">
+          Manifest details
         </Link>
       </div>
     </div>

package/src/components/docs/ecosystem/RegistryPage.tsx

@@ -6,70 +6,62 @@ export function EcosystemRegistryPage() {
   return (
     <div className="space-y-8">
       <div className="space-y-3">
-        <h1 className="text-4xl font-bold">Registry resolution</h1>
+        <h1 className="text-4xl font-bold">Marketplace manifest</h1>
         <p className="text-muted-foreground text-lg">
-          Resolve plugins from local workspaces, npm packages, or remote
-          registries.
+          ContractSpec publishes a multi-plugin Cursor marketplace catalog from
+          a single root manifest.
         </p>
       </div>
 
       <div className="card-subtle space-y-4 p-6">
-        <h2 className="text-2xl font-bold">Resolution order</h2>
+        <h2 className="text-2xl font-bold">Root manifest shape</h2>
         <p className="text-muted-foreground text-sm">
-          Control where ContractSpec loads plugins and how versions are
-          resolved.
+          Cursor reads <code>.cursor-plugin/marketplace.json</code> at
+          repository root and resolves each plugin source path.
         </p>
         <CodeBlock
           language="json"
-          filename=".contractsrc.json"
+          filename=".cursor-plugin/marketplace.json"
           code={`{
+  "name": "contractspec-marketplace",
   "plugins": [
     {
-      "id": "markdown-generator",
-      "package": "@contractspec/plugin.markdown-generator",
-      "capabilities": ["generator"],
-      "options": {
-        "outputDir": "./docs/generated",
-        "format": "table"
-      }
-    }
-  ],
-  "pluginRegistry": {
-    "resolutionOrder": ["workspace", "npm", "remote"],
-    "allowPrerelease": false,
-    "sources": {
-      "remote": "https://registry.contractspec.io"
+      "name": "contractspec",
+      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec"
+    },
+    {
+      "name": "contractspec-contracts-spec",
+      "source": "packages/apps-registry/cursor-marketplace/plugins/contractspec-contracts-spec"
     }
-  }
+  ]
 }`}
         />
       </div>
 
       <div className="card-subtle space-y-4 p-6">
-        <h2 className="text-2xl font-bold">Custom registry resolvers</h2>
+        <h2 className="text-2xl font-bold">Per-plugin contract</h2>
         <p className="text-muted-foreground text-sm">
-          Register resolver plugins to load plugins from private registries.
+          Each plugin source must include a Cursor plugin manifest and
+          composable assets.
         </p>
         <CodeBlock
-          language="typescript"
-          filename="registry-resolver.ts"
-          code={`import type { RegistryResolverPlugin } from "@contractspec/lib.plugins";
+          language="text"
+          filename="plugin-layout"
+          code={`plugins/<plugin-name>/
+  .cursor-plugin/plugin.json
+  rules/
+  commands/
+  agents/
+  skills/
+  .mcp.json`}
+        />
+        <CodeBlock
+          language="bash"
+          filename="validate-catalog"
+          code={`bun run plugin:contractspec:validate
 
-export const PrivateRegistryResolver: RegistryResolverPlugin = {
-  meta: {
-    id: "private-registry",
-    version: "1.0.0",
-    type: "registryResolver",
-    provides: ["private-registry"],
-  },
-  resolve: async (request) => {
-    // Fetch plugin package metadata from private registry
-    const result = await fetch(
-      "https://registry.acme.io/" + request.package
-    );
-    return result.json();
-  },
-};`}
+# Optional in offline environments
+SKIP_PLUGIN_NETWORK_CHECK=1 bun run plugin:contractspec:validate`}
         />
       </div>
 
@@ -78,7 +70,7 @@ export const PrivateRegistryResolver: RegistryResolverPlugin = {
           Integrations <ChevronRight size={16} />
         </Link>
         <Link href="/docs/ecosystem/templates" className="btn-ghost">
-          Plugin templates
+          Plugin authoring templates
         </Link>
       </div>
     </div>

package/src/components/docs/ecosystem/TemplatesPage.tsx

@@ -7,47 +7,54 @@ export function EcosystemTemplatesPage() {
   return (
     <div className="space-y-8">
       <div className="space-y-3">
-        <h1 className="text-4xl font-bold">Plugin templates</h1>
+        <h1 className="text-4xl font-bold">Plugin authoring templates</h1>
         <p className="text-muted-foreground text-lg">
-          Scaffold new plugins with create-contractspec-plugin.
+          Scaffold focused Cursor plugins for ContractSpec product and core
+          libraries.
         </p>
       </div>
 
       <div className="card-subtle space-y-4 p-6">
-        <h2 className="text-2xl font-bold">Create a new plugin</h2>
+        <h2 className="text-2xl font-bold">Create a focused plugin</h2>
         <p className="text-muted-foreground text-sm">
-          Generate a plugin scaffold with tests, documentation, and CI wiring.
+          Start from a scoped domain and keep each plugin aligned to one product
+          or library surface.
         </p>
         <CodeBlock
           language="bash"
-          filename="create-plugin"
-          code={`bunx create-contractspec-plugin create \\
-  --name markdown-generator \\
-  --description "Markdown docs generator" \\
-  --author "Your name"`}
+          filename="catalog-authoring-layout"
+          code={`packages/apps-registry/cursor-marketplace/
+  plugins/
+    <plugin-name>/
+      .cursor-plugin/plugin.json
+      rules/
+      commands/
+      agents/
+      skills/
+      .mcp.json`}
         />
       </div>
 
       <div className="card-subtle space-y-4 p-6">
         <h2 className="text-2xl font-bold">Template outputs</h2>
         <ul className="text-muted-foreground space-y-2 text-sm">
-          <li>src/generator.ts, src/types.ts, src/config.ts</li>
-          <li>tests/ with sample fixtures</li>
-          <li>.github/workflows/ci.yml</li>
-          <li>README.md with usage instructions</li>
+          <li>.cursor-plugin/plugin.json with plugin metadata and paths</li>
+          <li>rules/, commands/, agents/, and skills/ content directories</li>
+          <li>.mcp.json with all MCP server declarations used by the plugin</li>
+          <li>README.md describing scope and governance boundaries</li>
         </ul>
       </div>
 
       <div className="card-subtle space-y-4 p-6">
-        <h2 className="text-2xl font-bold">Publish and install</h2>
+        <h2 className="text-2xl font-bold">Validate before submission</h2>
         <CodeBlock
           language="bash"
-          filename="publish-plugin"
-          code={`bun run build
-bun publish
+          filename="validate-marketplace-catalog"
+          code={`# Validate all plugins referenced by root marketplace manifest
+bun run plugin:contractspec:validate
 
-# install in a ContractSpec workspace
-bun add @contractspec/integration.markdown-generator`}
+# Optional in offline environments
+SKIP_PLUGIN_NETWORK_CHECK=1 bun run plugin:contractspec:validate`}
         />
       </div>
 
@@ -58,10 +65,10 @@ bun add @contractspec/integration.markdown-generator`}
 
       <div className="flex items-center gap-4 pt-4">
         <Link href="/docs/ecosystem/plugins" className="btn-primary">
-          Plugin API <ChevronRight size={16} />
+          Marketplace plugins <ChevronRight size={16} />
         </Link>
         <Link href="/docs/ecosystem/registry" className="btn-ghost">
-          Registry resolution
+          Marketplace manifest
         </Link>
       </div>
     </div>

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

@@ -4,15 +4,16 @@ import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
 const ecosystemDocBlocks: DocBlock[] = [
   {
     id: 'docs.ecosystem.plugins',
-    title: 'Plugin API',
-    summary: 'Build generators, validators, adapters, and registry resolvers.',
+    title: 'Marketplace plugins',
+    summary:
+      'Focused Cursor marketplace plugins for product and core libraries.',
     kind: 'usage',
     visibility: 'public',
     route: '/docs/ecosystem/plugins',
     tags: ['ecosystem', 'plugins', 'extensions'],
-    body: `# Plugin API
+    body: `# Marketplace plugins
 
-ContractSpec plugins extend the platform with generators, validators, adapters, formatters, and registry resolvers. Define capabilities in code, register them through configuration, and ship reusable packages.`,
+ContractSpec ships a focused Cursor marketplace catalog with plugins for the product and key libraries. Plugin sources live in \`packages/apps-registry/cursor-marketplace/plugins/*\`, while the root manifest at \`.cursor-plugin/marketplace.json\` drives submission.`,
   },
   {
     id: 'docs.ecosystem.integrations',
@@ -28,24 +29,25 @@ Reference integrations demonstrate how to extend ContractSpec with real-world pl
   },
   {
     id: 'docs.ecosystem.templates',
-    title: 'Plugin templates',
-    summary: 'Scaffold new plugins with create-contractspec-plugin.',
+    title: 'Plugin authoring templates',
+    summary:
+      'Author focused plugins with a consistent marketplace-ready layout.',
     kind: 'usage',
     visibility: 'public',
     route: '/docs/ecosystem/templates',
     tags: ['ecosystem', 'templates'],
-    body: '# Plugin templates\n\nUse `create-contractspec-plugin` to scaffold a new plugin package with tests, documentation, and CI wiring.',
+    body: '# Plugin authoring templates\n\nCreate each plugin under `packages/apps-registry/cursor-marketplace/plugins/<plugin-name>/` and include `.cursor-plugin/plugin.json`, `rules/`, `commands/`, `agents/`, `skills/`, and `.mcp.json`.',
   },
 
   {
     id: 'docs.ecosystem.registry',
-    title: 'Registry resolution',
-    summary: 'Discover plugins locally or from remote registries.',
+    title: 'Marketplace manifest',
+    summary: 'Manage and validate root marketplace entries for all plugins.',
     kind: 'usage',
     visibility: 'public',
     route: '/docs/ecosystem/registry',
     tags: ['ecosystem', 'registry'],
-    body: '# Registry resolution\n\nPlugins can be resolved from local workspaces, npm packages, or remote registries. Configure resolution order in `.contractsrc.json` and use registry resolver plugins for custom sources.',
+    body: '# Marketplace manifest\n\nKeep all plugin entries in `.cursor-plugin/marketplace.json` and validate them with `bun run plugin:contractspec:validate` before submission.',
   },
 ];