@lssm/example.learning-journey-ui-shared 0.0.0-canary-20251213172311 → 0.0.0-canary-20251215220103

package/.turbo/turbo-build.log

@@ -1,24 +1,24 @@
 $ bun build:bundle && bun build:types
 $ tsdown
-ℹ tsdown v0.17.0 powered by rolldown v1.0.0-beta.53
+ℹ tsdown v0.17.4 powered by rolldown v1.0.0-beta.53
 ℹ config file: /home/runner/work/contractspec/contractspec/packages/examples/learning-journey-ui-shared/tsdown.config.js 
 ℹ entry: src/index.ts, src/hooks/index.ts, src/components/index.ts, src/types.ts
 ℹ target: esnext
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/index.mjs                97.89 kB │ gzip: 33.49 kB
-ℹ dist/components/index.mjs      0.17 kB │ gzip:  0.14 kB
-ℹ dist/hooks/index.mjs           0.10 kB │ gzip:  0.09 kB
-ℹ dist/types.mjs                 0.01 kB │ gzip:  0.03 kB
-ℹ dist/components-tyJAN4Ru.mjs   4.53 kB │ gzip:  1.63 kB
-ℹ dist/hooks-B-tDvppY.mjs        2.48 kB │ gzip:  0.87 kB
-ℹ dist/index.d.mts               1.58 kB │ gzip:  0.60 kB
-ℹ dist/types.d.mts               0.38 kB │ gzip:  0.19 kB
-ℹ dist/components/index.d.mts    0.16 kB │ gzip:  0.14 kB
-ℹ dist/hooks/index.d.mts         0.10 kB │ gzip:  0.09 kB
-ℹ dist/types-BMAby_Ku.d.mts      1.70 kB │ gzip:  0.60 kB
-ℹ dist/index-EWErSKip.d.mts      0.95 kB │ gzip:  0.37 kB
-ℹ dist/index-D_7WU_xm.d.mts      0.68 kB │ gzip:  0.35 kB
-ℹ 13 files, total: 110.72 kB
-✔ Build complete in 9285ms
+ℹ dist/index.mjs                121.60 kB │ gzip: 40.46 kB
+ℹ dist/components/index.mjs       0.17 kB │ gzip:  0.14 kB
+ℹ dist/hooks/index.mjs            0.10 kB │ gzip:  0.09 kB
+ℹ dist/types.mjs                  0.01 kB │ gzip:  0.03 kB
+ℹ dist/components-tyJAN4Ru.mjs    4.53 kB │ gzip:  1.63 kB
+ℹ dist/hooks-B-tDvppY.mjs         2.48 kB │ gzip:  0.87 kB
+ℹ dist/index.d.mts                1.58 kB │ gzip:  0.60 kB
+ℹ dist/types.d.mts                0.38 kB │ gzip:  0.19 kB
+ℹ dist/components/index.d.mts     0.16 kB │ gzip:  0.14 kB
+ℹ dist/hooks/index.d.mts          0.10 kB │ gzip:  0.09 kB
+ℹ dist/types-BMAby_Ku.d.mts       1.70 kB │ gzip:  0.60 kB
+ℹ dist/index-EWErSKip.d.mts       0.95 kB │ gzip:  0.37 kB
+ℹ dist/index-D_7WU_xm.d.mts       0.68 kB │ gzip:  0.35 kB
+ℹ 13 files, total: 134.43 kB
+✔ Build complete in 8575ms
 $ tsc --noEmit

package/CHANGELOG.md

@@ -1,10 +1,10 @@
 # @lssm/example.learning-journey-ui-shared
 
-## 0.0.0-canary-20251213172311
+## 0.0.0-canary-20251215220103
 
 ### Patch Changes
 
 - Updated dependencies [3086383]
-  - @lssm/lib.design-system@0.0.0-canary-20251213172311
-  - @lssm/lib.ui-kit-web@0.0.0-canary-20251213172311
-  - @lssm/module.learning-journey@0.0.0-canary-20251213172311
+  - @lssm/lib.design-system@0.0.0-canary-20251215220103
+  - @lssm/lib.ui-kit-web@0.0.0-canary-20251215220103
+  - @lssm/module.learning-journey@0.0.0-canary-20251215220103

package/dist/index.mjs

@@ -270,6 +270,84 @@ const tech_presentation_runtime_DocBlocks = [{
 }];
 registerDocBlocks(tech_presentation_runtime_DocBlocks);
 
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/auth/better-auth-nextjs.docblock.ts
+const tech_auth_better_auth_nextjs_DocBlocks = [{
+	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.
+`
+}];
+registerDocBlocks(tech_auth_better_auth_nextjs_DocBlocks);
+
 //#endregion
 //#region ../../libs/contracts/src/docs/tech/schema/README.docblock.ts
 const tech_schema_README_DocBlocks = [{
@@ -666,6 +744,529 @@ The registry module must export one of:
 }];
 registerDocBlocks(tech_contracts_openapi_export_DocBlocks);
 
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/workspaces.docblock.ts
+const tech_studio_workspaces_DocBlocks = [{
+	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.
+`
+}];
+registerDocBlocks(tech_studio_workspaces_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/sandbox-unlogged.docblock.ts
+const tech_studio_sandbox_unlogged_DocBlocks = [{
+	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)
+`
+}];
+registerDocBlocks(tech_studio_sandbox_unlogged_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/workspace-ops.docblock.ts
+const tech_studio_workspace_ops_DocBlocks = [{
+	id: "docs.tech.studio.workspace_ops",
+	title: "Workspace ops (repo-linked): list / validate / deps / diff",
+	summary: "Read-only repo operations used by Studio to inspect and validate a linked ContractSpec workspace.",
+	kind: "reference",
+	visibility: "mixed",
+	route: "/docs/tech/studio/workspace-ops",
+	tags: [
+		"studio",
+		"repo",
+		"workspace",
+		"validate",
+		"diff"
+	],
+	body: `## API surface (api-contractspec)
+
+Base: \`/api/workspace-ops\`
+
+These endpoints are **read-only** in v1 and never push to git:
+
+- \`GET /api/workspace-ops/:integrationId/config?organizationId=\`
+- \`GET /api/workspace-ops/:integrationId/specs?organizationId=\`
+- \`POST /api/workspace-ops/:integrationId/validate\` (body: organizationId, files?, pattern?)
+- \`POST /api/workspace-ops/:integrationId/deps\` (body: organizationId, pattern?)
+- \`POST /api/workspace-ops/:integrationId/diff\` (body: organizationId, specPath, baseline?, breakingOnly?)
+
+## Repo resolution
+
+- The repo root is resolved from the Studio Integration (\`IntegrationProvider.GITHUB\`) config:
+  - \`config.repoCachePath\` (preferred) or \`config.localPath\`
+- Resolution is constrained to \`CONTRACTSPEC_REPO_CACHE_DIR\` (default: \`/tmp/contractspec-repos\`)
+
+## Intended UX
+
+- Studio Assistant can run these checks and present results as suggestions.
+- Users can copy equivalent CLI commands for local runs:
+  - \`contractspec validate\`
+  - \`contractspec deps\`
+  - \`contractspec diff --baseline <ref>\`
+`
+}];
+registerDocBlocks(tech_studio_workspace_ops_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/project-routing.docblock.ts
+const tech_studio_project_routing_DocBlocks = [{
+	id: "docs.tech.studio.project-routing",
+	title: "Studio Project Routing",
+	summary: "Studio uses slugged, project-first routes: /studio/{projectSlug}/* with canonical slug redirects and soft-deleted projects hidden.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/project-routing",
+	tags: [
+		"studio",
+		"routing",
+		"projects",
+		"slug",
+		"redirects"
+	],
+	body: `# Studio Project Routing
+
+ContractSpec Studio uses a **project-first URL scheme**:
+
+- \`/studio/projects\` — create, select, and delete projects.
+- \`/studio/{projectSlug}/*\` — project modules (canvas/specs/deploy/integrations/evolution/learning).
+- \`/studio/learning\` — learning hub that does not require selecting a project.
+
+## Studio layout shell
+
+Studio routes are wrapped in a dedicated **Studio app shell** (header + footer) that provides in-app navigation (Projects/Learning/Teams), organization switching, and account actions.
+
+Project module routes (\`/studio/{projectSlug}/*\`) render their own module shell (\`WorkspaceProjectShellLayout\`). When combined with the global Studio header, the project shell uses a **sticky header offset** to avoid overlapping sticky headers.
+
+## Slug behavior (rename-safe)
+
+- Each project has a \`slug\` stored in the database (\`StudioProject.slug\`).
+- When a project name changes, Studio **updates the slug** and stores the previous slug as an alias (\`StudioProjectSlugAlias\`).
+- Requests to an alias slug are **redirected to the canonical slug**.
+
+GraphQL entrypoint:
+
+- \`studioProjectBySlug(slug: String!)\` returns:
+  - \`project\`
+  - \`canonicalSlug\`
+  - \`wasRedirect\`
+
+## Deletion behavior (soft delete)
+
+Projects are **soft-deleted**:
+
+- \`deleteStudioProject(id: String!)\` sets \`StudioProject.deletedAt\`.
+- All listings and access checks filter \`deletedAt = null\`.
+- Soft-deleted projects are treated as “not found” in Studio routes and GraphQL access checks.
+
+## Available modules for a selected project
+
+The following project modules are expected under \`/studio/{projectSlug}\`:
+
+- \`/canvas\` — Visual builder canvas (stored via overlays and canvas versions).
+- \`/specs\` — Spec editor (stored as \`StudioSpec\`).
+- \`/deploy\` — Deployments history + triggers (stored as \`StudioDeployment\`).
+- \`/integrations\` — Integrations scoped to project (stored as \`StudioIntegration\`).
+- \`/evolution\` — Evolution sessions (stored as \`EvolutionSession\`).
+- \`/learning\` — Project learning activity.
+`
+}];
+registerDocBlocks(tech_studio_project_routing_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/platform-admin-panel.docblock.ts
+const tech_studio_platform_admin_panel_DocBlocks = [{
+	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/*\`
+`
+}];
+registerDocBlocks(tech_studio_platform_admin_panel_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/learning-events.docblock.ts
+const tech_studio_learning_events_DocBlocks = [{
+	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
+
+Studio emits lightweight **learning/activity events** to support onboarding, ambient coaching, and learning journeys.
+
+## Persistence model
+
+- **Studio**: events are persisted to the database in \`StudioLearningEvent\` and are organization-scoped (optionally project-scoped).
+- **Sandbox**: events remain **local-only** (unlogged); they must never be sent to backend services.
+
+## GraphQL API
+
+- \`recordLearningEvent(input: { name, projectId?, payload? })\`
+- \`myLearningEvents(projectId?, limit?)\`
+- \`myOnboardingTracks(productId?, includeProgress?)\`
+- \`myOnboardingProgress(trackKey)\`
+- \`dismissOnboardingTrack(trackKey)\`
+
+## Common event names (convention)
+
+- \`module.navigated\` — user navigated to a Studio module (payload at minimum: \`{ moduleId }\`).
+- \`studio.template.instantiated\` — created a new Studio project (starter template). Payload commonly includes \`{ templateId, projectSlug }\`.
+- \`spec.changed\` — created or updated a Studio spec. Payload may include \`{ action: 'create' | 'update', specId?, specType? }\`.
+- \`regeneration.completed\` — finished a “regen/deploy” action (currently emitted on successful Studio deploy actions).
+- \`studio.evolution.applied\` — completed an Evolution session (payload commonly includes \`{ evolutionSessionId }\`).
+
+These events are intentionally minimal and must avoid PII/secrets in payloads.
+`
+}];
+registerDocBlocks(tech_studio_learning_events_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/learning-journeys.docblock.ts
+const tech_studio_learning_journeys_DocBlocks = [{
+	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).
+`
+}];
+registerDocBlocks(tech_studio_learning_journeys_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/project-access-teams.docblock.ts
+const tech_studio_project_access_teams_DocBlocks = [{
+	id: "docs.tech.studio.project-access-teams",
+	title: "Studio Project Access via Teams",
+	summary: "Projects live under organizations; team sharing refines access with an admin/owner override.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/project-access-teams",
+	tags: [
+		"studio",
+		"projects",
+		"teams",
+		"rbac",
+		"access-control"
+	],
+	body: `# Studio Project Access via Teams
+
+Studio access control is **organization-first** with optional **team-based sharing**.
+
+## Data model
+
+- \`Team\` and \`TeamMember\` define team membership inside an organization.
+- \`StudioProject\` is owned by an organization.
+- \`StudioProjectTeam\` links projects to 0..N teams.
+
+## Access rules
+
+- **Admins/owners**: always have access to all projects in the organization.
+- **Org-wide projects**: if a project has **no team links**, all organization members can access it.
+- **Team-scoped projects**: if a project has **one or more team links**, a user must be a member of at least one linked team.
+
+## GraphQL surfaces
+
+- Read:\n  - \`myStudioProjects\` (returns only projects you can access)\n  - \`studioProjectBySlug(slug)\` (enforces the same access rules)\n  - \`myTeams\`\n  - \`projectTeams(projectId)\`\n\n- Write:\n  - \`createStudioProject(input.teamIds?)\` (teamIds optional)\n  - \`setProjectTeams(projectId, teamIds)\` (admin-only)\n
+## Related\n+\n+- Team administration + invitations: see \`/docs/tech/studio/team-invitations\`.\n+
+## Notes
+
+Payloads and events must avoid secrets/PII. For Sandbox, the model remains local-first and unlogged.
+`
+}];
+registerDocBlocks(tech_studio_project_access_teams_DocBlocks);
+
+//#endregion
+//#region ../../libs/contracts/src/docs/tech/studio/team-invitations.docblock.ts
+const tech_studio_team_invitations_DocBlocks = [{
+	id: "docs.tech.studio.team-invitations",
+	title: "Studio Teams & Invitations",
+	summary: "Admin-only team management and email invitation flow to join an organization and optionally a team.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/studio/team-invitations",
+	tags: [
+		"studio",
+		"teams",
+		"invitations",
+		"access-control",
+		"onboarding"
+	],
+	body: `# Studio Teams & Invitations
+
+Studio uses **organization membership** as the base access model. Teams are optional and used to refine access to projects.
+
+## Who can manage teams?
+
+- **Admins/owners only**: create, rename, delete teams; manage project team access; issue invitations.
+
+## Invitation data model
+
+- \`Invitation\` rows are stored under an organization and target an **email** address.\n
+- An invitation can optionally target a \`teamId\`, which will grant the user membership in that team upon acceptance.
+
+Key fields:
+- \`email\`: invited address (must match the accepting user's account email)\n
+- \`status\`: \`pending | accepted | declined | expired\`\n
+- \`teamId?\`: optional team to join\n
+- \`inviterId\`: user who issued the invitation
+
+## GraphQL surfaces
+
+- Team CRUD (admin-only):\n
+  - \`createTeam(name)\`\n
+  - \`renameTeam(teamId, name)\`\n
+  - \`deleteTeam(teamId)\`\n
+
+- Invitations (admin-only):\n
+  - \`organizationInvitations\`\n
+  - \`inviteToOrganization(email, role?, teamId?)\` → returns \`inviteUrl\` and whether an email was sent
+
+## Accepting an invitation
+
+The invite link is served as:\n
+- \`/invite/{invitationId}\`
+
+Acceptance rules:
+- The user must be authenticated.\n
+- The authenticated user’s email must match \`Invitation.email\`.\n
+- If not already a member, create \`Member(userId, organizationId, role)\`.\n
+- If \`teamId\` is present, ensure \`TeamMember(teamId, userId)\`.\n
+- Mark invitation \`status='accepted'\` and set \`acceptedAt\`.\n
+- Set \`activeOrganizationId\` for the session so \`/studio/*\` routes work immediately.
+
+## Email delivery
+
+- If \`RESEND_API_KEY\` is set, the system attempts to send an email.\n
+- Otherwise, the UI uses the returned \`inviteUrl\` for manual copy/share.
+`
+}];
+registerDocBlocks(tech_studio_team_invitations_DocBlocks);
+
 //#endregion
 //#region src/docs/learning-journey-ui-shared.docblock.ts
 registerDocBlocks([{