@lssm/example.learning-journey-registry 0.0.0-canary-20251212004227

package/dist/libs/contracts/src/docs/tech/lifecycle-stage-system.docblock.js

@@ -0,0 +1,213 @@
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.lifecycle-stage-system`,title:`ContractSpec Lifecycle Stage System – Technical Design`,summary:`This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.`,kind:`reference`,visibility:`public`,route:`/docs/tech/lifecycle-stage-system`,tags:[`tech`,`lifecycle-stage-system`],body:`## ContractSpec Lifecycle Stage System – Technical Design
+
+This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.
+
+---
+
+### 1. Architecture Overview
+
+\`\`\`
+┌──────────────────────┐
+│ @lssm/lib.lifecycle  │  Types, enums, helpers (pure data)
+└───────────┬──────────┘
+            │
+┌───────────▼──────────┐    ┌───────────────────────────┐
+│ modules/lifecycle-   │    │ modules/lifecycle-advisor  │
+│ core (detection)     │    │ (guidance & ceremonies)    │
+└───────────┬──────────┘    └───────────┬───────────────┘
+            │                           │
+            ├────────────┬──────────────┤
+            ▼            ▼              ▼
+  Adapters: analytics, intent, questionnaires
+            │
+┌───────────▼──────────┐
+│ bundles/lifecycle-   │  Managed service for Studio
+│ managed              │  (REST handlers, AI agent)     │
+└───────────┬──────────┘
+            │
+  ContractSpec Studio surfaces
+  (web/mobile APIs, CLI, docs)
+\`\`\`
+
+- **Libraries** provide shared vocabulary.
+- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.
+- **Bundles** compose modules, register agents/events, and expose APIs for Studio.
+- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve \`@lssm/bundle.contractspec-studio\` and \`@lssm/lib.database-contractspec-studio\` directly from their \`packages/.../src\` folders via \`tsconfig\` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled \`dist\` artifacts into client chunks.
+
+---
+
+### 2. Core Library (\`@lssm/lib.lifecycle\`)
+
+- Stage enum (0–6) with metadata (\`question\`, \`signals\`, \`traps\`).
+- Axes types (\`ProductPhase\`, \`CompanyPhase\`, \`CapitalPhase\`).
+- \`LifecycleSignal\` (source, metric, value, timestamp).
+- \`LifecycleMetricSnapshot\` (aggregated numbers).
+- \`LifecycleMilestone\`, \`LifecycleAction\`, \`LifecycleAssessment\` interfaces.
+- Utility helpers:
+  - \`formatStageSummary(stage, assessment)\`
+  - \`rankStageCandidates(scores)\`
+
+The library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.
+
+---
+
+### 3. Lifecycle Core Module
+
+**Location:** \`packages/modules/lifecycle-core/\`
+
+#### Components
+1. **StageSignalCollector**
+   - Accepts adapter interfaces:
+     - \`AnalyticsAdapter\` (pulls metrics from \`@lssm/lib.analytics\` or fixture streams).
+     - \`IntentAdapter\` (hooks into \`@lssm/lib.observability\` intent detectors or logs).
+     - \`QuestionnaireAdapter\` (loads JSON questionnaires and responses).
+   - Produces normalized \`LifecycleSignal[]\`.
+
+2. **StageScorer**
+   - Weighted scoring model:
+     - Base weight per stage (reflecting expected maturity).
+     - Feature weights (retention, revenue, team size, qualitative feedback).
+     - Confidence computed via variance of contributing signals.
+   - Supports pluggable scoring matrices via JSON config.
+   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.
+
+3. **LifecycleOrchestrator**
+   - Coordinates collectors + scorer.
+   - Returns \`LifecycleAssessment\` with:
+     - \`stage\`, \`confidence\`, \`axisSnapshot\`, \`signalsUsed\`.
+     - Recommended focus areas (high-level categories only).
+   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).
+
+4. **LifecycleMilestonePlanner**
+   - Loads \`milestones-catalog.json\` (no DB).
+   - Filters upcoming milestones per stage + axis.
+   - Tracks completion using provided IDs (caller persists).
+
+#### Data Files
+- \`configs/stage-weights.json\`
+- \`configs/milestones-catalog.json\`
+- \`questionnaires/stage-readiness.json\`
+
+#### Extension Hooks
+- All adapters exported as TypeScript interfaces.
+- Implementations for analytics/intent can live in bundles or apps without modifying module code.
+
+---
+
+### 4. Lifecycle Advisor Module
+
+**Location:** \`packages/modules/lifecycle-advisor/\`
+
+#### Components
+1. **LifecycleRecommendationEngine**
+   - Consumes \`LifecycleAssessment\`.
+   - Maps gaps to \`LifecycleAction[]\` using rule tables (\`stage-playbooks.ts\`).
+   - Supports override hooks for customer-specific rules.
+
+2. **ContractSpecLibraryRecommender**
+   - Maintains mapping from stage → recommended libraries/modules/bundles.
+   - Returns prioritized list with rationale and adoption prerequisites.
+
+3. **LifecycleCeremonyDesigner**
+   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).
+   - Ensures low-tech friendly instructions (clear copy, undo guidance).
+
+4. **AI Hooks**
+   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).
+   - Keeps actual LLM integration outside module.
+
+---
+
+### 5. Managed Bundle (\`lifecycle-managed\`)
+
+**Responsibilities**
+- Wire modules together.
+- Provide HTTP/GraphQL handlers (exact transport optional).
+- Register LifecycleAdvisorAgent via \`@lssm/lib.ai-agent\`.
+- LifecycleAdvisorAgent meta: domain \`operations\`, owners \`team-lifecycle\`, stability \`experimental\`, tags \`guide/lifecycle/ops\` so ops tooling can route incidents quickly.
+- Emit lifecycle events through \`@lssm/lib.bus\` + \`@lssm/lib.analytics\`.
+- Integrate with \`contractspec-studio\` packages:
+  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).
+  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).
+
+**APIs**
+- \`POST /lifecycle/assessments\`: Accepts metrics + optional questionnaire answers. Returns \`LifecycleAssessment\`.
+- \`GET /lifecycle/playbooks/:stage\`: Returns stage playbook + ceremonies.
+- \`POST /lifecycle/advise\`: Invokes LifecycleAdvisorAgent with context.
+
+**Events**
+- \`LifecycleAssessmentCreated\`
+- \`LifecycleStageChanged\`
+- \`LifecycleGuidanceConsumed\`
+
+---
+
+### 6. Library Enhancements
+
+| Library | Enhancement |
+| --- | --- |
+| \`@lssm/lib.analytics\` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by \`StageSignalCollector\`. |
+| \`@lssm/lib.evolution\` | Accepts \`LifecycleContext\` when ranking spec anomalies/suggestions. |
+| \`@lssm/lib.growth\` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |
+| \`@lssm/lib.observability\` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |
+
+Each enhancement must import stage types from \`@lssm/lib.lifecycle\`.
+
+---
+
+### 7. Feature Flags & Progressive Delivery
+
+- Add new flags in progressive-delivery library:
+  - \`LIFECYCLE_DETECTION_ALPHA\`
+  - \`LIFECYCLE_ADVISOR_ALPHA\`
+  - \`LIFECYCLE_MANAGED_SERVICE\`
+- Bundles/modules should check flags before enabling workflows.
+- Flags referenced in docs + Studio UI to avoid accidental exposure.
+
+---
+
+### 8. Analytics & Telemetry
+
+- Events defined in analytics library; consumed by bundle/app:
+  - \`lifecycle_assessment_run\`
+  - \`lifecycle_stage_changed\`
+  - \`lifecycle_guidance_consumed\`
+- Observability pipeline includes:
+  - Composite lifecycle health metric (weighted sum of KPIs).
+  - Drift detection comparing stage predictions over time.
+  - Alert manager recipes for regression (e.g., PMF drop).
+
+---
+
+### 9. Testing Strategy
+
+1. **Unit**
+   - StageScorer weight matrix.
+   - RecommendationEngine mapping.
+   - Library recommender stage coverage.
+
+2. **Contract**
+   - Adapters: ensure mock adapters satisfy interfaces.
+   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.
+
+3. **Integration**
+   - CLI example runs detection + guidance end-to-end on fixture data.
+   - Dashboard example renders assessments, verifying JSON structures remain stable.
+
+---
+
+### 10. Implementation Checklist
+
+- [ ] Documentation (product, tech, ops, user).
+- [ ] Library creation (\`@lssm/lib.lifecycle\`).
+- [ ] Modules (\`lifecycle-core\`, \`lifecycle-advisor\`).
+- [ ] Bundle (\`lifecycle-managed\`) + Studio wiring.
+- [ ] Library enhancements (analytics/evolution/growth/observability).
+- [ ] Examples (CLI + dashboard).
+- [ ] Feature flags + telemetry.
+- [ ] Automated tests + fixtures.
+
+Keep this document in sync as modules evolve. When adding new stages or axes, update \`@lssm/lib.lifecycle\` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch
+
+
+`}]);

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

@@ -0,0 +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"}]);

package/dist/libs/contracts/src/docs/tech/presentation-runtime.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.presentation-runtime`,title:`Presentation Runtime`,summary:`Cross-platform runtime for list pages and presentation flows.`,kind:`reference`,visibility:`public`,route:`/docs/tech/presentation-runtime`,tags:[`tech`,`presentation-runtime`],body:"## Presentation Runtime\n\nCross-platform runtime for list pages and presentation flows.\n\n### Packages\n\n- `@lssm/lib.presentation-runtime-core`: shared types and config helpers\n- `@lssm/lib.presentation-runtime-react`: React hooks (web/native-compatible API)\n- `@lssm/lib.presentation-runtime-react-native`: Native entrypoint (re-exports React API for now)\n\n### Next.js config helper\n\n```ts\n// next.config.mjs\nimport { withPresentationNextAliases } from '@lssm/lib.presentation-runtime-core/next';\n\nconst nextConfig = {\n  webpack: (config) => withPresentationNextAliases(config),\n};\n\nexport default nextConfig;\n```\n\n### Metro config helper\n\n```js\n// metro.config.js (CJS)\nconst { getDefaultConfig } = require('expo/metro-config');\nconst {\n  withPresentationMetroAliases,\n} = require('@lssm/lib.presentation-runtime-core/src/metro.cjs');\n\nconst projectRoot = __dirname;\nconst config = getDefaultConfig(projectRoot);\n\nmodule.exports = withPresentationMetroAliases(config);\n```\n\n### React hooks\n\n- `useListCoordinator`: URL + RHF + derived variables (no fetching)\n- `usePresentationController`: Same plus `fetcher` integration\n- `DataViewRenderer` (design-system): render `DataViewSpec` projections (`list`, `table`, `detail`, `grid`) using shared UI atoms\n\nBoth accept a `useUrlState` adapter. On web, use `useListUrlState` (design-system) or a Next adapter.\n\n### KYC molecules (bundle)\n\n- `ComplianceBadge` in `@lssm/bundle.strit/presentation/components/kyc` renders a status badge for KYC/compliance snapshots. It accepts a `state` (missing_core | incomplete | complete | expiring | unknown) and optional localized `labels`. Prefer consuming apps to pass translated labels (e.g., via `useT('appPlatformAdmin')`).\n\n### Markdown routes and llms.txt\n\n- Each web app exposes `/llms` (and `/llms.txt`, `/llms.md`) via rewrites. See [llmstxt.org](https://llmstxt.org/).\n- Catch‑all markdown handler lives at `app/[...slug].md/route.ts`. It resolves a page descriptor from `app/.presentations.manifest.json` and renders via the `presentations.v2` engine (target: `markdown`).\n- Per‑page companion convention: add `app/<route>/ai.ts` exporting a `PresentationDescriptorV2`.\n- Build‑time tool: `tools/generate-presentations-manifest.mjs <app-root>` populates the manifest.\n- CI check: `pnpm llms:check` verifies coverage (% of pages with descriptors) and fails if below threshold.\n"}]);

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

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

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

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

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

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

package/dist/presentations/index.js

@@ -0,0 +1 @@
+const e={domain:`learning-journey`,owners:[`learning-team`],tags:[`learning`,`journey`,`onboarding`]},t={meta:{name:`learning.journey.track_list`,version:1,description:`List of learning journeys available to the learner.`,...e},source:{type:`component`,framework:`react`,componentKey:`LearningTrackList`},targets:[`react`,`markdown`]},n={meta:{name:`learning.journey.track_detail`,version:1,description:`Track detail with steps and progress state.`,...e},source:{type:`component`,framework:`react`,componentKey:`LearningTrackDetail`},targets:[`react`,`markdown`,`application/json`]},r={meta:{name:`learning.journey.progress_widget`,version:1,description:`Compact widget showing progress for active track.`,...e},source:{type:`component`,framework:`react`,componentKey:`LearningTrackProgressWidget`},targets:[`react`]},i=[t,n,r];export{n as LearningTrackDetailPresentation,t as LearningTrackListPresentation,r as LearningTrackProgressWidgetPresentation,i as learningJourneyPresentations};

package/dist/progress-store.js

@@ -0,0 +1 @@
+const e=new Map,t=e=>t=>e.find(e=>e.id===t),n=t=>{let n=e.get(t);if(n)return n;let r=new Map;return e.set(t,r),r},r=(e,t)=>({learnerId:e,trackId:t.id,progress:0,isCompleted:!1,xpEarned:0,steps:t.steps.map(e=>({id:e.id,status:`PENDING`,xpEarned:0,occurrences:0,masteryCount:0})),startedAt:void 0,completedAt:void 0,lastActivityAt:void 0});export{n as getLearnerTracks,t as getTrackResolver,r as initProgress,e as progressStore};

package/dist/tracks.js

@@ -0,0 +1 @@
+import{crmLearningTracks as e}from"@lssm/example.learning-journey.crm-onboarding/track";import{drillTracks as t}from"@lssm/example.learning-journey.duo-drills/track";import{ambientCoachTracks as n}from"@lssm/example.learning-journey.ambient-coach/track";import{questTracks as r}from"@lssm/example.learning-journey.quest-challenges/track";import{platformLearningTracks as i}from"@lssm/example.learning-journey.platform-tour/track";import{studioLearningTracks as a}from"@lssm/example.learning-journey.studio-onboarding/track";const o=e=>({id:e.id,title:e.title,description:e.description,completionEvent:e.completion.eventName,completionCondition:e.completion,xpReward:e.xpReward,isRequired:e.isRequired,canSkip:e.canSkip,actionUrl:e.actionUrl,actionLabel:e.actionLabel,availability:e.availability,metadata:e.metadata}),s=e=>({id:e.id,name:e.name,description:e.description,productId:e.productId,targetUserSegment:e.targetUserSegment,targetRole:e.targetRole,totalXp:e.totalXp,streakRule:e.streakRule,completionRewards:e.completionRewards,steps:e.steps.map(o),metadata:e.metadata}),c=[...a,...i,...e,...t,...n,...r],l=c.map(s);export{e as crmLearningTracks,c as learningJourneyTracks,o as mapStep,s as mapTrackSpecToDto,l as onboardingTrackCatalog,i as platformLearningTracks,a as studioLearningTracks};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lssm/example.learning-journey-registry",
+  "version": "0.0.0-canary-20251212004227",
+  "description": "Registry that aggregates learning journey example tracks.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api": "./src/api.ts",
+    "./api-types": "./src/api-types.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/learning-journey-registry.docblock": "./src/docs/learning-journey-registry.docblock.ts",
+    "./presentations": "./src/presentations/index.ts",
+    "./progress-store": "./src/progress-store.ts",
+    "./tracks": "./src/tracks.ts",
+    "./*": "./*"
+  },
+  "scripts": {
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "test": "bun test",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "dependencies": {
+    "@lssm/example.learning-journey.ambient-coach": "workspace:*",
+    "@lssm/example.learning-journey.duo-drills": "workspace:*",
+    "@lssm/example.learning-journey.crm-onboarding": "workspace:*",
+    "@lssm/example.learning-journey.platform-tour": "workspace:*",
+    "@lssm/example.learning-journey.quest-challenges": "workspace:*",
+    "@lssm/example.learning-journey.studio-onboarding": "workspace:*",
+    "@lssm/module.learning-journey": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./api": "./dist/api.js",
+      "./api-types": "./dist/api-types.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/learning-journey-registry.docblock": "./dist/docs/learning-journey-registry.docblock.js",
+      "./presentations": "./dist/presentations/index.js",
+      "./progress-store": "./dist/progress-store.js",
+      "./tracks": "./dist/tracks.js",
+      "./*": "./*"
+    }
+  }
+}

package/src/api-types.ts

@@ -0,0 +1,43 @@
+import type { LearningJourneyTrackSpec } from '@lssm/module.learning-journey/track-spec';
+
+export interface LearningEvent {
+  name: string;
+  version?: number;
+  sourceModule?: string;
+  payload?: Record<string, unknown>;
+  occurredAt?: Date;
+  learnerId: string;
+  trackId?: string;
+}
+
+export type StepStatus = 'PENDING' | 'COMPLETED';
+
+export interface StepProgress {
+  id: string;
+  status: StepStatus;
+  xpEarned: number;
+  completedAt?: Date;
+  triggeringEvent?: string;
+  eventPayload?: Record<string, unknown>;
+  occurrences?: number;
+  counterStartedAt?: Date;
+  availableAt?: Date;
+  dueAt?: Date;
+  masteryCount?: number;
+}
+
+export interface TrackProgress {
+  learnerId: string;
+  trackId: string;
+  progress: number;
+  isCompleted: boolean;
+  xpEarned: number;
+  startedAt?: Date;
+  completedAt?: Date;
+  lastActivityAt?: Date;
+  steps: StepProgress[];
+}
+
+export type TrackResolver = (
+  trackId: string
+) => LearningJourneyTrackSpec | undefined;