@lssm/example.crm-pipeline 0.0.0-canary-20251217060834 → 0.0.0-canary-20251217072406

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/studio/project-access-teams.docblock.js

@@ -0,0 +1,44 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/studio/project-access-teams.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.studio.project-access-teams",
+	title: "Studio Project Access via Teams",
+	summary: "Projects live under organizations; team sharing refines access with an admin/owner override.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/project-access-teams",
+	tags: [
+		"studio",
+		"projects",
+		"teams",
+		"rbac",
+		"access-control"
+	],
+	body: `# Studio Project Access via Teams
+
+Studio access control is **organization-first** with optional **team-based sharing**.
+
+## Data model
+
+- \`Team\` and \`TeamMember\` define team membership inside an organization.
+- \`StudioProject\` is owned by an organization.
+- \`StudioProjectTeam\` links projects to 0..N teams.
+
+## Access rules
+
+- **Admins/owners**: always have access to all projects in the organization.
+- **Org-wide projects**: if a project has **no team links**, all organization members can access it.
+- **Team-scoped projects**: if a project has **one or more team links**, a user must be a member of at least one linked team.
+
+## GraphQL surfaces
+
+- Read:\n  - \`myStudioProjects\` (returns only projects you can access)\n  - \`studioProjectBySlug(slug)\` (enforces the same access rules)\n  - \`myTeams\`\n  - \`projectTeams(projectId)\`\n\n- Write:\n  - \`createStudioProject(input.teamIds?)\` (teamIds optional)\n  - \`setProjectTeams(projectId, teamIds)\` (admin-only)\n
+## Related\n+\n+- Team administration + invitations: see \`/docs/tech/studio/team-invitations\`.\n+
+## Notes
+
+Payloads and events must avoid secrets/PII. For Sandbox, the model remains local-first and unlogged.
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/studio/project-routing.docblock.js

@@ -0,0 +1,66 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/studio/project-routing.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.studio.project-routing",
+	title: "Studio Project Routing",
+	summary: "Studio uses slugged, project-first routes: /studio/{projectSlug}/* with canonical slug redirects and soft-deleted projects hidden.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/project-routing",
+	tags: [
+		"studio",
+		"routing",
+		"projects",
+		"slug",
+		"redirects"
+	],
+	body: `# Studio Project Routing
+
+ContractSpec Studio uses a **project-first URL scheme**:
+
+- \`/studio/projects\` — create, select, and delete projects.
+- \`/studio/{projectSlug}/*\` — project modules (canvas/specs/deploy/integrations/evolution/learning).
+- \`/studio/learning\` — learning hub that does not require selecting a project.
+
+## Studio layout shell
+
+Studio routes are wrapped in a dedicated **Studio app shell** (header + footer) that provides in-app navigation (Projects/Learning/Teams), organization switching, and account actions.
+
+Project module routes (\`/studio/{projectSlug}/*\`) render their own module shell (\`WorkspaceProjectShellLayout\`). When combined with the global Studio header, the project shell uses a **sticky header offset** to avoid overlapping sticky headers.
+
+## Slug behavior (rename-safe)
+
+- Each project has a \`slug\` stored in the database (\`StudioProject.slug\`).
+- When a project name changes, Studio **updates the slug** and stores the previous slug as an alias (\`StudioProjectSlugAlias\`).
+- Requests to an alias slug are **redirected to the canonical slug**.
+
+GraphQL entrypoint:
+
+- \`studioProjectBySlug(slug: String!)\` returns:
+  - \`project\`
+  - \`canonicalSlug\`
+  - \`wasRedirect\`
+
+## Deletion behavior (soft delete)
+
+Projects are **soft-deleted**:
+
+- \`deleteStudioProject(id: String!)\` sets \`StudioProject.deletedAt\`.
+- All listings and access checks filter \`deletedAt = null\`.
+- Soft-deleted projects are treated as “not found” in Studio routes and GraphQL access checks.
+
+## Available modules for a selected project
+
+The following project modules are expected under \`/studio/{projectSlug}\`:
+
+- \`/canvas\` — Visual builder canvas (stored via overlays and canvas versions).
+- \`/specs\` — Spec editor (stored as \`StudioSpec\`).
+- \`/deploy\` — Deployments history + triggers (stored as \`StudioDeployment\`).
+- \`/integrations\` — Integrations scoped to project (stored as \`StudioIntegration\`).
+- \`/evolution\` — Evolution sessions (stored as \`EvolutionSession\`).
+- \`/learning\` — Project learning activity.
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/studio/sandbox-unlogged.docblock.js

@@ -0,0 +1,39 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/studio/sandbox-unlogged.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.studio.sandbox.unlogged",
+	title: "Sandbox (unlogged) vs Studio (authenticated)",
+	summary: "The sandbox is a lightweight, unlogged surface that mirrors Studio navigation without auth or analytics.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/sandbox-unlogged",
+	tags: [
+		"studio",
+		"sandbox",
+		"privacy",
+		"analytics"
+	],
+	body: `## Sandbox guarantees
+
+- Route: \`/sandbox\`
+- **No auth requirement**
+- **No PostHog init**
+- **No Vercel Analytics**
+- Local-only state (in-browser runtime + localStorage where needed)
+
+## What Sandbox is for
+
+- Try templates and feature modules safely
+- Preview specs/builder/evolution/learning
+- Produce copyable CLI commands (no side effects)
+
+## What Sandbox is *not* for
+
+- Persisted projects/workspaces
+- Real deployments
+- Organization-scoped integrations (unless explicitly enabled later)
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/studio/team-invitations.docblock.js

@@ -0,0 +1,68 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/studio/team-invitations.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.studio.team-invitations",
+	title: "Studio Teams & Invitations",
+	summary: "Admin-only team management and email invitation flow to join an organization and optionally a team.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/team-invitations",
+	tags: [
+		"studio",
+		"teams",
+		"invitations",
+		"access-control",
+		"onboarding"
+	],
+	body: `# Studio Teams & Invitations
+
+Studio uses **organization membership** as the base access model. Teams are optional and used to refine access to projects.
+
+## Who can manage teams?
+
+- **Admins/owners only**: create, rename, delete teams; manage project team access; issue invitations.
+
+## Invitation data model
+
+- \`Invitation\` rows are stored under an organization and target an **email** address.\n
+- An invitation can optionally target a \`teamId\`, which will grant the user membership in that team upon acceptance.
+
+Key fields:
+- \`email\`: invited address (must match the accepting user's account email)\n
+- \`status\`: \`pending | accepted | declined | expired\`\n
+- \`teamId?\`: optional team to join\n
+- \`inviterId\`: user who issued the invitation
+
+## GraphQL surfaces
+
+- Team CRUD (admin-only):\n
+  - \`createTeam(name)\`\n
+  - \`renameTeam(teamId, name)\`\n
+  - \`deleteTeam(teamId)\`\n
+
+- Invitations (admin-only):\n
+  - \`organizationInvitations\`\n
+  - \`inviteToOrganization(email, role?, teamId?)\` → returns \`inviteUrl\` and whether an email was sent
+
+## Accepting an invitation
+
+The invite link is served as:\n
+- \`/invite/{invitationId}\`
+
+Acceptance rules:
+- The user must be authenticated.\n
+- The authenticated user’s email must match \`Invitation.email\`.\n
+- If not already a member, create \`Member(userId, organizationId, role)\`.\n
+- If \`teamId\` is present, ensure \`TeamMember(teamId, userId)\`.\n
+- Mark invitation \`status='accepted'\` and set \`acceptedAt\`.\n
+- Set \`activeOrganizationId\` for the session so \`/studio/*\` routes work immediately.
+
+## Email delivery
+
+- If \`RESEND_API_KEY\` is set, the system attempts to send an email.\n
+- Otherwise, the UI uses the returned \`inviteUrl\` for manual copy/share.
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/studio/workspace-ops.docblock.js

@@ -0,0 +1,46 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/studio/workspace-ops.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.studio.workspace_ops",
+	title: "Workspace ops (repo-linked): list / validate / deps / diff",
+	summary: "Read-only repo operations used by Studio to inspect and validate a linked ContractSpec workspace.",
+	kind: "reference",
+	visibility: "mixed",
+	route: "/docs/tech/studio/workspace-ops",
+	tags: [
+		"studio",
+		"repo",
+		"workspace",
+		"validate",
+		"diff"
+	],
+	body: `## API surface (api-contractspec)
+
+Base: \`/api/workspace-ops\`
+
+These endpoints are **read-only** in v1 and never push to git:
+
+- \`GET /api/workspace-ops/:integrationId/config?organizationId=\`
+- \`GET /api/workspace-ops/:integrationId/specs?organizationId=\`
+- \`POST /api/workspace-ops/:integrationId/validate\` (body: organizationId, files?, pattern?)
+- \`POST /api/workspace-ops/:integrationId/deps\` (body: organizationId, pattern?)
+- \`POST /api/workspace-ops/:integrationId/diff\` (body: organizationId, specPath, baseline?, breakingOnly?)
+
+## Repo resolution
+
+- The repo root is resolved from the Studio Integration (\`IntegrationProvider.GITHUB\`) config:
+  - \`config.repoCachePath\` (preferred) or \`config.localPath\`
+- Resolution is constrained to \`CONTRACTSPEC_REPO_CACHE_DIR\` (default: \`/tmp/contractspec-repos\`)
+
+## Intended UX
+
+- Studio Assistant can run these checks and present results as suggestions.
+- Users can copy equivalent CLI commands for local runs:
+  - \`contractspec validate\`
+  - \`contractspec deps\`
+  - \`contractspec diff --baseline <ref>\`
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/studio/workspaces.docblock.js

@@ -0,0 +1,61 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/studio/workspaces.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.studio.workspaces",
+	title: "Studio projects, teams, environments",
+	summary: "Organization-first Studio: projects live under an organization; teams refine access; projects deploy to multiple environments.",
+	kind: "reference",
+	visibility: "mixed",
+	route: "/docs/tech/studio/workspaces",
+	tags: [
+		"studio",
+		"projects",
+		"teams",
+		"rbac",
+		"environments"
+	],
+	body: `## Concepts
+
+- **Organization**: the primary grouping boundary for Studio projects.
+- **Project**: one application (specs, overlays, deployments, integrations, evolution, learning).
+- **Team**: refines who can see/edit a project within an organization.
+- **Environment**: deployment target (Development / Staging / Production).
+
+## Project access (teams + admin override)
+
+Studio uses multi-team sharing to refine access:
+
+- **Admins/owners** can access all projects.
+- If a project is shared with **no teams**, it is **org-wide** (all org members).
+- If a project is shared with **one or more teams**, it is visible to:
+  - admins/owners, and
+  - members of any linked team.
+
+## Current persistence (DB + GraphQL)
+
+- DB (Prisma): \`StudioProject\`, \`Team\`, \`TeamMember\`, \`StudioProjectTeam\`
+- GraphQL:
+  - \`myStudioProjects\`
+  - \`createStudioProject(input.teamIds?)\`
+  - \`myTeams\`
+  - \`projectTeams(projectId)\`
+  - \`setProjectTeams(projectId, teamIds)\`
+
+## UI shell behavior
+
+Studio and Sandbox both use a shared shell:
+
+- Project selector → Module navigation → Environment selector
+- Always-on Assistant button (floating)
+- Learning journey progress (Studio persists learning events; Sandbox stays local-only)
+
+## Routing
+
+- \`/studio/projects\`: create/select/delete projects (organization-first).
+- \`/studio/{projectSlug}/*\`: project modules (canvas/specs/deploy/integrations/evolution/learning).
+- \`/studio/learning\`: learning hub without selecting a project.
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/telemetry-ingest.docblock.js

@@ -0,0 +1,154 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/telemetry-ingest.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.telemetry.ingest",
+	title: "Telemetry Ingest Endpoint",
+	summary: "Server-side telemetry ingestion for ContractSpec clients (VS Code extension, CLI, etc.).",
+	kind: "reference",
+	visibility: "internal",
+	route: "/docs/tech/telemetry/ingest",
+	tags: [
+		"telemetry",
+		"api",
+		"posthog",
+		"analytics"
+	],
+	body: `# Telemetry Ingest Endpoint
+
+The ContractSpec API provides a telemetry ingest endpoint for clients to send product analytics events.
+
+## Endpoint
+
+\`\`\`
+POST /api/telemetry/ingest
+\`\`\`
+
+## Request
+
+\`\`\`json
+{
+  "event": "contractspec.vscode.command_run",
+  "distinct_id": "client-uuid",
+  "properties": {
+    "command": "validate"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+\`\`\`
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| \`x-contractspec-client-id\` | Optional client identifier (used as fallback for distinct_id) |
+| \`Content-Type\` | Must be \`application/json\` |
+
+### Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`event\` | string | Yes | Event name (e.g., \`contractspec.vscode.activated\`) |
+| \`distinct_id\` | string | Yes | Anonymous client identifier |
+| \`properties\` | object | No | Event properties |
+| \`timestamp\` | string | No | ISO 8601 timestamp |
+
+## Response
+
+\`\`\`json
+{
+  "success": true
+}
+\`\`\`
+
+## Configuration
+
+The endpoint requires \`POSTHOG_PROJECT_KEY\` environment variable to be set. If not configured, events are accepted but not forwarded.
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| \`POSTHOG_HOST\` | PostHog host URL | \`https://eu.posthog.com\` |
+| \`POSTHOG_PROJECT_KEY\` | PostHog project API key | (required) |
+
+## Privacy
+
+- No PII is collected or stored
+- \`distinct_id\` is an anonymous client-generated UUID
+- File paths and source code are never included in events
+- Respects VS Code telemetry settings on the client side
+
+## Events
+
+### Extension Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.vscode.activated\` | Extension activated | \`version\` |
+| \`contractspec.vscode.command_run\` | Command executed | \`command\` |
+| \`contractspec.vscode.mcp_call\` | MCP call made | \`endpoint\`, \`tool\` |
+
+### API Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.api.mcp_request\` | MCP request processed | \`endpoint\`, \`method\`, \`success\`, \`duration_ms\` |
+`
+}, {
+	id: "docs.tech.telemetry.hybrid",
+	title: "Hybrid Telemetry Model",
+	summary: "How ContractSpec clients choose between direct PostHog and API-routed telemetry.",
+	kind: "usage",
+	visibility: "internal",
+	route: "/docs/tech/telemetry/hybrid",
+	tags: [
+		"telemetry",
+		"architecture",
+		"posthog"
+	],
+	body: `# Hybrid Telemetry Model
+
+ContractSpec uses a hybrid telemetry model where clients can send events either directly to PostHog or via the API server.
+
+## Decision Flow
+
+\`\`\`
+Is contractspec.api.baseUrl configured?
+├── Yes → Send via /api/telemetry/ingest
+└── No → Is posthogProjectKey configured?
+    ├── Yes → Send directly to PostHog
+    └── No → Telemetry disabled
+\`\`\`
+
+## Benefits
+
+### Direct PostHog
+- No server dependency
+- Works offline (with batching)
+- Lower latency
+
+### Via API
+- Centralized key management (no client-side keys)
+- Server-side enrichment and validation
+- Rate limiting and abuse prevention
+- Easier migration to other providers
+
+## Recommendation
+
+- **Development**: Use direct PostHog with a dev project key
+- **Production**: Route via API for better governance
+
+## Future: OpenTelemetry
+
+The current PostHog implementation is behind a simple interface that can be swapped for OpenTelemetry:
+
+\`\`\`typescript
+interface TelemetryClient {
+  send(event: TelemetryEvent): Promise<void>;
+}
+\`\`\`
+
+This allows future migration without changing client code.
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/templates/runtime.docblock.js

@@ -0,0 +1,19 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/templates/runtime.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.templates.runtime",
+	title: "ContractSpec Template Runtime (Phase 9)",
+	summary: "Phase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/templates/runtime",
+	tags: [
+		"tech",
+		"templates",
+		"runtime"
+	],
+	body: "## ContractSpec Template Runtime (Phase 9)\n\nPhase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.\n\n### Building Blocks\n\n- **Local database** – `@lssm/lib.runtime-local` wraps `sql.js` (SQLite WASM) and `IndexedDB` so we can seed demo data, run migrations, and persist state between sessions. Tests point the runtime to `node_modules/sql.js/dist` so CI doesn’t need a browser.\n- **Local GraphQL** – `LocalGraphQLClient` wires Apollo Client + SchemaLink to resolvers for tasks, messaging, and i18n recipes. All `/templates`, `/studio`, and `/sandbox` previews use those resolvers so we never call remote APIs during demos.\n- **Template registry + installer** – `.../templates/registry.ts` stores the catalog (todos, messaging, recipes). `TemplateInstaller` can seed the runtime (`install`) or export a base64 snapshot via the new `saveTemplateToStudio` mutation.\n- **TemplateShell** – Shared UI wrapper that creates a `TemplateRuntimeProvider`, shows `LocalDataIndicator`, and (optionally) surfaces the new `SaveToStudioButton`.\n\n### Runtime Flows\n\n1. `/templates` now opens a modal that renders `TemplateShell` for each template. Users can explore without leaving the marketing site.\n2. `/studio` switches to a tabbed mini-app (Projects, Canvas, Specs, Deploy) to showcase Studio surfaces with mock data. Visitors see a **preview** shell, while authenticated users (Better Auth via Sigil) unlock full persistence, versioning, and deployment controls.\n3. `/sandbox` lets visitors pick a template and mode (Playground, Spec Editor, Visual Builder). The console at the bottom streams runtime events for transparency.\n\n### GraphQL Mutations\n\n- `saveTemplateToStudio(input: SaveTemplateInput!): SaveTemplateResult!` writes a placeholder project + spec so that templates installed from the sandbox appear in Studio. The mutation is intentionally simple right now: it records which template was imported, stores metadata, and returns `{ projectId, status: 'QUEUED' }` for the UI.\n- `saveCanvasDraft(input: SaveCanvasDraftInput!): CanvasVersion!` snapshots the current Visual Builder nodes to a draft version tied to a canvas overlay. Inputs include `canvasId`, arbitrary `nodes` JSON, and an optional `label`. The resolver enforces org/org access before calling `CanvasVersionManager`.\n- `deployCanvasVersion(input: DeployCanvasVersionInput!): CanvasVersion!` promotes a previously saved draft (`versionId`) to the deployed state. The returned object includes `status`, `nodes`, `createdAt`, and `createdBy` for UI timelines.\n- `undoCanvasVersion(input: UndoCanvasInput!): CanvasVersion` rewinds the visual builder to the prior snapshot (returns `null` when history is empty) so Studio’s toolbar can surface “Undo” without shelling out to local storage.\n\n### Studio GraphQL endpoint\n\n- The landing app exposes the Studio schema at `/api/studio/graphql` via Yoga so React Query hooks (`useStudioProjects`, `useCreateStudioProject`, `useDeployStudioProject`, etc.) can talk to the bundle without spinning up a separate server.\n\n### Spec Editor typing\n\n- Studio’s spec editor now preloads Monaco with ambient declarations for `@lssm/lib.contracts` and `zod`, so snippets receive autocomplete and inline errors even before the spec ships to the backend. The helper lives in `presentation/components/studio/organisms/monaco-spec-types.ts` and registers the extra libs once per browser session via `monaco.languages.typescript.typescriptDefaults.addExtraLib`.\n- Compiler options are aligned with our frontend toolchain (ES2020 + React JSX) which means drafts written in the editor behave like the compiled artifacts that flow through Studio pipelines.\n\n### Spec templates\n\n- Selecting a spec type now injects a ready-to-edit scaffold (capability, workflow, policy, dataview, component) so authors start from a canonical layout instead of a blank file. Templates live alongside `SpecEditor.tsx`, and we only overwrite the content when the previous value is empty or when the author explicitly switches types via the dropdown.\n\n### Spec preview\n\n- The validation side panel now embeds a `SpecPreview` widget that shows validation errors alongside transport artifacts (GraphQL schema, REST endpoints, component summaries) once a preview run completes. Tabs let authors toggle between “Validation” and “Artifacts,” mirroring the UX described in the Studio plan.\n\n### Testing\n\n- `src/templates/__tests__/runtime.test.ts` covers todos CRUD, messaging delivery, and recipe locale switching through the local GraphQL API.\n- Studio infrastructure tests live in `src/__tests__/e2e/project-lifecycle.test.ts` and continue to exercise project creation + deploy flows.\n\n### Next Steps\n\nFuture templates can register their React components via `registerTemplateComponents(templateId, components)` so TemplateShell can render them automatically. When new templates are added, remember to:\n\n1. Update the registry entry (schema + tags).\n2. Register components inside `presentation/components/templates`.\n3. Document the template under `docs/templates/`.\n\n\n\n\n\n"
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/vscode-extension.docblock.js

@@ -0,0 +1,100 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/vscode-extension.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.vscode.extension",
+	title: "ContractSpec VS Code Extension",
+	summary: "VS Code extension for spec-first development with validation, scaffolding, and MCP integration.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/vscode/extension",
+	tags: [
+		"vscode",
+		"extension",
+		"tooling",
+		"dx"
+	],
+	body: `# ContractSpec VS Code Extension
+
+The ContractSpec VS Code extension provides spec-first development tooling directly in your editor.
+
+## Features
+
+- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files
+- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)
+- **Spec Explorer**: List and navigate all specs in your workspace
+- **Dependency Analysis**: Visualize spec dependencies and detect cycles
+- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol
+- **Snippets**: Code snippets for common ContractSpec patterns
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`ContractSpec: Validate Current Spec\` | Validate the currently open spec file |
+| \`ContractSpec: Validate All Specs\` | Validate all spec files in the workspace |
+| \`ContractSpec: Build/Scaffold\` | Generate handler/component from the current spec |
+| \`ContractSpec: List All Specs\` | Show all specs in the workspace |
+| \`ContractSpec: Analyze Dependencies\` | Analyze and visualize spec dependencies |
+| \`ContractSpec: Search Docs (MCP)\` | Search documentation via MCP |
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| \`contractspec.api.baseUrl\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \`""\` |
+| \`contractspec.telemetry.posthogHost\` | PostHog host URL for direct telemetry | \`"https://eu.posthog.com"\` |
+| \`contractspec.telemetry.posthogProjectKey\` | PostHog project key for direct telemetry | \`""\` |
+| \`contractspec.validation.onSave\` | Run validation on save | \`true\` |
+| \`contractspec.validation.onOpen\` | Run validation on open | \`true\` |
+
+## Architecture
+
+The extension uses:
+- \`@lssm/module.contractspec-workspace\` for pure analysis + templates
+- \`@lssm/bundle.contractspec-workspace\` for workspace services + adapters
+
+This allows the extension to work without requiring the CLI to be installed.
+
+## Telemetry
+
+The extension uses a hybrid telemetry approach:
+1. If \`contractspec.api.baseUrl\` is configured → send to API \`/api/telemetry/ingest\`
+2. Otherwise → send directly to PostHog (if project key configured)
+
+Telemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.
+`
+}, {
+	id: "docs.tech.vscode.snippets",
+	title: "ContractSpec Snippets",
+	summary: "Code snippets for common ContractSpec patterns in VS Code.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/vscode/snippets",
+	tags: [
+		"vscode",
+		"snippets",
+		"dx"
+	],
+	body: `# ContractSpec Snippets
+
+The VS Code extension includes snippets for common ContractSpec patterns.
+
+## Available Snippets
+
+| Prefix | Description |
+|--------|-------------|
+| \`contractspec-command\` | Create a new command (write operation) |
+| \`contractspec-query\` | Create a new query (read-only operation) |
+| \`contractspec-event\` | Create a new event |
+| \`contractspec-docblock\` | Create a new DocBlock |
+| \`contractspec-telemetry\` | Create a new TelemetrySpec |
+| \`contractspec-presentation\` | Create a new Presentation |
+
+## Usage
+
+Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.
+`
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/docs/tech/workflows/overview.docblock.js

@@ -0,0 +1,19 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/docs/tech/workflows/overview.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.workflows.overview",
+	title: "WorkflowSpec Overview",
+	summary: "WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/workflows/overview",
+	tags: [
+		"tech",
+		"workflows",
+		"overview"
+	],
+	body: "# WorkflowSpec Overview\n\n## Purpose\n\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\n\n## Core Types\n\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\n- `WorkflowDefinition`:\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\n  - `steps[]`: ordered list of `Step` descriptors.\n  - `transitions[]`: directed edges between steps with optional expressions.\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\n- `Step`:\n  - `type`: `human`, `automation`, or `decision`.\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\n- `Transition`: `from` → `to` with optional `condition` string (simple data expressions).\n\n## Registry & Validation\n\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\n  - Duplicate step IDs.\n  - Unknown `from`/`to` transitions.\n  - Empty guards/conditions.\n  - Reachability from the entry step.\n  - Cycles in the graph.\n  - Operation/Form references against provided registries.\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\n\n## Runtime\n\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\n  - `start(name, version?, initialData?)` returns a `workflowId`.\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\n  - `getState(workflowId)` retrieves the latest state snapshot.\n  - `cancel(workflowId)` marks the workflow as cancelled.\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\n- React bindings (`@lssm/lib.presentation-runtime-react`):\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\n  - `WorkflowStepper` progress indicator using design-system Stepper.\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\n\n## Authoring Checklist\n\n1. Reuse existing operations/forms; create new specs when missing.\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\n\n## Testing\n\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\n\n## Tooling\n\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\n\n## Next Steps (Non-MVP)\n\n- Persistence adapters (database/file) for workflow state (Phase 2).\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\n- Telemetry hooks for step execution metrics.\n\n"
+}]);
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/events.js

@@ -0,0 +1,10 @@
+import "./schema/dist/index.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/events.js
+/** Identity function to keep type inference when declaring events. */
+function defineEvent(e) {
+	return e;
+}
+
+//#endregion
+export { defineEvent };

package/dist/libs/identity-rbac/dist/contracts/dist/experiments/evaluator.js

@@ -0,0 +1 @@
+import "node:crypto";