@contractspec/lib.contracts-spec 2.0.0

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

@@ -0,0 +1,164 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/contracts/tests.docblock.ts
+var 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 OperationSpecRegistry 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 OperationSpecRegistry 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 '@contractspec/lib.contracts-spec';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { name: 'math.add', version: '1.0.0', /* … */ },\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.0.0',\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.0.0', min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `OperationSpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new OperationSpecRegistry();\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);
+export {
+  tech_contracts_tests_DocBlocks
+};

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

@@ -0,0 +1,257 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/contracts/themes.docblock.ts
+var 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 `@contractspec/lib.contracts-spec`, 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
+
+## Purpose
+
+\`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 \`@contractspec/lib.contracts-spec\`, making them accessible to generators, docs, and runtime tooling.
+
+## Location
+
+- Types & registry: \`packages/libs/contracts/src/themes.ts\`
+- Design tokens bridge: \`packages/libs/design-system/src/theme/*\`
+
+## Schema
+
+\`\`\`ts
+export interface ThemeSpec {
+  meta: ThemeMeta;            // ownership metadata + { name, version, extends?, scopes? }
+  tokens: ThemeTokens;        // design tokens grouped by colors, radii, space, etc.
+  components?: ComponentVariantSpec[]; // per-component variant configuration
+  overrides?: ThemeOverride[];         // scoped tenant/user overrides
+}
+\`\`\`
+
+- **ThemeMeta**
+  - \`name\`: fully-qualified identifier (e.g., \`design.pastel\`)
+  - \`version\`: increment when tokens/variants change in a breaking way
+  - \`extends?\`: optional \`{ name, version }\` pointer to a base theme
+  - \`scopes?\`: default scopes where the theme applies (\`global\`, \`tenant\`, \`user\`)
+- **ThemeTokens**
+  - \`colors\`, \`radii\`, \`space\`, \`typography\`, \`shadows\`, \`motion\`
+  - Each entry is a map of \`{ value: T; description?: string }\`
+- **ComponentVariantSpec**
+  - \`component\`: design-system component key (e.g., \`Button\`, \`NavMain\`)
+  - \`variants\`: map of variant names → \`{ props?, tokens? }\`
+- **ThemeOverride**
+  - \`scope\`: \`'global' | 'tenant' | 'user'\`
+  - \`target\`: identifier (e.g., \`tenant:artisanos\`, \`user:123\`)
+  - \`tokens?\` / \`components?\`: partial token/variant overrides for the target
+
+## Registry Usage
+
+\`\`\`ts
+import { ThemeRegistry } from '@contractspec/lib.contracts-spec/themes';
+import { PastelTheme } from './themes/design.pastel';
+
+const themes = new ThemeRegistry();
+themes.register(PastelTheme);
+
+const theme = themes.get('design.pastel');
+const tenantVariant = themes
+  .get('design.pastel')
+  ?.overrides?.find((o) => o.target === 'tenant:artisanos');
+\`\`\`
+
+The registry guarantees \`name + version\` uniqueness and exposes \`list()\` for discovery tooling.
+
+## Rendering
+
+The design system consumes specs (via adapters you provide) to build runtime tokens. A simple adapter might:
+
+1. Resolve the base theme + applicable overrides.
+2. Merge token maps using \`ThemeTokens\`.
+3. Feed the result into \`mapTokensForPlatform\` in \`@contractspec/lib.design-system\`.
+
+\`\`\`ts
+import { ThemeRegistry } from '@contractspec/lib.contracts-spec/themes';
+import { mapTokensForPlatform } from '@contractspec/lib.design-system';
+
+function resolveTokens(registry: ThemeRegistry, ref: ThemeRef, ctx: { tenant?: string; user?: string }) {
+  const spec = registry.get(ref.name, ref.version);
+  if (!spec) throw new Error('Theme not found');
+
+  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));
+  return mapTokensForPlatform(tokens);
+}
+\`\`\`
+
+## Authoring Guidelines
+
+1. Keep token names aligned with the design-system defaults (\`background\`, \`mutedForeground\`, etc.).
+2. Use \`extends\` to create layered themes (base brand → tenant tweaks → user-level overrides).
+3. Document variants with \`description\` to help designers and automation understand intent.
+4. Prefer scoped overrides (\`tenant:foo\`) instead of duplicating the entire theme per tenant.
+5. When tokens influence multiple components, capture them in \`tokens\` and keep \`components\` for API-level variant wiring.
+
+## CLI (Future Work)
+
+The \`contractspec\` CLI does not yet scaffold theme specs. Planned additions:
+
+- \`contractspec create --type theme\`
+- \`contractspec build <theme.theme.ts>\` → generate design-system adapters
+
+For now, author specs manually and register them alongside contract bundles.
+
+`
+  }
+];
+registerDocBlocks(tech_contracts_themes_DocBlocks);
+export {
+  tech_contracts_themes_DocBlocks
+};

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

@@ -0,0 +1,269 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/contracts/vertical-pocket-family-office.docblock.ts
+var 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
+
+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/examples/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.
+
+
+
+`
+  }
+];
+registerDocBlocks(tech_contracts_vertical_pocket_family_office_DocBlocks);
+export {
+  tech_contracts_vertical_pocket_family_office_DocBlocks
+};