@contractspec/lib.contracts 1.57.0 → 1.59.0

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

@@ -1,21 +1,164 @@
-import { registerDocBlocks } from "../../registry.js";
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
 
-//#region src/docs/tech/schema/README.docblock.ts
-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 `@contractspec/app.cli-database` CLI: `database import|check|generate|migrate:*|seed` to manage a single DB; `@contractspec/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 '@contractspec/app.cli-database';\n\nexport default defineMergedPrismaConfig({\n  modules: [\n    '@contractspec/app.cli-database-sigil',\n    '@contractspec/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 `@contractspec/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  - `@contractspec/app.cli-database-sigil`, `@contractspec/app.cli-database-content`, `@contractspec/app.cli-database-ops`, `@contractspec/app.cli-database-planning`, `@contractspec/app.cli-database-quill`, `@contractspec/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  - `@contractspec/app.cli-database-sigil`, `@contractspec/app.cli-database-content`, `@contractspec/app.cli-database-featureflags`, `@contractspec/app.cli-database-ops`, `@contractspec/app.cli-database-planning`, `@contractspec/app.cli-database-quill`, `@contractspec/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: `@contractspec/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### Multi-Format Wrappers\n\nUse existing schema definitions from other libraries:\n- `ZodSchemaType`: Wraps a raw Zod schema (`z.infer` becomes the TS type).\n- `JsonSchemaType`: Wraps a JSON Schema object.\n- `GraphQLSchemaType`: Wraps a GraphQL SDL string.\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 '@contractspec/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 '@contractspec/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);
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
 
-//#endregion
-export { tech_schema_README_DocBlocks };
+// src/docs/tech/schema/README.docblock.ts
+var tech_schema_README_DocBlocks = [
+  {
+    id: "docs.tech.schema.README",
+    title: "Multi\u2011File Prisma Schema Conventions (per database)",
+    summary: "We adopt Prisma multi\u2011file schema (GA \u2265 v6.7) to organize each database\u2019s 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\u2011File Prisma Schema Conventions (per database)\n\nWe adopt Prisma multi\u2011file schema (GA \u2265 v6.7) to organize each database\u2019s 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\u2011specific models split by bounded context\n```\n\nNotes:\n\n- Imported files contain only `model` and `enum` blocks (strip `datasource`/`generator`).\n- Preserve `@@schema("\u2026")` 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 `@contractspec/app.cli-database` CLI: `database import|check|generate|migrate:*|seed` to manage a single DB; `@contractspec/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 \'@contractspec/app.cli-database\';\n\nexport default defineMergedPrismaConfig({\n  modules: [\n    \'@contractspec/app.cli-database-sigil\',\n    \'@contractspec/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 \u2013 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) \u2013 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` \u2013 core identity with email, optional phone, role, passkeys, apiKeys\n- `Session` \u2013 session tokens and metadata; includes `activeOrganizationId`\n- `Account` \u2013 external providers (password, OAuth)\n- `Organization` \u2013 tenant boundary; includes `type` additional field\n- `Member`, `Invitation`, `Team`, `TeamMember` \u2013 org/teams\n- `Role`, `Permission`, `PolicyBinding` \u2013 RBAC\n- `ApiKey`, `Passkey` \u2013 programmable access and WebAuthn\n- `SsoProvider` \u2013 OIDC/SAML provider configuration (org- or user-scoped)\n- `OAuthApplication`, `OAuthAccessToken`, `OAuthConsent` \u2013 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*\u2026 but STRIT*\u2026 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` \u2013 base URL for Better Auth server\n- `BETTER_AUTH_SECRET` \u2013 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 `@contractspec/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  - `@contractspec/app.cli-database-sigil`, `@contractspec/app.cli-database-content`, `@contractspec/app.cli-database-ops`, `@contractspec/app.cli-database-planning`, `@contractspec/app.cli-database-quill`, `@contractspec/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`\u2192Organization, `uploadedBy`\u2192User)\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  - `@contractspec/app.cli-database-sigil`, `@contractspec/app.cli-database-content`, `@contractspec/app.cli-database-featureflags`, `@contractspec/app.cli-database-ops`, `@contractspec/app.cli-database-planning`, `@contractspec/app.cli-database-quill`, `@contractspec/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: `@contractspec/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### Multi-Format Wrappers\n\nUse existing schema definitions from other libraries:\n- `ZodSchemaType`: Wraps a raw Zod schema (`z.infer` becomes the TS type).\n- `JsonSchemaType`: Wraps a JSON Schema object.\n- `GraphQLSchemaType`: Wraps a GraphQL SDL string.\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 \'@contractspec/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 \u2192 GraphQL `String`\n- Numbers \u2192 `Int` if safe 32-bit integer else `Float`\n- Booleans \u2192 `Boolean`\n- Dates \u2192 custom `Date` scalar\n- Arrays<T> \u2192 list of mapped T (set `isArray: true` on the field)\n- Top-level arrays \u2192 set `isArray: true` on the model config\n- Objects \u2192 input/output object types with stable field order\n- Unions \u2192 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 \'@contractspec/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);
+export {
+  tech_schema_README_DocBlocks
+};

package/dist/docs/tech/studio/learning-events.docblock.d.ts

@@ -1,6 +1,3 @@
-import { DocBlock } from "@contractspec/lib.contracts/docs";
-
-//#region src/docs/tech/studio/learning-events.docblock.d.ts
-declare const tech_studio_learning_events_DocBlocks: DocBlock[];
-//#endregion
-export { tech_studio_learning_events_DocBlocks };
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+export declare const tech_studio_learning_events_DocBlocks: DocBlock[];
+//# sourceMappingURL=learning-events.docblock.d.ts.map

package/dist/docs/tech/studio/learning-events.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-events.docblock.d.ts","sourceRoot":"","sources":["../../../../src/docs/tech/studio/learning-events.docblock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,qCAAqC,EAAE,QAAQ,EAsC3D,CAAC"}

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

@@ -1,21 +1,161 @@
-import { registerDocBlocks } from "../../registry.js";
-
-//#region src/docs/tech/studio/learning-events.docblock.ts
-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
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/docs/tech/studio/learning-events.docblock.ts
+var 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.
 
@@ -34,16 +174,17 @@ Studio emits lightweight **learning/activity events** to support onboarding, amb
 
 ## 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 }\`).
+- \`module.navigated\` \u2014 user navigated to a Studio module (payload at minimum: \`{ moduleId }\`).
+- \`studio.template.instantiated\` \u2014 created a new Studio project (starter template). Payload commonly includes \`{ templateId, projectSlug }\`.
+- \`spec.changed\` \u2014 created or updated a Studio spec. Payload may include \`{ action: 'create' | 'update', specId?, specType? }\`.
+- \`regeneration.completed\` \u2014 finished a \u201Cregen/deploy\u201D action (currently emitted on successful Studio deploy actions).
+- \`studio.evolution.applied\` \u2014 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
-export { tech_studio_learning_events_DocBlocks };
+export {
+  tech_studio_learning_events_DocBlocks
+};

package/dist/docs/tech/studio/learning-journeys.docblock.d.ts

@@ -1,6 +1,3 @@
-import { DocBlock } from "@contractspec/lib.contracts/docs";
-
-//#region src/docs/tech/studio/learning-journeys.docblock.d.ts
-declare const tech_studio_learning_journeys_DocBlocks: DocBlock[];
-//#endregion
-export { tech_studio_learning_journeys_DocBlocks };
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+export declare const tech_studio_learning_journeys_DocBlocks: DocBlock[];
+//# sourceMappingURL=learning-journeys.docblock.d.ts.map

package/dist/docs/tech/studio/learning-journeys.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-journeys.docblock.d.ts","sourceRoot":"","sources":["../../../../src/docs/tech/studio/learning-journeys.docblock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,uCAAuC,EAAE,QAAQ,EA2E7D,CAAC"}