@lssm/example.learning-journey-registry 0.0.0-canary-20251217080011 → 0.0.0-canary-20251219202229

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js

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

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js.map

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

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js

@@ -0,0 +1,37 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region ../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js
+registerDocBlocks([{
+	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\`.
+`
+}]);
+
+//#endregion
+//# sourceMappingURL=mcp-endpoints.docblock.js.map

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-endpoints.docblock.js","names":[],"sources":["../../../../../../../../../../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../registry.js\";\n\n//#region ../../libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js\nconst tech_mcp_endpoints_DocBlocks = [{\n\tid: \"docs.tech.mcp.endpoints\",\n\ttitle: \"ContractSpec MCP endpoints\",\n\tsummary: \"Dedicated MCP servers for docs, CLI usage, and internal development.\",\n\tkind: \"reference\",\n\tvisibility: \"mixed\",\n\troute: \"/docs/tech/mcp/endpoints\",\n\ttags: [\n\t\t\"mcp\",\n\t\t\"docs\",\n\t\t\"cli\",\n\t\t\"internal\"\n\t],\n\tbody: `# 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`\n}];\nregisterDocBlocks(tech_mcp_endpoints_DocBlocks);\n\n//#endregion\n//# sourceMappingURL=mcp-endpoints.docblock.js.map"],"mappings":";;;AAkCA,kBA/BqC,CAAC;CACrC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;CAiBN,CAAC,CAC6C"}

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/presentation-runtime.docblock.js

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

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/presentation-runtime.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation-runtime.docblock.js","names":[],"sources":["../../../../../../../../../../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/presentation-runtime.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../registry.js\";\n\n//#region ../../libs/contracts/dist/docs/tech/presentation-runtime.docblock.js\nconst tech_presentation_runtime_DocBlocks = [{\n\tid: \"docs.tech.presentation-runtime\",\n\ttitle: \"Presentation Runtime\",\n\tsummary: \"Cross-platform runtime for list pages and presentation flows.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/presentation-runtime\",\n\ttags: [\"tech\", \"presentation-runtime\"],\n\tbody: \"## 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\"\n}];\nregisterDocBlocks(tech_presentation_runtime_DocBlocks);\n\n//#endregion\n//# sourceMappingURL=presentation-runtime.docblock.js.map"],"mappings":";;;AAaA,kBAV4C,CAAC;CAC5C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,QAAQ,uBAAuB;CACtC,MAAM;CACN,CAAC,CACoD"}

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/schema/README.docblock.js

@@ -0,0 +1,20 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/schema/README.docblock.js
+registerDocBlocks([{
+	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"
+}]);
+
+//#endregion
+//# sourceMappingURL=README.docblock.js.map

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/schema/README.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"README.docblock.js","names":[],"sources":["../../../../../../../../../../../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/schema/README.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region ../../libs/contracts/dist/docs/tech/schema/README.docblock.js\nconst tech_schema_README_DocBlocks = [{\n\tid: \"docs.tech.schema.README\",\n\ttitle: \"Multi‑File Prisma Schema Conventions (per database)\",\n\tsummary: \"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.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/schema/README\",\n\ttags: [\n\t\t\"tech\",\n\t\t\"schema\",\n\t\t\"README\"\n\t],\n\tbody: \"# 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\"\n}];\nregisterDocBlocks(tech_schema_README_DocBlocks);\n\n//#endregion\n//# sourceMappingURL=README.docblock.js.map"],"mappings":";;;AAiBA,kBAdqC,CAAC;CACrC,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;CACN,CAAC,CAC6C"}

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js

@@ -0,0 +1,48 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js
+registerDocBlocks([{
+	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.
+`
+}]);
+
+//#endregion
+//# sourceMappingURL=learning-events.docblock.js.map

package/dist/examples/learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-events.docblock.js","names":[],"sources":["../../../../../../../../../../../learning-journey-ui-onboarding/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region ../../libs/contracts/dist/docs/tech/studio/learning-events.docblock.js\nconst tech_studio_learning_events_DocBlocks = [{\n\tid: \"docs.tech.studio.learning-events\",\n\ttitle: \"Studio Learning Events\",\n\tsummary: \"Studio persists learning/activity events to the database; Sandbox keeps learning local-first and unlogged.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/studio/learning-events\",\n\ttags: [\n\t\t\"studio\",\n\t\t\"learning\",\n\t\t\"events\",\n\t\t\"analytics\",\n\t\t\"sandbox\"\n\t],\n\tbody: `# Studio Learning Events\n\nStudio emits lightweight **learning/activity events** to support onboarding, ambient coaching, and learning journeys.\n\n## Persistence model\n\n- **Studio**: events are persisted to the database in \\`StudioLearningEvent\\` and are organization-scoped (optionally project-scoped).\n- **Sandbox**: events remain **local-only** (unlogged); they must never be sent to backend services.\n\n## GraphQL API\n\n- \\`recordLearningEvent(input: { name, projectId?, payload? })\\`\n- \\`myLearningEvents(projectId?, limit?)\\`\n- \\`myOnboardingTracks(productId?, includeProgress?)\\`\n- \\`myOnboardingProgress(trackKey)\\`\n- \\`dismissOnboardingTrack(trackKey)\\`\n\n## Common event names (convention)\n\n- \\`module.navigated\\` — user navigated to a Studio module (payload at minimum: \\`{ moduleId }\\`).\n- \\`studio.template.instantiated\\` — created a new Studio project (starter template). Payload commonly includes \\`{ templateId, projectSlug }\\`.\n- \\`spec.changed\\` — created or updated a Studio spec. Payload may include \\`{ action: 'create' | 'update', specId?, specType? }\\`.\n- \\`regeneration.completed\\` — finished a “regen/deploy” action (currently emitted on successful Studio deploy actions).\n- \\`studio.evolution.applied\\` — completed an Evolution session (payload commonly includes \\`{ evolutionSessionId }\\`).\n\nThese events are intentionally minimal and must avoid PII/secrets in payloads.\n`\n}];\nregisterDocBlocks(tech_studio_learning_events_DocBlocks);\n\n//#endregion\n//# sourceMappingURL=learning-events.docblock.js.map"],"mappings":";;;AA6CA,kBA1C8C,CAAC;CAC9C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BN,CAAC,CACsD"}