@lssm/lib.contracts 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217072406

package/dist/docs/tech/contracts/ops-to-presentation-linking.docblock.js

@@ -1,62 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.ops-to-presentation-linking`,title:`Ops ↔ Presentation linking (V2)`,summary:`This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/ops-to-presentation-linking`,tags:[`tech`,`contracts`,`ops-to-presentation-linking`],body:`### Ops ↔ Presentation linking (V2)
+import { registerDocBlocks } from "../../registry.js";
 
-This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.
+//#region src/docs/tech/contracts/ops-to-presentation-linking.docblock.ts
+const tech_contracts_ops_to_presentation_linking_DocBlocks = [{
+	id: "docs.tech.contracts.ops-to-presentation-linking",
+	title: "Ops ↔ Presentation linking (V2)",
+	summary: "This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/ops-to-presentation-linking",
+	tags: [
+		"tech",
+		"contracts",
+		"ops-to-presentation-linking"
+	],
+	body: "### Ops ↔ Presentation linking (V2)\n\nThis document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.\n\n- Location: `@lssm/lib.contracts/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\n- Validation: `installFeature()` validates that linked ops exist in `SpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\n\nExample:\n\n```ts\nimport type { SpecRegistry } from '@lssm/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@lssm/lib.contracts';\n\nexport function buildFeaturesWithOps(ops: SpecRegistry) {\n  const features = new FeatureRegistry();\n  features.register(\n    createFeatureModule(\n      {\n        key: 'myapp.widgets.linkage',\n        title: 'Widgets (linked)',\n        description: 'Links create/update ops to UI presentations',\n        domain: 'widgets',\n        tags: ['widgets', 'linkage'],\n        stability: 'beta',\n      },\n      {\n        operations: [\n          { name: 'widgets.create', version: 1 },\n          { name: 'widgets.update', version: 1 },\n        ],\n        presentations: [{ name: 'myapp.widgets.editor.page', version: 1 }],\n        opToPresentation: [\n          {\n            op: { name: 'widgets.create', version: 1 },\n            pres: { name: 'myapp.widgets.editor.page', version: 1 },\n          },\n          {\n            op: { name: 'widgets.update', version: 1 },\n            pres: { name: 'myapp.widgets.editor.page', version: 1 },\n          },\n        ],\n        presentationsTargets: [\n          {\n            name: 'myapp.widgets.editor.page',\n            version: 1,\n            targets: ['react', 'markdown'],\n          },\n        ],\n      }\n    )\n  );\n  return { features };\n}\n```\n\nNotes\n\n- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.\n- Presentations can target multiple outputs (`react`, `markdown`, `application/json`, `application/xml`).\n- Use `renderFeaturePresentation()` to render a descriptor to a given target with a component map.\n"
+}];
+registerDocBlocks(tech_contracts_ops_to_presentation_linking_DocBlocks);
 
-- Location: \`@lssm/lib.contracts/src/features.ts\`
-- Field: \`FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]\`
-- Validation: \`installFeature()\` validates that linked ops exist in \`SpecRegistry\` and linked presentations exist in the registry, and that declared targets are present.
-
-Example:
-
-\`\`\`ts
-import type { SpecRegistry } from '@lssm/lib.contracts/src/registry';
-import { FeatureRegistry, createFeatureModule } from '@lssm/lib.contracts';
-
-export function buildFeaturesWithOps(ops: SpecRegistry) {
-  const features = new FeatureRegistry();
-  features.register(
-    createFeatureModule(
-      {
-        key: 'myapp.widgets.linkage',
-        title: 'Widgets (linked)',
-        description: 'Links create/update ops to UI presentations',
-        domain: 'widgets',
-        tags: ['widgets', 'linkage'],
-        stability: 'beta',
-      },
-      {
-        operations: [
-          { name: 'widgets.create', version: 1 },
-          { name: 'widgets.update', version: 1 },
-        ],
-        presentations: [{ name: 'myapp.widgets.editor.page', version: 1 }],
-        opToPresentation: [
-          {
-            op: { name: 'widgets.create', version: 1 },
-            pres: { name: 'myapp.widgets.editor.page', version: 1 },
-          },
-          {
-            op: { name: 'widgets.update', version: 1 },
-            pres: { name: 'myapp.widgets.editor.page', version: 1 },
-          },
-        ],
-        presentationsTargets: [
-          {
-            name: 'myapp.widgets.editor.page',
-            version: 1,
-            targets: ['react', 'markdown'],
-          },
-        ],
-      }
-    )
-  );
-  return { features };
-}
-\`\`\`
-
-Notes
-
-- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.
-- Presentations can target multiple outputs (\`react\`, \`markdown\`, \`application/json\`, \`application/xml\`).
-- Use \`renderFeaturePresentation()\` to render a descriptor to a given target with a component map.
-`}];e(t);export{t as tech_contracts_ops_to_presentation_linking_DocBlocks};
+//#endregion
+export { tech_contracts_ops_to_presentation_linking_DocBlocks };

package/dist/docs/tech/contracts/overlays.docblock.js

@@ -1,68 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.overlays`,title:`OverlaySpec Implementation`,summary:"OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@lssm/lib.overlay-engine`.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/overlays`,tags:[`tech`,`contracts`,`overlays`],body:`# OverlaySpec Implementation
-
-OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in \`@lssm/lib.overlay-engine\`.
-
-## Structure
-
-\`\`\`ts
-interface OverlaySpec {
-  overlayId: string;
-  version: string;
-  appliesTo: {
-    capability?: string;
-    workflow?: string;
-    dataView?: string;
-    presentation?: string;
-    tenantId?: string;
-    userId?: string;
-    role?: string;
-    device?: string;
-  };
-  modifications: OverlayModification[];
-}
-\`\`\`
-
-Supported modifications:
-
-- \`hideField\`
-- \`renameLabel\`
-- \`reorderFields\`
-- \`setDefault\`
-- \`addHelpText\`
-- \`makeRequired\`
-
-## Signing
-
-Overlays must be signed. Use the signer helper:
-
-\`\`\`ts
-import { signOverlay } from '@lssm/lib.overlay-engine/signer';
-
-const signed = await signOverlay(overlay, privateKeyPem);
-registry.register(signed);
-\`\`\`
-
-Keys are stored in \`OverlaySigningKey\` (Prisma) and referenced by the \`Overlay\` model for auditing.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`}];e(t);export{t as tech_contracts_overlays_DocBlocks};
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/overlays.docblock.ts
+const tech_contracts_overlays_DocBlocks = [{
+	id: "docs.tech.contracts.overlays",
+	title: "OverlaySpec Implementation",
+	summary: "OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@lssm/lib.overlay-engine`.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/overlays",
+	tags: [
+		"tech",
+		"contracts",
+		"overlays"
+	],
+	body: "# OverlaySpec Implementation\n\nOverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@lssm/lib.overlay-engine`.\n\n## Structure\n\n```ts\ninterface OverlaySpec {\n  overlayId: string;\n  version: string;\n  appliesTo: {\n    capability?: string;\n    workflow?: string;\n    dataView?: string;\n    presentation?: string;\n    tenantId?: string;\n    userId?: string;\n    role?: string;\n    device?: string;\n  };\n  modifications: OverlayModification[];\n}\n```\n\nSupported modifications:\n\n- `hideField`\n- `renameLabel`\n- `reorderFields`\n- `setDefault`\n- `addHelpText`\n- `makeRequired`\n\n## Signing\n\nOverlays must be signed. Use the signer helper:\n\n```ts\nimport { signOverlay } from '@lssm/lib.overlay-engine/signer';\n\nconst signed = await signOverlay(overlay, privateKeyPem);\nregistry.register(signed);\n```\n\nKeys are stored in `OverlaySigningKey` (Prisma) and referenced by the `Overlay` model for auditing.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"
+}];
+registerDocBlocks(tech_contracts_overlays_DocBlocks);
+
+//#endregion
+export { tech_contracts_overlays_DocBlocks };

package/dist/docs/tech/contracts/tests.docblock.js

@@ -1,132 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.tests`,title:`TestSpec & TestRunner`,summary:"Use `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same SpecRegistry handlers the app uses.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/tests`,tags:[`tech`,`contracts`,`tests`],body:`## TestSpec & TestRunner
-
-Use \`TestSpec\` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same SpecRegistry handlers the app uses.
-
-- Types & registry: \`packages/libs/contracts/src/tests/spec.ts\`
-- Runtime runner: \`packages/libs/contracts/src/tests/runner.ts\`
-- CLI: \`contractspec test\`
-
-### Structure
-
-\`\`\`ts
-export interface TestSpec {
-  meta: TestSpecMeta;
-  target: TestTarget;  // contract or workflow
-  fixtures?: Fixture[]; // optional shared setup before each scenario
-  scenarios: TestScenario[];
-  coverage?: CoverageRequirement;
-}
-\`\`\`
-
-- \`Fixture\`: run an operation before the scenario (\`operation\`, optional \`input\`)
-- \`Action\`: operation input that the scenario exercises
-- \`Assertion\`:
-  - \`expectOutput\` \`{ match }\` deep-equals the handler output
-  - \`expectError\` \`{ messageIncludes? }\` ensures an error was thrown
-  - \`expectEvents\` \`{ events: [{ name, version, min?, max? }] }\` checks emitted events
-
-### Example
-
-\`\`\`ts
-import { defineCommand, type TestSpec } from '@lssm/lib.contracts';
-
-export const AddNumbersSpec = defineCommand({
-  meta: { name: 'math.add', version: 1, /* … */ },
-  io: {
-    input: AddNumbersInput,
-    output: AddNumbersOutput,
-  },
-  policy: { auth: 'user' },
-});
-
-export const MathAddTests: TestSpec = {
-  meta: {
-    name: 'math.add.tests',
-    version: 1,
-    title: 'Math add scenarios',
-    owners: ['@team.math'],
-    tags: ['math'],
-    stability: StabilityEnum.Experimental,
-  },
-  target: { type: 'contract', operation: { name: 'math.add' } },
-  scenarios: [
-    {
-      name: 'adds positive numbers',
-      when: {
-        operation: { name: 'math.add' },
-        input: { a: 2, b: 3 },
-      },
-      then: [
-        { type: 'expectOutput', match: { sum: 5 } },
-        {
-          type: 'expectEvents',
-          events: [{ name: 'math.sum_calculated', version: 1, min: 1 }],
-        },
-      ],
-    },
-  ],
-};
-\`\`\`
-
-### Running tests
-
-1. Register the contract handlers in a \`SpecRegistry\`:
-
-\`\`\`ts
-export function createRegistry() {
-  const registry = new SpecRegistry();
-  registry.register(AddNumbersSpec);
-  registry.bind(AddNumbersSpec, addNumbersHandler);
-  return registry;
-}
-\`\`\`
-
-2. Run the CLI:
-
-\`\`\`
-contractspec test apps/math/tests/math.add.tests.ts \\
-  --registry apps/math/tests/registry.ts
-\`\`\`
-
-- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via \`TestRunner\`.
-- \`--json\` outputs machine-readable results.
-
-### Programmatic usage
-
-\`\`\`ts
-const runner = new TestRunner({
-  registry,
-  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),
-});
-
-const result = await runner.run(MathAddTests);
-console.log(result.passed, result.failed);
-\`\`\`
-
-- \`createContext\` can supply default \`HandlerCtx\` values.
-- \`beforeEach\` / \`afterEach\` hooks let you seed databases or reset state.
-
-### Best practices
-
-- Keep fixtures idempotent so scenarios can run in parallel in the future.
-- Use \`expectEvents\` to guard analytics/telemetry expectations.
-- Add specs to \`TestRegistry\` for discovery and documentation.
-- \`coverage\` captures desired coverage metrics (enforced by future tooling).
-- Pair TestSpec files with CI using \`contractspec test --json\` and fail builds when \`failed > 0\`.
-
-### Mocking with Bun's \`vi\`
-
-- Pass a single function type to \`vi.fn<TFunction>()\` so calls retain typed arguments:
-
-\`\`\`ts
-const handler = vi.fn<typeof fetch>();
-const fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;
-Object.defineProperty(fetchImpl, 'preconnect', {
-  value: vi.fn<typeof fetch.preconnect>(),
-});
-\`\`\`
-
-- When you need to inspect calls, use the typed mock (\`handler.mock.calls\`) rather than casting to \`any\`.
-- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict \`tsconfig\` settings.
-
-`}];e(t);export{t as tech_contracts_tests_DocBlocks};
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/tests.docblock.ts
+const tech_contracts_tests_DocBlocks = [{
+	id: "docs.tech.contracts.tests",
+	title: "TestSpec & TestRunner",
+	summary: "Use `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same SpecRegistry handlers the app uses.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/tests",
+	tags: [
+		"tech",
+		"contracts",
+		"tests"
+	],
+	body: "## TestSpec & TestRunner\n\nUse `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same SpecRegistry handlers the app uses.\n\n- Types & registry: `packages/libs/contracts/src/tests/spec.ts`\n- Runtime runner: `packages/libs/contracts/src/tests/runner.ts`\n- CLI: `contractspec test`\n\n### Structure\n\n```ts\nexport interface TestSpec {\n  meta: TestSpecMeta;\n  target: TestTarget;  // contract or workflow\n  fixtures?: Fixture[]; // optional shared setup before each scenario\n  scenarios: TestScenario[];\n  coverage?: CoverageRequirement;\n}\n```\n\n- `Fixture`: run an operation before the scenario (`operation`, optional `input`)\n- `Action`: operation input that the scenario exercises\n- `Assertion`:\n  - `expectOutput` `{ match }` deep-equals the handler output\n  - `expectError` `{ messageIncludes? }` ensures an error was thrown\n  - `expectEvents` `{ events: [{ name, version, min?, max? }] }` checks emitted events\n\n### Example\n\n```ts\nimport { defineCommand, type TestSpec } from '@lssm/lib.contracts';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { name: 'math.add', version: 1, /* … */ },\n  io: {\n    input: AddNumbersInput,\n    output: AddNumbersOutput,\n  },\n  policy: { auth: 'user' },\n});\n\nexport const MathAddTests: TestSpec = {\n  meta: {\n    name: 'math.add.tests',\n    version: 1,\n    title: 'Math add scenarios',\n    owners: ['@team.math'],\n    tags: ['math'],\n    stability: StabilityEnum.Experimental,\n  },\n  target: { type: 'contract', operation: { name: 'math.add' } },\n  scenarios: [\n    {\n      name: 'adds positive numbers',\n      when: {\n        operation: { name: 'math.add' },\n        input: { a: 2, b: 3 },\n      },\n      then: [\n        { type: 'expectOutput', match: { sum: 5 } },\n        {\n          type: 'expectEvents',\n          events: [{ name: 'math.sum_calculated', version: 1, min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `SpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new SpecRegistry();\n  registry.register(AddNumbersSpec);\n  registry.bind(AddNumbersSpec, addNumbersHandler);\n  return registry;\n}\n```\n\n2. Run the CLI:\n\n```\ncontractspec test apps/math/tests/math.add.tests.ts \\\n  --registry apps/math/tests/registry.ts\n```\n\n- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via `TestRunner`.\n- `--json` outputs machine-readable results.\n\n### Programmatic usage\n\n```ts\nconst runner = new TestRunner({\n  registry,\n  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),\n});\n\nconst result = await runner.run(MathAddTests);\nconsole.log(result.passed, result.failed);\n```\n\n- `createContext` can supply default `HandlerCtx` values.\n- `beforeEach` / `afterEach` hooks let you seed databases or reset state.\n\n### Best practices\n\n- Keep fixtures idempotent so scenarios can run in parallel in the future.\n- Use `expectEvents` to guard analytics/telemetry expectations.\n- Add specs to `TestRegistry` for discovery and documentation.\n- `coverage` captures desired coverage metrics (enforced by future tooling).\n- Pair TestSpec files with CI using `contractspec test --json` and fail builds when `failed > 0`.\n\n### Mocking with Bun's `vi`\n\n- Pass a single function type to `vi.fn<TFunction>()` so calls retain typed arguments:\n\n```ts\nconst handler = vi.fn<typeof fetch>();\nconst fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;\nObject.defineProperty(fetchImpl, 'preconnect', {\n  value: vi.fn<typeof fetch.preconnect>(),\n});\n```\n\n- When you need to inspect calls, use the typed mock (`handler.mock.calls`) rather than casting to `any`.\n- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict `tsconfig` settings.\n\n"
+}];
+registerDocBlocks(tech_contracts_tests_DocBlocks);
+
+//#endregion
+export { tech_contracts_tests_DocBlocks };

package/dist/docs/tech/contracts/themes.docblock.js

@@ -1 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.themes`,title:`ThemeSpec Overview`,summary:"`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts`, making them accessible to generators, docs, and runtime tooling.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/themes`,tags:[`tech`,`contracts`,`themes`],body:"# ThemeSpec Overview\n\n## Purpose\n\n`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts`, making them accessible to generators, docs, and runtime tooling.\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/themes.ts`\n- Design tokens bridge: `packages/libs/design-system/src/theme/*`\n\n## Schema\n\n```ts\nexport interface ThemeSpec {\n  meta: ThemeMeta;            // ownership metadata + { name, version, extends?, scopes? }\n  tokens: ThemeTokens;        // design tokens grouped by colors, radii, space, etc.\n  components?: ComponentVariantSpec[]; // per-component variant configuration\n  overrides?: ThemeOverride[];         // scoped tenant/user overrides\n}\n```\n\n- **ThemeMeta**\n  - `name`: fully-qualified identifier (e.g., `design.pastel`)\n  - `version`: increment when tokens/variants change in a breaking way\n  - `extends?`: optional `{ name, version }` pointer to a base theme\n  - `scopes?`: default scopes where the theme applies (`global`, `tenant`, `user`)\n- **ThemeTokens**\n  - `colors`, `radii`, `space`, `typography`, `shadows`, `motion`\n  - Each entry is a map of `{ value: T; description?: string }`\n- **ComponentVariantSpec**\n  - `component`: design-system component key (e.g., `Button`, `NavMain`)\n  - `variants`: map of variant names → `{ props?, tokens? }`\n- **ThemeOverride**\n  - `scope`: `'global' | 'tenant' | 'user'`\n  - `target`: identifier (e.g., `tenant:artisanos`, `user:123`)\n  - `tokens?` / `components?`: partial token/variant overrides for the target\n\n## Registry Usage\n\n```ts\nimport { ThemeRegistry } from '@lssm/lib.contracts/themes';\nimport { PastelTheme } from './themes/design.pastel';\n\nconst themes = new ThemeRegistry();\nthemes.register(PastelTheme);\n\nconst theme = themes.get('design.pastel');\nconst tenantVariant = themes\n  .get('design.pastel')\n  ?.overrides?.find((o) => o.target === 'tenant:artisanos');\n```\n\nThe registry guarantees `name + version` uniqueness and exposes `list()` for discovery tooling.\n\n## Rendering\n\nThe design system consumes specs (via adapters you provide) to build runtime tokens. A simple adapter might:\n\n1. Resolve the base theme + applicable overrides.\n2. Merge token maps using `ThemeTokens`.\n3. Feed the result into `mapTokensForPlatform` in `@lssm/lib.design-system`.\n\n```ts\nimport { ThemeRegistry } from '@lssm/lib.contracts/themes';\nimport { mapTokensForPlatform } from '@lssm/lib.design-system';\n\nfunction resolveTokens(registry: ThemeRegistry, ref: ThemeRef, ctx: { tenant?: string; user?: string }) {\n  const spec = registry.get(ref.name, ref.version);\n  if (!spec) throw new Error('Theme not found');\n\n  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));\n  return mapTokensForPlatform(tokens);\n}\n```\n\n## Authoring Guidelines\n\n1. Keep token names aligned with the design-system defaults (`background`, `mutedForeground`, etc.).\n2. Use `extends` to create layered themes (base brand → tenant tweaks → user-level overrides).\n3. Document variants with `description` to help designers and automation understand intent.\n4. Prefer scoped overrides (`tenant:foo`) instead of duplicating the entire theme per tenant.\n5. When tokens influence multiple components, capture them in `tokens` and keep `components` for API-level variant wiring.\n\n## CLI (Future Work)\n\nThe `contractspec` CLI does not yet scaffold theme specs. Planned additions:\n\n- `contractspec create --type theme`\n- `contractspec build <theme.theme.ts>` → generate design-system adapters\n\nFor now, author specs manually and register them alongside contract bundles.\n\n"}];e(t);export{t as tech_contracts_themes_DocBlocks};
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/themes.docblock.ts
+const tech_contracts_themes_DocBlocks = [{
+	id: "docs.tech.contracts.themes",
+	title: "ThemeSpec Overview",
+	summary: "`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts`, making them accessible to generators, docs, and runtime tooling.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/themes",
+	tags: [
+		"tech",
+		"contracts",
+		"themes"
+	],
+	body: "# ThemeSpec Overview\n\n## Purpose\n\n`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts`, making them accessible to generators, docs, and runtime tooling.\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/themes.ts`\n- Design tokens bridge: `packages/libs/design-system/src/theme/*`\n\n## Schema\n\n```ts\nexport interface ThemeSpec {\n  meta: ThemeMeta;            // ownership metadata + { name, version, extends?, scopes? }\n  tokens: ThemeTokens;        // design tokens grouped by colors, radii, space, etc.\n  components?: ComponentVariantSpec[]; // per-component variant configuration\n  overrides?: ThemeOverride[];         // scoped tenant/user overrides\n}\n```\n\n- **ThemeMeta**\n  - `name`: fully-qualified identifier (e.g., `design.pastel`)\n  - `version`: increment when tokens/variants change in a breaking way\n  - `extends?`: optional `{ name, version }` pointer to a base theme\n  - `scopes?`: default scopes where the theme applies (`global`, `tenant`, `user`)\n- **ThemeTokens**\n  - `colors`, `radii`, `space`, `typography`, `shadows`, `motion`\n  - Each entry is a map of `{ value: T; description?: string }`\n- **ComponentVariantSpec**\n  - `component`: design-system component key (e.g., `Button`, `NavMain`)\n  - `variants`: map of variant names → `{ props?, tokens? }`\n- **ThemeOverride**\n  - `scope`: `'global' | 'tenant' | 'user'`\n  - `target`: identifier (e.g., `tenant:artisanos`, `user:123`)\n  - `tokens?` / `components?`: partial token/variant overrides for the target\n\n## Registry Usage\n\n```ts\nimport { ThemeRegistry } from '@lssm/lib.contracts/themes';\nimport { PastelTheme } from './themes/design.pastel';\n\nconst themes = new ThemeRegistry();\nthemes.register(PastelTheme);\n\nconst theme = themes.get('design.pastel');\nconst tenantVariant = themes\n  .get('design.pastel')\n  ?.overrides?.find((o) => o.target === 'tenant:artisanos');\n```\n\nThe registry guarantees `name + version` uniqueness and exposes `list()` for discovery tooling.\n\n## Rendering\n\nThe design system consumes specs (via adapters you provide) to build runtime tokens. A simple adapter might:\n\n1. Resolve the base theme + applicable overrides.\n2. Merge token maps using `ThemeTokens`.\n3. Feed the result into `mapTokensForPlatform` in `@lssm/lib.design-system`.\n\n```ts\nimport { ThemeRegistry } from '@lssm/lib.contracts/themes';\nimport { mapTokensForPlatform } from '@lssm/lib.design-system';\n\nfunction resolveTokens(registry: ThemeRegistry, ref: ThemeRef, ctx: { tenant?: string; user?: string }) {\n  const spec = registry.get(ref.name, ref.version);\n  if (!spec) throw new Error('Theme not found');\n\n  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));\n  return mapTokensForPlatform(tokens);\n}\n```\n\n## Authoring Guidelines\n\n1. Keep token names aligned with the design-system defaults (`background`, `mutedForeground`, etc.).\n2. Use `extends` to create layered themes (base brand → tenant tweaks → user-level overrides).\n3. Document variants with `description` to help designers and automation understand intent.\n4. Prefer scoped overrides (`tenant:foo`) instead of duplicating the entire theme per tenant.\n5. When tokens influence multiple components, capture them in `tokens` and keep `components` for API-level variant wiring.\n\n## CLI (Future Work)\n\nThe `contractspec` CLI does not yet scaffold theme specs. Planned additions:\n\n- `contractspec create --type theme`\n- `contractspec build <theme.theme.ts>` → generate design-system adapters\n\nFor now, author specs manually and register them alongside contract bundles.\n\n"
+}];
+registerDocBlocks(tech_contracts_themes_DocBlocks);
+
+//#endregion
+export { tech_contracts_themes_DocBlocks };

package/dist/docs/tech/contracts/vertical-pocket-family-office.docblock.js

@@ -1,106 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.vertical-pocket-family-office`,title:`Pocket Family Office Vertical`,summary:`Pocket Family Office is a ContractSpec reference vertical that`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/vertical-pocket-family-office`,tags:[`tech`,`contracts`,`vertical-pocket-family-office`],body:`# Pocket Family Office Vertical
-
-Pocket Family Office is a ContractSpec reference vertical that
-demonstrates finance automation atop the integration and knowledge
-layers. It is optimised for the hackathon stack (Google Cloud, Mistral,
-Qdrant, ElevenLabs) while remaining provider-agnostic.
-
-## Goals
-
-- Ingest household financial documents (uploads + Gmail threads).
-- Generate AI summaries and optionally deliver them as voice notes.
-- Schedule multi-channel reminders for upcoming bills.
-- Showcase spec-first composition of integrations, knowledge spaces, and
-  workflows.
-
-## Blueprint Overview
-
-Source: \`packages/verticals/pocket-family-office/blueprint.ts\`
-
-- **Integration slots**
-  - \`primaryLLM\` → Mistral chat/embeddings
-  - \`primaryVectorDb\` → Qdrant
-  - \`primaryStorage\` → Google Cloud Storage
-  - \`primaryOpenBanking\` → Powens BYOK project for account aggregation
-  - \`emailInbound\` / \`emailOutbound\` → Gmail + Postmark
-  - \`calendarScheduling\` → Google Calendar
-  - \`voicePlayback\` → ElevenLabs (optional)
-  - \`smsNotifications\` → Twilio (optional)
-  - \`paymentsProcessing\` → Stripe (optional)
-- **Workflows**
-  - \`process-uploaded-document\`
-  - \`upcoming-payments-reminder\`
-  - \`generate-financial-summary\`
-  - \`ingest-email-threads\`
-  - \`sync-openbanking-accounts\`
-  - \`sync-openbanking-transactions\`
-  - \`refresh-openbanking-balances\`
-  - \`generate-openbanking-overview\`
-- **Policies/Telemetry** – references tenant policy specs and
-  \`pfo.telemetry\` for observability.
-
-## Tenant Sample
-
-\`tenant.sample.ts\` binds each slot to sample connections defined in
-\`connections/samples.ts\`. Key details:
-
-- Uses Google Cloud Secret Manager URIs for all credentials.
-- Enables knowledge spaces \`knowledge.financial-docs\` and
-  \`knowledge.email-threads\`, plus the derived summaries space
-  \`knowledge.financial-overview\` populated by open banking workflows.
-- Keeps \`voicePlayback\` and \`paymentsProcessing\` optional so tenants can
-  enable them incrementally.
-
-## Contracts
-
-\`contracts/index.ts\` defines command/query specs that power the
-workflows:
-
-- \`pfo.documents.upload\` – store object + enqueue ingestion.
-- \`pfo.reminders.schedule-payment\` – send email/SMS/calendar reminders.
-- \`pfo.summary.generate\` – run RAG over knowledge spaces.
-- \`pfo.summary.dispatch\` – deliver summaries via email / voice.
-- \`pfo.email.sync-threads\` – ingest Gmail threads.
-
-## Workflows
-
-- **Process Uploaded Document**
-  1. Upload to storage / queue ingestion.
-  2. Optional human review step.
-- **Upcoming Payments Reminder**
-  1. Human review (confirm due date / channel).
-  2. Automation schedules reminders (email/SMS/calendar).
-- **Generate Financial Summary**
-  1. Run RAG to produce Markdown summary.
-  2. Dispatch summary (email + optional ElevenLabs voice note).
-- **Ingest Email Threads**
-  1. Sync Gmail threads into knowledge space.
-  2. Triage step for operators when nothing new is ingested.
-
-## Knowledge & Jobs
-
-- Knowledge spaces registered via
-  \`registerFinancialDocsKnowledgeSpace\` and
-  \`registerEmailThreadsKnowledgeSpace\`.
-- Ingestion adapters (\`GmailIngestionAdapter\`, \`StorageIngestionAdapter\`)
-  and job handlers (\`createGmailSyncHandler\`,
-  \`createStorageDocumentHandler\`) wire Gmail labels & GCS prefixes into
-  Qdrant.
-- \`KnowledgeQueryService\` provides summarisation + references for the
-  summary generation workflow.
-
-## Tests & Usage
-
-\`tests/pocket-family-office.test.ts\` exercises:
-
-- Blueprint validation + config composition.
-- In-memory ingestion of a sample invoice.
-- Retrieval augmented generation producing a summary with references.
-
-Use these files as scaffolding for new tenants or as a template for the
-hackathon deliverable. Replace the sample connection metadata with
-tenant-specific IDs/secret references before deploying.
-
-
-
-`}];e(t);export{t as tech_contracts_vertical_pocket_family_office_DocBlocks};
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/vertical-pocket-family-office.docblock.ts
+const tech_contracts_vertical_pocket_family_office_DocBlocks = [{
+	id: "docs.tech.contracts.vertical-pocket-family-office",
+	title: "Pocket Family Office Vertical",
+	summary: "Pocket Family Office is a ContractSpec reference vertical that",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/vertical-pocket-family-office",
+	tags: [
+		"tech",
+		"contracts",
+		"vertical-pocket-family-office"
+	],
+	body: "# Pocket Family Office Vertical\n\nPocket Family Office is a ContractSpec reference vertical that\ndemonstrates finance automation atop the integration and knowledge\nlayers. It is optimised for the hackathon stack (Google Cloud, Mistral,\nQdrant, ElevenLabs) while remaining provider-agnostic.\n\n## Goals\n\n- Ingest household financial documents (uploads + Gmail threads).\n- Generate AI summaries and optionally deliver them as voice notes.\n- Schedule multi-channel reminders for upcoming bills.\n- Showcase spec-first composition of integrations, knowledge spaces, and\n  workflows.\n\n## Blueprint Overview\n\nSource: `packages/verticals/pocket-family-office/blueprint.ts`\n\n- **Integration slots**\n  - `primaryLLM` → Mistral chat/embeddings\n  - `primaryVectorDb` → Qdrant\n  - `primaryStorage` → Google Cloud Storage\n  - `primaryOpenBanking` → Powens BYOK project for account aggregation\n  - `emailInbound` / `emailOutbound` → Gmail + Postmark\n  - `calendarScheduling` → Google Calendar\n  - `voicePlayback` → ElevenLabs (optional)\n  - `smsNotifications` → Twilio (optional)\n  - `paymentsProcessing` → Stripe (optional)\n- **Workflows**\n  - `process-uploaded-document`\n  - `upcoming-payments-reminder`\n  - `generate-financial-summary`\n  - `ingest-email-threads`\n  - `sync-openbanking-accounts`\n  - `sync-openbanking-transactions`\n  - `refresh-openbanking-balances`\n  - `generate-openbanking-overview`\n- **Policies/Telemetry** – references tenant policy specs and\n  `pfo.telemetry` for observability.\n\n## Tenant Sample\n\n`tenant.sample.ts` binds each slot to sample connections defined in\n`connections/samples.ts`. Key details:\n\n- Uses Google Cloud Secret Manager URIs for all credentials.\n- Enables knowledge spaces `knowledge.financial-docs` and\n  `knowledge.email-threads`, plus the derived summaries space\n  `knowledge.financial-overview` populated by open banking workflows.\n- Keeps `voicePlayback` and `paymentsProcessing` optional so tenants can\n  enable them incrementally.\n\n## Contracts\n\n`contracts/index.ts` defines command/query specs that power the\nworkflows:\n\n- `pfo.documents.upload` – store object + enqueue ingestion.\n- `pfo.reminders.schedule-payment` – send email/SMS/calendar reminders.\n- `pfo.summary.generate` – run RAG over knowledge spaces.\n- `pfo.summary.dispatch` – deliver summaries via email / voice.\n- `pfo.email.sync-threads` – ingest Gmail threads.\n\n## Workflows\n\n- **Process Uploaded Document**\n  1. Upload to storage / queue ingestion.\n  2. Optional human review step.\n- **Upcoming Payments Reminder**\n  1. Human review (confirm due date / channel).\n  2. Automation schedules reminders (email/SMS/calendar).\n- **Generate Financial Summary**\n  1. Run RAG to produce Markdown summary.\n  2. Dispatch summary (email + optional ElevenLabs voice note).\n- **Ingest Email Threads**\n  1. Sync Gmail threads into knowledge space.\n  2. Triage step for operators when nothing new is ingested.\n\n## Knowledge & Jobs\n\n- Knowledge spaces registered via\n  `registerFinancialDocsKnowledgeSpace` and\n  `registerEmailThreadsKnowledgeSpace`.\n- Ingestion adapters (`GmailIngestionAdapter`, `StorageIngestionAdapter`)\n  and job handlers (`createGmailSyncHandler`,\n  `createStorageDocumentHandler`) wire Gmail labels & GCS prefixes into\n  Qdrant.\n- `KnowledgeQueryService` provides summarisation + references for the\n  summary generation workflow.\n\n## Tests & Usage\n\n`tests/pocket-family-office.test.ts` exercises:\n\n- Blueprint validation + config composition.\n- In-memory ingestion of a sample invoice.\n- Retrieval augmented generation producing a summary with references.\n\nUse these files as scaffolding for new tenants or as a template for the\nhackathon deliverable. Replace the sample connection metadata with\ntenant-specific IDs/secret references before deploying.\n\n\n\n"
+}];
+registerDocBlocks(tech_contracts_vertical_pocket_family_office_DocBlocks);
+
+//#endregion
+export { tech_contracts_vertical_pocket_family_office_DocBlocks };