@lssm/example.service-business-os 0.0.0-canary-20251217083314 → 0.0.0-canary-20251220002821

package/dist/libs/contracts/dist/docs/tech/schema/README.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"README.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/schema/README.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/schema/README.docblock.ts\nconst tech_schema_README_DocBlocks = [{\n\tid: \"docs.tech.schema.README\",\n\ttitle: \"Multi‑File Prisma Schema Conventions (per database)\",\n\tsummary: \"We adopt Prisma multi‑file schema (GA ≥ v6.7) to organize each database’s models by domain and to import core LSSM module schemas locally.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/schema/README\",\n\ttags: [\n\t\t\"tech\",\n\t\t\"schema\",\n\t\t\"README\"\n\t],\n\tbody: \"# Multi‑File Prisma Schema Conventions (per database)\\n\\nWe adopt Prisma multi‑file schema (GA ≥ v6.7) to organize each database’s models by domain and to import core LSSM module schemas locally.\\n\\nCanonical layout per DB:\\n\\n```\\nprisma/\\n  schema/\\n    main.prisma             # datasource + generators only\\n    imported/\\n      lssm_sigil/*.prisma   # imported models/enums only (no datasource/generator)\\n      lssm_content/*.prisma # idem\\n    <domain>/*.prisma       # vertical‑specific models split by bounded context\\n```\\n\\nNotes:\\n\\n- Imported files contain only `model` and `enum` blocks (strip `datasource`/`generator`).\\n- Preserve `@@schema(\\\"…\\\")` annotations to keep tables in their Postgres schemas; we now explicitly list schemas in `main.prisma` to avoid P1012: `schemas = [\\\"public\\\",\\\"lssm_sigil\\\",\\\"lssm_content\\\",\\\"lssm_featureflags\\\",\\\"lssm_ops\\\",\\\"lssm_planning\\\",\\\"lssm_quill\\\",\\\"lssm_geoterro\\\"]`.\\n- Use `@lssm/app.cli-database` CLI: `database import|check|generate|migrate:*|seed` to manage a single DB; `@lssm/app.cli-databases` orchestrates multiple DBs.\\n\\n## Typed merger config\\n\\n- Define imported module list once per DB with a typed config:\\n\\n```ts\\n// prisma-merger.config.ts\\nimport { defineMergedPrismaConfig } from '@lssm/app.cli-database';\\n\\nexport default defineMergedPrismaConfig({\\n  modules: [\\n    '@lssm/app.cli-database-sigil',\\n    '@lssm/app.cli-database-content',\\n    // ...\\n  ],\\n});\\n```\\n\\n- Then run `database import --target .` (no need to pass `--modules`).\\n\\n## Prisma Config (prisma.config.ts)\\n\\nWe use Prisma Config per official docs to point Prisma to the multi-file schema folder and migrations:\\n\\n```ts\\n// prisma.config.ts\\nimport path from 'node:path';\\nimport { defineConfig } from 'prisma/config';\\n\\nexport default defineConfig({\\n  schema: path.join('prisma', 'schema'),\\n  migrations: { path: path.join('prisma', 'migrations') },\\n});\\n```\\n\\nReference: Prisma blog – Organize Your Prisma Schema into Multiple Files: https://www.prisma.io/blog/organize-your-prisma-schema-with-multi-file-support\\n\\n---\\n\\n# LSSM Auth (Sigil) – Models & Integration\\n\\nThis document tracks the identity models and integration points used by the LSSM Sigil module.\\n\\n## Models (Prisma `lssm_sigil`)\\n\\n- `User` – core identity with email, optional phone, role, passkeys, apiKeys\\n- `Session` – session tokens and metadata; includes `activeOrganizationId`\\n- `Account` – external providers (password, OAuth)\\n- `Organization` – tenant boundary; includes `type` additional field\\n- `Member`, `Invitation`, `Team`, `TeamMember` – org/teams\\n- `Role`, `Permission`, `PolicyBinding` – RBAC\\n- `ApiKey`, `Passkey` – programmable access and WebAuthn\\n- `SsoProvider` – OIDC/SAML provider configuration (org- or user-scoped)\\n- `OAuthApplication`, `OAuthAccessToken`, `OAuthConsent` – first/third-party OAuth\\n\\nThese mirror STRIT additions so Better Auth advanced plugins (admin, organization, apiKey, passkey, genericOAuth) work uniformly across apps.\\n\\n## Better Auth (server)\\n\\nEnabled methods:\\n\\n- Email & password\\n- Phone OTP (Telnyx)\\n- Passkey (WebAuthn)\\n- API keys\\n- Organizations & Teams\\n- Generic OAuth (FranceConnect+ via OIDC with JWE/JWS using JOSE)\\n\\nServer config lives at `packages/lssm/modules/sigil/src/application/services/auth.ts`.\\n\\n## Clients (Expo / React)\\n\\nClient config lives at `packages/lssm/modules/sigil/src/presentation/providers/auth/expo.ts` with plugins for admin, passkey, apiKey, organization, phone, genericOAuth.\\n\\n## Environment Variables\\n\\nTelnyx (phone OTP):\\n\\n- `TELNYX_API_KEY`\\n- `TELNYX_MESSAGING_PROFILE_ID`\\n- `TELNYX_FROM_NUMBER`\\n\\nFranceConnect+ (prefer LSSM*… but STRIT*… fallbacks are supported):\\n\\n- `LSSM_FRANCECONNECTPLUS_DISCOVERY_URL`\\n- `LSSM_FRANCECONNECTPLUS_CLIENT_ID`\\n- `LSSM_FRANCECONNECTPLUS_CLIENT_SECRET`\\n- `LSSM_FRANCECONNECTPLUS_ENC_PRIVATE_KEY_PEM` (PKCS8; RSA-OAEP-256)\\n\\nGeneric:\\n\\n- `API_URL_IDENTITIES` – base URL for Better Auth server\\n- `BETTER_AUTH_SECRET` – server secret\\n\\nKeep this in sync with code changes to avoid drift.\\n\\n## HCircle domain splits and auth removal\\n\\n- Auth/identity models are not defined locally anymore. They come from `@lssm/app.cli-database-sigil` under the `lssm_sigil` schema.\\n- `packages/hcircle/libs/database-coliving/prisma/schema/domain/` is split by domain; newsletter/waiting list lives in `newsletter.prisma` and uses `@@map(\\\"waiting_list\\\")`.\\n- To avoid collisions with module names, the local event models were renamed to `SocialEvent`, `SocialEventAttendee`, and `SocialEventRecurrence` with `@@map` pointing to existing table names.\\n\\n---\\n\\n## Vertical profiles (current)\\n\\n### STRIT\\n\\n- prisma-merger modules:\\n  - `@lssm/app.cli-database-sigil`, `@lssm/app.cli-database-content`, `@lssm/app.cli-database-ops`, `@lssm/app.cli-database-planning`, `@lssm/app.cli-database-quill`, `@lssm/app.cli-database-geoterro`\\n- main.prisma schemas:\\n  - `schemas = [\\\"public\\\",\\\"lssm_sigil\\\",\\\"lssm_content\\\",\\\"lssm_ops\\\",\\\"lssm_planning\\\",\\\"lssm_quill\\\",\\\"lssm_geoterro\\\"]`\\n- domain splits (`packages/strit/libs/database/prisma/schema/domain/`):\\n  - `bookings.prisma` (Booking, StritDocument + links to Content `File` and Sigil `Organization`)\\n  - `commerce.prisma` (Wholesale models; `sellerId` linked to Sigil `Organization`)\\n  - `files.prisma` (PublicFile, PublicFileAccessLog; `ownerId`→Organization, `uploadedBy`→User)\\n  - `geo.prisma` (PublicCountry, PublicAddress, City; links to Spots/Series)\\n  - `spots.prisma`, `urbanism.prisma`, `analytics.prisma`, `onboarding.prisma`, `referrals.prisma`, `subscriptions.prisma`, `content.prisma`\\n- auth models are imported from Sigil (no local auth tables).\\n- Back-relations for `Organization` (e.g., `files`, seller relations) are declared in the Sigil module to avoid scattering.\\n\\n### ARTISANOS\\n\\n- prisma-merger modules:\\n  - `@lssm/app.cli-database-sigil`, `@lssm/app.cli-database-content`, `@lssm/app.cli-database-featureflags`, `@lssm/app.cli-database-ops`, `@lssm/app.cli-database-planning`, `@lssm/app.cli-database-quill`, `@lssm/app.cli-database-geoterro`\\n- main.prisma schemas:\\n  - `schemas = [\\\"public\\\",\\\"lssm_sigil\\\",\\\"lssm_content\\\",\\\"lssm_featureflags\\\",\\\"lssm_ops\\\",\\\"lssm_planning\\\",\\\"lssm_quill\\\",\\\"lssm_geoterro\\\"]`\\n- domain splits (`packages/artisanos/libs/database-artisan/prisma/schema/domain/`):\\n  - `sales.prisma` (Client, Quote, QuoteTemplate, Invoice, FollowUps)\\n  - `subsidies.prisma` (SubsidyProgram, AidApplication, SupportingDocument)\\n  - `projects.prisma` (Project, ProjectPlanningSettings)\\n  - `crm.prisma` (OrganizationProfessionalProfile, OrganizationCertification)\\n  - `professions.prisma`, `products.prisma`, `templates.prisma`, `analytics.prisma`, `onboarding.prisma`, `referrals.prisma`, `subscriptions.prisma`, `files.prisma`\\n- auth/organization/team models are provided by Sigil; local legacy copies were removed.\\n- Where names collide with Content, local models are prefixed (e.g., `PublicFile`) and use `@@map` to keep existing table names where applicable.\\n\\n## Schema Dictionary: `@lssm/lib.schema`\\n\\n### Purpose\\n\\nDescribe operation I/O once and generate:\\n\\n- zod (runtime validation)\\n- GraphQL (Pothos types/refs)\\n- JSON Schema (via `zod-to-json-schema` or native descriptors)\\n\\n### Primitives\\n\\n- **FieldType<T>**: describes a scalar or composite field and carries:\\n  - `zod` schema for validation\\n  - optional JSON Schema descriptor\\n  - optional GraphQL scalar reference/name\\n- **SchemaModel**: named object model composed of fields. Exposes helpers:\\n  - `getZod(): z.ZodObject<ZodShapeFromFields<Fields>> | z.ZodArray<z.ZodObject<...>>`\\n    - Preserves each field's schema, optionality, and array-ness\\n    - Top-level lists are supported via `config.isArray: true`\\n  - `getJsonSchema(): JSONSchema7` (export for docs, MCP, forms)\\n  - `getPothosInput()` (GraphQL input object name)\\n\\n### Conventions\\n\\n- Name models with PascalCase; suffix with `Input`/`Result` when ambiguous.\\n- Use explicit enums for multi-value constants; reuse the same enum across input/output.\\n- Define domain enums via `defineEnum('Name', [...])` in the relevant domain package (e.g., `packages/strit/libs/contracts-strit/src/enums/`), not in `ScalarTypeEnum`.\\n- Reference those enums in `SchemaModel` fields directly (they expose `getZod`, `getPothos`, `getJsonSchema`).\\n\\n#### Example (STRIT)\\n\\n```ts\\n// packages/strit/libs/contracts-strit/src/enums/recurrence.ts\\nimport { defineEnum } from '@lssm/lib.schema';\\nexport const SpotEnum = {\\n  Weekday: () =>\\n    defineEnum('Weekday', ['MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU'] as const),\\n  RecurrenceFrequency: () =>\\n    defineEnum('RecurrenceFrequency', [\\n      'DAILY',\\n      'WEEKLY',\\n      'MONTHLY',\\n      'YEARLY',\\n    ] as const),\\n} as const;\\n```\\n\\n```ts\\n// usage in contracts\\nfrequency: { type: SpotEnum.RecurrenceFrequency(), isOptional: false },\\nbyWeekday: { type: SpotEnum.Weekday(), isOptional: true, isArray: true },\\n```\\n\\n- Use `Date` type for temporal values and ensure ISO strings in JSON transports where needed.\\n\\n### Mapping rules (summary)\\n\\n- Strings → GraphQL `String`\\n- Numbers → `Int` if safe 32-bit integer else `Float`\\n- Booleans → `Boolean`\\n- Dates → custom `Date` scalar\\n- Arrays<T> → list of mapped T (set `isArray: true` on the field)\\n- Top-level arrays → set `isArray: true` on the model config\\n- Objects → input/output object types with stable field order\\n- Unions → supported for output; input unions map to JSON (structural input is not supported by GraphQL)\\n\\n### JSON Schema export\\n\\nPrefer `getZod()` + `zod-to-json-schema` for consistency. For advanced cases, provide a custom `getJsonSchema()` on the model.\\n\\n### Example\\n\\n```ts\\nimport { ScalarTypeEnum, SchemaModel } from '@lssm/lib.schema';\\n\\n// Nested model\\nconst Weekday = new SchemaModel({\\n  name: 'Weekday',\\n  fields: {\\n    value: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },\\n  },\\n});\\n\\n// Parent model with array field and nested object\\nconst Rule = new SchemaModel({\\n  name: 'Rule',\\n  fields: {\\n    timezone: { type: ScalarTypeEnum.TimeZone(), isOptional: false },\\n    byWeekday: { type: Weekday, isOptional: true, isArray: true },\\n  },\\n});\\n\\nconst CreateThingInput = new SchemaModel({\\n  name: 'CreateThingInput',\\n  fields: {\\n    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\\n    rule: { type: Rule, isOptional: false },\\n  },\\n});\\n\\n// zod\\nconst z = CreateThingInput.getZod();\\n```\\n\"\n}];\nregisterDocBlocks(tech_schema_README_DocBlocks);\n\n//#endregion\nexport { tech_schema_README_DocBlocks };"],"mappings":";;;AAGA,MAAM,+BAA+B,CAAC;CACrC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;CACN,CAAC;AACF,kBAAkB,6BAA6B"}

package/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js

@@ -45,4 +45,5 @@ These events are intentionally minimal and must avoid PII/secrets in payloads.
 }];
 registerDocBlocks(tech_studio_learning_events_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=learning-events.docblock.js.map

package/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-events.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/learning-events.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/learning-events.docblock.ts\nconst tech_studio_learning_events_DocBlocks = [{\n\tid: \"docs.tech.studio.learning-events\",\n\ttitle: \"Studio Learning Events\",\n\tsummary: \"Studio persists learning/activity events to the database; Sandbox keeps learning local-first and unlogged.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/learning-events\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"learning\",\n\t\t\"events\",\n\t\t\"analytics\",\n\t\t\"sandbox\"\n\t],\n\tbody: `# Studio Learning Events\n\nStudio emits lightweight **learning/activity events** to support onboarding, ambient coaching, and learning journeys.\n\n## Persistence model\n\n- **Studio**: events are persisted to the database in \\`StudioLearningEvent\\` and are organization-scoped (optionally project-scoped).\n- **Sandbox**: events remain **local-only** (unlogged); they must never be sent to backend services.\n\n## GraphQL API\n\n- \\`recordLearningEvent(input: { name, projectId?, payload? })\\`\n- \\`myLearningEvents(projectId?, limit?)\\`\n- \\`myOnboardingTracks(productId?, includeProgress?)\\`\n- \\`myOnboardingProgress(trackKey)\\`\n- \\`dismissOnboardingTrack(trackKey)\\`\n\n## Common event names (convention)\n\n- \\`module.navigated\\` — user navigated to a Studio module (payload at minimum: \\`{ moduleId }\\`).\n- \\`studio.template.instantiated\\` — created a new Studio project (starter template). Payload commonly includes \\`{ templateId, projectSlug }\\`.\n- \\`spec.changed\\` — created or updated a Studio spec. Payload may include \\`{ action: 'create' | 'update', specId?, specType? }\\`.\n- \\`regeneration.completed\\` — finished a “regen/deploy” action (currently emitted on successful Studio deploy actions).\n- \\`studio.evolution.applied\\` — completed an Evolution session (payload commonly includes \\`{ evolutionSessionId }\\`).\n\nThese events are intentionally minimal and must avoid PII/secrets in payloads.\n`\n}];\nregisterDocBlocks(tech_studio_learning_events_DocBlocks);\n\n//#endregion\nexport { tech_studio_learning_events_DocBlocks };"],"mappings":";;;AAGA,MAAM,wCAAwC,CAAC;CAC9C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BN,CAAC;AACF,kBAAkB,sCAAsC"}

package/dist/libs/contracts/dist/docs/tech/studio/learning-journeys.docblock.js

@@ -76,4 +76,5 @@ Learning journey progress lives in the \`lssm_learning\` schema:
 }];
 registerDocBlocks(tech_studio_learning_journeys_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=learning-journeys.docblock.js.map

package/dist/libs/contracts/dist/docs/tech/studio/learning-journeys.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-journeys.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/learning-journeys.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/learning-journeys.docblock.ts\nconst tech_studio_learning_journeys_DocBlocks = [{\n\tid: \"docs.tech.studio.learning-journeys\",\n\ttitle: \"Studio learning journeys (onboarding + coach)\",\n\tsummary: \"DB-backed learning journeys tracked per organization: seeded tracks/steps, event-driven progress, XP/streaks, and a Studio coach surface.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/learning-journeys\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"learning\",\n\t\t\"onboarding\",\n\t\t\"journey\",\n\t\t\"graphql\",\n\t\t\"database\"\n\t],\n\tbody: `# Studio learning journeys\n\nStudio supports **DB-backed learning journeys** (onboarding tracks + ambient coach tips) that are advanced by **recorded learning events**.\n\n> See also: \\`/docs/tech/studio/learning-events\\` for event naming + payload guardrails.\n\n## Scope (multi-tenancy)\n\n- Progress is tracked **per organization** (tenant/workspace), via a \\`Learner\\` record keyed by \\`(userId, organizationId)\\`.\n- Learning events are stored as \\`StudioLearningEvent\\` under the Studio DB schema, scoped to an organization (optionally a project).\n\n## Persistence model (Prisma)\n\nLearning journey progress lives in the \\`lssm_learning\\` schema:\n\n- \\`Learner\\` — one per \\`(userId, organizationId)\\`\n- \\`OnboardingTrack\\` — seeded track definitions (trackKey, name, metadata)\n- \\`OnboardingStep\\` — seeded step definitions (stepKey, completionCondition, xpReward, metadata)\n- \\`OnboardingProgress\\` — learner × track progress (progress %, xpEarned, completedAt, dismissedAt)\n- \\`OnboardingStepCompletion\\` — append-only completion records (stepKey, status, xpEarned, completedAt)\n\n## Track definition source (spec-first)\n\n- Canonical track specs live in \\`@lssm/example.learning-journey-registry\\`.\n- The Studio API seeds/updates the DB definitions via an idempotent “ensure tracks” routine.\n- The DB is kept aligned with track specs (stale steps are removed) to prevent drift and unblock completion.\n\n## Progress advancement (event-driven)\n\n1) UI records an event via GraphQL \\`recordLearningEvent\\`\n2) Backend creates \\`StudioLearningEvent\\`\n3) Backend advances onboarding by matching the new event against step completion conditions\n4) Backend persists step completions and recomputes:\n   - \\`progress\\` percentage\n   - \\`xpEarned\\` (including streak/completion bonuses when configured)\n   - track completion state (\\`completedAt\\`)\n\n## GraphQL API (Studio)\n\n- \\`myOnboardingTracks(productId?, includeProgress?)\\`\n  - returns all tracks + optional progress for the current learner\n- \\`myOnboardingProgress(trackKey)\\`\n  - returns progress + step completion list for a single track\n- \\`dismissOnboardingTrack(trackKey)\\`\n  - marks a track dismissed for the learner (prevents auto-coach)\n\n## UI routes/surfaces (web)\n\n- \\`/studio/learning\\` — learning hub (track list + progress widget)\n- \\`/studio/learning/{trackKey}\\` — track detail (steps + map)\n- Studio shell mounts a **coach sheet** that can auto-open for incomplete, non-dismissed onboarding.\n\n## Security + data hygiene\n\n- Do not put secrets/PII in \\`payload\\` fields of learning events.\n- Prefer shallow payload filters (small, stable keys).\n`\n}];\nregisterDocBlocks(tech_studio_learning_journeys_DocBlocks);\n\n//#endregion\nexport { tech_studio_learning_journeys_DocBlocks };"],"mappings":";;;AAGA,MAAM,0CAA0C,CAAC;CAChD,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDN,CAAC;AACF,kBAAkB,wCAAwC"}

package/dist/libs/contracts/dist/docs/tech/studio/platform-admin-panel.docblock.js

@@ -81,4 +81,5 @@ The platform-admin GraphQL operations are guarded by the active org type and inc
 }];
 registerDocBlocks(tech_studio_platform_admin_panel_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=platform-admin-panel.docblock.js.map

package/dist/libs/contracts/dist/docs/tech/studio/platform-admin-panel.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-admin-panel.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/platform-admin-panel.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/platform-admin-panel.docblock.ts\nconst tech_studio_platform_admin_panel_DocBlocks = [{\n\tid: \"docs.tech.studio.platform-admin-panel\",\n\ttitle: \"Studio Platform Admin Panel\",\n\tsummary: \"How PLATFORM_ADMIN organizations manage tenant orgs and integration connections without session switching.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/platform-admin-panel\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"admin\",\n\t\t\"multi-tenancy\",\n\t\t\"integrations\",\n\t\t\"better-auth\"\n\t],\n\tbody: `# Studio Platform Admin Panel\n\nContractSpec Studio exposes a dedicated **Platform Admin Panel** for users whose **active organization** has:\n\n- \\`Organization.type = PLATFORM_ADMIN\\`\n\nThe UI route is:\n\n- \\`/studio/admin\\`\n\n## Authorization model (no org switching)\n\nPlatform admins **remain in their own organization**. Cross-tenant actions are always explicit and scoped:\n\n- Admin operations require an explicit \\`targetOrganizationId\\`.\n- No session / activeOrganizationId switching is performed as part of admin operations.\n\n## Integrations management\n\nThe admin panel manages the full ContractSpec Integrations system:\n\n- Lists all shipped \\`IntegrationSpec\\` entries (registry built via \\`createDefaultIntegrationSpecRegistry()\\`).\n- CRUD \\`IntegrationConnection\\` records for a selected tenant org.\n\n### Secrets (reference-only + write-only)\n\nThe admin UI supports two modes:\n\n- **Reference-only (BYOK)**: store only \\`secretProvider\\` + \\`secretRef\\`.\n- **Write-only provisioning/rotation**: paste a raw secret payload; server writes to the selected backend and stores the resulting reference. The secret value is **never returned or displayed**.\n\nSupported backends:\n\n- Env overrides (\\`env://...\\`)\n- Google Cloud Secret Manager (\\`gcp://...\\`)\n- AWS Secrets Manager (\\`aws://secretsmanager/...\\`)\n- Scaleway Secret Manager (\\`scw://secret-manager/...\\`)\n\n## Better Auth Admin plugin\n\nThe panel uses the Better Auth **Admin plugin** for user operations (list users, impersonation):\n\n- Client calls use \\`authClient.admin.*\\`.\n- Server-side, ContractSpec enforces that users in a PLATFORM_ADMIN active org have \\`User.role\\` containing \\`admin\\` so Better Auth Admin endpoints authorize.\n\n## GraphQL surface\n\nThe platform-admin GraphQL operations are guarded by the active org type and include:\n\n- \\`platformAdminOrganizations(search, limit, offset)\\`\n- \\`platformAdminIntegrationSpecs\\`\n- \\`platformAdminIntegrationConnections(input: { targetOrganizationId, category?, status? })\\`\n- \\`platformAdminIntegrationConnectionCreate(input)\\`\n- \\`platformAdminIntegrationConnectionUpdate(input)\\`\n- \\`platformAdminIntegrationConnectionDelete(targetOrganizationId, connectionId)\\`\n\n## Key implementation files\n\n- Auth + role enforcement: \\`packages/bundles/contractspec-studio/src/application/services/auth.ts\\`\n- Admin GraphQL module: \\`packages/bundles/contractspec-studio/src/infrastructure/graphql/modules/platform-admin.ts\\`\n- Integrations admin service: \\`packages/bundles/contractspec-studio/src/modules/platform-integrations/index.ts\\`\n- Web route: \\`packages/apps/web-landing/src/app/(app-customer)/studio/admin/*\\`\n`\n}];\nregisterDocBlocks(tech_studio_platform_admin_panel_DocBlocks);\n\n//#endregion\nexport { tech_studio_platform_admin_panel_DocBlocks };"],"mappings":";;;AAGA,MAAM,6CAA6C,CAAC;CACnD,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DN,CAAC;AACF,kBAAkB,2CAA2C"}

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

@@ -42,4 +42,5 @@ Payloads and events must avoid secrets/PII. For Sandbox, the model remains local
 }];
 registerDocBlocks(tech_studio_project_access_teams_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=project-access-teams.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project-access-teams.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/project-access-teams.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/project-access-teams.docblock.ts\nconst tech_studio_project_access_teams_DocBlocks = [{\n\tid: \"docs.tech.studio.project-access-teams\",\n\ttitle: \"Studio Project Access via Teams\",\n\tsummary: \"Projects live under organizations; team sharing refines access with an admin/owner override.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/project-access-teams\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"projects\",\n\t\t\"teams\",\n\t\t\"rbac\",\n\t\t\"access-control\"\n\t],\n\tbody: `# Studio Project Access via Teams\n\nStudio access control is **organization-first** with optional **team-based sharing**.\n\n## Data model\n\n- \\`Team\\` and \\`TeamMember\\` define team membership inside an organization.\n- \\`StudioProject\\` is owned by an organization.\n- \\`StudioProjectTeam\\` links projects to 0..N teams.\n\n## Access rules\n\n- **Admins/owners**: always have access to all projects in the organization.\n- **Org-wide projects**: if a project has **no team links**, all organization members can access it.\n- **Team-scoped projects**: if a project has **one or more team links**, a user must be a member of at least one linked team.\n\n## GraphQL surfaces\n\n- 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\n## Related\\n+\\n+- Team administration + invitations: see \\`/docs/tech/studio/team-invitations\\`.\\n+\n## Notes\n\nPayloads and events must avoid secrets/PII. For Sandbox, the model remains local-first and unlogged.\n`\n}];\nregisterDocBlocks(tech_studio_project_access_teams_DocBlocks);\n\n//#endregion\nexport { tech_studio_project_access_teams_DocBlocks };"],"mappings":";;;AAGA,MAAM,6CAA6C,CAAC;CACnD,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;CAwBN,CAAC;AACF,kBAAkB,2CAA2C"}

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

@@ -64,4 +64,5 @@ The following project modules are expected under \`/studio/{projectSlug}\`:
 }];
 registerDocBlocks(tech_studio_project_routing_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=project-routing.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project-routing.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/project-routing.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/project-routing.docblock.ts\nconst tech_studio_project_routing_DocBlocks = [{\n\tid: \"docs.tech.studio.project-routing\",\n\ttitle: \"Studio Project Routing\",\n\tsummary: \"Studio uses slugged, project-first routes: /studio/{projectSlug}/* with canonical slug redirects and soft-deleted projects hidden.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/project-routing\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"routing\",\n\t\t\"projects\",\n\t\t\"slug\",\n\t\t\"redirects\"\n\t],\n\tbody: `# Studio Project Routing\n\nContractSpec Studio uses a **project-first URL scheme**:\n\n- \\`/studio/projects\\` — create, select, and delete projects.\n- \\`/studio/{projectSlug}/*\\` — project modules (canvas/specs/deploy/integrations/evolution/learning).\n- \\`/studio/learning\\` — learning hub that does not require selecting a project.\n\n## Studio layout shell\n\nStudio routes are wrapped in a dedicated **Studio app shell** (header + footer) that provides in-app navigation (Projects/Learning/Teams), organization switching, and account actions.\n\nProject 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.\n\n## Slug behavior (rename-safe)\n\n- Each project has a \\`slug\\` stored in the database (\\`StudioProject.slug\\`).\n- When a project name changes, Studio **updates the slug** and stores the previous slug as an alias (\\`StudioProjectSlugAlias\\`).\n- Requests to an alias slug are **redirected to the canonical slug**.\n\nGraphQL entrypoint:\n\n- \\`studioProjectBySlug(slug: String!)\\` returns:\n  - \\`project\\`\n  - \\`canonicalSlug\\`\n  - \\`wasRedirect\\`\n\n## Deletion behavior (soft delete)\n\nProjects are **soft-deleted**:\n\n- \\`deleteStudioProject(id: String!)\\` sets \\`StudioProject.deletedAt\\`.\n- All listings and access checks filter \\`deletedAt = null\\`.\n- Soft-deleted projects are treated as “not found” in Studio routes and GraphQL access checks.\n\n## Available modules for a selected project\n\nThe following project modules are expected under \\`/studio/{projectSlug}\\`:\n\n- \\`/canvas\\` — Visual builder canvas (stored via overlays and canvas versions).\n- \\`/specs\\` — Spec editor (stored as \\`StudioSpec\\`).\n- \\`/deploy\\` — Deployments history + triggers (stored as \\`StudioDeployment\\`).\n- \\`/integrations\\` — Integrations scoped to project (stored as \\`StudioIntegration\\`).\n- \\`/evolution\\` — Evolution sessions (stored as \\`EvolutionSession\\`).\n- \\`/learning\\` — Project learning activity.\n`\n}];\nregisterDocBlocks(tech_studio_project_routing_DocBlocks);\n\n//#endregion\nexport { tech_studio_project_routing_DocBlocks };"],"mappings":";;;AAGA,MAAM,wCAAwC,CAAC;CAC9C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CN,CAAC;AACF,kBAAkB,sCAAsC"}

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

@@ -37,4 +37,5 @@ const tech_studio_sandbox_unlogged_DocBlocks = [{
 }];
 registerDocBlocks(tech_studio_sandbox_unlogged_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=sandbox-unlogged.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-unlogged.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/sandbox-unlogged.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/sandbox-unlogged.docblock.ts\nconst tech_studio_sandbox_unlogged_DocBlocks = [{\n\tid: \"docs.tech.studio.sandbox.unlogged\",\n\ttitle: \"Sandbox (unlogged) vs Studio (authenticated)\",\n\tsummary: \"The sandbox is a lightweight, unlogged surface that mirrors Studio navigation without auth or analytics.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/sandbox-unlogged\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"sandbox\",\n\t\t\"privacy\",\n\t\t\"analytics\"\n\t],\n\tbody: `## Sandbox guarantees\n\n- Route: \\`/sandbox\\`\n- **No auth requirement**\n- **No PostHog init**\n- **No Vercel Analytics**\n- Local-only state (in-browser runtime + localStorage where needed)\n\n## What Sandbox is for\n\n- Try templates and feature modules safely\n- Preview specs/builder/evolution/learning\n- Produce copyable CLI commands (no side effects)\n\n## What Sandbox is *not* for\n\n- Persisted projects/workspaces\n- Real deployments\n- Organization-scoped integrations (unless explicitly enabled later)\n`\n}];\nregisterDocBlocks(tech_studio_sandbox_unlogged_DocBlocks);\n\n//#endregion\nexport { tech_studio_sandbox_unlogged_DocBlocks };"],"mappings":";;;AAGA,MAAM,yCAAyC,CAAC;CAC/C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;CAoBN,CAAC;AACF,kBAAkB,uCAAuC"}

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

@@ -66,4 +66,5 @@ Acceptance rules:
 }];
 registerDocBlocks(tech_studio_team_invitations_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=team-invitations.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"team-invitations.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/team-invitations.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/team-invitations.docblock.ts\nconst tech_studio_team_invitations_DocBlocks = [{\n\tid: \"docs.tech.studio.team-invitations\",\n\ttitle: \"Studio Teams & Invitations\",\n\tsummary: \"Admin-only team management and email invitation flow to join an organization and optionally a team.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/team-invitations\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"teams\",\n\t\t\"invitations\",\n\t\t\"access-control\",\n\t\t\"onboarding\"\n\t],\n\tbody: `# Studio Teams & Invitations\n\nStudio uses **organization membership** as the base access model. Teams are optional and used to refine access to projects.\n\n## Who can manage teams?\n\n- **Admins/owners only**: create, rename, delete teams; manage project team access; issue invitations.\n\n## Invitation data model\n\n- \\`Invitation\\` rows are stored under an organization and target an **email** address.\\n\n- An invitation can optionally target a \\`teamId\\`, which will grant the user membership in that team upon acceptance.\n\nKey fields:\n- \\`email\\`: invited address (must match the accepting user's account email)\\n\n- \\`status\\`: \\`pending | accepted | declined | expired\\`\\n\n- \\`teamId?\\`: optional team to join\\n\n- \\`inviterId\\`: user who issued the invitation\n\n## GraphQL surfaces\n\n- Team CRUD (admin-only):\\n\n  - \\`createTeam(name)\\`\\n\n  - \\`renameTeam(teamId, name)\\`\\n\n  - \\`deleteTeam(teamId)\\`\\n\n\n- Invitations (admin-only):\\n\n  - \\`organizationInvitations\\`\\n\n  - \\`inviteToOrganization(email, role?, teamId?)\\` → returns \\`inviteUrl\\` and whether an email was sent\n\n## Accepting an invitation\n\nThe invite link is served as:\\n\n- \\`/invite/{invitationId}\\`\n\nAcceptance rules:\n- The user must be authenticated.\\n\n- The authenticated user’s email must match \\`Invitation.email\\`.\\n\n- If not already a member, create \\`Member(userId, organizationId, role)\\`.\\n\n- If \\`teamId\\` is present, ensure \\`TeamMember(teamId, userId)\\`.\\n\n- Mark invitation \\`status='accepted'\\` and set \\`acceptedAt\\`.\\n\n- Set \\`activeOrganizationId\\` for the session so \\`/studio/*\\` routes work immediately.\n\n## Email delivery\n\n- If \\`RESEND_API_KEY\\` is set, the system attempts to send an email.\\n\n- Otherwise, the UI uses the returned \\`inviteUrl\\` for manual copy/share.\n`\n}];\nregisterDocBlocks(tech_studio_team_invitations_DocBlocks);\n\n//#endregion\nexport { tech_studio_team_invitations_DocBlocks };"],"mappings":";;;AAGA,MAAM,yCAAyC,CAAC;CAC/C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDN,CAAC;AACF,kBAAkB,uCAAuC"}

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

@@ -44,4 +44,5 @@ These endpoints are **read-only** in v1 and never push to git:
 }];
 registerDocBlocks(tech_studio_workspace_ops_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=workspace-ops.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-ops.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/workspace-ops.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/workspace-ops.docblock.ts\nconst tech_studio_workspace_ops_DocBlocks = [{\n\tid: \"docs.tech.studio.workspace_ops\",\n\ttitle: \"Workspace ops (repo-linked): list / validate / deps / diff\",\n\tsummary: \"Read-only repo operations used by Studio to inspect and validate a linked ContractSpec workspace.\",\n\tkind: \"reference\",\n\tvisibility: \"mixed\",\n\troute: \"/docs/tech/studio/workspace-ops\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"repo\",\n\t\t\"workspace\",\n\t\t\"validate\",\n\t\t\"diff\"\n\t],\n\tbody: `## API surface (api-contractspec)\n\nBase: \\`/api/workspace-ops\\`\n\nThese endpoints are **read-only** in v1 and never push to git:\n\n- \\`GET /api/workspace-ops/:integrationId/config?organizationId=\\`\n- \\`GET /api/workspace-ops/:integrationId/specs?organizationId=\\`\n- \\`POST /api/workspace-ops/:integrationId/validate\\` (body: organizationId, files?, pattern?)\n- \\`POST /api/workspace-ops/:integrationId/deps\\` (body: organizationId, pattern?)\n- \\`POST /api/workspace-ops/:integrationId/diff\\` (body: organizationId, specPath, baseline?, breakingOnly?)\n\n## Repo resolution\n\n- The repo root is resolved from the Studio Integration (\\`IntegrationProvider.GITHUB\\`) config:\n  - \\`config.repoCachePath\\` (preferred) or \\`config.localPath\\`\n- Resolution is constrained to \\`CONTRACTSPEC_REPO_CACHE_DIR\\` (default: \\`/tmp/contractspec-repos\\`)\n\n## Intended UX\n\n- Studio Assistant can run these checks and present results as suggestions.\n- Users can copy equivalent CLI commands for local runs:\n  - \\`contractspec validate\\`\n  - \\`contractspec deps\\`\n  - \\`contractspec diff --baseline <ref>\\`\n`\n}];\nregisterDocBlocks(tech_studio_workspace_ops_DocBlocks);\n\n//#endregion\nexport { tech_studio_workspace_ops_DocBlocks };"],"mappings":";;;AAGA,MAAM,sCAAsC,CAAC;CAC5C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BN,CAAC;AACF,kBAAkB,oCAAoC"}

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

@@ -59,4 +59,5 @@ Studio and Sandbox both use a shared shell:
 }];
 registerDocBlocks(tech_studio_workspaces_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=workspaces.docblock.js.map

package/dist/libs/contracts/dist/docs/tech/studio/workspaces.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/studio/workspaces.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/studio/workspaces.docblock.ts\nconst tech_studio_workspaces_DocBlocks = [{\n\tid: \"docs.tech.studio.workspaces\",\n\ttitle: \"Studio projects, teams, environments\",\n\tsummary: \"Organization-first Studio: projects live under an organization; teams refine access; projects deploy to multiple environments.\",\n\tkind: \"reference\",\n\tvisibility: \"mixed\",\n\troute: \"/docs/tech/studio/workspaces\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"projects\",\n\t\t\"teams\",\n\t\t\"rbac\",\n\t\t\"environments\"\n\t],\n\tbody: `## Concepts\n\n- **Organization**: the primary grouping boundary for Studio projects.\n- **Project**: one application (specs, overlays, deployments, integrations, evolution, learning).\n- **Team**: refines who can see/edit a project within an organization.\n- **Environment**: deployment target (Development / Staging / Production).\n\n## Project access (teams + admin override)\n\nStudio uses multi-team sharing to refine access:\n\n- **Admins/owners** can access all projects.\n- If a project is shared with **no teams**, it is **org-wide** (all org members).\n- If a project is shared with **one or more teams**, it is visible to:\n  - admins/owners, and\n  - members of any linked team.\n\n## Current persistence (DB + GraphQL)\n\n- DB (Prisma): \\`StudioProject\\`, \\`Team\\`, \\`TeamMember\\`, \\`StudioProjectTeam\\`\n- GraphQL:\n  - \\`myStudioProjects\\`\n  - \\`createStudioProject(input.teamIds?)\\`\n  - \\`myTeams\\`\n  - \\`projectTeams(projectId)\\`\n  - \\`setProjectTeams(projectId, teamIds)\\`\n\n## UI shell behavior\n\nStudio and Sandbox both use a shared shell:\n\n- Project selector → Module navigation → Environment selector\n- Always-on Assistant button (floating)\n- Learning journey progress (Studio persists learning events; Sandbox stays local-only)\n\n## Routing\n\n- \\`/studio/projects\\`: create/select/delete projects (organization-first).\n- \\`/studio/{projectSlug}/*\\`: project modules (canvas/specs/deploy/integrations/evolution/learning).\n- \\`/studio/learning\\`: learning hub without selecting a project.\n`\n}];\nregisterDocBlocks(tech_studio_workspaces_DocBlocks);\n\n//#endregion\nexport { tech_studio_workspaces_DocBlocks };"],"mappings":";;;AAGA,MAAM,mCAAmC,CAAC;CACzC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCN,CAAC;AACF,kBAAkB,iCAAiC"}

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

@@ -152,4 +152,5 @@ This allows future migration without changing client code.
 }];
 registerDocBlocks(tech_telemetry_ingest_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=telemetry-ingest.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-ingest.docblock.js","names":[],"sources":["../../../../../../../../libs/contracts/dist/docs/tech/telemetry-ingest.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../registry.js\";\n\n//#region src/docs/tech/telemetry-ingest.docblock.ts\nconst tech_telemetry_ingest_DocBlocks = [{\n\tid: \"docs.tech.telemetry.ingest\",\n\ttitle: \"Telemetry Ingest Endpoint\",\n\tsummary: \"Server-side telemetry ingestion for ContractSpec clients (VS Code extension, CLI, etc.).\",\n\tkind: \"reference\",\n\tvisibility: \"internal\",\n\troute: \"/docs/tech/telemetry/ingest\",\n\ttags: [\n\t\t\"telemetry\",\n\t\t\"api\",\n\t\t\"posthog\",\n\t\t\"analytics\"\n\t],\n\tbody: `# Telemetry Ingest Endpoint\n\nThe ContractSpec API provides a telemetry ingest endpoint for clients to send product analytics events.\n\n## Endpoint\n\n\\`\\`\\`\nPOST /api/telemetry/ingest\n\\`\\`\\`\n\n## Request\n\n\\`\\`\\`json\n{\n  \"event\": \"contractspec.vscode.command_run\",\n  \"distinct_id\": \"client-uuid\",\n  \"properties\": {\n    \"command\": \"validate\"\n  },\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n\\`\\`\\`\n\n### Headers\n\n| Header | Description |\n|--------|-------------|\n| \\`x-contractspec-client-id\\` | Optional client identifier (used as fallback for distinct_id) |\n| \\`Content-Type\\` | Must be \\`application/json\\` |\n\n### Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| \\`event\\` | string | Yes | Event name (e.g., \\`contractspec.vscode.activated\\`) |\n| \\`distinct_id\\` | string | Yes | Anonymous client identifier |\n| \\`properties\\` | object | No | Event properties |\n| \\`timestamp\\` | string | No | ISO 8601 timestamp |\n\n## Response\n\n\\`\\`\\`json\n{\n  \"success\": true\n}\n\\`\\`\\`\n\n## Configuration\n\nThe endpoint requires \\`POSTHOG_PROJECT_KEY\\` environment variable to be set. If not configured, events are accepted but not forwarded.\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| \\`POSTHOG_HOST\\` | PostHog host URL | \\`https://eu.posthog.com\\` |\n| \\`POSTHOG_PROJECT_KEY\\` | PostHog project API key | (required) |\n\n## Privacy\n\n- No PII is collected or stored\n- \\`distinct_id\\` is an anonymous client-generated UUID\n- File paths and source code are never included in events\n- Respects VS Code telemetry settings on the client side\n\n## Events\n\n### Extension Events\n\n| Event | Description | Properties |\n|-------|-------------|------------|\n| \\`contractspec.vscode.activated\\` | Extension activated | \\`version\\` |\n| \\`contractspec.vscode.command_run\\` | Command executed | \\`command\\` |\n| \\`contractspec.vscode.mcp_call\\` | MCP call made | \\`endpoint\\`, \\`tool\\` |\n\n### API Events\n\n| Event | Description | Properties |\n|-------|-------------|------------|\n| \\`contractspec.api.mcp_request\\` | MCP request processed | \\`endpoint\\`, \\`method\\`, \\`success\\`, \\`duration_ms\\` |\n`\n}, {\n\tid: \"docs.tech.telemetry.hybrid\",\n\ttitle: \"Hybrid Telemetry Model\",\n\tsummary: \"How ContractSpec clients choose between direct PostHog and API-routed telemetry.\",\n\tkind: \"usage\",\n\tvisibility: \"internal\",\n\troute: \"/docs/tech/telemetry/hybrid\",\n\ttags: [\n\t\t\"telemetry\",\n\t\t\"architecture\",\n\t\t\"posthog\"\n\t],\n\tbody: `# Hybrid Telemetry Model\n\nContractSpec uses a hybrid telemetry model where clients can send events either directly to PostHog or via the API server.\n\n## Decision Flow\n\n\\`\\`\\`\nIs contractspec.api.baseUrl configured?\n├── Yes → Send via /api/telemetry/ingest\n└── No → Is posthogProjectKey configured?\n    ├── Yes → Send directly to PostHog\n    └── No → Telemetry disabled\n\\`\\`\\`\n\n## Benefits\n\n### Direct PostHog\n- No server dependency\n- Works offline (with batching)\n- Lower latency\n\n### Via API\n- Centralized key management (no client-side keys)\n- Server-side enrichment and validation\n- Rate limiting and abuse prevention\n- Easier migration to other providers\n\n## Recommendation\n\n- **Development**: Use direct PostHog with a dev project key\n- **Production**: Route via API for better governance\n\n## Future: OpenTelemetry\n\nThe current PostHog implementation is behind a simple interface that can be swapped for OpenTelemetry:\n\n\\`\\`\\`typescript\ninterface TelemetryClient {\n  send(event: TelemetryEvent): Promise<void>;\n}\n\\`\\`\\`\n\nThis allows future migration without changing client code.\n`\n}];\nregisterDocBlocks(tech_telemetry_ingest_DocBlocks);\n\n//#endregion\nexport { tech_telemetry_ingest_DocBlocks };"],"mappings":";;;AAGA,MAAM,kCAAkC,CAAC;CACxC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+EN,EAAE;CACF,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CN,CAAC;AACF,kBAAkB,gCAAgC"}

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

@@ -17,4 +17,5 @@ const tech_templates_runtime_DocBlocks = [{
 }];
 registerDocBlocks(tech_templates_runtime_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=runtime.docblock.js.map

package/dist/libs/contracts/dist/docs/tech/templates/runtime.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/templates/runtime.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/templates/runtime.docblock.ts\nconst tech_templates_runtime_DocBlocks = [{\n\tid: \"docs.tech.templates.runtime\",\n\ttitle: \"ContractSpec Template Runtime (Phase 9)\",\n\tsummary: \"Phase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/templates/runtime\",\n\ttags: [\n\t\t\"tech\",\n\t\t\"templates\",\n\t\t\"runtime\"\n\t],\n\tbody: \"## 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\"\n}];\nregisterDocBlocks(tech_templates_runtime_DocBlocks);\n\n//#endregion\nexport { tech_templates_runtime_DocBlocks };"],"mappings":";;;AAGA,MAAM,mCAAmC,CAAC;CACzC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;CACN,CAAC;AACF,kBAAkB,iCAAiC"}

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

@@ -98,4 +98,5 @@ Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab th
 }];
 registerDocBlocks(tech_vscode_extension_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=vscode-extension.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vscode-extension.docblock.js","names":[],"sources":["../../../../../../../../libs/contracts/dist/docs/tech/vscode-extension.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../registry.js\";\n\n//#region src/docs/tech/vscode-extension.docblock.ts\nconst tech_vscode_extension_DocBlocks = [{\n\tid: \"docs.tech.vscode.extension\",\n\ttitle: \"ContractSpec VS Code Extension\",\n\tsummary: \"VS Code extension for spec-first development with validation, scaffolding, and MCP integration.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/vscode/extension\",\n\ttags: [\n\t\t\"vscode\",\n\t\t\"extension\",\n\t\t\"tooling\",\n\t\t\"dx\"\n\t],\n\tbody: `# ContractSpec VS Code Extension\n\nThe ContractSpec VS Code extension provides spec-first development tooling directly in your editor.\n\n## Features\n\n- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files\n- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)\n- **Spec Explorer**: List and navigate all specs in your workspace\n- **Dependency Analysis**: Visualize spec dependencies and detect cycles\n- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol\n- **Snippets**: Code snippets for common ContractSpec patterns\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| \\`ContractSpec: Validate Current Spec\\` | Validate the currently open spec file |\n| \\`ContractSpec: Validate All Specs\\` | Validate all spec files in the workspace |\n| \\`ContractSpec: Build/Scaffold\\` | Generate handler/component from the current spec |\n| \\`ContractSpec: List All Specs\\` | Show all specs in the workspace |\n| \\`ContractSpec: Analyze Dependencies\\` | Analyze and visualize spec dependencies |\n| \\`ContractSpec: Search Docs (MCP)\\` | Search documentation via MCP |\n\n## Configuration\n\n| Setting | Description | Default |\n|---------|-------------|---------|\n| \\`contractspec.api.baseUrl\\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \\`\"\"\\` |\n| \\`contractspec.telemetry.posthogHost\\` | PostHog host URL for direct telemetry | \\`\"https://eu.posthog.com\"\\` |\n| \\`contractspec.telemetry.posthogProjectKey\\` | PostHog project key for direct telemetry | \\`\"\"\\` |\n| \\`contractspec.validation.onSave\\` | Run validation on save | \\`true\\` |\n| \\`contractspec.validation.onOpen\\` | Run validation on open | \\`true\\` |\n\n## Architecture\n\nThe extension uses:\n- \\`@lssm/module.contractspec-workspace\\` for pure analysis + templates\n- \\`@lssm/bundle.contractspec-workspace\\` for workspace services + adapters\n\nThis allows the extension to work without requiring the CLI to be installed.\n\n## Telemetry\n\nThe extension uses a hybrid telemetry approach:\n1. If \\`contractspec.api.baseUrl\\` is configured → send to API \\`/api/telemetry/ingest\\`\n2. Otherwise → send directly to PostHog (if project key configured)\n\nTelemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.\n`\n}, {\n\tid: \"docs.tech.vscode.snippets\",\n\ttitle: \"ContractSpec Snippets\",\n\tsummary: \"Code snippets for common ContractSpec patterns in VS Code.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/vscode/snippets\",\n\ttags: [\n\t\t\"vscode\",\n\t\t\"snippets\",\n\t\t\"dx\"\n\t],\n\tbody: `# ContractSpec Snippets\n\nThe VS Code extension includes snippets for common ContractSpec patterns.\n\n## Available Snippets\n\n| Prefix | Description |\n|--------|-------------|\n| \\`contractspec-command\\` | Create a new command (write operation) |\n| \\`contractspec-query\\` | Create a new query (read-only operation) |\n| \\`contractspec-event\\` | Create a new event |\n| \\`contractspec-docblock\\` | Create a new DocBlock |\n| \\`contractspec-telemetry\\` | Create a new TelemetrySpec |\n| \\`contractspec-presentation\\` | Create a new Presentation |\n\n## Usage\n\nType the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.\n`\n}];\nregisterDocBlocks(tech_vscode_extension_DocBlocks);\n\n//#endregion\nexport { tech_vscode_extension_DocBlocks };"],"mappings":";;;AAGA,MAAM,kCAAkC,CAAC;CACxC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDN,EAAE;CACF,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;CAmBN,CAAC;AACF,kBAAkB,gCAAgC"}

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

@@ -17,4 +17,5 @@ const tech_workflows_overview_DocBlocks = [{
 }];
 registerDocBlocks(tech_workflows_overview_DocBlocks);
 
-//#endregion
+//#endregion
+//# sourceMappingURL=overview.docblock.js.map

package/dist/libs/contracts/dist/docs/tech/workflows/overview.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.docblock.js","names":[],"sources":["../../../../../../../../../libs/contracts/dist/docs/tech/workflows/overview.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region src/docs/tech/workflows/overview.docblock.ts\nconst tech_workflows_overview_DocBlocks = [{\n\tid: \"docs.tech.workflows.overview\",\n\ttitle: \"WorkflowSpec Overview\",\n\tsummary: \"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.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/workflows/overview\",\n\ttags: [\n\t\t\"tech\",\n\t\t\"workflows\",\n\t\t\"overview\"\n\t],\n\tbody: \"# 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\"\n}];\nregisterDocBlocks(tech_workflows_overview_DocBlocks);\n\n//#endregion\nexport { tech_workflows_overview_DocBlocks };"],"mappings":";;;AAGA,MAAM,oCAAoC,CAAC;CAC1C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;CACN,CAAC;AACF,kBAAkB,kCAAkC"}

package/dist/libs/contracts/dist/docs/tech-contracts.docs.js

@@ -0,0 +1,97 @@
+import { registerDocBlocks } from "./registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech-contracts.docs.js
+const techContractsDocs = [{
+	id: "docs.tech.contracts.presentations-v2",
+	title: "Presentations V2 — Unified Descriptor & Transform Engine",
+	summary: "How PresentationDescriptorV2 and TransformEngine keep docs/renderers consistent.",
+	visibility: "public",
+	route: "/docs/tech/contracts/presentations-v2",
+	kind: "reference",
+	tags: [
+		"presentations",
+		"docs",
+		"mcp"
+	],
+	body: `## Presentations V2 — Unified Descriptor & Transform Engine
+
+### Purpose
+
+Unify presentations into one descriptor (\`PresentationDescriptorV2\`) that declares a single source (React component key or BlockNote doc) and a list of output targets (react, markdown, application/json, application/xml). A pluggable \`TransformEngine\` renders any target and applies PII redaction.
+
+### Types
+
+\`\`\`ts
+type PresentationTarget =
+  | 'react'
+  | 'markdown'
+  | 'application/json'
+  | 'application/xml';
+
+type PresentationSource =
+  | {
+      type: 'component';
+      framework: 'react';
+      componentKey: string;
+      props?: AnySchemaModel;
+    }
+  | { type: 'blocknotejs'; docJson: unknown; blockConfig?: unknown };
+
+interface PresentationDescriptorV2 {
+  meta: PresentationV2Meta; // includes partial OwnerShipMeta + description
+  policy?: { flags?: string[]; pii?: string[] };
+  source: PresentationSource;
+  targets: PresentationTarget[];
+}
+
+// Shared ownership schema (source of truth in @lssm/lib.contracts/src/ownership.ts)
+interface OwnerShipMeta {
+  title: string;
+  description: string;
+  domain: string;
+  owners: Owner[];
+  tags: Tag[];
+  stability: Stability;
+}
+
+type Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';
+type Owner = string; // curated list available in code (e.g., '@sigil-team', 'team-strit')
+type Tag = string; // curated list available in code (e.g., 'auth', 'spots')
+
+// For V2 presentations, meta is a Partial<OwnerShipMeta> plus description, name, version
+interface PresentationV2Meta extends Partial<OwnerShipMeta> {
+  name: string;
+  version: number;
+  description?: string;
+}
+\`\`\`
+
+### Engine
+
+Use \`createDefaultTransformEngine()\` and register custom renderers as needed (e.g., high-fidelity BlockNote → Markdown). The default engine supports markdown/json/xml; a React renderer returns a serializable descriptor the host app renders via a \`componentMap\` or a BlockNote renderer. The canonical source type string is \`blocknotejs\` (not \`blocknote\`).
+
+PII paths (JSON-like) are redacted from rendered outputs.
+
+### MCP Integration
+
+\`createMcpServer\` accepts \`presentationsV2\`. Each descriptor is exposed under \`presentation://<name>/v<version>\` and negotiated variants (\`.md/.json/.xml\`) are rendered by the engine.
+
+### Migration
+
+- V1 \`PresentationSpec\` remains supported; a back-compat helper converts V1 → V2 when convenient.
+- Prefer V2 for new work.
+
+### Examples (Sigil)
+
+- \`sigil.auth.webauth_tabs_v2\`: component source (\`componentKey: 'sigil.webauth.tabs'\`), targets \`react/json/xml\`.
+- \`sigil.signup.guide_v2\`: BlockNote doc source, targets \`react/markdown/json/xml\`.
+
+### React Rendering
+
+Host apps use a \`componentMap\` (e.g., \`'sigil.webauth.tabs' → WebAuthTabs\`) and a BlockNote renderer to turn the React render descriptor into elements.`
+}];
+registerDocBlocks(techContractsDocs);
+
+//#endregion
+export { techContractsDocs };
+//# sourceMappingURL=tech-contracts.docs.js.map

package/dist/libs/contracts/dist/docs/tech-contracts.docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tech-contracts.docs.js","names":[],"sources":["../../../../../../../libs/contracts/dist/docs/tech-contracts.docs.js"],"sourcesContent":["import { registerDocBlocks } from \"./registry.js\";\n\n//#region src/docs/tech-contracts.docs.ts\nconst techContractsDocs = [{\n\tid: \"docs.tech.contracts.presentations-v2\",\n\ttitle: \"Presentations V2 — Unified Descriptor & Transform Engine\",\n\tsummary: \"How PresentationDescriptorV2 and TransformEngine keep docs/renderers consistent.\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/contracts/presentations-v2\",\n\tkind: \"reference\",\n\ttags: [\n\t\t\"presentations\",\n\t\t\"docs\",\n\t\t\"mcp\"\n\t],\n\tbody: `## Presentations V2 — Unified Descriptor & Transform Engine\n\n### Purpose\n\nUnify presentations into one descriptor (\\`PresentationDescriptorV2\\`) that declares a single source (React component key or BlockNote doc) and a list of output targets (react, markdown, application/json, application/xml). A pluggable \\`TransformEngine\\` renders any target and applies PII redaction.\n\n### Types\n\n\\`\\`\\`ts\ntype PresentationTarget =\n  | 'react'\n  | 'markdown'\n  | 'application/json'\n  | 'application/xml';\n\ntype PresentationSource =\n  | {\n      type: 'component';\n      framework: 'react';\n      componentKey: string;\n      props?: AnySchemaModel;\n    }\n  | { type: 'blocknotejs'; docJson: unknown; blockConfig?: unknown };\n\ninterface PresentationDescriptorV2 {\n  meta: PresentationV2Meta; // includes partial OwnerShipMeta + description\n  policy?: { flags?: string[]; pii?: string[] };\n  source: PresentationSource;\n  targets: PresentationTarget[];\n}\n\n// Shared ownership schema (source of truth in @lssm/lib.contracts/src/ownership.ts)\ninterface OwnerShipMeta {\n  title: string;\n  description: string;\n  domain: string;\n  owners: Owner[];\n  tags: Tag[];\n  stability: Stability;\n}\n\ntype Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';\ntype Owner = string; // curated list available in code (e.g., '@sigil-team', 'team-strit')\ntype Tag = string; // curated list available in code (e.g., 'auth', 'spots')\n\n// For V2 presentations, meta is a Partial<OwnerShipMeta> plus description, name, version\ninterface PresentationV2Meta extends Partial<OwnerShipMeta> {\n  name: string;\n  version: number;\n  description?: string;\n}\n\\`\\`\\`\n\n### Engine\n\nUse \\`createDefaultTransformEngine()\\` and register custom renderers as needed (e.g., high-fidelity BlockNote → Markdown). The default engine supports markdown/json/xml; a React renderer returns a serializable descriptor the host app renders via a \\`componentMap\\` or a BlockNote renderer. The canonical source type string is \\`blocknotejs\\` (not \\`blocknote\\`).\n\nPII paths (JSON-like) are redacted from rendered outputs.\n\n### MCP Integration\n\n\\`createMcpServer\\` accepts \\`presentationsV2\\`. Each descriptor is exposed under \\`presentation://<name>/v<version>\\` and negotiated variants (\\`.md/.json/.xml\\`) are rendered by the engine.\n\n### Migration\n\n- V1 \\`PresentationSpec\\` remains supported; a back-compat helper converts V1 → V2 when convenient.\n- Prefer V2 for new work.\n\n### Examples (Sigil)\n\n- \\`sigil.auth.webauth_tabs_v2\\`: component source (\\`componentKey: 'sigil.webauth.tabs'\\`), targets \\`react/json/xml\\`.\n- \\`sigil.signup.guide_v2\\`: BlockNote doc source, targets \\`react/markdown/json/xml\\`.\n\n### React Rendering\n\nHost apps use a \\`componentMap\\` (e.g., \\`'sigil.webauth.tabs' → WebAuthTabs\\`) and a BlockNote renderer to turn the React render descriptor into elements.`\n}];\nregisterDocBlocks(techContractsDocs);\n\n//#endregion\nexport { techContractsDocs };"],"mappings":";;;AAGA,MAAM,oBAAoB,CAAC;CAC1B,IAAI;CACJ,OAAO;CACP,SAAS;CACT,YAAY;CACZ,OAAO;CACP,MAAM;CACN,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EN,CAAC;AACF,kBAAkB,kBAAkB"}

package/dist/libs/contracts/dist/events.js

@@ -7,4 +7,5 @@ function defineEvent(e) {
 }
 
 //#endregion
-export { defineEvent };
+export { defineEvent };
+//# sourceMappingURL=events.js.map

package/dist/libs/contracts/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","names":[],"sources":["../../../../../../libs/contracts/dist/events.js"],"sourcesContent":["import \"./schema/dist/index.js\";\n\n//#region src/events.ts\n/** Identity function to keep type inference when declaring events. */\nfunction defineEvent(e) {\n\treturn e;\n}\n/** Build a stable string key for an event name/version pair. */\nconst eventKey = (name, version) => `${name}.v${version}`;\n\n//#endregion\nexport { defineEvent, eventKey };"],"mappings":";;;;AAIA,SAAS,YAAY,GAAG;AACvB,QAAO"}

package/dist/libs/contracts/dist/index.js

@@ -1,4 +1,3 @@
-import "./schema/dist/SchemaModel.js";
 import "./schema/dist/index.js";
 import { defineEvent } from "./events.js";
 import "./presentations.v2.js";
@@ -65,6 +64,8 @@ import "./regenerator/service.js";
 import "./regenerator/index.js";
 import "./workflow/runner.js";
 import "./workflow/index.js";
+import { techContractsDocs } from "./docs/tech-contracts.docs.js";
+import { metaDocs } from "./docs/meta.docs.js";
 import "./docs/index.js";
 import "./llm/exporters.js";
 import "./llm/prompts.js";