@lssm/example.analytics-dashboard 0.0.0-canary-20251217060804 → 0.0.0-canary-20251217062139

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

@@ -0,0 +1,357 @@
+import { a } from "../../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js
+const t = [
+	{
+		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
+`
+	}
+];
+a(t);
+
+//#endregion

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

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

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

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

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

@@ -0,0 +1,281 @@
+import { a } from "../../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/schema/README.docblock.js
+const t = [{
+	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();
+\`\`\`
+`
+}];
+a(t);
+
+//#endregion