@lssm/example.learning-patterns 0.0.0-canary-20251217083314 → 1.41.0

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

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

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

@@ -1,48 +0,0 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/studio/learning-events.docblock.js
-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

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

@@ -1,45 +0,0 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/studio/project-access-teams.docblock.js
-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

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

@@ -1,67 +0,0 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/studio/project-routing.docblock.js
-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

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

@@ -1,40 +0,0 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/studio/sandbox-unlogged.docblock.js
-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

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

@@ -1,47 +0,0 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/studio/workspace-ops.docblock.js
-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

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

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

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

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

package/dist/tracks/ambient-coach.d.ts

@@ -1,7 +0,0 @@
-import { LearningJourneyTrackSpec } from "@lssm/module.learning-journey/track-spec";
-
-//#region src/tracks/ambient-coach.d.ts
-declare const ambientCoachTrack: LearningJourneyTrackSpec;
-declare const ambientCoachTracks: LearningJourneyTrackSpec[];
-//#endregion
-export { ambientCoachTrack, ambientCoachTracks };

package/dist/tracks/drills.d.ts

@@ -1,7 +0,0 @@
-import { LearningJourneyTrackSpec } from "@lssm/module.learning-journey/track-spec";
-
-//#region src/tracks/drills.d.ts
-declare const drillsTrack: LearningJourneyTrackSpec;
-declare const drillTracks: LearningJourneyTrackSpec[];
-//#endregion
-export { drillTracks, drillsTrack };

package/dist/tracks/index.d.ts

@@ -1,4 +0,0 @@
-import { drillTracks, drillsTrack } from "./drills.js";
-import { ambientCoachTrack, ambientCoachTracks } from "./ambient-coach.js";
-import { questTrack, questTracks } from "./quests.js";
-export { ambientCoachTrack, ambientCoachTracks, drillTracks, drillsTrack, questTrack, questTracks };

package/dist/tracks/quests.d.ts

@@ -1,7 +0,0 @@
-import { LearningJourneyTrackSpec } from "@lssm/module.learning-journey/track-spec";
-
-//#region src/tracks/quests.d.ts
-declare const questTrack: LearningJourneyTrackSpec;
-declare const questTracks: LearningJourneyTrackSpec[];
-//#endregion
-export { questTrack, questTracks };