@contractspec/lib.contracts 1.44.0

package/dist/docs/tech/contracts/graphql-typed-outputs.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/graphql-typed-outputs.docblock.d.ts
+declare const tech_contracts_graphql_typed_outputs_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_graphql_typed_outputs_DocBlocks };

package/dist/docs/tech/contracts/graphql-typed-outputs.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/graphql-typed-outputs.docblock.ts
+const tech_contracts_graphql_typed_outputs_DocBlocks = [{
+	id: "docs.tech.contracts.graphql-typed-outputs",
+	title: "GraphQL Typed Outputs for Contracts",
+	summary: "Improved `@contractspec/lib.contracts` to automatically generate proper GraphQL object types from `SchemaModel` outputs instead of defaulting to `JSON` scalar types.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/graphql-typed-outputs",
+	tags: [
+		"tech",
+		"contracts",
+		"graphql-typed-outputs"
+	],
+	body: "# GraphQL Typed Outputs for Contracts\n\n## Overview\n\nImproved `@contractspec/lib.contracts` to automatically generate proper GraphQL object types from `SchemaModel` outputs instead of defaulting to `JSON` scalar types.\n\n## Problem\n\nPreviously, when GraphQL operations were defined using contracts with `SchemaModel` outputs, the GraphQL schema would default to returning `JSON` scalar types. This meant:\n\n- GraphQL clients couldn't query specific fields\n- No type safety for operation outputs\n- Codegen would fail with \"must have a selection of subfields\" errors\n\n## Solution\n\n### 1. Auto-Type Registration in `graphql-pothos.ts`\n\n**File**: `packages/lssm/libs/contracts/src/server/graphql-pothos.ts`\n\n**Changes**:\n\n- Scan all contract specs and collect their `SchemaModel` outputs\n- Automatically register GraphQL object types for each `SchemaModel`\n- Map field types from SchemaModel to proper GraphQL scalar types\n- Update `resolveGraphQLTypeName` to check for `SchemaModel` names before defaulting to `JSON`\n\n**Key Code**:\n\n```typescript\n// Build a map of output types we need to register\nconst outputTypeCache = new Map<string, AnySchemaModel>();\nfor (const spec of reg.listSpecs()) {\n  const out = spec.io.output as AnySchemaModel | ResourceRefDescriptor<boolean>;\n  if (out && 'getZod' in out && typeof out.getZod === 'function') {\n    const model = out as AnySchemaModel;\n    const typeName = model.config?.name ?? 'UnknownOutput';\n    if (!outputTypeCache.has(typeName)) {\n      outputTypeCache.set(typeName, model);\n    }\n  }\n}\n\n// Register all output types as GraphQL object types\nfor (const [typeName, model] of outputTypeCache.entries()) {\n  builder.objectType(typeName, {\n    fields: (t) => {\n      // Map each field from SchemaModel to GraphQL field\n      // ...\n    },\n  });\n}\n```\n\n### 2. Fix Contract Definitions\n\n**File**: `packages/hcircle/libs/contracts-coliving/src/interactions/onboarding/org/contracts.ts`\n\n**Changes**:\n\n- Changed `GetOrgOnboardingDraftSpec` from `defineCommand` to `defineQuery` (read-only operation)\n- Added `defineQuery` import\n\n**Before**:\n\n```typescript\nexport const GetOrgOnboardingDraftSpec = defineCommand({\n  // ...\n});\n```\n\n**After**:\n\n```typescript\nexport const GetOrgOnboardingDraftSpec = defineQuery({\n  // ...\n});\n```\n\n### 3. Update All GraphQL Queries\n\nUpdated all GraphQL operation calls to select proper subfields based on the output type:\n\n#### Output Types and Their Fields\n\n1. **`CreateOrgOutput`**:\n   - `organizationId: ID!`\n   - `orgType: String!`\n\n2. **`CompleteUserOnboardingOutput`**:\n   - `success: Boolean!`\n   - `userId: ID!`\n\n3. **`CompleteOrgOnboardingOutput`**:\n   - `success: Boolean!`\n   - `organizationId: ID!`\n   - `orgType: String!`\n\n4. **`OnboardingDraft`** (from resource_ref):\n   - `id: ID!`\n   - `organizationId: ID!`\n   - `data: JSON!`\n   - `createdAt: DateTime!`\n   - `updatedAt: DateTime!`\n\n5. **`GetOnboardingDraftOutput`**:\n   - `id: ID`\n   - `organizationId: ID`\n   - `data: JSON`\n   - `createdAt: DateTime`\n   - `updatedAt: DateTime`\n\n6. **`DeleteOnboardingDraftOutput`**:\n   - `ok: Boolean!` _(note: not `success`)_\n\n#### Files Updated\n\n1. `/packages/hcircle/apps/mobile-coliving/src/app/onboarding-org-select.tsx`\n2. `/packages/hcircle/apps/mobile-coliving/src/app/onboarding-org.tsx`\n3. `/packages/hcircle/apps/mobile-coliving/src/app/onboarding-user.tsx`\n4. `/packages/hcircle/apps/web-coliving/src/app/onboarding/user/page.tsx`\n5. `/packages/hcircle/apps/web-coliving/src/components/onboarding/OnboardingFlow.tsx`\n6. `/packages/hcircle/apps/web-coliving/src/components/onboarding/OrgSelectionFlow.tsx`\n\n**Example Before**:\n\n```graphql\nmutation CreateOrg($orgType: String!, $name: String!, $slug: String!) {\n  createOrganization(input: { orgType: $orgType, name: $name, slug: $slug })\n}\n```\n\n**Example After**:\n\n```graphql\nmutation CreateOrg($orgType: String!, $name: String!, $slug: String!) {\n  createOrganization(input: { orgType: $orgType, name: $name, slug: $slug }) {\n    organizationId\n    orgType\n  }\n}\n```\n\n## Benefits\n\n1. **Type Safety**: Full type safety for GraphQL operation outputs\n2. **Auto-Generated Types**: No need to manually specify `returns` in contract transport config\n3. **Better DX**: GraphQL clients can now query specific fields and benefit from autocomplete\n4. **Consistency**: All `SchemaModel` outputs are automatically typed in GraphQL\n5. **Backward Compatible**: Operations with explicit `returns` config still work as before\n\n## Testing\n\nAll GraphQL codegen now passes:\n\n```bash\ncd packages/hcircle/libs/gql-client-coliving\nbun graphql-codegen --config codegen.ts  # ✅ Success\n```\n\n## Migration Guide for Other Verticals\n\nTo apply this to other verticals (e.g., Artisanos, Strit):\n\n1. **No code changes needed** - the improved `graphql-pothos.ts` automatically handles all `SchemaModel` outputs\n2. **Update GraphQL queries** - Add field selections to queries that previously returned `JSON`\n3. **Fix query/command mismatches** - Ensure read-only operations use `defineQuery` instead of `defineCommand`\n\n## Future Improvements\n\n1. Add support for nested `SchemaModel` references (currently only supports scalar fields)\n2. Add support for array fields of SchemaModels\n3. Consider auto-generating field selections based on the output type to reduce boilerplate\n\n## Related Documentation\n\n- [Contracts README](../../packages/lssm/libs/contracts/README.md)\n- [Onboarding System](./hcircle/IMPLEMENTATION_COMPLETE.md)\n- [GraphQL Architecture](./graphql/architecture.md)\n"
+}];
+registerDocBlocks(tech_contracts_graphql_typed_outputs_DocBlocks);
+
+//#endregion
+export { tech_contracts_graphql_typed_outputs_DocBlocks };

package/dist/docs/tech/contracts/migrations.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/migrations.docblock.d.ts
+declare const tech_contracts_migrations_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_migrations_DocBlocks };

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

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/migrations.docblock.ts
+const tech_contracts_migrations_DocBlocks = [{
+	id: "docs.tech.contracts.migrations",
+	title: "MigrationSpec Overview",
+	summary: "`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/migrations",
+	tags: [
+		"tech",
+		"contracts",
+		"migrations"
+	],
+	body: "# MigrationSpec Overview\n\n## Purpose\n\n`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.\n\n## Location\n\n- Spec + registry: `packages/libs/contracts/src/migrations.ts`\n- Tests: `packages/.../migrations.test.ts`\n\n## Schema\n\n```ts\nexport interface MigrationSpec {\n  meta: MigrationMeta;   // ownership metadata + { name, version }\n  plan: {\n    up: MigrationStep[];   // required forward plan\n    down?: MigrationStep[];// optional rollback steps\n  };\n  dependencies?: string[]; // optional list of migration keys this depends on\n}\n```\n\n- **MigrationStep**\n  - `kind`: `'schema' | 'data' | 'validation'`\n  - Shared fields: `description?`, `timeoutMs?`, `retries?`, `preChecks?`, `postChecks?`\n  - `schema`: `sql` string executed in transactional context\n  - `data`: arbitrary `script` (e.g., JS/TS snippet, path to file, instructions)\n  - `validation`: `assertion` expression verifying state (e.g., SQL returning boolean)\n- **MigrationCheck** (`preChecks`/`postChecks`)\n  - `description`: human context\n  - `expression`: expression or SQL snippet to evaluate before/after the step\n- **Dependencies**\n  - Array of migration keys (`\"boundedContext.namespace.timestamp_slug\"`) used to ensure the registry executes prerequisites first\n\n## Registry Usage\n\n```ts\nimport { MigrationRegistry } from '@contractspec/lib.contracts/migrations';\nimport { AddUsersMigration } from './migrations/core.db.2025_01_add_users';\n\nconst registry = new MigrationRegistry();\nregistry.register(AddUsersMigration);\n\nconst migration = registry.get('core.db.2025_01_add_users');\nconst all = registry.list(); // sorted by name/version\n```\n\n## Authoring Guidelines\n\n1. Name migrations with timestamped slugs (`domain.db.YYYY_MM_description`) for clarity.\n2. Capture ownership metadata (`owners`, `tags`, `stability`) so tooling can route approvals.\n3. Prefer small, reversible steps. Use `plan.down` when safe; otherwise document fallback.\n4. Use `preChecks`/`postChecks` for critical invariants (row counts, schema existence).\n5. Specify dependencies explicitly to avoid parallel execution hazards.\n6. For large data scripts, use `script` as a pointer (URL, file path) rather than embedding code directly.\n\n## Tooling Roadmap\n\nUpcoming CLI support (Phase 4 plan):\n\n- `contractspec create --type migration` (scaffolds spec skeleton)\n- `contractspec build <migration>` (generate executor harness)\n- `contractspec migrate create/up/down/status` orchestration commands\n\nThe current implementation focuses on the spec/registry foundation so downstream tooling can be layered iteratively.\n\n"
+}];
+registerDocBlocks(tech_contracts_migrations_DocBlocks);
+
+//#endregion
+export { tech_contracts_migrations_DocBlocks };

package/dist/docs/tech/contracts/openapi-export.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/openapi-export.docblock.d.ts
+declare const tech_contracts_openapi_export_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_openapi_export_DocBlocks };

package/dist/docs/tech/contracts/openapi-export.docblock.js

@@ -0,0 +1,58 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/openapi-export.docblock.ts
+const tech_contracts_openapi_export_DocBlocks = [{
+	id: "docs.tech.contracts.openapi-export",
+	title: "OpenAPI export (OpenAPI 3.1) from OperationSpecRegistry",
+	summary: "Generate a deterministic OpenAPI document from a OperationSpecRegistry using jsonSchemaForSpec + REST transport metadata.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/openapi-export",
+	tags: [
+		"contracts",
+		"openapi",
+		"rest"
+	],
+	body: `## OpenAPI export (OpenAPI 3.1) from OperationSpecRegistry
+
+### Purpose
+
+ContractSpec specs can be exported into an **OpenAPI 3.1** document for tooling (SDK generation, docs, gateways).
+
+The export is **spec-first**:
+
+- Uses \`jsonSchemaForSpec(spec)\` for input/output JSON Schema (from SchemaModel → zod → JSON Schema)
+- Uses \`spec.transport.rest.method/path\` when present
+- Falls back to deterministic defaults:
+  - Method: \`POST\` for commands, \`GET\` for queries
+  - Path: \`defaultRestPath(name, version)\` → \`/<dot/name>/v<version>\`
+
+### Library API
+
+- Function: \`openApiForRegistry(registry, options?)\`
+- Location: \`@contractspec/lib.contracts/openapi\`
+
+### CLI
+
+Export OpenAPI from a registry module:
+
+\`\`\`bash
+contractspec openapi --registry ./src/registry.ts --out ./openapi.json
+\`\`\`
+
+The registry module must export one of:
+
+- \`registry: OperationSpecRegistry\`
+- \`default(): OperationSpecRegistry | Promise<OperationSpecRegistry>\`
+- \`createRegistry(): OperationSpecRegistry | Promise<OperationSpecRegistry>\`
+
+### Notes / limitations (current)
+
+- Responses are generated as a basic \`200\` response (plus schemas when available).
+- Query (GET) inputs are currently represented as a JSON request body when an input schema exists.
+- Errors are not yet expanded into OpenAPI responses; that will be added when we standardize error envelopes.`
+}];
+registerDocBlocks(tech_contracts_openapi_export_DocBlocks);
+
+//#endregion
+export { tech_contracts_openapi_export_DocBlocks };

package/dist/docs/tech/contracts/openapi-import.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/openapi-import.docblock.d.ts
+declare const tech_contracts_openapi_import_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_openapi_import_DocBlocks };

package/dist/docs/tech/contracts/openapi-import.docblock.js

@@ -0,0 +1,65 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/openapi-import.docblock.ts
+const tech_contracts_openapi_import_DocBlocks = [{
+	id: "docs.tech.contracts.openapi-import",
+	title: "OpenAPI Import (OpenAPI 3.1) to ContractSpec",
+	summary: "Import OpenAPI specifications into ContractSpec models, or generate pure Zod/JSON-Schema/GraphQL representations.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/openapi-import",
+	tags: [
+		"contracts",
+		"openapi",
+		"import",
+		"codegen"
+	],
+	body: `## OpenAPI Import (OpenAPI 3.1)
+
+### Purpose
+
+Import external API definitions into your codebase. Supports both one-time scaffolding and multi-format generation for integration.
+
+### Modes
+
+#### 1. ContractSpec Scaffolding (Default)
+
+Generates standard \`defineSchemaModel\` definitions for full ContractSpec integration.
+
+\`\`\`bash
+contractspec openapi import --file api.json --output ./src/contracts
+\`\`\`
+
+#### 2. Multi-Format Generation
+
+Generate schemas in specific formats for direct use in other parts of your stack (adapters, UI, etc.).
+
+- **Zod**: Pure Zod schemas (\`z.object(...)\`).
+- **GraphQL**: GraphQL SDL type definitions.
+- **JSON Schema**: Standard JSON Schema objects.
+
+\`\`\`bash
+# Generate Zod schemas suitable for runtime validation
+contractspec openapi import --file api.json --output ./src/zod --schema-format zod
+\`\`\`
+
+### Library API
+
+- Function: \`importFromOpenApi(doc, options)\`
+- Location: \`@contractspec/lib.contracts-transformers/openapi\`
+- Options:
+  - \`schemaFormat\`: 'contractspec' | 'zod' | 'json-schema' | 'graphql'
+  - \`prefix\`: Prefix for model names
+  - \`tags\`: Filter by OpenAPI tags
+
+### CLI
+
+\`\`\`bash
+contractspec openapi import --file <path-or-url> --output <dir> [--schema-format <format>]
+\`\`\`
+`
+}];
+registerDocBlocks(tech_contracts_openapi_import_DocBlocks);
+
+//#endregion
+export { tech_contracts_openapi_import_DocBlocks };

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

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/ops-to-presentation-linking.docblock.d.ts
+declare const tech_contracts_ops_to_presentation_linking_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_ops_to_presentation_linking_DocBlocks };

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

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#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 (OperationSpec) are linked to Presentations (PresentationSpec) 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 (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.\n\n- Location: `@contractspec/lib.contracts/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\n- Validation: `installFeature()` validates that linked ops exist in `OperationSpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\n\nExample:\n\n```ts\nimport type { OperationSpecRegistry } from '@contractspec/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@contractspec/lib.contracts';\n\nexport function buildFeaturesWithOps(ops: OperationSpecRegistry) {\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);
+
+//#endregion
+export { tech_contracts_ops_to_presentation_linking_DocBlocks };

package/dist/docs/tech/contracts/overlays.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/overlays.docblock.d.ts
+declare const tech_contracts_overlays_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_overlays_DocBlocks };

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

@@ -0,0 +1,21 @@
+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 `@contractspec/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 `@contractspec/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 '@contractspec/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.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/tests.docblock.d.ts
+declare const tech_contracts_tests_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_tests_DocBlocks };

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

@@ -0,0 +1,21 @@
+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 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';\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 `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);
+
+//#endregion
+export { tech_contracts_tests_DocBlocks };

package/dist/docs/tech/contracts/themes.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/themes.docblock.d.ts
+declare const tech_contracts_themes_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_themes_DocBlocks };

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

@@ -0,0 +1,21 @@
+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 `@contractspec/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 `@contractspec/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 '@contractspec/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 `@contractspec/lib.design-system`.\n\n```ts\nimport { ThemeRegistry } from '@contractspec/lib.contracts/themes';\nimport { mapTokensForPlatform } from '@contractspec/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.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/vertical-pocket-family-office.docblock.d.ts
+declare const tech_contracts_vertical_pocket_family_office_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_vertical_pocket_family_office_DocBlocks };

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

@@ -0,0 +1,21 @@
+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 };

package/dist/docs/tech/lifecycle-stage-system.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/lifecycle-stage-system.docblock.d.ts
+declare const tech_lifecycle_stage_system_DocBlocks: DocBlock[];
+//#endregion
+export { tech_lifecycle_stage_system_DocBlocks };

package/dist/docs/tech/lifecycle-stage-system.docblock.js

@@ -0,0 +1,17 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/lifecycle-stage-system.docblock.ts
+const tech_lifecycle_stage_system_DocBlocks = [{
+	id: "docs.tech.lifecycle-stage-system",
+	title: "ContractSpec Lifecycle Stage System – Technical Design",
+	summary: "This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/lifecycle-stage-system",
+	tags: ["tech", "lifecycle-stage-system"],
+	body: "## ContractSpec Lifecycle Stage System – Technical Design\n\nThis document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.\n\n---\n\n### 1. Architecture Overview\n\n```\n┌──────────────────────┐\n│ @contractspec/lib.lifecycle  │  Types, enums, helpers (pure data)\n└───────────┬──────────┘\n            │\n┌───────────▼──────────┐    ┌───────────────────────────┐\n│ modules/lifecycle-   │    │ modules/lifecycle-advisor  │\n│ core (detection)     │    │ (guidance & ceremonies)    │\n└───────────┬──────────┘    └───────────┬───────────────┘\n            │                           │\n            ├────────────┬──────────────┤\n            ▼            ▼              ▼\n  Adapters: analytics, intent, questionnaires\n            │\n┌───────────▼──────────┐\n│ bundles/lifecycle-   │  Managed service for Studio\n│ managed              │  (REST handlers, AI agent)     │\n└───────────┬──────────┘\n            │\n  ContractSpec Studio surfaces\n  (web/mobile APIs, CLI, docs)\n```\n\n- **Libraries** provide shared vocabulary.\n- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.\n- **Bundles** compose modules, register agents/events, and expose APIs for Studio.\n- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve `@contractspec/bundle.studio` and `@contractspec/lib.database-contractspec-studio` directly from their `packages/.../src` folders via `tsconfig` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled `dist` artifacts into client chunks.\n\n---\n\n### 2. Core Library (`@contractspec/lib.lifecycle`)\n\n- Stage enum (0–6) with metadata (`question`, `signals`, `traps`).\n- Axes types (`ProductPhase`, `CompanyPhase`, `CapitalPhase`).\n- `LifecycleSignal` (source, metric, value, timestamp).\n- `LifecycleMetricSnapshot` (aggregated numbers).\n- `LifecycleMilestone`, `LifecycleAction`, `LifecycleAssessment` interfaces.\n- Utility helpers:\n  - `formatStageSummary(stage, assessment)`\n  - `rankStageCandidates(scores)`\n\nThe library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.\n\n---\n\n### 3. Lifecycle Core Module\n\n**Location:** `packages/modules/lifecycle-core/`\n\n#### Components\n1. **StageSignalCollector**\n   - Accepts adapter interfaces:\n     - `AnalyticsAdapter` (pulls metrics from `@contractspec/lib.analytics` or fixture streams).\n     - `IntentAdapter` (hooks into `@contractspec/lib.observability` intent detectors or logs).\n     - `QuestionnaireAdapter` (loads JSON questionnaires and responses).\n   - Produces normalized `LifecycleSignal[]`.\n\n2. **StageScorer**\n   - Weighted scoring model:\n     - Base weight per stage (reflecting expected maturity).\n     - Feature weights (retention, revenue, team size, qualitative feedback).\n     - Confidence computed via variance of contributing signals.\n   - Supports pluggable scoring matrices via JSON config.\n   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.\n\n3. **LifecycleOrchestrator**\n   - Coordinates collectors + scorer.\n   - Returns `LifecycleAssessment` with:\n     - `stage`, `confidence`, `axisSnapshot`, `signalsUsed`.\n     - Recommended focus areas (high-level categories only).\n   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).\n\n4. **LifecycleMilestonePlanner**\n   - Loads `milestones-catalog.json` (no DB).\n   - Filters upcoming milestones per stage + axis.\n   - Tracks completion using provided IDs (caller persists).\n\n#### Data Files\n- `configs/stage-weights.json`\n- `configs/milestones-catalog.json`\n- `questionnaires/stage-readiness.json`\n\n#### Extension Hooks\n- All adapters exported as TypeScript interfaces.\n- Implementations for analytics/intent can live in bundles or apps without modifying module code.\n\n---\n\n### 4. Lifecycle Advisor Module\n\n**Location:** `packages/modules/lifecycle-advisor/`\n\n#### Components\n1. **LifecycleRecommendationEngine**\n   - Consumes `LifecycleAssessment`.\n   - Maps gaps to `LifecycleAction[]` using rule tables (`stage-playbooks.ts`).\n   - Supports override hooks for customer-specific rules.\n\n2. **ContractSpecLibraryRecommender**\n   - Maintains mapping from stage → recommended libraries/modules/bundles.\n   - Returns prioritized list with rationale and adoption prerequisites.\n\n3. **LifecycleCeremonyDesigner**\n   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).\n   - Ensures low-tech friendly instructions (clear copy, undo guidance).\n\n4. **AI Hooks**\n   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).\n   - Keeps actual LLM integration outside module.\n\n---\n\n### 5. Managed Bundle (`lifecycle-managed`)\n\n**Responsibilities**\n- Wire modules together.\n- Provide HTTP/GraphQL handlers (exact transport optional).\n- Register LifecycleAdvisorAgent via `@contractspec/lib.ai-agent`.\n- LifecycleAdvisorAgent meta: domain `operations`, owners `team-lifecycle`, stability `experimental`, tags `guide/lifecycle/ops` so ops tooling can route incidents quickly.\n- Emit lifecycle events through `@contractspec/lib.bus` + `@contractspec/lib.analytics`.\n- Integrate with `contractspec-studio` packages:\n  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).\n  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).\n\n**APIs**\n- `POST /lifecycle/assessments`: Accepts metrics + optional questionnaire answers. Returns `LifecycleAssessment`.\n- `GET /lifecycle/playbooks/:stage`: Returns stage playbook + ceremonies.\n- `POST /lifecycle/advise`: Invokes LifecycleAdvisorAgent with context.\n\n**Events**\n- `LifecycleAssessmentCreated`\n- `LifecycleStageChanged`\n- `LifecycleGuidanceConsumed`\n\n---\n\n### 6. Library Enhancements\n\n| Library | Enhancement |\n| --- | --- |\n| `@contractspec/lib.analytics` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by `StageSignalCollector`. |\n| `@contractspec/lib.evolution` | Accepts `LifecycleContext` when ranking spec anomalies/suggestions. |\n| `@contractspec/lib.growth` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |\n| `@contractspec/lib.observability` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |\n\nEach enhancement must import stage types from `@contractspec/lib.lifecycle`.\n\n---\n\n### 7. Feature Flags & Progressive Delivery\n\n- Add new flags in progressive-delivery library:\n  - `LIFECYCLE_DETECTION_ALPHA`\n  - `LIFECYCLE_ADVISOR_ALPHA`\n  - `LIFECYCLE_MANAGED_SERVICE`\n- Bundles/modules should check flags before enabling workflows.\n- Flags referenced in docs + Studio UI to avoid accidental exposure.\n\n---\n\n### 8. Analytics & Telemetry\n\n- Events defined in analytics library; consumed by bundle/app:\n  - `lifecycle_assessment_run`\n  - `lifecycle_stage_changed`\n  - `lifecycle_guidance_consumed`\n- Observability pipeline includes:\n  - Composite lifecycle health metric (weighted sum of KPIs).\n  - Drift detection comparing stage predictions over time.\n  - Alert manager recipes for regression (e.g., PMF drop).\n\n---\n\n### 9. Testing Strategy\n\n1. **Unit**\n   - StageScorer weight matrix.\n   - RecommendationEngine mapping.\n   - Library recommender stage coverage.\n\n2. **Contract**\n   - Adapters: ensure mock adapters satisfy interfaces.\n   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.\n\n3. **Integration**\n   - CLI example runs detection + guidance end-to-end on fixture data.\n   - Dashboard example renders assessments, verifying JSON structures remain stable.\n\n---\n\n### 10. Implementation Checklist\n\n- [ ] Documentation (product, tech, ops, user).\n- [ ] Library creation (`@contractspec/lib.lifecycle`).\n- [ ] Modules (`lifecycle-core`, `lifecycle-advisor`).\n- [ ] Bundle (`lifecycle-managed`) + Studio wiring.\n- [ ] Library enhancements (analytics/evolution/growth/observability).\n- [ ] Examples (CLI + dashboard).\n- [ ] Feature flags + telemetry.\n- [ ] Automated tests + fixtures.\n\nKeep this document in sync as modules evolve. When adding new stages or axes, update `@contractspec/lib.lifecycle` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch\n\n\n"
+}];
+registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
+
+//#endregion
+export { tech_lifecycle_stage_system_DocBlocks };

package/dist/docs/tech/llm/llm-integration.docblock.d.ts

@@ -0,0 +1,7 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/llm/llm-integration.docblock.d.ts
+
+declare const tech_llm_integration_DocBlocks: DocBlock[];
+//#endregion
+export { tech_llm_integration_DocBlocks };