@contractspec/bundle.library 0.0.0-canary-20260206014742

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

@@ -0,0 +1,96 @@
+// export const metadata: Metadata = {
+//   title: 'Multi-Tenancy Architecture | ContractSpec',
+//   description:
+//     'Learn how ContractSpec handles data isolation and tenant management.',
+// };
+
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function ArchitectureMultiTenancyPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Multi-Tenancy</h1>
+        <p className="text-muted-foreground">
+          ContractSpec is designed from the ground up for multi-tenancy. Apps
+          built with ContractSpec can serve multiple organizations (tenants)
+          from a single deployment, while ensuring strict data isolation and
+          configuration separation.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Core Concepts</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Tenant</strong>: An organization or customer that uses your
+            app. Each tenant has a unique <code>tenantId</code>.
+          </li>
+          <li>
+            <strong>Tenant Isolation</strong>: Data and configuration for one
+            tenant is never accessible to another tenant unless explicitly
+            shared.
+          </li>
+          <li>
+            <strong>Tenant Context</strong>: Every request and operation runs
+            within the context of a specific tenant.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Tenant Resolution</h2>
+        <p className="text-muted-foreground">
+          The runtime automatically resolves the tenant context for every
+          request based on:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Subdomain (e.g., <code>acme.app.com</code>)
+          </li>
+          <li>
+            Custom Domain (e.g., <code>portal.acme.com</code>)
+          </li>
+          <li>
+            Header (e.g., <code>x-tenant-id: acme-corp</code>)
+          </li>
+          <li>Authentication Token (embedded tenant claim)</li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Configuration Isolation</h2>
+        <p className="text-muted-foreground">
+          Each tenant has its own <code>TenantAppConfig</code> which defines:
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`type TenantAppConfig = {
+  tenantId: string;
+  blueprintId: string;
+  // ...
+  integrationBindings: AppIntegrationBinding[];
+  knowledgeBindings: AppKnowledgeBinding[];
+  featureFlags: Record<string, boolean>;
+};`}
+        />
+        <p className="text-muted-foreground mt-2">
+          This allows you to customize feature flags, integration connections,
+          and knowledge sources per tenant without changing the application
+          code.
+        </p>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/architecture" className="btn-ghost">
+          Back to Architecture
+        </Link>
+        <Link href="/docs/libraries/multi-tenancy" className="btn-primary">
+          Multi-Tenancy Library <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,268 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Architecture: ContractSpec Docs',
+//   description:
+//     "Understand ContractSpec's architecture: app configuration, integrations, knowledge, and runtime resolution.",
+// };
+
+export function ArchitectureOverviewPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Architecture</h1>
+        <p className="text-muted-foreground">
+          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.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Core layers</h2>
+        <div className="space-y-6">
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">1. Specification Layer</h3>
+            <p className="text-muted-foreground">
+              The foundation of ContractSpec. Typed specifications define what
+              your application can do:
+            </p>
+            <ul className="text-muted-foreground ml-4 list-inside list-disc space-y-2">
+              <li>
+                <Link
+                  href="/docs/specs/capabilities"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  CapabilitySpec
+                </Link>{' '}
+                - Operations and their inputs/outputs
+              </li>
+              <li>
+                <Link
+                  href="/docs/specs/dataviews"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  DataViewSpec
+                </Link>{' '}
+                - Data queries and presentation
+              </li>
+              <li>
+                <Link
+                  href="/docs/specs/workflows"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  WorkflowSpec
+                </Link>{' '}
+                - Multi-step processes
+              </li>
+              <li>
+                <Link
+                  href="/docs/specs/policy"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  PolicySpec
+                </Link>{' '}
+                - Access control and data protection
+              </li>
+              <li>
+                <Link
+                  href="/docs/integrations/spec-model"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  IntegrationSpec
+                </Link>{' '}
+                - External service providers
+              </li>
+              <li>
+                <Link
+                  href="/docs/knowledge/spaces"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  KnowledgeSpaceSpec
+                </Link>{' '}
+                - Knowledge and context management
+              </li>
+            </ul>
+          </div>
+
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">2. Configuration Layer</h3>
+            <p className="text-muted-foreground">
+              How applications are configured and customized:
+            </p>
+            <ul className="text-muted-foreground ml-4 list-inside list-disc space-y-2">
+              <li>
+                <Link
+                  href="/docs/architecture/app-config"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  AppBlueprintSpec
+                </Link>{' '}
+                - Global, versioned app definition
+              </li>
+              <li>
+                <Link
+                  href="/docs/architecture/app-config"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  TenantAppConfig
+                </Link>{' '}
+                - Per-tenant, per-environment configuration
+              </li>
+              <li>
+                <Link
+                  href="/docs/architecture/integration-binding"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  AppIntegrationBinding
+                </Link>{' '}
+                - How apps use integrations
+              </li>
+              <li>
+                <Link
+                  href="/docs/architecture/knowledge-binding"
+                  className="text-violet-400 hover:text-violet-300"
+                >
+                  AppKnowledgeBinding
+                </Link>{' '}
+                - How apps access knowledge
+              </li>
+            </ul>
+          </div>
+
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">3. Runtime Layer</h3>
+            <p className="text-muted-foreground">
+              How specifications are executed at runtime:
+            </p>
+            <ul className="text-muted-foreground ml-4 list-inside list-disc space-y-2">
+              <li>
+                <strong>ResolvedAppConfig</strong> - Merged blueprint + tenant
+                config
+              </li>
+              <li>
+                <strong>Policy Decision Point (PDP)</strong> - Enforces policies
+                on every operation
+              </li>
+              <li>
+                <strong>Presentation Runtime</strong> - React and React Native
+                renderers
+              </li>
+              <li>
+                <strong>Integration Connectors</strong> - Execute external API
+                calls
+              </li>
+              <li>
+                <strong>Knowledge Retrieval</strong> - Query vector databases
+                and knowledge sources
+              </li>
+            </ul>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Configuration model</h2>
+        <p className="text-muted-foreground">
+          ContractSpec uses a three-tier configuration model:
+        </p>
+        <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">Layer</th>
+                <th className="px-4 py-3 font-semibold">Type</th>
+                <th className="px-4 py-3 font-semibold">Scope</th>
+                <th className="px-4 py-3 font-semibold">Storage</th>
+              </tr>
+            </thead>
+            <tbody className="divide-border/50 divide-y">
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Blueprint</strong>
+                </td>
+                <td className="px-4 py-3 align-top font-mono text-xs">
+                  AppBlueprintSpec
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Global, versioned, no tenant info
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Version control, immutable
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Tenant Config</strong>
+                </td>
+                <td className="px-4 py-3 align-top font-mono text-xs">
+                  TenantAppConfig
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Per-tenant, per-environment
+                </td>
+                <td className="px-4 py-3 align-top">Database, mutable</td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Resolved Config</strong>
+                </td>
+                <td className="px-4 py-3 align-top font-mono text-xs">
+                  ResolvedAppConfig
+                </td>
+                <td className="px-4 py-3 align-top">Runtime, ephemeral</td>
+                <td className="px-4 py-3 align-top">
+                  In-memory, not persisted
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Key architectural principles</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Spec-first</strong> - Everything is defined declaratively
+            before code generation
+          </li>
+          <li>
+            <strong>Type-safe</strong> - All specifications are strongly typed
+            and validated at compile time
+          </li>
+          <li>
+            <strong>Policy-enforced</strong> - Every operation passes through
+            the PDP
+          </li>
+          <li>
+            <strong>Multi-tenant by default</strong> - Tenant isolation is
+            built-in, not bolted on
+          </li>
+          <li>
+            <strong>Environment-aware</strong> - Separate configurations for
+            sandbox, staging, production
+          </li>
+          <li>
+            <strong>Auditable</strong> - All operations are logged for
+            compliance and debugging
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/architecture/app-config" className="btn-primary">
+          App Configuration <ChevronRight size={16} />
+        </Link>
+        <Link href="/docs/integrations" className="btn-ghost">
+          Integrations
+        </Link>
+        <Link href="/docs/knowledge" className="btn-ghost">
+          Knowledge & Context
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,5 @@
+export { ArchitectureOverviewPage } from './ArchitectureOverviewPage';
+export { ArchitectureAppConfigPage } from './ArchitectureAppConfigPage';
+export { ArchitectureMultiTenancyPage } from './ArchitectureMultiTenancyPage';
+export { ArchitectureIntegrationBindingPage } from './ArchitectureIntegrationBindingPage';
+export { ArchitectureKnowledgeBindingPage } from './ArchitectureKnowledgeBindingPage';

package/src/components/docs/comparison/ComparisonAutomationPlatformsPage.tsx

@@ -0,0 +1,147 @@
+// export const metadata = {
+//   title: 'Automation Platforms Comparison: ContractSpec Docs',
+//   description:
+//     'Compare automation platforms like Zapier, Make, n8n, and Pipedream with ContractSpec.',
+// };
+
+export function ComparisonAutomationPlatformsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Automation platforms</h1>
+        <p className="text-muted-foreground">
+          Automation platforms connect apps and automate tasks through triggers
+          and actions. They serve operations and non-technical users well but
+          stop short of generating full applications or enforcing fine-grained
+          policies.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Feature comparison</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">Feature</th>
+                <th className="px-4 py-3 font-semibold">Zapier</th>
+                <th className="px-4 py-3 font-semibold">Make (Integromat)</th>
+                <th className="px-4 py-3 font-semibold">n8n</th>
+                <th className="px-4 py-3 font-semibold">Pipedream</th>
+              </tr>
+            </thead>
+            <tbody className="divide-border/50 divide-y">
+              <tr>
+                <td className="px-4 py-3 align-top font-semibold">
+                  Workflow model
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Zaps: trigger + one or more actions
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Real-time visual orchestration for AI agents and automations
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Node-based workflow builder with drag-and-drop and code; build
+                  multi-step AI agents
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Workflows connect any API; Pipedream Connect SDK adds
+                  integrations quickly
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top font-semibold">
+                  Visual builder?
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Yes (simple; web-based).
+                </td>
+                <td className="px-4 py-3 align-top">Yes; AI-assisted editor</td>
+                <td className="px-4 py-3 align-top">Yes; visual canvas.</td>
+                <td className="px-4 py-3 align-top">
+                  Code-centric editor; no visual UI builder
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top font-semibold">
+                  Self-host?
+                </td>
+                <td className="px-4 py-3 align-top">No (cloud only).</td>
+                <td className="px-4 py-3 align-top">Cloud only.</td>
+                <td className="px-4 py-3 align-top">Yes (Docker, self-host)</td>
+                <td className="px-4 py-3 align-top">Cloud only (hosted).</td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top font-semibold">
+                  Integrations &amp; AI
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Connects almost 8 000 apps; limited AI features.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  3 000+ pre-built apps; supports GenAI tools; GDPR/SOC2 and SSO
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Integrates LLMs; allows JS or Python code and library imports;
+                  chatbots with Slack/Teams
+                </td>
+                <td className="px-4 py-3 align-top">
+                  MCP servers add 3 000+ APIs and 10 000+ tools to agents; AI
+                  agent builder prompts and deploys agents; SOC 2/ HIPAA/GDPR
+                  compliant
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top font-semibold">
+                  Policy &amp; UI generation
+                </td>
+                <td className="px-4 py-3 align-top">
+                  No policy engine; does not generate user interfaces.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  No policy engine; does not generate UIs beyond a workflow
+                  dashboard.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  No policy engine; no UI builder
+                </td>
+                <td className="px-4 py-3 align-top">
+                  No policy engine; does not generate UI.
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Why ContractSpec differs</h2>
+        <ul className="text-muted-foreground space-y-2">
+          <li>
+            <strong>Full application generation</strong> – ContractSpec compiles
+            specs into back-end, events and user interfaces for both web and
+            mobile.
+          </li>
+          <li>
+            <strong>Policy enforcement</strong> – A built-in policy engine
+            governs PII access and mutations across the UI.
+          </li>
+          <li>
+            <strong>Customisation via overlays</strong> – Non-technical users
+            can safely personalise layouts while respecting policies.
+          </li>
+          <li>
+            <strong>Extensible capabilities</strong> – Connect to external APIs
+            and services via capability providers while maintaining type safety.
+          </li>
+        </ul>
+        <p className="text-muted-foreground">
+          Automation tools simplify integrations and tasks; ContractSpec goes
+          further by generating a complete, policy-safe application around your
+          data and processes.
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/comparison/ComparisonEnterprisePlatformsPage.tsx

@@ -0,0 +1,150 @@
+import Link from '@contractspec/lib.ui-link';
+
+// export const metadata = {
+//   title: 'Enterprise Orchestration Comparison: ContractSpec Docs',
+//   description:
+//     'See how Redwood RunMyJobs compares to ContractSpec for enterprise orchestration.',
+// };
+
+export function ComparisonEnterprisePlatformsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">
+          Enterprise orchestration platforms
+        </h1>
+        <p className="text-muted-foreground">
+          Enterprise orchestration platforms manage mission-critical workloads
+          and integrate deeply with ERP systems. They prioritise governance,
+          reliability and compliance, but they do not provide spec-driven app
+          generation or per-user customisation.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Redwood RunMyJobs</h2>
+        <p className="text-muted-foreground">
+          <Link
+            href="https://www.redwood.com/workload-automation/"
+            className="hover:text-foreground underline decoration-dotted underline-offset-4"
+            target="_blank"
+            rel="noreferrer"
+          >
+            RunMyJobs by Redwood
+          </Link>{' '}
+          is a cloud-native service orchestration and automation platform. Key
+          attributes include:
+        </p>
+        <ul className="text-muted-foreground space-y-2">
+          <li>
+            <strong>Self-service portal.</strong> Business users can run and
+            customise workloads while IT ensures governance and compliance
+          </li>
+          <li>
+            <strong>Full-stack orchestration.</strong> Integrates with both SAP
+            and non-SAP systems; Redwood is recognised as a Leader in Gartner’s
+            Magic Quadrant for service orchestration
+          </li>
+          <li>
+            <strong>Observability and AI insights.</strong> Dashboards and
+            AI-enhanced analytics identify bottlenecks and forecast issues
+          </li>
+          <li>
+            <strong>Deep SAP integration.</strong> Supports SAP’s latest
+            technologies and orchestrates mission-critical business processes
+          </li>
+          <li>
+            <strong>Connectors &amp; wizard.</strong> Provides pre-built
+            connectors and a wizard to link on-prem and cloud systems
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h3 className="text-xl font-semibold">Comparison with ContractSpec</h3>
+        <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">Aspect</th>
+                <th className="px-4 py-3 font-semibold">RunMyJobs</th>
+                <th className="px-4 py-3 font-semibold">ContractSpec</th>
+              </tr>
+            </thead>
+            <tbody className="divide-border/50 divide-y">
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Target user</strong>
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Enterprise IT and operations teams automating SAP and
+                  mission-critical workflows.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Developers, product teams and SMBs wanting to generate
+                  policy-safe apps with customisable UIs.
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Workload focus</strong>
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Service orchestration and job scheduling across ERP/legacy
+                  systems
+                </td>
+                <td className="px-4 py-3 align-top">
+                  End-to-end application generation with back-end, UI and
+                  policies.
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>User interface</strong>
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Self-service portal to run/monitor jobs; no custom UI
+                  generation for new apps.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Generates React/React-Native UIs from specs; users can
+                  personalise layout via overlays.
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Open source</strong>
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Proprietary SaaS; enterprise agreements.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Core compiler is proprietary; SDK and certain modules may be
+                  open-source; offers hosted and on-prem options.
+                </td>
+              </tr>
+              <tr>
+                <td className="px-4 py-3 align-top">
+                  <strong>Policy &amp; personalisation</strong>
+                </td>
+                <td className="px-4 py-3 align-top">
+                  IT controls governance; no per-user overlay concept.
+                </td>
+                <td className="px-4 py-3 align-top">
+                  Built-in policy engine and per-user overlays for safe
+                  personalisation.
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+        <p className="text-muted-foreground">
+          Redwood RunMyJobs is designed for orchestrating enterprise workloads
+          and SAP processes. ContractSpec targets a different problem:
+          generating complete applications from typed specs and letting end
+          users adapt them safely.
+        </p>
+      </div>
+    </div>
+  );
+}