@lssm/example.team-hub 0.0.0-canary-20251217080011 → 1.41.0

package/dist/libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js

@@ -1,357 +0,0 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js
-const tech_llm_integration_DocBlocks = [
-	{
-		id: "docs.tech.llm.overview",
-		title: "LLM Integration Overview",
-		summary: "Export specs to LLM-friendly formats, generate implementation guides, and verify implementations.",
-		kind: "reference",
-		visibility: "public",
-		route: "/docs/tech/llm/overview",
-		tags: [
-			"llm",
-			"ai",
-			"export",
-			"guide",
-			"verify"
-		],
-		body: `# LLM Integration
-
-ContractSpec provides first-class LLM integration to bridge specifications and AI coding agents.
-
-## Core Features
-
-### 1. Multi-Format Export
-
-Export specs to markdown in formats optimized for LLM consumption:
-
-- **Context format**: Summary for understanding (goal, context, acceptance criteria)
-- **Full format**: Complete spec with all details (I/O schemas, policy, events)
-- **Prompt format**: Actionable prompt with implementation instructions
-
-### 2. Implementation Guidance
-
-Generate agent-specific implementation plans:
-
-- **Claude Code**: Extended thinking mode with structured prompts
-- **Cursor CLI**: Background/composer mode with .mdc rules generation
-- **Generic MCP**: Standard format for any MCP-compatible agent
-
-### 3. Tiered Verification
-
-Verify implementations against specs:
-
-- **Tier 1 (Structure)**: Types, exports, imports validation
-- **Tier 2 (Behavior)**: Scenario coverage, error handling, events
-- **Tier 3 (AI Review)**: Semantic compliance analysis via LLM
-
-## Access Points
-
-| Surface | Commands/Tools |
-|---------|---------------|
-| CLI | \`contractspec llm export\`, \`guide\`, \`verify\`, \`copy\` |
-| MCP | \`llm.export\`, \`llm.guide\`, \`llm.verify\` tools |
-| VSCode | Export to LLM, Generate Guide, Verify, Copy commands |
-
-## Quick Start
-
-### CLI Usage
-
-\`\`\`bash
-# Export spec as markdown
-contractspec llm export path/to/my.spec.ts --format full
-
-# Generate implementation guide
-contractspec llm guide path/to/my.spec.ts --agent claude-code
-
-# Verify implementation
-contractspec llm verify path/to/my.spec.ts path/to/impl.ts --tier 2
-
-# Copy spec to clipboard
-contractspec llm copy path/to/my.spec.ts --format context
-\`\`\`
-
-### MCP Usage
-
-\`\`\`
-# Export spec
-llm.export { specPath: "path/to/my.spec.ts", format: "full" }
-
-# Generate guide
-llm.guide { specPath: "path/to/my.spec.ts", agent: "cursor-cli" }
-
-# Verify implementation
-llm.verify { specPath: "path/to/my.spec.ts", implementationPath: "path/to/impl.ts", tier: "2" }
-\`\`\`
-
-### Programmatic Usage
-
-\`\`\`typescript
-import { specToFullMarkdown, specToAgentPrompt } from '@lssm/lib.contracts/llm';
-import { createAgentGuideService, createVerifyService } from '@lssm/bundle.contractspec-workspace';
-
-// Export
-const markdown = specToFullMarkdown(mySpec);
-
-// Generate guide
-const guideService = createAgentGuideService({ defaultAgent: 'claude-code' });
-const guide = guideService.generateGuide(mySpec);
-
-// Verify
-const verifyService = createVerifyService();
-const result = await verifyService.verify(mySpec, implementationCode, {
-  tiers: ['structure', 'behavior']
-});
-\`\`\`
-`
-	},
-	{
-		id: "docs.tech.llm.export-formats",
-		title: "LLM Export Formats",
-		summary: "Detailed explanation of the three export formats for LLM consumption.",
-		kind: "reference",
-		visibility: "public",
-		route: "/docs/tech/llm/export-formats",
-		tags: [
-			"llm",
-			"export",
-			"markdown"
-		],
-		body: `# LLM Export Formats
-
-ContractSpec provides three export formats optimized for different LLM use cases.
-
-## Context Format
-
-Best for: Understanding what a spec does, providing background to LLMs.
-
-Includes:
-- Spec name, version, type
-- Goal and context
-- Description
-- Acceptance scenarios
-
-Example:
-
-\`\`\`markdown
-# users.createUser (v1)
-
-> Create a new user account with email verification.
-
-**Type:** command | **Stability:** stable
-
-## Goal
-Create a new user in the system and trigger email verification.
-
-## Context
-Part of the user onboarding flow. Called after signup form submission.
-
-## Acceptance Criteria
-### Happy path
-**Given:** Valid email and password
-**When:** User submits registration
-**Then:** Account is created, verification email is sent
-\`\`\`
-
-## Full Format
-
-Best for: Complete documentation, implementation reference.
-
-Includes everything:
-- All metadata
-- JSON schemas for I/O
-- Error definitions
-- Policy (auth, rate limits, PII)
-- Events emitted
-- Examples
-- Transport configuration
-
-## Prompt Format
-
-Best for: Feeding directly to coding agents.
-
-Includes:
-- Task header with clear instructions
-- Full spec context
-- Implementation requirements
-- Task-specific guidance (implement/test/refactor/review)
-- Expected output format
-
-The prompt format adapts based on task type:
-- **implement**: Full implementation with tests
-- **test**: Test generation for existing code
-- **refactor**: Refactoring while maintaining behavior
-- **review**: Code review against spec
-`
-	},
-	{
-		id: "docs.tech.llm.agent-adapters",
-		title: "Agent Adapters",
-		summary: "Adapters for different AI coding agents (Claude, Cursor, MCP).",
-		kind: "reference",
-		visibility: "public",
-		route: "/docs/tech/llm/agent-adapters",
-		tags: [
-			"llm",
-			"agents",
-			"claude",
-			"cursor",
-			"mcp"
-		],
-		body: `# Agent Adapters
-
-ContractSpec provides specialized adapters for different AI coding agents.
-
-## Claude Code Adapter
-
-Optimized for Anthropic Claude's extended thinking and code generation.
-
-Features:
-- Structured markdown with clear sections
-- Checklists for steps and verification
-- Icons for file operations (📝 create, ✏️ modify)
-- System prompt for ContractSpec context
-
-Usage:
-\`\`\`typescript
-const guideService = createAgentGuideService({ defaultAgent: 'claude-code' });
-const result = guideService.generateGuide(spec, { agent: 'claude-code' });
-// result.prompt.systemPrompt - Claude system context
-// result.prompt.taskPrompt - Task-specific instructions
-\`\`\`
-
-## Cursor CLI Adapter
-
-Optimized for Cursor's background/composer mode.
-
-Features:
-- Compact format for context efficiency
-- .mdc cursor rules generation
-- Integration with Cursor's file system
-- Concise step lists
-
-Generate Cursor Rules:
-\`\`\`typescript
-const cursorRules = guideService.generateAgentConfig(spec, 'cursor-cli');
-// Save to .cursor/rules/my-spec.mdc
-\`\`\`
-
-## Generic MCP Adapter
-
-Works with any MCP-compatible agent (Cline, Aider, etc.).
-
-Features:
-- Standard markdown format
-- Table-based metadata
-- JSON resource format support
-- Prompt message format
-
-The generic adapter is the default and works across all agents.
-
-## Choosing an Adapter
-
-| Agent | Best For | Key Features |
-|-------|----------|--------------|
-| Claude Code | Complex implementations | Extended thinking, detailed steps |
-| Cursor CLI | IDE-integrated work | Cursor rules, compact format |
-| Generic MCP | Any MCP agent | Universal compatibility |
-`
-	},
-	{
-		id: "docs.tech.llm.verification",
-		title: "Implementation Verification",
-		summary: "Tiered verification of implementations against specifications.",
-		kind: "reference",
-		visibility: "public",
-		route: "/docs/tech/llm/verification",
-		tags: [
-			"llm",
-			"verify",
-			"validation",
-			"testing"
-		],
-		body: `# Implementation Verification
-
-ContractSpec provides tiered verification to check if implementations comply with specs.
-
-## Verification Tiers
-
-### Tier 1: Structure (Fast)
-
-Checks TypeScript structure against spec requirements:
-
-| Check | What it validates |
-|-------|------------------|
-| Handler export | Function is properly exported |
-| Contracts import | Imports from @lssm/lib.contracts |
-| Schema import | Imports from @lssm/lib.schema |
-| No \`any\` type | TypeScript strict compliance |
-| Error handling | Error codes are referenced |
-| Event emission | Event patterns exist |
-| Input validation | Validation patterns used |
-| Async patterns | Async/await for commands |
-
-### Tier 2: Behavior (Comprehensive)
-
-Checks implementation coverage of spec behaviors:
-
-| Check | What it validates |
-|-------|------------------|
-| Scenario coverage | Acceptance scenarios implemented |
-| Example coverage | Example I/O values referenced |
-| Error cases | All error conditions handled |
-| Event conditions | Events emitted correctly |
-| Idempotency | Idempotent patterns (if required) |
-
-### Tier 3: AI Review (Deep)
-
-Uses LLM for semantic analysis:
-
-- Does the implementation fulfill the spec's intent?
-- Are edge cases properly handled?
-- Is the code quality acceptable?
-- Are there any subtle violations?
-
-Requires AI API key configuration.
-
-## Running Verification
-
-\`\`\`typescript
-const verifyService = createVerifyService({
-  aiApiKey: process.env.ANTHROPIC_API_KEY, // Optional, for Tier 3
-  aiProvider: 'anthropic',
-});
-
-const result = await verifyService.verify(spec, implementationCode, {
-  tiers: ['structure', 'behavior'],
-  failFast: false,
-  includeSuggestions: true,
-});
-
-console.log(result.passed);  // true/false
-console.log(result.score);   // 0-100
-console.log(result.summary); // Human-readable summary
-\`\`\`
-
-## Verification Report
-
-The report includes:
-
-- **passed**: Overall compliance
-- **score**: 0-100 score
-- **issues**: Array of problems found
-- **suggestions**: Recommended fixes
-- **coverage**: Metrics on scenario/error/field coverage
-
-Each issue has:
-- **severity**: error, warning, or info
-- **category**: type, export, import, scenario, error_handling, semantic
-- **message**: Description of the issue
-- **suggestion**: How to fix it
-`
-	}
-];
-registerDocBlocks(tech_llm_integration_DocBlocks);
-
-//#endregion

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

@@ -1,37 +0,0 @@
-import { registerDocBlocks } from "../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js
-const tech_mcp_endpoints_DocBlocks = [{
-	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
-
-Three dedicated MCP servers keep AI agents efficient and scoped:
-
-- **Docs MCP**: \`/api/mcp/docs\` — exposes DocBlocks as resources + presentations. Tool: \`docs.search\`.
-- **CLI MCP**: \`/api/mcp/cli\` — surfaces CLI quickstart/reference/README and suggests commands. Tool: \`cli.suggestCommand\`.
-- **Internal MCP**: \`/api/mcp/internal\` — internal routing hints, playbook, and example registry access. Tool: \`internal.describe\`.
-
-### Usage notes
-- Transports are HTTP POST (streamable HTTP); SSE is disabled.
-- Resources are namespaced (\`docs://*\`, \`cli://*\`, \`internal://*\`) and are read-only.
-- Internal MCP also exposes the examples registry via \`examples://*\` resources:
-  - \`examples://list?q=<query>\`
-  - \`examples://example/<id>\`
-- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.
-- GraphQL remains at \`/graphql\`; health at \`/health\`.
-`
-}];
-registerDocBlocks(tech_mcp_endpoints_DocBlocks);
-
-//#endregion

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

@@ -1,16 +0,0 @@
-import { registerDocBlocks } from "../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/presentation-runtime.docblock.js
-const tech_presentation_runtime_DocBlocks = [{
-	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"
-}];
-registerDocBlocks(tech_presentation_runtime_DocBlocks);
-
-//#endregion

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/learning-journeys.docblock.js

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

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

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