@lssm/example.workflow-system 0.0.0-canary-20251217060804 → 0.0.0-canary-20251217062139

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

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

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

@@ -0,0 +1 @@
+import{a as e}from"../../registry.js";e([{id:`docs.tech.studio.learning-events`,title:`Studio Learning Events`,summary:`Studio persists learning/activity events to the database; Sandbox keeps learning local-first and unlogged.`,kind:`reference`,visibility:`public`,route:`/docs/tech/studio/learning-events`,tags:[`studio`,`learning`,`events`,`analytics`,`sandbox`],body:"# 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"}]);

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

@@ -0,0 +1,57 @@
+import{a as e}from"../../registry.js";e([{id:`docs.tech.studio.learning-journeys`,title:`Studio learning journeys (onboarding + coach)`,summary:`DB-backed learning journeys tracked per organization: seeded tracks/steps, event-driven progress, XP/streaks, and a Studio coach surface.`,kind:`reference`,visibility:`public`,route:`/docs/tech/studio/learning-journeys`,tags:[`studio`,`learning`,`onboarding`,`journey`,`graphql`,`database`],body:`# Studio learning journeys
+
+Studio supports **DB-backed learning journeys** (onboarding tracks + ambient coach tips) that are advanced by **recorded learning events**.
+
+> See also: \`/docs/tech/studio/learning-events\` for event naming + payload guardrails.
+
+## Scope (multi-tenancy)
+
+- Progress is tracked **per organization** (tenant/workspace), via a \`Learner\` record keyed by \`(userId, organizationId)\`.
+- Learning events are stored as \`StudioLearningEvent\` under the Studio DB schema, scoped to an organization (optionally a project).
+
+## Persistence model (Prisma)
+
+Learning journey progress lives in the \`lssm_learning\` schema:
+
+- \`Learner\` — one per \`(userId, organizationId)\`
+- \`OnboardingTrack\` — seeded track definitions (trackKey, name, metadata)
+- \`OnboardingStep\` — seeded step definitions (stepKey, completionCondition, xpReward, metadata)
+- \`OnboardingProgress\` — learner × track progress (progress %, xpEarned, completedAt, dismissedAt)
+- \`OnboardingStepCompletion\` — append-only completion records (stepKey, status, xpEarned, completedAt)
+
+## Track definition source (spec-first)
+
+- Canonical track specs live in \`@lssm/example.learning-journey-registry\`.
+- The Studio API seeds/updates the DB definitions via an idempotent “ensure tracks” routine.
+- The DB is kept aligned with track specs (stale steps are removed) to prevent drift and unblock completion.
+
+## Progress advancement (event-driven)
+
+1) UI records an event via GraphQL \`recordLearningEvent\`
+2) Backend creates \`StudioLearningEvent\`
+3) Backend advances onboarding by matching the new event against step completion conditions
+4) Backend persists step completions and recomputes:
+   - \`progress\` percentage
+   - \`xpEarned\` (including streak/completion bonuses when configured)
+   - track completion state (\`completedAt\`)
+
+## GraphQL API (Studio)
+
+- \`myOnboardingTracks(productId?, includeProgress?)\`
+  - returns all tracks + optional progress for the current learner
+- \`myOnboardingProgress(trackKey)\`
+  - returns progress + step completion list for a single track
+- \`dismissOnboardingTrack(trackKey)\`
+  - marks a track dismissed for the learner (prevents auto-coach)
+
+## UI routes/surfaces (web)
+
+- \`/studio/learning\` — learning hub (track list + progress widget)
+- \`/studio/learning/{trackKey}\` — track detail (steps + map)
+- Studio shell mounts a **coach sheet** that can auto-open for incomplete, non-dismissed onboarding.
+
+## Security + data hygiene
+
+- Do not put secrets/PII in \`payload\` fields of learning events.
+- Prefer shallow payload filters (small, stable keys).
+`}]);

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

@@ -0,0 +1,63 @@
+import{a as e}from"../../registry.js";e([{id:`docs.tech.studio.platform-admin-panel`,title:`Studio Platform Admin Panel`,summary:`How PLATFORM_ADMIN organizations manage tenant orgs and integration connections without session switching.`,kind:`reference`,visibility:`public`,route:`/docs/tech/studio/platform-admin-panel`,tags:[`studio`,`admin`,`multi-tenancy`,`integrations`,`better-auth`],body:`# Studio Platform Admin Panel
+
+ContractSpec Studio exposes a dedicated **Platform Admin Panel** for users whose **active organization** has:
+
+- \`Organization.type = PLATFORM_ADMIN\`
+
+The UI route is:
+
+- \`/studio/admin\`
+
+## Authorization model (no org switching)
+
+Platform admins **remain in their own organization**. Cross-tenant actions are always explicit and scoped:
+
+- Admin operations require an explicit \`targetOrganizationId\`.
+- No session / activeOrganizationId switching is performed as part of admin operations.
+
+## Integrations management
+
+The admin panel manages the full ContractSpec Integrations system:
+
+- Lists all shipped \`IntegrationSpec\` entries (registry built via \`createDefaultIntegrationSpecRegistry()\`).
+- CRUD \`IntegrationConnection\` records for a selected tenant org.
+
+### Secrets (reference-only + write-only)
+
+The admin UI supports two modes:
+
+- **Reference-only (BYOK)**: store only \`secretProvider\` + \`secretRef\`.
+- **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**.
+
+Supported backends:
+
+- Env overrides (\`env://...\`)
+- Google Cloud Secret Manager (\`gcp://...\`)
+- AWS Secrets Manager (\`aws://secretsmanager/...\`)
+- Scaleway Secret Manager (\`scw://secret-manager/...\`)
+
+## Better Auth Admin plugin
+
+The panel uses the Better Auth **Admin plugin** for user operations (list users, impersonation):
+
+- Client calls use \`authClient.admin.*\`.
+- Server-side, ContractSpec enforces that users in a PLATFORM_ADMIN active org have \`User.role\` containing \`admin\` so Better Auth Admin endpoints authorize.
+
+## GraphQL surface
+
+The platform-admin GraphQL operations are guarded by the active org type and include:
+
+- \`platformAdminOrganizations(search, limit, offset)\`
+- \`platformAdminIntegrationSpecs\`
+- \`platformAdminIntegrationConnections(input: { targetOrganizationId, category?, status? })\`
+- \`platformAdminIntegrationConnectionCreate(input)\`
+- \`platformAdminIntegrationConnectionUpdate(input)\`
+- \`platformAdminIntegrationConnectionDelete(targetOrganizationId, connectionId)\`
+
+## Key implementation files
+
+- Auth + role enforcement: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Admin GraphQL module: \`packages/bundles/contractspec-studio/src/infrastructure/graphql/modules/platform-admin.ts\`
+- Integrations admin service: \`packages/bundles/contractspec-studio/src/modules/platform-integrations/index.ts\`
+- Web route: \`packages/apps/web-landing/src/app/(app-customer)/studio/admin/*\`
+`}]);

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

@@ -0,0 +1,36 @@
+import{a as e}from"../../registry.js";e([{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:
+  - \`myStudioProjects\` (returns only projects you can access)
+  - \`studioProjectBySlug(slug)\` (enforces the same access rules)
+  - \`myTeams\`
+  - \`projectTeams(projectId)\`
+
+- Write:
+  - \`createStudioProject(input.teamIds?)\` (teamIds optional)
+  - \`setProjectTeams(projectId, teamIds)\` (admin-only)
+
+## Related
++
++- Team administration + invitations: see \`/docs/tech/studio/team-invitations\`.
++
+## Notes
+
+Payloads and events must avoid secrets/PII. For Sandbox, the model remains local-first and unlogged.
+`}]);

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

@@ -0,0 +1 @@
+import{a as e}from"../../registry.js";e([{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\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"}]);

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

@@ -0,0 +1,20 @@
+import{a as e}from"../../registry.js";e([{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)
+`}]);

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

@@ -0,0 +1,65 @@
+import{a as e}from"../../registry.js";e([{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.
+
+- 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)
+
+- \`status\`: \`pending | accepted | declined | expired\`
+
+- \`teamId?\`: optional team to join
+
+- \`inviterId\`: user who issued the invitation
+
+## GraphQL surfaces
+
+- Team CRUD (admin-only):
+
+  - \`createTeam(name)\`
+
+  - \`renameTeam(teamId, name)\`
+
+  - \`deleteTeam(teamId)\`
+
+
+- Invitations (admin-only):
+
+  - \`organizationInvitations\`
+
+  - \`inviteToOrganization(email, role?, teamId?)\` → returns \`inviteUrl\` and whether an email was sent
+
+## Accepting an invitation
+
+The invite link is served as:
+
+- \`/invite/{invitationId}\`
+
+Acceptance rules:
+- The user must be authenticated.
+
+- The authenticated user’s email must match \`Invitation.email\`.
+
+- If not already a member, create \`Member(userId, organizationId, role)\`.
+
+- If \`teamId\` is present, ensure \`TeamMember(teamId, userId)\`.
+
+- Mark invitation \`status='accepted'\` and set \`acceptedAt\`.
+
+- 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.
+
+- Otherwise, the UI uses the returned \`inviteUrl\` for manual copy/share.
+`}]);

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

@@ -0,0 +1 @@
+import{a as e}from"../../registry.js";e([{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)\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"}]);

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

@@ -0,0 +1,41 @@
+import{a as e}from"../../registry.js";e([{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.
+`}]);