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

package/dist/docs/tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.js

@@ -1,86 +1,17 @@
-import{registerDocBlocks as e}from"../registry.js";const t=[{id:`docs.tech.PHASE_4_PERSONALIZATION_ENGINE`,title:`Phase 4: Personalization Engine`,summary:`**Status**: Complete`,kind:`reference`,visibility:`public`,route:`/docs/tech/PHASE_4_PERSONALIZATION_ENGINE`,tags:[`tech`,`PHASE_4_PERSONALIZATION_ENGINE`],body:`# Phase 4: Personalization Engine
-
-**Status**: Complete  
-**Last updated**: 2025-11-21
-
-Phase 4 unlocks tenant-scoped personalization with zero bespoke code. We shipped three new libraries, a signing-aware Overlay editor, and the persistence layer required to observe usage and apply overlays safely.
-
----
-
-## 1. Libraries
-
-### @lssm/lib.overlay-engine
-
-- OverlaySpec types + validator mirror the public spec.
-- Cryptographic signer (\`ed25519\`, \`rsa-pss-sha256\`) with canonical JSON serialization.
-- Registry that merges tenant/role/user/device overlays with predictable specificity.
-- React hooks (\`useOverlay\`, \`useOverlayFields\`) for client-side rendering.
-- Runtime engine audits every applied overlay for traceability.
-
-### @lssm/lib.personalization
-
-- Behavior tracker buffers field/feature/workflow events and exports OTel metrics.
-- Analyzer summarizes field usage and workflow drop-offs into actionable insights.
-- Adapter translates insights into overlay suggestions or workflow tweaks.
-- In-memory store implementation + interface for plugging Prisma/ClickHouse later.
-
-### @lssm/lib.workflow-composer
-
-- \`WorkflowComposer\` merges base workflows with tenant/role/device extensions.
-- Step injection utilities keep transitions intact and validate anchor steps.
-- Template helpers for common tenant review/approval, plus merge helpers for multi-scope extensions.
-
----
-
-## 2. Overlay Editor App
-
-Path: \`packages/apps/overlay-editor\`
-
-- Next.js App Router UI for toggling field visibility, renaming labels, and reordering lists.
-- Live JSON preview powered by \`defineOverlay\`.
-- Server action that signs overlays via PEM private keys (Ed25519 by default) using the overlay engine signer.
-
----
-
-## 3. Persistence
-
-Added Prisma models (see \`packages/libs/database/prisma/schema.prisma\`):
-
-- \`UserBehaviorEvent\` – field/feature/workflow telemetry.
-- \`OverlaySigningKey\` – tenant managed signing keys with revocation timestamps.
-- \`Overlay\` – stored overlays (tenant/user/role/device scope) plus signature metadata.
-
----
-
-## 4. Integration Steps
-
-1. Track usage inside apps via \`createBehaviorTracker\`.
-2. Periodically run \`BehaviorAnalyzer.analyze\` to generate insights.
-3. Convert insights into OverlaySpecs or Workflow extensions.
-4. Register tenant overlays in \`OverlayRegistry\` and serve via presentation runtimes.
-5. Compose workflows per tenant using \`WorkflowComposer\`.
-
-See the \`docs/tech/personalization/*\` guides for concrete examples.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`}];e(t);export{t as tech_PHASE_4_PERSONALIZATION_ENGINE_DocBlocks};
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.ts
+const tech_PHASE_4_PERSONALIZATION_ENGINE_DocBlocks = [{
+	id: "docs.tech.PHASE_4_PERSONALIZATION_ENGINE",
+	title: "Phase 4: Personalization Engine",
+	summary: "**Status**: Complete",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/PHASE_4_PERSONALIZATION_ENGINE",
+	tags: ["tech", "PHASE_4_PERSONALIZATION_ENGINE"],
+	body: "# Phase 4: Personalization Engine\n\n**Status**: Complete  \n**Last updated**: 2025-11-21\n\nPhase 4 unlocks tenant-scoped personalization with zero bespoke code. We shipped three new libraries, a signing-aware Overlay editor, and the persistence layer required to observe usage and apply overlays safely.\n\n---\n\n## 1. Libraries\n\n### @lssm/lib.overlay-engine\n\n- OverlaySpec types + validator mirror the public spec.\n- Cryptographic signer (`ed25519`, `rsa-pss-sha256`) with canonical JSON serialization.\n- Registry that merges tenant/role/user/device overlays with predictable specificity.\n- React hooks (`useOverlay`, `useOverlayFields`) for client-side rendering.\n- Runtime engine audits every applied overlay for traceability.\n\n### @lssm/lib.personalization\n\n- Behavior tracker buffers field/feature/workflow events and exports OTel metrics.\n- Analyzer summarizes field usage and workflow drop-offs into actionable insights.\n- Adapter translates insights into overlay suggestions or workflow tweaks.\n- In-memory store implementation + interface for plugging Prisma/ClickHouse later.\n\n### @lssm/lib.workflow-composer\n\n- `WorkflowComposer` merges base workflows with tenant/role/device extensions.\n- Step injection utilities keep transitions intact and validate anchor steps.\n- Template helpers for common tenant review/approval, plus merge helpers for multi-scope extensions.\n\n---\n\n## 2. Overlay Editor App\n\nPath: `packages/apps/overlay-editor`\n\n- Next.js App Router UI for toggling field visibility, renaming labels, and reordering lists.\n- Live JSON preview powered by `defineOverlay`.\n- Server action that signs overlays via PEM private keys (Ed25519 by default) using the overlay engine signer.\n\n---\n\n## 3. Persistence\n\nAdded Prisma models (see `packages/libs/database/prisma/schema.prisma`):\n\n- `UserBehaviorEvent` – field/feature/workflow telemetry.\n- `OverlaySigningKey` – tenant managed signing keys with revocation timestamps.\n- `Overlay` – stored overlays (tenant/user/role/device scope) plus signature metadata.\n\n---\n\n## 4. Integration Steps\n\n1. Track usage inside apps via `createBehaviorTracker`.\n2. Periodically run `BehaviorAnalyzer.analyze` to generate insights.\n3. Convert insights into OverlaySpecs or Workflow extensions.\n4. Register tenant overlays in `OverlayRegistry` and serve via presentation runtimes.\n5. Compose workflows per tenant using `WorkflowComposer`.\n\nSee the `docs/tech/personalization/*` guides for concrete examples.\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_PHASE_4_PERSONALIZATION_ENGINE_DocBlocks);
+
+//#endregion
+export { tech_PHASE_4_PERSONALIZATION_ENGINE_DocBlocks };

package/dist/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.js

@@ -1 +1,17 @@
-import{registerDocBlocks as e}from"../registry.js";const t=[{id:`docs.tech.PHASE_5_ZERO_TOUCH_OPERATIONS`,title:`Phase 5: Zero-Touch Operations`,summary:`**Status**: In progress`,kind:`reference`,visibility:`public`,route:`/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS`,tags:[`tech`,`PHASE_5_ZERO_TOUCH_OPERATIONS`],body:"# Phase 5: Zero-Touch Operations\n\n**Status**: In progress  \n**Last updated**: 2025-11-21\n\nPhase 5 delivers progressive delivery, SLO intelligence, cost attribution, and anomaly-driven remediation so the platform can deploy continuously without pager rotations.\n\n---\n\n## 1. New Libraries\n\n### @lssm/lib.progressive-delivery\n- `DeploymentStrategy` types capture canary vs blue-green rollouts.\n- `CanaryController` + `CanaryAnalyzer` orchestrate stage evaluation against telemetry thresholds.\n- `TrafficShifter` keeps stable/candidate splits in sync with feature-flag or router state.\n- `DeploymentCoordinator` drives stage progression, emits events, and triggers rollbacks.\n- `RollbackManager` encapsulates safe revert hooks (spec version revert, traffic shift, etc.).\n\n### @lssm/lib.slo\n- Declarative `SLODefinition` with latency + availability targets per capability/spec.\n- `SLOTracker` stores rolling snapshots + error budget positions.\n- `BurnRateCalculator` implements multi-window burn computations (fast vs slow burn).\n- `SLOMonitor` pushes incidents to Ops tooling automatically when burn exceeds thresholds.\n\n### @lssm/lib.cost-tracking\n- `CostTracker` normalizes DB/API/compute metrics into per-operation cost totals.\n- `BudgetAlertManager` raises tenant budget warnings (80% default) with contextual payloads.\n- `OptimizationRecommender` suggests batching, caching, or contract tweaks to cut spend.\n\n### Observability Anomaly Toolkit\n- `BaselineCalculator` establishes rolling intent metrics (latency, error rate, throughput).\n- `AnomalyDetector` flags spikes/drops via relative deltas after 10+ samples.\n- `RootCauseAnalyzer` correlates anomalies with recent deployments.\n- `AlertManager` deduplicates notifications and feeds MCP/SRE transports.\n\n---\n\n## 2. Data Model Additions\n\nFile: `packages/libs/database/prisma/schema.prisma`\n\n| Model | Purpose |\n| --- | --- |\n| `SLODefinition`, `SLOSnapshot`, `ErrorBudget`, `SLOIncident` | Persist definitions, rolling windows, and incidents. |\n| `OperationCost`, `TenantBudget`, `CostAlert`, `OptimizationSuggestion` | Track per-operation costs, budgets, and generated recommendations. |\n| `Deployment`, `DeploymentStage`, `RollbackEvent` | Audit progressive delivery runs and automated rollbacks. |\n| `MetricBaseline`, `AnomalyEvent` | Store computed baselines and anomaly evidence for training/analytics. |\n\nRun `bun database generate` after pulling to refresh the Prisma client.\n\n---\n\n## 3. Operational Flow\n\n1. **Deploy**: Define a `DeploymentStrategy` and feed telemetry via `@lssm/lib.observability`. Canary stages run automatically.\n2. **Protect**: `CanaryAnalyzer` evaluates error rate + latency thresholds. Failures trigger `RollbackManager`.\n3. **Observe**: `SLOMonitor` consumes snapshots and opens incidents when burn rate exceeds thresholds.\n4. **Optimize**: `CostTracker` aggregates spend per tenant + capability, while `OptimizationRecommender` surfaces fixes.\n5. **Detect**: Anomaly signals route to `RootCauseAnalyzer`, which links them to specific deployments for auto-rollback.\n\n---\n\n## 4. Integration Checklist\n\n1. Instrument adapters with `createTracingMiddleware({ onSample })` to feed metric points into `AnomalyDetector`.\n2. Register SLOs per critical operation (`billing.charge`, `knowledge.search`) and wire monitors to Ops notifications.\n3. Attach `CostTracker.recordSample` to workflow runners (DB instrumentation + external call wrappers).\n4. Store deployment metadata using the new Prisma models for auditing + UI surfacing.\n5. Update `@lssm/app.ops-console` (next iteration) to list deployments, SLO status, costs, and anomalies in one timeline.\n\n---\n\n## 5. Next Steps\n\n- Wire `DeploymentCoordinator` into the Contracts CLI so `contractspec deploy` can run staged rollouts.\n- Add UI for SLO dashboards (burn rate sparkline + incident feed).\n- Ship budget suggestions into Growth Agent for automated cost optimizations.\n- Connect `AnomalyEvent` stream to MCP agents for root-cause playbooks.\n"}];e(t);export{t as tech_PHASE_5_ZERO_TOUCH_OPERATIONS_DocBlocks};
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.ts
+const tech_PHASE_5_ZERO_TOUCH_OPERATIONS_DocBlocks = [{
+	id: "docs.tech.PHASE_5_ZERO_TOUCH_OPERATIONS",
+	title: "Phase 5: Zero-Touch Operations",
+	summary: "**Status**: In progress",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS",
+	tags: ["tech", "PHASE_5_ZERO_TOUCH_OPERATIONS"],
+	body: "# Phase 5: Zero-Touch Operations\n\n**Status**: In progress  \n**Last updated**: 2025-11-21\n\nPhase 5 delivers progressive delivery, SLO intelligence, cost attribution, and anomaly-driven remediation so the platform can deploy continuously without pager rotations.\n\n---\n\n## 1. New Libraries\n\n### @lssm/lib.progressive-delivery\n- `DeploymentStrategy` types capture canary vs blue-green rollouts.\n- `CanaryController` + `CanaryAnalyzer` orchestrate stage evaluation against telemetry thresholds.\n- `TrafficShifter` keeps stable/candidate splits in sync with feature-flag or router state.\n- `DeploymentCoordinator` drives stage progression, emits events, and triggers rollbacks.\n- `RollbackManager` encapsulates safe revert hooks (spec version revert, traffic shift, etc.).\n\n### @lssm/lib.slo\n- Declarative `SLODefinition` with latency + availability targets per capability/spec.\n- `SLOTracker` stores rolling snapshots + error budget positions.\n- `BurnRateCalculator` implements multi-window burn computations (fast vs slow burn).\n- `SLOMonitor` pushes incidents to Ops tooling automatically when burn exceeds thresholds.\n\n### @lssm/lib.cost-tracking\n- `CostTracker` normalizes DB/API/compute metrics into per-operation cost totals.\n- `BudgetAlertManager` raises tenant budget warnings (80% default) with contextual payloads.\n- `OptimizationRecommender` suggests batching, caching, or contract tweaks to cut spend.\n\n### Observability Anomaly Toolkit\n- `BaselineCalculator` establishes rolling intent metrics (latency, error rate, throughput).\n- `AnomalyDetector` flags spikes/drops via relative deltas after 10+ samples.\n- `RootCauseAnalyzer` correlates anomalies with recent deployments.\n- `AlertManager` deduplicates notifications and feeds MCP/SRE transports.\n\n---\n\n## 2. Data Model Additions\n\nFile: `packages/libs/database/prisma/schema.prisma`\n\n| Model | Purpose |\n| --- | --- |\n| `SLODefinition`, `SLOSnapshot`, `ErrorBudget`, `SLOIncident` | Persist definitions, rolling windows, and incidents. |\n| `OperationCost`, `TenantBudget`, `CostAlert`, `OptimizationSuggestion` | Track per-operation costs, budgets, and generated recommendations. |\n| `Deployment`, `DeploymentStage`, `RollbackEvent` | Audit progressive delivery runs and automated rollbacks. |\n| `MetricBaseline`, `AnomalyEvent` | Store computed baselines and anomaly evidence for training/analytics. |\n\nRun `bun database generate` after pulling to refresh the Prisma client.\n\n---\n\n## 3. Operational Flow\n\n1. **Deploy**: Define a `DeploymentStrategy` and feed telemetry via `@lssm/lib.observability`. Canary stages run automatically.\n2. **Protect**: `CanaryAnalyzer` evaluates error rate + latency thresholds. Failures trigger `RollbackManager`.\n3. **Observe**: `SLOMonitor` consumes snapshots and opens incidents when burn rate exceeds thresholds.\n4. **Optimize**: `CostTracker` aggregates spend per tenant + capability, while `OptimizationRecommender` surfaces fixes.\n5. **Detect**: Anomaly signals route to `RootCauseAnalyzer`, which links them to specific deployments for auto-rollback.\n\n---\n\n## 4. Integration Checklist\n\n1. Instrument adapters with `createTracingMiddleware({ onSample })` to feed metric points into `AnomalyDetector`.\n2. Register SLOs per critical operation (`billing.charge`, `knowledge.search`) and wire monitors to Ops notifications.\n3. Attach `CostTracker.recordSample` to workflow runners (DB instrumentation + external call wrappers).\n4. Store deployment metadata using the new Prisma models for auditing + UI surfacing.\n5. Update `@lssm/app.ops-console` (next iteration) to list deployments, SLO status, costs, and anomalies in one timeline.\n\n---\n\n## 5. Next Steps\n\n- Wire `DeploymentCoordinator` into the Contracts CLI so `contractspec deploy` can run staged rollouts.\n- Add UI for SLO dashboards (burn rate sparkline + incident feed).\n- Ship budget suggestions into Growth Agent for automated cost optimizations.\n- Connect `AnomalyEvent` stream to MCP agents for root-cause playbooks.\n"
+}];
+registerDocBlocks(tech_PHASE_5_ZERO_TOUCH_OPERATIONS_DocBlocks);
+
+//#endregion
+export { tech_PHASE_5_ZERO_TOUCH_OPERATIONS_DocBlocks };

package/dist/docs/tech/auth/better-auth-nextjs.docblock.js

@@ -1,4 +1,22 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.auth.better-auth-nextjs`,title:`Better Auth + Next.js integration (ContractSpec)`,summary:`How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).`,kind:`reference`,visibility:`public`,route:`/docs/tech/auth/better-auth-nextjs`,tags:[`auth`,`better-auth`,`nextjs`,`cookies`,`proxy`,`hmr`],body:`# Better Auth + Next.js integration (ContractSpec)
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/auth/better-auth-nextjs.docblock.ts
+const tech_auth_better_auth_nextjs_DocBlocks = [{
+	id: "docs.tech.auth.better-auth-nextjs",
+	title: "Better Auth + Next.js integration (ContractSpec)",
+	summary: "How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/auth/better-auth-nextjs",
+	tags: [
+		"auth",
+		"better-auth",
+		"nextjs",
+		"cookies",
+		"proxy",
+		"hmr"
+	],
+	body: `# Better Auth + Next.js integration (ContractSpec)
 
 This repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).
 
@@ -55,4 +73,9 @@ The Next.js proxy/middleware is used for **redirect decisions only**. It must no
   - \`getCookieCache(request)\`
 
 These checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.
-`}];e(t);export{t as tech_auth_better_auth_nextjs_DocBlocks};
+`
+}];
+registerDocBlocks(tech_auth_better_auth_nextjs_DocBlocks);
+
+//#endregion
+export { tech_auth_better_auth_nextjs_DocBlocks };

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

@@ -1 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.README`,title:`Contracts: Specs, Registry, Handlers, Adapters`,summary:"- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, install helpers, REST/MCP adapters).",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/README`,tags:[`tech`,`contracts`,`README`],body:"## Contracts: Specs, Registry, Handlers, Adapters\n\n### What lives where\n\n- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, install helpers, REST/MCP adapters).\n- `packages/lssm/libs/schema` defines the schema dictionary (`SchemaModel`, `FieldType`) used to describe I/O once and map to multiple targets (zod, GraphQL, JSON Schema).\n- App adapters (e.g. GraphQL) live close to the app. Example: `packages/hcircle/apps/api-coliving/src/graphql/contracts-adapter.ts`.\n\n### npm distribution\n\n- `@lssm/lib.contracts` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@lssm/lib.contracts/client` exposes only browser-safe helpers (React renderers, client SDK, drivers). Import from this entry when bundling for the web or React Native to avoid dragging server adapters.\n- `@lssm/lib.contracts/server` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@lssm/lib.contracts/types` exports the runtime handler context utilities, while `@lssm/lib.contracts/types/all` re-exports every type alias/interface across the package via `export type` so consumers can import a single module for typings without shipping runtime code.\n- `@lssm/lib.schema`, `@lssm/lib.design-system`, `@lssm/lib.ui-kit`, `@lssm/lib.ui-kit-web`, `@lssm/lib.accessibility`, and the presentation runtime packages are published to npm alongside contracts; prefer the scoped packages to keep tree-shaking intact.\n- Bundlers with conditional exports should resolve subpaths first; keep root imports for server-only code paths.\n\n### Core concepts\n\n- **ContractSpec**: immutable description of an operation.\n  - `meta`: `{ name, version, kind: 'query' | 'command' }`\n  - `io`: `{ input: SchemaModel | zod schema, output: SchemaModel | zod schema }`\n  - `policy`: `{ auth?: {...}, rateLimit?: {...}, flags?: string[] }`\n  - `transport.gql.field?`: explicit GraphQL field name (otherwise derived via `defaultGqlField`).\n- **SpecRegistry**: registry of specs + handlers. Use `installOp(reg, spec, handler)` to attach a handler.\n- **Handler**: `(ctx, input) => Promise<output>` implementing the operation.\n- **CapabilitySpec**: canonical capability declaration stored in `src/capabilities.ts`. Tracks `meta` (`{ key, version, kind, title, description, domain, owners, tags, stability }`), `provides` surfaces (`operation`, `event`, `workflow`, `presentation`, `resource`), and `requires` which other capabilities must be present. Enforced during `installFeature`.\n- **PolicySpec**: declarative policy rules (`src/policy/spec.ts`) covering ABAC/ReBAC, consent + rate limit requirements, field-level controls, and PII guidance. `PolicyEngine` evaluates refs, while `OPAPolicyAdapter` lets OPA override/augment runtime decisions.\n- **TelemetrySpec**: analytics definitions (`src/telemetry/spec.ts`) describing event semantics, privacy level, retention, sampling, and anomaly detection. `TelemetryTracker` handles redaction/sampling, `TelemetryAnomalyMonitor` raises alerts, and specs integrate with contracts/workflows via `ctx.telemetry`.\n- **TestSpec**: declarative scenario definitions in `src/tests/spec.ts`. `TestRunner` executes fixtures/actions/assertions against a `SpecRegistry`, and the CLI (`contractspec test`) wraps the runner for automation.\n- **ExperimentSpec**: experiment definitions (`src/experiments/spec.ts`) describing variants, allocation strategies, and success metrics. `ExperimentEvaluator` assigns variants (random/sticky/targeted) and integrates with Policy/Telemetry for safe experimentation.\n- **AppBlueprintSpec / TenantAppConfig**: global blueprints and per-tenant overrides (`src/app-config/spec.ts`). `resolveAppConfig()` merges the two into a `ResolvedAppConfig`, while `composeAppConfig()` hydrates the merged view against registries and reports missing references for safe rollout.\n- **RegeneratorService**: background daemon (`src/regenerator/service.ts`) that consumes telemetry/error/behavior signals, evaluates regeneration rules, and produces `SpecChangeProposal`s for Studio review.\n- **DataViewSpec**: declarative data presentation layer in `src/data-views.ts`. Describes entity projections (`fields`, `filters`, `actions`) with `view.kind` (`list`, `table`, `detail`, `grid`), ties to query operations via `source.primary`, and exposes optional presentation-based empty/error states.\n- **ThemeSpec**: design token + component variant definitions in `src/themes.ts`. Supports inheritance (`extends`), tenant/user overrides, and component-specific variant metadata for the design system.\n- **MigrationSpec**: schema/data migration descriptors (`src/migrations.ts`) with ordered step plans, dependency tracking, and pre/post checks to support automated database/content migrations.\n- **WorkflowSpec**: typed definition of multi-step workflows living in `src/workflow/spec.ts`. `WorkflowRegistry` stores versioned specs, and `validateWorkflowSpec()` (in `src/workflow/validation.ts`) checks graph integrity, step references, and reachability.\n\n### Lifecycle\n\n1. Define the spec (I/O via `SchemaModel` or zod) in a vertical lib (e.g. `contracts-coliving`).\n2. Register it: `installOp(registry, spec, handler)` within the app/service.\n3. Expose it via an adapter (REST, GraphQL, MCP). Each adapter maps the I/O to its transport and enforces policy.\n4. Validate at runtime: parse `input` before executing, parse `output` before returning.\n\n### Adapters\n\n- **REST**: see `packages/lssm/libs/contracts/src/server/rest-*`. Binds routes, validates request/response, maps errors/policies.\n- **MCP**: see `packages/lssm/libs/contracts/src/server/provider-mcp.ts` (standalone MCP server) and `packages/lssm/libs/contracts/src/server/rest-next-mcp.ts` (MCP over Next.js route). Provides tools/resources/prompts.\n  - Tools + resources are registered from Zod schemas.\n  - Resource templates are keyed by full `ResourceMeta.uriTemplate` (e.g. `docs://list`, `docs://doc/{id}`), so multiple templates can share a scheme (`docs://*`) without collisions.\n- **GraphQL (Pothos)**: see `packages/lssm/libs/contracts/src/server/graphql-pothos.ts`. Adds Query/Mutation fields by transforming contract I/O to GraphQL types.\n\n### GraphQL adapter behaviour (summary)\n\n- Field naming: `spec.transport.gql.field` or `<name_with_dots>_v<version>`.\n- Input/Output types from `SchemaModel` (preferred) or fallback zod introspection.\n- Scalars: String/Int/Float/Boolean/Date/JSON; Objects/Arrays/Enums; unions for outputs; input unions => JSON.\n- Policy: auth gate checks GraphQL context; optional feature flag gating.\n- Complexity & tracing: attaches hints and records timings; log includes `{ specName, version }`.\n\n#### Returns mapping and hydration\n\n- `spec.transport.gql.returns` can declare the GraphQL return wrapper: e.g. `\"Spot\"` or `[Spot]`. If omitted, the adapter infers from `io.output` (SchemaModel) or `resourceRef.graphQLType`.\n- Resource outputs: when `io.output` is a `resourceRef(...)` or `transport.gql.resource` is set, the adapter will optionally hydrate via a `ResourceRegistry` using `contracts-adapter-hydration.ts`:\n  - Grammar is parsed with `parseReturns()`.\n  - Entities are resolved via `hydrateResourceIfNeeded(resources, result, { template, varName, returns })` after handler execution.\n\n### Resource outputs\n\n- Declare resource outputs using `resourceRef(uriTemplate, opts)`.\n- `opts.varName` (default `id`) selects the identifier field returned by the handler for URI substitution.\n- `opts.graphQLType` is the GraphQL return type name (e.g., `Spot`) or list form (e.g., `[Spot]`).\n- `opts.many: true` indicates the handler returns an array of resources. The handler type becomes an array of items that include the identifier field.\n\nExample:\n\n```ts\nio: {\n  input: ListThingsInput,\n  output: resourceRef('myapp://thing/{id}', { graphQLType: '[Thing]', many: true }),\n}\n```\n\nHandler return (simplified): `{ id: string | number }[]`.\n\n### Errors\n\n- Validation errors → transport 400/GraphQL UserInputError.\n- Policy/auth errors → 401/403 or GraphQL ForbiddenError.\n- Handler errors → mapped to transport error with safe message.\n\n### Versioning & naming\n\n- Keep `meta.version` monotonic. Clients should pin to a versioned field/key.\n- Avoid renaming existing fields; add new fields with new versions.\n\n### Ownership metadata (OwnerShipMeta)\n\nAll contracts, events, features, and presentations reference a shared ownership schema (source of truth in `packages/lssm/libs/contracts/src/ownership.ts`).\n\n- Required fields: `title`, `description`, `domain`, `owners[]`, `tags[]`, `stability`.\n- Curated enums: the library exports suggested constants for owners and tags; free-form strings are still allowed for forward-compatibility.\n- Operations (`spec.ts`): `meta` requires `stability`, `owners`, and `tags` alongside `name`, `version`, `kind`, `description`, `goal`, and `context`.\n- Presentations V2: `meta` is a partial of ownership plus `description`.\n- Events: may specify `ownership` (recommended) for discoverability and docs.\n\n### Quick start\n\n```ts\n// app bootstrap\nconst reg = new SpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"}];e(t);export{t as tech_contracts_README_DocBlocks};
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/README.docblock.ts
+const tech_contracts_README_DocBlocks = [{
+	id: "docs.tech.contracts.README",
+	title: "Contracts: Specs, Registry, Handlers, Adapters",
+	summary: "- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, install helpers, REST/MCP adapters).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/README",
+	tags: [
+		"tech",
+		"contracts",
+		"README"
+	],
+	body: "## Contracts: Specs, Registry, Handlers, Adapters\n\n### What lives where\n\n- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, install helpers, REST/MCP adapters).\n- `packages/lssm/libs/schema` defines the schema dictionary (`SchemaModel`, `FieldType`) used to describe I/O once and map to multiple targets (zod, GraphQL, JSON Schema).\n- App adapters (e.g. GraphQL) live close to the app. Example: `packages/hcircle/apps/api-coliving/src/graphql/contracts-adapter.ts`.\n\n### npm distribution\n\n- `@lssm/lib.contracts` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@lssm/lib.contracts/client` exposes only browser-safe helpers (React renderers, client SDK, drivers). Import from this entry when bundling for the web or React Native to avoid dragging server adapters.\n- `@lssm/lib.contracts/server` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@lssm/lib.contracts/types` exports the runtime handler context utilities, while `@lssm/lib.contracts/types/all` re-exports every type alias/interface across the package via `export type` so consumers can import a single module for typings without shipping runtime code.\n- `@lssm/lib.schema`, `@lssm/lib.design-system`, `@lssm/lib.ui-kit`, `@lssm/lib.ui-kit-web`, `@lssm/lib.accessibility`, and the presentation runtime packages are published to npm alongside contracts; prefer the scoped packages to keep tree-shaking intact.\n- Bundlers with conditional exports should resolve subpaths first; keep root imports for server-only code paths.\n\n### Core concepts\n\n- **ContractSpec**: immutable description of an operation.\n  - `meta`: `{ name, version, kind: 'query' | 'command' }`\n  - `io`: `{ input: SchemaModel | zod schema, output: SchemaModel | zod schema }`\n  - `policy`: `{ auth?: {...}, rateLimit?: {...}, flags?: string[] }`\n  - `transport.gql.field?`: explicit GraphQL field name (otherwise derived via `defaultGqlField`).\n- **SpecRegistry**: registry of specs + handlers. Use `installOp(reg, spec, handler)` to attach a handler.\n- **Handler**: `(ctx, input) => Promise<output>` implementing the operation.\n- **CapabilitySpec**: canonical capability declaration stored in `src/capabilities.ts`. Tracks `meta` (`{ key, version, kind, title, description, domain, owners, tags, stability }`), `provides` surfaces (`operation`, `event`, `workflow`, `presentation`, `resource`), and `requires` which other capabilities must be present. Enforced during `installFeature`.\n- **PolicySpec**: declarative policy rules (`src/policy/spec.ts`) covering ABAC/ReBAC, consent + rate limit requirements, field-level controls, and PII guidance. `PolicyEngine` evaluates refs, while `OPAPolicyAdapter` lets OPA override/augment runtime decisions.\n- **TelemetrySpec**: analytics definitions (`src/telemetry/spec.ts`) describing event semantics, privacy level, retention, sampling, and anomaly detection. `TelemetryTracker` handles redaction/sampling, `TelemetryAnomalyMonitor` raises alerts, and specs integrate with contracts/workflows via `ctx.telemetry`.\n- **TestSpec**: declarative scenario definitions in `src/tests/spec.ts`. `TestRunner` executes fixtures/actions/assertions against a `SpecRegistry`, and the CLI (`contractspec test`) wraps the runner for automation.\n- **ExperimentSpec**: experiment definitions (`src/experiments/spec.ts`) describing variants, allocation strategies, and success metrics. `ExperimentEvaluator` assigns variants (random/sticky/targeted) and integrates with Policy/Telemetry for safe experimentation.\n- **AppBlueprintSpec / TenantAppConfig**: global blueprints and per-tenant overrides (`src/app-config/spec.ts`). `resolveAppConfig()` merges the two into a `ResolvedAppConfig`, while `composeAppConfig()` hydrates the merged view against registries and reports missing references for safe rollout.\n- **RegeneratorService**: background daemon (`src/regenerator/service.ts`) that consumes telemetry/error/behavior signals, evaluates regeneration rules, and produces `SpecChangeProposal`s for Studio review.\n- **DataViewSpec**: declarative data presentation layer in `src/data-views.ts`. Describes entity projections (`fields`, `filters`, `actions`) with `view.kind` (`list`, `table`, `detail`, `grid`), ties to query operations via `source.primary`, and exposes optional presentation-based empty/error states.\n- **ThemeSpec**: design token + component variant definitions in `src/themes.ts`. Supports inheritance (`extends`), tenant/user overrides, and component-specific variant metadata for the design system.\n- **MigrationSpec**: schema/data migration descriptors (`src/migrations.ts`) with ordered step plans, dependency tracking, and pre/post checks to support automated database/content migrations.\n- **WorkflowSpec**: typed definition of multi-step workflows living in `src/workflow/spec.ts`. `WorkflowRegistry` stores versioned specs, and `validateWorkflowSpec()` (in `src/workflow/validation.ts`) checks graph integrity, step references, and reachability.\n\n### Lifecycle\n\n1. Define the spec (I/O via `SchemaModel` or zod) in a vertical lib (e.g. `contracts-coliving`).\n2. Register it: `installOp(registry, spec, handler)` within the app/service.\n3. Expose it via an adapter (REST, GraphQL, MCP). Each adapter maps the I/O to its transport and enforces policy.\n4. Validate at runtime: parse `input` before executing, parse `output` before returning.\n\n### Adapters\n\n- **REST**: see `packages/lssm/libs/contracts/src/server/rest-*`. Binds routes, validates request/response, maps errors/policies.\n- **MCP**: see `packages/lssm/libs/contracts/src/server/provider-mcp.ts` (standalone MCP server) and `packages/lssm/libs/contracts/src/server/rest-next-mcp.ts` (MCP over Next.js route). Provides tools/resources/prompts.\n  - Tools + resources are registered from Zod schemas.\n  - Resource templates are keyed by full `ResourceMeta.uriTemplate` (e.g. `docs://list`, `docs://doc/{id}`), so multiple templates can share a scheme (`docs://*`) without collisions.\n- **GraphQL (Pothos)**: see `packages/lssm/libs/contracts/src/server/graphql-pothos.ts`. Adds Query/Mutation fields by transforming contract I/O to GraphQL types.\n\n### GraphQL adapter behaviour (summary)\n\n- Field naming: `spec.transport.gql.field` or `<name_with_dots>_v<version>`.\n- Input/Output types from `SchemaModel` (preferred) or fallback zod introspection.\n- Scalars: String/Int/Float/Boolean/Date/JSON; Objects/Arrays/Enums; unions for outputs; input unions => JSON.\n- Policy: auth gate checks GraphQL context; optional feature flag gating.\n- Complexity & tracing: attaches hints and records timings; log includes `{ specName, version }`.\n\n#### Returns mapping and hydration\n\n- `spec.transport.gql.returns` can declare the GraphQL return wrapper: e.g. `\"Spot\"` or `[Spot]`. If omitted, the adapter infers from `io.output` (SchemaModel) or `resourceRef.graphQLType`.\n- Resource outputs: when `io.output` is a `resourceRef(...)` or `transport.gql.resource` is set, the adapter will optionally hydrate via a `ResourceRegistry` using `contracts-adapter-hydration.ts`:\n  - Grammar is parsed with `parseReturns()`.\n  - Entities are resolved via `hydrateResourceIfNeeded(resources, result, { template, varName, returns })` after handler execution.\n\n### Resource outputs\n\n- Declare resource outputs using `resourceRef(uriTemplate, opts)`.\n- `opts.varName` (default `id`) selects the identifier field returned by the handler for URI substitution.\n- `opts.graphQLType` is the GraphQL return type name (e.g., `Spot`) or list form (e.g., `[Spot]`).\n- `opts.many: true` indicates the handler returns an array of resources. The handler type becomes an array of items that include the identifier field.\n\nExample:\n\n```ts\nio: {\n  input: ListThingsInput,\n  output: resourceRef('myapp://thing/{id}', { graphQLType: '[Thing]', many: true }),\n}\n```\n\nHandler return (simplified): `{ id: string | number }[]`.\n\n### Errors\n\n- Validation errors → transport 400/GraphQL UserInputError.\n- Policy/auth errors → 401/403 or GraphQL ForbiddenError.\n- Handler errors → mapped to transport error with safe message.\n\n### Versioning & naming\n\n- Keep `meta.version` monotonic. Clients should pin to a versioned field/key.\n- Avoid renaming existing fields; add new fields with new versions.\n\n### Ownership metadata (OwnerShipMeta)\n\nAll contracts, events, features, and presentations reference a shared ownership schema (source of truth in `packages/lssm/libs/contracts/src/ownership.ts`).\n\n- Required fields: `title`, `description`, `domain`, `owners[]`, `tags[]`, `stability`.\n- Curated enums: the library exports suggested constants for owners and tags; free-form strings are still allowed for forward-compatibility.\n- Operations (`spec.ts`): `meta` requires `stability`, `owners`, and `tags` alongside `name`, `version`, `kind`, `description`, `goal`, and `context`.\n- Presentations V2: `meta` is a partial of ownership plus `description`.\n- Events: may specify `ownership` (recommended) for discoverability and docs.\n\n### Quick start\n\n```ts\n// app bootstrap\nconst reg = new SpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"
+}];
+registerDocBlocks(tech_contracts_README_DocBlocks);
+
+//#endregion
+export { tech_contracts_README_DocBlocks };

package/dist/docs/tech/contracts/create-subscription.docblock.js

@@ -1 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.create-subscription`,title:`Subscriptions via Better Auth Stripe`,summary:`This app uses Better Auth's Stripe plugin for subscription management.`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/create-subscription`,tags:[`tech`,`contracts`,`create-subscription`],body:"### Subscriptions via Better Auth Stripe\n\nThis app uses Better Auth's Stripe plugin for subscription management.\n\nKey endpoints:\n\n- `/api/auth/[...all]` – Better Auth server\n- `/api/auth/stripe/webhook` – Stripe webhook handled by Better Auth\n\nClient usage (org mode):\n\n```ts\nimport { subscription } from '@/lib/auth-client';\n\nawait subscription.upgrade({\n  plan: 'core',\n  annual: true,\n  referenceId: activeOrganization?.id,\n  successUrl: '/dashboard',\n  cancelUrl: '/pricing',\n});\n```\n\nPlans are configured in `src/lib/auth.ts` referencing env-provided price IDs. See Better Auth Stripe docs: [plugins: Stripe](`https://better-auth.com/docs/plugins/stripe.mdx`) and [Using with organizations](`https://www.better-auth.com/docs/plugins/stripe#using-with-organizations`).\n\nLanding pricing UX\n\n- Components: `SectionEyebrow`, `PriceBadge`, `FeatureList`, `PriceCard`\n- Sections: `PricingSection`, `StoryPricingBenefits`\n- Canonical pricing source: `src/lib/pricing/config.ts`\n\nTrial period\n\n- Le plan « Essentiel » inclut une période d’essai gratuite de 30 jours.\n- Config côté auth: `freeTrial: { days: 30 }` dans `src/lib/auth.ts` (Better Auth Stripe plugin).\n- Config côté pricing: `trial: { days: 30 }` dans `src/lib/pricing/config.ts`.\n\nDashboard badges\n\n- Le `Tableau de bord` affiche des badges d’état d’abonnement:\n  - « Essai · se termine le JJ/MM/AAAA » lorsque l’essai est en cours\n  - « Abonnement actif » lorsque l’abonnement est actif\n  - « Annulé · fin au terme de la période » lorsque la résiliation est planifiée\n- Composant: `components/dashboard/DashboardPage/molecules/Header.tsx`\n- Source des états: hook `useProfileBillingPage()` (`components/profile/ProfileBillingPage/hooks/useProfileBillingPage.tsx`)\n"}];e(t);export{t as tech_contracts_create_subscription_DocBlocks};
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/create-subscription.docblock.ts
+const tech_contracts_create_subscription_DocBlocks = [{
+	id: "docs.tech.contracts.create-subscription",
+	title: "Subscriptions via Better Auth Stripe",
+	summary: "This app uses Better Auth's Stripe plugin for subscription management.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/create-subscription",
+	tags: [
+		"tech",
+		"contracts",
+		"create-subscription"
+	],
+	body: "### Subscriptions via Better Auth Stripe\n\nThis app uses Better Auth's Stripe plugin for subscription management.\n\nKey endpoints:\n\n- `/api/auth/[...all]` – Better Auth server\n- `/api/auth/stripe/webhook` – Stripe webhook handled by Better Auth\n\nClient usage (org mode):\n\n```ts\nimport { subscription } from '@/lib/auth-client';\n\nawait subscription.upgrade({\n  plan: 'core',\n  annual: true,\n  referenceId: activeOrganization?.id,\n  successUrl: '/dashboard',\n  cancelUrl: '/pricing',\n});\n```\n\nPlans are configured in `src/lib/auth.ts` referencing env-provided price IDs. See Better Auth Stripe docs: [plugins: Stripe](`https://better-auth.com/docs/plugins/stripe.mdx`) and [Using with organizations](`https://www.better-auth.com/docs/plugins/stripe#using-with-organizations`).\n\nLanding pricing UX\n\n- Components: `SectionEyebrow`, `PriceBadge`, `FeatureList`, `PriceCard`\n- Sections: `PricingSection`, `StoryPricingBenefits`\n- Canonical pricing source: `src/lib/pricing/config.ts`\n\nTrial period\n\n- Le plan « Essentiel » inclut une période d’essai gratuite de 30 jours.\n- Config côté auth: `freeTrial: { days: 30 }` dans `src/lib/auth.ts` (Better Auth Stripe plugin).\n- Config côté pricing: `trial: { days: 30 }` dans `src/lib/pricing/config.ts`.\n\nDashboard badges\n\n- Le `Tableau de bord` affiche des badges d’état d’abonnement:\n  - « Essai · se termine le JJ/MM/AAAA » lorsque l’essai est en cours\n  - « Abonnement actif » lorsque l’abonnement est actif\n  - « Annulé · fin au terme de la période » lorsque la résiliation est planifiée\n- Composant: `components/dashboard/DashboardPage/molecules/Header.tsx`\n- Source des états: hook `useProfileBillingPage()` (`components/profile/ProfileBillingPage/hooks/useProfileBillingPage.tsx`)\n"
+}];
+registerDocBlocks(tech_contracts_create_subscription_DocBlocks);
+
+//#endregion
+export { tech_contracts_create_subscription_DocBlocks };

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

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

@@ -1 +1,21 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{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 '@lssm/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"}];e(t);export{t as tech_contracts_migrations_DocBlocks};
+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 '@lssm/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.js

@@ -1,4 +1,19 @@
-import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.openapi-export`,title:`OpenAPI export (OpenAPI 3.1) from SpecRegistry`,summary:`Generate a deterministic OpenAPI document from a SpecRegistry 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 SpecRegistry
+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 SpecRegistry",
+	summary: "Generate a deterministic OpenAPI document from a SpecRegistry 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 SpecRegistry
 
 ### Purpose
 
@@ -35,4 +50,9 @@ The registry module must export one of:
 
 - 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.`}];e(t);export{t as tech_contracts_openapi_export_DocBlocks};
+- 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 };