@contractspec/lib.contracts-spec 2.0.0

package/dist/node/docs/index.js

@@ -0,0 +1,4719 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/registry-utils.ts
+var exports_registry_utils = {};
+__export(exports_registry_utils, {
+  groupByToArray: () => groupByToArray,
+  groupByMultiple: () => groupByMultiple,
+  groupBy: () => groupBy,
+  getUniqueTags: () => getUniqueTags,
+  getUniqueOwners: () => getUniqueOwners,
+  getUniqueDomains: () => getUniqueDomains,
+  filterBy: () => filterBy,
+  GroupingStrategies: () => GroupingStrategies
+});
+function filterBy(items, filter) {
+  return items.filter((item) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.domain) {
+      const itemDomain = GroupingStrategies.byDomain(item);
+      if (itemDomain !== filter.domain)
+        return false;
+    }
+    if (filter.keyPattern) {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(name))
+        return false;
+    }
+    return true;
+  });
+}
+function groupBy(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupByToArray(items, keyFn) {
+  const map = groupBy(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
+}
+function groupByMultiple(items, keysFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const keys = keysFn(item);
+    for (const key of keys) {
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+  }
+  return groups;
+}
+function getUniqueTags(items) {
+  const tags = new Set;
+  for (const item of items) {
+    for (const tag of item.meta.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueOwners(items) {
+  const owners = new Set;
+  for (const item of items) {
+    for (const owner of item.meta.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueDomains(items) {
+  const domains = new Set;
+  for (const item of items) {
+    domains.add(GroupingStrategies.byDomain(item));
+  }
+  return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esm(() => {
+  GroupingStrategies = {
+    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+    byDomain: (item) => {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      return name.split(".")[0] ?? "default";
+    },
+    byStability: (item) => item.meta.stability ?? "stable",
+    byUrlPath: (level) => (item) => {
+      if (!item.path)
+        return "root";
+      const segments = item.path.split("/").filter(Boolean);
+      return segments.slice(0, level).join("/") || "root";
+    }
+  };
+});
+
+// src/capabilities/capabilities.ts
+import { compareVersions } from "compare-versions";
+var capKey = (key, version) => `${key}.v${version}`;
+
+class CapabilityRegistry {
+  items = new Map;
+  surfaceIndex = null;
+  register(spec) {
+    const key = capKey(spec.meta.key, spec.meta.version);
+    if (this.items.has(key))
+      throw new Error(`Duplicate capability ${key}`);
+    this.items.set(key, spec);
+    this.surfaceIndex = null;
+    return this;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(capKey(key, version));
+    let candidate;
+    for (const spec of this.items.values()) {
+      if (spec.meta.key !== key)
+        continue;
+      if (!candidate || compareVersions(spec.meta.version, candidate.meta.version) > 0) {
+        candidate = spec;
+      }
+    }
+    return candidate;
+  }
+  satisfies(requirement, additional) {
+    if (requirement.optional)
+      return true;
+    if (additional?.some((ref) => matchesRequirement(ref, requirement)))
+      return true;
+    const spec = requirement.version ? this.get(requirement.key, requirement.version) : this.get(requirement.key);
+    if (!spec)
+      return false;
+    if (requirement.kind && spec.meta.kind !== requirement.kind)
+      return false;
+    if (requirement.version != null && spec.meta.version !== requirement.version)
+      return false;
+    return true;
+  }
+  buildSurfaceIndex() {
+    if (this.surfaceIndex)
+      return this.surfaceIndex;
+    this.surfaceIndex = new Map;
+    for (const spec of this.items.values()) {
+      const capabilityKey = capKey(spec.meta.key, spec.meta.version);
+      for (const surface of spec.provides ?? []) {
+        const surfaceKey = `${surface.surface}:${surface.key}`;
+        if (!this.surfaceIndex.has(surfaceKey)) {
+          this.surfaceIndex.set(surfaceKey, new Set);
+        }
+        this.surfaceIndex.get(surfaceKey)?.add(capabilityKey);
+      }
+    }
+    return this.surfaceIndex;
+  }
+  getOperationsFor(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    return spec.provides?.filter((s) => s.surface === "operation").map((s) => s.key) ?? [];
+  }
+  getEventsFor(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    return spec.provides?.filter((s) => s.surface === "event").map((s) => s.key) ?? [];
+  }
+  getPresentationsFor(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    return spec.provides?.filter((s) => s.surface === "presentation").map((s) => s.key) ?? [];
+  }
+  getWorkflowsFor(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    return spec.provides?.filter((s) => s.surface === "workflow").map((s) => s.key) ?? [];
+  }
+  getResourcesFor(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    return spec.provides?.filter((s) => s.surface === "resource").map((s) => s.key) ?? [];
+  }
+  getCapabilitiesForOperation(operationKey) {
+    const index = this.buildSurfaceIndex();
+    const capKeys = index.get(`operation:${operationKey}`);
+    if (!capKeys)
+      return [];
+    return [...capKeys].map((k) => {
+      const spec = this.items.get(k);
+      return { key: spec?.meta.key ?? "", version: spec?.meta.version ?? "" };
+    });
+  }
+  getCapabilitiesForEvent(eventKey) {
+    const index = this.buildSurfaceIndex();
+    const capKeys = index.get(`event:${eventKey}`);
+    if (!capKeys)
+      return [];
+    return [...capKeys].map((k) => {
+      const spec = this.items.get(k);
+      return { key: spec?.meta.key ?? "", version: spec?.meta.version ?? "" };
+    });
+  }
+  getCapabilitiesForPresentation(presentationKey) {
+    const index = this.buildSurfaceIndex();
+    const capKeys = index.get(`presentation:${presentationKey}`);
+    if (!capKeys)
+      return [];
+    return [...capKeys].map((k) => {
+      const spec = this.items.get(k);
+      return { key: spec?.meta.key ?? "", version: spec?.meta.version ?? "" };
+    });
+  }
+  getAncestors(capabilityKey, version) {
+    const ancestors = [];
+    const visited = new Set;
+    let current = this.get(capabilityKey, version);
+    while (current?.extends) {
+      const parentKey = capKey(current.extends.key, current.extends.version);
+      if (visited.has(parentKey)) {
+        break;
+      }
+      visited.add(parentKey);
+      const parent = this.get(current.extends.key, current.extends.version);
+      if (!parent)
+        break;
+      ancestors.push(parent);
+      current = parent;
+    }
+    return ancestors;
+  }
+  getEffectiveRequirements(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    const ancestors = this.getAncestors(capabilityKey, version);
+    const requirementMap = new Map;
+    for (const ancestor of [...ancestors].reverse()) {
+      for (const req of ancestor.requires ?? []) {
+        requirementMap.set(req.key, req);
+      }
+    }
+    for (const req of spec.requires ?? []) {
+      requirementMap.set(req.key, req);
+    }
+    return [...requirementMap.values()];
+  }
+  getEffectiveSurfaces(capabilityKey, version) {
+    const spec = this.get(capabilityKey, version);
+    if (!spec)
+      return [];
+    const ancestors = this.getAncestors(capabilityKey, version);
+    const surfaces = [];
+    for (const ancestor of [...ancestors].reverse()) {
+      surfaces.push(...ancestor.provides ?? []);
+    }
+    surfaces.push(...spec.provides ?? []);
+    return surfaces;
+  }
+}
+function matchesRequirement(ref, requirement) {
+  if (ref.key !== requirement.key)
+    return false;
+  if (requirement.version != null && ref.version !== requirement.version)
+    return false;
+  return true;
+}
+function capabilityKey(spec) {
+  return capKey(spec.meta.key, spec.meta.version);
+}
+function defineCapability(spec) {
+  return spec;
+}
+
+// src/capabilities/validation.ts
+function validateCapabilityConsistency(deps) {
+  const errors = [];
+  const warnings = [];
+  for (const capability of deps.capabilities.list()) {
+    const capKey2 = `${capability.meta.key}.v${capability.meta.version}`;
+    for (const surface of capability.provides ?? []) {
+      const exists = checkSurfaceExists(deps, surface.surface, surface.key);
+      if (!exists) {
+        errors.push({
+          type: "missing_surface_spec",
+          message: `Capability "${capKey2}" provides ${surface.surface} "${surface.key}" but spec not found`,
+          capabilityKey: capKey2,
+          surface: surface.surface,
+          specKey: surface.key
+        });
+      }
+    }
+  }
+  if (deps.operations) {
+    for (const op of deps.operations.list()) {
+      if (op.capability) {
+        const capSpec = deps.capabilities.get(op.capability.key, op.capability.version);
+        if (!capSpec) {
+          errors.push({
+            type: "capability_not_found",
+            message: `Operation "${op.meta.key}" references capability "${op.capability.key}.v${op.capability.version}" but capability not found`,
+            specKey: op.meta.key,
+            capabilityKey: `${op.capability.key}.v${op.capability.version}`,
+            surface: "operation"
+          });
+        } else {
+          const inProvides = capSpec.provides?.some((p) => p.surface === "operation" && p.key === op.meta.key);
+          if (!inProvides) {
+            errors.push({
+              type: "surface_not_in_provides",
+              message: `Operation "${op.meta.key}" claims capability "${op.capability.key}.v${op.capability.version}" but not in capability's provides`,
+              specKey: op.meta.key,
+              capabilityKey: `${op.capability.key}.v${op.capability.version}`,
+              surface: "operation"
+            });
+          }
+        }
+      }
+    }
+  }
+  if (deps.events) {
+    for (const event of deps.events.list()) {
+      if (event.capability) {
+        const capSpec = deps.capabilities.get(event.capability.key, event.capability.version);
+        if (!capSpec) {
+          errors.push({
+            type: "capability_not_found",
+            message: `Event "${event.meta.key}" references capability "${event.capability.key}.v${event.capability.version}" but capability not found`,
+            specKey: event.meta.key,
+            capabilityKey: `${event.capability.key}.v${event.capability.version}`,
+            surface: "event"
+          });
+        } else {
+          const inProvides = capSpec.provides?.some((p) => p.surface === "event" && p.key === event.meta.key);
+          if (!inProvides) {
+            errors.push({
+              type: "surface_not_in_provides",
+              message: `Event "${event.meta.key}" claims capability "${event.capability.key}.v${event.capability.version}" but not in capability's provides`,
+              specKey: event.meta.key,
+              capabilityKey: `${event.capability.key}.v${event.capability.version}`,
+              surface: "event"
+            });
+          }
+        }
+      }
+    }
+  }
+  if (deps.presentations) {
+    for (const pres of deps.presentations.list()) {
+      if (pres.capability) {
+        const capSpec = deps.capabilities.get(pres.capability.key, pres.capability.version);
+        if (!capSpec) {
+          errors.push({
+            type: "capability_not_found",
+            message: `Presentation "${pres.meta.key}" references capability "${pres.capability.key}.v${pres.capability.version}" but capability not found`,
+            specKey: pres.meta.key,
+            capabilityKey: `${pres.capability.key}.v${pres.capability.version}`,
+            surface: "presentation"
+          });
+        } else {
+          const inProvides = capSpec.provides?.some((p) => p.surface === "presentation" && p.key === pres.meta.key);
+          if (!inProvides) {
+            errors.push({
+              type: "surface_not_in_provides",
+              message: `Presentation "${pres.meta.key}" claims capability "${pres.capability.key}.v${pres.capability.version}" but not in capability's provides`,
+              specKey: pres.meta.key,
+              capabilityKey: `${pres.capability.key}.v${pres.capability.version}`,
+              surface: "presentation"
+            });
+          }
+        }
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function checkSurfaceExists(deps, surface, key) {
+  switch (surface) {
+    case "operation":
+      return deps.operations?.has(key) ?? true;
+    case "event":
+      return deps.events?.has(key) ?? true;
+    case "presentation":
+      return deps.presentations?.has(key) ?? true;
+    case "workflow":
+    case "resource":
+      return true;
+    default:
+      return true;
+  }
+}
+function findOrphanSpecs(deps) {
+  const result = {
+    operations: [],
+    events: [],
+    presentations: []
+  };
+  if (deps.operations) {
+    for (const op of deps.operations.list()) {
+      if (!op.capability) {
+        result.operations.push(op.meta.key);
+      }
+    }
+  }
+  if (deps.events) {
+    for (const event of deps.events.list()) {
+      if (!event.capability) {
+        result.events.push(event.meta.key);
+      }
+    }
+  }
+  if (deps.presentations) {
+    for (const pres of deps.presentations.list()) {
+      if (!pres.capability) {
+        result.presentations.push(pres.meta.key);
+      }
+    }
+  }
+  return result;
+}
+
+// src/capabilities/context.ts
+class CapabilityMissingError extends Error {
+  capabilityKey;
+  requiredVersion;
+  constructor(capabilityKey2, requiredVersion) {
+    const versionSuffix = requiredVersion ? `.v${requiredVersion}` : "";
+    super(`Missing required capability: ${capabilityKey2}${versionSuffix}`);
+    this.name = "CapabilityMissingError";
+    this.capabilityKey = capabilityKey2;
+    this.requiredVersion = requiredVersion;
+  }
+}
+
+class CapabilityContextImpl {
+  capabilities;
+  capabilityVersions;
+  constructor(enabledCapabilities) {
+    const capSet = new Set;
+    const versionMap = new Map;
+    for (const cap of enabledCapabilities) {
+      capSet.add(cap.key);
+      versionMap.set(cap.key, cap.version);
+    }
+    this.capabilities = capSet;
+    this.capabilityVersions = versionMap;
+  }
+  hasCapability(key, version) {
+    if (!this.capabilities.has(key))
+      return false;
+    if (version != null) {
+      const enabledVersion = this.capabilityVersions.get(key);
+      return enabledVersion === version;
+    }
+    return true;
+  }
+  requireCapability(key, version) {
+    if (!this.hasCapability(key, version)) {
+      throw new CapabilityMissingError(key, version);
+    }
+  }
+  hasAllCapabilities(keys) {
+    return keys.every((k) => this.capabilities.has(k));
+  }
+  hasAnyCapability(keys) {
+    return keys.some((k) => this.capabilities.has(k));
+  }
+  getMatchingCapabilities(pattern) {
+    if (!pattern.includes("*")) {
+      return this.capabilities.has(pattern) ? [pattern] : [];
+    }
+    const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    const regex = new RegExp(`^${regexPattern}$`);
+    return [...this.capabilities].filter((key) => regex.test(key));
+  }
+}
+function createCapabilityContext(enabledCapabilities) {
+  return new CapabilityContextImpl(enabledCapabilities);
+}
+function createEmptyCapabilityContext() {
+  return new CapabilityContextImpl([]);
+}
+function createBypassCapabilityContext(allCapabilities) {
+  return new CapabilityContextImpl(allCapabilities);
+}
+
+// src/capabilities/guards.ts
+function checkCapabilityForOperation(ctx, operation) {
+  if (!operation.capability) {
+    return { allowed: true };
+  }
+  const { key, version } = operation.capability;
+  if (ctx.hasCapability(key, version)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    missingCapability: { key, version },
+    reason: `Operation "${operation.meta.key}" requires capability "${key}.v${version}"`
+  };
+}
+function assertCapabilityForOperation(ctx, operation) {
+  const result = checkCapabilityForOperation(ctx, operation);
+  if (!result.allowed && result.missingCapability) {
+    throw new CapabilityMissingError(result.missingCapability.key, result.missingCapability.version);
+  }
+}
+function checkCapabilityForEvent(ctx, event) {
+  if (!event.capability) {
+    return { allowed: true };
+  }
+  const { key, version } = event.capability;
+  if (ctx.hasCapability(key, version)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    missingCapability: { key, version },
+    reason: `Event "${event.meta.key}" requires capability "${key}.v${version}"`
+  };
+}
+function assertCapabilityForEvent(ctx, event) {
+  const result = checkCapabilityForEvent(ctx, event);
+  if (!result.allowed && result.missingCapability) {
+    throw new CapabilityMissingError(result.missingCapability.key, result.missingCapability.version);
+  }
+}
+function checkCapabilityForPresentation(ctx, presentation) {
+  if (!presentation.capability) {
+    return { allowed: true };
+  }
+  const { key, version } = presentation.capability;
+  if (ctx.hasCapability(key, version)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    missingCapability: { key, version },
+    reason: `Presentation "${presentation.meta.key}" requires capability "${key}.v${version}"`
+  };
+}
+function assertCapabilityForPresentation(ctx, presentation) {
+  const result = checkCapabilityForPresentation(ctx, presentation);
+  if (!result.allowed && result.missingCapability) {
+    throw new CapabilityMissingError(result.missingCapability.key, result.missingCapability.version);
+  }
+}
+function filterOperationsByCapability(ctx, operations) {
+  return operations.filter((op) => checkCapabilityForOperation(ctx, op).allowed);
+}
+function filterEventsByCapability(ctx, events) {
+  return events.filter((ev) => checkCapabilityForEvent(ctx, ev).allowed);
+}
+function filterPresentationsByCapability(ctx, presentations) {
+  return presentations.filter((pres) => checkCapabilityForPresentation(ctx, pres).allowed);
+}
+
+// src/ownership.ts
+var StabilityEnum = {
+  Idea: "idea",
+  InCreation: "in_creation",
+  Experimental: "experimental",
+  Beta: "beta",
+  Stable: "stable",
+  Deprecated: "deprecated"
+};
+var OwnersEnum = {
+  PlatformCore: "platform.core",
+  PlatformSigil: "platform.sigil",
+  PlatformMarketplace: "platform.marketplace",
+  PlatformMessaging: "platform.messaging",
+  PlatformContent: "platform.content",
+  PlatformFeatureFlags: "platform.featureflags",
+  PlatformFinance: "platform.finance"
+};
+var Owners = OwnersEnum;
+var TagsEnum = {
+  Spots: "spots",
+  Collectivity: "collectivity",
+  Marketplace: "marketplace",
+  Sellers: "sellers",
+  Auth: "auth",
+  Login: "login",
+  Signup: "signup",
+  Guide: "guide",
+  Docs: "docs",
+  I18n: "i18n",
+  Incident: "incident",
+  Automation: "automation",
+  Hygiene: "hygiene"
+};
+var Tags = TagsEnum;
+
+// src/capabilities/openbanking.ts
+var OWNERS = ["platform.finance"];
+var TAGS = ["open-banking", "finance"];
+var openBankingAccountsReadCapability = {
+  meta: {
+    key: "openbanking.accounts.read",
+    version: "1.0.0",
+    kind: "integration",
+    title: "Open Banking Accounts (Read)",
+    description: "Provides read-only access to linked bank accounts, including account summaries and metadata.",
+    domain: "finance",
+    owners: [...OWNERS],
+    tags: [...TAGS],
+    stability: StabilityEnum.Experimental
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "openbanking.accounts.list",
+      version: "1.0.0",
+      description: "List bank accounts linked to a Powens open banking connection."
+    },
+    {
+      surface: "operation",
+      key: "openbanking.accounts.get",
+      version: "1.0.0",
+      description: "Retrieve the canonical bank account record for a specific account."
+    },
+    {
+      surface: "operation",
+      key: "openbanking.accounts.sync",
+      version: "1.0.0",
+      description: "Trigger a refresh of bank account metadata from the open banking provider."
+    }
+  ]
+};
+var openBankingTransactionsReadCapability = {
+  meta: {
+    key: "openbanking.transactions.read",
+    version: "1.0.0",
+    kind: "integration",
+    title: "Open Banking Transactions (Read)",
+    description: "Enables retrieval of transaction history for linked bank accounts via open banking providers.",
+    domain: "finance",
+    owners: [...OWNERS],
+    tags: [...TAGS, "transactions"],
+    stability: StabilityEnum.Experimental
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "openbanking.transactions.list",
+      version: "1.0.0",
+      description: "List transactions for a given bank account with optional date filtering."
+    },
+    {
+      surface: "operation",
+      key: "openbanking.transactions.sync",
+      version: "1.0.0",
+      description: "Synchronise transactions from the open banking provider into the canonical ledger."
+    }
+  ]
+};
+var openBankingBalancesReadCapability = {
+  meta: {
+    key: "openbanking.balances.read",
+    version: "1.0.0",
+    kind: "integration",
+    title: "Open Banking Balances (Read)",
+    description: "Allows querying of current and available balances for linked bank accounts via open banking providers.",
+    domain: "finance",
+    owners: [...OWNERS],
+    tags: [...TAGS, "balances"],
+    stability: StabilityEnum.Experimental
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "openbanking.balances.get",
+      version: "1.0.0",
+      description: "Retrieve the latest known balances for a specified bank account."
+    },
+    {
+      surface: "operation",
+      key: "openbanking.balances.refresh",
+      version: "1.0.0",
+      description: "Force a balance refresh from the open banking provider."
+    }
+  ]
+};
+function registerOpenBankingCapabilities(registry) {
+  return registry.register(openBankingAccountsReadCapability).register(openBankingTransactionsReadCapability).register(openBankingBalancesReadCapability);
+}
+
+// src/capabilities/meeting-recorder.ts
+var OWNERS2 = ["platform.integrations"];
+var TAGS2 = ["meeting-recorder", "transcripts", "integrations"];
+var meetingRecorderMeetingsReadCapability = {
+  meta: {
+    key: "meeting-recorder.meetings.read",
+    version: "1.0.0",
+    kind: "integration",
+    title: "Meeting Recorder Meetings (Read)",
+    description: "Provides read-only access to recorded meetings and their metadata.",
+    domain: "integrations",
+    owners: [...OWNERS2],
+    tags: [...TAGS2, "meetings"],
+    stability: StabilityEnum.Experimental
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "meeting-recorder.meetings.list",
+      version: "1.0.0",
+      description: "List meetings available from the recorder provider."
+    },
+    {
+      surface: "operation",
+      key: "meeting-recorder.meetings.get",
+      version: "1.0.0",
+      description: "Fetch detailed metadata for a specific meeting."
+    }
+  ]
+};
+var meetingRecorderTranscriptsReadCapability = {
+  meta: {
+    key: "meeting-recorder.transcripts.read",
+    version: "1.0.0",
+    kind: "integration",
+    title: "Meeting Recorder Transcripts (Read)",
+    description: "Enables retrieval of transcripts for recorded meetings from external providers.",
+    domain: "integrations",
+    owners: [...OWNERS2],
+    tags: [...TAGS2, "transcripts"],
+    stability: StabilityEnum.Experimental
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "meeting-recorder.transcripts.get",
+      version: "1.0.0",
+      description: "Fetch the transcript for a specific meeting recording."
+    },
+    {
+      surface: "operation",
+      key: "meeting-recorder.transcripts.sync",
+      version: "1.0.0",
+      description: "Trigger a transcript sync from the recorder provider."
+    }
+  ]
+};
+var meetingRecorderWebhooksCapability = {
+  meta: {
+    key: "meeting-recorder.webhooks",
+    version: "1.0.0",
+    kind: "integration",
+    title: "Meeting Recorder Webhooks",
+    description: "Allows processing of webhook events for meeting transcript readiness.",
+    domain: "integrations",
+    owners: [...OWNERS2],
+    tags: [...TAGS2, "webhooks"],
+    stability: StabilityEnum.Experimental
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "meeting-recorder.webhooks.ingest",
+      version: "1.0.0",
+      description: "Ingest and verify meeting recorder webhook payloads."
+    }
+  ]
+};
+function registerMeetingRecorderCapabilities(registry) {
+  return registry.register(meetingRecorderMeetingsReadCapability).register(meetingRecorderTranscriptsReadCapability).register(meetingRecorderWebhooksCapability);
+}
+// src/operations/operation.ts
+var isEmitDeclRef = (e) => ("ref" in e);
+var defineCommand = (spec) => ({
+  ...spec,
+  meta: { ...spec.meta, kind: "command" },
+  policy: {
+    ...spec.policy,
+    idempotent: spec.policy?.["policy"]?.idempotent ?? false
+  }
+});
+var defineQuery = (spec) => ({
+  ...spec,
+  meta: { ...spec.meta, kind: "query" },
+  policy: { ...spec.policy, idempotent: true }
+});
+
+// src/registry.ts
+init_registry_utils();
+import { compareVersions as compareVersions2 } from "compare-versions";
+var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
+
+class SpecContractRegistry {
+  contractType;
+  items = new Map;
+  constructor(contractType, items) {
+    this.contractType = contractType;
+    if (items) {
+      items.forEach((p) => this.register(p));
+    }
+  }
+  register(p) {
+    const key = keyOfSpecContract(p);
+    if (this.items.has(key))
+      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
+    this.items.set(key, p);
+    return this;
+  }
+  count() {
+    return this.items.size;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, p] of this.items.entries()) {
+      if (!k.startsWith(`${key}.v`))
+        continue;
+      if (!candidate || compareVersions2(p.meta.version, candidate.meta.version) > 0) {
+        candidate = p;
+      }
+    }
+    return candidate;
+  }
+  has(key, version) {
+    return !!this.get(key, version);
+  }
+  filter(criteria) {
+    return filterBy(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((p) => p.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((p) => p.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    return groupBy(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    return getUniqueTags(this.list());
+  }
+}
+
+// src/events.ts
+function defineEvent(e) {
+  return e;
+}
+var eventKey = (key, version) => `${key}.v${version}`;
+
+class EventRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("event", items);
+  }
+}
+
+// src/operations/registry.ts
+function opKey(key, version) {
+  return `${key}.v${version}`;
+}
+
+class OperationSpecRegistry extends SpecContractRegistry {
+  handlers = new Map;
+  constructor(items) {
+    super("operation", items);
+  }
+  bind(spec, handler) {
+    const key = opKey(spec.meta.key, spec.meta.version);
+    if (!this.items.has(key))
+      throw new Error(`Cannot bind; spec not found: ${key}`);
+    if (this.handlers.has(key))
+      throw new Error(`Handler already bound for ${key}`);
+    this.handlers.set(key, handler);
+    return this;
+  }
+  getHandler(key, version) {
+    const spec = this.get(key, version);
+    if (!spec)
+      return;
+    return this.handlers.get(opKey(spec.meta.key, spec.meta.version));
+  }
+  listBound() {
+    const out = [];
+    for (const [k, spec] of this.items.entries()) {
+      const h = this.handlers.get(k);
+      if (h)
+        out.push({ spec, handler: h });
+    }
+    return out;
+  }
+  async execute(key, version, rawInput, ctx) {
+    const baseSpec = this.get(key, version);
+    if (!baseSpec)
+      throw new Error(`Spec not found for ${key}${version ? `.v${version}` : ""}`);
+    const spec = await ctx.specVariantResolver?.resolve({
+      name: baseSpec.meta.key,
+      version: baseSpec.meta.version,
+      kind: baseSpec.meta.kind
+    }, ctx) ?? baseSpec;
+    let handlerKey = opKey(spec.meta.key, spec.meta.version);
+    let handler = this.handlers.get(handlerKey);
+    if (!handler) {
+      const fallbackKey = opKey(baseSpec.meta.key, baseSpec.meta.version);
+      handler = this.handlers.get(fallbackKey);
+      handlerKey = fallbackKey;
+    }
+    if (!handler)
+      throw new Error(`No handler bound for ${handlerKey}`);
+    const parsedInput = spec.io.input?.getZod().parse(rawInput);
+    if (ctx.decide) {
+      const [service, command] = spec.meta.key.split(".");
+      if (!service || !command)
+        throw new Error(`Invalid spec name: ${spec.meta.key}`);
+      const decision = await ctx.decide({
+        service,
+        command,
+        version: spec.meta.version,
+        actor: ctx.actor ?? "anonymous",
+        channel: ctx.channel,
+        roles: ctx.roles,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        flags: []
+      });
+      if (decision.effect === "deny") {
+        throw new Error(`PolicyDenied: ${spec.meta.key}.v${spec.meta.version}`);
+      }
+      if (decision.rateLimit && ctx.rateLimit) {
+        const key2 = decision.rateLimit.key ?? "default";
+        const rpm = decision.rateLimit.rpm ?? 60;
+        await ctx.rateLimit(key2, 1, rpm);
+      }
+    }
+    const allowedEvents = new Map;
+    if (spec.sideEffects?.emits) {
+      for (const e of spec.sideEffects.emits) {
+        if (isEmitDeclRef(e)) {
+          const eventSpec = ctx.eventSpecResolver?.get(e.ref.key, e.ref.version);
+          if (eventSpec) {
+            allowedEvents.set(`${e.ref.key}.v${e.ref.version}`, eventSpec.payload);
+          }
+        } else {
+          allowedEvents.set(`${e.key}.v${e.version}`, e.payload);
+        }
+      }
+    }
+    const emitGuard = async (eventName, eventVersion, payload) => {
+      const key2 = eventKey(eventName, eventVersion);
+      const schema = allowedEvents.get(key2);
+      if (!schema)
+        throw new Error(`UndeclaredEvent: ${key2} not allowed by ${opKey(spec.meta.key, spec.meta.version)}`);
+      const parsed = schema.getZod().parse(payload);
+      await ctx.eventPublisher?.({
+        key: eventName,
+        version: eventVersion,
+        payload: parsed,
+        traceId: ctx.traceId
+      });
+    };
+    if (ctx.appConfig) {
+      if (!ctx.branding) {
+        ctx.branding = ctx.appConfig.branding;
+      }
+      if (!ctx.translation) {
+        ctx.translation = { config: ctx.appConfig.translation };
+      } else if (!ctx.translation.config) {
+        ctx.translation = {
+          ...ctx.translation,
+          config: ctx.appConfig.translation
+        };
+      }
+    }
+    const telemetryContext = ctx.telemetry;
+    const trackTelemetry = async (trigger, details) => {
+      if (!telemetryContext || !trigger?.event)
+        return;
+      try {
+        const props = trigger.properties?.(details) ?? {};
+        await telemetryContext.track(trigger.event.key, trigger.event.version ?? "1.0.0", props, {
+          tenantId: ctx.organizationId ?? undefined,
+          organizationId: ctx.organizationId,
+          userId: ctx.userId,
+          actor: ctx.actor,
+          channel: ctx.channel,
+          metadata: ctx.traceId ? { traceId: ctx.traceId } : undefined
+        });
+      } catch (_error) {}
+    };
+    let result;
+    try {
+      result = await handler(parsedInput, {
+        ...ctx,
+        __emitGuard__: emitGuard
+      });
+    } catch (error) {
+      if (spec.telemetry?.failure) {
+        await trackTelemetry(spec.telemetry.failure, {
+          input: parsedInput ?? rawInput,
+          error
+        });
+      }
+      throw error;
+    }
+    if (spec.telemetry?.success) {
+      await trackTelemetry(spec.telemetry.success, {
+        input: parsedInput ?? rawInput,
+        output: result
+      });
+    }
+    const outputModel = spec.io.output;
+    if (outputModel?.getZod) {
+      const parsedOutput = outputModel.getZod().parse(result);
+      return parsedOutput;
+    }
+    return result;
+  }
+}
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/data-views/spec.ts
+function defineDataView(spec) {
+  return spec;
+}
+
+// src/data-views/registry.ts
+function dataViewKey(spec) {
+  return `${spec.meta.key}.v${spec.meta.version}`;
+}
+
+class DataViewRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("data-view", items);
+  }
+}
+// src/docs/accessibility_wcag_compliance_specs.docblock.ts
+var accessibility_wcag_compliance_specs_DocBlocks = [
+  {
+    id: "docs.accessibility_wcag_compliance_specs",
+    title: "Accessibility & WCAG Compliance — **specs.md**",
+    summary: "> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG 2.2 AA** (aim for AAA where low‑cost), align with **EN 301 549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React Native)**.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/accessibility_wcag_compliance_specs",
+    tags: ["accessibility_wcag_compliance_specs"],
+    body: `# Accessibility & WCAG Compliance — **specs.md**
+
+> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG 2.2 AA** (aim for AAA where low‑cost), align with **EN 301 549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React Native)**.
+
+---
+
+## 0) Scope & Principles
+
+- **Standards:** WCAG 2.2 AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN 301 549 compliance by conformance to WCAG.
+- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).
+- **Rule of ARIA:** “No ARIA is better than bad ARIA.” Prefer native elements.
+- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.
+- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in \`packages/lssm/libs/ui-kit-web\`. Prefer those components over per‑app duplicates (\`packages/*/apps/*/src/components/ui\`). When missing, add to \`ui-kit-web\` first, then adopt app‑side.
+
+---
+
+## 1) Design Requirements (Design System & Tokens)
+
+**1.1 Color & Contrast**
+
+- Body text, icons essential to meaning: **≥ 4.5:1**; large text (≥ 18.66px regular / 14px bold): **≥ 3:1**.
+- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥ 3:1** against adjacent colors; text within components follows text ratios.
+- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.
+
+**1.2 Focus Indicators (WCAG 2.4.11/12)**
+
+- Every interactive element has a **visible focus** with clear offset; indicator contrast **≥ 3:1** vs adjacent colors and indicator **area ≥ 2 CSS px** thick.
+- Focus **must not be obscured** by sticky headers/footers or scroll containers.
+
+**1.3 Motion & Preferences**
+
+- Respect \`prefers-reduced-motion\`: suppress large parallax, auto‑animations; provide instant alternatives.
+- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.
+
+**1.4 Target Size (2.5.8)**
+
+- Hit areas **≥ 24×24 CSS px** (web) and **≥ 44×44 dp** (mobile) unless exempt.
+
+**1.5 Typography & Layout**
+
+- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320 CSS px** width.
+- Maintain clear heading hierarchy (h1…h6), one **h1** per view.
+
+- Repository baseline (Web): default body text uses Tailwind \`text-lg\` (≈18px). As of 2025‑09‑20, the repository bumped all Tailwind typography scale usages by +1 step (e.g., \`text-sm\`→\`text-base\`, \`text-base\`→\`text-lg\`, …, \`text-8xl\`→\`text-9xl\`). For long‑form content, default to \`prose-lg\`.
+- Do not use \`text-xs\` for body copy. Reserve \`text-sm\` only for non‑essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.
+- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or \`leading-relaxed\`/\`leading-7\` for body text where dense blocks appear.
+
+**1.6 Iconography & Imagery**
+
+- Decorative images: \`alt=""\` or \`aria-hidden="true"\`.
+- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.
+
+---
+
+## 2) Content Requirements (UX Writing)
+
+- Links say **what happens** (avoid “click here”).
+- Buttons start with verbs; avoid ambiguous labels.
+- Form labels are **visible**; placeholders are **not labels**.
+- Error messages: human + programmatic association; avoid color‑only.
+- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).
+- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).
+
+---
+
+## 3) Engineering Requirements (Web — Next.js/React)
+
+> Use and extend \`packages/lssm/libs/ui-kit-web\` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to \`ui-kit-web\` first.
+
+**3.1 Semantics & Landmarks**
+
+- Use native elements: \`<button>\`, \`<a href>\`, \`<label for>\`, \`<fieldset>\`, \`<legend>\`, \`<table>\`, etc.
+- Landmarks per page: \`header\`, \`nav\`, \`main\`, \`aside\`, \`footer\`. Provide a **Skip to main content** link.
+- Provide a **Route Announcer** (\`aria-live="polite"\`) and move focus to page **h1** after navigation.
+
+**3.2 Keyboard**
+
+- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.
+- Common bindings:
+  - Space/Enter → activate button; Enter on link;
+  - Esc closes dialogs/menus;
+  - Arrow keys for lists/menus/tablists with **roving tabindex**.
+
+**3.3 Focus Management**
+
+- On route change (Next.js), move focus to the page \`<h1>\` or container and announce via a live region.
+- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.
+- Don’t steal focus except after explicit user action.
+
+**3.4 Forms**
+
+- Each input has a \`<label>\` or \`aria-label\`. Group related inputs with \`<fieldset><legend>\`.
+- Associate errors via \`aria-describedby\` or inline IDs; announce with \`role="alert"\` (assertive only for critical).
+- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.
+
+**3.5 ARIA Usage**
+
+- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.
+- Ensure **name/role/value** are programmatically determinable.
+
+**3.6 Media**
+
+- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.
+- No auto‑playing audio. Auto‑playing video must be muted and pausable; provide controls.
+
+**3.7 Tables & Data**
+
+- Use \`<th scope>\` for headers; captions via \`<caption>\`; announce sorting via \`aria-sort\`.
+- Provide CSV/JSON export where charts are primary.
+
+**3.8 Performance & Robustness**
+
+- Avoid content shifts that move focus; reserve space or use skeletons.
+- Maintain accessible names through hydration/SSR; avoid \`dangerouslySetInnerHTML\` where possible.
+
+**3.9 Next.js specifics**
+
+- Use \`next/link\` for navigation; ensure links are **links**, not buttons.
+- \`next/image\` must include **alt** (empty if decorative).
+- Announce route changes with a **global live region** and shift focus to the new view.
+
+**3.10 Accessibility library integration**
+
+- Import \`@contractspec/lib.accessibility\` at app root. It auto-imports its \`styles.css\` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:
+
+\`\`\`tsx
+// app/layout.tsx
+import '@contractspec/lib.accessibility'; // includes tokens and provider exports
+// or if needed: import '@contractspec/lib.accessibility/src/styles.css';
+\`\`\`
+
+- Wrap the app with \`AccessibilityProvider\` and include an element with \`id="main"\` for the skip link target.
+
+---
+
+## 3b) lssm/ui-kit-web — Component Patterns & Defaults
+
+> Source: \`packages/lssm/libs/ui-kit-web/ui/*\`
+
+- **Button/Input/Textarea**: Built‑in \`focus-visible\` rings; ensure visible labels via \`FormLabel\` or \`aria-label\`.
+- **Form** (\`form.tsx\`): \`FormControl\` wires \`aria-invalid\` and \`aria-describedby\` to \`FormMessage\` and \`FormDescription\`. Prefer \`FormMessage\` for inline errors. Add \`role="alert"\` only for critical.
+- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus‑trap and return‑focus. Provide \`DialogTitle\` + \`DialogDescription\` for name/description.
+- **Select/Combobox**: Prefer \`SelectTrigger\` with visible label; for icon‑only triggers, supply \`aria-label\`. Document examples in each app.
+- **Tabs**: Use \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`; names are programmatically determinable.
+- **Toast/Toaster**: Prefer non‑blocking announcements; map critical to assertive region; include action buttons with clear labels.
+- **Table**: Use \`TableCaption\`; ensure \`TableHead\` cells use proper \`scope\`. Provide \`aria-sort\` on sortable headers.
+- **Utilities to add (repo action)**:
+  - \`SkipLink\` component and pattern in layouts.
+  - \`RouteAnnouncer\` (\`aria-live="polite"\`) and **FocusOnRouteChange** helper.
+  - \`VisuallyHidden\` wrapper (Radix visually-hidden or minimal utility).
+  - \`useReducedMotion\` helper; honor in animated components.
+  - Touch‑size variants (≥44×44) for interactive atoms.
+
+---
+
+## 4) Engineering Requirements (Mobile — Expo/React Native)
+
+- Set \`accessibilityLabel\`, \`accessibilityHint\`, and \`accessibilityRole\` on touchables.
+- Ensure **hit slop** / min size **≥ 44×44 dp**.
+- Support Dynamic Type / font scaling; no clipped text at **200%**.
+- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.
+- Group related items with \`accessibilityElements\` ordering; hide decoration with \`accessible={false}\` or \`importantForAccessibility="no-hide-descendants"\` when appropriate.
+- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.
+
+---
+
+## 5) Component Patterns (Acceptance Rules)
+
+**Buttons & Links**
+
+- Use \`<button>\` for actions, \`<a href>\` for navigation. Provide disabled states that are perceivable beyond color.
+
+**Navigation**
+
+- Provide **Skip link**. One primary nav landmark. Indicate current page (\`aria-current="page"\`).
+
+**Menus/Combobox/Autocomplete**
+
+- Follow ARIA patterns: focus moves into list; \`aria-expanded\`, \`aria-controls\`, \`aria-activedescendant\` when applicable; Esc closes; typing filters.
+
+**Modals/Dialogs**
+
+- \`role="dialog"\` or \`alertdialog\` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.
+
+**Tabs**
+
+- \`role="tablist"\`; tabs are in the tab order; arrow keys switch focus; content is \`role="tabpanel"\` with \`aria-labelledby\`.
+
+**Toasts/Notifications**
+
+- Non-critical: \`aria-live="polite"\`; critical: \`role="alert"\` sparingly.
+
+**Infinite Scroll / “Load More”**
+
+- Provide **Load more** control; announce new content to SR; preserve keyboard position.
+
+**Drag & Drop (2.5.7)**
+
+- Provide **non‑drag** alternative (e.g., move up/down buttons).
+
+**Charts & Maps**
+
+- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.
+
+---
+
+## 6) Testing & CI (Blocking Gates)
+
+**Static & Unit**
+
+- \`eslint-plugin-jsx-a11y\` — error on violations.
+- \`jest-axe\` — unit tests for components.
+
+**Automated Integration**
+
+- \`axe-core\` via Playwright or Cypress on critical flows.
+- \`pa11y-ci\` on key routes; threshold: **0 Critical / 0 Serious** to merge.
+- Lighthouse CI a11y score **≥ 95** on target pages.
+
+**Manual QA (per release)**
+
+- **Keyboard patrol:** navigate primary flows without mouse.
+- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.
+- **Zoom & Reflow:** 200–400% & 320 px width.
+- **Color/Contrast check:** tokens in both themes.
+
+**Reporting**
+
+- A11y issues labeled: \`a11y-blocker\`, \`a11y-bug\`, \`a11y-enhancement\` with WCAG ref.
+
+---
+
+## 7) Repository‑Specific Adoption Plan
+
+- Centralize UI usage on \`packages/lssm/libs/ui-kit-web\` and de‑duplicate per‑app \`components/ui\` where feasible.
+- Introduce \`SkipLink\`, \`RouteAnnouncer\`, \`FocusOnRouteChange\`, and \`VisuallyHidden\` in \`ui-kit-web\`. Adopt in app layouts (\`app/layout.tsx\`) first.
+- Add \`useReducedMotion\` and wire into animated components (e.g., \`drawer\`, \`tooltip\`, \`carousel\`).
+- Add touch‑size variants to \`Button\`, \`IconButton\`, \`TabsTrigger\`, toggles.
+- Document Select label patterns and error association in Forms.
+
+---
+
+## 8) Code Snippets
+
+**Skip Link**
+
+\`\`\`html
+<a
+  class="sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2"
+  href="#main"
+  >Skip to main content</a
+>
+<main id="main">…</main>
+\`\`\`
+
+**Dialog (Radix + shadcn/ui) — essentials**
+
+\`\`\`tsx
+// Ensure label, description, focus trap, and return focus on close remain intact
+<Dialog>
+  <DialogTrigger asChild>
+    <button aria-haspopup="dialog">Open settings</button>
+  </DialogTrigger>
+  <DialogContent aria-describedby="settings-desc">
+    <DialogTitle>Settings</DialogTitle>
+    <p id="settings-desc">Update your preferences.</p>
+    <DialogClose asChild>
+      <button>Close</button>
+    </DialogClose>
+  </DialogContent>
+</Dialog>
+\`\`\`
+
+**Form error association**
+
+\`\`\`tsx
+<label htmlFor="email">Email</label>
+<input id="email" name="email" type="email" aria-describedby="email-err" />
+<p id="email-err" role="alert">Enter a valid email.</p>
+\`\`\`
+
+**Route change announcement (Next.js)**
+
+\`\`\`tsx
+// Add once at app root
+<div
+  aria-live="polite"
+  aria-atomic="true"
+  id="route-announcer"
+  className="sr-only"
+/>
+\`\`\`
+
+---
+
+## 9) Exceptions & Waivers
+
+- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**
+
+---
+
+## 10) Ownership
+
+- **Design:** maintains token contrast, component specs.
+- **Engineering:** enforces CI gates, implements patterns.
+- **QA:** runs manual checks per release.
+- **PM:** blocks release if AA not met on user‑visible flows.
+
+---
+
+## 11) References (internalize; no external dependency at runtime)
+
+- WCAG 2.2 (AA), EN 301 549. ARIA Authoring Practices. Platform HIG (Apple, Material).
+- \`packages/lssm/libs/ui-kit-web\` as the canonical UI source for web.
+
+> **Bottom line:** Shipping means **accessible by default**. We don’t trade a11y for speed; we bake it into speed.
+
+---
+
+## 12) Adoption Status (2025-09-23)
+
+- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.
+- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.
+- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to \`Section\`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role="alert" where critical.
+
+> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.
+
+---
+
+## 13) CI Hardening & Visual QA
+
+- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.
+- Unit: Run jest-axe for ui-kit-web and app-level components.
+- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).
+- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).
+- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.
+- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.
+
+### Recent additions (2025-09-26)
+
+- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with \`aria-controls\`, \`aria-activedescendant\`, \`Escape\`/\`Tab\` handling, and labelled listbox.
+- Cypress a11y tests added for furniture and incidents modules on \`/modules\` and operators flows; checks run axe with critical/serious impacts.
+
+## 14) Accessibility Telemetry (PostHog)
+
+- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.
+- Properties: app, route, previous_value, new_value, timestamp.
+- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.
+- Privacy: No PII; aggregate only.
+`
+  }
+];
+registerDocBlocks(accessibility_wcag_compliance_specs_DocBlocks);
+
+// src/docs/constants.ts
+var DOCS_DOMAIN = "docs";
+var DOCS_OWNERS = ["docs-platform"];
+var DOCS_TAGS = ["docs", "documentation"];
+var DOCS_STABILITY = StabilityEnum.Experimental;
+
+// src/docs/capabilities/documentationSystem.capability.ts
+var DocumentationSystemCapability = defineCapability({
+  meta: {
+    key: "docs.system",
+    version: "1.0.0",
+    kind: "ui",
+    title: "Documentation System",
+    description: "End-to-end docs generation, indexing, and presentation.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "system"],
+    stability: DOCS_STABILITY
+  },
+  provides: [
+    {
+      surface: "operation",
+      key: "docs.generate",
+      version: "1.0.0",
+      description: "Generate documentation artifacts."
+    },
+    {
+      surface: "operation",
+      key: "docs.publish",
+      version: "1.0.0",
+      description: "Publish documentation artifacts."
+    },
+    {
+      surface: "operation",
+      key: "docs.search",
+      version: "1.0.0",
+      description: "Index and search DocBlocks."
+    },
+    {
+      surface: "operation",
+      key: "docs.contract.reference",
+      version: "1.0.0",
+      description: "Resolve contract references for docs."
+    },
+    {
+      surface: "event",
+      key: "docs.generated",
+      version: "1.0.0",
+      description: "Docs generation completed."
+    },
+    {
+      surface: "event",
+      key: "docs.published",
+      version: "1.0.0",
+      description: "Docs publish completed."
+    },
+    {
+      surface: "presentation",
+      key: "docs.layout",
+      version: "1.0.0",
+      description: "Docs layout presentation."
+    },
+    {
+      surface: "presentation",
+      key: "docs.reference.page",
+      version: "1.0.0",
+      description: "Docs reference page presentation."
+    }
+  ]
+});
+// src/docs/tech/docs-system.docblock.ts
+var docsSystemDocBlocks = [
+  {
+    id: "docs.tech.docs-system",
+    title: "Docs system overview",
+    summary: "How ContractSpec generates, indexes, and presents documentation.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/system",
+    tags: ["docs", "system", "contracts"],
+    body: `# Docs system overview
+
+ContractSpec treats documentation as a first-class output of your specs. The docs system combines:
+
+- Contract operations and schemas
+- DocBlocks (goal/how/usage/reference)
+- Presentations for rendering
+
+The result is a consistent docs surface across CLI, web, and MCP.
+
+## Key surfaces
+
+- Generation: \`docs.generate\`
+- Index/search: \`docs.search\`
+- Contract reference: \`docs.contract.reference\`
+- Publish: \`docs.publish\`
+`
+  },
+  {
+    id: "docs.tech.docs-generator",
+    title: "Docs generator",
+    summary: "Generate reference docs and metadata from ContractSpecs.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/docs/generator",
+    tags: ["docs", "generator", "cli"],
+    body: `# Docs generator
+
+The generator produces documentation artifacts from registered ContractSpecs and DocBlocks.
+
+## Outputs
+
+- Reference pages for operations, events, forms, data views, and presentations
+- Search index metadata (DocBlocks + routes)
+- Contract schemas rendered to markdown or JSON
+`
+  },
+  {
+    id: "docs.tech.docs-search",
+    title: "Docs index and search",
+    summary: "Search DocBlocks by query, tag, kind, or visibility.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/search",
+    tags: ["docs", "search"],
+    body: `# Docs index and search
+
+The docs index is the canonical list of DocBlocks exposed to UI and MCP surfaces.
+
+## Query
+
+- Operation: \`docs.search\`
+- Filters: query, tag, kind, visibility
+`
+  },
+  {
+    id: "docs.tech.docs-reference",
+    title: "Contract reference pages",
+    summary: "Resolve any spec into a docs-ready reference payload.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/reference",
+    tags: ["docs", "reference"],
+    body: `# Contract reference
+
+Contract reference pages are generated from spec metadata plus schema details.
+
+## Query
+
+- Operation: \`docs.contract.reference\`
+`
+  },
+  {
+    id: "docs.tech.docs-publish",
+    title: "Docs publish",
+    summary: "Publish generated artifacts to the docs host.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/docs/publish",
+    tags: ["docs", "publish"],
+    body: `# Docs publish
+
+Publishing moves generated artifacts to a hosting target with versioning.
+
+## Command
+
+- Operation: \`docs.publish\`
+`
+  },
+  {
+    id: "docs.tech.docs-examples",
+    title: "Examples catalog",
+    summary: "Document and surface example projects with sandbox support.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/examples",
+    tags: ["docs", "examples"],
+    body: `# Examples catalog
+
+Examples are registered as ExampleSpecs and surface DocBlocks for discovery.
+
+- Docs index tags should include \`examples\` to populate the catalog.
+- Sandbox support is available under \`/sandbox\`.
+`
+  }
+];
+registerDocBlocks(docsSystemDocBlocks);
+// src/docs/events/docsGenerated.event.ts
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var DocsGeneratedPayload = new SchemaModel({
+  name: "DocsGeneratedPayload",
+  fields: {
+    buildId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    generatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    outputDir: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    artifactCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    warnings: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    }
+  }
+});
+var DocsGeneratedEvent = defineEvent({
+  meta: {
+    key: "docs.generated",
+    version: "1.0.0",
+    description: "Emitted when documentation artifacts are generated.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "generation"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-generator")]
+  },
+  payload: DocsGeneratedPayload
+});
+
+// src/docs/commands/docsGenerate.command.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, SchemaModel as SchemaModel2 } from "@contractspec/lib.schema";
+var DocsArtifactModel = new SchemaModel2({
+  name: "DocsArtifact",
+  fields: {
+    path: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    format: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    bytes: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var DocsGenerateInput = new SchemaModel2({
+  name: "DocsGenerateInput",
+  fields: {
+    workspaceRoot: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    outputDir: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    version: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    formats: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    includeInternal: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    includeExperimental: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    contractFilter: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    docblockFilter: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    dryRun: { type: ScalarTypeEnum2.Boolean(), isOptional: true }
+  }
+});
+var DocsGenerateOutput = new SchemaModel2({
+  name: "DocsGenerateOutput",
+  fields: {
+    buildId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    generatedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    outputDir: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    artifacts: { type: DocsArtifactModel, isOptional: true, isArray: true },
+    warnings: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    }
+  }
+});
+var DocsGenerateCommand = defineCommand({
+  meta: {
+    key: "docs.generate",
+    title: "Generate Documentation",
+    version: "1.0.0",
+    description: "Generate documentation artifacts from ContractSpecs.",
+    goal: "Produce up-to-date reference docs and guides from specs and DocBlocks.",
+    context: "Used by CLI and CI to keep docs in sync with contract definitions.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "generation"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-generator")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  io: {
+    input: DocsGenerateInput,
+    output: DocsGenerateOutput,
+    errors: {
+      OUTPUT_WRITE_FAILED: {
+        description: "Failed to write generated docs output.",
+        http: 500,
+        when: "The generator cannot persist artifacts to the output path."
+      }
+    }
+  },
+  policy: {
+    auth: "admin",
+    pii: []
+  },
+  sideEffects: {
+    emits: [
+      {
+        ref: DocsGeneratedEvent.meta,
+        when: "Docs generation completes successfully."
+      }
+    ]
+  }
+});
+
+// src/docs/events/docsPublished.event.ts
+import { SchemaModel as SchemaModel3, ScalarTypeEnum as ScalarTypeEnum3 } from "@contractspec/lib.schema";
+var DocsPublishedPayload = new SchemaModel3({
+  name: "DocsPublishedPayload",
+  fields: {
+    publishId: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
+    environment: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
+    url: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
+    publishedAt: { type: ScalarTypeEnum3.DateTime(), isOptional: false },
+    status: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
+    warnings: {
+      type: ScalarTypeEnum3.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    }
+  }
+});
+var DocsPublishedEvent = defineEvent({
+  meta: {
+    key: "docs.published",
+    version: "1.0.0",
+    description: "Emitted when documentation is published.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "publish"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-publish")]
+  },
+  payload: DocsPublishedPayload
+});
+
+// src/docs/commands/docsPublish.command.ts
+import { ScalarTypeEnum as ScalarTypeEnum4, SchemaModel as SchemaModel4 } from "@contractspec/lib.schema";
+var DocsPublishInput = new SchemaModel4({
+  name: "DocsPublishInput",
+  fields: {
+    buildId: { type: ScalarTypeEnum4.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true },
+    environment: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true },
+    deployTarget: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true },
+    artifactPath: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true },
+    dryRun: { type: ScalarTypeEnum4.Boolean(), isOptional: true },
+    notes: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true }
+  }
+});
+var DocsPublishOutput = new SchemaModel4({
+  name: "DocsPublishOutput",
+  fields: {
+    publishId: { type: ScalarTypeEnum4.String_unsecure(), isOptional: false },
+    publishedAt: { type: ScalarTypeEnum4.DateTime(), isOptional: false },
+    url: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true },
+    status: { type: ScalarTypeEnum4.String_unsecure(), isOptional: true },
+    warnings: {
+      type: ScalarTypeEnum4.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    }
+  }
+});
+var DocsPublishCommand = defineCommand({
+  meta: {
+    key: "docs.publish",
+    title: "Publish Documentation",
+    version: "1.0.0",
+    description: "Publish generated documentation artifacts.",
+    goal: "Deploy docs to the public docs surface with consistent versioning.",
+    context: "Used by release pipelines to push generated docs to hosting targets.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "publish"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-publish")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  io: {
+    input: DocsPublishInput,
+    output: DocsPublishOutput,
+    errors: {
+      DEPLOY_FAILED: {
+        description: "Failed to deploy documentation artifacts.",
+        http: 500,
+        when: "The docs publish step fails to deploy to the target host."
+      }
+    }
+  },
+  policy: {
+    auth: "admin",
+    pii: []
+  },
+  sideEffects: {
+    emits: [
+      {
+        ref: DocsPublishedEvent.meta,
+        when: "Docs publish completes successfully."
+      }
+    ]
+  }
+});
+// src/docs/queries/docsIndex.query.ts
+import { ScalarTypeEnum as ScalarTypeEnum5, SchemaModel as SchemaModel5 } from "@contractspec/lib.schema";
+var DocSummaryModel = new SchemaModel5({
+  name: "DocSummary",
+  fields: {
+    id: { type: ScalarTypeEnum5.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum5.String_unsecure(), isOptional: false },
+    summary: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    route: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    visibility: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    version: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum5.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    }
+  }
+});
+var DocsIndexInput = new SchemaModel5({
+  name: "DocsIndexInput",
+  fields: {
+    query: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    tag: {
+      type: ScalarTypeEnum5.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    visibility: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum5.String_unsecure(), isOptional: true },
+    limit: { type: ScalarTypeEnum5.Int_unsecure(), isOptional: true },
+    offset: { type: ScalarTypeEnum5.Int_unsecure(), isOptional: true }
+  }
+});
+var DocsIndexOutput = new SchemaModel5({
+  name: "DocsIndexOutput",
+  fields: {
+    items: { type: DocSummaryModel, isOptional: true, isArray: true },
+    docs: { type: DocSummaryModel, isOptional: false, isArray: true },
+    total: { type: ScalarTypeEnum5.Int_unsecure(), isOptional: true },
+    nextOffset: { type: ScalarTypeEnum5.Int_unsecure(), isOptional: true }
+  }
+});
+var DocsIndexQuery = defineQuery({
+  meta: {
+    key: "docs.search",
+    title: "Docs Index",
+    version: "1.0.0",
+    description: "Search and filter DocBlocks by query, tag, or visibility.",
+    goal: "Provide a consistent index of documentation entries for UI and MCP.",
+    context: "Used by docs surfaces to list and filter DocBlocks without coupling to storage.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "search", "index"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-search")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  io: {
+    input: DocsIndexInput,
+    output: DocsIndexOutput
+  },
+  policy: {
+    auth: "anonymous",
+    pii: []
+  }
+});
+
+// src/docs/queries/contractReference.query.ts
+import { ScalarTypeEnum as ScalarTypeEnum6, SchemaModel as SchemaModel6 } from "@contractspec/lib.schema";
+var ContractReferenceInput = new SchemaModel6({
+  name: "ContractReferenceInput",
+  fields: {
+    key: { type: ScalarTypeEnum6.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    type: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    format: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    includeSchema: { type: ScalarTypeEnum6.Boolean(), isOptional: true }
+  }
+});
+var ContractReferenceModel = new SchemaModel6({
+  name: "ContractReference",
+  fields: {
+    key: { type: ScalarTypeEnum6.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum6.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum6.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    markdown: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    route: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true },
+    schema: { type: ScalarTypeEnum6.JSONObject(), isOptional: true },
+    policy: { type: ScalarTypeEnum6.JSONObject(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum6.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    owners: {
+      type: ScalarTypeEnum6.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    stability: { type: ScalarTypeEnum6.String_unsecure(), isOptional: true }
+  }
+});
+var ContractReferenceOutput = new SchemaModel6({
+  name: "ContractReferenceOutput",
+  fields: {
+    reference: { type: ContractReferenceModel, isOptional: false }
+  }
+});
+var ContractReferenceQuery = defineQuery({
+  meta: {
+    key: "docs.contract.reference",
+    title: "Contract Reference",
+    version: "1.0.0",
+    description: "Resolve a contract into a documentation-ready reference.",
+    goal: "Expose a canonical reference view for any ContractSpec surface.",
+    context: "Used by docs generators and UI to render consistent reference pages.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "reference"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-reference")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  io: {
+    input: ContractReferenceInput,
+    output: ContractReferenceOutput
+  },
+  policy: {
+    auth: "anonymous",
+    pii: []
+  }
+});
+// src/presentations/presentations.ts
+var definePresentation = (spec) => {
+  return spec;
+};
+
+// src/presentations/registry.ts
+class PresentationRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("presentation", items);
+  }
+}
+// src/docs/presentations/docsLayout.presentation.ts
+var DocsLayoutPresentation = definePresentation({
+  meta: {
+    key: "docs.layout",
+    title: "Docs Layout",
+    version: "1.0.0",
+    description: "Shared layout shell for documentation pages.",
+    goal: "Provide consistent navigation, layout, and docs UI scaffolding.",
+    context: "Used by web docs surfaces to render DocBlock-based content.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "layout"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-system")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  source: {
+    type: "component",
+    framework: "react",
+    componentKey: "docsLayout"
+  },
+  targets: ["react"]
+});
+
+// src/docs/presentations/docsReferencePage.presentation.ts
+var DocsReferencePagePresentation = definePresentation({
+  meta: {
+    key: "docs.reference.page",
+    title: "Docs Reference Page",
+    version: "1.0.0",
+    description: "Reference page layout for contract documentation.",
+    goal: "Render contract references with consistent metadata and formatting.",
+    context: "Used by docs surfaces to present contract reference content and schemas.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "reference"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-reference")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  source: {
+    type: "component",
+    framework: "react",
+    componentKey: "docsReferencePage"
+  },
+  targets: ["react", "markdown"]
+});
+// src/forms/forms.ts
+import { compareVersions as compareVersions3 } from "compare-versions";
+function formKey(meta) {
+  return `${meta.key}.v${meta.version}`;
+}
+
+class FormRegistry {
+  items = new Map;
+  register(spec) {
+    const key = formKey(spec.meta);
+    if (this.items.has(key))
+      throw new Error(`Duplicate form ${key}`);
+    this.items.set(key, spec);
+    return this;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, v] of this.items.entries()) {
+      if (v.meta.key !== key)
+        continue;
+      if (!candidate || compareVersions3(v.meta.version, candidate.meta.version) > 0) {
+        candidate = v;
+      }
+    }
+    return candidate;
+  }
+  filter(criteria) {
+    const { filterBy: filterBy2 } = (init_registry_utils(), __toCommonJS(exports_registry_utils));
+    return filterBy2(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((f) => f.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((f) => f.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    const { groupBy: groupBy2 } = (init_registry_utils(), __toCommonJS(exports_registry_utils));
+    return groupBy2(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    const { getUniqueTags: getUniqueTags2 } = (init_registry_utils(), __toCommonJS(exports_registry_utils));
+    return getUniqueTags2(this.list());
+  }
+}
+function getAtPath(values, path) {
+  if (!path)
+    return;
+  const segs = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  let cur = values;
+  for (const s of segs) {
+    if (cur == null)
+      return;
+    if (cur && typeof cur === "object" && s in cur) {
+      cur = cur[s];
+    } else {
+      return;
+    }
+  }
+  return cur;
+}
+function evalPredicate(values, pred) {
+  if (!pred)
+    return true;
+  if (pred.not)
+    return !evalPredicate(values, pred.not);
+  if (pred.all && pred.all.length)
+    return pred.all.every((p) => evalPredicate(values, p));
+  if (pred.anyOf && pred.anyOf.length)
+    return pred.anyOf.some((p) => evalPredicate(values, p));
+  if (pred.when) {
+    const { path, op = "truthy", value } = pred.when;
+    const v = getAtPath(values, path);
+    switch (op) {
+      case "equals":
+        return v === value;
+      case "notEquals":
+        return v !== value;
+      case "in":
+        return Array.isArray(value) && value.includes(v);
+      case "notIn":
+        return Array.isArray(value) && !value.includes(v);
+      case "gt":
+        return Number(v) > Number(value);
+      case "gte":
+        return Number(v) >= Number(value);
+      case "lt":
+        return Number(v) < Number(value);
+      case "lte":
+        return Number(v) <= Number(value);
+      case "empty":
+        return v == null || (Array.isArray(v) ? v.length === 0 : String(v).length === 0);
+      case "lengthGt":
+        return (Array.isArray(v) || typeof v === "string") && v.length > Number(value ?? 0);
+      case "lengthGte":
+        return (Array.isArray(v) || typeof v === "string") && v.length >= Number(value ?? 0);
+      case "lengthLt":
+        return (Array.isArray(v) || typeof v === "string") && v.length < Number(value ?? 0);
+      case "lengthLte":
+        return (Array.isArray(v) || typeof v === "string") && v.length <= Number(value ?? 0);
+      case "truthy":
+      default:
+        return Boolean(v);
+    }
+  }
+  return true;
+}
+function buildZodWithRelations(spec, handlers) {
+  const base = spec.model.getZod();
+  return base.superRefine((values, ctx) => {
+    const visit = (field, parentPath) => {
+      const path = field.name ? parentPath ? `${parentPath}.${field.name}` : field.name : parentPath ?? "";
+      if (field.requiredWhen) {
+        const should = evalPredicate(values, field.requiredWhen);
+        if (should) {
+          const v = getAtPath(values, path);
+          const empty = v == null || typeof v === "string" && v.trim().length === 0 || Array.isArray(v) && v.length === 0;
+          if (empty)
+            ctx.addIssue({
+              code: "custom",
+              path: path.split("."),
+              message: "required"
+            });
+        }
+      }
+      if (field.kind === "array") {
+        const arr = getAtPath(values, path);
+        if (field.min != null && Array.isArray(arr) && arr.length < field.min) {
+          ctx.addIssue({
+            code: "custom",
+            path: path.split("."),
+            message: `min:${field.min}`
+          });
+        }
+        if (field.max != null && Array.isArray(arr) && arr.length > field.max) {
+          ctx.addIssue({
+            code: "custom",
+            path: path.split("."),
+            message: `max:${field.max}`
+          });
+        }
+        visit(field.of, path);
+      } else if (field.kind === "group") {
+        for (const child of field.fields)
+          visit(child, path);
+      }
+    };
+    for (const f of spec.fields)
+      visit(f);
+    if (spec.constraints && handlers) {
+      for (const c of spec.constraints) {
+        const fn = handlers[c.key];
+        if (!fn)
+          continue;
+        const res = fn(values, c.paths, c.args);
+        if (!res.ok) {
+          ctx.addIssue({
+            code: "custom",
+            path: (res.path ?? c.paths[0] ?? "").split(".").filter(Boolean),
+            message: res.message ?? c.messageI18n
+          });
+        }
+      }
+    }
+  });
+}
+function defineFormSpec(spec) {
+  return spec;
+}
+
+// src/docs/forms/docsSearch.form.ts
+import { SchemaModel as SchemaModel7, ScalarTypeEnum as ScalarTypeEnum7 } from "@contractspec/lib.schema";
+var DocsSearchFormModel = new SchemaModel7({
+  name: "DocsSearchFormModel",
+  fields: {
+    query: { type: ScalarTypeEnum7.String_unsecure(), isOptional: true },
+    visibility: { type: ScalarTypeEnum7.String_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum7.String_unsecure(), isOptional: true }
+  }
+});
+var DocsSearchForm = defineFormSpec({
+  meta: {
+    key: "docs.search.form",
+    title: "Docs Search",
+    version: "1.0.0",
+    description: "Search form for documentation discovery.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "search"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-search")]
+  },
+  model: DocsSearchFormModel,
+  fields: [
+    {
+      kind: "text",
+      name: "query",
+      labelI18n: "Search",
+      placeholderI18n: "Search docs"
+    },
+    {
+      kind: "select",
+      name: "visibility",
+      labelI18n: "Visibility",
+      options: {
+        kind: "static",
+        options: [
+          { labelI18n: "Public", value: "public" },
+          { labelI18n: "Internal", value: "internal" },
+          { labelI18n: "Mixed", value: "mixed" }
+        ]
+      }
+    },
+    {
+      kind: "select",
+      name: "kind",
+      labelI18n: "Kind",
+      options: {
+        kind: "static",
+        options: [
+          { labelI18n: "Goal", value: "goal" },
+          { labelI18n: "How", value: "how" },
+          { labelI18n: "Usage", value: "usage" },
+          { labelI18n: "Reference", value: "reference" },
+          { labelI18n: "FAQ", value: "faq" },
+          { labelI18n: "Changelog", value: "changelog" }
+        ]
+      }
+    }
+  ],
+  actions: [
+    {
+      key: "search",
+      labelI18n: "Search"
+    }
+  ],
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+// src/docs/views/docsIndex.dataView.ts
+var DocsIndexDataView = defineDataView({
+  meta: {
+    key: "docs.index.view",
+    title: "Docs Index",
+    version: "1.0.0",
+    description: "List and filter documentation entries.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "index"],
+    stability: DOCS_STABILITY,
+    entity: "docs",
+    docId: [docId("docs.tech.docs-search")]
+  },
+  source: {
+    primary: {
+      key: DocsIndexQuery.meta.key,
+      version: DocsIndexQuery.meta.version
+    }
+  },
+  view: {
+    kind: "list",
+    fields: [
+      { key: "id", label: "ID", dataPath: "id" },
+      { key: "title", label: "Title", dataPath: "title" },
+      { key: "summary", label: "Summary", dataPath: "summary" },
+      { key: "route", label: "Route", dataPath: "route" },
+      { key: "tags", label: "Tags", dataPath: "tags", format: "badge" },
+      { key: "kind", label: "Kind", dataPath: "kind" },
+      { key: "visibility", label: "Visibility", dataPath: "visibility" }
+    ],
+    primaryField: "title",
+    secondaryFields: ["summary", "route"],
+    filters: [
+      { key: "query", label: "Search", field: "query", type: "search" },
+      {
+        key: "visibility",
+        label: "Visibility",
+        field: "visibility",
+        type: "enum",
+        options: [
+          { value: "public", label: "Public" },
+          { value: "internal", label: "Internal" },
+          { value: "mixed", label: "Mixed" }
+        ]
+      },
+      {
+        key: "kind",
+        label: "Kind",
+        field: "kind",
+        type: "enum",
+        options: [
+          { value: "goal", label: "Goal" },
+          { value: "how", label: "How" },
+          { value: "usage", label: "Usage" },
+          { value: "reference", label: "Reference" },
+          { value: "faq", label: "FAQ" },
+          { value: "changelog", label: "Changelog" }
+        ]
+      }
+    ]
+  },
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+
+// src/docs/views/contractReference.dataView.ts
+var ContractReferenceDataView = defineDataView({
+  meta: {
+    key: "docs.contract.reference.view",
+    title: "Contract Reference",
+    version: "1.0.0",
+    description: "Detail view for a single contract reference.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "reference"],
+    stability: DOCS_STABILITY,
+    entity: "contract-reference",
+    docId: [docId("docs.tech.docs-reference")]
+  },
+  source: {
+    primary: {
+      key: ContractReferenceQuery.meta.key,
+      version: ContractReferenceQuery.meta.version
+    }
+  },
+  view: {
+    kind: "detail",
+    fields: [
+      {
+        key: "key",
+        label: "Key",
+        dataPath: "reference.key"
+      },
+      {
+        key: "version",
+        label: "Version",
+        dataPath: "reference.version"
+      },
+      {
+        key: "type",
+        label: "Type",
+        dataPath: "reference.type"
+      },
+      {
+        key: "title",
+        label: "Title",
+        dataPath: "reference.title"
+      },
+      {
+        key: "description",
+        label: "Description",
+        dataPath: "reference.description",
+        format: "markdown"
+      },
+      {
+        key: "tags",
+        label: "Tags",
+        dataPath: "reference.tags"
+      },
+      {
+        key: "owners",
+        label: "Owners",
+        dataPath: "reference.owners"
+      },
+      {
+        key: "stability",
+        label: "Stability",
+        dataPath: "reference.stability"
+      }
+    ],
+    primaryField: "title",
+    secondaryFields: ["description"]
+  },
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+
+// src/docs/views/exampleCatalog.dataView.ts
+var ExampleCatalogDataView = defineDataView({
+  meta: {
+    key: "docs.examples.catalog.view",
+    title: "Examples Catalog",
+    version: "1.0.0",
+    description: "Catalog view of ContractSpec examples and demos.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "examples"],
+    stability: DOCS_STABILITY,
+    entity: "docs-examples",
+    docId: [docId("docs.tech.docs-examples")]
+  },
+  source: {
+    primary: {
+      key: DocsIndexQuery.meta.key,
+      version: DocsIndexQuery.meta.version
+    }
+  },
+  view: {
+    kind: "grid",
+    fields: [
+      { key: "id", label: "ID", dataPath: "id" },
+      { key: "title", label: "Title", dataPath: "title" },
+      { key: "summary", label: "Summary", dataPath: "summary" },
+      { key: "route", label: "Route", dataPath: "route" },
+      { key: "tags", label: "Tags", dataPath: "tags", format: "badge" }
+    ],
+    primaryField: "title",
+    secondaryFields: ["summary"],
+    filters: [
+      { key: "query", label: "Search", field: "query", type: "search" },
+      {
+        key: "tags",
+        label: "Tags",
+        field: "tag",
+        type: "enum",
+        options: [
+          { value: "examples", label: "Examples" },
+          { value: "templates", label: "Templates" },
+          { value: "sandbox", label: "Sandbox" }
+        ]
+      }
+    ]
+  },
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+// src/docs/contracts.ts
+var docsOperationContracts = {
+  DocsIndexQuery,
+  ContractReferenceQuery,
+  DocsGenerateCommand,
+  DocsPublishCommand
+};
+var docsEventContracts = {
+  DocsGeneratedEvent,
+  DocsPublishedEvent
+};
+var docsPresentationContracts = {
+  DocsLayoutPresentation,
+  DocsReferencePagePresentation
+};
+var docsFormContracts = {
+  DocsSearchForm
+};
+var docsDataViewContracts = {
+  DocsIndexDataView,
+  ContractReferenceDataView,
+  ExampleCatalogDataView
+};
+function registerDocsOperations(registry3) {
+  return registry3.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
+}
+function registerDocsEvents(registry3) {
+  return registry3.register(DocsGeneratedEvent).register(DocsPublishedEvent);
+}
+function registerDocsPresentations(registry3) {
+  return registry3.register(DocsLayoutPresentation).register(DocsReferencePagePresentation);
+}
+function registerDocsForms(registry3) {
+  return registry3.register(DocsSearchForm);
+}
+function registerDocsDataViews(registry3) {
+  return registry3.register(DocsIndexDataView).register(ContractReferenceDataView).register(ExampleCatalogDataView);
+}
+// src/docs/tech-contracts.docs.ts
+var techContractsDocs = [
+  {
+    id: "docs.tech.contracts.presentations",
+    title: "Presentations — Unified Descriptor & Transform Engine",
+    summary: "How PresentationSpec and TransformEngine keep docs/renderers consistent.",
+    visibility: "public",
+    route: "/docs/tech/contracts/presentations",
+    kind: "reference",
+    tags: ["presentations", "docs", "mcp"],
+    body: `## Presentations V2 — Unified Descriptor & Transform Engine
+
+### Purpose
+
+Unify presentations into one descriptor (\`PresentationSpec\`) that declares a single source (React component key or BlockNote doc) and a list of output targets (react, markdown, application/json, application/xml). A pluggable \`TransformEngine\` renders any target and applies PII redaction.
+
+### Types
+
+\`\`\`ts
+type PresentationTarget =
+  | 'react'
+  | 'markdown'
+  | 'application/json'
+  | 'application/xml';
+
+type PresentationSource =
+  | {
+      type: 'component';
+      framework: 'react';
+      componentKey: string;
+      props?: AnySchemaModel;
+    }
+  | { type: 'blocknotejs'; docJson: unknown; blockConfig?: unknown };
+
+interface PresentationSpec {
+  meta: PresentationMeta; // includes partial OwnerShipMeta + description
+  policy?: { flags?: string[]; pii?: string[] };
+  source: PresentationSource;
+  targets: PresentationTarget[];
+}
+
+// Shared ownership schema (source of truth in @contractspec/lib.contracts-spec/src/ownership.ts)
+interface OwnerShipMeta {
+  title: string;
+  description: string;
+  domain: string;
+  owners: Owner[];
+  tags: Tag[];
+  stability: Stability;
+}
+
+type Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';
+type Owner = string; // curated list available in code (e.g., '@sigil-team', 'team-strit')
+type Tag = string; // curated list available in code (e.g., 'auth', 'spots')
+
+// For presentations, meta is a Partial<OwnerShipMeta> plus description, name, version
+interface PresentationMeta extends Partial<OwnerShipMeta> {
+  name: string;
+  version: string;
+  description?: string;
+}
+\`\`\`
+
+### Engine
+
+Use \`createDefaultTransformEngine()\` and register custom renderers as needed (e.g., high-fidelity BlockNote → Markdown). The default engine supports markdown/json/xml; a React renderer returns a serializable descriptor the host app renders via a \`componentMap\` or a BlockNote renderer. The canonical source type string is \`blocknotejs\` (not \`blocknote\`).
+
+PII paths (JSON-like) are redacted from rendered outputs.
+
+### MCP Integration
+
+\`createMcpServer\` accepts \`presentationsV2\`. Each descriptor is exposed under \`presentation://<name>/v<version>\` and negotiated variants (\`.md/.json/.xml\`) are rendered by the engine.
+
+### Migration
+
+- V1 \`PresentationSpec\` remains supported; a back-compat helper converts V1 → V2 when convenient.
+- Prefer V2 for new work.
+
+### Examples (Sigil)
+
+- \`sigil.auth.webauth_tabs_v2\`: component source (\`componentKey: 'sigil.webauth.tabs'\`), targets \`react/json/xml\`.
+- \`sigil.signup.guide_v2\`: BlockNote doc source, targets \`react/markdown/json/xml\`.
+
+### React Rendering
+
+Host apps use a \`componentMap\` (e.g., \`'sigil.webauth.tabs' → WebAuthTabs\`) and a BlockNote renderer to turn the React render descriptor into elements.`
+  }
+];
+registerDocBlocks(techContractsDocs);
+
+// src/docs/meta.docs.ts
+var metaDocs = [
+  {
+    id: "docs.meta.docblocks-process",
+    title: "DocBlocks process",
+    summary: "How to author goal/how/usage DocBlocks close to code.",
+    kind: "reference",
+    visibility: "mixed",
+    route: "/docs/meta/docblocks-process",
+    tags: ["docs", "process"],
+    body: `## DocBlocks authoring rules
+
+- Colocate docs beside implementation; avoid barrel /docs folders.
+- Split intent:
+  - **goal**: why this exists (before implementation).
+  - **how**: operational/runbook steps.
+  - **usage**: quick checklist for consumers.
+- Use \`visibility\`: public | internal | mixed.
+- Prefer routes like \`/docs/<domain>/<topic>/<kind>\`; ids mirror that.
+- Keep body Markdown LLM-friendly; avoid HTML.
+- Add owners/tags/domain/stability when known.
+- For presentations/markdown outputs, rely on TransformEngine via DocRegistry.
+- No sourcePath; DocBlocks are canonical.`
+  }
+];
+registerDocBlocks(metaDocs);
+
+// src/docs/tech/lifecycle-stage-system.docblock.ts
+var 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
+
+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.
+
+---
+
+### 1. Architecture Overview
+
+\`\`\`
+┌──────────────────────┐
+│ @contractspec/lib.lifecycle  │  Types, enums, helpers (pure data)
+└───────────┬──────────┘
+            │
+┌───────────▼──────────┐    ┌───────────────────────────┐
+│ modules/lifecycle-   │    │ modules/lifecycle-advisor  │
+│ core (detection)     │    │ (guidance & ceremonies)    │
+└───────────┬──────────┘    └───────────┬───────────────┘
+            │                           │
+            ├────────────┬──────────────┤
+            ▼            ▼              ▼
+  Adapters: analytics, intent, questionnaires
+            │
+┌───────────▼──────────┐
+│ bundles/lifecycle-   │  Managed service for Studio
+│ managed              │  (REST handlers, AI agent)     │
+└───────────┬──────────┘
+            │
+  ContractSpec Studio surfaces
+  (web/mobile APIs, CLI, docs)
+\`\`\`
+
+- **Libraries** provide shared vocabulary.
+- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.
+- **Bundles** compose modules, register agents/events, and expose APIs for Studio.
+- **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-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.
+
+---
+
+### 2. Core Library (\`@contractspec/lib.lifecycle\`)
+
+- Stage enum (0–6) with metadata (\`question\`, \`signals\`, \`traps\`).
+- Axes types (\`ProductPhase\`, \`CompanyPhase\`, \`CapitalPhase\`).
+- \`LifecycleSignal\` (source, metric, value, timestamp).
+- \`LifecycleMetricSnapshot\` (aggregated numbers).
+- \`LifecycleMilestone\`, \`LifecycleAction\`, \`LifecycleAssessment\` interfaces.
+- Utility helpers:
+  - \`formatStageSummary(stage, assessment)\`
+  - \`rankStageCandidates(scores)\`
+
+The library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.
+
+---
+
+### 3. Lifecycle Core Module
+
+**Location:** \`packages/modules/lifecycle-core/\`
+
+#### Components
+1. **StageSignalCollector**
+   - Accepts adapter interfaces:
+     - \`AnalyticsAdapter\` (pulls metrics from \`@contractspec/lib.analytics\` or fixture streams).
+     - \`IntentAdapter\` (hooks into \`@contractspec/lib.observability\` intent detectors or logs).
+     - \`QuestionnaireAdapter\` (loads JSON questionnaires and responses).
+   - Produces normalized \`LifecycleSignal[]\`.
+
+2. **StageScorer**
+   - Weighted scoring model:
+     - Base weight per stage (reflecting expected maturity).
+     - Feature weights (retention, revenue, team size, qualitative feedback).
+     - Confidence computed via variance of contributing signals.
+   - Supports pluggable scoring matrices via JSON config.
+   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.
+
+3. **LifecycleOrchestrator**
+   - Coordinates collectors + scorer.
+   - Returns \`LifecycleAssessment\` with:
+     - \`stage\`, \`confidence\`, \`axisSnapshot\`, \`signalsUsed\`.
+     - Recommended focus areas (high-level categories only).
+   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).
+
+4. **LifecycleMilestonePlanner**
+   - Loads \`milestones-catalog.json\` (no DB).
+   - Filters upcoming milestones per stage + axis.
+   - Tracks completion using provided IDs (caller persists).
+
+#### Data Files
+- \`configs/stage-weights.json\`
+- \`configs/milestones-catalog.json\`
+- \`questionnaires/stage-readiness.json\`
+
+#### Extension Hooks
+- All adapters exported as TypeScript interfaces.
+- Implementations for analytics/intent can live in bundles or apps without modifying module code.
+
+---
+
+### 4. Lifecycle Advisor Module
+
+**Location:** \`packages/modules/lifecycle-advisor/\`
+
+#### Components
+1. **LifecycleRecommendationEngine**
+   - Consumes \`LifecycleAssessment\`.
+   - Maps gaps to \`LifecycleAction[]\` using rule tables (\`stage-playbooks.ts\`).
+   - Supports override hooks for customer-specific rules.
+
+2. **ContractSpecLibraryRecommender**
+   - Maintains mapping from stage → recommended libraries/modules/bundles.
+   - Returns prioritized list with rationale and adoption prerequisites.
+
+3. **LifecycleCeremonyDesigner**
+   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).
+   - Ensures low-tech friendly instructions (clear copy, undo guidance).
+
+4. **AI Hooks**
+   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).
+   - Keeps actual LLM integration outside module.
+
+---
+
+### 5. Managed Bundle (\`lifecycle-managed\`)
+
+**Responsibilities**
+- Wire modules together.
+- Provide HTTP/GraphQL handlers (exact transport optional).
+- Register LifecycleAdvisorAgent via \`@contractspec/lib.ai-agent\`.
+- LifecycleAdvisorAgent meta: domain \`operations\`, owners \`team-lifecycle\`, stability \`experimental\`, tags \`guide/lifecycle/ops\` so ops tooling can route incidents quickly.
+- Emit lifecycle events through \`@contractspec/lib.bus\` + \`@contractspec/lib.analytics\`.
+- Integrate with \`contractspec-studio\` packages:
+  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).
+  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).
+
+**APIs**
+- \`POST /lifecycle/assessments\`: Accepts metrics + optional questionnaire answers. Returns \`LifecycleAssessment\`.
+- \`GET /lifecycle/playbooks/:stage\`: Returns stage playbook + ceremonies.
+- \`POST /lifecycle/advise\`: Invokes LifecycleAdvisorAgent with context.
+
+**Events**
+- \`LifecycleAssessmentCreated\`
+- \`LifecycleStageChanged\`
+- \`LifecycleGuidanceConsumed\`
+
+---
+
+### 6. Library Enhancements
+
+| Library | Enhancement |
+| --- | --- |
+| \`@contractspec/lib.analytics\` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by \`StageSignalCollector\`. |
+| \`@contractspec/lib.evolution\` | Accepts \`LifecycleContext\` when ranking spec anomalies/suggestions. |
+| \`@contractspec/lib.growth\` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |
+| \`@contractspec/lib.observability\` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |
+
+Each enhancement must import stage types from \`@contractspec/lib.lifecycle\`.
+
+---
+
+### 7. Feature Flags & Progressive Delivery
+
+- Add new flags in progressive-delivery library:
+  - \`LIFECYCLE_DETECTION_ALPHA\`
+  - \`LIFECYCLE_ADVISOR_ALPHA\`
+  - \`LIFECYCLE_MANAGED_SERVICE\`
+- Bundles/modules should check flags before enabling workflows.
+- Flags referenced in docs + Studio UI to avoid accidental exposure.
+
+---
+
+### 8. Analytics & Telemetry
+
+- Events defined in analytics library; consumed by bundle/app:
+  - \`lifecycle_assessment_run\`
+  - \`lifecycle_stage_changed\`
+  - \`lifecycle_guidance_consumed\`
+- Observability pipeline includes:
+  - Composite lifecycle health metric (weighted sum of KPIs).
+  - Drift detection comparing stage predictions over time.
+  - Alert manager recipes for regression (e.g., PMF drop).
+
+---
+
+### 9. Testing Strategy
+
+1. **Unit**
+   - StageScorer weight matrix.
+   - RecommendationEngine mapping.
+   - Library recommender stage coverage.
+
+2. **Contract**
+   - Adapters: ensure mock adapters satisfy interfaces.
+   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.
+
+3. **Integration**
+   - CLI example runs detection + guidance end-to-end on fixture data.
+   - Dashboard example renders assessments, verifying JSON structures remain stable.
+
+---
+
+### 10. Implementation Checklist
+
+- [ ] Documentation (product, tech, ops, user).
+- [ ] Library creation (\`@contractspec/lib.lifecycle\`).
+- [ ] Modules (\`lifecycle-core\`, \`lifecycle-advisor\`).
+- [ ] Bundle (\`lifecycle-managed\`) + Studio wiring.
+- [ ] Library enhancements (analytics/evolution/growth/observability).
+- [ ] Examples (CLI + dashboard).
+- [ ] Feature flags + telemetry.
+- [ ] Automated tests + fixtures.
+
+Keep 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
+
+
+`
+  }
+];
+registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
+
+// src/docs/tech/presentation-runtime.docblock.ts
+var tech_presentation_runtime_DocBlocks = [
+  {
+    id: "docs.tech.presentation-runtime",
+    title: "Presentation Runtime",
+    summary: "Cross-platform runtime for list pages and presentation flows.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/presentation-runtime",
+    tags: ["tech", "presentation-runtime"],
+    body: `## Presentation Runtime
+
+Cross-platform runtime for list pages and presentation flows.
+
+### Packages
+
+- \`@contractspec/lib.presentation-runtime-core\`: shared types and config helpers
+- \`@contractspec/lib.presentation-runtime-react\`: React hooks (web/native-compatible API)
+- \`@contractspec/lib.presentation-runtime-react-native\`: Native entrypoint (re-exports React API for now)
+
+### Next.js config helper
+
+\`\`\`ts
+// next.config.mjs
+import { withPresentationNextAliases } from '@contractspec/lib.presentation-runtime-core/next';
+
+const nextConfig = {
+  webpack: (config) => withPresentationNextAliases(config),
+};
+
+export default nextConfig;
+\`\`\`
+
+### Metro config helper
+
+\`\`\`js
+// metro.config.js (CJS)
+const { getDefaultConfig } = require('expo/metro-config');
+const {
+  withPresentationMetroAliases,
+} = require('@contractspec/lib.presentation-runtime-core/src/metro.cjs');
+
+const projectRoot = __dirname;
+const config = getDefaultConfig(projectRoot);
+
+module.exports = withPresentationMetroAliases(config);
+\`\`\`
+
+### React hooks
+
+- \`useListCoordinator\`: URL + RHF + derived variables (no fetching)
+- \`usePresentationController\`: Same plus \`fetcher\` integration
+- \`DataViewRenderer\` (design-system): render \`DataViewSpec\` projections (\`list\`, \`table\`, \`detail\`, \`grid\`) using shared UI atoms
+
+Both accept a \`useUrlState\` adapter. On web, use \`useListUrlState\` (design-system) or a Next adapter.
+
+### KYC molecules (bundle)
+
+- \`ComplianceBadge\` in \`@contractspec/bundle.strit/presentation/components/kyc\` renders a status badge for KYC/compliance snapshots. It accepts a \`state\` (missing_core | incomplete | complete | expiring | unknown) and optional localized \`labels\`. Prefer consuming apps to pass translated labels (e.g., via \`useT('appPlatformAdmin')\`).
+
+### Markdown routes and llms.txt
+
+- Each web app exposes \`/llms\` (and \`/llms.txt\`, \`/llms.md\`) via rewrites. See [llmstxt.org](https://llmstxt.org/).
+- Catch‑all markdown handler lives at \`app/[...slug].md/route.ts\`. It resolves a page descriptor from \`app/.presentations.manifest.json\` and renders via the \`presentations.v2\` engine (target: \`markdown\`).
+- Per‑page companion convention: add \`app/<route>/ai.ts\` exporting a \`PresentationSpec\`.
+- Build‑time tool: \`tools/generate-presentations-manifest.mjs <app-root>\` populates the manifest.
+- CI check: \`bunllms:check\` verifies coverage (% of pages with descriptors) and fails if below threshold.
+`
+  }
+];
+registerDocBlocks(tech_presentation_runtime_DocBlocks);
+
+// src/docs/tech/auth/better-auth-nextjs.docblock.ts
+var 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).
+
+## Server config (Better Auth)
+
+- Source: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Important: \`nextCookies()\` must be the **last** plugin in the Better Auth plugin list so \`Set-Cookie\` is applied correctly in Next.js environments.
+
+## Better Auth Admin plugin
+
+ContractSpec Studio enables the Better Auth **Admin plugin** to support platform-admin user operations (list users, impersonation, etc.).
+
+- Server: \`admin()\` plugin in \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Client: \`adminClient()\` in \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+
+### PLATFORM_ADMIN ⇒ Better Auth admin role
+
+Better Auth Admin endpoints authorize via \`user.role\`. ContractSpec enforces an org-driven rule:
+
+- If the **active organization** has \`type = PLATFORM_ADMIN\`, the signed-in user is ensured to have \`User.role\` containing \`admin\`.
+- This is applied in the session creation hook and re-checked in \`assertsPlatformAdmin()\`.
+
+This keeps admin enablement deterministic and avoids manual role backfills.
+
+## Client config (React web + Expo)
+
+To avoid duplicate background refresh/polling loops in dev (Fast Refresh/HMR), the Better Auth client is implemented as a singleton cached on \`globalThis\`.
+
+- Web client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+- Native client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.native.ts\`
+
+Import guidance:
+
+- If you only need the context/hook, prefer importing from \`@contractspec/bundle.studio/presentation/providers/auth\`.
+- If you explicitly need the Better Auth client instance (e.g. admin impersonation, direct API calls), import from \`@contractspec/bundle.studio/presentation/providers/auth/client\`.
+
+## Public routes (login / signup)
+
+Public auth pages should avoid eager \`authClient\` initialization.
+
+Pattern used:
+
+- In the submit handler, dynamically import \`@contractspec/bundle.studio/presentation/providers/auth/index.web\` and call \`authClient.signIn.*\` / \`authClient.signUp.*\`.
+
+This prevents session refresh behavior from starting just because a public page rendered.
+
+## Next.js proxy auth (web-landing)
+
+The Next.js proxy/middleware is used for **redirect decisions only**. It must not perform DB-backed session reads on every request.
+
+- Source: \`packages/apps/web-landing/src/proxy.ts\`
+- Approach: cookie-only checks via Better Auth cookies helpers:
+  - \`getSessionCookie(request)\`
+  - \`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.
+`
+  }
+];
+registerDocBlocks(tech_auth_better_auth_nextjs_DocBlocks);
+
+// src/docs/tech/schema/README.docblock.ts
+var tech_schema_README_DocBlocks = [
+  {
+    id: "docs.tech.schema.README",
+    title: "Multi‑File Prisma Schema Conventions (per database)",
+    summary: "We adopt Prisma multi‑file schema (GA ≥ v6.7) to organize each database’s models by domain and to import core LSSM module schemas locally.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/schema/README",
+    tags: ["tech", "schema", "README"],
+    body: '# Multi‑File Prisma Schema Conventions (per database)\n\nWe adopt Prisma multi‑file schema (GA ≥ v6.7) to organize each database’s models by domain and to import core LSSM module schemas locally.\n\nCanonical layout per DB:\n\n```\nprisma/\n  schema/\n    main.prisma             # datasource + generators only\n    imported/\n      lssm_sigil/*.prisma   # imported models/enums only (no datasource/generator)\n      lssm_content/*.prisma # idem\n    <domain>/*.prisma       # vertical‑specific models split by bounded context\n```\n\nNotes:\n\n- Imported files contain only `model` and `enum` blocks (strip `datasource`/`generator`).\n- Preserve `@@schema("…")` annotations to keep tables in their Postgres schemas; we now explicitly list schemas in `main.prisma` to avoid P1012: `schemas = ["public","lssm_sigil","lssm_content","lssm_featureflags","lssm_ops","lssm_planning","lssm_quill","lssm_geoterro"]`.\n- Use `@contractspec/app.cli-database` CLI: `database import|check|generate|migrate:*|seed` to manage a single DB; `@contractspec/app.cli-databases` orchestrates multiple DBs.\n\n## Typed merger config\n\n- Define imported module list once per DB with a typed config:\n\n```ts\n// prisma-merger.config.ts\nimport { defineMergedPrismaConfig } from \'@contractspec/app.cli-database\';\n\nexport default defineMergedPrismaConfig({\n  modules: [\n    \'@contractspec/app.cli-database-sigil\',\n    \'@contractspec/app.cli-database-content\',\n    // ...\n  ],\n});\n```\n\n- Then run `database import --target .` (no need to pass `--modules`).\n\n## Prisma Config (prisma.config.ts)\n\nWe use Prisma Config per official docs to point Prisma to the multi-file schema folder and migrations:\n\n```ts\n// prisma.config.ts\nimport path from \'node:path\';\nimport { defineConfig } from \'prisma/config\';\n\nexport default defineConfig({\n  schema: path.join(\'prisma\', \'schema\'),\n  migrations: { path: path.join(\'prisma\', \'migrations\') },\n});\n```\n\nReference: Prisma blog – Organize Your Prisma Schema into Multiple Files: https://www.prisma.io/blog/organize-your-prisma-schema-with-multi-file-support\n\n---\n\n# LSSM Auth (Sigil) – Models & Integration\n\nThis document tracks the identity models and integration points used by the LSSM Sigil module.\n\n## Models (Prisma `lssm_sigil`)\n\n- `User` – core identity with email, optional phone, role, passkeys, apiKeys\n- `Session` – session tokens and metadata; includes `activeOrganizationId`\n- `Account` – external providers (password, OAuth)\n- `Organization` – tenant boundary; includes `type` additional field\n- `Member`, `Invitation`, `Team`, `TeamMember` – org/teams\n- `Role`, `Permission`, `PolicyBinding` – RBAC\n- `ApiKey`, `Passkey` – programmable access and WebAuthn\n- `SsoProvider` – OIDC/SAML provider configuration (org- or user-scoped)\n- `OAuthApplication`, `OAuthAccessToken`, `OAuthConsent` – first/third-party OAuth\n\nThese mirror STRIT additions so Better Auth advanced plugins (admin, organization, apiKey, passkey, genericOAuth) work uniformly across apps.\n\n## Better Auth (server)\n\nEnabled methods:\n\n- Email & password\n- Phone OTP (Telnyx)\n- Passkey (WebAuthn)\n- API keys\n- Organizations & Teams\n- Generic OAuth (FranceConnect+ via OIDC with JWE/JWS using JOSE)\n\nServer config lives at `packages/lssm/modules/sigil/src/application/services/auth.ts`.\n\n## Clients (Expo / React)\n\nClient config lives at `packages/lssm/modules/sigil/src/presentation/providers/auth/expo.ts` with plugins for admin, passkey, apiKey, organization, phone, genericOAuth.\n\n## Environment Variables\n\nTelnyx (phone OTP):\n\n- `TELNYX_API_KEY`\n- `TELNYX_MESSAGING_PROFILE_ID`\n- `TELNYX_FROM_NUMBER`\n\nFranceConnect+ (prefer LSSM*… but STRIT*… fallbacks are supported):\n\n- `LSSM_FRANCECONNECTPLUS_DISCOVERY_URL`\n- `LSSM_FRANCECONNECTPLUS_CLIENT_ID`\n- `LSSM_FRANCECONNECTPLUS_CLIENT_SECRET`\n- `LSSM_FRANCECONNECTPLUS_ENC_PRIVATE_KEY_PEM` (PKCS8; RSA-OAEP-256)\n\nGeneric:\n\n- `API_URL_IDENTITIES` – base URL for Better Auth server\n- `BETTER_AUTH_SECRET` – server secret\n\nKeep this in sync with code changes to avoid drift.\n\n## HCircle domain splits and auth removal\n\n- Auth/identity models are not defined locally anymore. They come from `@contractspec/app.cli-database-sigil` under the `lssm_sigil` schema.\n- `packages/hcircle/libs/database-coliving/prisma/schema/domain/` is split by domain; newsletter/waiting list lives in `newsletter.prisma` and uses `@@map("waiting_list")`.\n- To avoid collisions with module names, the local event models were renamed to `SocialEvent`, `SocialEventAttendee`, and `SocialEventRecurrence` with `@@map` pointing to existing table names.\n\n---\n\n## Vertical profiles (current)\n\n### STRIT\n\n- prisma-merger modules:\n  - `@contractspec/app.cli-database-sigil`, `@contractspec/app.cli-database-content`, `@contractspec/app.cli-database-ops`, `@contractspec/app.cli-database-planning`, `@contractspec/app.cli-database-quill`, `@contractspec/app.cli-database-geoterro`\n- main.prisma schemas:\n  - `schemas = ["public","lssm_sigil","lssm_content","lssm_ops","lssm_planning","lssm_quill","lssm_geoterro"]`\n- domain splits (`packages/strit/libs/database/prisma/schema/domain/`):\n  - `bookings.prisma` (Booking, StritDocument + links to Content `File` and Sigil `Organization`)\n  - `commerce.prisma` (Wholesale models; `sellerId` linked to Sigil `Organization`)\n  - `files.prisma` (PublicFile, PublicFileAccessLog; `ownerId`→Organization, `uploadedBy`→User)\n  - `geo.prisma` (PublicCountry, PublicAddress, City; links to Spots/Series)\n  - `spots.prisma`, `urbanism.prisma`, `analytics.prisma`, `onboarding.prisma`, `referrals.prisma`, `subscriptions.prisma`, `content.prisma`\n- auth models are imported from Sigil (no local auth tables).\n- Back-relations for `Organization` (e.g., `files`, seller relations) are declared in the Sigil module to avoid scattering.\n\n### ARTISANOS\n\n- prisma-merger modules:\n  - `@contractspec/app.cli-database-sigil`, `@contractspec/app.cli-database-content`, `@contractspec/app.cli-database-featureflags`, `@contractspec/app.cli-database-ops`, `@contractspec/app.cli-database-planning`, `@contractspec/app.cli-database-quill`, `@contractspec/app.cli-database-geoterro`\n- main.prisma schemas:\n  - `schemas = ["public","lssm_sigil","lssm_content","lssm_featureflags","lssm_ops","lssm_planning","lssm_quill","lssm_geoterro"]`\n- domain splits (`packages/artisanos/libs/database-artisan/prisma/schema/domain/`):\n  - `sales.prisma` (Client, Quote, QuoteTemplate, Invoice, FollowUps)\n  - `subsidies.prisma` (SubsidyProgram, AidApplication, SupportingDocument)\n  - `projects.prisma` (Project, ProjectPlanningSettings)\n  - `crm.prisma` (OrganizationProfessionalProfile, OrganizationCertification)\n  - `professions.prisma`, `products.prisma`, `templates.prisma`, `analytics.prisma`, `onboarding.prisma`, `referrals.prisma`, `subscriptions.prisma`, `files.prisma`\n- auth/organization/team models are provided by Sigil; local legacy copies were removed.\n- Where names collide with Content, local models are prefixed (e.g., `PublicFile`) and use `@@map` to keep existing table names where applicable.\n\n## Schema Dictionary: `@contractspec/lib.schema`\n\n### Purpose\n\nDescribe operation I/O once and generate:\n\n- zod (runtime validation)\n- GraphQL (Pothos types/refs)\n- JSON Schema (via `zod-to-json-schema` or native descriptors)\n\n### Primitives\n\n- **FieldType<T>**: describes a scalar or composite field and carries:\n  - `zod` schema for validation\n  - optional JSON Schema descriptor\n  - optional GraphQL scalar reference/name\n- **SchemaModel**: named object model composed of fields. Exposes helpers:\n  - `getZod(): z.ZodObject<ZodShapeFromFields<Fields>> | z.ZodArray<z.ZodObject<...>>`\n    - Preserves each field\'s schema, optionality, and array-ness\n    - Top-level lists are supported via `config.isArray: true`\n  - `getJsonSchema(): JSONSchema7` (export for docs, MCP, forms)\n  - `getPothosInput()` (GraphQL input object name)\n\n### Multi-Format Wrappers\n\nUse existing schema definitions from other libraries:\n- `ZodSchemaType`: Wraps a raw Zod schema (`z.infer` becomes the TS type).\n- `JsonSchemaType`: Wraps a JSON Schema object.\n- `GraphQLSchemaType`: Wraps a GraphQL SDL string.\n\n### Conventions\n\n- Name models with PascalCase; suffix with `Input`/`Result` when ambiguous.\n- Use explicit enums for multi-value constants; reuse the same enum across input/output.\n- Define domain enums via `defineEnum(\'Name\', [...])` in the relevant domain package (e.g., `packages/strit/libs/contracts-strit/src/enums/`), not in `ScalarTypeEnum`.\n- Reference those enums in `SchemaModel` fields directly (they expose `getZod`, `getPothos`, `getJsonSchema`).\n\n#### Example (STRIT)\n\n```ts\n// packages/strit/libs/contracts-strit/src/enums/recurrence.ts\nimport { defineEnum } from \'@contractspec/lib.schema\';\nexport const SpotEnum = {\n  Weekday: () =>\n    defineEnum(\'Weekday\', [\'MO\', \'TU\', \'WE\', \'TH\', \'FR\', \'SA\', \'SU\'] as const),\n  RecurrenceFrequency: () =>\n    defineEnum(\'RecurrenceFrequency\', [\n      \'DAILY\',\n      \'WEEKLY\',\n      \'MONTHLY\',\n      \'YEARLY\',\n    ] as const),\n} as const;\n```\n\n```ts\n// usage in contracts\nfrequency: { type: SpotEnum.RecurrenceFrequency(), isOptional: false },\nbyWeekday: { type: SpotEnum.Weekday(), isOptional: true, isArray: true },\n```\n\n- Use `Date` type for temporal values and ensure ISO strings in JSON transports where needed.\n\n### Mapping rules (summary)\n\n- Strings → GraphQL `String`\n- Numbers → `Int` if safe 32-bit integer else `Float`\n- Booleans → `Boolean`\n- Dates → custom `Date` scalar\n- Arrays<T> → list of mapped T (set `isArray: true` on the field)\n- Top-level arrays → set `isArray: true` on the model config\n- Objects → input/output object types with stable field order\n- Unions → supported for output; input unions map to JSON (structural input is not supported by GraphQL)\n\n### JSON Schema export\n\nPrefer `getZod()` + `zod-to-json-schema` for consistency. For advanced cases, provide a custom `getJsonSchema()` on the model.\n\n### Example\n\n```ts\nimport { ScalarTypeEnum, SchemaModel } from \'@contractspec/lib.schema\';\n\n// Nested model\nconst Weekday = new SchemaModel({\n  name: \'Weekday\',\n  fields: {\n    value: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },\n  },\n});\n\n// Parent model with array field and nested object\nconst Rule = new SchemaModel({\n  name: \'Rule\',\n  fields: {\n    timezone: { type: ScalarTypeEnum.TimeZone(), isOptional: false },\n    byWeekday: { type: Weekday, isOptional: true, isArray: true },\n  },\n});\n\nconst CreateThingInput = new SchemaModel({\n  name: \'CreateThingInput\',\n  fields: {\n    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\n    rule: { type: Rule, isOptional: false },\n  },\n});\n\n// zod\nconst z = CreateThingInput.getZod();\n```\n'
+  }
+];
+registerDocBlocks(tech_schema_README_DocBlocks);
+
+// src/workflow/overview.docblock.ts
+var tech_workflows_overview_DocBlocks = [
+  {
+    id: "docs.tech.workflows.overview",
+    title: "WorkflowSpec Overview",
+    summary: "WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@contractspec/lib.contracts-spec` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/workflows/overview",
+    tags: ["tech", "workflows", "overview"],
+    body: "# WorkflowSpec Overview\n\n## Purpose\n\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@contractspec/lib.contracts-spec` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\n\n## Core Types\n\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\n- `WorkflowDefinition`:\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\n  - `steps[]`: ordered list of `Step` descriptors.\n  - `transitions[]`: directed edges between steps with optional expressions.\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\n- `Step`:\n  - `type`: `human`, `automation`, or `decision`.\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\n- `Transition`: `from` → `to` with optional `condition` string (simple data expressions).\n\n## Registry & Validation\n\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\n  - Duplicate step IDs.\n  - Unknown `from`/`to` transitions.\n  - Empty guards/conditions.\n  - Reachability from the entry step.\n  - Cycles in the graph.\n  - Operation/Form references against provided registries.\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\n\n## Runtime\n\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\n  - `start(name, version?, initialData?)` returns a `workflowId`.\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\n  - `getState(workflowId)` retrieves the latest state snapshot.\n  - `cancel(workflowId)` marks the workflow as cancelled.\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\n- React bindings (`@contractspec/lib.presentation-runtime-react`):\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\n  - `WorkflowStepper` progress indicator using design-system Stepper.\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\n\n## Authoring Checklist\n\n1. Reuse existing operations/forms; create new specs when missing.\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\n\n## Testing\n\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\n\n## Tooling\n\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\n\n## Next Steps (Non-MVP)\n\n- Persistence adapters (database/file) for workflow state (Phase 2).\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\n- Telemetry hooks for step execution metrics.\n\n"
+  }
+];
+registerDocBlocks(tech_workflows_overview_DocBlocks);
+
+// src/docs/tech/mcp-endpoints.docblock.ts
+var tech_mcp_endpoints_DocBlocks = [
+  {
+    id: "docs.tech.mcp.endpoints",
+    title: "ContractSpec MCP endpoints",
+    summary: "Dedicated MCP servers for docs, CLI usage, and internal development.",
+    kind: "reference",
+    visibility: "mixed",
+    route: "/docs/tech/mcp/endpoints",
+    tags: ["mcp", "docs", "cli", "internal"],
+    body: `# ContractSpec MCP endpoints
+
+Three dedicated MCP servers keep AI agents efficient and scoped:
+
+- **Docs MCP**: \`/api/mcp/docs\` — exposes DocBlocks as resources + presentations. Tool: \`docs.search\`.
+- **CLI MCP**: \`/api/mcp/cli\` — surfaces CLI quickstart/reference/README and suggests commands. Tool: \`cli.suggestCommand\`.
+- **Internal MCP**: \`/api/mcp/internal\` — internal routing hints, playbook, and example registry access. Tool: \`internal.describe\`.
+
+### Usage notes
+- Transports are HTTP POST (streamable HTTP); SSE is disabled.
+- Resources are namespaced (\`docs://*\`, \`cli://*\`, \`internal://*\`) and are read-only.
+- Internal MCP also exposes the examples registry via \`examples://*\` resources:
+  - \`examples://list?q=<query>\`
+  - \`examples://example/<id>\`
+- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.
+- GraphQL remains at \`/graphql\`; health at \`/health\`.
+
+### Alpic hosting
+- Alpic exposes MCP at \`/\` (SSE + Streamable HTTP) and \`/mcp\` (Streamable HTTP).
+- Static UI assets are served at \`/assets\` from repo \`/assets\` or build output \`dist/assets\`.
+- Use the \`ALPIC_HOST\` environment variable to build absolute asset URLs.
+`
+  }
+];
+registerDocBlocks(tech_mcp_endpoints_DocBlocks);
+
+// src/docs/tech/vscode-extension.docblock.ts
+var tech_vscode_extension_DocBlocks = [
+  {
+    id: "docs.tech.vscode.extension",
+    title: "ContractSpec VS Code Extension",
+    summary: "VS Code extension for spec-first development with validation, scaffolding, and MCP integration.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/vscode/extension",
+    tags: ["vscode", "extension", "tooling", "dx"],
+    body: `# ContractSpec VS Code Extension
+
+The ContractSpec VS Code extension provides spec-first development tooling directly in your editor.
+
+## Features
+
+- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files
+- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)
+- **Spec Explorer**: List and navigate all specs in your workspace
+- **Dependency Analysis**: Visualize spec dependencies and detect cycles
+- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol
+- **Snippets**: Code snippets for common ContractSpec patterns
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`ContractSpec: Validate Current Spec\` | Validate the currently open spec file |
+| \`ContractSpec: Validate All Specs\` | Validate all spec files in the workspace |
+| \`ContractSpec: Build/Scaffold\` | Generate handler/component from the current spec |
+| \`ContractSpec: List All Specs\` | Show all specs in the workspace |
+| \`ContractSpec: Analyze Dependencies\` | Analyze and visualize spec dependencies |
+| \`ContractSpec: Search Docs (MCP)\` | Search documentation via MCP |
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| \`contractspec.api.baseUrl\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \`""\` |
+| \`contractspec.telemetry.posthogHost\` | PostHog host URL for direct telemetry | \`"https://eu.posthog.com"\` |
+| \`contractspec.telemetry.posthogProjectKey\` | PostHog project key for direct telemetry | \`""\` |
+| \`contractspec.validation.onSave\` | Run validation on save | \`true\` |
+| \`contractspec.validation.onOpen\` | Run validation on open | \`true\` |
+
+## Architecture
+
+The extension uses:
+- \`@contractspec/module.workspace\` for pure analysis + templates
+- \`@contractspec/bundle.workspace\` for workspace services + adapters
+
+This allows the extension to work without requiring the CLI to be installed.
+
+## Telemetry
+
+The extension uses a hybrid telemetry approach:
+1. If \`contractspec.api.baseUrl\` is configured → send to API \`/api/telemetry/ingest\`
+2. Otherwise → send directly to PostHog (if project key configured)
+
+Telemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.
+`
+  },
+  {
+    id: "docs.tech.vscode.snippets",
+    title: "ContractSpec Snippets",
+    summary: "Code snippets for common ContractSpec patterns in VS Code.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/vscode/snippets",
+    tags: ["vscode", "snippets", "dx"],
+    body: `# ContractSpec Snippets
+
+The VS Code extension includes snippets for common ContractSpec patterns.
+
+## Available Snippets
+
+| Prefix | Description |
+|--------|-------------|
+| \`contractspec-command\` | Create a new command (write operation) |
+| \`contractspec-query\` | Create a new query (read-only operation) |
+| \`contractspec-event\` | Create a new event |
+| \`contractspec-docblock\` | Create a new DocBlock |
+| \`contractspec-telemetry\` | Create a new TelemetrySpec |
+| \`contractspec-presentation\` | Create a new Presentation |
+
+## Usage
+
+Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.
+`
+  }
+];
+registerDocBlocks(tech_vscode_extension_DocBlocks);
+
+// src/docs/tech/telemetry-ingest.docblock.ts
+var tech_telemetry_ingest_DocBlocks = [
+  {
+    id: "docs.tech.telemetry.ingest",
+    title: "Telemetry Ingest Endpoint",
+    summary: "Server-side telemetry ingestion for ContractSpec clients (VS Code extension, CLI, etc.).",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/tech/telemetry/ingest",
+    tags: ["telemetry", "api", "posthog", "analytics"],
+    body: `# Telemetry Ingest Endpoint
+
+The ContractSpec API provides a telemetry ingest endpoint for clients to send product analytics events.
+
+## Endpoint
+
+\`\`\`
+POST /api/telemetry/ingest
+\`\`\`
+
+## Request
+
+\`\`\`json
+{
+  "event": "contractspec.vscode.command_run",
+  "distinct_id": "client-uuid",
+  "properties": {
+    "command": "validate"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+\`\`\`
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| \`x-contractspec-client-id\` | Optional client identifier (used as fallback for distinct_id) |
+| \`Content-Type\` | Must be \`application/json\` |
+
+### Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`event\` | string | Yes | Event name (e.g., \`contractspec.vscode.activated\`) |
+| \`distinct_id\` | string | Yes | Anonymous client identifier |
+| \`properties\` | object | No | Event properties |
+| \`timestamp\` | string | No | ISO 8601 timestamp |
+
+## Response
+
+\`\`\`json
+{
+  "success": true
+}
+\`\`\`
+
+## Configuration
+
+The endpoint requires \`POSTHOG_PROJECT_KEY\` environment variable to be set. If not configured, events are accepted but not forwarded.
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| \`POSTHOG_HOST\` | PostHog host URL | \`https://eu.posthog.com\` |
+| \`POSTHOG_PROJECT_KEY\` | PostHog project API key | (required) |
+
+## Privacy
+
+- No PII is collected or stored
+- \`distinct_id\` is an anonymous client-generated UUID
+- File paths and source code are never included in events
+- Respects VS Code telemetry settings on the client side
+
+## Events
+
+### OSS Adoption Funnel
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`cta_install_click\` | Clicked Install OSS CTA | \`surface\` |
+| \`cta_studio_click\` | Clicked Studio waitlist CTA | \`surface\`, \`variant\` |
+| \`docs_quickstart_view\` | Entered quickstart docs path | \`surface\`, \`destination\` |
+| \`copy_command_click\` | Copied a command block | \`surface\`, \`language\`, \`filename\`, \`packageManager\` |
+| \`example_repo_open\` | Selected a template/example | \`surface\`, \`templateId\`, \`source\` |
+
+### Extension Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.vscode.activated\` | Extension activated | \`version\` |
+| \`contractspec.vscode.command_run\` | Command executed | \`command\` |
+| \`contractspec.vscode.mcp_call\` | MCP call made | \`endpoint\`, \`tool\` |
+
+### API Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.api.mcp_request\` | MCP request processed | \`endpoint\`, \`method\`, \`success\`, \`duration_ms\` |
+`
+  },
+  {
+    id: "docs.tech.telemetry.hybrid",
+    title: "Hybrid Telemetry Model",
+    summary: "How ContractSpec clients choose between direct PostHog and API-routed telemetry.",
+    kind: "usage",
+    visibility: "internal",
+    route: "/docs/tech/telemetry/hybrid",
+    tags: ["telemetry", "architecture", "posthog"],
+    body: `# Hybrid Telemetry Model
+
+ContractSpec uses a hybrid telemetry model where clients can send events either directly to PostHog or via the API server.
+
+## Decision Flow
+
+\`\`\`
+Is contractspec.api.baseUrl configured?
+├── Yes → Send via /api/telemetry/ingest
+└── No → Is posthogProjectKey configured?
+    ├── Yes → Send directly to PostHog
+    └── No → Telemetry disabled
+\`\`\`
+
+## Benefits
+
+### Direct PostHog
+- No server dependency
+- Works offline (with batching)
+- Lower latency
+
+### Via API
+- Centralized key management (no client-side keys)
+- Server-side enrichment and validation
+- Rate limiting and abuse prevention
+- Easier migration to other providers
+
+## Recommendation
+
+- **Development**: Use direct PostHog with a dev project key
+- **Production**: Route via API for better governance
+
+## Future: OpenTelemetry
+
+The current PostHog implementation is behind a simple interface that can be swapped for OpenTelemetry:
+
+\`\`\`typescript
+interface TelemetryClient {
+  send(event: TelemetryEvent): Promise<void>;
+}
+\`\`\`
+
+This allows future migration without changing client code.
+`
+  }
+];
+registerDocBlocks(tech_telemetry_ingest_DocBlocks);
+
+// src/docs/tech/contracts/README.docblock.ts
+var tech_contracts_README_DocBlocks = [
+  {
+    id: "docs.tech.contracts.README",
+    title: "Contracts: Specs, Registry, Handlers, Adapters",
+    summary: "- `packages/lssm/libs/contracts` defines the contracts core (OperationSpecRegistry, OperationSpec, PresentationSpec, 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 (OperationSpecRegistry, OperationSpec, PresentationSpec, 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- `@contractspec/lib.contracts-spec` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@contractspec/lib.contracts-runtime-client-react` 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- `@contractspec/lib.contracts-runtime-server-rest` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@contractspec/lib.contracts-spec/types` exports the runtime handler context utilities, while `@contractspec/lib.contracts-spec/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- `@contractspec/lib.schema`, `@contractspec/lib.design-system`, `@contractspec/lib.ui-kit`, `@contractspec/lib.ui-kit-web`, `@contractspec/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- **OperationSpec**: 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- **OperationSpecRegistry**: 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 `OperationSpecRegistry`, 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 OperationSpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"
+  }
+];
+registerDocBlocks(tech_contracts_README_DocBlocks);
+
+// src/docs/tech/contracts/openapi-export.docblock.ts
+var 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-spec/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);
+
+// src/docs/tech/contracts/openapi-import.docblock.ts
+var 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);
+
+// src/workspace-config/workspace-config.docblock.ts
+var tech_workspace_config_DocBlocks = [
+  {
+    id: "docs.tech.contracts.workspace-config",
+    title: "Workspace Configuration (.contractsrc)",
+    summary: "Configuration-as-code conventions for ContractSpec workspaces (`.contractsrc.json`).",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/contracts/workspace-config",
+    tags: ["tech", "contracts", "config"],
+    body: `## Workspace Configuration (.contractsrc)
+
+ContractSpec uses a hierarchical configuration system anchored by \`.contractsrc.json\` files. Configuration loader supports standard rc-file discovery (cosmiconfig).
+
+### Schema Formats
+
+The \`schemaFormat\` option controls the output format of schema generation commands (like \`contractspec openapi import\`).
+
+Supported formats:
+- \`contractspec\` (default): Generates standard \`defineSchemaModel\` code.
+- \`zod\`: Generates raw Zod schemas using \`z.object({...})\`.
+- \`json-schema\`: Generates JSON Schema definitions.
+- \`graphql\`: Generates GraphQL SDL type definitions.
+
+### Config Interface
+
+\`\`\`ts
+export interface ContractsrcConfig {
+  // ... existing fields ...
+  schemaFormat?: 'contractspec' | 'zod' | 'json-schema' | 'graphql';
+}
+\`\`\`
+
+Defined in \`@contractspec/lib.contracts-spec/workspace-config\`.
+`
+  }
+];
+registerDocBlocks(tech_workspace_config_DocBlocks);
+
+// src/docs/tech/studio/workspaces.docblock.ts
+var tech_studio_workspaces_DocBlocks = [
+  {
+    id: "docs.tech.studio.workspaces",
+    title: "Studio projects, teams, environments",
+    summary: "Organization-first Studio: projects live under an organization; teams refine access; projects deploy to multiple environments.",
+    kind: "reference",
+    visibility: "mixed",
+    route: "/docs/tech/studio/workspaces",
+    tags: ["studio", "projects", "teams", "rbac", "environments"],
+    body: `## Concepts
+
+- **Organization**: the primary grouping boundary for Studio projects.
+- **Project**: one application (specs, overlays, deployments, integrations, evolution, learning).
+- **Team**: refines who can see/edit a project within an organization.
+- **Environment**: deployment target (Development / Staging / Production).
+
+## Project access (teams + admin override)
+
+Studio uses multi-team sharing to refine access:
+
+- **Admins/owners** can access all projects.
+- If a project is shared with **no teams**, it is **org-wide** (all org members).
+- If a project is shared with **one or more teams**, it is visible to:
+  - admins/owners, and
+  - members of any linked team.
+
+## Current persistence (DB + GraphQL)
+
+- DB (Prisma): \`StudioProject\`, \`Team\`, \`TeamMember\`, \`StudioProjectTeam\`
+- GraphQL:
+  - \`myStudioProjects\`
+  - \`createStudioProject(input.teamIds?)\`
+  - \`myTeams\`
+  - \`projectTeams(projectId)\`
+  - \`setProjectTeams(projectId, teamIds)\`
+
+## UI shell behavior
+
+Studio and Sandbox both use a shared shell:
+
+- Project selector → Module navigation → Environment selector
+- Always-on Assistant button (floating)
+- Learning journey progress (Studio persists learning events; Sandbox stays local-only)
+
+## Routing
+
+- \`/studio/projects\`: create/select/delete projects (organization-first).
+- \`/studio/{projectSlug}/*\`: project modules (canvas/specs/deploy/integrations/evolution/learning).
+- \`/studio/learning\`: learning hub without selecting a project.
+`
+  }
+];
+registerDocBlocks(tech_studio_workspaces_DocBlocks);
+
+// src/docs/tech/studio/sandbox-unlogged.docblock.ts
+var tech_studio_sandbox_unlogged_DocBlocks = [
+  {
+    id: "docs.tech.studio.sandbox.unlogged",
+    title: "Sandbox (unlogged) vs Studio (authenticated)",
+    summary: "The sandbox is a lightweight, unlogged surface that mirrors Studio navigation without auth or analytics.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/sandbox-unlogged",
+    tags: ["studio", "sandbox", "privacy", "analytics"],
+    body: `## Sandbox guarantees
+
+- Route: \`/sandbox\`
+- **No auth requirement**
+- **No PostHog init**
+- **No Vercel Analytics**
+- Local-only state (in-browser runtime + localStorage where needed)
+
+## What Sandbox is for
+
+- Try templates and feature modules safely
+- Preview specs/builder/evolution/learning
+- Produce copyable CLI commands (no side effects)
+
+## What Sandbox is *not* for
+
+- Persisted projects/workspaces
+- Real deployments
+- Organization-scoped integrations (unless explicitly enabled later)
+`
+  }
+];
+registerDocBlocks(tech_studio_sandbox_unlogged_DocBlocks);
+
+// src/docs/tech/studio/workspace-ops.docblock.ts
+var tech_studio_workspace_ops_DocBlocks = [
+  {
+    id: "docs.tech.studio.workspace_ops",
+    title: "Workspace ops (repo-linked): list / validate / deps / diff",
+    summary: "Read-only repo operations used by Studio to inspect and validate a linked ContractSpec workspace.",
+    kind: "reference",
+    visibility: "mixed",
+    route: "/docs/tech/studio/workspace-ops",
+    tags: ["studio", "repo", "workspace", "validate", "diff"],
+    body: `## API surface (api-contractspec)
+
+Base: \`/api/workspace-ops\`
+
+These endpoints are **read-only** in v1 and never push to git:
+
+- \`GET /api/workspace-ops/:integrationId/config?organizationId=\`
+- \`GET /api/workspace-ops/:integrationId/specs?organizationId=\`
+- \`POST /api/workspace-ops/:integrationId/validate\` (body: organizationId, files?, pattern?)
+- \`POST /api/workspace-ops/:integrationId/deps\` (body: organizationId, pattern?)
+- \`POST /api/workspace-ops/:integrationId/diff\` (body: organizationId, specPath, baseline?, breakingOnly?)
+
+## Repo resolution
+
+- The repo root is resolved from the Studio Integration (\`IntegrationProvider.GITHUB\`) config:
+  - \`config.repoCachePath\` (preferred) or \`config.localPath\`
+- Resolution is constrained to \`CONTRACTSPEC_REPO_CACHE_DIR\` (default: \`/tmp/contractspec-repos\`)
+
+## Intended UX
+
+- Studio Assistant can run these checks and present results as suggestions.
+- Users can copy equivalent CLI commands for local runs:
+  - \`contractspec validate\`
+  - \`contractspec deps\`
+  - \`contractspec diff --baseline <ref>\`
+`
+  }
+];
+registerDocBlocks(tech_studio_workspace_ops_DocBlocks);
+
+// src/docs/tech/studio/project-routing.docblock.ts
+var tech_studio_project_routing_DocBlocks = [
+  {
+    id: "docs.tech.studio.project-routing",
+    title: "Studio Project Routing",
+    summary: "Studio uses slugged, project-first routes: /studio/{projectSlug}/* with canonical slug redirects and soft-deleted projects hidden.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/project-routing",
+    tags: ["studio", "routing", "projects", "slug", "redirects"],
+    body: `# Studio Project Routing
+
+ContractSpec Studio uses a **project-first URL scheme**:
+
+- \`/studio/projects\` — create, select, and delete projects.
+- \`/studio/{projectSlug}/*\` — project modules (canvas/specs/deploy/integrations/evolution/learning).
+- \`/studio/learning\` — learning hub that does not require selecting a project.
+
+## Studio layout shell
+
+Studio routes are wrapped in a dedicated **Studio app shell** (header + footer) that provides in-app navigation (Projects/Learning/Teams), organization switching, and account actions.
+
+Project module routes (\`/studio/{projectSlug}/*\`) render their own module shell (\`WorkspaceProjectShellLayout\`). When combined with the global Studio header, the project shell uses a **sticky header offset** to avoid overlapping sticky headers.
+
+## Slug behavior (rename-safe)
+
+- Each project has a \`slug\` stored in the database (\`StudioProject.slug\`).
+- When a project name changes, Studio **updates the slug** and stores the previous slug as an alias (\`StudioProjectSlugAlias\`).
+- Requests to an alias slug are **redirected to the canonical slug**.
+
+GraphQL entrypoint:
+
+- \`studioProjectBySlug(slug: String!)\` returns:
+  - \`project\`
+  - \`canonicalSlug\`
+  - \`wasRedirect\`
+
+## Deletion behavior (soft delete)
+
+Projects are **soft-deleted**:
+
+- \`deleteStudioProject(id: String!)\` sets \`StudioProject.deletedAt\`.
+- All listings and access checks filter \`deletedAt = null\`.
+- Soft-deleted projects are treated as “not found” in Studio routes and GraphQL access checks.
+
+## Available modules for a selected project
+
+The following project modules are expected under \`/studio/{projectSlug}\`:
+
+- \`/canvas\` — Visual builder canvas (stored via overlays and canvas versions).
+- \`/specs\` — Spec editor (stored as \`StudioSpec\`).
+- \`/deploy\` — Deployments history + triggers (stored as \`StudioDeployment\`).
+- \`/integrations\` — Integrations scoped to project (stored as \`StudioIntegration\`).
+- \`/evolution\` — Evolution sessions (stored as \`EvolutionSession\`).
+- \`/learning\` — Project learning activity.
+`
+  }
+];
+registerDocBlocks(tech_studio_project_routing_DocBlocks);
+
+// src/docs/tech/studio/platform-admin-panel.docblock.ts
+var tech_studio_platform_admin_panel_DocBlocks = [
+  {
+    id: "docs.tech.studio.platform-admin-panel",
+    title: "Studio Platform Admin Panel",
+    summary: "How PLATFORM_ADMIN organizations manage tenant orgs and integration connections without session switching.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/platform-admin-panel",
+    tags: ["studio", "admin", "multi-tenancy", "integrations", "better-auth"],
+    body: `# Studio Platform Admin Panel
+
+ContractSpec Studio exposes a dedicated **Platform Admin Panel** for users whose **active organization** has:
+
+- \`Organization.type = PLATFORM_ADMIN\`
+
+The UI route is:
+
+- \`/studio/admin\`
+
+## Authorization model (no org switching)
+
+Platform admins **remain in their own organization**. Cross-tenant actions are always explicit and scoped:
+
+- Admin operations require an explicit \`targetOrganizationId\`.
+- No session / activeOrganizationId switching is performed as part of admin operations.
+
+## Integrations management
+
+The admin panel manages the full ContractSpec Integrations system:
+
+- Lists all shipped \`IntegrationSpec\` entries (registry built via \`createDefaultIntegrationSpecRegistry()\`).
+- CRUD \`IntegrationConnection\` records for a selected tenant org.
+
+### Secrets (reference-only + write-only)
+
+The admin UI supports two modes:
+
+- **Reference-only (BYOK)**: store only \`secretProvider\` + \`secretRef\`.
+- **Write-only provisioning/rotation**: paste a raw secret payload; server writes to the selected backend and stores the resulting reference. The secret value is **never returned or displayed**.
+
+Supported backends:
+
+- Env overrides (\`env://...\`)
+- Google Cloud Secret Manager (\`gcp://...\`)
+- AWS Secrets Manager (\`aws://secretsmanager/...\`)
+- Scaleway Secret Manager (\`scw://secret-manager/...\`)
+
+## Better Auth Admin plugin
+
+The panel uses the Better Auth **Admin plugin** for user operations (list users, impersonation):
+
+- Client calls use \`authClient.admin.*\`.
+- Server-side, ContractSpec enforces that users in a PLATFORM_ADMIN active org have \`User.role\` containing \`admin\` so Better Auth Admin endpoints authorize.
+
+## GraphQL surface
+
+The platform-admin GraphQL operations are guarded by the active org type and include:
+
+- \`platformAdminOrganizations(search, limit, offset)\`
+- \`platformAdminIntegrationSpecs\`
+- \`platformAdminIntegrationConnections(input: { targetOrganizationId, category?, status? })\`
+- \`platformAdminIntegrationConnectionCreate(input)\`
+- \`platformAdminIntegrationConnectionUpdate(input)\`
+- \`platformAdminIntegrationConnectionDelete(targetOrganizationId, connectionId)\`
+
+## Key implementation files
+
+- Auth + role enforcement: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Admin GraphQL module: \`packages/bundles/contractspec-studio/src/infrastructure/graphql/modules/platform-admin.ts\`
+- Integrations admin service: \`packages/bundles/contractspec-studio/src/modules/platform-integrations/index.ts\`
+- Web route: \`packages/apps/web-landing/src/app/(app-customer)/studio/admin/*\`
+`
+  }
+];
+registerDocBlocks(tech_studio_platform_admin_panel_DocBlocks);
+
+// src/docs/tech/studio/learning-events.docblock.ts
+var tech_studio_learning_events_DocBlocks = [
+  {
+    id: "docs.tech.studio.learning-events",
+    title: "Studio Learning Events",
+    summary: "Studio persists learning/activity events to the database; Sandbox keeps learning local-first and unlogged.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/learning-events",
+    tags: ["studio", "learning", "events", "analytics", "sandbox"],
+    body: `# Studio Learning Events
+
+Studio emits lightweight **learning/activity events** to support onboarding, ambient coaching, and learning journeys.
+
+## Persistence model
+
+- **Studio**: events are persisted to the database in \`StudioLearningEvent\` and are organization-scoped (optionally project-scoped).
+- **Sandbox**: events remain **local-only** (unlogged); they must never be sent to backend services.
+
+## GraphQL API
+
+- \`recordLearningEvent(input: { name, projectId?, payload? })\`
+- \`myLearningEvents(projectId?, limit?)\`
+- \`myOnboardingTracks(productId?, includeProgress?)\`
+- \`myOnboardingProgress(trackKey)\`
+- \`dismissOnboardingTrack(trackKey)\`
+
+## Common event names (convention)
+
+- \`module.navigated\` — user navigated to a Studio module (payload at minimum: \`{ moduleId }\`).
+- \`studio.template.instantiated\` — created a new Studio project (starter template). Payload commonly includes \`{ templateId, projectSlug }\`.
+- \`spec.changed\` — created or updated a Studio spec. Payload may include \`{ action: 'create' | 'update', specId?, specType? }\`.
+- \`regeneration.completed\` — finished a “regen/deploy” action (currently emitted on successful Studio deploy actions).
+- \`studio.evolution.applied\` — completed an Evolution session (payload commonly includes \`{ evolutionSessionId }\`).
+
+These events are intentionally minimal and must avoid PII/secrets in payloads.
+`
+  }
+];
+registerDocBlocks(tech_studio_learning_events_DocBlocks);
+
+// src/docs/tech/studio/learning-journeys.docblock.ts
+var tech_studio_learning_journeys_DocBlocks = [
+  {
+    id: "docs.tech.studio.learning-journeys",
+    title: "Studio learning journeys (onboarding + coach)",
+    summary: "DB-backed learning journeys tracked per organization: seeded tracks/steps, event-driven progress, XP/streaks, and a Studio coach surface.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/learning-journeys",
+    tags: [
+      "studio",
+      "learning",
+      "onboarding",
+      "journey",
+      "graphql",
+      "database"
+    ],
+    body: `# Studio learning journeys
+
+Studio supports **DB-backed learning journeys** (onboarding tracks + ambient coach tips) that are advanced by **recorded learning events**.
+
+> See also: \`/docs/tech/studio/learning-events\` for event naming + payload guardrails.
+
+## Scope (multi-tenancy)
+
+- Progress is tracked **per organization** (tenant/workspace), via a \`Learner\` record keyed by \`(userId, organizationId)\`.
+- Learning events are stored as \`StudioLearningEvent\` under the Studio DB schema, scoped to an organization (optionally a project).
+
+## Persistence model (Prisma)
+
+Learning journey progress lives in the \`lssm_learning\` schema:
+
+- \`Learner\` — one per \`(userId, organizationId)\`
+- \`OnboardingTrack\` — seeded track definitions (trackKey, name, metadata)
+- \`OnboardingStep\` — seeded step definitions (stepKey, completionCondition, xpReward, metadata)
+- \`OnboardingProgress\` — learner × track progress (progress %, xpEarned, completedAt, dismissedAt)
+- \`OnboardingStepCompletion\` — append-only completion records (stepKey, status, xpEarned, completedAt)
+
+## Track definition source (spec-first)
+
+- Canonical track specs live in \`@contractspec/example.learning-journey-registry\`.
+- The Studio API seeds/updates the DB definitions via an idempotent “ensure tracks” routine.
+- The DB is kept aligned with track specs (stale steps are removed) to prevent drift and unblock completion.
+
+## Progress advancement (event-driven)
+
+1) UI records an event via GraphQL \`recordLearningEvent\`
+2) Backend creates \`StudioLearningEvent\`
+3) Backend advances onboarding by matching the new event against step completion conditions
+4) Backend persists step completions and recomputes:
+   - \`progress\` percentage
+   - \`xpEarned\` (including streak/completion bonuses when configured)
+   - track completion state (\`completedAt\`)
+
+## GraphQL API (Studio)
+
+- \`myOnboardingTracks(productId?, includeProgress?)\`
+  - returns all tracks + optional progress for the current learner
+- \`myOnboardingProgress(trackKey)\`
+  - returns progress + step completion list for a single track
+- \`dismissOnboardingTrack(trackKey)\`
+  - marks a track dismissed for the learner (prevents auto-coach)
+
+## UI routes/surfaces (web)
+
+- \`/studio/learning\` — learning hub (track list + progress widget)
+- \`/studio/learning/{trackKey}\` — track detail (steps + map)
+- Studio shell mounts a **coach sheet** that can auto-open for incomplete, non-dismissed onboarding.
+
+## Security + data hygiene
+
+- Do not put secrets/PII in \`payload\` fields of learning events.
+- Prefer shallow payload filters (small, stable keys).
+`
+  }
+];
+registerDocBlocks(tech_studio_learning_journeys_DocBlocks);
+
+// src/docs/tech/studio/project-access-teams.docblock.ts
+var tech_studio_project_access_teams_DocBlocks = [
+  {
+    id: "docs.tech.studio.project-access-teams",
+    title: "Studio Project Access via Teams",
+    summary: "Projects live under organizations; team sharing refines access with an admin/owner override.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/project-access-teams",
+    tags: ["studio", "projects", "teams", "rbac", "access-control"],
+    body: `# Studio Project Access via Teams
+
+Studio access control is **organization-first** with optional **team-based sharing**.
+
+## Data model
+
+- \`Team\` and \`TeamMember\` define team membership inside an organization.
+- \`StudioProject\` is owned by an organization.
+- \`StudioProjectTeam\` links projects to 0..N teams.
+
+## Access rules
+
+- **Admins/owners**: always have access to all projects in the organization.
+- **Org-wide projects**: if a project has **no team links**, all organization members can access it.
+- **Team-scoped projects**: if a project has **one or more team links**, a user must be a member of at least one linked team.
+
+## GraphQL surfaces
+
+- Read:
+  - \`myStudioProjects\` (returns only projects you can access)
+  - \`studioProjectBySlug(slug)\` (enforces the same access rules)
+  - \`myTeams\`
+  - \`projectTeams(projectId)\`
+
+- Write:
+  - \`createStudioProject(input.teamIds?)\` (teamIds optional)
+  - \`setProjectTeams(projectId, teamIds)\` (admin-only)
+
+
+## Related
++
++- Team administration + invitations: see \`/docs/tech/studio/team-invitations\`.
++
+## Notes
+
+Payloads and events must avoid secrets/PII. For Sandbox, the model remains local-first and unlogged.
+`
+  }
+];
+registerDocBlocks(tech_studio_project_access_teams_DocBlocks);
+
+// src/docs/tech/studio/team-invitations.docblock.ts
+var tech_studio_team_invitations_DocBlocks = [
+  {
+    id: "docs.tech.studio.team-invitations",
+    title: "Studio Teams & Invitations",
+    summary: "Admin-only team management and email invitation flow to join an organization and optionally a team.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/studio/team-invitations",
+    tags: ["studio", "teams", "invitations", "access-control", "onboarding"],
+    body: `# Studio Teams & Invitations
+
+Studio uses **organization membership** as the base access model. Teams are optional and used to refine access to projects.
+
+## Who can manage teams?
+
+- **Admins/owners only**: create, rename, delete teams; manage project team access; issue invitations.
+
+## Invitation data model
+
+- \`Invitation\` rows are stored under an organization and target an **email** address.
+
+- An invitation can optionally target a \`teamId\`, which will grant the user membership in that team upon acceptance.
+
+Key fields:
+- \`email\`: invited address (must match the accepting user's account email)
+
+- \`status\`: \`pending | accepted | declined | expired\`
+
+- \`teamId?\`: optional team to join
+
+- \`inviterId\`: user who issued the invitation
+
+## GraphQL surfaces
+
+- Team CRUD (admin-only):
+
+  - \`createTeam(name)\`
+
+  - \`renameTeam(teamId, name)\`
+
+  - \`deleteTeam(teamId)\`
+
+
+- Invitations (admin-only):
+
+  - \`organizationInvitations\`
+
+  - \`inviteToOrganization(email, role?, teamId?)\` → returns \`inviteUrl\` and whether an email was sent
+
+## Accepting an invitation
+
+The invite link is served as:
+
+- \`/invite/{invitationId}\`
+
+Acceptance rules:
+- The user must be authenticated.
+
+- The authenticated user’s email must match \`Invitation.email\`.
+
+- If not already a member, create \`Member(userId, organizationId, role)\`.
+
+- If \`teamId\` is present, ensure \`TeamMember(teamId, userId)\`.
+
+- Mark invitation \`status='accepted'\` and set \`acceptedAt\`.
+
+- Set \`activeOrganizationId\` for the session so \`/studio/*\` routes work immediately.
+
+## Email delivery
+
+- If \`RESEND_API_KEY\` is set, the system attempts to send an email.
+
+- Otherwise, the UI uses the returned \`inviteUrl\` for manual copy/share.
+`
+  }
+];
+registerDocBlocks(tech_studio_team_invitations_DocBlocks);
+
+// src/docs/tech/llm/llm-integration.docblock.ts
+var tech_llm_integration_DocBlocks = [
+  {
+    id: "docs.tech.llm.overview",
+    title: "LLM Integration Overview",
+    summary: "Export specs to LLM-friendly formats, generate implementation guides, and verify implementations.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/llm/overview",
+    tags: ["llm", "ai", "export", "guide", "verify"],
+    body: `# LLM Integration
+
+ContractSpec provides first-class LLM integration to bridge specifications and AI coding agents.
+
+## Core Features
+
+### 1. Multi-Format Export
+
+Export specs to markdown in formats optimized for LLM consumption:
+
+- **Context format**: Summary for understanding (goal, context, acceptance criteria)
+- **Full format**: Complete spec with all details (I/O schemas, policy, events)
+- **Prompt format**: Actionable prompt with implementation instructions
+
+### 2. Implementation Guidance
+
+Generate agent-specific implementation plans:
+
+- **Claude Code**: Extended thinking mode with structured prompts
+- **Cursor CLI**: Background/composer mode with .mdc rules generation
+- **Generic MCP**: Standard format for any MCP-compatible agent
+
+### 3. Tiered Verification
+
+Verify implementations against specs:
+
+- **Tier 1 (Structure)**: Types, exports, imports validation
+- **Tier 2 (Behavior)**: Scenario coverage, error handling, events
+- **Tier 3 (AI Review)**: Semantic compliance analysis via LLM
+
+## Access Points
+
+| Surface | Commands/Tools |
+|---------|---------------|
+| CLI | \`contractspec llm export\`, \`guide\`, \`verify\`, \`copy\` |
+| MCP | \`llm.export\`, \`llm.guide\`, \`llm.verify\` tools |
+| VSCode | Export to LLM, Generate Guide, Verify, Copy commands |
+
+## Quick Start
+
+### CLI Usage
+
+\`\`\`bash
+# Export spec as markdown
+contractspec llm export path/to/my.spec.ts --format full
+
+# Generate implementation guide
+contractspec llm guide path/to/my.spec.ts --agent claude-code
+
+# Verify implementation
+contractspec llm verify path/to/my.spec.ts path/to/impl.ts --tier 2
+
+# Copy spec to clipboard
+contractspec llm copy path/to/my.spec.ts --format context
+\`\`\`
+
+### MCP Usage
+
+\`\`\`
+# Export spec
+llm.export { specPath: "path/to/my.spec.ts", format: "full" }
+
+# Generate guide
+llm.guide { specPath: "path/to/my.spec.ts", agent: "cursor-cli" }
+
+# Verify implementation
+llm.verify { specPath: "path/to/my.spec.ts", implementationPath: "path/to/impl.ts", tier: "2" }
+\`\`\`
+
+### Programmatic Usage
+
+\`\`\`typescript
+import { operationSpecToFullMarkdown, operationSpecToAgentPrompt } from '@contractspec/lib.contracts-spec/llm';
+import { createAgentGuideService, createVerifyService } from '@contractspec/bundle.workspace';
+
+// Export
+const markdown = operationSpecToFullMarkdown(mySpec);
+
+// Generate guide
+const guideService = createAgentGuideService({ defaultAgent: 'claude-code' });
+const guide = guideService.generateGuide(mySpec);
+
+// Verify
+const verifyService = createVerifyService();
+const result = await verifyService.verify(mySpec, implementationCode, {
+  tiers: ['structure', 'behavior']
+});
+\`\`\`
+`
+  },
+  {
+    id: "docs.tech.llm.export-formats",
+    title: "LLM Export Formats",
+    summary: "Detailed explanation of the three export formats for LLM consumption.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/llm/export-formats",
+    tags: ["llm", "export", "markdown"],
+    body: `# LLM Export Formats
+
+ContractSpec provides three export formats optimized for different LLM use cases.
+
+## Context Format
+
+Best for: Understanding what a spec does, providing background to LLMs.
+
+Includes:
+- Spec name, version, type
+- Goal and context
+- Description
+- Acceptance scenarios
+
+Example:
+
+\`\`\`markdown
+# users.createUser (v1)
+
+> Create a new user account with email verification.
+
+**Type:** command | **Stability:** stable
+
+## Goal
+Create a new user in the system and trigger email verification.
+
+## Context
+Part of the user onboarding flow. Called after signup form submission.
+
+## Acceptance Criteria
+### Happy path
+**Given:** Valid email and password
+**When:** User submits registration
+**Then:** Account is created, verification email is sent
+\`\`\`
+
+## Full Format
+
+Best for: Complete documentation, implementation reference.
+
+Includes everything:
+- All metadata
+- JSON schemas for I/O
+- Error definitions
+- Policy (auth, rate limits, PII)
+- Events emitted
+- Examples
+- Transport configuration
+
+## Prompt Format
+
+Best for: Feeding directly to coding agents.
+
+Includes:
+- Task header with clear instructions
+- Full spec context
+- Implementation requirements
+- Task-specific guidance (implement/test/refactor/review)
+- Expected output format
+
+The prompt format adapts based on task type:
+- **implement**: Full implementation with tests
+- **test**: Test generation for existing code
+- **refactor**: Refactoring while maintaining behavior
+- **review**: Code review against spec
+`
+  },
+  {
+    id: "docs.tech.llm.agent-adapters",
+    title: "Agent Adapters",
+    summary: "Adapters for different AI coding agents (Claude, Cursor, MCP).",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/llm/agent-adapters",
+    tags: ["llm", "agents", "claude", "cursor", "mcp"],
+    body: `# Agent Adapters
+
+ContractSpec provides specialized adapters for different AI coding agents.
+
+## Claude Code Adapter
+
+Optimized for Anthropic Claude's extended thinking and code generation.
+
+Features:
+- Structured markdown with clear sections
+- Checklists for steps and verification
+- Icons for file operations (\uD83D\uDCDD create, ✏️ modify)
+- System prompt for ContractSpec context
+
+Usage:
+\`\`\`typescript
+const guideService = createAgentGuideService({ defaultAgent: 'claude-code' });
+const result = guideService.generateGuide(spec, { agent: 'claude-code' });
+// result.prompt.systemPrompt - Claude system context
+// result.prompt.taskPrompt - Task-specific instructions
+\`\`\`
+
+## Cursor CLI Adapter
+
+Optimized for Cursor's background/composer mode.
+
+Features:
+- Compact format for context efficiency
+- .mdc cursor rules generation
+- Integration with Cursor's file system
+- Concise step lists
+
+Generate Cursor Rules:
+\`\`\`typescript
+const cursorRules = guideService.generateAgentConfig(spec, 'cursor-cli');
+// Save to .cursor/rules/my-spec.mdc
+\`\`\`
+
+## Generic MCP Adapter
+
+Works with any MCP-compatible agent (Cline, Aider, etc.).
+
+Features:
+- Standard markdown format
+- Table-based metadata
+- JSON resource format support
+- Prompt message format
+
+The generic adapter is the default and works across all agents.
+
+## Choosing an Adapter
+
+| Agent | Best For | Key Features |
+|-------|----------|--------------|
+| Claude Code | Complex implementations | Extended thinking, detailed steps |
+| Cursor CLI | IDE-integrated work | Cursor rules, compact format |
+| Generic MCP | Any MCP agent | Universal compatibility |
+`
+  },
+  {
+    id: "docs.tech.llm.verification",
+    title: "Implementation Verification",
+    summary: "Tiered verification of implementations against specifications.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/llm/verification",
+    tags: ["llm", "verify", "validation", "testing"],
+    body: `# Implementation Verification
+
+ContractSpec provides tiered verification to check if implementations comply with specs.
+
+## Verification Tiers
+
+### Tier 1: Structure (Fast)
+
+Checks TypeScript structure against spec requirements:
+
+| Check | What it validates |
+|-------|------------------|
+| Handler export | Function is properly exported |
+| Contracts import | Imports from @contractspec/lib.contracts-spec |
+| Schema import | Imports from @contractspec/lib.schema |
+| No \`any\` type | TypeScript strict compliance |
+| Error handling | Error codes are referenced |
+| Event emission | Event patterns exist |
+| Input validation | Validation patterns used |
+| Async patterns | Async/await for commands |
+
+### Tier 2: Behavior (Comprehensive)
+
+Checks implementation coverage of spec behaviors:
+
+| Check | What it validates |
+|-------|------------------|
+| Scenario coverage | Acceptance scenarios implemented |
+| Example coverage | Example I/O values referenced |
+| Error cases | All error conditions handled |
+| Event conditions | Events emitted correctly |
+| Idempotency | Idempotent patterns (if required) |
+
+### Tier 3: AI Review (Deep)
+
+Uses LLM for semantic analysis:
+
+- Does the implementation fulfill the spec's intent?
+- Are edge cases properly handled?
+- Is the code quality acceptable?
+- Are there any subtle violations?
+
+Requires AI API key configuration.
+
+## Running Verification
+
+\`\`\`typescript
+const verifyService = createVerifyService({
+  aiApiKey: process.env.ANTHROPIC_API_KEY, // Optional, for Tier 3
+  aiProvider: 'anthropic',
+});
+
+const result = await verifyService.verify(spec, implementationCode, {
+  tiers: ['structure', 'behavior'],
+  failFast: false,
+  includeSuggestions: true,
+});
+
+console.log(result.passed);  // true/false
+console.log(result.score);   // 0-100
+console.log(result.summary); // Human-readable summary
+\`\`\`
+
+## Verification Report
+
+The report includes:
+
+- **passed**: Overall compliance
+- **score**: 0-100 score
+- **issues**: Array of problems found
+- **suggestions**: Recommended fixes
+- **coverage**: Metrics on scenario/error/field coverage
+
+Each issue has:
+- **severity**: error, warning, or info
+- **category**: type, export, import, scenario, error_handling, semantic
+- **message**: Description of the issue
+- **suggestion**: How to fix it
+`
+  }
+];
+registerDocBlocks(tech_llm_integration_DocBlocks);
+
+// src/docs/tech/cli.docblock.ts
+var tech_cli_DocBlocks = [
+  {
+    id: "docs.tech.cli.contractspec",
+    title: "ContractSpec CLI",
+    summary: "The command-line interface for creating, building, and validating contract specifications.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/cli/contractspec",
+    tags: ["cli", "tooling", "reference"],
+    owners: ["@contractspec/app.cli-contractspec"],
+    body: `# ContractSpec CLI
+
+The \`@contractspec/app.cli-contractspec\` package provides the command-line interface for the ContractSpec ecosystem.
+
+It is also exposed via \`@contractspec/apps-registry/contractspec\` for convenience.
+
+## Installation
+
+\`\`\`bash
+bun add -D @contractspec/app.cli-contractspec
+\`\`\`
+
+## Quick Start
+
+\`\`\`bash
+# Create a new contract spec interactively
+contractspec create
+
+# Create with AI assistance
+contractspec create --ai
+
+# Build implementation from spec
+contractspec build src/contracts/mySpec.ts
+
+# Validate a spec
+contractspec validate src/contracts/mySpec.ts
+\`\`\`
+
+## Core Commands
+
+### \`create\`
+
+Interactive wizard to create contract specifications.
+
+\`\`\`bash
+contractspec create --type operation --ai
+\`\`\`
+
+### \`build\`
+
+Generate implementation code from contract specs using AI agents or templates.
+
+\`\`\`bash
+contractspec build src/contracts/signup.contracts.ts --agent-mode claude-code
+\`\`\`
+
+Available agent modes: simple, cursor, claude-code, openai-codex, opencode (alias for opencode-sdk).
+
+OpenCode uses \`@opencode-ai/sdk\` via dynamic import and is ideal for teams running a self-hosted, open backend.
+
+### \`validate\`
+
+Validate contract specifications and verify implementations.
+
+\`\`\`bash
+contractspec validate src/contracts/signup.contracts.ts --check-implementation
+\`\`\`
+
+You can also validate with OpenCode:
+
+\`\`\`bash
+contractspec validate src/contracts/signup.contracts.ts --check-implementation --agent-mode opencode
+\`\`\`
+
+### \`watch\`
+
+Watch contract specifications and auto-regenerate on changes.
+
+\`\`\`bash
+contractspec watch --build --validate
+\`\`\`
+
+### \`list\`
+
+List all contract specifications in the project.
+
+\`\`\`bash
+contractspec list --owner @team-platform
+\`\`\`
+
+### \`cleanup\` / \`clean\`
+
+Clean generated files and build artifacts.
+
+\`\`\`bash
+contractspec clean
+\`\`\`
+
+### \`deps\`
+
+Analyze contract dependencies and relationships (circular dependencies, missing refs).
+
+\`\`\`bash
+contractspec deps --circular
+\`\`\`
+
+### \`diff\`
+
+Compare contract specifications and show differences (breaking changes, semantic diff).
+
+\`\`\`bash
+contractspec diff spec1.ts spec2.ts --breaking
+\`\`\`
+
+### \`ci\`
+
+Run all validation checks for CI/CD pipelines (structure, integrity, deps, doctor, handlers, tests).
+
+\`\`\`bash
+contractspec ci --format sarif --output results.sarif
+\`\`\`
+
+## Configuration
+
+The CLI is configured via \`.contractsrc.json\` in your project root.
+
+\`\`\`json
+{
+  "aiProvider": "claude",
+  "aiModel": "claude-3-7-sonnet-20250219",
+  "agentMode": "claude-code",
+  "outputDir": "./src"
+}
+\`\`\`
+
+For full documentation, refer to the [package README](https://github.com/contractspec/monorepo/tree/main/packages/apps/cli-contractspec).
+`
+  }
+];
+registerDocBlocks(tech_cli_DocBlocks);
+
+// src/docs/tech/report-verification-table.docblock.ts
+var reportVerificationTableDocBlocks = [
+  {
+    id: "docs.tech.report-verification-table",
+    title: "Contract Verification Table",
+    summary: "How the impact report renders per-contract verification status.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/report/verification-table",
+    tags: ["report", "drift", "verification", "impact"],
+    owners: ["platform.core"],
+    domain: "report",
+    body: `# Contract Verification Table
+
+The impact report includes an optional per-contract verification table that summarises the health of each contract at a glance.
+
+## Columns
+
+| Column | Description |
+|--------|-------------|
+| Contract / Endpoint / Event | Fully qualified contract name (e.g. \`user.create\`) |
+| Drift debt | Number of mismatches currently detected |
+| Time since verified | Human-friendly elapsed time (e.g. "23 days") or "Never" |
+| Surfaces covered | Comma-separated list (API, runtime validation, UI form, docs/examples, permissions) |
+| Last verified commit | Short SHA of the last drift-free commit |
+
+## Data flow
+
+1. The drift detector produces per-contract mismatch counts.
+2. \`.contractspec/verified.json\` records the last clean commit per contract.
+3. The report script reads both sources and renders the Markdown table.
+
+## Backward compatibility
+
+When \`contracts\` is absent from the report JSON, the table is skipped and the existing report sections render unchanged.
+
+## Contracts
+
+- Query: \`report.getContractVerificationStatus\` (v1.0.0)
+- Data view: \`report.contractVerificationTable\` (v1.0.0)
+`
+  }
+];
+registerDocBlocks(reportVerificationTableDocBlocks);
+export {
+  techContractsDocs,
+  registerDocsPresentations,
+  registerDocsOperations,
+  registerDocsForms,
+  registerDocsEvents,
+  registerDocsDataViews,
+  registerDocBlocks,
+  metaDocs,
+  mapDocRoutes,
+  listRegisteredDocBlocks,
+  docsPresentationContracts,
+  docsOperationContracts,
+  docsFormContracts,
+  docsEventContracts,
+  docsDataViewContracts,
+  docId,
+  docBlocksToPresentationSpecs,
+  docBlocksToPresentationRoutes,
+  docBlockToPresentationSpec,
+  defaultDocRegistry,
+  ExampleCatalogDataView,
+  DocumentationSystemCapability,
+  DocsSearchForm,
+  DocsReferencePagePresentation,
+  DocsPublishedPayload,
+  DocsPublishedEvent,
+  DocsPublishCommand,
+  DocsLayoutPresentation,
+  DocsIndexQuery,
+  DocsIndexOutput,
+  DocsIndexInput,
+  DocsIndexDataView,
+  DocsGeneratedPayload,
+  DocsGeneratedEvent,
+  DocsGenerateCommand,
+  DocSummaryModel,
+  DocRegistry,
+  DOCS_TAGS,
+  DOCS_STABILITY,
+  DOCS_OWNERS,
+  DOCS_DOMAIN,
+  ContractReferenceQuery,
+  ContractReferenceOutput,
+  ContractReferenceModel,
+  ContractReferenceInput,
+  ContractReferenceDataView
+};