@lssm/lib.personalization 0.0.0-canary-20251212230121 → 0.0.0-canary-20251215220103

package/dist/contracts/src/docs/index.js

@@ -1 +1 @@
-import{docBlockToPresentationSpec as e,docBlockToPresentationV2 as t,docBlocksToPresentationRoutes as n}from"./presentations.js";import{DocRegistry as r,defaultDocRegistry as i,registerDocBlocks as a}from"./registry.js";import"./PUBLISHING.docblock.js";import"./accessibility_wcag_compliance_specs.docblock.js";import"./tech/PHASE_1_QUICKSTART.docblock.js";import"./tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js";import"./tech/PHASE_3_AUTO_EVOLUTION.docblock.js";import"./tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.js";import"./tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.js";import"./tech/lifecycle-stage-system.docblock.js";import"./tech/presentation-runtime.docblock.js";import"./tech/schema/README.docblock.js";import"./tech/templates/runtime.docblock.js";import"./tech/workflows/overview.docblock.js";import"./tech/mcp-endpoints.docblock.js";
+import{docBlockToPresentationSpec as e,docBlockToPresentationV2 as t,docBlocksToPresentationRoutes as n}from"./presentations.js";import{DocRegistry as r,defaultDocRegistry as i,registerDocBlocks as a}from"./registry.js";import"./PUBLISHING.docblock.js";import"./accessibility_wcag_compliance_specs.docblock.js";import"./tech/PHASE_1_QUICKSTART.docblock.js";import"./tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js";import"./tech/PHASE_3_AUTO_EVOLUTION.docblock.js";import"./tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.js";import"./tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.js";import"./tech/lifecycle-stage-system.docblock.js";import"./tech/presentation-runtime.docblock.js";import"./tech/auth/better-auth-nextjs.docblock.js";import"./tech/schema/README.docblock.js";import"./tech/templates/runtime.docblock.js";import"./tech/workflows/overview.docblock.js";import"./tech/mcp-endpoints.docblock.js";import"./tech/vscode-extension.docblock.js";import"./tech/telemetry-ingest.docblock.js";import"./tech/contracts/openapi-export.docblock.js";import"./tech/studio/workspaces.docblock.js";import"./tech/studio/sandbox-unlogged.docblock.js";import"./tech/studio/workspace-ops.docblock.js";import"./tech/studio/project-routing.docblock.js";import"./tech/studio/platform-admin-panel.docblock.js";import"./tech/studio/learning-events.docblock.js";import"./tech/studio/learning-journeys.docblock.js";import"./tech/studio/project-access-teams.docblock.js";import"./tech/studio/team-invitations.docblock.js";

package/dist/contracts/src/docs/tech/auth/better-auth-nextjs.docblock.js

@@ -0,0 +1,58 @@
+import{registerDocBlocks as e}from"../../registry.js";e([{id:`docs.tech.auth.better-auth-nextjs`,title:`Better Auth + Next.js integration (ContractSpec)`,summary:`How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).`,kind:`reference`,visibility:`public`,route:`/docs/tech/auth/better-auth-nextjs`,tags:[`auth`,`better-auth`,`nextjs`,`cookies`,`proxy`,`hmr`],body:`# Better Auth + Next.js integration (ContractSpec)
+
+This repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).
+
+## Server config (Better Auth)
+
+- Source: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Important: \`nextCookies()\` must be the **last** plugin in the Better Auth plugin list so \`Set-Cookie\` is applied correctly in Next.js environments.
+
+## Better Auth Admin plugin
+
+ContractSpec Studio enables the Better Auth **Admin plugin** to support platform-admin user operations (list users, impersonation, etc.).
+
+- Server: \`admin()\` plugin in \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Client: \`adminClient()\` in \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+
+### PLATFORM_ADMIN ⇒ Better Auth admin role
+
+Better Auth Admin endpoints authorize via \`user.role\`. ContractSpec enforces an org-driven rule:
+
+- If the **active organization** has \`type = PLATFORM_ADMIN\`, the signed-in user is ensured to have \`User.role\` containing \`admin\`.
+- This is applied in the session creation hook and re-checked in \`assertsPlatformAdmin()\`.
+
+This keeps admin enablement deterministic and avoids manual role backfills.
+
+## Client config (React web + Expo)
+
+To avoid duplicate background refresh/polling loops in dev (Fast Refresh/HMR), the Better Auth client is implemented as a singleton cached on \`globalThis\`.
+
+- Web client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+- Native client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.native.ts\`
+
+Import guidance:
+
+- If you only need the context/hook, prefer importing from \`@lssm/bundle.contractspec-studio/presentation/providers/auth\`.
+- If you explicitly need the Better Auth client instance (e.g. admin impersonation, direct API calls), import from \`@lssm/bundle.contractspec-studio/presentation/providers/auth/client\`.
+
+## Public routes (login / signup)
+
+Public auth pages should avoid eager \`authClient\` initialization.
+
+Pattern used:
+
+- In the submit handler, dynamically import \`@lssm/bundle.contractspec-studio/presentation/providers/auth/index.web\` and call \`authClient.signIn.*\` / \`authClient.signUp.*\`.
+
+This prevents session refresh behavior from starting just because a public page rendered.
+
+## Next.js proxy auth (web-landing)
+
+The Next.js proxy/middleware is used for **redirect decisions only**. It must not perform DB-backed session reads on every request.
+
+- Source: \`packages/apps/web-landing/src/proxy.ts\`
+- Approach: cookie-only checks via Better Auth cookies helpers:
+  - \`getSessionCookie(request)\`
+  - \`getCookieCache(request)\`
+
+These checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.
+`}]);

package/dist/contracts/src/docs/tech/contracts/openapi-export.docblock.js

@@ -0,0 +1,38 @@
+import{registerDocBlocks as e}from"../../registry.js";e([{id:`docs.tech.contracts.openapi-export`,title:`OpenAPI export (OpenAPI 3.1) from SpecRegistry`,summary:`Generate a deterministic OpenAPI document from a SpecRegistry using jsonSchemaForSpec + REST transport metadata.`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/openapi-export`,tags:[`contracts`,`openapi`,`rest`],body:`## OpenAPI export (OpenAPI 3.1) from SpecRegistry
+
+### Purpose
+
+ContractSpec specs can be exported into an **OpenAPI 3.1** document for tooling (SDK generation, docs, gateways).
+
+The export is **spec-first**:
+
+- Uses \`jsonSchemaForSpec(spec)\` for input/output JSON Schema (from SchemaModel → zod → JSON Schema)
+- Uses \`spec.transport.rest.method/path\` when present
+- Falls back to deterministic defaults:
+  - Method: \`POST\` for commands, \`GET\` for queries
+  - Path: \`defaultRestPath(name, version)\` → \`/<dot/name>/v<version>\`
+
+### Library API
+
+- Function: \`openApiForRegistry(registry, options?)\`
+- Location: \`@lssm/lib.contracts/openapi\`
+
+### CLI
+
+Export OpenAPI from a registry module:
+
+\`\`\`bash
+contractspec openapi --registry ./src/registry.ts --out ./openapi.json
+\`\`\`
+
+The registry module must export one of:
+
+- \`registry: SpecRegistry\`
+- \`default(): SpecRegistry | Promise<SpecRegistry>\`
+- \`createRegistry(): SpecRegistry | Promise<SpecRegistry>\`
+
+### Notes / limitations (current)
+
+- Responses are generated as a basic \`200\` response (plus schemas when available).
+- Query (GET) inputs are currently represented as a JSON request body when an input schema exists.
+- Errors are not yet expanded into OpenAPI responses; that will be added when we standardize error envelopes.`}]);

package/dist/contracts/src/docs/tech/mcp-endpoints.docblock.js

@@ -1 +1 @@
-import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.mcp.endpoints`,title:`ContractSpec MCP endpoints`,summary:`Dedicated MCP servers for docs, CLI usage, and internal development.`,kind:`reference`,visibility:`mixed`,route:`/docs/tech/mcp/endpoints`,tags:[`mcp`,`docs`,`cli`,`internal`],body:"# ContractSpec MCP endpoints\n\nThree dedicated MCP servers keep AI agents efficient and scoped:\n\n- **Docs MCP**: `/api/mcp/docs` — exposes DocBlocks as resources + presentations. Tool: `docs.search`.\n- **CLI MCP**: `/api/mcp/cli` — surfaces CLI quickstart/reference/README and suggests commands. Tool: `cli.suggestCommand`.\n- **Internal MCP**: `/api/mcp/internal` — internal routing hints and playbook. Tool: `internal.describe`.\n\n### Usage notes\n- Transports are HTTP POST (streamable HTTP); SSE is disabled.\n- Resources are namespaced (`docs://*`, `cli://*`, `internal://*`) and are read-only.\n- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.\n- GraphQL remains at `/graphql`; health at `/health`.\n"}]);
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.mcp.endpoints`,title:`ContractSpec MCP endpoints`,summary:`Dedicated MCP servers for docs, CLI usage, and internal development.`,kind:`reference`,visibility:`mixed`,route:`/docs/tech/mcp/endpoints`,tags:[`mcp`,`docs`,`cli`,`internal`],body:"# ContractSpec MCP endpoints\n\nThree dedicated MCP servers keep AI agents efficient and scoped:\n\n- **Docs MCP**: `/api/mcp/docs` — exposes DocBlocks as resources + presentations. Tool: `docs.search`.\n- **CLI MCP**: `/api/mcp/cli` — surfaces CLI quickstart/reference/README and suggests commands. Tool: `cli.suggestCommand`.\n- **Internal MCP**: `/api/mcp/internal` — internal routing hints, playbook, and example registry access. Tool: `internal.describe`.\n\n### Usage notes\n- Transports are HTTP POST (streamable HTTP); SSE is disabled.\n- Resources are namespaced (`docs://*`, `cli://*`, `internal://*`) and are read-only.\n- Internal MCP also exposes the examples registry via `examples://*` resources:\n  - `examples://list?q=<query>`\n  - `examples://example/<id>`\n- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.\n- GraphQL remains at `/graphql`; health at `/health`.\n"}]);

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

@@ -0,0 +1 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/learning-journeys.docblock.js

@@ -0,0 +1,57 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/platform-admin-panel.docblock.js

@@ -0,0 +1,63 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/project-access-teams.docblock.js

@@ -0,0 +1,36 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/project-routing.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/sandbox-unlogged.docblock.js

@@ -0,0 +1,20 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/team-invitations.docblock.js

@@ -0,0 +1,65 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/workspace-ops.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks 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/contracts/src/docs/tech/studio/workspaces.docblock.js

@@ -0,0 +1,41 @@
+import{registerDocBlocks 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.
+`}]);

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

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

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

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

package/dist/docs/behavior-tracking.docblock.js

@@ -1,4 +1,4 @@
-import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";e([{id:`docs.personalization.behavior-tracking`,title:`Behavior Tracking`,summary:"`@lssm/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.",kind:`reference`,visibility:`public`,route:`/docs/personalization/behavior-tracking`,tags:[`personalization`,`behavior-tracking`],body:`# Behavior Tracking
+import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";const t=[{id:`docs.personalization.behavior-tracking`,title:`Behavior Tracking`,summary:"`@lssm/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.",kind:`reference`,visibility:`public`,route:`/docs/personalization/behavior-tracking`,tags:[`personalization`,`behavior-tracking`],body:`# Behavior Tracking
 
 \`@lssm/lib.personalization\` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.
 
@@ -77,4 +77,4 @@ When the adapter returns an overlay spec, pass it to the overlay engine to regis
 
 
 
-`}]);
+`}];e(t);export{t as personalization_behavior_tracking_DocBlocks};

package/dist/docs/overlay-engine.docblock.js

@@ -1,4 +1,4 @@
-import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";e([{id:`docs.personalization.overlay-engine`,title:`Overlay Engine`,summary:"`@lssm/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.",kind:`reference`,visibility:`public`,route:`/docs/personalization/overlay-engine`,tags:[`personalization`,`overlay-engine`],body:`# Overlay Engine
+import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";const t=[{id:`docs.personalization.overlay-engine`,title:`Overlay Engine`,summary:"`@lssm/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.",kind:`reference`,visibility:`public`,route:`/docs/personalization/overlay-engine`,tags:[`personalization`,`overlay-engine`],body:`# Overlay Engine
 
 \`@lssm/lib.overlay-engine\` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.
 
@@ -78,4 +78,4 @@ const result = engine.apply({
 
 
 
-`}]);
+`}];e(t);export{t as personalization_overlay_engine_DocBlocks};

package/dist/docs/workflow-composition.docblock.js

@@ -1,4 +1,4 @@
-import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";e([{id:`docs.personalization.workflow-composition`,title:`Workflow Composition`,summary:"`@lssm/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.",kind:`reference`,visibility:`public`,route:`/docs/personalization/workflow-composition`,tags:[`personalization`,`workflow-composition`],body:`# Workflow Composition
+import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";const t=[{id:`docs.personalization.workflow-composition`,title:`Workflow Composition`,summary:"`@lssm/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.",kind:`reference`,visibility:`public`,route:`/docs/personalization/workflow-composition`,tags:[`personalization`,`workflow-composition`],body:`# Workflow Composition
 
 \`@lssm/lib.workflow-composer\` composes base WorkflowSpecs with tenant/role/device-specific extensions.
 
@@ -63,4 +63,4 @@ The composer uses anchor references (\`after\`/\`before\`) to place injected ste
 
 
 
-`}]);
+`}];e(t);export{t as personalization_workflow_composition_DocBlocks};

package/dist/index.js

@@ -1 +1 @@
-import{InMemoryBehaviorStore as e}from"./store.js";import{BehaviorTracker as t,createBehaviorTracker as n}from"./tracker.js";import{BehaviorAnalyzer as r}from"./analyzer.js";import{insightsToOverlaySuggestion as i,insightsToWorkflowAdaptations as a}from"./adapter.js";import"./docs/index.js";export{r as BehaviorAnalyzer,t as BehaviorTracker,e as InMemoryBehaviorStore,n as createBehaviorTracker,i as insightsToOverlaySuggestion,a as insightsToWorkflowAdaptations};
+import{insightsToOverlaySuggestion as e,insightsToWorkflowAdaptations as t}from"./adapter.js";import{BehaviorAnalyzer as n}from"./analyzer.js";import{InMemoryBehaviorStore as r}from"./store.js";import{BehaviorTracker as i,createBehaviorTracker as a}from"./tracker.js";import"./docs/index.js";export{n as BehaviorAnalyzer,i as BehaviorTracker,r as InMemoryBehaviorStore,a as createBehaviorTracker,e as insightsToOverlaySuggestion,t as insightsToWorkflowAdaptations};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.personalization",
-  "version": "0.0.0-canary-20251212230121",
+  "version": "0.0.0-canary-20251215220103",
   "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,17 +33,35 @@
   "devDependencies": {
     "@lssm/tool.tsdown": "workspace:*",
     "@lssm/tool.typescript": "workspace:*",
-    "tsdown": "^0.17.0",
+    "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "exports": {
     ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
+    "./analyzer": "./src/analyzer.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/behavior-tracking.docblock": "./src/docs/behavior-tracking.docblock.ts",
+    "./docs/overlay-engine.docblock": "./src/docs/overlay-engine.docblock.ts",
+    "./docs/workflow-composition.docblock": "./src/docs/workflow-composition.docblock.ts",
+    "./store": "./src/store.ts",
+    "./tracker": "./src/tracker.ts",
+    "./types": "./src/types.ts",
     "./*": "./*"
   },
   "publishConfig": {
     "access": "public",
     "exports": {
       ".": "./dist/index.js",
+      "./adapter": "./dist/adapter.js",
+      "./analyzer": "./dist/analyzer.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/behavior-tracking.docblock": "./dist/docs/behavior-tracking.docblock.js",
+      "./docs/overlay-engine.docblock": "./dist/docs/overlay-engine.docblock.js",
+      "./docs/workflow-composition.docblock": "./dist/docs/workflow-composition.docblock.js",
+      "./store": "./dist/store.js",
+      "./tracker": "./dist/tracker.js",
+      "./types": "./dist/types.js",
       "./*": "./*"
     }
   }