@lssm/lib.contracts-spec 17.3.2

package/dist/node/docs/docblocks.manifest.generated.js

@@ -0,0 +1,3215 @@
+export const contractsSpecDocManifest={packageName:"@lssm/lib.contracts-spec",generatedAt:"1970-01-01T00:00:00.000Z",blocks:[{id:"ai-improvement-v2",exportName:"aiImprovementV2DocBlock",sourceModule:"ai-improvement/contracts-v2",block:{id:"ai-improvement-v2",title:"Governed adaptive improvement V2",body:"Versioned contracts for sanitized operational signals, explicit canary observation, deterministic automation risk, provider patch receipts, and work orders with an observing stage. V1 contracts remain unchanged. Operational signals carry metadata and evidence only; raw prompts, payloads, credentials, and personal data are outside this contract.",kind:"reference",route:"packages/libs/contracts-spec/src/ai-improvement/contracts-v2.ts",visibility:"public"}},{id:"contractspec-delivery-chain-artifact-v1",exportName:"deliveryChainArtifactV1DocBlock",sourceModule:"delivery/chain",block:{id:"contractspec-delivery-chain-artifact-v1",title:"Intent-to-production delivery chain artifacts",body:"The delivery chain links product intent, Builder planning, Connect decisions, candidate patches, release plans, infrastructure work orders, deployment receipts, runtime evidence, outcome observations, and governed evolution proposals through canonical SHA-256 digests. Every artifact has effectAuthority none: existing Connect, Runtime Node, infrastructure, release, and provider adapters retain execution authority.",kind:"reference",route:"/docs/contracts/delivery/chain-v1",visibility:"public"}},{id:"contractspec-delivery-ci-budget-state-v2",exportName:"ciBudgetStateV2DocBlock",sourceModule:"delivery/ci-budget",block:{id:"contractspec-delivery-ci-budget-state-v2",title:"CI budget state V2",body:"CiBudgetStateV2 is the provider-neutral, tenant-scoped economic admission state for delivery work. It reconciles fixed costs, provider actuals, active reservations, projections, and recovery reserve against strictly increasing tenant thresholds. Stale or mismatched evidence fails to recovery-only admission, and exposure at the hard limit closes all positive-cost admission.",kind:"reference",route:"/docs/contracts/delivery/ci-budget-state-v2",visibility:"public"}},{id:"contractspec-delivery-manual-author-attestation-v1",exportName:"manualAuthorAttestationV1DocBlock",sourceModule:"delivery/manual-author-attestation",block:{id:"contractspec-delivery-manual-author-attestation-v1",title:"Manual author attestation V1",body:"ManualAuthorAttestationV1 records who authored an exact existing worktree, commit, or patch series before its first governed remote mutation. It binds tenant, repository, source and path digests, intent, evidence, and a Connect decision. It explicitly grants no promotion, provider, migration, or other mutation authority; those actions require their own current Connect decisions and permits.",kind:"reference",route:"/docs/contracts/delivery/manual-author-attestation-v1",visibility:"public"}},{id:"contractspec-delivery-plan-v1",exportName:"deliveryPlanV1DocBlock",sourceModule:"delivery/contracts",block:{id:"contractspec-delivery-plan-v1",title:"Digest-bound delivery plan V1",body:"DeliveryPlanV1 is the provider-neutral aggregate for one exact candidate. Its canonical SHA-256 digest binds tenant, repository, environment, Git base/head/tree, intent, goals, contracts, ownership, autonomy, a signed Connect plan decision reference, catalog provenance, risk, quality, and observation. DeliveryEvidenceEnvelopeV2 links Builder, Connect, quality, release, infrastructure, deployment, runtime, economic, and outcome evidence without embedding provider payloads or secrets.",kind:"reference",route:"/docs/contracts/delivery/plan-v1",visibility:"public"}},{id:"contractspec-delivery-project-profile-v1",exportName:"deliveryProjectProfileV1DocBlock",sourceModule:"delivery/project-profile",block:{id:"contractspec-delivery-project-profile-v1",title:"Adaptive delivery project profiles",body:"DeliveryProjectProfileV1 independently selects adoption, control-plane placement, application hosting, state topology, optional agent execution and company context. Contracts-only consumers need no infrastructure. A mixed Vercel/Railway project needs no Kubernetes, broker, or persistent agent. Preview environments require bounded lifetime, access policy and teardown. CI and operating budget categories remain distinct. A digest proves identity, not qualification or authority: hosts must independently verify referenced qualifications and obtain Connect authorization before effects.",kind:"reference",route:"/docs/contracts/delivery/project-profile-v1",visibility:"public"}},{id:"contractspec-delivery-scoped-autonomy-v2",exportName:"deliveryScopedAutonomyV2DocBlock",sourceModule:"delivery/scoped-autonomy",block:{id:"contractspec-delivery-scoped-autonomy-v2",title:"Scoped delivery autonomy",body:"Additive V2 policies preserve TenantDeliveryPolicyV1. Organization roots and explicit parent chains constrain workspace, project, environment, team, user, action and resource policies. Resolution intersects autonomy, risk and cost limits and unions required checks. Missing parents, cycles, scope expansion, revocation, expiry and digest substitution block progression. Hosts must load the complete applicable policy set and authenticated context, then recheck current policy in Connect before execution. This helper computes an explanation, never a permit; qualified_autonomous still requires independent runtime qualification and authority.",kind:"reference",route:"/docs/contracts/delivery/scoped-autonomy-v2",visibility:"public"}},{id:"contractspec-delivery-telemetry-v2",exportName:"ContractSpecDeliveryTelemetryV2DocBlock",sourceModule:"telemetry/delivery-v2",block:{id:"contractspec-delivery-telemetry-v2",title:"ContractSpec engineering delivery telemetry V2",body:"The canonical delivery event taxonomy projects sanitized, HMAC-grouped operational evidence into the dedicated ContractSpec Engineering analytics project. Every event binds a delivery-plan digest and durable evidence reference. This projection measures the governed loop but can never authorize mutation, promotion, release, deployment, or evolution.",kind:"reference",route:"/docs/contracts/telemetry/delivery-v2",visibility:"public"}},{id:"contractspec-delivery-tenant-authority-v1",exportName:"tenantDeliveryAuthorityV1DocBlock",sourceModule:"delivery/authority",block:{id:"contractspec-delivery-tenant-authority-v1",title:"Tenant delivery authority V1",body:"TenantDeliveryPolicyV1 binds one active owner for every delivery role to tenant scope, risk rules, quality, environments, providers, budget, Connect policy, rollback, and evidence. Delegations expire and remain revocable. Fully autonomous policies additionally require expiry, qualification, and a kill switch. No mode waives exact authority or evidence.",kind:"reference",route:"/docs/contracts/delivery/tenant-authority-v1",visibility:"public"}},{id:"contractspec-quality-plan-v1",exportName:"qualityPlanV1DocBlock",sourceModule:"quality/plan",block:{id:"contractspec-quality-plan-v1",title:"Digest-bound quality plan V1",body:"QualityPlanV1 selects immutable QualityCheckRef values from a qualified profile for one exact delivery digest and Git tree. Each selected check names a gate, blocking or advisory requirement, dependency keys, a qualified execution reference, and reason references. CI executes this plan; it does not decide policy or receive raw command strings from Builder.",kind:"reference",route:"/docs/contracts/quality/plan-v1",visibility:"public"}},{id:"contractspec-quality-profile-v1",exportName:"qualityProfileSpecDocBlock",sourceModule:"quality/profile",block:{id:"contractspec-quality-profile-v1",title:"Quality profile specification V1",body:"QualityProfileSpec catalogs immutable typed checks, binds each check to one qualified execution capability and dependency set, assigns checks to the local, PR, risk, merge/release, nightly, and post-deploy gates, and caps duration and cost. Profiles do not embed provider commands or let an agent invent untyped checks.",kind:"reference",route:"/docs/contracts/quality/profile-v1",visibility:"public"}},{id:"contractspec-quality-run-receipt-v1",exportName:"qualityRunReceiptV1DocBlock",sourceModule:"quality/receipt",block:{id:"contractspec-quality-run-receipt-v1",title:"Quality run receipt V1",body:"QualityRunReceiptV1 binds one immutable quality plan and delivery plan to exact Git SHAs, runner image, toolchains, command digests, cache states, attempts, durations, costs, sanitized evidence digests, Connect decisions, and blocking reasons. Verification rejects omitted or changed checks and prevents a blocking failure from being represented as passing.",kind:"reference",route:"/docs/contracts/quality/run-receipt-v1",visibility:"public"}},{id:"contractspec-telemetry-spec-v2",exportName:"telemetrySpecV2DocBlock",sourceModule:"telemetry/v2",block:{id:"contractspec-telemetry-spec-v2",title:"Strict telemetry specification V2",body:"TelemetrySpecV2 is a provider-neutral, content-addressed contract for separate logs, metrics, traces, analytics, flags, experiments, and errors ports. It requires typed properties, consent, residency, deterministic sampling, HMAC-pseudonymized tenant/workspace/subject groups, cardinality/ingestion/cost budgets, sanitized evidence links, and fail-closed redaction. Raw secrets, prompts, payloads, reasoning, chain of thought, and direct personal identifiers are non-waivable forbidden data. Telemetry remains evidence projection, never promotion authority.",kind:"reference",route:"/docs/contracts/telemetry/spec-v2",visibility:"public"}},{id:"customer-support-v1",exportName:"CustomerSupportV1DocBlock",sourceModule:"customer-support/customer-support.feature",block:{id:"customer-support-v1",title:"Customer SupportOS v1",summary:"Provider-neutral cases, queues, SLAs, AI governance, provider cutover, messenger, portal, and help-center contracts.",kind:"reference",visibility:"public",route:"/docs/platform/customer-support-v1",tags:["support","supportos","intercom","communication-os"],body:`# Customer SupportOS v1
+
+SupportOS owns cases and service operations. CommunicationOS owns messages and channels. Provider credentials are refs, authority is server-derived, and consequential actions remain Connect-governed.`}},{id:"customer-support-v1-capability-matrix",exportName:"SupportCapabilityMatrixDocBlock",sourceModule:"customer-support/capability-matrix",block:{id:"customer-support-v1-capability-matrix",title:"SupportOS v1 capability and qualification matrix",summary:"Typed delivery truth for SupportOS modules, feature hierarchy, ownership, routes, evidence, blockers, and production qualification.",kind:"reference",visibility:"public",route:"/docs/platform/supportos-v1-capability-matrix",tags:["supportos","delivery","qualification","product-health"],body:`# SupportOS v1 capability matrix
+
+Version 1.1 adds registry-backed service, storage, event, journey, SLO, data-class, rollout, ownership, and qualification-scope metadata without removing the v1.0 authoring surface. The matrix separates implementation stage from open blockers. Source and test definitions are inventory evidence; executed proof requires immutable receipts, and production proof expires relative to the matrix asOf. Intrinsic semantics prevent proof-profile downgrades, newer failed or stale receipts supersede older passes, and blocker resolution links verified evidence. Only evidence-complete capabilities without open blockers may be marked qualified.`}},{id:"customer-support-v1-platform-authority",exportName:"SupportPlatformAuthorityDocBlock",sourceModule:"customer-support/platform-authority-doc",block:{id:"customer-support-v1-platform-authority",title:"SupportOS composite platform authority",summary:"Provider-neutral, capability-declared authority facets for managed and self-hosted SupportOS runtimes.",kind:"reference",visibility:"public",route:"/docs/platform/supportos/platform-authority",tags:["supportos","authority","ports","self-hosted"],body:`# SupportOS platform authority
+
+The legacy four-method SupportAuthorityPort remains supported through adaptLegacySupportAuthority. Missing facets stay explicitly unavailable and fail conformance; adapters never silently claim complete v1 support. Production and self-hosted profiles declare every enabled facet, typed authority binding, and canonical operation they require. Conformance rejects missing bindings, undiscoverable operations, inconsistent facet registries, and capabilities advertised without an executable surface. Mutations carry idempotency, revision/fencing, policy, and evidence references. Queries carry pagination, watermark, and redaction intent.`}},{id:"decision-lifecycle-v2",exportName:"DecisionLifecycleDocBlock",sourceModule:"decisioning/lifecycle-operations",block:{id:"decision-lifecycle-v2",title:"Decision lifecycle v2",summary:"Revision-fenced drafts and immutable, digest-pinned DecisionGraph publications.",kind:"reference",visibility:"public",route:"/docs/platform/decision-lifecycle-v2",tags:["decisioning","supportos","revisioning","audit"],body:`# Decision lifecycle v2
+
+Decision definitions are workspace-scoped by authenticated server context. Draft
+mutations use optimistic revision fencing and stable idempotency keys. Publishing
+creates an immutable digest-pinned revision; editing never mutates a published
+revision. Lists use fixed watermarks and keyset cursors. Creator JavaScript and
+business effects are not accepted or executed.`}},{id:"decision-operations-v1",exportName:"DecisionOperationsDocBlock",sourceModule:"decisioning/decisioning.feature",block:{id:"decision-operations-v1",title:"Decision operations v1",summary:"Deterministic, serializable decision graphs shared by Forms, SOPs, support, and workflows.",kind:"reference",visibility:"public",route:"/docs/platform/decision-operations-v1",tags:["decisioning","forms","workflow","support"],body:`# Decision operations v1
+
+DecisionGraph is a pure, revision-pinned DAG. It evaluates typed predicates and produces replay traces; it never executes creator code or business effects.`}},{id:"decision-operations-v2",exportName:"DecisionOperationsV2DocBlock",sourceModule:"decisioning/decisioning.feature",block:{id:"decision-operations-v2",title:"Decision operations v2",summary:"Strict, deterministic, revision-pinned decision validation, simulation, evaluation, replay, comparison, and redacted evidence administration.",kind:"reference",visibility:"public",route:"/docs/platform/decision-operations-v2",tags:["decisioning","forms","workflow","support"],body:`# Decision operations v2
+
+DecisionGraph is a pure, revision-pinned DAG. V2 operations use strict typed envelopes and stable idempotency keys. Evidence-producing validation, simulation, evaluation, replay, and comparison never execute creator code or business effects. Evidence list and detail queries expose digest-bound traces and engine provenance through opaque fixed-watermark pagination without protected inputs, outcome payload data, or authority scope. V1 remains available through its original aggregate and feature identity during migration.`}},{id:"doc:sop.generation-sources",exportName:"SopGenerationSourcesDocBlock",sourceModule:"sop/generation-sources",block:{id:"doc:sop.generation-sources",title:"Living SOP generation source snapshots",body:`Living SOP generation consumes canonical, serializable source contributions rather than provider objects or delivery-matrix state.
+
+Each contribution names an immutable source revision, validity window, and opaque evidence references. Source providers must never place raw answers, message bodies, contact data, prompts, or secrets in identity or evidence references. The runtime copies only the declared semantic fields, applies kind-specific freshness ceilings, canonicalizes ordering, and computes a content-addressed snapshot. Live generation revalidates source expiry against the current clock; historical projection is replay-only. Product adapters derive authority from authenticated server context; generation intent never carries tenant, workspace, actor, policy, or capability authority.
+
+Capability availability comes from the deployed runtime source. Delivery and qualification matrices may be recorded as documentation evidence, but never decide executable availability. Operation contributions resolve aliases to canonical registered key and version before snapshotting. The snapshot executes no effects; Workflow and Connect retain effect authority.`,tags:["sop","generation","provenance","security"]}},{id:"docs.accessibility_wcag_compliance_specs",exportName:"accessibility_wcag_compliance_specs_DocBlocks",sourceModule:"docs/docs.feature",block:{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 \`@lssm/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 '@lssm/lib.accessibility'; // includes tokens and provider exports
+// or if needed: import '@lssm/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.
+`}},{id:"docs.contracts-spec.data-views.annotation",exportName:"annotationDoc",sourceModule:"data-views/annotation",block:{id:"docs.contracts-spec.data-views.annotation",title:"Annotation contract — per-node sticky notes with @-mention support",summary:"Defines AnnotationState, MentionRecord, AnnotationStore and the conflict-resolution constants for graph sticky notes. LWW per field; edit-wins within 60 s of soft-delete; 5-min soft-delete TTL; mentions are append-only.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/annotation",tags:["graph","annotation","mention","conflict","lww","m3"],body:`# Annotation contract
+
+Per-node sticky notes with @-mention support.
+
+## Conflict policy
+
+| Rule | Value |
+|---|---|
+| Last-write-wins per field | Yes — fields are independent |
+| Edit-wins window after delete | 60 s |
+| Soft-delete TTL | 300 s |
+| Mentions | Append-only |
+
+## AnnotationState fields
+
+| Field | Mutable | Description |
+|---|---|---|
+| \`id\` | No | Unique annotation id |
+| \`targetId\` | No | Node/edge this is pinned to |
+| \`authorId\` | No | Creator user id |
+| \`createdAt\` | No | ISO 8601 creation timestamp |
+| \`title\` | Yes (LWW) | Short label |
+| \`color\` | Yes (LWW) | Hex background color |
+| \`resolved\` | Yes (LWW) | Resolved flag |
+| \`body\` | Yes (LWW) | Markdown body with @-mentions |
+| \`deletedAt\` | Yes (soft-delete) | ISO 8601 or null |
+| \`mentions\` | Append-only | @-mention records |
+`}},{id:"docs.contracts-spec.data-views.graph-export",exportName:"graphExportDoc",sourceModule:"data-views/graph-export",block:{id:"docs.contracts-spec.data-views.graph-export",title:"GraphExport — export pipeline contract",summary:"ExportFormat union (png/svg/json/pdf/mermaid/dot), shared option/result shapes, and the GraphExportProvider interface for format-specific exporters.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/graph-export",tags:["graph","export","contract","png","svg","pdf","mermaid","dot","m3"],body:`# GraphExport contract
+
+## ExportFormat
+\`"png" | "svg" | "json" | "pdf" | "mermaid" | "dot"\`
+
+## GraphExportProvider
+Interface all format exporters must implement.
+
+\`\`\`ts
+interface GraphExportProvider {
+  readonly format: ExportFormat;
+  export(options: GraphExportOptions): Promise<GraphExportResult>;
+  isSupported(): boolean;
+}
+\`\`\`
+
+## Web implementations (M3 P6/W6.2)
+- \`PngExporter\` — dom-to-image-more, HiDPI scale=2
+- \`SvgExporter\` — XMLSerializer + data URL`}},{id:"docs.contracts-spec.data-views.graph-filter-codec",exportName:"graphFilterCodecDoc",sourceModule:"data-views/graph-filter-codec",block:{id:"docs.contracts-spec.data-views.graph-filter-codec",title:"graph-filter-codec — URL round-trip codec for GraphFilterSpec",summary:"encodeFilterToUrl() + decodeFilterFromUrl(): lossless URL serialization with gf.* prefix (M3 P4/W4.1).",kind:"reference",visibility:"internal",route:"/docs/contracts-spec/data-views/graph-filter-codec",tags:["graph","filter","codec","url","m3"],body:"# graph-filter-codec\n\n`encodeFilterToUrl(spec)` → `URLSearchParams` with `gf.*` keys.\n`decodeFilterFromUrl(params)` → `GraphFilterSpec | null` (null = no active filter).\n\n| Tier-1 key | URL param |\n| --- | --- |\n| `kinds` | `gf.kinds` (comma-sep) |\n| `statuses` | `gf.statuses` |\n| `owners` | `gf.owners` |\n| `timeRange.from` | `gf.tr.from` |\n| `timeRange.to` | `gf.tr.to` |\n| `timeRange.field` | `gf.tr.field` |\n| `facets[i]` | `gf.facet.{field}` |\n| `predicates` | `gf.preds` (JSON) |"}},{id:"docs.contracts-spec.data-views.graph-filter-spec",exportName:"graphFilterSpecDoc",sourceModule:"data-views/graph-filter-spec",block:{id:"docs.contracts-spec.data-views.graph-filter-spec",title:"GraphFilterSpec — persistent graph filter contract",summary:"Two-tier persistent filter: named fields (kinds/statuses/owners/timeRange) + open fields (facets/predicates). URL-serialisable via graph-filter-codec (M3 P4/W4.1).",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/graph-filter-spec",tags:["graph","filter","contract","url","facet","predicate","m3"],body:"# GraphFilterSpec\n\n`GraphFilterSpec` lives at `DataViewGraphSpec.source.where`.\nAll fields optional — `{}` = no filter.\n\n| Field | Type | Tier |\n| --- | --- | --- |\n| `kinds` | `string[]` | 1 |\n| `statuses` | `string[]` | 1 |\n| `owners` | `string[]` | 1 |\n| `timeRange` | `GraphTimeRangeFilter` | 1 |\n| `facets` | `GraphFacetFilter[]` | 2 |\n| `predicates` | `GraphFilterPredicate[]` | 2 |\n\nURL codec: `encodeFilterToUrl(spec)` → `URLSearchParams`; `decodeFilterFromUrl(params)` → `GraphFilterSpec | null`."}},{id:"docs.contracts-spec.data-views.graph-subscription",exportName:"graphSubscriptionDoc",sourceModule:"data-views/graph-subscription",block:{id:"docs.contracts-spec.data-views.graph-subscription",title:"GraphSubscription — live graph subscription configuration contract",summary:"Configuration sent by clients to establish an SSE graph subscription. Server validates viewKey, applies filter, and streams GraphSubscriptionEvents.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/graph-subscription",tags:["graph","subscription","sse","live","contract","m3","p5"],body:`# GraphSubscription
+
+\`\`\`typescript
+interface GraphSubscription {
+  id: string;        // client- or server-generated
+  viewKey: string;   // DataView registry key
+  filter?: Record<string, unknown>;   // optional server-side filter
+  eventKinds?: GraphSubscriptionEventKind[];  // subset of events
+  heartbeatMs?: number;  // default 30_000
+}
+\`\`\`
+
+## SSE wire format
+
+Each event is serialised as a standard SSE frame:
+\`\`\`
+data: {"kind":"node-added","node":{"id":"n1","label":"My Node"}}
+
+\`\`\`
+
+Heartbeat comments keep the connection alive:
+\`\`\`
+: heartbeat
+
+\`\`\``}},{id:"docs.contracts-spec.data-views.graph-subscription-event",exportName:"graphSubscriptionEventDoc",sourceModule:"data-views/graph-subscription",block:{id:"docs.contracts-spec.data-views.graph-subscription-event",title:"GraphSubscriptionEvent — live graph update discriminated union",summary:"Discriminated union covering all live graph patch events: node-added, node-updated, node-removed, edge-*, and snapshot-replace. Consumed by SSE adapters and client hooks.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/graph-subscription-event",tags:["graph","subscription","sse","live","events","m3","p5"],body:"# GraphSubscriptionEvent\n\nDiscriminated union for live graph update events.\n\n| `kind` | Payload | Notes |\n| --- | --- | --- |\n| `node-added` | `node: SubscriptionNode` | New node arrived |\n| `node-updated` | `node`, `previous?` | Partial patch; previous is optional |\n| `node-removed` | `nodeId: string` | Node deleted |\n| `edge-added` | `edge: SubscriptionEdge` | New edge |\n| `edge-updated` | `edge`, `previous?` | Edge attribute change |\n| `edge-removed` | `edgeId: string` | Edge deleted |\n| `snapshot-replace` | `nodes[]`, `edges[]` | Full resync — replace all state |\n\n`snapshot-replace` is emitted on initial connect, reconnect after gap, or server invalidation.\nClients must exhaustively switch on `kind` for forward-compatibility."}},{id:"docs.contracts-spec.data-views.layout-spec",exportName:"layoutSpecDoc",sourceModule:"data-views/layout-spec",block:{id:"docs.contracts-spec.data-views.layout-spec",title:"LayoutSpec — M3 layout discriminated union",summary:"Six-variant discriminated union replacing M2 GraphLayoutKind. Variants: force, dag, radial, tree, swimlane, time-axis.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/layout-spec",tags:["graph","layout","spec","m3","elkjs","d3","discriminated-union"],body:"# LayoutSpec\n\nDiscriminated union replacing `GraphLayoutKind` from M2.\n\n| kind | Key config | Engine (web / native) | Async chunk |\n| --- | --- | --- | --- |\n| `force` | strength, alphaDecay, collisionRadius | d3-force | d3-force.chunk ≤20 KB gz |\n| `dag` | rankSep, nodeSep, direction | elkjs LAYERED / dagre | elkjs-layout-engine.chunk ≤250 KB gz |\n| `radial` | innerRadius, outerRadius, angularRange | d3-hierarchy | d3-hierarchy.chunk ≤15 KB gz |\n| `tree` | nodeSep, levelSep, orientation | d3-hierarchy tidy | d3-hierarchy.chunk ≤15 KB gz |\n| `swimlane` | laneBy (req), lanes | elkjs BOX / dag fallback | elkjs-layout-engine.chunk ≤250 KB gz |\n| `time-axis` | xField (req), scale | pure TS | base bundle (sync) |\n\n## Migration from M2\n\n```ts\nimport { layoutKindToSpec } from '@lssm/lib.contracts-spec/data-views/layout-spec';\nlayoutKindToSpec('dag') // → { kind: 'dag' }\n```\n\nRemove `layoutKindToSpec` shim in P10 alongside `GraphLayoutKind` removal."}},{id:"docs.contracts-spec.data-views.saved-view",exportName:"savedViewDoc",sourceModule:"data-views/saved-view",block:{id:"docs.contracts-spec.data-views.saved-view",title:"SavedView — serialisable graph viewport + filter + layout snapshot",summary:"Encodes graph viewport, active filter, and layout as a base64 URL param (?gv=). Use serializeSavedView / deserializeSavedView to persist and restore. useSavedViewRestore reads ?gv= on mount and applies the snapshot.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/saved-view",tags:["graph","saved-view","url","restore","viewport","m3"],body:"# SavedView\n\nSerialisable snapshot of the current graph state stored in `?gv=<base64>`.\n\n## Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `id` | `string` | Unique view identifier |\n| `name` | `string` | Human-readable label |\n| `viewport` | `SavedViewport` | Pan + zoom state |\n| `filter` | `GraphFilterSpec?` | Active filter snapshot |\n| `layout` | `string?` | Layout kind key |\n| `savedAt` | `string` | ISO 8601 timestamp |\n\n## URL encoding\n\nZoom is clamped to `[0.05, 10]` on decode. Invalid or absent `?gv=` always yields `null`.\n"}},{id:"docs.contracts-spec.data-views.story-slide",exportName:"storySlideDoc",sourceModule:"data-views/story-slide",block:{id:"docs.contracts-spec.data-views.story-slide",title:"StorySlide — presenter-led graph slide contract",summary:"StorySlide type, DataViewGraphStory config, StorySlideTransition, and StoryPlaybackMode for presenter-led graph sequences (M3 P6/W6.7).",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/story-slide",tags:["graph","story","slide","presenter","contract","m3","p6"],body:"# StorySlide contract\n\nStory mode is a presentation overlay — it does **not** mutate graph structure.\n\n## Key types\n\n| Type | Purpose |\n|---|---|\n| `StorySlide` | One step in the sequence: viewport, highlights, transition, speaker notes |\n| `DataViewGraphStory` | Top-level config stored in `DataViewGraphSpec.story` |\n| `StorySlideTransition` | `viewport-pan \\| fade \\| zoom-to-node \\| zoom-out \\| instant` |\n| `StoryPlaybackMode` | `PRESENTER_LED` (default) or `PER_USER` |\n| `ViewportState` | `{ centerX, centerY, zoom }` in graph-space |\n\n## Playback state\nEphemeral Yjs Awareness — not persisted in the Y.Doc.\n`DataViewGraphStory.slides` is static config.\n\n## Reduced motion\nAll transitions skip-to-end-state when `prefers-reduced-motion` is active.\n\n## Voice narration\nWhen `voiceNarrationEnabled: true`, transcripts become annotations on `highlightedNodeIds[0]`."}},{id:"docs.contracts-spec.design-packs.operations",exportName:"DesignPackOperationsDocBlock",sourceModule:"design-packs/operations",block:{id:"docs.contracts-spec.design-packs.operations",title:"Design pack operations",summary:"Versioned catalog, selection, private draft, certification, publication, and evidence operations.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/design-packs/operations",tags:["design-pack","design-studio","operations"],body:`# Design pack operations
+
+Queries cover catalog discovery, selection reads, previews, validation, and audit evidence. Commands cover selection changes, owner-scoped draft lifecycle, certification, immutable publication, and unpublication. Publication and unpublication require their exact permissions; runtime handlers must preserve tenant and RoleMorph boundaries.`}},{id:"docs.contracts-spec.forms.marketing",exportName:"MarketingFormsDocBlock",sourceModule:"forms/marketing.forms",block:{id:"docs.contracts-spec.forms.marketing",title:"Marketing & BillingOS-adjacent FormSpecs",summary:"Contract-first FormSpecs for form-like marketing/BillingOS UI; rendering goes through the design-system FormSpec renderer and submission binds to OperationSpecs.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/forms/marketing",tags:["marketing","billing","forms","lead-capture","estimate"],body:"# Marketing & BillingOS-adjacent FormSpecs\n\nThree generic, reusable FormSpecs make form-like marketing/BillingOS UI\ncontract-first. Each binds its action to an OperationSpec by `key`+`version`;\nhosts own copy, option catalogs, provider logic, and handlers.\n\n- `marketing.lead.capture.form` (`MarketingLeadCaptureFormSpec`) → action binds\n  to `marketing.lead.capture` (command).\n- `marketing.estimate.input.form` (`MarketingEstimateInputFormSpec`) → action\n  binds to `marketing.estimate.calculate` (query). Bundle options are\n  illustrative defaults; hosts override them.\n- `billing.estimate.intake.form` (`BillingEstimateIntakeFormSpec`) → action binds\n  to `billing.estimate.prepare` (query, **side-effect-free**).\n\nThese specs are schema/layout/action metadata only. The design system renders\nfields and an operation/host-provided result; it never computes pricing, calls a\nprovider, payment, CRM, or invoice path. Live billing execution stays host-owned.\n\nRelationship to `marketing/forms.ts`: `MarketingStudioDemoRequestForm` +\n`marketingFormRegistry` are the Studio-specific demo-CTA form and its registry;\nthe specs here are the generic, reusable lead/estimate/billing forms."}},{id:"docs.contracts-spec.operations.marketing",exportName:"MarketingOperationsDocBlock",sourceModule:"operations/marketing",block:{id:"docs.contracts-spec.operations.marketing",title:"Marketing agent tools",summary:"Public product/plan reads + auth-gated demo booking for the on-site agent and MCP projection.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/operations/marketing",tags:["marketing","agent-surface","operations"],body:`# Marketing agent tools
+
+Three operations power the on-site embedded agent and the public MCP projection:
+
+- \`marketing.product.get\` (query, **public**) — product/feature facts.
+- \`marketing.plans.compare\` (query, **public**) — ranked pricing-plan comparison.
+- \`marketing.demo.book\` (command, **auth + rate-limited**) — books a demo and
+  returns a synthetic booking id. Default-deny: unauthenticated callers are
+  rejected.
+
+Schemas live in \`operations/marketing.ts\`; stub handlers in
+\`operations/marketing.handlers.ts\`. Real product/plan data is sourced from
+app-config \`aiDiscovery.productKnowledge\` and marketing config at the
+composition root.`}},{id:"docs.contracts-spec.rich-reference.detail",exportName:"ReferenceDetailDocBlock",sourceModule:"operations/reference-detail",block:{id:"docs.contracts-spec.rich-reference.detail",title:"Detail of one rich reference",summary:"Resolve a single `(kindId, id)` reference with the kind-specific detail hook.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/rich-reference/detail",tags:["rich-reference","governance"],body:"# reference.detail\n\nResolves a single reference using the kind's optional `detail` handler (or the `resolve` fallback). Redaction is applied post-handler; unknown payload fields are stripped before propagation."}},{id:"docs.contracts-spec.rich-reference.goal",exportName:"richReferenceGoalDoc",sourceModule:"rich-reference/index",block:{id:"docs.contracts-spec.rich-reference.goal",title:"RichReference goal",summary:"One canonical, governance-aware reference type across all surfaces.",kind:"goal",visibility:"public",route:"/docs/contracts-spec/rich-reference/goal",tags:["rich-reference","governance","contracts-spec"],body:`# RichReference
+
+RichReference is the canonical transport for governed, kind-typed references that travel through REST, GraphQL, MCP, and agent surfaces. Each kind declares its payload schema and the subset of fields that may carry sensitive data; the runtime (S-2) enforces post-handler redaction using HMAC-signed denial tokens (F-5 mitigation).`}},{id:"docs.contracts-spec.rich-reference.kinds.entity.goal",exportName:"entityKindGoalDoc",sourceModule:"rich-reference/kinds/entity",block:{id:"docs.contracts-spec.rich-reference.kinds.entity.goal",title:"entityKind — goal",summary:"Canonical reference kind for typed entity instances governed by ContractEntitySpec.",kind:"goal",visibility:"public",route:"/docs/contracts-spec/rich-reference/kinds/entity/goal",tags:["rich-reference","entity","kind","contracts-spec"],body:"# entityKind\n\n`entityKind` is the built-in `ReferenceKindDefinition` for entity references. Each instance\ncarries a `slug` (entity type key) and an `id` (instance identifier). The slug resolves to a\n`ContractEntitySpec` via `resolveEntitySpec(payload, registry)`, connecting RichReference\ngovernance (redaction, policy, audit) to the contracts-spec entity graph."}},{id:"docs.contracts-spec.rich-reference.kinds.entity.usage",exportName:"entityKindUsageDoc",sourceModule:"rich-reference/kinds/entity",block:{id:"docs.contracts-spec.rich-reference.kinds.entity.usage",title:"entityKind — usage",summary:"How to build entity references and resolve entity specs from payloads.",kind:"usage",visibility:"public",route:"/docs/contracts-spec/rich-reference/kinds/entity/usage",tags:["rich-reference","entity","kind"],body:`# Using entityKind
+
+## Building a reference
+
+\`\`\`ts
+import { asReferenceInstanceId, asReferenceKindId } from '@lssm/lib.contracts-spec/rich-reference';
+import { entityKind } from '@lssm/lib.contracts-spec/rich-reference/kinds/entity';
+
+const ref = {
+  kindId: asReferenceKindId('entity'),
+  id: asReferenceInstanceId('user-42'),
+  payload: { slug: 'user', id: 'user-42', label: 'Ada Lovelace' },
+  redactionState: 'unredacted',
+} satisfies RichReference<EntityPayload>;
+\`\`\`
+
+## Resolving the entity spec
+
+\`\`\`ts
+import { resolveEntitySpec } from '@lssm/lib.contracts-spec/rich-reference/kinds/entity';
+
+const spec = resolveEntitySpec(ref.payload, registry);
+// spec is ContractEntitySpec | undefined
+\`\`\`
+
+\`sensitiveFields\` for \`entityKind\` are \`['id', 'label', 'url']\`. The RichReference runtime
+will redact these fields based on the active KindPolicy.`}},{id:"docs.contracts-spec.rich-reference.resolve",exportName:"ReferenceResolveDocBlock",sourceModule:"operations/reference-resolve",block:{id:"docs.contracts-spec.rich-reference.resolve",title:"Resolve rich references",summary:"Batch-resolve `(kindId, id)` references into governed RichReference payloads.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/rich-reference/resolve",tags:["rich-reference","governance","batch"],body:`# reference.resolve
+
+Returns one wire-form RichReference per request. Sensitive fields are replaced with HMAC-signed denial tokens per the active KindPolicy; unknown payload fields are stripped before propagation (F-1 mitigation).`}},{id:"docs.contracts-spec.rich-reference.usage",exportName:"richReferenceUsageDoc",sourceModule:"rich-reference/index",block:{id:"docs.contracts-spec.rich-reference.usage",title:"RichReference usage",summary:"Authoring kinds and wiring governance ports.",kind:"usage",visibility:"public",route:"/docs/contracts-spec/rich-reference/usage",tags:["rich-reference","authoring"],body:`# Authoring a reference kind
+
+\`\`\`ts
+import { defineReferenceKind } from '@lssm/lib.contracts-spec/rich-reference';
+import { z } from 'zod';
+
+export const ticketKind = defineReferenceKind({
+  id: 'ticket',
+  schema: z.object({ id: z.string(), title: z.string() }),
+  sensitiveFields: ['title'],
+  defaultPreview: 'inline-card',
+  defaultPanel: 'drawer',
+  icon: 'ticket',
+});
+\`\`\`
+
+\`sensitiveFields\` is required at the type level and at runtime; kinds with no sensitive fields MUST pass \`[]\` with an inline confirmation comment (F-4 mitigation).`}},{id:"docs.contracts-spec.structured-data",exportName:"StructuredDataDocBlock",sourceModule:"structured-data/kinds",block:{id:"docs.contracts-spec.structured-data",title:"Structured data (schema.org / JSON-LD)",summary:"Typed schema.org shapes + StructuredDataRef for route-level and derived JSON-LD.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/structured-data",tags:["structured-data","seo","json-ld"],body:"# Structured data\n\nTyped schema.org shapes for marketing surfaces. `@context` is added at emission\n(the Next lane); shapes here carry only `@type` + fields.\n\n- **Derivable** (`Organization`, `WebSite`, `SoftwareApplication`) come from\n  branding + app metadata via `structured-data/derive.ts`.\n- **Authored** (`Product`, `FAQPage`, `Article`, `BreadcrumbList`) are supplied\n  inline on a route via `route.seo.schemaOrg`.\n\nA `StructuredDataRef` is either `{ mode: 'inline', kind, data }` (kind↔shape\ncorrelated) or `{ mode: 'derive', kind }` for the derivable kinds."}},{id:"docs.customer-support.attachment-safety",exportName:"SupportAttachmentSafetyDocBlock",sourceModule:"customer-support/attachment-safety",block:{id:"docs.customer-support.attachment-safety",title:"SupportOS attachment safety",summary:"Reference-only attachment scan, quarantine, consent, and release evidence.",kind:"reference",visibility:"public",route:"/docs/customer-support/attachment-safety",tags:["supportos","attachments","security","communication-os"],body:`# SupportOS attachment safety
+
+CommunicationOS owns attachment bytes, storage, upload, download, and channel
+linkage. SupportOS stores only opaque attachment and evidence references. Its
+contracts never accept filenames, MIME claims, storage locations, digests, or
+file content from callers.
+
+Registration requires exact short-lived scanner, scope, case, attachment,
+consent, and request-digest evidence. Quarantined material is never released by
+scan state alone: release requires a separate state-bound governance decision.
+Mutations are idempotent and revision-fenced; projections and events remain
+body-free and safe for operational audit.
+`}},{id:"docs.customer-support.authority-errors",exportName:"SupportAuthorityErrorsDocBlock",sourceModule:"customer-support/errors",block:{id:"docs.customer-support.authority-errors",title:"SupportOS authority errors",summary:"Stable failures shared by SupportOS authority implementations.",kind:"reference",visibility:"public",route:"/docs/customer-support/authority-errors",tags:["supportos","authority","errors"],body:`# SupportOS authority errors
+
+Authority adapters throw \`SupportAuthorityError\` with a stable code. API
+transports map the code to their protocol without inspecting human-readable
+messages. Unknown adapter failures remain dependency failures and fail closed.
+`}},{id:"docs.customer-support.authos-session-authority",exportName:"SupportAuthOsSessionDocBlock",sourceModule:"customer-support/authos-session",block:{id:"docs.customer-support.authos-session-authority",title:"SupportOS AuthOS session authority",summary:"Short-lived, live-checked AuthOS grants for SupportOS authority.",kind:"reference",visibility:"public",route:"/docs/customer-support/authos-session-authority",tags:["supportos","authos","oidc","security"],body:`# SupportOS AuthOS session authority
+
+SupportOS accepts only short-lived AuthOS grants with a verified signature,
+issuer, SupportOS audience, temporal claims, token id, and session or workload
+identity. Every request checks AuthOS revocation/session status and current
+SupportOS membership. Effective capabilities are the intersection of the grant
+and live membership. Tenant and workspace authority never comes from request
+bodies or query parameters. Raw grants, cookies, and claims are excluded from
+logs and evidence.
+`}},{id:"docs.customer-support.case-assignments",exportName:"SupportCaseAssignmentsDocBlock",sourceModule:"customer-support/case-assignments",block:{id:"docs.customer-support.case-assignments",title:"SupportOS case assignments",summary:"Revision-fenced claim, release, assignment, and governed steal semantics.",kind:"reference",visibility:"public",route:"/docs/customer-support/case-assignments",tags:["supportos","assignment","collision","idempotency"],body:`# SupportOS case assignments
+
+Assignment mutations are scoped by authenticated tenant, workspace, and actor.
+Claim always derives the assignee from that actor. Release is limited to the
+current assignee or an administrator. Assign and steal require administrator
+authority, and steal also requires governed evidence. Every write is fenced by
+the case revision and a stable idempotency key. Durable authorities update the
+assignment projection and immutable case history atomically.
+
+The steal decision is verified server-side and bound to scope, case, target,
+revision, and expiry. Exact receipt replay does not require a still-live
+decision; any new or changed mutation does.
+
+An assign or steal mutation may bind a routing decision. Production authorities
+must revalidate the selected case, assignee, active team and membership, target
+queue, current policy revision, and live capacity, then consume that immutable
+decision exactly once in the assignment transaction. Authorities that cannot
+provide atomic decision consumption fail closed.
+`}},{id:"docs.customer-support.case-cursor",exportName:"SupportCaseCursorDocBlock",sourceModule:"customer-support/case-cursor",block:{id:"docs.customer-support.case-cursor",title:"SupportOS case cursor",summary:"Bounded, opaque keyset pagination cursor shared by authorities.",kind:"reference",visibility:"public",route:"/docs/customer-support/case-cursor",tags:["supportos","pagination","security"],body:`# SupportOS case cursor
+
+Case collections use one bounded opaque keyset cursor containing the canonical
+updated timestamp and case reference. Managed, self-hosted, and in-memory
+authorities use the same encoder and validator. Malformed, oversized, or stale
+shapes fail with the stable validation error and never become dependency
+outages.
+`}},{id:"docs.customer-support.case-lifecycle",exportName:"SupportCaseLifecycleDocBlock",sourceModule:"customer-support/case-lifecycle",block:{id:"docs.customer-support.case-lifecycle",title:"SupportOS durable case lifecycle",summary:"Revision-fenced snooze, automatic resume, and archive semantics.",kind:"reference",visibility:"public",route:"/docs/customer-support/case-lifecycle",tags:["supportos","cases","snooze","archive"],body:`# SupportOS durable case lifecycle
+
+Snooze and archive mutations derive authority from server context, require an
+idempotency key and current case revision, and append immutable events. Snooze
+persists the prior service state and atomically emits a fenced unsnooze job.
+Hosts must register the matching durable handler before enabling automatic
+resume. Archive is terminal and cannot be used as a substitute for erasure.
+`}},{id:"docs.customer-support.case-presence",exportName:"SupportCasePresenceDocBlock",sourceModule:"customer-support/case-presence",block:{id:"docs.customer-support.case-presence",title:"SupportOS case presence",summary:"Ephemeral, scope-bound collision awareness for case operators.",kind:"reference",visibility:"public",route:"/docs/customer-support/case-presence",tags:["supportos","presence","collision","realtime"],body:`# SupportOS case presence
+
+Presence is ephemeral coordination state, never durable case history. A server
+binds each opaque browser session to authenticated tenant, workspace, actor, and
+case authority. Heartbeat sequence numbers are monotonic, timestamps and expiry
+come from the server, and stale sessions disappear without an explicit leave.
+
+Portable projections expose counts only. They never expose actor, contact,
+message, answer, or note identifiers. Distributed adapters must preserve the
+same scope, sequence, TTL, and fail-closed authorization semantics.
+`}},{id:"docs.customer-support.case-relations",exportName:"SupportCaseRelationsDocBlock",sourceModule:"customer-support/case-relations",block:{id:"docs.customer-support.case-relations",title:"SupportOS case relations",summary:"Atomic, revision-fenced merge, split, and link evidence between support cases.",kind:"reference",visibility:"public",route:"/docs/customer-support/case-relations",tags:["supportos","cases","relations","idempotency"],body:`# SupportOS case relations
+
+Case relations are immutable evidence edges. Both cases belong to the
+server-derived tenant and workspace, both revisions are fenced, and both case
+histories advance atomically. Implementations lock case rows in canonical order
+to prevent deadlocks. Exact idempotent replays return the original receipt;
+changed input fails closed. Relation records contain opaque references and
+evidence references only. CommunicationOS message and attachment bodies are
+never copied into SupportOS relation evidence.
+
+The original one-revision relation input remains available as a deprecated
+compatibility surface. Managed execution requires the strict mutation input,
+including the related-case revision and a stable relation reference.
+`}},{id:"docs.customer-support.crypto-lifecycle",exportName:"SupportCryptoLifecycleDocBlock",sourceModule:"customer-support/crypto-lifecycle",block:{id:"docs.customer-support.crypto-lifecycle",title:"SupportOS cryptographic lifecycle",summary:"Versioned envelope keys, scoped hashes, rotation, and secret refs.",kind:"reference",visibility:"public",route:"/docs/customer-support/crypto-lifecycle",tags:["supportos","security","kms","rotation"],body:`# SupportOS cryptographic lifecycle
+
+Production data protection uses versioned envelope keys. Ciphertext identifies
+the non-secret key reference and version needed to unwrap its data key; raw
+master keys and secret values never enter persisted contracts or telemetry.
+Authenticated context binds tenant, workspace, purpose, and data class.
+Rotation creates a new active version, preserves decrypt-only predecessors,
+and rewraps data keys through an idempotent, fenced, evidence-bearing workflow.
+Scoped lookup hashes use a distinct key purpose and cannot be reused as
+encryption or signing keys. Plaintext data keys are ephemeral, explicitly
+destroyable runtime values. Secret references are scope-bound metadata only.
+`}},{id:"docs.customer-support.crypto-rotation",exportName:"SupportCryptoRotationDocBlock",sourceModule:"customer-support/crypto-rotation",block:{id:"docs.customer-support.crypto-rotation",title:"SupportOS durable cryptographic rotation",summary:"Fenced key rotation and opaque online re-encryption evidence.",kind:"reference",visibility:"public",route:"/docs/customer-support/crypto-rotation",tags:["supportos","security","kms","rotation","worker"],body:`# SupportOS durable cryptographic rotation
+
+Rotation plans bind a server-derived scope, cryptographic context, active key,
+region, policy evidence, and immutable request digest. A plan never contains raw
+keys, secrets, ciphertext, or protected values. Advancing a plan is revision and
+fencing-token guarded. Online re-encryption jobs carry only opaque plan and
+cursor references and use stable downstream idempotency keys. Production
+qualification requires a managed KMS adapter, restore and rollback drills, and
+digest-bound evidence; fixture receipts never qualify those gates.
+`}},{id:"docs.customer-support.csat",exportName:"SupportCsatDocBlock",sourceModule:"customer-support/csat",block:{id:"docs.customer-support.csat",title:"SupportOS satisfaction evidence",summary:"Forms-verified satisfaction scores with immutable, privacy-safe provenance.",kind:"reference",visibility:"public",route:"/docs/customer-support/csat",tags:["supportos","csat","forms","privacy","reporting"],body:`# SupportOS satisfaction evidence
+
+SupportOS stores the canonical score and opaque Forms definition, response,
+revision, and stable score-question references. It never copies form answers or
+free-text feedback. A server-side Forms verifier must echo the exact case,
+definition, response, revision, score question, score, locale, and channel and
+return immutable evidence before a score is accepted.
+
+Recording is revision-fenced and idempotent. Reports use a fixed watermark and
+keyset pagination. Tenant and workspace authority always comes from the
+authenticated server context, never the request body.
+`}},{id:"docs.customer-support.csat-surveys",exportName:"SupportCsatSurveyDocBlock",sourceModule:"customer-support/csat-surveys",block:{id:"docs.customer-support.csat-surveys",title:"SupportOS CSAT survey eligibility",summary:"Forms-authoritative, body-free CSAT invitation denominator evidence.",kind:"reference",visibility:"public",route:"/docs/customer-support/csat-surveys",tags:["supportos","csat","forms","privacy","reporting"],body:`# SupportOS CSAT survey eligibility
+
+Forms decides whether a case is eligible and issues the survey invitation.
+SupportOS persists only opaque survey, case, form revision, policy, and evidence
+references plus channel, locale, a database-issued timestamp, and immutable
+replay evidence. It never receives answers, identity, message bodies, or free
+text.
+
+Forms calls the service-only record-issued operation after issuance and retries
+the stable idempotency key until SupportOS returns the immutable receipt.
+
+The exact invitation is the reporting denominator for CSAT response rate.
+Global and workspace rollout, live membership, current case revision, and exact
+Forms evidence are rechecked fail closed.
+`}},{id:"docs.customer-support.customer-session-consent",exportName:"SupportCustomerSessionConsentDocBlock",sourceModule:"customer-support/customer-session-consent",block:{id:"docs.customer-support.customer-session-consent",title:"SupportOS customer sessions and consent",summary:"Short-lived public sessions, immutable consent receipts, abuse minimization, and authenticated upgrade.",kind:"reference",visibility:"public",route:"/docs/customer-support/customer-session-consent",tags:["supportos","customer","session","consent","security"],body:`# Customer sessions and consent
+
+Hosts issue opaque public-access tokens from an authenticated workspace context.
+Public clients exchange the token for a short-lived session and rotate it with an
+exact revision fence. Authorities persist only scoped token hashes and rotating
+abuse identifiers; raw tokens, IP addresses, messages, answers, and contact data
+never enter session evidence.
+
+Consent is append-only, purpose-specific, localized, and bound to the exact
+policy reference and notice digest shown to the customer. Withdrawal supersedes
+an earlier grant without deleting its audit receipt. Authenticated upgrade uses
+the server-derived AuthOS principal and assurance evidence; public request bodies
+cannot choose tenant, workspace, principal, or capabilities.
+`}},{id:"docs.customer-support.data-lifecycle",exportName:"SupportDataLifecycleDocBlock",sourceModule:"customer-support/data-lifecycle",block:{id:"docs.customer-support.data-lifecycle",title:"SupportOS governed data lifecycle",summary:"Retention, legal holds, and cross-owner subject erasure.",kind:"reference",visibility:"public",route:"/docs/customer-support/data-lifecycle",tags:["supportos","retention","legal-hold","erasure","privacy"],body:`# SupportOS governed data lifecycle
+
+Retention policy, legal holds, and erasure requests derive scope from authenticated server authority. Erasure and subject-level holds begin from a revision-fenced case; the server derives the requester closure and never accepts an arbitrary subject target. Subject references are protected immediately; portable projections expose only a scoped digest. Active holds fail closed and remain visible.
+
+Erasure is durable, idempotent, and evidence-bound across SupportOS, CommunicationOS, Forms, Knowledge, and CompanyOS. Each owner remains authoritative for its data. Completion requires terminal evidence from every owner, removal of the protected orchestration subject, and an immutable tombstone that prevents provider resurrection.`}},{id:"docs.customer-support.durable-job-contract",exportName:"SupportDurableJobContractDocBlock",sourceModule:"customer-support/job-runtime",block:{id:"docs.customer-support.durable-job-contract",title:"SupportOS durable job contract",summary:"Fenced, tenant-scoped background work for managed and self-hosted cells.",kind:"reference",visibility:"public",route:"/docs/customer-support/durable-jobs",tags:["supportos","operations","jobs"],body:`# SupportOS durable jobs
+
+Claims are bounded and carry monotonically increasing fencing tokens. Completion,
+retry, pause, and dead-letter settlement reject stale or expired leases. Pause
+returns deliberately disabled work to the queue without consuming an attempt.
+Abort signals
+cancel active claims; an aborted handler leaves its lease unsettled for
+expiry-based recovery. Delivery is at-least-once: handlers pass a stable effect
+idempotency key to every downstream mutation. Payloads remain protected
+references, and database time is authoritative for lease validity. Export
+artifact cleanup uses the dedicated export.artifact.cleanup kind so exact-version
+deletion, tombstones, retries, and readiness remain independently observable.
+`}},{id:"docs.customer-support.exports",exportName:"SupportExportDocBlock",sourceModule:"customer-support/exports",block:{id:"docs.customer-support.exports",title:"SupportOS audited asynchronous exports",summary:"Snapshot-pinned, permission-separated SupportOS CSV exports.",kind:"reference",visibility:"public",route:"/docs/customer-support/exports",tags:["supportos","exports","csv","privacy","audit"],body:"# SupportOS audited exports\n\nExports are asynchronous, immutable-snapshot jobs. Redacted and sensitive permissions are separate, every mutation is idempotent and revision/fence-bound, and public projections never expose storage locators. Retrieval uses a separate `support.export-downloads` capability and authority. The public handoff contains only an opaque token and canonical relative path, expires within five minutes, and permits at most three exact idempotent downloads. Internal authorizations bind tenant, workspace, actor, export revision, immutable artifact version, digest, byte count, storage evidence, and ordinal without exposing provider URLs. Streams are explicitly authorized then settled as completed, aborted, or failed so partial delivery is audited accurately. Access can be revoked, and protected storage supports bounded streaming writes, exact-version reads, exact deletion, tombstones, and readiness. The cases export schema intentionally contains no message body, note body, form answer, attachment payload, or download URL. CSV writers emit UTF-8 and neutralize spreadsheet formulas."}},{id:"docs.customer-support.identity-resolution",exportName:"SupportIdentityResolutionDocBlock",sourceModule:"customer-support/identity-resolution",block:{id:"docs.customer-support.identity-resolution",title:"SupportOS identity resolution",summary:"Scoped-hash identity matching with explainable, governed, reversible merge edges.",kind:"reference",visibility:"public",route:"/docs/customer-support/identity-resolution",tags:["supportos","identity","privacy","governance","deduplication"],body:`# SupportOS identity resolution
+
+SupportOS never accepts or persists raw email addresses, phone numbers, or
+provider identifiers for matching. An injected server-side evidence port
+resolves an opaque source identity into a tenant/workspace-scoped lookup hash,
+key version, evidence reference, and short expiry. Hashes are never returned by
+public queries or emitted in events.
+
+Matches are candidates, not automatic merges. Operators review redacted profile
+and candidate references. Merge and reversal operations require exact,
+state-bound governance decisions covering scope, profiles, candidates, digest,
+and expiry. A merge creates an immutable reversible graph edge; it does not copy,
+delete, or rewrite profile fields or CommunicationOS identities.
+
+Every mutation is idempotent and revision-fenced. Evidence is immutable,
+tenant/workspace authority comes only from authenticated server context, and
+key rotation must preserve version-addressed lookup until reindexing completes.
+`}},{id:"docs.customer-support.internal-notes",exportName:"SupportInternalNotesDocBlock",sourceModule:"customer-support/internal-notes",block:{id:"docs.customer-support.internal-notes",title:"SupportOS internal-note evidence",summary:"Private immutable case-note evidence without duplicating CommunicationOS message content.",kind:"reference",visibility:"public",route:"/docs/customer-support/internal-notes",tags:["supportos","cases","notes","communicationos","privacy"],body:`# SupportOS internal-note evidence
+
+CommunicationOS remains authoritative for private note content. SupportOS stores
+only bounded note and evidence references, actor and case revision fencing,
+policy/evidence references, and an immutable timestamp. Note bodies are rejected
+from the semantic contract, persistence, events, telemetry, and list projection.
+
+The compose operation is the sole exception at the transport boundary: SupportOS
+may forward a bounded body directly to CommunicationOS, but never persists,
+events, logs, traces, or returns it. Before forwarding, SupportOS persists a
+body-free intent bound to authenticated scope, case revision, idempotency, and a
+server-issued policy decision. CommunicationOS emits a redacted, intent-bound
+delivery that SupportOS can reconcile after crashes without recovering content.
+
+Creation requires a server-derived workspace scope, case-write permission,
+idempotency, the current case revision, and a CommunicationOS verifier receipt
+that proves the referenced note is private and linked to the same case. Missing,
+mismatched, public, or unavailable verification fails closed. Lists require
+case-read permission, use a bounded keyset cursor, and remain pinned to a stable
+watermark.
+
+Reconciliation is idempotent and explicit. Expired or revoked policy, stale case
+revision, mismatched scope/case/actor, and unavailable dependencies produce a
+visible needs-review or failed state; they never silently attach or discard a
+CommunicationOS note. Composer, delivery, reconciliation worker, and read paths
+remain behind independent global-and-workspace rollout controls.
+`}},{id:"docs.customer-support.live-chat-continuity",exportName:"SupportLiveChatContinuityDocBlock",sourceModule:"customer-support/live-chat-continuity",block:{id:"docs.customer-support.live-chat-continuity",title:"Customer live-chat continuity",summary:"Short-lived immutable session-to-conversation grants.",kind:"reference",visibility:"public",route:"/docs/customer-support/live-chat-continuity",tags:["supportos","customer","session","live-chat","security"],body:`# Customer live-chat continuity
+
+A customer session may receive a short-lived grant for one exact existing case
+conversation and room. The grant never carries operator, queue, reporting, or
+workload capability. Session rotation, revocation, expiry, or case revision
+change invalidates the grant. Evidence contains opaque references only; message
+bodies and transport tokens are prohibited. Binding requires an independently
+created canonical case/conversation link plus an immutable relation-authority
+receipt; existence of a CommunicationOS room is never ownership evidence.`}},{id:"docs.customer-support.membership-administration",exportName:"SupportMembershipAdministrationDocBlock",sourceModule:"customer-support/memberships",block:{id:"docs.customer-support.membership-administration",title:"SupportOS workspace membership administration",summary:"Revision-fenced, least-privilege membership grants and revocation for SupportOS workspaces.",kind:"reference",visibility:"public",route:"/docs/customer-support/membership-administration",tags:["supportos","authos","membership","security"],body:`# SupportOS workspace membership administration
+
+Tenant and workspace authority comes only from the live AuthOS scope. Public
+inputs carry opaque principal references, typed roles and capabilities,
+expected revisions, policy references, evidence references, and caller-stable
+idempotency. Roles are versioned presets; the frozen capability projection is
+the sole authorization input. Role changes never silently expand an existing
+membership.
+
+Create, grant replacement, and revocation are distinct. Principal kind is
+immutable, revoked memberships never reactivate implicitly, self-mutation and
+last-administrator removal fail closed, and privileged grants require a Connect
+decision reference. A server-side governance port binds the authenticated actor,
+workspace, operation, expected revision, exact current and proposed membership
+state digests, policy, and claimed evidence to the authorization digest. The
+authority recomputes both state digests and rechecks approval expiry after its
+database fence; client references are never treated as approval by themselves.
+Exact replays return the original immutable receipt while changed input is rejected.
+
+Authorized administrators can read a redacted immutable event timeline through
+stable-watermark keyset pagination. The projection excludes request bodies,
+session claims and provider tokens while retaining opaque actor, policy and
+governance evidence references needed for review and replay.
+`}},{id:"docs.customer-support.metadata",exportName:"SupportMetadataDocBlock",sourceModule:"customer-support/metadata",block:{id:"docs.customer-support.metadata",title:"SupportOS tags and custom fields",summary:"Localized metadata definitions and protected case values.",kind:"reference",visibility:"public",route:"/docs/customer-support/metadata",tags:["supportos","metadata","tags","custom-fields","privacy"],body:`# SupportOS tags and custom fields
+
+Tag and field definitions are localized, revision-fenced, and workspace scoped.
+Case metadata replacement is atomic with the case revision and immutable event
+evidence. Scalar and option values are canonical and locale independent.
+
+Case values are encrypted through the injected data-protection port; plaintext
+values never enter database events, audit rows, outbox payloads, logs, or
+idempotency receipts. Sensitive reads require an explicit capability. Lists use
+fixed-watermark keyset pagination and tenant/workspace authority comes only from
+authenticated server context.
+`}},{id:"docs.customer-support.notifications",exportName:"SupportNotificationDocBlock",sourceModule:"customer-support/notifications",block:{id:"docs.customer-support.notifications",title:"SupportOS notification evidence",summary:"Preference-aware, body-free notification intent and CommunicationOS delivery evidence.",kind:"reference",visibility:"public",route:"/docs/customer-support/notifications",tags:["supportos","notifications","communication-os","privacy"],body:`# SupportOS notification evidence
+
+SupportOS owns notification preferences, intent, escalation policy, and durable
+delivery evidence. CommunicationOS owns channel identity, rendered message
+content, provider delivery, and attachments. Notification contracts contain
+only opaque party, template, source-event, policy, and delivery references;
+message bodies, contact destinations, provider payloads, and credentials are
+never copied into SupportOS.
+
+Mutations derive tenant and workspace authority from authenticated server
+context, require idempotency and revision fencing, and persist immutable audit
+evidence. Collection reads use keyset pagination and a stable watermark.
+Delivery failure never silently downgrades a required escalation.
+Durable workers resolve only a body-free dispatch projection by opaque
+notification reference, pass a stable effect-idempotency key to the channel
+authority, and record exact delivery evidence before completing the fenced job.
+`}},{id:"docs.customer-support.opa-handoffs",exportName:"SupportOpaHandoffsDocBlock",sourceModule:"customer-support/opa-handoffs",block:{id:"docs.customer-support.opa-handoffs",title:"SupportOS to OPA handoffs",summary:"Consent-bound public profile and booking handoffs owned by OPA.",kind:"reference",visibility:"public",route:"/docs/customer-support/opa-handoffs",tags:["supportos","opa","booking","profile","consent"],body:`# SupportOS to OPA handoffs
+
+SupportOS stores only opaque destination references, an explicit consent receipt,
+and redacted lifecycle evidence. OPA resolves the canonical public HTTPS URL and
+retains profile, availability, booking, calendar, and provider authority.
+`}},{id:"docs.customer-support.operations",exportName:"CustomerSupportOperationsDocBlock",sourceModule:"customer-support/operations",block:{id:"docs.customer-support.operations",title:"SupportOS operations",summary:"Semantic SupportOS commands and their transport bindings.",kind:"reference",visibility:"public",route:"/docs/customer-support/operations",tags:["supportos","operations","http"],body:`# SupportOS operations
+
+The contracts are transport-neutral. The HTTP adapter derives tenant and
+workspace authority from the authenticated session, reads \`caseRef\` from the
+path for transitions, reads \`idempotencyKey\` from the Idempotency-Key header,
+and validates the remaining semantic fields from the JSON body. Mutation
+outputs may include a redacted \`projection\`; sensitive case content is never
+required in a receipt. Stable error keys are mapped to protocol status codes.
+`}},{id:"docs.customer-support.reporting",exportName:"SupportReportingDocBlock",sourceModule:"customer-support/reporting-doc",block:{id:"docs.customer-support.reporting",title:"SupportOS privacy-safe case reporting",summary:"Immutable report definitions and aggregate-only case outcome analytics.",kind:"reference",visibility:"public",route:"/docs/customer-support/reporting",tags:["supportos","reporting","analytics","privacy"],body:`# SupportOS reporting
+
+Report definitions are immutable revisions. Definition reads default to the active published revision; administrators may explicitly request the current head while editing a draft without hiding or changing the published report. Queries pin an exact revision, timezone-data revision, and stable fact-sequence watermark. First-page requests omit both cursor and watermark; continuation requests provide both. Results contain aggregate cells and opaque references only; raw case, message, note, answer, attachment, identity, and AI content are forbidden. Minimum-cohort suppression applies to every projection, including sensitive reporting. A query projection cannot exceed the definition maximumProjection, and sensitive access additionally requires an explicit support.reporting.sensitive grant. Correction and outcome event time is assigned by the authority database clock. Aggregate CSV exports bind the immutable query receipt and watermark, then reuse the governed export artifact and protected-download pipeline.`}},{id:"docs.customer-support.routing-administration",exportName:"SupportRoutingAdministrationDocBlock",sourceModule:"customer-support/routing-administration",block:{id:"docs.customer-support.routing-administration",title:"SupportOS teams and queues",summary:"Revision-fenced, tenant-scoped team and queue administration for SupportOS routing.",kind:"reference",visibility:"public",route:"/docs/customer-support/routing-administration",tags:["supportos","routing","teams","queues"],body:`# SupportOS teams and queues
+
+Team and queue administration is scoped exclusively by authenticated tenant,
+workspace, and actor authority. Mutations use caller-stable idempotency keys,
+expected revisions, server timestamps, and immutable evidence receipts. Exact
+replays return the original projection; changed input fails closed.
+
+Queue team references and fallback queues must resolve inside the same
+workspace. Self-fallback and fallback cycles are invalid. Archiving a referenced
+team or queue is rejected until dependants are migrated. Lists use stable-
+watermark keyset pagination and expose opaque references only.
+`}},{id:"docs.customer-support.runtime-readiness",exportName:"SupportRuntimeReadinessDocBlock",sourceModule:"customer-support/platform-ports",block:{id:"docs.customer-support.runtime-readiness",title:"SupportOS runtime readiness",summary:"Truthful dependency readiness for managed and self-hosted cells.",kind:"reference",visibility:"public",route:"/docs/customer-support/runtime-readiness",tags:["supportos","operations","readiness"],body:`# SupportOS runtime readiness
+
+Liveness proves only that the API process can answer. Readiness is a fresh,
+bounded projection of required migrations, database, worker, queue, feature
+flag, and adapter checks. A missing port or any required non-ready check fails
+closed. Callers provide an abort signal so timed-out checks release database and
+provider resources. Evidence references must not contain credentials or
+customer data.
+`}},{id:"docs.customer-support.search-views",exportName:"SupportSearchViewsDocBlock",sourceModule:"customer-support/search-views",block:{id:"docs.customer-support.search-views",title:"SupportOS case search and saved views",summary:"Permission-aware redacted case discovery and revisioned operator views.",kind:"reference",visibility:"public",route:"/docs/customer-support/search-views",tags:["supportos","search","saved-views","privacy","pagination"],body:`# SupportOS case search and saved views
+
+Search authority is derived from authenticated tenant and workspace context. A
+client cannot provide either scope. Results are redacted case-operational
+projections and never include subjects, requester identities, messages,
+answers, notes, or protected values.
+
+Free-text matching is limited to case numbers and explicitly indexed,
+non-sensitive operational references. It never searches protected subjects,
+requester identifiers, message or note content, form answers, or attachment
+content.
+
+Filters are typed and bounded. Every result set is pinned to a server-issued
+watermark and traversed with opaque keyset cursors. Saved-view mutations require
+idempotency, optimistic revision fencing, and immutable event receipts. Private
+views are visible only to their owner; workspace views require scoped read and
+write capabilities. Public saved-view v2 projections omit owner identity and
+expose only the server-derived canMutate decision needed for operator controls.
+`}},{id:"docs.customer-support.service-profile",exportName:"SupportServiceProfileDocBlock",sourceModule:"customer-support/service-profile",block:{id:"docs.customer-support.service-profile",title:"SupportOS service profiles",summary:"Consent-bound, encrypted customer context with redacted operator projections.",kind:"reference",visibility:"public",route:"/docs/customer-support/service-profiles",tags:["supportos","customer-context","privacy","consent","encryption"],body:`# SupportOS service profiles
+
+SupportOS stores only opaque party references and an encrypted field envelope.
+It never becomes the authority for CommunicationOS identities, CompanyOS graph
+entities, Billing entitlements, or raw provider records.
+
+Every write is revision-fenced and idempotent. A server-injected verifier binds
+the exact party, segment, entitlement, consent, source-evidence, and input digest
+before persistence. Missing, expired, mismatched, or unavailable evidence fails
+closed. Immutable events store only field keys and verified evidence references.
+
+The default operator projection exposes opaque references, classifications, and
+available field keys, not encrypted references or field values. Sensitive reads
+require a separate permission and are audited. Tenant and workspace authority
+always comes from authenticated server context.
+`}},{id:"docs.customer-support.skills-routing",exportName:"SupportSkillsRoutingDocBlock",sourceModule:"customer-support/skills-routing",block:{id:"docs.customer-support.skills-routing",title:"Deterministic skills routing",summary:"Pure, capacity-aware and replayable SupportOS operator selection without assignment effects.",kind:"reference",visibility:"public",route:"/docs/customer-support/skills-routing",tags:["supportos","routing","skills","capacity","fairness"],body:`# Deterministic skills routing
+
+The skills-routing evaluator is a pure decision function. The protected
+SupportOS authority derives bounded candidate projections from active teams,
+live memberships and assignment load under a revision-pinned policy. Public
+clients never supply candidates or workspace authority. It filters exclusions,
+availability, capacity and required skills before applying
+preferred-team, load, oldest-assignment and stable-reference ordering.
+
+Policy mutations are revision-fenced and idempotent. Simulations freeze their
+policy revision, input digest, candidate watermark and explainable trace in
+immutable evidence. Optional skill fallback is
+explicit in both the policy and result. The evaluator never assigns a case or
+executes effects; assignment remains owned by the SupportOS assignment authority
+and must persist the accepted decision and policy evidence separately.
+`}},{id:"docs.customer-support.sla-administration",exportName:"SupportSlaAdministrationDocBlock",sourceModule:"customer-support/sla-administration",block:{id:"docs.customer-support.sla-administration",title:"SupportOS SLA administration",summary:"Revision-fenced SLA policies and database-time clock lifecycle contracts.",kind:"reference",visibility:"public",route:"/docs/customer-support/sla-administration",tags:["supportos","sla","business-hours","escalation"],body:`# SupportOS SLA administration
+
+SLA authority is tenant and workspace scoped by the authenticated server
+context. Policies are revision-fenced and immutable evidence receipts make
+exact replays distinguishable from changed-input conflicts.
+
+Canonical clock mutations are target-bound so first-response and resolution
+deadlines cannot alias one another. Version 2 remains discoverable for pinned
+clients; new authority implementations accept the strict version 3 shape.
+
+Clock scheduling uses database time. Business-hours resolution is supplied by
+an approved server adapter, and unavailable calendars fail closed. A breach is
+recorded exactly once before a pinned Workflow/SOP escalation is requested;
+the SLA runtime never performs consequential business effects directly.
+`}},{id:"docs.customer-support.slo-incident",exportName:"SupportSloIncidentDocBlock",sourceModule:"customer-support/slo-incident-doc",block:{id:"docs.customer-support.slo-incident",title:"SupportOS SLO and incident authority",summary:"Privacy-safe SLO evidence, incident lifecycle, paging, and review contracts.",kind:"reference",visibility:"public",route:"/docs/customer-support/slo-incident",tags:["supportos","slo","incident","operations"],body:`# SupportOS SLO and incident authority
+
+Public inputs never carry tenant, workspace, actor, timestamps, computed
+verdicts, or receipt authority. SLO evidence separates API and customer-surface
+availability windows and binds a stable source digest to opaque telemetry,
+incident, and drill references. Incident mutations are revision-fenced and
+idempotent; lifecycle actions contain only typed taxonomy and opaque references,
+never narrative, customer content, destinations, or provider payloads. Lists
+use bounded keyset cursors and a stable server watermark. Fixture evidence
+proves deterministic behavior but never qualifies production SLO, alert
+delivery, paging coverage, drills, or canaries.
+`}},{id:"docs.customer-support.workspace-administration",exportName:"SupportWorkspaceAdministrationDocBlock",sourceModule:"customer-support/workspace-administration",block:{id:"docs.customer-support.workspace-administration",title:"SupportOS workspace topology administration",summary:"Revision-fenced brand, product, host, locale, and residency provenance for SupportOS workspaces.",kind:"reference",visibility:"public",route:"/docs/customer-support/workspace-administration",tags:["supportos","workspace","topology","residency"],body:`# SupportOS workspace topology administration
+
+Tenant and workspace identifiers come only from authenticated server context.
+Configuration records the exact product, host, brand, locale, and residency
+provenance for an isolated or pooled workspace. Brand bindings are unique and
+complete, the default locale must be enabled, and every mutation requires an
+idempotency key, expected revision, policy evidence, and immutable receipt.
+
+This contract configures one workspace. Moving data between isolated and pooled
+workspaces uses the separately fenced migration planner and ledger; changing the
+mode here never implies that cases, identities, messages, or attachments moved.
+`}},{id:"docs.customer-support.workspace-brand-locale-residency",exportName:"SupportWorkspaceBrandLocaleResidencyDocBlock",sourceModule:"customer-support/workspace-brand-locale-residency",block:{id:"docs.customer-support.workspace-brand-locale-residency",title:"SupportOS workspace brand, locale, and residency policy",summary:"Topology-bound branding, localization, residency, and non-relaxing inherited policy evidence.",kind:"reference",visibility:"public",route:"/docs/customer-support/workspace-brand-locale-residency",tags:["supportos","workspace","brand","locale","residency"],body:`# Workspace brand, locale, and residency policy
+
+The aggregate is bound to one exact workspace topology revision. Its brand set,
+locale set, and residency region must exactly match that topology. Locale
+fallbacks are acyclic. Global, tenant, and workspace policy layers are ordered
+and may only narrow their predecessor. Artifact verification is provider-neutral
+and expires. Reads expose topology drift as \`stale-topology\`; callers cannot
+mistake stale configuration for current policy.
+`}},{id:"docs.customer-support.workspace-migration",exportName:"SupportWorkspaceMigrationDocBlock",sourceModule:"customer-support/workspace-migration",block:{id:"docs.customer-support.workspace-migration",title:"SupportOS workspace topology migration",summary:"Collision-previewed, governed, fenced, resumable, and reversible workspace topology migration.",kind:"reference",visibility:"public",route:"/docs/customer-support/workspace-migration",tags:["supportos","workspace","migration","rollback"],body:`# SupportOS workspace topology migration
+
+Preview persists the exact original and target topology plus deterministic
+collision findings. Start and rollback require a state-bound Connect decision.
+Advance uses a monotonic plan fence, is resumable, and records immutable step evidence.
+Blocking collisions prevent execution. Completed topology never implies that
+CommunicationOS messages, Forms answers, or Knowledge content changed owner.
+`}},{id:"docs.customer-support.workspace-onboarding",exportName:"SupportWorkspaceOnboardingDocBlock",sourceModule:"customer-support/workspace-onboarding",block:{id:"docs.customer-support.workspace-onboarding",title:"SupportOS isolated workspace onboarding",summary:"Atomic tenant-authorized creation of an isolated workspace and its founding administrator.",kind:"reference",visibility:"public",route:"/docs/customer-support/workspace-onboarding",tags:["supportos","workspace","onboarding","authos","connect"],body:`# SupportOS isolated workspace onboarding
+
+Onboarding uses a short-lived tenant bootstrap grant because a live workspace
+membership cannot exist before the workspace is created. Tenant, workspace,
+actor, and principal kind come only from authenticated server context; none is
+accepted in the operation body. The grant must carry the dedicated
+support.workspace.onboard capability and immutable authority evidence.
+
+One transaction creates an isolated, single-brand workspace and its founding
+support administrator. Exact retries replay a digest-bound receipt. Conflicting
+workspace identities, stale or revoked Connect decisions, disabled rollout, or
+partial writes fail closed. The bootstrap capability is not persisted as a
+delegable workspace capability.
+`}},{id:"docs.harness.browser-structured-reads",exportName:"HarnessBrowserStructuredReadsDocBlock",sourceModule:"harness/harness.feature",block:{id:"docs.harness.browser-structured-reads",title:"Harness browser structured reads",summary:"Keyed browser get actions collect exact deterministic values while legacy unkeyed reads remain output-neutral.",kind:"reference",visibility:"public",route:"/docs/harness/browser-structured-reads",tags:["harness","browser","playwright","structured-output"],body:"## Keyed reads\n\nAdd a non-empty `key` to a browser `get` action to collect its result in\nthe step output. Keyed reads execute in authored order and return a plain object\nwhose keys preserve that order. Values are strings, except a successful\n`text` read may return `null`.\n\n- `text`, `html`, and `value` require a selector.\n- `title` and `url` reject selectors.\n- Empty or duplicate keys and unsupported browser methods fail the step without\n  returning partial output.\n- Unkeyed `get` actions remain legacy no-ops and do not create step output.\n\nHarness `json-match` assertions compare this object with exact deep equality;\nthey do not coerce values or ignore missing, extra, or mistyped fields.\n\n## Deterministic Playwright execution\n\nBefore navigation or interaction, the Playwright adapter verifies support for\nall requested actions, viewport changes and keyed reads. Missing capabilities\nfail setup; double-click never degrades to click, and typing never degrades to\nfill. Text waits wait for visible matching text. Legacy unkeyed reads retain\ntheir documented output-neutral behavior.\n\nA non-empty domain allowlist requires an isolated browser context with HTTP and\nWebSocket routing installed before navigation and service workers disabled.\nBlocked requests fail the run; failed setup closes partially created resources.\nBrowser routing is a QA guard, not an OS network sandbox: the execution host\nmust independently enforce the quality environment network policy, including\nredirect destinations, DNS and protocols outside browser routing."}},{id:"docs.meta.docblocks-process",exportName:"metaDocs",sourceModule:"docs/docs.feature",block:{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.`}},{id:"docs.tech.acp.fs.access",exportName:"AcpFsAccessDocBlock",sourceModule:"acp/commands/acpFsAccess.command",block:{id:"docs.tech.acp.fs.access",title:"ACP file system access",summary:"Access file system through ACP.",kind:"reference",visibility:"public",route:"/docs/tech/acp/fs/access",tags:["acp","filesystem"],body:`# acp.fs.access
+
+Performs file system access with policy gating.
+`}},{id:"docs.tech.acp.prompt.turn",exportName:"AcpPromptTurnDocBlock",sourceModule:"acp/commands/acpPromptTurn.command",block:{id:"docs.tech.acp.prompt.turn",title:"ACP prompt turn",summary:"Execute a prompt turn within a session.",kind:"reference",visibility:"public",route:"/docs/tech/acp/prompt/turn",tags:["acp","prompt"],body:`# acp.prompt.turn
+
+Runs a prompt turn and returns structured outputs and tool calls.
+`}},{id:"docs.tech.acp.session.init",exportName:"AcpSessionInitDocBlock",sourceModule:"acp/commands/acpSessionInit.command",block:{id:"docs.tech.acp.session.init",title:"ACP session init",summary:"Initialize a new ACP session.",kind:"reference",visibility:"public",route:"/docs/tech/acp/session/init",tags:["acp","session"],body:`# acp.session.init
+
+Creates a new ACP session and returns session metadata.
+`}},{id:"docs.tech.acp.session.resume",exportName:"AcpSessionResumeDocBlock",sourceModule:"acp/commands/acpSessionResume.command",block:{id:"docs.tech.acp.session.resume",title:"ACP session resume",summary:"Resume an existing ACP session.",kind:"reference",visibility:"public",route:"/docs/tech/acp/session/resume",tags:["acp","session"],body:`# acp.session.resume
+
+Resumes a previously initialized ACP session.
+`}},{id:"docs.tech.acp.session.stop",exportName:"AcpSessionStopDocBlock",sourceModule:"acp/commands/acpSessionStop.command",block:{id:"docs.tech.acp.session.stop",title:"ACP session stop",summary:"Stop an ACP session.",kind:"reference",visibility:"public",route:"/docs/tech/acp/session/stop",tags:["acp","session"],body:`# acp.session.stop
+
+Stops an active ACP session with audit trails.
+`}},{id:"docs.tech.acp.terminal.exec",exportName:"AcpTerminalExecDocBlock",sourceModule:"acp/commands/acpTerminalExec.command",block:{id:"docs.tech.acp.terminal.exec",title:"ACP terminal exec",summary:"Execute terminal commands via ACP.",kind:"reference",visibility:"public",route:"/docs/tech/acp/terminal/exec",tags:["acp","terminal"],body:`# acp.terminal.exec
+
+Executes terminal commands in a governed ACP session.
+`}},{id:"docs.tech.acp.tool.calls",exportName:"AcpToolCallsDocBlock",sourceModule:"acp/commands/acpToolCalls.command",block:{id:"docs.tech.acp.tool.calls",title:"ACP tool calls",summary:"Execute ACP tool calls.",kind:"reference",visibility:"public",route:"/docs/tech/acp/tool/calls",tags:["acp","tools"],body:`# acp.tool.calls
+
+Executes tool calls with governance and telemetry.
+`}},{id:"docs.tech.acp.transport",exportName:"AcpTransportDocBlock",sourceModule:"acp/capabilities/acpTransport.capability",block:{id:"docs.tech.acp.transport",title:"ACP transport",summary:"Agent Client Protocol transport surfaces.",kind:"reference",visibility:"public",route:"/docs/tech/acp/transport",tags:["acp","transport"],body:`# ACP transport
+
+Defines the ContractSpec ACP server + client surfaces for HTTP streamable transport.
+`}},{id:"docs.tech.agent.ai-agent-editor",exportName:"AiAgentEditorDocBlock",sourceModule:"agent/graph-conversation",block:{id:"docs.tech.agent.ai-agent-editor",title:"AiAgentEditor — graph editing session contract",summary:"Composes GraphConversation with graphOps capability refs for the AiPairPanel editing session.",kind:"reference",visibility:"public",route:"/docs/tech/agent/ai-agent-editor",tags:["automation","agent","execution","graph","ai","conversation","m5"],domain:"agent",owners:["platform.ai"],stability:"beta",body:"# AiAgentEditor\n\nSession contract that wires a `GraphConversation` to the set of graph\noperations available to the AI agent in this editing context.\n\n## Key invariants\n\n- `autoCommit` must default to `false` (W7.4 suggestion-confirmation UX)\n- `availableOps` defaults to all graphOps + `graph.edit`\n- `contextGraphId` matches the `contextGraphId` accepted by all graphOps commands\n\n## Composition\n\n`AiAgentEditor` is the session state held by `AiPairPanel` (M5 P3/W3.1).\nEach user interaction advances `conversation.history` and may trigger one or\nmore graphOps/edit tool calls.\n"}},{id:"docs.tech.agent.ai-turn-state",exportName:"AiTurnStateDocBlock",sourceModule:"agent/graph-conversation",block:{id:"docs.tech.agent.ai-turn-state",title:"AiTurnState — LLM turn discriminated union",summary:"Discriminated union for every LLM conversation turn: system | user | assistant | tool-call | tool-result.",kind:"reference",visibility:"public",route:"/docs/tech/agent/ai-turn-state",tags:["automation","agent","execution","graph","ai","conversation","m5"],domain:"agent",owners:["platform.ai"],stability:"beta",body:"# AiTurnState\n\nDiscriminated union covering all LLM conversation turn types. Discriminant: `role`.\n\n## Variants\n\n| role | purpose |\n|------|---------|\n| `system` | System-level instruction (persona, capability context) |\n| `user` | User message text |\n| `assistant` | LLM response, optionally carrying `toolCalls` |\n| `tool-call` | Tool invocation request from the LLM |\n| `tool-result` | Result returned by the tool handler |\n\n## Correlation\n\n`tool-call` and `tool-result` turns are linked by `toolCallId`.\n"}},{id:"docs.tech.agent.approval.requested",exportName:"AgentApprovalRequestedDocBlock",sourceModule:"agent/events/agentApprovalRequested.event",block:{id:"docs.tech.agent.approval.requested",title:"Agent approval requested event",summary:"Emitted when approval is required.",kind:"reference",visibility:"public",route:"/docs/tech/agent/approval/requested",tags:["agent","event","approval"],body:`# agent.approval.requested
+
+Emitted when an approval gate is triggered.
+`}},{id:"docs.tech.agent.approvals",exportName:"AgentApprovalsDocBlock",sourceModule:"agent/commands/agentApprovals.command",block:{id:"docs.tech.agent.approvals",title:"Agent approvals",summary:"Resolve an agent approval request.",kind:"reference",visibility:"public",route:"/docs/tech/agent/approvals",tags:["agent","approval"],body:`# agent.approvals
+
+Approve or reject a pending agent action.
+`}},{id:"docs.tech.agent.artifacts",exportName:"AgentArtifactsDocBlock",sourceModule:"agent/queries/agentArtifacts.query",block:{id:"docs.tech.agent.artifacts",title:"Agent artifacts",summary:"List artifacts produced by an agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/artifacts",tags:["agent","artifacts"],body:`# agent.artifacts
+
+Lists files, diffs, and outputs produced during agent execution.
+`}},{id:"docs.tech.agent.automation-protocol-v1",exportName:"AgentAutomationProtocolV1DocBlock",sourceModule:"agent/protocol/automation/contracts",block:{id:"docs.tech.agent.automation-protocol-v1",title:"Governed agent automation protocol V1",summary:"Immutable previews, materializations, claims, receipts, and follow-ups for bounded durable automation.",kind:"reference",visibility:"public",route:"/docs/tech/agent/automation-protocol-v1",tags:["agent","automation","scheduling","durability"],body:`# Governed agent automation protocol V1
+
+Protocol V1 maps a user preview onto one qualified application schedule, then binds materialization, lifecycle state, exact occurrence claims, durable run receipts, and CommunicationOS follow-ups by scope and digest. Every artifact carries \`effectAuthority: "none"\`. Agent Host owns scheduling and recovery, injected policy ports own authority, CommunicationOS owns delivery admission and fallback, and Runtime Nodes remain the only external-effect executors.
+`}},{id:"docs.tech.agent.cancel",exportName:"AgentCancelDocBlock",sourceModule:"agent/commands/agentCancel.command",block:{id:"docs.tech.agent.cancel",title:"Cancel agent run",summary:"Cancel an in-flight agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/cancel",tags:["agent","cancel"],body:`# agent.cancel
+
+Stops an active agent run and records cancellation metadata.
+`}},{id:"docs.tech.agent.context-v1",exportName:"AgentContextV1DocBlock",sourceModule:"context/agent-context-validation",block:{id:"docs.tech.agent.context-v1",title:"Agent context V1",summary:"Provenance-aware, least-privileged context compilation contracts.",kind:"reference",visibility:"public",route:"/docs/tech/agent/context-v1",tags:["agent","context","provenance"],body:`# Agent context V1
+
+Every context item is scoped, hashed, classified, and attributable. Retrieved evidence, channel content, tool results, model summaries, memory proposals, and external documents are data only. Delegation uses explicit projections; compaction preserves source and evidence references.
+`}},{id:"docs.tech.agent.eval.harness",exportName:"evalHarnessDoc",sourceModule:"agent/__tests__/eval/types",block:{id:"docs.tech.agent.eval.harness",title:"Eval harness — prompt fixtures + assertions",summary:"M5 P4 eval harness: 5 domain fixtures × 4 graphOps tools with tolerance-aware mutation assertions and per-tool latency/cost budgets.",kind:"reference",visibility:"internal",route:"/docs/tech/agent/eval/harness",tags:["agent","eval","graphOps","llm","m5"],body:`# Eval harness
+
+Defines types for the M5 P4 eval gate across 5 template domains:
+  workflow-design | agent-tree | conversation-routing | engineering-loop | person-activity
+
+Each EvalFixture bundles:
+  - EvalPromptFixture: id, domain, tool, prompt, contextGraphId, description
+  - EvalMutationAssertion[]: tolerance-gated checks on tool output
+  - EvalBudget: maxLatencyMs + GRAPH_AI_BUDGETS values for the tool
+
+Tolerance in [0, 1]: 0 = exact match required, 1 = any output accepted.`}},{id:"docs.tech.agent.eval.runner",exportName:"runEvalDoc",sourceModule:"agent/__tests__/eval/run-eval",block:{id:"docs.tech.agent.eval.runner",title:"Eval runner — PASS / PARTIAL / FAIL diff",summary:"Runs EvalFixture assertions against actual LLM output, produces PASS/PARTIAL/FAIL with budget violation list.",kind:"how",visibility:"internal",route:"/docs/tech/agent/eval/runner",tags:["agent","eval","graphOps","llm","m5"],body:`# runEval
+
+Diffs actual tool output against fixture assertions and emits a structured EvalResult.
+
+Status rules:
+  FAIL    — any assertion with tolerance=0.0 fails
+  PARTIAL — no zero-tolerance failures; at least one assertion with 0 < tolerance < 0.5 fails
+  PASS    — all low-tolerance assertions pass (permissive ≥0.5 failures ignored)
+
+Budget violations are non-fatal annotations (do not change status).
+Use checkSessionBudget() to enforce the $0.50 / 50-query session ceiling.`}},{id:"docs.tech.agent.execution",exportName:"AgentExecutionDocBlock",sourceModule:"agent/agent.feature",block:{id:"docs.tech.agent.execution",title:"Agent execution",summary:"Background agent execution, approvals, and artifacts.",kind:"reference",visibility:"public",route:"/docs/tech/agent/execution",tags:["agent","execution"],body:`# Agent execution
+
+Defines the core operations, events, and UI surfaces for background agent runs with auditability and approvals.
+`}},{id:"docs.tech.agent.graph-conversation",exportName:"GraphConversationDocBlock",sourceModule:"agent/graph-conversation",block:{id:"docs.tech.agent.graph-conversation",title:"GraphConversation — AI session history buffer",summary:"Ordered turn history + capacity ceiling for AI graph agent sessions. Session identity via sessionId.",kind:"reference",visibility:"public",route:"/docs/tech/agent/graph-conversation",tags:["automation","agent","execution","graph","ai","conversation","m5"],domain:"agent",owners:["platform.ai"],stability:"beta",body:`# GraphConversation
+
+Session history buffer for the AI graph agent. Holds up to \`capacity\` turns
+(default 20, max 50).
+
+## Cost alignment
+
+Capacity is bounded to keep context-window token costs within the per-session
+$0.50 ceiling defined in \`m3-p0-ai-cost-ceiling.md\`.
+
+## Fields
+
+| field | description |
+|-------|-------------|
+| \`sessionId\` | Stable session identifier |
+| \`history\` | Ordered AiTurnState array (oldest first) |
+| \`capacity\` | Max retained turns before eviction |
+| \`createdAt\` | ISO 8601 timestamp when the session was created |
+`}},{id:"docs.tech.agent.markdown-migration-v1",exportName:"AgentMarkdownMigrationV1DocBlock",sourceModule:"agent/protocol/markdown-migration",block:{id:"docs.tech.agent.markdown-migration-v1",title:"Reviewable external agent Markdown archives",kind:"reference",visibility:"public",route:"/docs/tech/agent/markdown-migration-v1",body:"Versioned restricted archives preserve selected Hermes/OpenClaw Markdown memory and skill definitions with content hashes, source provenance and disabled activation. Import data never grants permissions. Memory proposals remain owned by PersonalOS or CompanyOS governance. This initial slice does not migrate schedules, channel configuration, skill scripts/assets, or external memory databases. Hosts must authorize source selection and storage; archive data must not be logged or published as ordinary telemetry."}},{id:"docs.tech.agent.memory-tools",exportName:"AgentMemoryToolsDocBlock",sourceModule:"agent/spec",block:{id:"docs.tech.agent.memory-tools",title:"Memory tools",summary:"Governed memory proposals with legacy direct-store compatibility.",kind:"reference",visibility:"public",route:"/docs/tech/agent/memory-tools",tags:["agent","memory","tools"],body:`# Memory tools
+
+Protocol V1 memory tools create provenance-bound proposals only. PersonalOS or CompanyOS must independently bind consent, policy, retention, authority, revision, and evidence before committing a mutation. The legacy direct-store adapter remains available only for non-Protocol-V1 agents and does not establish governed production memory.
+`}},{id:"docs.tech.agent.operations-as-tools",exportName:"AgentOperationsAsToolsDocBlock",sourceModule:"agent/spec",block:{id:"docs.tech.agent.operations-as-tools",title:"Operations as tools",summary:"Reference ContractSpec operations as agent tools. One contract to many surfaces.",kind:"reference",visibility:"public",route:"/docs/tech/agent/operations-as-tools",tags:["agent","tools","operations"],body:"# Operations as tools\n\nReference ContractSpec operations in `AgentSpec.tools` with `operationRef` to reuse schemas, handlers, and output bindings across REST, GraphQL, MCP, and agent execution.\n"}},{id:"docs.tech.agent.protocol-v1",exportName:"AgentProtocolV1DocBlock",sourceModule:"agent/protocol/application",block:{id:"docs.tech.agent.protocol-v1",title:"Agent protocol V1",summary:"Portable Plan–Act–Reflect contracts with deterministic authority.",kind:"reference",visibility:"public",route:"/docs/tech/agent/protocol-v1",tags:["agent","protocol","plan-act-reflect"],body:`# Agent protocol V1
+
+The protocol describes durable context, plans, checkpoints, reflections, help, delegation, model routes, and evidence. It does not execute tools, grant authority, deliver messages, schedule work, or persist runtime state. External effects remain authorized by Connect and performed by Runtime Nodes.
+`}},{id:"docs.tech.agent.run",exportName:"AgentRunDocBlock",sourceModule:"agent/commands/agentRun.command",block:{id:"docs.tech.agent.run",title:"Run agent",summary:"Submit a background agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run",tags:["agent","run"],body:`# agent.run
+
+Creates a new agent run with a context snapshot and execution metadata.
+`}},{id:"docs.tech.agent.run.audit",exportName:"AgentRunAuditDocBlock",sourceModule:"agent/presentations/agentRunAudit.presentation",block:{id:"docs.tech.agent.run.audit",title:"Agent run audit presentation",summary:"Presentation spec for agent run audit views.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/audit",tags:["agent","presentation","audit"],body:`# agent.run.audit
+
+Presentation surface used to inspect run provenance, tools, approvals, and outputs.
+`}},{id:"docs.tech.agent.run.completed",exportName:"AgentRunCompletedDocBlock",sourceModule:"agent/events/agentRunCompleted.event",block:{id:"docs.tech.agent.run.completed",title:"Agent run completed event",summary:"Emitted when an agent run completes.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/completed",tags:["agent","event"],body:`# agent.run.completed
+
+Emitted when a run completes successfully.
+`}},{id:"docs.tech.agent.run.failed",exportName:"AgentRunFailedDocBlock",sourceModule:"agent/events/agentRunFailed.event",block:{id:"docs.tech.agent.run.failed",title:"Agent run failed event",summary:"Emitted when an agent run fails.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/failed",tags:["agent","event"],body:`# agent.run.failed
+
+Emitted when a run terminates with failure.
+`}},{id:"docs.tech.agent.run.form",exportName:"AgentRunFormDocBlock",sourceModule:"agent/forms/agentRun.form",block:{id:"docs.tech.agent.run.form",title:"Agent run form",summary:"Form specification for launching an agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/form",tags:["agent","form"],body:`# agent.run.form
+
+Form surface used by Studio to submit agent runs.
+`}},{id:"docs.tech.agent.run.index",exportName:"AgentRunsDataViewDocBlock",sourceModule:"agent/views/agentRuns.dataView",block:{id:"docs.tech.agent.run.index",title:"Agent run index view",summary:"Data view for listing agent runs.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/index",tags:["agent","data-view"],body:`# agent.run.index
+
+List view over agent runs and their status.
+`}},{id:"docs.tech.agent.run.started",exportName:"AgentRunStartedDocBlock",sourceModule:"agent/events/agentRunStarted.event",block:{id:"docs.tech.agent.run.started",title:"Agent run started event",summary:"Emitted when an agent run starts.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/started",tags:["agent","event"],body:`# agent.run.started
+
+Emitted when an agent run begins execution.
+`}},{id:"docs.tech.agent.runner.goal",exportName:"agentRunnerGoalDoc",sourceModule:"agent/runner",block:{id:"docs.tech.agent.runner.goal",title:"Agent runner — goal",summary:"Synchronous depth-first agent task-tree executor with cancel propagation.",kind:"goal",visibility:"public",route:"/docs/tech/agent/runner/goal",tags:["agent","runner","task-tree"],body:"# Agent runner\n\nThe agent runner walks a flat list of `AgentTask` records as a depth-first tree,\nexecuting parent tasks before their children. It emits four lifecycle events:\n`agent.task_started`, `agent.task_completed`, `agent.task_failed`, and\n`agent.task_cancelled`. Cancellation propagates to all remaining descendants."}},{id:"docs.tech.agent.status",exportName:"AgentStatusDocBlock",sourceModule:"agent/queries/agentStatus.query",block:{id:"docs.tech.agent.status",title:"Agent status",summary:"Query agent run status.",kind:"reference",visibility:"public",route:"/docs/tech/agent/status",tags:["agent","status"],body:`# agent.status
+
+Returns status summaries for one or many agent runs.
+`}},{id:"docs.tech.agent.subagents",exportName:"AgentSubagentsDocBlock",sourceModule:"agent/spec",block:{id:"docs.tech.agent.subagents",title:"Subagents",summary:"Delegate tasks to subagents with streaming and isolated context.",kind:"reference",visibility:"public",route:"/docs/tech/agent/subagents",tags:["agent","subagents","delegation"],body:`# Subagents
+
+Subagents let a primary agent delegate bounded work to worker agents while keeping orchestration, summaries, and approval policy in the parent flow.
+`}},{id:"docs.tech.agent.task-tree.goal",exportName:"agentTaskTreeGoalDoc",sourceModule:"agent/task-tree",block:{id:"docs.tech.agent.task-tree.goal",title:"AgentTask — goal",summary:"Tree-topology specialisation of SharedTask for the agent runtime.",kind:"goal",visibility:"public",route:"/docs/tech/agent/task-tree/goal",tags:["agent","task-tree","a9"],body:"# AgentTask\n\n`AgentTask` is the agent-context specialisation of `SharedTask` (A9 invariant).\nEach node carries at most one `parent` reference, forming a strict tree topology.\n`dependsOn` is prohibited at runtime — use `validateAgentTaskTree()` to enforce this.\n\n## Tree invariant\n\n- Exactly one root per tree (`parent` is `undefined`).\n- Every non-root task references one existing task as its parent.\n- `dependsOn` is reserved for workflow DAG context and MUST NOT be set here."}},{id:"docs.tech.agent.task-tree.usage",exportName:"agentTaskTreeUsageDoc",sourceModule:"agent/task-tree",block:{id:"docs.tech.agent.task-tree.usage",title:"AgentTask — usage",summary:"How to build and validate an agent task tree.",kind:"usage",visibility:"public",route:"/docs/tech/agent/task-tree/usage",tags:["agent","task-tree"],body:`# Using AgentTask
+
+## Build a tree
+
+\`\`\`ts
+import type { AgentTask } from '@lssm/lib.contracts-spec/agent';
+
+const tasks: AgentTask[] = [
+  { id: 'root', label: 'Root task' },
+  { id: 'child-a', label: 'Child A', parent: 'root' },
+  { id: 'child-b', label: 'Child B', parent: 'root' },
+];
+\`\`\`
+
+## Validate before running
+
+\`\`\`ts
+import { validateAgentTaskTree } from '@lssm/lib.contracts-spec/agent';
+
+const result = validateAgentTaskTree(tasks);
+if (!result.valid) throw new Error(result.error);
+\`\`\``}},{id:"docs.tech.agent.workflow-integration",exportName:"AgentWorkflowIntegrationDocBlock",sourceModule:"agent/spec",block:{id:"docs.tech.agent.workflow-integration",title:"Workflow-agent integration",summary:"Patterns for orchestrator-worker, workflow steps, and evaluator loops.",kind:"reference",visibility:"public",route:"/docs/tech/agent/workflow-integration",tags:["agent","workflow","orchestrator"],body:`# Workflow-agent integration
+
+Agents can act as workflow workers, orchestrators, or evaluators. Contract-backed operations keep those integrations explicit and replayable.
+`}},{id:"docs.tech.companyos.calendar-intelligence.delivery.retry",exportName:"PersonalBriefingDeliveryRetryDocBlock",sourceModule:"companyos/commands/personalBriefingDeliveryRetry.command",block:{id:"docs.tech.companyos.calendar-intelligence.delivery.retry",title:"Retry a personal briefing delivery",summary:"Retries one failed or stale delivery owned by the authenticated recipient.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/delivery-retry",tags:["companyos","calendar-intelligence","briefings","recovery"],body:`# Retry personal briefing delivery
+
+The opaque delivery identifier is resolved inside the authenticated user's
+personal tenant. Delivered, suppressed, fresh in-flight, exhausted, and
+cross-user records cannot be retried. The same idempotency key and bounded
+personal calendar pipeline are reused; no recipient or calendar authority is
+accepted from the browser.
+`}},{id:"docs.tech.companyos.calendar-intelligence.google-oauth.complete",exportName:"PersonalBriefingGoogleOAuthCompleteDocBlock",sourceModule:"companyos/commands/personalBriefingGoogleOAuthComplete.command",block:{id:"docs.tech.companyos.calendar-intelligence.google-oauth.complete",title:"Complete personal Google Calendar authorization",summary:"Completes signed OAuth state for the same authenticated CompanyOS user.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/google-oauth-complete",tags:["companyos","calendar-intelligence","google-calendar","oauth"],body:`# Complete personal Google Calendar OAuth
+
+Signed provider state must resolve to the current user’s personal context and
+server-derived account reference. A mismatched user, tenant, account, state, or
+session is rejected before a personal source is materialized.
+`}},{id:"docs.tech.companyos.calendar-intelligence.google-oauth.start",exportName:"PersonalBriefingGoogleOAuthStartDocBlock",sourceModule:"companyos/commands/personalBriefingGoogleOAuthStart.command",block:{id:"docs.tech.companyos.calendar-intelligence.google-oauth.start",title:"Start personal Google Calendar authorization",summary:"Starts OAuth for the authenticated user’s non-shareable personal CompanyOS context.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/google-oauth-start",tags:["companyos","calendar-intelligence","google-calendar","oauth"],body:`# Start personal Google Calendar OAuth
+
+The account reference, user, owner, and personal tenant are server-derived.
+The operation never accepts browser-provided identity selectors and never
+authorizes a workspace booking calendar as a personal source.
+`}},{id:"docs.tech.companyos.calendar-intelligence.microsoft-calendar.disconnect",exportName:"PersonalBriefingMicrosoftDisconnectDocBlock",sourceModule:"companyos/commands/personalBriefingMicrosoftDisconnect.command",block:{id:"docs.tech.companyos.calendar-intelligence.microsoft-calendar.disconnect",title:"Disconnect personal Microsoft Calendar",summary:"Revokes local credentials and disables only the current personal Microsoft connection.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/microsoft-calendar-disconnect",tags:["companyos","calendar-intelligence","microsoft-calendar","oauth"],body:`# Disconnect personal Microsoft Calendar
+
+The account reference, user, owner, and personal tenant are server-derived.
+The operation deletes local account credentials and pending authorization state, disables the personal source, and preserves Google data. It does not claim to revoke consent in Microsoft itself. No provider network request is required.
+`}},{id:"docs.tech.companyos.calendar-intelligence.microsoft-oauth.complete",exportName:"PersonalBriefingMicrosoftOAuthCompleteDocBlock",sourceModule:"companyos/commands/personalBriefingMicrosoftOAuthComplete.command",block:{id:"docs.tech.companyos.calendar-intelligence.microsoft-oauth.complete",title:"Complete personal Microsoft Calendar authorization",summary:"Completes opaque one-use OAuth state for the same authenticated CompanyOS user.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/microsoft-oauth-complete",tags:["companyos","calendar-intelligence","microsoft-calendar","oauth"],body:`# Complete personal Microsoft Calendar OAuth
+
+Opaque one-use provider state must resolve to the current user’s personal context and
+server-derived account reference. A mismatched user, tenant, account, state, or
+session is rejected before credentials are persisted.
+Successful HTML browser callbacks return HTTP 303 to the configured CompanyOS
+settings origin and fixed path, without forwarding callback parameters. JSON
+clients retain the connected boolean response. No caller return URL is accepted.
+`}},{id:"docs.tech.companyos.calendar-intelligence.microsoft-oauth.start",exportName:"PersonalBriefingMicrosoftOAuthStartDocBlock",sourceModule:"companyos/commands/personalBriefingMicrosoftOAuthStart.command",block:{id:"docs.tech.companyos.calendar-intelligence.microsoft-oauth.start",title:"Start personal Microsoft Calendar authorization",summary:"Starts OAuth for the authenticated user’s non-shareable personal CompanyOS context.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/microsoft-oauth-start",tags:["companyos","calendar-intelligence","microsoft-calendar","oauth"],body:`# Start personal Microsoft Calendar OAuth
+
+The account reference, user, owner, and personal tenant are server-derived.
+The operation never accepts browser-provided identity selectors and never
+authorizes a workspace booking calendar as a personal source.
+`}},{id:"docs.tech.companyos.calendar-intelligence.personal-calendars.list",exportName:"PersonalBriefingCalendarsListDocBlock",sourceModule:"companyos/queries/personalBriefingCalendarsList.query",block:{id:"docs.tech.companyos.calendar-intelligence.personal-calendars.list",title:"List personal Google calendars",summary:"Enumerates only calendars available through the current user’s personal Google grant.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/personal-calendars-list",tags:["companyos","calendar-intelligence","google-calendar","privacy"],body:`# List personal Google calendars
+
+The operation has no account, tenant, owner, or user input. It derives the
+personal account reference from the session and returns only opaque calendar
+references suitable for subsequent selection.
+`}},{id:"docs.tech.companyos.calendar-intelligence.personal-calendars.select",exportName:"PersonalBriefingCalendarsSelectDocBlock",sourceModule:"companyos/commands/personalBriefingCalendarsSelect.command",block:{id:"docs.tech.companyos.calendar-intelligence.personal-calendars.select",title:"Select personal briefing calendars",summary:"Selects calendars owned by the current user and maps each to currently authorized workspaces.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/personal-calendars-select",tags:["companyos","calendar-intelligence","oauth","authorization"],body:`# Personal calendar selection
+
+Every calendar reference is re-enumerated from the authenticated user’s Google
+grant. Every selected calendar requires at least one explicit workspace mapping,
+and every mapping is revalidated against current CompanyOS membership.
+
+Workspace booking resources are permanently excluded from this operation.
+
+Compatibility intent: **breaking major** in
+\`companyos.calendar-intelligence@3.0.0\`. A successful selection returns the
+server-derived delivery rollout state alongside setup readiness.
+`}},{id:"docs.tech.companyos.calendar-intelligence.personal-preferences.update",exportName:"PersonalBriefingPreferencesUpdateDocBlock",sourceModule:"companyos/commands/personalBriefingPreferencesUpdate.command",block:{id:"docs.tech.companyos.calendar-intelligence.personal-preferences.update",title:"Update personal briefing preferences",summary:"Updates only the authenticated user’s locale, timezone, cadence, enablement, and delivery channels.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/personal-preferences-update",tags:["companyos","calendar-intelligence","briefings","privacy"],body:`# Personal briefing preferences
+
+The server derives the user, personal context, and verified delivery address.
+Browser payloads cannot select another user, tenant, owner, or recipient.
+
+Compatibility intent: **additive minor** in
+\`companyos.calendar-intelligence@3.1.0\`. The server derives delivery rollout
+from setup readiness and the two delivery toggles. Workspace briefing
+preferences are not read or migrated into the personal delivery runtime. The
+durable in-app route is mandatory and the user may additionally select email.
+`}},{id:"docs.tech.companyos.calendar-intelligence.personal-status",exportName:"PersonalBriefingStatusDocBlock",sourceModule:"companyos/queries/personalBriefingStatus.query",block:{id:"docs.tech.companyos.calendar-intelligence.personal-status",title:"Read personal briefing status",summary:"Returns only the authenticated user’s setup, sources, mappings, preferences, and privacy-safe delivery evidence.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/personal-status",tags:["companyos","calendar-intelligence","briefings","privacy"],body:`# Personal briefing status
+
+This query has no identity input. The server derives the user and personal
+context from the session. Recent delivery evidence excludes event notes, graph
+content, rendered bodies, provider event identifiers, and attendee addresses.
+Provider delivery state is a monotonic, signed-webhook-derived projection. API
+acceptance alone must never be described as delivered.
+
+Connection health is provider-backed rather than inferred from a persisted
+source row. A calendar enumeration authorization failure moves the source to
+\`reauthorization_required\` and records only a redacted failure stage; the
+status query must not continue to describe that source as connected.
+`}},{id:"docs.tech.companyos.calendar-intelligence.preview.send",exportName:"PersonalBriefingPreviewSendDocBlock",sourceModule:"companyos/commands/personalBriefingPreviewSend.command",block:{id:"docs.tech.companyos.calendar-intelligence.preview.send",title:"Send a personal briefing preview",summary:"Prepares a non-production morning or preparation preview through the current user’s selected CommunicationOS routes.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/calendar-intelligence/preview-send",tags:["companyos","calendar-intelligence","briefings","preview"],body:`# Send personal briefing preview
+
+The browser supplies only the kind field as morning-recap or
+meeting-preparation; it supplies no recipient. The server resolves the
+current CompanyOS identity and resolves the selected delivery routes. Email
+uses exactly one verified recipient with no cc or bcc. The server reads only
+that user’s selected personal calendars, revalidates
+their mapped workspace authority, and composes the same grounded document used
+by live delivery. The rendered delivery is retained only as the canonical
+CommunicationOS message under the configured conversation-retention policy.
+Queue admission, provider acceptance, and confirmed delivery remain distinct. Preparation
+preview fails closed when no eligible timed event exists. Provider delivery
+failures return a stable, redacted unavailable error so the interface can show
+an actionable operator-owned blocker without exposing provider details.
+`}},{id:"docs.tech.companyos.company-metrics.commands",exportName:"CompanyMetricsCommandsDocBlock",sourceModule:"companyos/company-metrics/commands",block:{id:"docs.tech.companyos.company-metrics.commands",title:"Company metrics commands",summary:"Govern definition, collection, alert, digest, and publication lifecycle.",kind:"reference",visibility:"public",route:"/docs/tech/companyos/company-metrics/commands",tags:["companyos","metrics","governance"],body:`# Company metrics commands
+
+Every mutation is scope-bound and idempotent. Discovery approval does not authorize changed tools or schemas.`}},{id:"docs.tech.companyos.company-metrics.events",exportName:"CompanyMetricsEventsDocBlock",sourceModule:"companyos/company-metrics/events",block:{id:"docs.tech.companyos.company-metrics.events",title:"Company metrics events",summary:"Evidence-bearing facts emitted by the governed metrics lifecycle.",kind:"reference",visibility:"public",route:"/docs/tech/companyos/company-metrics/events",tags:["companyos","metrics"],body:`# Company metrics events
+
+Events contain aggregate references only; raw source payloads, prompts, credentials, and direct identifiers are excluded.`}},{id:"docs.tech.companyos.company-metrics.queries",exportName:"CompanyMetricsQueriesDocBlock",sourceModule:"companyos/company-metrics/queries",block:{id:"docs.tech.companyos.company-metrics.queries",title:"Company metrics queries",summary:"Read governed metric projections without provider-side reads.",kind:"reference",visibility:"public",route:"/docs/tech/companyos/company-metrics/queries",tags:["companyos","metrics"],body:`# Company metrics queries
+
+Dashboard reads use immutable CompanyOS snapshots. Providers are queried only by collection jobs.`}},{id:"docs.tech.companyos.onboarding-preferences.complete",exportName:"CompanyOsOnboardingPreferencesCompleteDocBlock",sourceModule:"companyos/commands/onboardingPreferencesComplete.command",block:{id:"docs.tech.companyos.onboarding-preferences.complete",title:"Complete CompanyOS onboarding preferences",summary:"Persists tenant-bound experience preferences for the authenticated user with optimistic concurrency and idempotent replay.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/onboarding-preferences-complete",tags:["companyos","onboarding","preferences","concurrency"],body:`# Complete CompanyOS onboarding preferences
+
+The browser supplies only a bounded preference patch, the last observed
+tenant-scoped experience revision, and an idempotency key. The host derives the
+user and tenant from the authenticated session. It stores one preference
+document per user and tenant, rejects cross-tenant selectors, and replays only
+the exact command within the same derived scope.
+`}},{id:"docs.tech.companyos.persona-preview.set",exportName:"CompanyOsPersonaPreviewSetDocBlock",sourceModule:"companyos/commands/personaPreviewSet.command",block:{id:"docs.tech.companyos.persona-preview.set",title:"Set CompanyOS persona preview",summary:"Sets or clears a server-authorized, session-scoped presentation-only persona preview.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/persona-preview-set",tags:["companyos","persona","rolemorph","session"],body:`# Set CompanyOS persona preview
+
+This additive v1 command stores an authorized view persona in the current
+session only. It never changes the actual authorization persona or grants
+capabilities; presentation and actions remain the intersection of the actual
+subject and the selected preview. Passing null exits preview mode.
+`}},{id:"docs.tech.companyos.shell-preferences.get",exportName:"CompanyOsShellPreferencesGetDocBlock",sourceModule:"companyos/queries/shellPreferencesGet.query",block:{id:"docs.tech.companyos.shell-preferences.get",title:"Get CompanyOS shell preferences",summary:"Returns the authenticated user’s versioned shell preference snapshot.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/shell-preferences-get",tags:["companyos","shell","preferences"],body:`# Get CompanyOS shell preferences
+
+Breaking v2 adds the required tenant-scoped experience preference document and
+its independent revision to the authenticated shell snapshot. The server still
+derives the user and tenant from the session. Placement and experience writes
+retain separate optimistic revisions.
+`}},{id:"docs.tech.companyos.shell-preferences.update",exportName:"CompanyOsShellPreferencesUpdateDocBlock",sourceModule:"companyos/commands/shellPreferencesUpdate.command",block:{id:"docs.tech.companyos.shell-preferences.update",title:"Update CompanyOS shell preferences",summary:"Updates the authenticated user’s context-switcher placement with optimistic concurrency.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/shell-preferences-update",tags:["companyos","shell","preferences","concurrency"],body:`# Update CompanyOS shell preferences
+
+Breaking v2 returns the complete authenticated shell snapshot, including the
+required tenant-scoped experience preference document and its independent
+revision. The command still mutates only context-switcher placement.
+`}},{id:"docs.tech.companyos.special-ops.review-card.decide",exportName:"ReviewCardDecideDocBlock",sourceModule:"companyos/commands/reviewCardDecide.command",block:{id:"docs.tech.companyos.special-ops.review-card.decide",title:"Decide a Special Ops review card",summary:"Record a human approve/reject decision on a submitted Special Ops review card; tenant- and workspace-scoped, idempotent, audit-emitting.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/special-ops/review-card-decide",tags:["special-ops","review-card","decide","mutation"],body:"# specialOps.reviewCard.decide\n\nRecords a human review decision (`approved` ∨ `rejected`) on a previously\nsubmitted Special Ops review card. Governs the already-shipped\n`decideReviewCard` repository handler in `api-application-monolith`; authored\nhere (Managed CompanyOS production contracts surface) rather than the\n`packages/examples/special-ops-cockpit` fixture, which stays a pure demo.\n\nScope: tenant- and workspace-scoped. The handler resolves the actor session to\nan access scope and refuses cross-scope mutation (`TENANT_MISMATCH`). Decision\nis human-only — this is the anti-surveillance human-review boundary, not an\nautomated transition.\n\nIdempotency: `idempotencyKey` is required. Replays return the original result\nwith `idempotentReplay = true`; the underlying evidence receipt is preserved.\n\nAudit: every decision is intended to emit a `managed_companyos_audit_events`\nrow (see `sideEffects.audit`) distinct from the in-memory evidence receipt.\n\nCompatibility intent: **additive** (new operation key, no change to existing\ncontracts).\n"}},{id:"docs.tech.companyos.special-ops.weekly-report.approve",exportName:"WeeklyReportApproveDocBlock",sourceModule:"companyos/commands/weeklyReportApprove.command",block:{id:"docs.tech.companyos.special-ops.weekly-report.approve",title:"Approve (publish) a Special Ops weekly report",summary:"Human-approve a Special Ops weekly report draft, transitioning it to published; tenant- and workspace-scoped, idempotent, audit-emitting.",kind:"reference",visibility:"internal",route:"/docs/tech/companyos/special-ops/weekly-report-approve",tags:["special-ops","weekly-report","approve","publish","mutation"],body:"# specialOps.weeklyReport.approve\n\nHuman approval gate for a Special Ops weekly report. Approval is the publish\ntransition: a draft report becomes `published` and its\n`publish_policy_ref` flips to `allow` only after an explicit human decision.\nGoverns the already-shipped `publishWeeklyReport` repository handler in\n`api-application-monolith`; authored here (Managed CompanyOS production\ncontracts surface) rather than the `packages/examples/special-ops-cockpit`\nfixture, which stays a pure demo.\n\nScope: tenant- and workspace-scoped. Cross-scope approval is refused\n(`TENANT_MISMATCH`). The report must already exist as a composed draft built\nfrom approved review cards only.\n\nIdempotency: `idempotencyKey` is required. Replays return the original result\nwith `idempotentReplay = true`; the underlying evidence receipt is preserved.\n\nAudit: every approval is intended to emit a `managed_companyos_audit_events`\nrow (see `sideEffects.audit`) distinct from the in-memory evidence receipt.\n\nCompatibility intent: **additive** (new operation key, no change to existing\ncontracts).\n"}},{id:"docs.tech.content-analysis.events",exportName:"ContentAnalysisEventsDocBlock",sourceModule:"content-analysis/events",block:{id:"docs.tech.content-analysis.events",title:"Content analysis events",summary:"Immutable lifecycle notifications for assistive media analysis.",kind:"reference",visibility:"public",route:"/docs/tech/content-analysis/events",tags:["content-analysis","ai","evidence","creator-intelligence","events"],body:`# Content analysis events
+
+Events carry identifiers and evidence references, never raw provider payloads or hidden reasoning.`}},{id:"docs.tech.content-analysis.operations",exportName:"ContentAnalysisOperationsDocBlock",sourceModule:"content-analysis/operations",block:{id:"docs.tech.content-analysis.operations",title:"Content analysis operations",summary:"Evidence-first, contestable analysis of text, image, audio, and video.",kind:"reference",visibility:"public",route:"/docs/tech/content-analysis/operations",tags:["content-analysis","ai","evidence","creator-intelligence"],body:`# Content analysis operations
+
+Requests are tenant scoped, bounded, versioned, evidence backed, and idempotent.
+Results may support human review and coaching but never grant review, publication,
+ranking, creator-selection, or economic authority.
+`}},{id:"docs.tech.content-generation.system",exportName:"ContentGenerationSystemDocBlock",sourceModule:"content-generation/contracts",block:{id:"docs.tech.content-generation.system",title:"Content Generation Contracts",summary:"Provider-agnostic contracts for text, image, video, TTS, STT, conversation, and multimodal workflows.",kind:"reference",visibility:"public",route:"/docs/tech/content-generation/system",tags:["content-generation","multimodal","providers"],body:`# Content Generation Contracts
+
+Defines source-of-truth operation schemas and provider ports for content-generation orchestration without owning concrete provider SDK adapters.
+`}},{id:"docs.tech.context.pack.describe",exportName:"ContextPackDescribeDocBlock",sourceModule:"context/queries/contextPackDescribe.query",block:{id:"docs.tech.context.pack.describe",title:"Describe context pack",summary:"Describe a context pack and its sources.",kind:"reference",visibility:"public",route:"/docs/tech/context/pack/describe",tags:["context","pack","describe"],body:`# context.pack.describe
+
+Returns a canonical view of a context pack, including sources and ownership metadata.
+`}},{id:"docs.tech.context.pack.search",exportName:"ContextPackSearchDocBlock",sourceModule:"context/queries/contextPackSearch.query",block:{id:"docs.tech.context.pack.search",title:"Search context packs",summary:"Search and filter context packs and snapshots.",kind:"reference",visibility:"public",route:"/docs/tech/context/pack/search",tags:["context","pack","search"],body:`# context.pack.search
+
+Search context packs and surface their latest snapshot details for discovery and UI lists.
+`}},{id:"docs.tech.context.pack.search.form",exportName:"ContextPackSearchFormDocBlock",sourceModule:"context/forms/contextPackSearch.form",block:{id:"docs.tech.context.pack.search.form",title:"Context pack search form",summary:"Form used to search context packs in UI surfaces.",kind:"reference",visibility:"public",route:"/docs/tech/context/pack/search-form",tags:["context","form","search"],body:`# context.pack.search.form
+
+Form specification for searching context packs by query, tag, or owner.
+`}},{id:"docs.tech.context.pack.snapshot",exportName:"ContextPackSnapshotDocBlock",sourceModule:"context/commands/contextPackSnapshot.command",block:{id:"docs.tech.context.pack.snapshot",title:"Create context snapshot",summary:"Create an immutable context snapshot from a pack.",kind:"reference",visibility:"public",route:"/docs/tech/context/pack/snapshot",tags:["context","snapshot","create"],body:`# context.pack.snapshot
+
+Creates a versioned snapshot that is used as the immutable context for agent execution.
+`}},{id:"docs.tech.context.snapshot.created",exportName:"ContextSnapshotCreatedDocBlock",sourceModule:"context/events/contextSnapshotCreated.event",block:{id:"docs.tech.context.snapshot.created",title:"Context snapshot created event",summary:"Emitted when a context snapshot is created.",kind:"reference",visibility:"public",route:"/docs/tech/context/snapshot/created",tags:["context","snapshot","event"],body:`# context.snapshot.created
+
+Emitted when a new snapshot has been persisted and is ready for use.
+`}},{id:"docs.tech.context.snapshot.index",exportName:"ContextSnapshotsDataViewDocBlock",sourceModule:"context/views/contextSnapshots.dataView",block:{id:"docs.tech.context.snapshot.index",title:"Context snapshot index view",summary:"Data view for listing context snapshots.",kind:"reference",visibility:"public",route:"/docs/tech/context/snapshot/index",tags:["context","snapshot","data-view"],body:`# context.snapshot.index
+
+Provides a list-oriented data view over context packs and snapshot metadata.
+`}},{id:"docs.tech.context.snapshot.presentation",exportName:"ContextSnapshotSummaryDocBlock",sourceModule:"context/presentations/contextSnapshot.presentation",block:{id:"docs.tech.context.snapshot.presentation",title:"Context snapshot presentation",summary:"Presentation spec for snapshot summaries.",kind:"reference",visibility:"public",route:"/docs/tech/context/snapshot/presentation",tags:["context","presentation","snapshot"],body:`# context.snapshot.summary
+
+Defines the presentation surface for snapshot summaries across UI channels.
+`}},{id:"docs.tech.context.system",exportName:"ContextSystemDocBlock",sourceModule:"context/capabilities/contextSystem.capability",block:{id:"docs.tech.context.system",title:"Context system",summary:"Context packs, snapshots, and discovery surfaces.",kind:"reference",visibility:"public",route:"/docs/tech/context/system",tags:["context","system","snapshot"],body:`# Context system
+
+The context system defines how ContractSpec bundles DocBlocks, contracts, knowledge spaces, and data views into deterministic snapshots.
+`}},{id:"docs.tech.contracts.app-config",exportName:"tech_contracts_app_config_DocBlocks",sourceModule:"app-config/spec",block:{id:"docs.tech.contracts.app-config",title:"App Configuration Layers",summary:"App orchestration is split into three explicit layers:",kind:"reference",visibility:"public",route:"/docs/tech/contracts/app-config",tags:["tech","contracts","app-config"],body:`## App Configuration Layers
+
+App orchestration is split into three explicit layers:
+
+1. **AppBlueprintSpec**: global, versioned description of what an app can look like. Stored in Git with no tenant or environment data.
+2. **TenantAppConfig**: tenant and environment overrides that Studio or control-plane workflows edit over time.
+3. **ResolvedAppConfig**: the pure merged view consumed by runtime code.
+
+- Types and registry: \`packages/libs/contracts-spec/src/app-config/spec.ts\`
+- Resolution helpers: \`packages/libs/contracts-spec/src/app-config/runtime.ts\`
+- Validation helpers: \`packages/libs/contracts-spec/src/app-config/validation.ts\`
+- CLI wizard: \`contractspec create app-config\`
+
+### 1. AppBlueprintSpec
+
+\`\`\`ts
+export interface AppBlueprintSpec {
+  meta: AppBlueprintMeta;          // { key, version, appId, ownership }
+  capabilities?: { enabled?: CapabilityRef[]; disabled?: CapabilityRef[] };
+  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };
+  integrationSlots?: AppIntegrationSlot[];
+  branding?: BrandingDefaults;
+  translationCatalog?: { key: string; version: string };
+  dataViews?: Record<string, SpecPointer>;
+  workflows?: Record<string, SpecPointer>;
+  jobs?: Record<string, SpecPointer>;
+  policies?: PolicyRef[];
+  theme?: AppThemeBinding;         // { primary: ThemeRef; fallbacks?: ThemeRef[] }
+  telemetry?: TelemetryBinding;    // { spec?: SpecPointer; disabledEvents?: string[] }
+  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };
+  featureFlags?: FeatureFlagState[];
+  routes?: AppRouteConfig[];
+  notes?: string;
+}
+\`\`\`
+
+Register blueprints with \`AppBlueprintRegistry\`. Blueprints only capture the default, global experience.
+
+- **Integration slots** declare the categories and capability requirements an app expects. Slots never include secrets.
+- **Branding defaults** provide message-key-based names, placeholder assets, and token references that tenants can override later.
+
+#### Branding meta surfaces (icons, manifest, verification)
+
+\`BrandingDefaults\` also carries the marketing/meta surfaces consumed by the Next SEO lane (\`toNextMetadata\`, \`buildManifest\`). All fields are optional and additive:
+
+- \`iconSet\` (\`BrandingIconSet\`): the full favicon/app-icon set (\`favicon\`, \`icon32\`, \`icon192\`, \`icon512\`, \`appleTouch180\`, \`maskable\`) plus PWA \`themeColor\`/\`backgroundColor\`. The run-once icon-gen CLI emits the referenced assets into the app's \`public/\`; the Next lane declares them via \`metadata.icons\`.
+- \`manifest\` (\`WebManifestDefaults\`): web app manifest fields in camelCase (\`shortName\`, \`startUrl\`, \`themeColor\`, …) including \`categories\`, \`shortcuts\`, and \`screenshots\`. \`buildManifest\` maps these onto the W3C snake_case manifest and derives top-level \`icons[]\` from \`iconSet\`.
+- \`seo.verification\` (\`SiteVerificationTokens\`): site-ownership tokens (\`google\`, \`bing\`, …; open-ended).
+
+\`resolveAppConfig\` merges these defaults with \`TenantBrandingConfig\` overrides (per-field, override-wins) and surfaces them on \`ResolvedBranding\` as \`iconSet\`, \`manifest\`, and \`verification\` (the latter also mirrored onto \`ResolvedBranding.seo.verification\`).
+
+### 2. TenantAppConfig
+
+\`\`\`ts
+export interface TenantAppConfig {
+  meta: TenantAppConfigMeta;  // { id, tenantId, appId, blueprintName, blueprintVersion, version, status }
+  capabilities?: { enable?: CapabilityRef[]; disable?: CapabilityRef[] };
+  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };
+  dataViewOverrides?: TenantSpecOverride[];
+  workflowOverrides?: TenantSpecOverride[];
+  jobOverrides?: TenantSpecOverride[];
+  additionalPolicies?: PolicyRef[];
+  themeOverride?: { primary?: ThemeRef | null; fallbacks?: ThemeRef[] };
+  telemetryOverride?: { spec?: SpecPointer | null; disabledEvents?: string[] };
+  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };
+  featureFlags?: FeatureFlagState[];
+  routeOverrides?: TenantRouteOverride[];
+  integrations?: AppIntegrationBinding[];
+  knowledge?: AppKnowledgeBinding[];
+  locales?: { defaultLocale: Locale; enabledLocales: Locale[] };
+  translationOverrides?: { entries?: TranslationEntry[] };
+  branding?: TenantBrandingConfig;
+  notes?: string;
+}
+\`\`\`
+
+- **AppIntegrationBinding** maps \`slotId\` to \`connectionId\` plus optional workflow scopes.
+- **TenantBrandingConfig** allows per-tenant names, assets, and domains while keeping secrets and large files out of blueprints.
+
+### 3. ResolvedAppConfig
+
+Use \`resolveAppConfig(blueprint, tenant)\` to build the merged pointer view. Use \`composeAppConfig(...)\` to hydrate those pointers against registries and collect missing references.
+
+\`\`\`ts
+const blueprint = blueprintRegistry.get('core.app', '1.0.0');
+const tenant = loadTenantConfigFromDB();
+
+const composition = composeAppConfig(blueprint!, tenant, {
+  capabilities,
+  features,
+  dataViews,
+  workflows,
+  jobs,
+  policies,
+  themes,
+  telemetry,
+  experiments,
+});
+
+if (composition.missing.length) {
+  console.warn('Unresolved references', composition.missing);
+}
+\`\`\`
+
+### Static Validation
+
+Use the validation helpers in \`@lssm/lib.contracts-spec/app-config/validation\` before publish or promotion:
+
+\`\`\`ts
+import {
+  assertBlueprintValid,
+  assertResolvedConfigValid,
+  assertTenantConfigValid,
+  validateBlueprint,
+  validateConfig,
+  validateResolvedConfig,
+  validateTenantConfig,
+} from '@lssm/lib.contracts-spec/app-config/validation';
+
+const blueprintReport = validateBlueprint(blueprint, context);
+const tenantReport = validateTenantConfig(blueprint, tenant, context);
+const publishReport = validateConfig(blueprint, tenant, context);
+const resolvedReport = validateResolvedConfig(blueprint, resolved, context);
+
+assertBlueprintValid(blueprint, context);
+assertTenantConfigValid(blueprint, tenant, context);
+assertResolvedConfigValid(blueprint, resolved, context);
+\`\`\`
+
+- \`ValidationResult\` exposes \`valid\`, plus structured \`errors\`, \`warnings\`, and \`info\`.
+- Core rules cover capability references, integration slot bindings, knowledge bindings, branding constraints, and translation coverage.
+- Run \`composeAppConfig(..., { strict: true })\` and the validators in CI to catch drift early.
+
+### CLI
+
+\`\`\`
+contractspec create app-config
+contractspec validate --blueprint packages/examples/integration-stripe/src/blueprint.ts
+\`\`\`
+
+### Lifecycle Types and Events
+
+To model multi-step configuration changes, import the lifecycle helpers from \`@lssm/lib.contracts-spec/app-config\`:
+
+\`\`\`ts
+import type {
+  ConfigStatus,
+  TenantAppConfigVersion,
+  ConfigTransition,
+} from '@lssm/lib.contracts-spec/app-config';
+import {
+  ConfigDraftCreatedEvent,
+  ConfigPromotedToPreviewEvent,
+  ConfigPublishedEvent,
+  ConfigRolledBackEvent,
+} from '@lssm/lib.contracts-spec/app-config';
+\`\`\`
+
+- \`ConfigStatus\` enumerates the canonical states: \`draft\`, \`preview\`, \`published\`, \`archived\`, \`superseded\`.
+- \`TenantAppConfigMeta\` includes lifecycle metadata such as \`createdBy\`, \`publishedBy\`, \`publishedAt\`, and rollback lineage.
+- Lifecycle contract specs under \`appConfig.lifecycle.*\` expose typed commands and queries for create -> preview -> publish -> rollback flows.
+`}},{id:"docs.tech.contracts.capabilities",exportName:"tech_contracts_capabilities_DocBlocks",sourceModule:"capabilities/capabilities",block:{id:"docs.tech.contracts.capabilities",title:"CapabilitySpec Overview",summary:"Capability specs define what a module provides (operations, events, presentations) and requires (dependencies). They enable bidirectional linking, inheritance, runtime enforcement, and automated validation.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/capabilities",tags:["tech","contracts","capabilities"],body:`# CapabilitySpec Overview
+
+## Purpose
+
+Capabilities are **module interfaces** that define:
+1. What operations, events, and presentations a module exposes (\`provides\`)
+2. What other capabilities it depends on (\`requires\`)
+3. Inheritance hierarchies via \`extends\`
+
+They enable:
+- **Bidirectional linking**: Specs reference capabilities, capabilities list their specs
+- **Dependency validation**: Features can't install without satisfying requirements
+- **Runtime enforcement**: Check capabilities before executing operations
+- **Inheritance**: Build capability hierarchies with shared requirements
+
+## Schema
+
+\`\`\`ts
+export interface CapabilitySpec {
+  meta: CapabilityMeta;              // ownership metadata + { key, version, kind }
+  extends?: CapabilityRef;           // NEW: inherit from parent capability
+  provides?: CapabilitySurfaceRef[]; // surfaces this capability exposes
+  requires?: CapabilityRequirement[];// capabilities that must exist
+}
+\`\`\`
+
+### Bidirectional Linking
+
+Operations, events, and presentations can now declare their capability:
+
+\`\`\`ts
+// In OperationSpec
+{
+  meta: { key: 'payments.charge.create', ... },
+  capability: { key: 'payments', version: '1.0.0' }, // Links to capability
+  io: { ... }
+}
+
+// In CapabilitySpec
+{
+  meta: { key: 'payments', version: '1.0.0', ... },
+  provides: [
+    { surface: 'operation', key: 'payments.charge.create' }
+  ]
+}
+\`\`\`
+
+Validation ensures both sides match via \`validateCapabilityConsistency()\`.
+
+## Registry Query Methods
+
+The \`CapabilityRegistry\` now provides rich query capabilities:
+
+\`\`\`ts
+// Forward lookups: Capability → Specs
+registry.getOperationsFor('payments');      // ['payments.charge.create', ...]
+registry.getEventsFor('payments');          // ['payments.charge.succeeded', ...]
+registry.getPresentationsFor('payments');   // ['payments.dashboard', ...]
+
+// Reverse lookups: Spec → Capabilities
+registry.getCapabilitiesForOperation('payments.charge.create');
+registry.getCapabilitiesForEvent('payments.charge.succeeded');
+registry.getCapabilitiesForPresentation('payments.dashboard');
+
+// Inheritance
+registry.getAncestors('payments.stripe');           // Parent chain
+registry.getEffectiveRequirements('payments.stripe'); // Includes inherited
+registry.getEffectiveSurfaces('payments.stripe');     // Includes inherited
+\`\`\`
+
+## Inheritance
+
+Capabilities can extend other capabilities:
+
+\`\`\`ts
+// Base capability
+defineCapability({
+  meta: { key: 'payments.base', version: '1.0.0', ... },
+  requires: [{ key: 'auth', version: '1.0.0' }],
+  provides: [{ surface: 'operation', key: 'payments.list' }]
+});
+
+// Child capability inherits requirements
+defineCapability({
+  meta: { key: 'payments.stripe', version: '1.0.0', ... },
+  extends: { key: 'payments.base', version: '1.0.0' },
+  requires: [{ key: 'encryption', version: '1.0.0' }], // Added
+  provides: [{ surface: 'operation', key: 'payments.stripe.charge' }]
+});
+
+// getEffectiveRequirements('payments.stripe') returns:
+// [{ key: 'auth', ... }, { key: 'encryption', ... }]
+\`\`\`
+
+## Runtime Enforcement
+
+Use \`CapabilityContext\` for opt-in runtime checks:
+
+\`\`\`ts
+
+// Create context from user's enabled capabilities
+const ctx = createCapabilityContext(user.capabilities);
+
+// Check capability
+if (ctx.hasCapability('payments')) {
+  // User can access payments features
+}
+
+// Assert capability (throws if missing)
+ctx.requireCapability('payments');
+
+// Guard an operation
+assertCapabilityForOperation(ctx, paymentOperation);
+
+// Filter operations by enabled capabilities
+const allowedOps = filterOperationsByCapability(ctx, allOperations);
+\`\`\`
+
+## Validation
+
+Validate bidirectional consistency between capabilities and specs:
+
+\`\`\`ts
+
+const result = validateCapabilityConsistency({
+  capabilities: capabilityRegistry,
+  operations: operationRegistry,
+  events: eventRegistry,
+  presentations: presentationRegistry,
+});
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+
+// Find specs without capability assignment (informational)
+const orphans = findOrphanSpecs({ capabilities, operations });
+\`\`\`
+
+## Feature Integration
+
+During \`installFeature()\`:
+1. \`provides\` capabilities must exist in the registry
+2. \`requires\` must be satisfied by registered capabilities or local \`provides\`
+3. Referenced operations/events/presentations must exist
+
+## Authoring Guidelines
+
+1. **Register capabilities first** before referencing them in features
+2. **Use bidirectional linking** - set \`capability\` on specs and list them in \`provides\`
+3. **Version consciously** - bump versions on breaking changes
+4. **Document dependencies** with \`reason\` strings
+5. **Use inheritance** for capability families with shared requirements
+6. **Validate during CI** with \`validateCapabilityConsistency()\`
+
+## Error Handling
+
+\`\`\`ts
+
+try {
+  ctx.requireCapability('premium-features');
+} catch (err) {
+  if (err instanceof CapabilityMissingError) {
+    console.log('Missing:', err.capabilityKey);
+    console.log('Required version:', err.requiredVersion);
+  }
+}
+\`\`\`
+
+## API Reference
+
+### Types
+- \`CapabilitySpec\` - Capability definition
+- \`CapabilityRef\` - Reference to a capability (key + version)
+- \`CapabilitySurfaceRef\` - Reference to a provided surface
+- \`CapabilityRequirement\` - Dependency requirement
+- \`CapabilityContext\` - Runtime capability context
+- \`CapabilityValidationResult\` - Validation result
+
+### Functions
+- \`defineCapability(spec)\` - Define a capability spec
+- \`createCapabilityContext(caps)\` - Create runtime context
+- \`validateCapabilityConsistency(deps)\` - Validate bidirectional links
+- \`findOrphanSpecs(deps)\` - Find specs without capability assignment
+- \`assertCapabilityForOperation/Event/Presentation(ctx, spec)\` - Guards
+- \`filterOperationsByCapability(ctx, ops)\` - Filter by enabled capabilities
+`}},{id:"docs.tech.contracts.cli-command-packs",exportName:"CliCommandPackDocBlock",sourceModule:"cli/command-pack",block:{id:"docs.tech.contracts.cli-command-packs",title:"CLI command packs",summary:"Portable metadata and consumer discovery controls for ContractSpec CLI command packs.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/cli-command-packs",tags:["cli","command-pack","configuration"],body:`## CLI command packs
+
+Published command packs expose \`contractspec.commandPack\` metadata containing a module entry and a \`CliCommandPackSpec\`. The CLI discovers only direct consumer dependencies with that metadata.
+
+Consumers can constrain discovery with \`.contractsrc.json\`:
+
+\`\`\`json
+{
+  "commandPacks": {
+    "include": ["@lssm/integration.cli-contractspec-ai"],
+    "exclude": ["@lssm/integration.cli-contractspec-examples"]
+  }
+}
+\`\`\`
+
+Exclusion wins when a package appears in both lists. Runtime registration and conflict handling are owned by \`@lssm/lib.cli-runtime\`.`}},{id:"docs.tech.contracts.data-views",exportName:"tech_contracts_data_views_DocBlocks",sourceModule:"data-views/spec",block:{id:"docs.tech.contracts.data-views",title:"DataViewSpec Overview",summary:"`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/data-views",tags:["tech","contracts","data-views"],body:`# DataViewSpec Overview
+
+## Purpose
+
+\`DataViewSpec\` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (\`source.primary\`, \`source.item\`) and describes how the UI should present, sort, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.
+
+## Schema Highlights
+
+- **DataViewMeta**: ownership metadata plus an entity slug.
+- **DataViewSource**: primary/item operation refs, mutation operation refs, refresh events, and optional database binding.
+- **DataViewConfig**: list/detail/table/grid definitions with fields, filters, actions, collection preferences, and optional \`view.management\` metadata.
+- **DataViewAction**: declarative actions with optional placement, intent, selection scope, approval/destructive boundary, and operation refs.
+- **DataViewConfig.management**: optional command-center metadata for header copy, master-detail layout, toolbar groups, selection/bulk actions, detail empty states, personalization keys, and RoleMorph refs.
+- **DataViewSections**: detail-view sections discriminated by \`kind\` (default \`'fields'\`). A \`'relationship'\` section carries a \`relationship: DataViewSectionRelationship\` (\`key\`, \`cardinality\`, \`dataPath?\`/\`source?\`/\`specKey?\`/inline \`fields?\`, \`displayMode?\`, \`limit?\`, \`emptyState?\`) and renders a related-record collection. The declared relation \`OpRef\` is host-executed; the design-system performs no I/O.
+
+## Authoring Guidelines
+
+1. Keep fetching logic inside contract operations; DataViewSpec only references them via \`source\`.
+2. Use \`view.management\` for entity-management projection metadata only.
+3. Keep persistence, validation, modal flow, destructive confirmations, and network side effects host-owned or FormSpec-owned.
+4. Prefer additive metadata and version specs deliberately when field membership, ordering, or semantics change.
+5. Declare relationships via a \`kind: 'relationship'\` section; supply related records embedded (\`dataPath\`) or host-supplied — the design-system never executes the relation \`OpRef\`.
+`}},{id:"docs.tech.contracts.data-views.graph",exportName:"tech_contracts_data_views_graph_DocBlocks",sourceModule:"data-views/graph-spec",block:{id:"docs.tech.contracts.data-views.graph",title:"DataViewGraphSpec & DataViewGraphSource",summary:"`DataViewGraphSpec` is the sibling-type contract for graph and timeline-graph data views. `DataViewGraphSource` is the discriminated union of three data-fetching strategies: `inline-op`, `two-op`, and `entity-declarative` (requires EntityRegistry at render time).",kind:"reference",visibility:"public",route:"/docs/tech/contracts/data-views/graph",tags:["tech","contracts","data-views","graph","timeline"],body:`# DataViewGraphSpec & DataViewGraphSource
+
+## Purpose
+
+\`DataViewGraphSpec\` extends the data-view contract system for graph and
+timeline-graph experiences. It is a **sibling type** to \`DataViewSpec\`:
+both are accepted by \`defineDataView()\`, discriminated at runtime by
+\`view.kind\`.
+
+- \`view.kind ∈ {graph, timeline-graph}\` → \`DataViewGraphSpec\` branch
+- \`view.kind ∈ {list, detail, table, grid, timeline}\` → \`DataViewSpec\` branch
+
+\`DataViewSource\` shape is **intentionally unchanged** — no \`primary?\`
+optionalisation, no \`graph?\` field added.
+
+## DataViewGraphSource variants
+
+### \`inline-op\`
+Single operation returns both nodes and edges in one payload. Paths are
+dot-notation selectors into the result object.
+
+No EntityRegistry precondition.
+
+\`\`\`typescript
+source: {
+  variant: 'inline-op',
+  primary: { key: 'graph.getContractGraph', version: '1.0.0' },
+  nodesPath: 'data.nodes',
+  edgesPath: 'data.edges',
+}
+\`\`\`
+
+### \`two-op\`
+Separate operations for nodes and edges. Use when your API splits the graph
+across two endpoints.
+
+No EntityRegistry precondition.
+
+\`\`\`typescript
+source: {
+  variant: 'two-op',
+  nodes: { key: 'graph.getNodes', version: '1.0.0' },
+  edges: { key: 'graph.getEdges', version: '1.0.0' },
+}
+\`\`\`
+
+### \`entity-declarative\`
+Derives graph structure from a registered entity slug and optional edge
+declarations. The renderer resolves the entity from the \`EntityRegistry\`
+at render time.
+
+**⚠ Precondition (C12)**: \`EntityRegistry\` MUST be loaded before this view
+renders. The renderer asserts \`EntityRegistry.isLoaded()\` and throws if the
+registry is absent. \`inline-op\` and \`two-op\` do NOT share this precondition.
+
+\`\`\`typescript
+source: {
+  variant: 'entity-declarative',
+  entity: 'user',
+  edges: [{ from: 'user', to: 'project', relation: 'has-many' }],
+}
+\`\`\`
+
+## Example
+
+\`\`\`typescript
+import { defineDataView } from '@lssm/lib.contracts-spec';
+
+export const ContractGraphView = defineDataView({
+  meta: { key: 'contractspec.graph', version: '1.0.0', entity: 'contract', ... },
+  source: {
+    variant: 'inline-op',
+    primary: { key: 'graph.getContractGraph', version: '1.0.0' },
+    nodesPath: 'nodes',
+    edgesPath: 'edges',
+  },
+  view: { kind: 'graph', layout: { kind: 'dag', direction: 'TB' }, nodeKindField: 'type' },
+});
+\`\`\`
+`}},{id:"docs.tech.contracts.editions.lifecycle",exportName:"tech_contracts_editions_DocBlocks",sourceModule:"editions/docs",block:{id:"docs.tech.contracts.editions.lifecycle",title:"Contract editions: lifecycle, versioning, storage, and AI loops",summary:"Contract editions are lifecycle envelopes that make file-backed and database-backed contract evolution explicit, governed, replayable, and AI-editable.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/editions/lifecycle",tags:["tech","contracts","editions","versioning","storage","ai-native"],body:`# Contract editions lifecycle
+
+A contract edition is the storage-agnostic lifecycle envelope around a typed TS contract. It lets humans and AI agents draft, review, experiment, publish, migrate, roll back, and archive contract changes without hiding authority, evidence, or storage behavior in runtime code.
+
+## Version taxonomy
+
+| Name | Meaning | Typical owner |
+| --- | --- | --- |
+| contractVersion | Public contract semantics, usually matching the contract meta/version. | Contract author |
+| editionVersion | Lifecycle envelope revision for a specific draft, experiment, migration, rollback, or release candidate. | Steward workflow |
+| storageRevision | Physical persistence revision: Git commit/path selector or database revision id. | Storage adapter |
+| releaseVersion | Deployment/promoted release capsule that consumed an edition. | Release workflow |
+| experimentVersion | Experiment allocation/variant revision using the edition. | Experiment owner |
+
+Rollback and migration are lifecycle states/events/evidence, not version numbers. They can create new editionVersion and storageRevision values, but the reason must stay explicit in lifecycle and evidence refs.
+
+## Storage kinds
+
+| Storage | Use when | Required evidence |
+| --- | --- | --- |
+| file | Stable source-of-truth, Git review, build/deploy reproducibility, package exports. Same-file multi-edition is allowed only with selector/build metadata. | Git/path refs; selector refs for same-file multi-edition |
+| database | Realtime collaboration, long-living processes, quick AI/human iteration, vertical-specific drafts, and live governance. | Revision/history refs and rollback refs |
+| hybrid | Sync/projection state between file and database, not a third canonical store. | Source/target refs, conflict state, sync evidence refs |
+
+## Lifecycle and authority
+
+Lifecycle states are draft, review, published, experiment, deprecated, archived, rollback, and migration. Authority is policy-per-vertical and can permit suggest-only AI, draft patches, reversible application, autonomous stewardship, human approval, or mixed control.
+
+Promotion and sync are blocked without evidence. Published editions require test, replay, rollback, and promotion evidence. Breaking and migration-required intents require migration refs. Experiments require experiment refs and an experimentVersion.
+
+## Primitive mapping matrix
+
+| Primitive | Edition role |
+| --- | --- |
+| agent-step-observability | Records AI/human suggestions, auto-apply decisions, and approval gates. |
+| ai-improvement | Produces draft patches, reversible applies, and evidence-linked improvement loops. |
+| experiments | Carries A/B allocations and experimentVersion for contract variants. |
+| ContractSpec Connect | Supplies policy verdicts, compatibility gates, and escalation evidence. |
+| release/replay capsules | Prove promoted editions are reproducible and rollback-ready. |
+| graph evolution commands | Provide human/AI editing surfaces for draft and migration flows. |
+| database contract surfaces | Persist realtime revisions, collaboration history, and rollback anchors. |
+
+## Managed CompanyOS posture
+
+Managed CompanyOS should start with file-backed published editions for stable contracts and database-backed experiment editions for fast vertical iteration. Database drafts materialize to file patches before release unless the vertical policy explicitly grants database authority for that lifecycle state.`}},{id:"docs.tech.contracts.entities.compatibility",exportName:"tech_contracts_entities_compatibility_DocBlocks",sourceModule:"entities/compatibility",block:{id:"docs.tech.contracts.entities.compatibility",title:"Contract Entity Ontology Compatibility Ledger",summary:"Entity ontology symbols are additive from the root barrel and the narrow `./entities` package subpath.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/entities/compatibility",tags:["tech","contracts","entities","compatibility","exports"],body:`# Contract Entity Ontology Compatibility Ledger
+
+The entity ontology public surface is intentionally additive through the root barrel and the narrow \`./entities\` package subpath.
+
+## Public import
+
+\`\`\`ts
+import {
+  defineContractEntity,
+  defineContractEdge,
+  EntityRegistry,
+} from '@lssm/lib.contracts-spec/entities';
+\`\`\`
+
+## Compatibility decision
+
+- \`@lssm/lib.contracts-spec\` exports the entity ontology symbols from the root barrel.
+- \`@lssm/lib.contracts-spec/entities\` is not introduced by this ledger.
+- Future work that adds \`./entities\` must update \`package.json\`, the publish exports, tests, docs, and release metadata together.
+`}},{id:"docs.tech.contracts.entities.edge",exportName:"tech_contracts_entities_edge_DocBlocks",sourceModule:"entities/defineContractEdge",block:{id:"docs.tech.contracts.entities.edge",title:"ContractEdgeSpec — Declarative Graph Edge Contract",summary:"`ContractEdgeSpec` is the declarative graph edge contract: a versioned, ownership-tagged wrapper around `EdgeSpec` for use in `EntityRegistry` and graph `DataViewSpec` sources.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/entities/edge",tags:["tech","contracts","entities","edge","graph"],body:`# ContractEdgeSpec
+
+## Purpose
+
+\`ContractEdgeSpec\` pairs an \`EdgeSpec\` with standard ownership metadata so
+graph edges can be registered, versioned, and discovered the same way other
+ContractSpec contracts are.
+
+## Factory
+
+\`\`\`typescript
+import { defineContractEdge } from '@lssm/lib.contracts-spec';
+
+export const UserToProjectEdge = defineContractEdge({
+  meta: {
+    key: 'user-to-project',
+    version: '1.0.0',
+    description: 'A user owns zero or more projects.',
+    stability: 'stable',
+    owners: ['platform.core'],
+    tags: ['graph'],
+  },
+  edge: { id: 'user-to-project', from: 'user', to: 'project', relation: 'has-many', cardinality: 'one-to-many', directed: true },
+});
+\`\`\`
+
+## Registry
+
+Register via \`EntityRegistry\`:
+
+\`\`\`typescript
+const registry = new EntityRegistry();
+registry.registerEdge(UserToProjectEdge);
+\`\`\`
+
+## Related
+
+- \`EdgeSpec\` — the inline edge shape (see \`entities/types.ts\`)
+- \`ContractEntitySpec\` — entity-level wrapper that can declare edges inline
+- \`EntityRegistry\` — stores both entity and edge contracts
+`}},{id:"docs.tech.contracts.entities.entity",exportName:"tech_contracts_entities_entity_DocBlocks",sourceModule:"entities/defineContractEntity",block:{id:"docs.tech.contracts.entities.entity",title:"ContractEntitySpec — Declarative Entity Contract (Layer 1 + 2)",summary:"`ContractEntitySpec` is the entity contract supporting two adoption layers: Layer 1 (slug + edges only) and Layer 2 (full `EntitySpec<TFields>` + edges). Schema layer's `defineEntity` is untouched per A4.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/entities/entity",tags:["tech","contracts","entities","graph"],body:`# ContractEntitySpec
+
+## Purpose
+
+\`ContractEntitySpec\` is the entity contract. It provides:
+
+1. A canonical **entity slug** via \`meta.key\`.
+2. Optional **inline edges** (\`edges?: EdgeSpec[]\`).
+3. Standard **ownership metadata** (version, stability, owners, tags).
+4. **Layer 2**: optional \`entity?: EntitySpec<TFields>\` for DB-modeling semantics
+   delegated to \`@lssm/lib.schema\`'s \`EntitySpec\`.
+
+## Layer Summary
+
+| Layer | What ships | \`entity\` field |
+|-------|------------|-----------------|
+| **Layer 1** | slug + edges | omitted |
+| **Layer 2** | slug + full \`EntitySpec<TFields>\` + edges | required |
+
+## Layer 1 Usage (slug + edges)
+
+\`\`\`typescript
+import { defineContractEntity } from '@lssm/lib.contracts-spec';
+
+export const UserEntity = defineContractEntity({
+  meta: {
+    key: 'user',
+    version: '1.0.0',
+    description: 'Platform user entity.',
+    stability: 'stable',
+    owners: ['platform.core'],
+    tags: ['user', 'auth'],
+  },
+  edges: [
+    { id: 'user-to-project', from: 'user', to: 'project', relation: 'has-many', cardinality: 'one-to-many', directed: true },
+  ],
+});
+\`\`\`
+
+## Layer 2 Usage (full EntitySpec + edges)
+
+\`\`\`typescript
+import { defineContractEntity } from '@lssm/lib.contracts-spec';
+import { defineEntity, field } from '@lssm/lib.schema';
+
+export const UserEntity = defineContractEntity({
+  meta: {
+    key: 'user',
+    version: '1.0.0',
+    description: 'Platform user with auth + profile.',
+    stability: 'stable',
+    owners: ['platform.core'],
+    tags: ['user', 'auth'],
+  },
+  entity: defineEntity({
+    name: 'User',
+    description: 'Platform user with auth + profile.',
+    fields: {
+      id: field.id(),
+      email: field.email(),
+      createdAt: field.createdAt(),
+    },
+  }),
+  edges: [
+    { id: 'user-to-project', from: 'user', to: 'project', relation: 'has-many', cardinality: 'one-to-many', directed: true },
+  ],
+});
+\`\`\`
+
+## A4 Constraint
+
+The schema layer's \`defineEntity\` (\`@lssm/lib.schema\`) remains untouched.
+\`defineContractEntity\` accepts its output via **structural typing** — no wrapping,
+no re-implementation, no modification to the schema package.
+
+## Registry Precondition (C12)
+
+The \`EntityRegistry\` holding this spec **must** be initialized before graph
+\`DataViewRenderer\` accesses entity slugs or edge relationships.
+`}},{id:"docs.tech.contracts.entities.registry",exportName:"tech_contracts_entities_registry_DocBlocks",sourceModule:"entities/registry",block:{id:"docs.tech.contracts.entities.registry",title:"EntityRegistry — Entity & Edge Contract Registry",summary:"`EntityRegistry` stores `ContractEntitySpec` and `ContractEdgeSpec` instances, then exposes a unified `listEdges()` view for graph renderers.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/entities/registry",tags:["tech","contracts","entities","registry","graph"],body:"# EntityRegistry\n\n## Purpose\n\n`EntityRegistry` is the single runtime store for entity and edge contracts.\nIt extends `SpecContractRegistry<'entity', ContractEntitySpec>` and adds a\nsecondary edge map for named `ContractEdgeSpec` entries.\n\n## Initialization (C12 Precondition)\n\nThe registry **must** be initialized (entities and edges registered) before\nany graph `DataViewRenderer` reads entity slugs or edge relationships.\nInline-edge-only views do not share this requirement.\n\n## API Summary\n\n| Method | Description |\n|--------|-------------|\n| `register(spec)` | Register a `ContractEntitySpec` (inherited). |\n| `registerEdge(spec)` | Register a named `ContractEdgeSpec`. |\n| `list()` | List all entity specs (inherited). |\n| `listEdgeSpecs()` | List all named edge specs. |\n| `listEdges()` | Unified flat list of all `EdgeSpec` (inline + named). |\n| `get(key, version?)` | Retrieve entity spec by key (inherited). |\n| `getEdge(key, version?)` | Retrieve named edge spec by key. |\n\n## Example\n\n```typescript\nconst registry = new EntityRegistry([UserEntity, ProjectEntity]);\nregistry.registerEdge(UserToProjectEdge);\n\nconst edges = registry.listEdges();\n// [{ id: 'user-to-project', from: 'user', to: 'project', relation: 'has-many', cardinality: 'one-to-many', ... }]\n```\n"}},{id:"docs.tech.contracts.entities.types",exportName:"tech_contracts_entities_types_DocBlocks",sourceModule:"entities/types",block:{id:"docs.tech.contracts.entities.types",title:"EdgeSpec — Graph Edge Contract Type",summary:"`EdgeSpec` is the Layer-1 declarative type for a relationship between two entity slugs in a ContractSpec graph view. Required fields: `id`, `from`, `to`, `relation`, `cardinality`.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/entities/types",tags:["tech","contracts","entities","edge","graph"],body:"# EdgeSpec\n\n## Purpose\n\n`EdgeSpec` describes a graph edge (relationship) between two entity types in\na ContractSpec graph view.\n\n## Fields\n\n| Field         | Type                                                          | Required | Description                                |\n|---------------|---------------------------------------------------------------|----------|--------------------------------------------|\n| `id`        | `string`                                                    | ✅       | Stable edge identifier                     |\n| `from`      | `string`                                                    | ✅       | Entity key of the source node              |\n| `to`        | `string`                                                    | ✅       | Entity key of the target node              |\n| `relation`  | `string`                                                    | ✅       | Semantic relation name                     |\n| `cardinality` | `'one-to-one' \\| 'one-to-many' \\| 'many-to-one' \\| 'many-to-many'` | ✅ | Cardinality |\n| `directed`  | `boolean`                                                   | —        | Defaults to `true` (from → to)           |\n| `inverse`   | `string`                                                    | —        | `id` of the inverse edge spec            |\n| `traversal` | `{ strategy?, maxDepth? }`                                  | —        | Graph traversal hints                      |\n| `label`     | `string`                                                    | —        | Human-readable edge label in graph views   |\n| `attributes` | `Record<string, unknown>`                                  | —        | Domain-specific rendering/rule metadata    |\n\n## Layer Roadmap\n\n- **Layer 1** (current): id + from/to + relation + cardinality. No DB modeling.\n- **Layer 2** (Phase 2): full `EntitySpec<TFields>` + edges via `defineContractEntity`.\n\n## Example\n\n```typescript\nimport { defineContractEdge } from '@lssm/lib.contracts-spec';\n\nconst UserToProjectEdge = defineContractEdge({\n  meta: { key: 'user-to-project', version: '1.0.0', description: '...', stability: 'stable', owners: [], tags: [] },\n  edge: {\n    id: 'user-to-project',\n    from: 'user',\n    to: 'project',\n    relation: 'has-many',\n    cardinality: 'one-to-many',\n    directed: true,\n  },\n});\n```\n"}},{id:"docs.tech.contracts.examples",exportName:"tech_contracts_examples_DocBlocks",sourceModule:"examples/index",block:{id:"docs.tech.contracts.examples",title:"Example Specifications",summary:"ExampleSpec defines complete, demonstrable ContractSpec applications.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/examples",tags:["tech","contracts","examples","templates"],body:`## Example Specifications
+
+ExampleSpec is a contract for defining complete, demonstrable ContractSpec applications. Examples integrate with AppBlueprintSpec and FeatureModuleSpec to provide a full application specification.
+
+### Overview
+
+An \`ExampleSpec\` captures:
+- **Metadata** (via \`ExampleMeta\` extending \`OwnerShipMeta\`): key, version, title, description, ownership, tags, stability
+- **Example-specific fields**: kind, visibility, summary
+- **Surfaces**: where the example can be used (templates, sandbox, studio, MCP)
+- **Entrypoints**: package exports mapping
+- **Blueprint**: optional AppBlueprintSpec or reference
+- **Features**: optional FeatureModuleSpec array or references
+
+### Usage
+
+\`\`\`typescript
+
+const example: ExampleSpec = {
+  meta: {
+    key: 'saas-boilerplate',
+    version: '1.0.0',
+    title: 'SaaS Boilerplate',
+    description: 'Multi-tenant SaaS foundation with billing and RBAC.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@saas-team'],
+    tags: ['saas', 'multi-tenant', 'billing'],
+    summary: 'Complete SaaS starter.',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'specs', 'builder'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+  entrypoints: {
+    packageName: '@lssm/example.saas-boilerplate',
+    feature: './saas-boilerplate.feature',
+    contracts: './contracts',
+  },
+  features: [SaasBoilerplateFeature],
+};
+\`\`\`
+
+### ExampleRegistry
+
+Use \`ExampleRegistry\` to manage examples:
+
+\`\`\`typescript
+const registry = new ExampleRegistry();
+registry.register(example);
+
+// Query examples
+registry.listByKind('template');
+registry.listByVisibility('public');
+registry.listBySurface('studio');
+registry.listInstallable();
+registry.search('billing');
+\`\`\`
+
+### ExampleMeta
+
+\`ExampleMeta\` extends \`OwnerShipMeta\` with example-specific fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| key | string | Unique identifier |
+| version | number | Spec version |
+| title | string? | Human-readable title |
+| description | string | Technical description |
+| kind | ExampleKind | template, workflow, integration, etc. |
+| visibility | ExampleVisibility | public, internal, experimental |
+| stability | Stability | idea, experimental, beta, stable, deprecated |
+| owners | string[] | Owner identifiers |
+| tags | string[] | Discovery tags |
+| summary | string? | Marketing summary |
+
+### ExampleKind
+
+| Kind | Use Case |
+|------|----------|
+| template | Full application template |
+| workflow | Workflow automation example |
+| integration | Integration showcase |
+| knowledge | Knowledge base example |
+| blueprint | App blueprint example |
+| ui | UI component showcase |
+| script | CLI/script example |
+| library | Library/SDK example |
+
+### Surfaces
+
+| Surface | Purpose |
+|---------|---------|
+| templates | Available as new project template |
+| sandbox | Interactive playground support |
+| studio | ContractSpec Studio support |
+| mcp | Model Context Protocol support |
+
+### Validation
+
+\`\`\`typescript
+
+const result = validateExample(example);
+if (!result.valid) {
+  console.error(result.errors);
+}
+
+// Batch validation with duplicate detection
+const batchResult = validateExamples([example1, example2]);
+\`\`\`
+
+### Integration with Blueprints and Features
+
+Examples can reference or embed blueprints and features:
+
+\`\`\`typescript
+const example: ExampleSpec = {
+  // ... meta, surfaces, entrypoints
+  
+  // Inline blueprint
+  blueprint: myAppBlueprint,
+  
+  // Or reference by pointer
+  blueprint: { key: 'core.app', version: '1.0.0' },
+  
+  // Inline features
+  features: [MyFeature],
+  
+  // Or reference
+  features: [{ key: 'my-feature' }],
+};
+\`\`\`
+
+### Related
+
+- [App Configuration](file:///docs/tech/contracts/app-config) - AppBlueprintSpec
+- [Features](file:///docs/tech/contracts/features) - FeatureModuleSpec
+`}},{id:"docs.tech.contracts.experiments",exportName:"tech_contracts_experiments_DocBlocks",sourceModule:"experiments/spec",block:{id:"docs.tech.contracts.experiments",title:"ExperimentSpec & ExperimentEvaluator",summary:"Use experiments to test alternative workflows, data views, or themes with controlled allocations and measurable outcomes.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/experiments",tags:["tech","contracts","experiments"],body:`# ExperimentSpec & ExperimentEvaluator
+
+Use experiments to test alternative workflows, data views, or themes with controlled allocations and measurable outcomes.
+
+- Types & registry: \`packages/libs/contracts/src/experiments/spec.ts\`
+- Runtime evaluator: \`packages/libs/contracts/src/experiments/evaluator.ts\`
+- CLI wizard/template: \`contractspec create experiment\`
+
+## Structure
+
+\`\`\`ts
+export interface ExperimentSpec {
+  meta: ExperimentMeta;
+  controlVariant: string;
+  variants: ExperimentVariant[];
+  allocation: AllocationStrategy;
+  successMetrics?: SuccessMetric[];
+}
+\`\`\`
+
+- \`variants\`: define UI/behavior overrides (data views, workflows, themes, policies)
+- \`allocation\`:
+  - \`random\`: 50/50 or weighted via \`weight\`
+  - \`sticky\`: deterministic hash on user/organization/session
+  - \`targeted\`: rule-based (policy + expression + optional percentage)
+- \`successMetrics\`: telemetry events + aggregation (count/avg/p95) to track outcomes
+
+### Example
+
+\`\`\`ts
+export const OnboardingSplitFormExperiment: ExperimentSpec = {
+  meta: {
+    name: 'sigil.onboarding.split_form',
+    version: '1.0.0',
+    title: 'Split onboarding form',
+    description: 'Compare single vs multi-step onboarding',
+    domain: 'onboarding',
+    owners: ['@team.onboarding'],
+    tags: ['experiment'],
+    stability: StabilityEnum.Experimental,
+  },
+  controlVariant: 'control',
+  variants: [
+    { id: 'control', name: 'Single-step form' },
+    {
+      id: 'multi_step',
+      name: 'Multi-step form',
+      overrides: [
+        { type: 'workflow', target: 'sigil.onboarding.workflow.multi_step' },
+      ],
+    },
+  ],
+  allocation: {
+    type: 'targeted',
+    rules: [
+      {
+        variantId: 'multi_step',
+        expression: "context.attributes?.segment === 'vip'",
+      },
+    ],
+    fallback: 'random',
+  },
+  successMetrics: [
+    {
+      name: 'Completion rate',
+      telemetryEvent: { name: 'sigil.telemetry.onboarding_completed', version: '1.0.0' },
+      aggregation: 'count',
+    },
+  ],
+};
+\`\`\`
+
+## Variant evaluation
+
+\`\`\`ts
+const evaluator = new ExperimentEvaluator({
+  registry: experimentRegistry,
+  policyChecker: (policyRef, context) =>
+    policyEngine.decide({
+      action: 'experiment_targeting',
+      subject: { roles: context.flags },
+      resource: { type: 'experiment', attributes: { name: context.experiment } },
+      policies: [policyRef],
+    }).effect === 'allow',
+});
+
+const assignment = await evaluator.chooseVariant({
+  experiment: 'sigil.onboarding.split_form',
+  userId: ctx.userId,
+  organizationId: ctx.organizationId,
+  attributes: ctx.attributes,
+});
+
+if (assignment) {
+  // Apply overrides for the chosen variant
+  applyExperimentOverrides(assignment.variant);
+}
+\`\`\`
+
+- \`random\` uses deterministic hashing (\`salt\` optional) for stable splits
+- \`sticky\` hashes a specified attribute (userId/orgId/sessionId)
+- \`targeted\` evaluates rules in order; each rule can reference a PolicySpec and simple JS expressions (\`context\` input)
+
+## Integrations
+
+- **Feature modules**: \`FeatureModuleSpec.experiments\` references experiments owned by a module
+- **DataViewSpec / WorkflowSpec**: \`experiments?: ExperimentRef[]\` indicate which experiments modify the spec
+- **Telemetry**: success metrics reference \`TelemetrySpec\` events to ensure compliant tracking
+- **Policy**: targeting rules call into \`PolicyEngine\` via the evaluator callback to respect privacy/security
+
+## CLI workflow
+
+\`\`\`
+contractspec create experiment
+\`\`\`
+
+- Prompts for control/variants, allocation strategy, targeting rules, success metrics
+- Outputs a typed \`ExperimentSpec\` file alongside your contracts
+
+## Best practices
+
+1. Keep experiments short-lived; increment \`meta.version\` when changing allocation or variants.
+2. Always declare a control variant and ensure overrides are reversible.
+3. Tie success metrics to privacy-reviewed telemetry events.
+4. Use targeting rules sparingly; combine with PolicySpec to avoid exposing experiments to unauthorized users.
+5. When an experiment wins, promote the variant to the canonical spec and retire the experiment.
+
+`}},{id:"docs.tech.contracts.forms",exportName:"tech_contracts_forms_DocBlocks",sourceModule:"forms/forms",block:{id:"docs.tech.contracts.forms",title:"Contracts: FormSpec",summary:"This document defines the canonical contracts for declarative forms.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/forms",tags:["tech","contracts","forms"],body:"# Contracts: FormSpec\n\nThis document defines the canonical contracts for declarative forms.\n\n## Overview\n\n- `FormSpec` (in `@lssm/lib.contracts-spec/forms`) declares:\n  - `meta` (extends `OwnerShipMeta`) + `key`/`version` for stability.\n  - `model` (`@lssm/lib.schema` `SchemaModel`) as the single source of truth.\n  - `fields` built from `FieldSpec` kinds: `text`, `email`, `textarea`, `select`, `checkbox`, `radio`, `switch`, `autocomplete`, `address`, `phone`, `number`, `percent`, `currency`, `date`, `time`, `datetime`, `duration`, `group`, `array`.\n  - `text.password` for masked current/new password fields with password-manager hints.\n  - field-level `readOnly` support that preserves submitted values.\n  - Optional `layout`, `layout.flow`, `actions`, `policy.flags`, `constraints` and `renderHints`.\n- Relations DSL provides `visibleWhen`, `enabledWhen`, `requiredWhen` based on predicates.\n- Entity-bound projections use `projection.parts` for form-to-entity-path\n  part bindings and `projection.relatedEdges` for references to actual\n  entity `EdgeSpec` relations. Part bindings do not own graph cardinality.\n- `FormRegistry.getByEntityProjection(entityKey, projectionKind, version?)`\n  deterministically resolves quick/full/intake/edit/part forms by entity\n  projection metadata instead of by renderable form key only.\n- `buildZodWithRelations(spec)` augments the base zod with conditional rules and constraints.\n- Entity-bound projections are declared with optional `projection` metadata:\n  `quick`, `full`, `intake`, `edit`, and `part` forms remain normal\n  renderable `FormSpec` objects while `FormProjectionSpec.entity` binds them\n  to a canonical `ContractEntitySpec.meta.key`.\n- `captureFormIntake(spec, values)` is permissive by design: it returns\n  `accepted: true` for partial values and records missing completion debt.\n- `evaluateFormCompletion(spec, values)` is the strict readiness companion:\n  it reports missing `FormCompletionDebt` for a completion profile without\n  invalidating the permissive capture result.\n- React adapter renders with React Hook Form + driver API for UI components.\n\n## Rich field contracts\n\n- `autocomplete` supports local filtering or resolver-backed search, including debounce/min-query hints and configurable submit-value mapping.\n- Resolver-backed autocomplete stays runtime-neutral: forms declare `resolverKey`, dependency paths, and optional args while host renderers provide the actual fetcher.\n- `email` represents one string email-address field; schema validation remains model-owned while renderers supply email input affordances.\n- `address` uses the canonical `AddressFormValue` object shape.\n- `phone` uses the canonical `PhoneFormValue` object shape.\n- `number`, `percent`, and `currency` map numeric schema intent to native input controls while preserving locale, precision, rounding, and currency-display metadata.\n- `date`, `time`, `datetime`, and `duration` map temporal schema intent to native controls while preserving locale, timezone, unit, and display metadata.\n- `array` remains the canonical dynamic-field primitive and can repeat grouped item layouts.\n- `text` can declare `password.purpose` as `current` or `new`; renderers map those to masked controls and `current-password` / `new-password` autocomplete hints.\n\n## Progressive form layout\n\n- `layout.flow.kind: \"sections\"` groups existing fields into accessible sections while keeping all sections visible.\n- `layout.flow.kind: \"steps\"` uses the same section metadata for progressive, one-section-at-a-time rendering.\n- `FormSectionSpec.fieldNames` references existing immediate field names; field definitions stay in `FormSpec.fields`.\n- Unlisted fields remain visible so flow metadata cannot accidentally drop required model inputs.\n- `text` and `textarea` can declare portable `inputGroup` addons for text and host-resolved icons.\n\n## Entity-bound projections and intake\n\n- Entity-bound form work is entity-first: canonical identity and true entity-to-entity relations stay on entity contracts.\n- Forms remain renderable projections. Quick, full, edit, intake, and part forms should be discoverable by entity key, projection kind, and optional version.\n- Form part bindings describe sub-capture surfaces such as identity or address. They must not overload `EdgeSpec`, which remains reserved for real entity graph relations and cardinality.\n- Capture acceptance and strict readiness are separate. Quick or message intake can accept partial values and return completion debt; stricter profiles can later report missing fields without rejecting the original capture.\n- Communication runtime intake hooks should map normalized messages into entity-bound intake payloads with source refs and completion debt. They should not implement full AI extraction, database persistence, or CommunicationOS UI.\n- The public documentation/migration subpath for this first-pass guidance is `@lssm/lib.contracts-spec/forms/entity-bound`.\n- Form configuration chrome is a design-system concern: reuse `FormConfigShell`, `FormConfigMenuBar`, and `FormConfigPanel` from `@lssm/lib.design-system/forms` instead of forking configuration panels in examples or apps.\n- FormSpec and FormConfig docs describe render/config metadata only. Persistence of drafts, submissions, credentials, or tenant state remains host-owned and approval-gated; examples should expose deterministic proof maps, not storage guarantees.\n\n## Layout and Groups\n\n- `FormSpec.layout` and `group.layout` can declare 1-4 responsive columns, gap size, and default field orientation.\n- `field.layout.colSpan` lets fields span one or more grid columns or the full row.\n- `wrapper.orientation` remains a compatibility alias for `layout.orientation`.\n- `group.legendI18n` renders as the semantic legend, falling back to `labelI18n`.\n\n## Driver API (UI-agnostic)\n\nHost apps supply a driver mapping slots to components:\n\n- Required: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Autocomplete`, `AddressField`, `PhoneField`, `NumberField`, `PercentField`, `CurrencyField`, `DateField`, `TimeField`, `DateTimeField`, `DurationField`, `Button`.\n- Optional: `FieldContent`, `FieldGroup`, `FieldSet`, `FieldLegend`, `FieldSeparator`, `InputGroup`, `InputGroupAddon`, `InputGroupInput`, `InputGroupTextarea`, `InputGroupText`, `InputGroupIcon`, and `PasswordInput`.\n- Autocomplete drivers should accept optional `loading`, `error`, `emptyText`, `loadingText`, and `errorText` props so resolver-backed fields can expose async state without embedding transport details in the contract.\n\nUse `createFormRenderer({ driver })` to obtain a `render(spec)` function.\n\n## Arrays and Groups\n\n- `array` items are rendered with `useFieldArray`, honoring `min`/`max` and add/remove controls.\n- `array.of` can repeat grouped multi-field rows.\n- `group` composes nested fields and provides optional legend/description/layout.\n\n## Feature Flags\n\n- Declare `policy.flags` on forms to signal gating. Gate usage at host boundary; avoid scattering flags across individual fields.\n\n## Example\n\nUse the exported `RichFieldsShowcaseForm` as the canonical reference for readonly, password, autocomplete, address, phone, temporal, layout, and input-group field authoring.\n"}},{id:"docs.tech.contracts.forms.entityBound",exportName:"tech_contracts_forms_entity_bound_DocBlocks",sourceModule:"forms/entity-bound-forms",block:{id:"docs.tech.contracts.forms.entityBound",title:"Contracts: Entity-bound Form Projections",summary:"How to model entity-first form projections, completion debt, and message intake without overloading entity edges.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/forms/entity-bound",tags:["tech","contracts","forms","entities","intake"],body:`# Entity-bound form projections
+
+Entity-bound forms treat the business entity as the stable semantic anchor and the form as a renderable projection. A customer, appointment, or other entity can expose quick, full, edit, intake, or part projections without turning each projection into a new entity type.
+
+## Authoring model
+
+- Keep canonical entity identity and true entity-to-entity cardinality on entity contracts.
+- Keep renderable fields, layout, policy, and actions on \`FormSpec\`.
+- Bind a form projection to an entity with metadata such as entity key, projection kind, version, and field/path mappings.
+- Use form-part bindings for identity, address, contact, and other sub-capture surfaces when they are parts of one entity.
+- Use \`EdgeSpec\` only for real entity relations, such as customer-to-appointment, not for field-group containment.
+
+## Capture versus readiness
+
+Capture acceptance and completion readiness are intentionally separate:
+
+1. **Capture accepted** means the user or message provided enough information to preserve a draft/intake payload.
+2. **Completion debt** records skipped or missing fields with path/profile metadata.
+3. **Strict readiness** can later require a full profile without invalidating the original capture.
+
+This keeps quick creation and message intake permissive while still giving downstream workflows explicit quality gates.
+
+## Communication intake boundary
+
+Communication runtime may map a normalized message/request into an entity-bound intake payload, but it should stay deterministic and adapter-free. The first-pass hook should carry source references such as message id, thread id, and channel, then return accepted values plus completion debt. Full AI extraction, persistence, and CommunicationOS UI remain downstream concerns.
+
+## Package exports
+
+Consumers should import the form projection documentation surface from \`@lssm/lib.contracts-spec/forms/entity-bound\` and implementation primitives from \`@lssm/lib.contracts-spec/forms\` unless a narrower subpath is introduced with matching package exports and tests.
+`}},{id:"docs.tech.contracts.knowledge",exportName:"tech_contracts_knowledge_DocBlocks",sourceModule:"knowledge/spec",block:{id:"docs.tech.contracts.knowledge",title:"Knowledge Layer",summary:"The knowledge layer turns unstructured inputs (uploads, email threads,",kind:"reference",visibility:"public",route:"/docs/tech/contracts/knowledge",tags:["tech","contracts","knowledge"],body:`# Knowledge Layer
+
+The knowledge layer turns unstructured inputs (uploads, email threads,
+notes) into searchable context for agents and workflows. The Pocket
+Family Office vertical ships a minimal but production-ready stack that
+covers ingestion, indexing, querying, and guardrails.
+
+## Knowledge Spaces
+
+Knowledge is organised via \`KnowledgeSpaceSpec\` definitions under
+\`packages/libs/contracts-spec/src/knowledge/spaces\`:
+
+- \`knowledge.financial-docs\` – canonical invoices, bills, and contracts.
+- \`knowledge.email-threads\` – operational Gmail threads.
+- \`knowledge.support-faq\` / \`knowledge.product-canon\` – reusable shared
+  spaces available to any vertical.
+
+Each space defines:
+
+- Ownership metadata (domain, owners, stability tags).
+- Retention policy (TTL/archival).
+- Access policy (trust level, automation write permissions).
+- Indexing configuration (embedding model, chunk size, vector DB slot).
+
+## Sources & Bindings
+
+- \`KnowledgeSourceConfig\` records tenant-specific connections (bucket,
+  Gmail labels, sync cadence). Pocket Family Office provides sample
+  configs in \`knowledge/sources.sample.ts\`.
+- \`AppKnowledgeBinding\` associates spaces with workflows/agents and adds
+  per-tenant constraints (rate limits, scopes).
+
+Validation ensures that:
+
+- All referenced spaces exist in the registry.
+- At least one source is configured per binding.
+- External/ephemeral spaces trigger warnings for policy-sensitive flows.
+
+## Ingestion Pipeline
+
+Implemented in \`@lssm/lib.knowledge/ingestion\`:
+
+1. **DocumentProcessor** – pluggable MIME extractors producing
+   \`DocumentFragment\`s.
+2. **EmbeddingService** – batches fragments through an \`EmbeddingProvider\`
+   (Mistral in the reference implementation).
+3. **VectorIndexer** – upserts fragments into a \`VectorStoreProvider\`
+   (Qdrant in production, with in-memory implementations for tests) and
+   persists canonical \`payload.text\` content alongside fragment metadata
+   so retrieval and query flows can reuse indexed text directly.
+4. **Adapters**
+   - \`GmailIngestionAdapter\`: list threads → convert to raw documents →
+     index.
+   - \`StorageIngestionAdapter\`: fetch object from storage provider →
+     index.
+
+Background jobs (see \`@lssm/lib.jobs\`) orchestrate ingestion via
+Cloud Tasks / Pub/Sub or in-memory workers. Handlers:
+
+- \`storage-document-handler\` – resolves storage object + indexes.
+- \`gmail-sync-handler\` – syncs threads based on label/date filters.
+
+## Query Service
+
+\`KnowledgeQueryService\` performs retrieval-augmented generation:
+
+1. Embed the user query using the configured provider.
+2. Search the vector store for top-k matches.
+3. Compose prompts combining system instructions + indexed contextual
+   snippets from \`payload.text\` (falling back to legacy \`payload.content\`
+   when needed).
+4. Invoke the LLM provider (Mistral) and return the answer plus
+   references and token usage.
+
+The service is designed for tooling: workflows can execute it directly
+or through custom operations (see \`pfo.summary.generate\` contract).
+
+## Guardrails
+
+- Automation can only write to spaces where \`automationWritable\` is true.
+- Canonical spaces default to high trust; external/ephemeral spaces are
+  flagged during validation.
+- Provider-free knowledge flows must block stale runbook or low-confidence
+  evidence before action, and non-dry-run knowledge mutations require approval
+  or audit references before execution.
+- Telemetry captures query volumes per tenant + space.
+
+## Extending
+
+1. Define a new \`KnowledgeSpaceSpec\` with indexing/retention policies.
+2. Add sources pointing to storage providers or APIs.
+3. Register adapters if ingestion requires bespoke logic.
+4. Reference the space in blueprints (\`AppKnowledgeBinding\`) and update
+   workflows/agents accordingly.
+
+The Pocket Family Office tests (\`tests/pocket-family-office.test.ts\`)
+show how to wire the ingestion pipeline, index a document, and run an
+end-to-end knowledge query using in-memory providers.
+## Knowledge Spaces & Guardrails
+
+Knowledge surfaces (\`KnowledgeSpaceSpec\`) describe curated corpora that agents and workflows can consult. Tenant bindings (\`AppKnowledgeBinding\`) declare which spaces are active, who can use them, and optional usage constraints.
+
+### Binding recap
+
+- \`spaceKey\` / \`spaceVersion\`: pointer to the \`KnowledgeSpaceSpec\`
+- \`scope.workflows\` / \`scope.agents\`: explicit allow-lists for consumers
+- \`constraints.maxTokensPerQuery\` & \`constraints.maxQueriesPerMinute\`: throttling knobs for LLM-backed search
+- \`required\`: mark the binding as blocking (defaults to \`true\`)
+
+At runtime, \`ResolvedAppConfig.knowledge\` contains \`ResolvedKnowledge\` entries with the bound space, active sources, and the binding metadata above.
+
+### KnowledgeAccessGuard
+
+\`KnowledgeAccessGuard\` (\`@lssm/lib.knowledge/access/guard\`) centralises the access checks that must run before any workflow/agent reads or mutates a knowledge space.
+
+\`\`\`ts
+import { KnowledgeAccessGuard } from '@lssm/lib.knowledge/access/guard';
+
+const guard = new KnowledgeAccessGuard({
+  disallowWriteCategories: ['external', 'ephemeral'], // default
+  requireWorkflowBinding: true,
+  requireAgentBinding: false,
+});
+
+const result = guard.checkAccess(resolvedKnowledge, {
+  tenantId,
+  appId,
+  workflowName: 'order-processing',
+  operation: 'read', // or 'write' / 'search'
+}, resolvedAppConfig);
+
+if (!result.allowed) {
+  throw new Error(result.reason);
+}
+\`\`\`
+
+Key behaviours:
+
+- **Binding**: rejects access when the space is not present in the resolved tenant config.
+- **Category guardrails**: blocks writes to \`external\` and \`ephemeral\` spaces by default; allows reads but emits warnings for \`ephemeral\`.
+- **Workflow/agent scoping**: when \`requireWorkflowBinding\` or \`requireAgentBinding\` is enabled, only explicitly authorised consumers may access the space.
+
+Use the guard inside workflow operations or agent resolvers to guarantee multi-tenant isolation and honour data governance rules.
+
+## Agent memory tools and ephemeral spaces
+
+Ephemeral spaces (\`category: 'ephemeral'\`) are the canonical home for agent memory storage (scratchpads, session context, drafts). Agent memory tools (Anthropic \`memory_20250818\`, custom operation-backed) can use ephemeral spaces as storage when configured with \`memoryTools.spaceKey\`.
+
+### Enabling agent memory writes
+
+By default, \`KnowledgeAccessGuard\` blocks writes to ephemeral spaces (\`disallowWriteCategories: ['external', 'ephemeral']\`). To allow agent memory tools to write:
+
+1. Configure \`disallowWriteCategories: ['external']\` (allow ephemeral writes).
+2. Ensure \`AppKnowledgeBinding.scope.agents\` includes the agent key when using knowledge-backed storage.
+3. Set \`requireAgentBinding: true\` so only explicitly bound agents can write.
+
+See \`@lssm/lib.ai-agent\` memory tools and \`AgentMemoryStore\` for implementation details.
+`}},{id:"docs.tech.contracts.knowledge-provider-backed",exportName:"tech_contracts_knowledge_DocBlocks",sourceModule:"knowledge/spec",block:{id:"docs.tech.contracts.knowledge-provider-backed",title:"Provider-backed knowledge",summary:"Provider-backed knowledge syncs Gmail and Google Drive through explicit provider delta and mutation governance evidence.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/knowledge-provider-backed",tags:["tech","contracts","knowledge","integrations"],body:`# Provider-backed knowledge
+
+Provider-backed knowledge starts from the same \`KnowledgeSpaceSpec\` and
+\`KnowledgeSourceConfig\` surfaces, then adds explicit provider delta and
+mutation governance evidence before runtime sync begins.
+
+Gmail and Google Drive ingestion should persist \`ProviderDeltaSyncState\` per
+source so leases, cursors, webhook channel expiry, provider event IDs,
+dedupe/idempotency keys, replay checkpoints, and tombstones survive retries.
+
+External mutations should route through
+\`knowledge.mutation.evaluateGovernance\` or
+\`@lssm/lib.knowledge/governance\` so dry-runs, approval refs,
+idempotency keys, audit evidence, and outbound-send gates are recorded before
+provider writes happen.`}},{id:"docs.tech.contracts.migrations",exportName:"tech_contracts_migrations_DocBlocks",sourceModule:"migrations",block:{id:"docs.tech.contracts.migrations",title:"MigrationSpec Overview",summary:"`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, target dialect, generated artifact provenance, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/migrations",tags:["tech","contracts","migrations"],body:`# MigrationSpec Overview
+
+## Purpose
+
+\`MigrationSpec\` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, target dialect, generated artifact provenance, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.
+
+## Location
+
+- Spec + registry: \`packages/libs/contracts/src/migrations.ts\`
+- Tests: \`packages/.../migrations.test.ts\`
+
+## Schema
+
+\`\`\`ts
+export interface MigrationSpec {
+  meta: MigrationMeta;   // ownership metadata + { name, version }
+  plan: {
+    up: MigrationStep[];   // required forward plan
+    down?: MigrationStep[];// optional rollback steps
+  };
+  dependencies?: string[]; // optional list of migration keys this depends on
+}
+\`\`\`
+
+- **MigrationStep**
+  - \`kind\`: \`'schema' | 'data' | 'validation'\`
+  - Shared fields: \`description?\`, \`timeoutMs?\`, \`retries?\`, \`preChecks?\`, \`postChecks?\`
+  - \`schema\`: \`sql\` string executed in transactional context
+  - \`data\`: arbitrary \`script\` (e.g., JS/TS snippet, path to file, instructions)
+  - \`validation\`: \`assertion\` expression verifying state (e.g., SQL returning boolean)
+- **MigrationCheck** (\`preChecks\`/\`postChecks\`)
+  - \`description\`: human context
+  - \`expression\`: expression or SQL snippet to evaluate before/after the step
+- **Dependencies**
+  - Array of migration keys (\`"boundedContext.namespace.timestamp_slug"\`) used to ensure the registry executes prerequisites first
+
+## Registry Usage
+
+\`\`\`ts
+import { MigrationRegistry } from '@lssm/lib.contracts-spec/migrations';
+import { AddUsersMigration } from './migrations/core.db.2025_01_add_users';
+
+const registry = new MigrationRegistry();
+registry.register(AddUsersMigration);
+
+const migration = registry.get('core.db.2025_01_add_users');
+const all = registry.list(); // sorted by name/version
+\`\`\`
+
+## Authoring Guidelines
+
+1. Name migrations with timestamped slugs (\`domain.db.YYYY_MM_description\`) for clarity.
+2. Capture ownership metadata (\`owners\`, \`tags\`, \`stability\`) so tooling can route approvals.
+3. Prefer small, reversible steps. Use \`plan.down\` when safe; otherwise document fallback.
+4. Use \`preChecks\`/\`postChecks\` for critical invariants (row counts, schema existence).
+5. Specify dependencies explicitly to avoid parallel execution hazards.
+6. For large data scripts, use \`script\` as a pointer (URL, file path) rather than embedding code directly.
+
+## Tooling Roadmap
+
+Upcoming CLI support (Phase 4 plan):
+
+- \`contractspec create --type migration\` (scaffolds spec skeleton)
+- \`contractspec build <migration>\` (generate executor harness)
+- \`contractspec migrate create/up/down/status\` orchestration commands
+
+The current implementation focuses on the spec/registry foundation so downstream tooling can be layered iteratively.
+
+`}},{id:"docs.tech.contracts.openapi-export",exportName:"tech_contracts_openapi_export_DocBlocks",sourceModule:"openapi",block:{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: \`@lssm/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.`}},{id:"docs.tech.contracts.ops-to-presentation-linking",exportName:"tech_contracts_ops_to_presentation_linking_DocBlocks",sourceModule:"features/types",block:{id:"docs.tech.contracts.ops-to-presentation-linking",title:"Ops ↔ Presentation linking (V2)",summary:"This document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/ops-to-presentation-linking",tags:["tech","contracts","ops-to-presentation-linking"],body:`### Ops to Presentation Linking (V2)
+
+This document explains how operations (\`OperationSpec\`) are linked to presentations (\`PresentationSpec\`) via feature modules.
+
+- Location: \`packages/libs/contracts-spec/src/features/types.ts\`
+- Field: \`FeatureModuleSpec.opToPresentation?: { op: OpRef; pres: PresentationRef }[]\`
+- Validation:
+  - \`validateFeatureSpec()\` checks that linked refs are declared in the feature itself
+  - \`installFeature()\` checks that declared refs exist in the provided registries
+  - \`validateFeatureTargetsV2()\` checks descriptor target support
+
+Example:
+
+\`\`\`ts
+import { defineFeature, FeatureRegistry } from '@lssm/lib.contracts-spec/features';
+
+export const WidgetsFeature = defineFeature({
+  meta: {
+    key: 'myapp.widgets.linkage',
+    version: '1.0.0',
+    title: 'Widgets (linked)',
+    description: 'Links create and update operations to UI presentations.',
+    domain: 'widgets',
+    owners: ['platform.widgets'],
+    tags: ['widgets', 'linkage'],
+    stability: 'beta',
+  },
+  operations: [
+    { key: 'widgets.create', version: '1.0.0' },
+    { key: 'widgets.update', version: '1.0.0' },
+  ],
+  presentations: [
+    { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+  ],
+  opToPresentation: [
+    {
+      op: { key: 'widgets.create', version: '1.0.0' },
+      pres: { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+    },
+    {
+      op: { key: 'widgets.update', version: '1.0.0' },
+      pres: { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+    },
+  ],
+  presentationsTargets: [
+    {
+      key: 'myapp.widgets.editor.page',
+      version: '1.0.0',
+      targets: ['react', 'markdown'],
+    },
+  ],
+});
+
+const features = new FeatureRegistry().register(WidgetsFeature);
+\`\`\`
+
+Notes:
+
+- This enables traceability: the UI flow that realizes an operation is discoverable via the feature catalog.
+- Presentations can target multiple outputs (\`react\`, \`markdown\`, \`application/json\`, \`application/xml\`).
+- Use \`renderFeaturePresentation()\` to render a descriptor to a given target with a component map.
+`}},{id:"docs.tech.contracts.policy",exportName:"tech_contracts_policy_DocBlocks",sourceModule:"policy/spec",block:{id:"docs.tech.contracts.policy",title:"PolicySpec & PolicyEngine",summary:"`PolicySpec` gives a declarative, typed home for access-control logic covering:",kind:"reference",visibility:"public",route:"/docs/tech/contracts/policy",tags:["tech","contracts","policy"],body:`# PolicySpec & PolicyEngine
+
+## Purpose
+
+\`PolicySpec\` gives a declarative, typed home for access-control logic covering:
+- **Who** can perform an action (ABAC/ReBAC style rules)
+- **What** they can access (resources + optional field-level overrides)
+- **When** special conditions apply (contextual expressions)
+- **How** PII should be handled (consent/retention hints)
+
+\`PolicyEngine\` evaluates one or more policies and returns an \`allow\`/\`deny\` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (\`OperationSpecRegistry\` → \`ctx.decide\`).
+
+## Location
+
+- Types & registry: \`packages/libs/contracts/src/policy/spec.ts\`
+- Runtime evaluation: \`packages/libs/contracts/src/policy/engine.ts\`
+- Tests: \`packages/.../policy/engine.test.ts\`
+
+## \`PolicySpec\`
+
+\`\`\`ts
+export interface PolicySpec {
+  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }
+  rules: PolicyRule[];       // allow/deny rules for actions
+  fieldPolicies?: FieldPolicyRule[];
+  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };
+  relationships?: RelationshipDefinition[];
+  consents?: ConsentDefinition[];
+  rateLimits?: RateLimitDefinition[];
+  opa?: { package: string; decision?: string };
+}
+\`\`\`
+
+- \`PolicyRule\`
+  - \`effect\`: \`'allow' | 'deny'\`
+  - \`actions\`: e.g., \`['read', 'write', 'delete']\` (string namespace is flexible)
+  - \`subject\`: \`{ roles?: string[]; attributes?: { attr: matcher } }\`
+  - \`resource\`: \`{ type: string; fields?: string[]; attributes?: {...} }\`
+  - \`relationships\`: \`{ relation, objectId?, objectType? }[]\` → ReBAC checks (use \`objectId: '$resource'\` to target the current resource)
+  - \`requiresConsent\`: \`['consent_id']\` → references spec-level consent definitions
+  - \`flags\`: feature flags that must be enabled (\`DecisionContext.flags\`)
+  - \`rateLimit\`: string reference to \`rateLimits\` entry or inline object \`{ rpm, key?, windowSeconds?, burst? }\`
+  - \`escalate\`: \`'human_review' | null\` to indicate manual approval
+  - \`conditions\`: optional expression snippets evaluated against \`{ subject, resource, context }\`
+- \`FieldPolicyRule\`
+  - \`field\`: dot-path string (e.g., \`contact.email\`)
+  - \`actions\`: subset of \`['read', 'write']\`
+  - Same \`subject\` / \`resource\` / \`conditions\` shape
+  - Useful for redacting specific fields, even when the global action is allowed
+- \`RelationshipDefinition\`
+  - Canonical tuples for relationship graph (\`subjectType\`, \`relation\`, \`objectType\`, \`transitive?\`)
+- \`ConsentDefinition\`
+  - \`{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }\`
+- \`RateLimitDefinition\`
+  - \`{ id, rpm, key?, windowSeconds?, burst? }\`
+- \`PolicyRef\`
+  - \`{ name: string; version: string }\` → attach to contract specs / workflows
+
+## Registry
+
+\`\`\`ts
+const registry = new PolicyRegistry();
+registry.register(CorePolicySpec);
+const spec = registry.get('core.default', 1);
+\`\`\`
+
+Guarantees uniqueness per \`(name, version)\` and exposes helpers to resolve highest versions.
+
+## Engine
+
+\`\`\`ts
+const engine = new PolicyEngine(policyRegistry);
+
+const decision = engine.decide({
+  action: 'read',
+  subject: { roles: ['admin'] },
+  resource: { type: 'resident', fields: ['contact.email'] },
+  policies: [{ name: 'core.default', version: '1.0.0' }],
+});
+/*
+{
+  effect: 'allow',
+  reason: 'core.default',
+  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],
+  pii: { fields: ['contact.email'], consentRequired: true }
+}
+*/
+\`\`\`
+
+- First matching **deny** wins; otherwise the first **allow** is returned.
+- Field policies are aggregated across referenced policies:
+  - Later denies override earlier allows for a given field.
+  - Returned as \`fieldDecisions\` to simplify downstream masking.
+- PII metadata is surfaced when defined to help adapt logging/telemetry.
+
+### Expression Support
+
+Conditions accept small JS snippets (e.g., \`subject.attributes.orgId === context.orgId\`). The engine runs them in a constrained scope (\`subject\`, \`resource\`, \`context\`) without access to global state.
+
+### ReBAC & Relationships
+
+- Provide relationship tuples via \`PolicySpec.relationships\` for documentation/validation.
+- Reference them inside rules with \`relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]\`.
+- The execution context must populate \`subject.relationships\` (\`[{ relation, object, objectType }]\`) for the engine to evaluate ReBAC guards.
+
+### Consent & Rate Limits
+
+- Declare reusable consent definitions under \`consents\`. Rules list the IDs they require; if a user session lacks the consent (\`DecisionContext.consents\`), the engine returns \`effect: 'deny'\` with \`reason: 'consent_required'\` and enumerates missing consents.
+- Attach rate limits either inline or via \`rateLimits\` references. When a rule matches, the engine surfaces \`{ rpm, key, windowSeconds?, burst? }\` so callers can feed it to shared limiters.
+
+### OPA Adapter
+
+- \`OPAPolicyAdapter\` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (\`effect\`, \`reason\`, \`fieldDecisions\`, \`requiredConsents\`).
+- Use when migrating to OPA policies or running defense-in-depth: call \`engine.decide()\`, then pass the preliminary decision to \`adapter.evaluate(...)\`. The adapter marks merged decisions with \`evaluatedBy: 'opa'\`.
+- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.
+
+## Contract Integration
+
+\`ContractSpec.policy\` now supports:
+
+\`\`\`ts
+policy: {
+  auth: 'anonymous' | 'user' | 'admin';
+  ...
+  policies?: PolicyRef[];                // policies evaluated before execution
+  fieldPolicies?: {                      // field hints (read/write) per policy
+    field: string;
+    actions: ('read' | 'write')[];
+    policy?: PolicyRef;
+  }[];
+}
+\`\`\`
+
+Adapters can resolve refs through a shared \`PolicyEngine\` and populate \`ctx.decide\` so \`OperationSpecRegistry.execute\` benefits from centralized enforcement.
+
+## Authoring Guidelines
+
+1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).
+2. Keep rule scopes narrow (per feature/operation) and compose multiple \`PolicyRef\`s when necessary.
+3. Store PII field lists here to avoid duplication across logs/telemetry.
+4. Use explicit rule reasons for auditability and better developer feedback.
+5. Treat versioning seriously; bump \`meta.version\` whenever behavior changes.
+
+## Future Enhancements
+
+- Richer expression language (composable predicates, time-based conditions).
+- Multi-tenant relationship graph services (store/resolve relationships at scale).
+- Tooling that auto-generates docs/tests for policies referenced in specs.
+
+`}},{id:"docs.tech.contracts.presentations",exportName:"techContractsDocs",sourceModule:"presentations/presentations",block:{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?: SurfacePolicyRequirement;
+  source: PresentationSource;
+  targets: PresentationTarget[];
+}
+
+// Shared ownership schema (source of truth in @lssm/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()\` from \`@lssm/lib.presentation-runtime-core/transform-engine\` and register custom renderers as needed. React hosts add \`registerDefaultReactRenderer()\` from \`@lssm/lib.contracts-runtime-client-react/transform-engine\`. The core engine supports markdown/json/xml; the 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.`}},{id:"docs.tech.contracts.presentations-conventions",exportName:"tech_contracts_presentations_conventions_DocBlocks",sourceModule:"presentations/presentations",block:{id:"docs.tech.contracts.presentations-conventions",title:"Presentations Conventions (A11y & i18n)",summary:"- Always provide `meta.description` (≥ 3 chars) — used by a11y/docs/agents.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/presentations-conventions",tags:["tech","contracts","presentations-conventions"],body:`## Presentations Conventions (A11y & i18n)
+
+- Always provide \`meta.description\` (≥ 3 chars) — used by a11y/docs/agents.
+- Prefer source = BlockNote for rich guides; use component key for interactive flows.
+- i18n strings belong in host apps; descriptors carry keys/defaults only.
+- Target selection: include only what you intend to support to avoid drift.
+- PII: declare JSON-like paths under \`policy.pii\`; engine redacts in outputs.
+`}},{id:"docs.tech.contracts.pwa-updates",exportName:"tech_contracts_pwa_updates_DocBlocks",sourceModule:"pwa/types",block:{id:"docs.tech.contracts.pwa-updates",title:"PWA update management",summary:"Configure frontend update checks with app defaults and release overrides.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/pwa-updates",tags:["tech","contracts","pwa","updates"],body:`# PWA update management
+
+PWA manifests describe the latest frontend release and the policy a runtime should apply when a browser is running an older version.
+
+Use \`defaultUpdatePolicy\` for application-wide behavior and \`release.updatePolicy\` when a release needs a stricter or looser policy. Host applications still own service worker registration and activation; ContractSpec standardizes the API contract, decision state, and update prompt behavior.
+`}},{id:"docs.tech.contracts.README",exportName:"tech_contracts_README_DocBlocks",sourceModule:"index",block:{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- `@lssm/lib.contracts-spec` is the contract-model package: specs, registries, install helpers, shared runtime types, and contract metadata.\n- `@lssm/lib.contracts-integrations` owns integration contracts, provider interfaces, connection models, and secret-provider abstractions.\n- `@lssm/lib.presentation-runtime-core` owns the platform-agnostic presentation transform engine for markdown/json/xml outputs.\n- `@lssm/lib.contracts-runtime-client-react` exposes browser-safe React helpers, including React presentation descriptors and feature rendering helpers.\n- `@lssm/lib.contracts-runtime-server-rest` covers HTTP/MCP adapters and other Node-only server helpers.\n- `@lssm/lib.schema`, `@lssm/lib.design-system`, `@lssm/lib.ui-kit`, `@lssm/lib.ui-kit-web`, `@lssm/lib.accessibility`, and the presentation runtime packages are published to npm alongside contracts; prefer the scoped packages to keep tree-shaking intact.\n- Bundlers with conditional exports should resolve subpaths first; keep root imports for server-only code paths.\n\n### Core concepts\n\n- **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"}},{id:"docs.tech.contracts.regenerator",exportName:"tech_contracts_regenerator_DocBlocks",sourceModule:"regenerator/service",block:{id:"docs.tech.contracts.regenerator",title:"Regenerator Service",summary:"The Regenerator daemon observes telemetry, error, and behavior streams, then suggests spec-level changes (not code patches) that can be reviewed and applied through the App Studio.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/regenerator",tags:["tech","contracts","regenerator"],body:"## Regenerator Service\n\nThe Regenerator daemon observes telemetry, error, and behavior streams, then suggests spec-level changes (not code patches) that can be reviewed and applied through the App Studio.\n\n- Runtime entrypoint: `packages/libs/contracts/src/regenerator/service.ts`\n- Types/interfaces: `packages/libs/contracts/src/regenerator/types.ts`\n- Signal adapters: `packages/libs/contracts/src/regenerator/adapters.ts`\n\n### Architecture\n\n```text\nSignal Adapters ──► RegeneratorService ──► Rules ──► ProposalSink\n          ▲                                       │\n          │                                       ▼\n     Telemetry / Errors / Behavior         Spec change proposals\n```\n\n1. **Signal adapters** pull batches of telemetry, error logs, or behavior metrics for each `RegenerationContext`.\n2. `RegeneratorService` schedules polling (`resolveAppConfig` + `composeAppConfig` provide context).\n3. **Rules** implement domain heuristics and emit `SpecChangeProposal` objects.\n4. **Proposal sinks** persist or forward proposals for human review.\n\n### Key types\n\n```ts\nexport interface RegenerationContext {\n  id: string;\n  blueprint: AppBlueprintSpec;\n  tenantConfig: TenantAppConfig;\n  resolved: ResolvedAppConfig;\n}\n\nexport interface RegeneratorRule {\n  id: string;\n  description: string;\n  evaluate(\n    context: RegenerationContext,\n    signals: RegeneratorSignal[]\n  ): Promise<SpecChangeProposal[]>;\n}\n\nexport interface SpecChangeProposal {\n  id: string;\n  title: string;\n  summary: string;\n  confidence: 'low' | 'medium' | 'high';\n  target: ProposalTarget;\n  actions: ProposalAction[];\n  blockers?: ProposalBlocker[];\n  signalIds: string[];\n  createdAt: Date;\n}\n```\n\n- Signals are normalized envelopes: telemetry (`count`, anomaly score), errors, and behavior trends.\n- Proposals reference blueprint or tenant specs via `ProposalTarget`.\n- Actions encode what the automation should perform (update blueprint, run tests/migrations, trigger regeneration).\n\n### Providing signals\n\nImplement `TelemetrySignalProvider`, `ErrorSignalProvider`, or `BehaviorSignalProvider`:\n\n```ts\nconst service = new RegeneratorService({\n  contexts,\n  adapters: {\n    telemetry: new PosthogTelemetryAdapter(),\n    errors: new SentryErrorAdapter(),\n  },\n  rules: [new WorkflowFailureRule(), new DataViewUsageRule()],\n  sink: new ProposalQueueSink(),\n  pollIntervalMs: 60_000,\n});\n```\n\nAdapters receive the full `RegenerationContext`, making it easy to scope queries per tenant/app.\n\n### Authoring rules\n\nRules focus on signals → proposals:\n\n```ts\nclass WorkflowFailureRule implements RegeneratorRule {\n  id = 'workflow-failure';\n  description = 'Suggest splitting workflows that exceed failure thresholds';\n\n  async evaluate(context, signals) {\n    const failures = signals.filter(\n      (signal) =>\n        signal.type === 'telemetry' &&\n        signal.signal.eventName === 'workflow.failure' &&\n        signal.signal.count >= 10\n    );\n\n    if (failures.length === 0) return [];\n\n    return [\n      {\n        id: `${this.id}-${context.id}`,\n        title: 'Split onboarding workflow',\n        summary: 'Step 3 fails consistently; propose dedicated remediation branch.',\n        confidence: 'medium',\n        rationale: ['Failure count ≥ 10 within last window'],\n        target: {\n          specType: 'workflow',\n          reference: { name: 'onboarding.workflow', version: '1.0.0' },\n          tenantScoped: true,\n        },\n        actions: [\n          { kind: 'update_tenant_config', summary: 'Add alternate fallback path' },\n          { kind: 'run_tests', tests: ['workflows/onboarding.spec.ts'] },\n        ],\n        signalIds: failures.map((f) => f.signal.eventName),\n        createdAt: new Date(),\n      },\n    ];\n  }\n}\n```\n\n### Reviewing proposals\n\nProposals flow to a `ProposalSink` (queue, DB, messaging bus). The Studio will surface:\n\n1. Signal evidence (telemetry counts, error metadata)\n2. Proposed spec diffs and required actions (tests/migrations)\n3. Approval workflow (approve → write spec diff → run automation)\n\n### CLI driver\n\nRun the regenerator daemon from the CLI:\n\n```bash\nbunx contracts regenerator ./app.blueprint.ts ./tenant.config.ts ./regenerator.rules.ts auto \\\n  --executor ./regenerator.executor.ts \\\n  --poll-interval 60000 \\\n  --batch-duration 300000 \\\n  --dry-run\n```\n\n- Expects modules exporting default `AppBlueprintSpec`, `TenantAppConfig`, and one or more `RegenerationRule`s.\n- Pass a sink module path, or use the special `auto` value with `--executor <module>` to instantiate an `ExecutorProposalSink`.\n- Executor modules can export a `ProposalExecutor` instance, a factory, or a plain dependency object for the executor constructor. Optional exports: `sinkOptions`, `logger`, `onResult`, `dryRun`.\n- Optionally provide `--contexts ./contexts.ts` to load custom context arrays (advanced multi-tenant scenarios).\n- Use `--dry-run` to preview actions without mutating specs/configs, and `--once` for CI smoke tests.\n\n### Proposal executor\n\n`ProposalExecutor` + `ExecutorProposalSink` orchestrate follow-up actions once a proposal is approved:\n\n- Interfaces for applying blueprint or tenant-config updates (`BlueprintUpdater`, `TenantConfigUpdater`).\n- Hooks for running contract tests and migrations (`TestExecutor`, `MigrationExecutor`).\n- Optional trigger to recompose the runtime (`RegenerationTrigger`).\n- Built-in `dryRun` mode to preview outcomes.\n- Pluggable result logging/forwarding via `ExecutorSinkOptions`.\n\n```ts\nimport {\n  ProposalExecutor,\n  ExecutorProposalSink,\n} from '@lssm/lib.contracts-spec/regenerator';\n\nconst executor = new ProposalExecutor({\n  tenantConfigUpdater,\n  testExecutor,\n  migrationExecutor,\n  regenerationTrigger,\n});\n\nconst sink = new ExecutorProposalSink(executor, {\n  dryRun: false,\n  onResult: ({ result }) => console.log(result.status),\n});\n```\n\nExecution results include per-action status (`success`, `skipped`, `failed`) plus aggregated proposal status (`success`, `partial`, `failed`). Missing dependencies mark actions as `skipped`, making it easy to plug into partial automation flows today and extend later.\n\n### Next steps\n\n- Build adapters for existing telemetry/error providers.\n- Encode canonical rules (workflow failure, feature under-use, high latency).\n- Integrate with App Studio proposal inbox and automate acceptance (write spec diff, run tests, queue migrations).\n\n"}},{id:"docs.tech.contracts.shared-entities.person",exportName:"shared_entities_person_DocBlocks",sourceModule:"shared-entities/person",block:{id:"docs.tech.contracts.shared-entities.person",title:"PersonEntity — Cross-Domain Person Contract Entity",summary:"`PersonEntity` is the canonical cross-domain entity for a human actor. Layer 1: `person` slug with edges to team, project, and task.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/person",tags:["tech","contracts","shared-entities","person"],body:`# PersonEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'person'\`.
+
+## Edges
+
+| ID | From | To | Relation | Cardinality |
+|----|----|----|----|----|
+| \`person-to-team\` | person | team | member-of | many-to-many |
+| \`person-to-project\` | person | project | contributes-to | many-to-many |
+| \`person-to-task\` | person | task | assigned-to | one-to-many |
+`}},{id:"docs.tech.contracts.shared-entities.project",exportName:"shared_entities_project_DocBlocks",sourceModule:"shared-entities/project",block:{id:"docs.tech.contracts.shared-entities.project",title:"ProjectEntity — Cross-Domain Project Contract Entity",summary:"`ProjectEntity` is the canonical cross-domain entity for a bounded initiative. Layer 1: `project` slug with edges to team, person, task, resource.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/project",tags:["tech","contracts","shared-entities","project"],body:`# ProjectEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'project'\`.
+`}},{id:"docs.tech.contracts.shared-entities.resource",exportName:"shared_entities_resource_DocBlocks",sourceModule:"shared-entities/resource",block:{id:"docs.tech.contracts.shared-entities.resource",title:"ResourceEntity — Cross-Domain Resource Contract Entity",summary:"`ResourceEntity` is the canonical cross-domain entity for a managed asset. Layer 1: `resource` slug with edges to team and project.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/resource",tags:["tech","contracts","shared-entities","resource"],body:`# ResourceEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'resource'\`.
+`}},{id:"docs.tech.contracts.shared-entities.task",exportName:"shared_entities_task_DocBlocks",sourceModule:"shared-entities/task",block:{id:"docs.tech.contracts.shared-entities.task",title:"SharedTask + TaskEntity — Cross-Context Task (A9 Invariant)",summary:"`SharedTask` carries both `dependsOn?` (workflow DAG) and `parent?` (agent tree) as optional. Validators enforce mutual exclusion per A9. `TaskEntity` is the Layer-1 contract registration.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/task",tags:["tech","contracts","shared-entities","task","a9","workflow","agent"],body:"# SharedTask + TaskEntity\n\n## A9 Invariant\n\n| Field | Context | Validator rejects |\n|-------|---------|------------------|\n| `dependsOn?` | Workflow DAG | Agent validator |\n| `parent?` | Agent tree | Workflow validator |\n\nBoth `undefined` → root task (valid in either context).\n\n## V2 Execution Fields (Path B parity)\n\n- `type`: `automation` (default) | `human` | `decision`\n- `operation?: OpRef` — dispatched by the V2 runner's OperationExecutor\n- `guard?` — expression or policy guard evaluated before execution; task skipped on false\n- `retry?` — fixed/exponential backoff with configurable attempts, delay, and cap\n- `timeoutMs?` — per-task timeout; raises `WorkflowExecutionError('timeout')`\n- `requiredIntegrations?` — slot IDs checked during pre-flight\n- `requiredCapabilities?` — CapabilityRefs checked during pre-flight\n"}},{id:"docs.tech.contracts.shared-entities.task-validators",exportName:"shared_entities_task_validators_DocBlocks",sourceModule:"shared-entities/task-validators",block:{id:"docs.tech.contracts.shared-entities.task-validators",title:"Task Validators — Dual Workflow/Agent Runtime Validators (A9)",summary:"`validateWorkflowTask` rejects tasks with `parent`; `validateAgentTask` rejects tasks with `dependsOn`. Both enforce the A9 invariant at runtime.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/task-validators",tags:["tech","contracts","shared-entities","task","validators","a9"],body:"# Task Validators (A9)\n\n| Function | Context | Rejects |\n|----------|---------|--------|\n| `validateWorkflowTask` | Workflow DAG | `parent` set |\n| `validateWorkflowTasks` | Workflow DAG (batch) | first task with `parent` |\n| `validateAgentTask` | Agent tree | `dependsOn` set |\n| `validateAgentTasks` | Agent tree (batch) | first task with `dependsOn` |\n"}},{id:"docs.tech.contracts.shared-entities.team",exportName:"shared_entities_team_DocBlocks",sourceModule:"shared-entities/team",block:{id:"docs.tech.contracts.shared-entities.team",title:"TeamEntity — Cross-Domain Team Contract Entity",summary:"`TeamEntity` is the canonical cross-domain entity for a group of persons. Layer 1: `team` slug with edges to person, project, resource.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/team",tags:["tech","contracts","shared-entities","team"],body:`# TeamEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'team'\`.
+
+## Edges
+
+| ID | From | To | Relation | Cardinality |
+|----|----|----|----|----|  
+| \`team-to-person\` | team | person | has-member | many-to-many |
+| \`team-to-project\` | team | project | owns | one-to-many |
+| \`team-to-resource\` | team | resource | manages | one-to-many |
+`}},{id:"docs.tech.contracts.telemetry",exportName:"tech_contracts_telemetry_DocBlocks",sourceModule:"telemetry/spec",block:{id:"docs.tech.contracts.telemetry",title:"TelemetrySpec",summary:"Telemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/telemetry",tags:["tech","contracts","telemetry"],body:"## TelemetrySpec\n\nTelemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.\n\n- **File location**: `packages/libs/contracts/src/telemetry/spec.ts`\n- **Runtime tracker**: `packages/libs/contracts/src/telemetry/tracker.ts`\n- **Anomaly monitor**: `packages/libs/contracts/src/telemetry/anomaly.ts`\n\n### Core concepts\n\n```ts\nexport interface TelemetrySpec {\n  meta: TelemetryMeta;\n  events: TelemetryEventDef[];\n  config?: TelemetryConfig;\n}\n```\n\n- `meta`: ownership + identifiers (`name`, `version`, `domain`)\n- `events`: per-event semantics, property definitions, privacy level, retention, sampling, anomaly rules\n- `config`: defaults and provider configuration\n- `TelemetryRegistry`: registers specs, resolves latest version, finds event definitions by name/version\n\n### An example\n\n```ts\nexport const SigilTelemetry: TelemetrySpec = {\n  meta: {\n    name: 'sigil.telemetry',\n    version: '1.0.0',\n    title: 'Sigil telemetry',\n    description: 'Core Sigil product telemetry',\n    domain: 'sigil',\n    owners: ['@team.analytics'],\n    tags: ['telemetry'],\n    stability: StabilityEnum.Experimental,\n  },\n  config: {\n    defaultRetentionDays: 30,\n    defaultSamplingRate: 1,\n    providers: [\n      { type: 'posthog', config: { projectApiKey: process.env.POSTHOG_KEY } },\n    ],\n  },\n  events: [\n    {\n      name: 'sigil.telemetry.workflow_step',\n      version: '1.0.0',\n      semantics: {\n        what: 'Workflow step executed',\n        who: 'Actor executing the workflow',\n      },\n      privacy: 'internal',\n      properties: {\n        workflow: { type: 'string', required: true },\n        step: { type: 'string', required: true },\n        durationMs: { type: 'number' },\n        userId: { type: 'string', pii: true, redact: true },\n      },\n      anomalyDetection: {\n        enabled: true,\n        minimumSample: 10,\n        thresholds: [\n          { metric: 'durationMs', max: 1500 },\n        ],\n        actions: ['alert', 'trigger_regen'],\n      },\n    },\n  ],\n};\n```\n\n### Tracking events at runtime\n\n`TelemetryTracker` performs sampling, PII redaction, provider dispatch, and anomaly detection.\n\n```ts\nconst tracker = new TelemetryTracker({\n  registry: telemetryRegistry,\n  providers: [\n    {\n      id: 'posthog',\n      async send(dispatch) {\n        posthog.capture({\n          event: dispatch.name,\n          properties: dispatch.properties,\n          distinctId: dispatch.context.userId ?? dispatch.context.sessionId,\n        });\n      },\n    },\n  ],\n  anomalyMonitor: new TelemetryAnomalyMonitor({\n    onAnomaly(event) {\n      console.warn('Telemetry anomaly detected', event);\n    },\n  }),\n});\n\nawait tracker.track('sigil.telemetry.workflow_step', 1, {\n  workflow: 'onboarding',\n  step: 'verify_email',\n  durationMs: 2100,\n  userId: 'user-123',\n});\n```\n\n- Sampling obeys the event-specific rate (fallback to spec defaults)\n- Properties flagged with `pii` or `redact` are masked before dispatch\n- Anomaly monitor evaluates thresholds and triggers actions (e.g., log, alert, regeneration)\n\n### Spec integration\n\n- `ContractSpec.telemetry` allows operations to emit success/failure events automatically\n- `OperationSpecRegistry.execute()` uses the tracker when `ctx.telemetry` is provided\n- `WorkflowRunner` (Phase 4 follow-up) will emit telemetry during step transitions\n- `TelemetrySpec` events should reuse `EventSpec` names/versions to keep analytics/contract parity\n\n### CLI workflow\n\n```\ncontracts-cli create telemetry\n```\n\n- Interactive wizard prompts for meta, providers, events, properties, retention, anomaly rules\n- Output: `*.telemetry.ts` file using `TelemetrySpec`\n\n### Best practices\n\n- Prefer `internal` privacy for non-PII; mark PII properties explicitly with `pii` + `redact`\n- Keep sampling ≥0.05 except for high-volume events\n- Configure anomaly detection on key metrics (duration, error count, conversion)\n- Check telemetry into source control alongside contracts; regenerate via CLI when specs change\n\n### Next steps\n\n- Phase 5: Regenerator monitors telemetry anomalies to propose spec improvements\n- Phase 6: Studio surfaces telemetry controls per tenant via `TenantAppConfig`\n\n"}},{id:"docs.tech.contracts.tests",exportName:"tech_contracts_tests_DocBlocks",sourceModule:"tests/spec",block:{id:"docs.tech.contracts.tests",title:"TestSpec & TestRunner",summary:"Use `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/tests",tags:["tech","contracts","tests"],body:"## TestSpec & TestRunner\n\nUse `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.\n\n- Types & registry: `packages/libs/contracts/src/tests/spec.ts`\n- Runtime runner: `packages/libs/contracts/src/tests/runner.ts`\n- CLI: `contractspec test`\n\n### Structure\n\n```ts\nexport interface TestSpec {\n  meta: TestSpecMeta;\n  target: TestTarget;  // contract or workflow\n  fixtures?: Fixture[]; // optional shared setup before each scenario\n  scenarios: TestScenario[];\n  coverage?: CoverageRequirement;\n}\n```\n\n- `Fixture`: run an operation before the scenario (`operation`, optional `input`)\n- `Action`: operation input that the scenario exercises\n- `Assertion`:\n  - `expectOutput` `{ match }` deep-equals the handler output\n  - `expectError` `{ messageIncludes? }` ensures an error was thrown\n  - `expectEvents` `{ events: [{ name, version, min?, max? }] }` checks emitted events\n\n### Example\n\n```ts\nimport { defineCommand, type TestSpec } from '@lssm/lib.contracts-spec';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { key: 'math.add', version: '1.0.0', /* … */ },\n  io: {\n    input: AddNumbersInput,\n    output: AddNumbersOutput,\n  },\n  policy: { auth: 'user' },\n});\n\nexport const MathAddTests: TestSpec = {\n  meta: {\n    name: 'math.add.tests',\n    version: '1.0.0',\n    title: 'Math add scenarios',\n    owners: ['@team.math'],\n    tags: ['math'],\n    stability: StabilityEnum.Experimental,\n  },\n  target: { type: 'contract', operation: { name: 'math.add' } },\n  scenarios: [\n    {\n      name: 'adds positive numbers',\n      when: {\n        operation: { name: 'math.add' },\n        input: { a: 2, b: 3 },\n      },\n      then: [\n        { type: 'expectOutput', match: { sum: 5 } },\n        {\n          type: 'expectEvents',\n          events: [{ name: 'math.sum_calculated', version: '1.0.0', min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `OperationSpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new OperationSpecRegistry();\n  registry.register(AddNumbersSpec);\n  registry.bind(AddNumbersSpec, addNumbersHandler);\n  return registry;\n}\n```\n\n2. Run the CLI:\n\n```\ncontractspec test apps/math/tests/math.add.tests.ts \\\n  --registry apps/math/tests/registry.ts\n```\n\n- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via `TestRunner`.\n- `--json` outputs machine-readable results.\n\n### Programmatic usage\n\n```ts\nconst runner = new TestRunner({\n  registry,\n  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),\n});\n\nconst result = await runner.run(MathAddTests);\nconsole.log(result.passed, result.failed);\n```\n\n- `createContext` can supply default `HandlerCtx` values.\n- `beforeEach` / `afterEach` hooks let you seed databases or reset state.\n\n### Best practices\n\n- Keep fixtures idempotent so scenarios can run in parallel in the future.\n- Use `expectEvents` to guard analytics/telemetry expectations.\n- Add specs to `TestRegistry` for discovery and documentation.\n- `coverage` captures desired coverage metrics (enforced by future tooling).\n- Pair TestSpec files with CI using `contractspec test --json` and fail builds when `failed > 0`.\n\n### Mocking with Bun's `vi`\n\n- Pass a single function type to `vi.fn<TFunction>()` so calls retain typed arguments:\n\n```ts\nconst handler = vi.fn<typeof fetch>();\nconst fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;\nObject.defineProperty(fetchImpl, 'preconnect', {\n  value: vi.fn<typeof fetch.preconnect>(),\n});\n```\n\n- When you need to inspect calls, use the typed mock (`handler.mock.calls`) rather than casting to `any`.\n- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict `tsconfig` settings.\n\n"}},{id:"docs.tech.contracts.themes",exportName:"tech_contracts_themes_DocBlocks",sourceModule:"themes",block:{id:"docs.tech.contracts.themes",title:"ThemeSpec Overview",summary:"`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts-spec`, making them accessible to generators, docs, and runtime tooling.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/themes",tags:["tech","contracts","themes"],body:'# ThemeSpec Overview\n\n## Purpose\n\n`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files.\n\n## Location\n\n- Types, helper, registry, and validation: `packages/libs/contracts-spec/src/themes.ts` and `packages/libs/contracts-spec/src/themes.validation.ts`\n- Design tokens bridge: `packages/libs/design-system/src/theme/*`\n\n## Schema\n\n```ts\nexport interface ThemeSpec {\n  meta: ThemeMeta;            // ownership metadata + { key, version, extends?, scopes? }\n  tokens: ThemeTokens;\n  components?: ComponentVariantSpec[];\n  overrides?: ThemeOverride[];\n  modes?: Record<string, ThemeModeSpec>; // use keys like "light" and "dark"\n}\n```\n\n- **ThemeMeta**\n  - `key`: fully-qualified identifier (for example `design.pastel`)\n  - `version`: semver string such as `1.0.0`\n  - `extends?`: optional `ThemeRef` to a base theme\n  - `scopes?`: default scopes where the theme applies (`global`, `tenant`, `user`)\n- **ThemeTokens**\n  - `colors`, `radii`, `space`, `typography`, `shadows`, `motion`\n  - each entry is a map of `{ value, description? }`\n  - the ContractSpec editorial radius taxonomy is additive and public: scale keys `xs/sm/md/lg/xl/full/default` plus semantic aliases `control/card/panel/overlay/pill`. Smaller radii communicate precision or higher action gravity; `md/control` is the normal control default; `lg/card`, `default/panel`, and `xl/overlay` provide progressively softer editorial surfaces; `full/pill` is reserved for capsules, avatars, and dots.\n  - persona-aware or RoleMorph-selected radius profiles are a future documentation hook only. This theme does not switch radius at runtime by persona, role, tone, or density.\n- **ComponentVariantSpec**\n  - `component`: design-system component key (for example `Button`, `NavMain`)\n  - `variants`: map of variant names to `{ props?, tokens? }`\n- **ThemeOverride**\n  - `scope`: `\'global\' | \'tenant\' | \'user\'`\n  - `target`: scoped identifier such as `tenant:artisanos` or `user:123`\n  - `tokens?` / `components?`: partial overrides for that target\n\n## Authoring\n\n```ts\nimport { defineTheme } from \'@lssm/lib.contracts-spec/themes\';\n\nexport const PastelTheme = defineTheme({\n  meta: {\n    key: \'design.pastel\',\n    version: \'1.0.0\',\n    title: \'Pastel\',\n    description: \'Soft pastel palette for marketing surfaces.\',\n    domain: \'design-system\',\n    owners: [\'platform.design\'],\n    tags: [\'theme\', \'marketing\'],\n    stability: \'experimental\',\n    scopes: [\'tenant\'],\n  },\n  tokens: {\n    colors: {\n      background: { value: \'#fdf2f8\', format: \'hex\', usage: \'semantic\' },\n      primary: {\n        value: \'oklch(0.72 0.11 221.19)\',\n        format: \'oklch\',\n        usage: \'semantic\',\n      },\n    },\n  },\n  modes: {\n    dark: {\n      tokens: {\n        colors: {\n          background: {\n            value: \'oklch(0.24 0.03 255)\',\n            format: \'oklch\',\n            usage: \'semantic\',\n          },\n          primary: {\n            value: \'oklch(0.64 0.15 246)\',\n            format: \'oklch\',\n            usage: \'semantic\',\n          },\n        },\n      },\n    },\n  },\n});\n```\n\n`tokens` stays the default/light-compatible token bag. Use `modes.dark.tokens` to overlay dark-mode values and preserve full CSS color strings such as OKLCH.\n\nUse `validateThemeSpec()` or `assertThemeSpecValid()` in CI and setup flows to catch duplicate overrides, empty targets, self-referential inheritance, invalid mode keys, and missing ownership metadata before publish time.\n\n## Registry Usage\n\n```ts\nimport { ThemeRegistry } from \'@lssm/lib.contracts-spec/themes\';\n\nconst themes = new ThemeRegistry();\nthemes.register(PastelTheme);\n\nconst theme = themes.get(\'design.pastel\', \'1.0.0\');\nconst tenantVariant = theme?.overrides?.find(\n  (override) => override.target === \'tenant:artisanos\'\n);\n```\n\nThe registry guarantees `key + version` uniqueness and exposes `list()` for discovery tooling.\n\n## Rendering\n\nThe design system consumes specs through adapters you provide:\n\n1. Resolve the base theme plus applicable overrides.\n2. Merge default tokens plus the selected light/dark mode token map using `ThemeTokens`.\n3. Feed the result into `mapTokensForPlatform` or the Tailwind bridge in `@lssm/lib.design-system`.\n\n```ts\nfunction resolveTokens(\n  registry: ThemeRegistry,\n  ref: ThemeRef,\n  ctx: { tenant?: string; user?: string }\n) {\n  const spec = registry.get(ref.key, ref.version);\n  if (!spec) throw new Error(\'Theme not found\');\n\n  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));\n  return mapTokensForPlatform(tokens);\n}\n```\n\n## CLI\n\n```\ncontractspec create theme\n```\n\nUse the theme wizard to scaffold a `.theme.ts` file that already imports and calls `defineTheme(...)`.\n'}},{id:"docs.tech.contracts.visual-scenarios",exportName:"VisualScenarioSpecDocBlock",sourceModule:"visual-scenarios/spec",block:{id:"docs.tech.contracts.visual-scenarios",title:"Visual scenario contracts",summary:"Provider-neutral, deterministic UI cases linked to React presentations.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/visual-scenarios",tags:["contracts","presentations","visual-testing"],body:"# Visual scenario contracts\n\nVisual scenarios describe named, deterministic UI cases independently of Storybook or any visual-diff provider. Each scenario references a React presentation and a stable product surface. Args, globals, and parameters remain JSON-compatible and may contain nested `{ $binding: string }` references resolved by a host-owned binding registry. Non-serializable components, decorators, setup hooks, and interactions are referenced by package-owned binding names.\n\nEvery scenario classifies captured data as `synthetic` or `sanitized`. A snapshot policy with `publish: true` is valid only when `capture.external` is explicitly `true`; omission always fails closed. Modes and render bindings are references and must resolve when their registries are supplied to validation.\n"}},{id:"docs.tech.contracts.visualizations.graph",exportName:"tech_contracts_visualizations_graph_DocBlocks",sourceModule:"visualizations/types",block:{id:"docs.tech.contracts.visualizations.graph",title:"Graph & Timeline Visualization Configs",summary:"`GraphVisualizationConfig` and `TimelineVisualizationConfig` extend `VisualizationKind` with `graph` and `timeline` variants for aggregated graph analytics (node-count by dimension, edge-weight measure) and time-axis projections (time dimension + measure series).",kind:"reference",visibility:"public",route:"/docs/tech/contracts/visualizations/graph",tags:["tech","contracts","visualizations","graph","timeline"],body:"# Graph & Timeline Visualization Configs\n\n## GraphVisualizationConfig (`kind: 'graph'`)\n\nAggregated graph analytics view. Use when you want to visualize node\npopulations grouped by a dimension, or edge weights as a measure — not\ninteractive graph topology (use `DataViewGraphSpec` for that).\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `nodeDimension` | `string?` | Dimension key to group/color nodes (e.g. type, status). |\n| `edgeWeightMeasure` | `string?` | Measure key representing edge weight or count. |\n| `layout` | `'force' | 'dag' | 'radial' | 'grid'?` | Default layout algorithm. |\n\n## TimelineVisualizationConfig (`kind: 'timeline'`)\n\nProjects records along a time axis. Use for event/activity charts where the\ngoal is aggregate density or value over time — not interactive graph topology.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `timeDimension` | `string` | **Required.** Dimension key holding the time value. |\n| `laneDimension` | `string?` | Dimension key for grouping swim-lanes. |\n| `measureSeries` | `string[]?` | Measure keys to render as overlaid chart series. |\n| `endDimension` | `string?` | End-time dimension for span/interval events. |\n\n## Choosing Between VisualizationSpec and DataViewGraphSpec\n\n- Use `VisualizationSpec` with `kind: 'graph' | 'timeline'` for **aggregated\n  analytics** (e.g., charts, dashboards).\n- Use `DataViewGraphSpec` with `view.kind: 'graph' | 'timeline-graph'` for\n  **interactive graph topology** (clickable nodes, editable edges, layout\n  algorithms, node inspector panels).\n"}},{id:"docs.tech.contracts.workspace-config",exportName:"tech_workspace_config_DocBlocks",sourceModule:"workspace-config/index",block:{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)\n\nContractSpec uses a hierarchical configuration system anchored by `.contractsrc.json` files. Configuration loader supports standard rc-file discovery (cosmiconfig).\n\n### Schema Formats\n\nThe `schemaFormat` option controls the output format of schema generation commands (like `contractspec openapi import`).\n\nSupported formats:\n- `contractspec` (default): Generates standard `defineSchemaModel` code.\n- `zod`: Generates raw Zod schemas using `z.object({...})`.\n- `json-schema`: Generates JSON Schema definitions.\n- `graphql`: Generates GraphQL SDL type definitions.\n\n### Config Interface\n\n```ts\nexport interface ContractsrcConfig {\n  // ... existing fields ...\n  schemaFormat?: 'contractspec' | 'zod' | 'json-schema' | 'graphql';\n}\n```\n\nDefined in `@lssm/lib.contracts-spec/workspace-config`.\n\n### CI Package Declaration Coverage\n\nThe `ci.packageDeclarations` section lets workspaces stage package-level contract declaration enforcement across the monorepo.\n\n```ts\nexport interface ContractsrcConfig {\n  ci?: {\n    packageDeclarations?: {\n      severity?: 'off' | 'warning' | 'error';\n      requiredByKind?: {\n        libs?: 'feature';\n        modules?: 'feature';\n        integrations?: 'integration';\n        bundles?: 'module-bundle';\n        apps?: 'app-config';\n        appsRegistry?: 'app-config';\n        examples?: 'example';\n      };\n      allowMissing?: string[];\n    };\n  };\n}\n```\n\n### Connect\n\nThe `connect` section configures ContractSpec Connect as a codebase-aligned adapter layer inside the existing CLI and runtime stack.\n\n```ts\nexport interface ContractsrcConfig {\n  connect?: {\n    enabled?: boolean;\n    adapters?: {\n      cursor?: { enabled?: boolean; mode?: 'plugin' | 'rule' | 'wrapper' };\n      codex?: { enabled?: boolean; mode?: 'plugin' | 'rule' | 'wrapper' };\n      'claude-code'?: { enabled?: boolean; mode?: 'plugin' | 'rule' | 'wrapper' };\n    };\n    storage?: {\n      root?: string;\n      contextPack?: string;\n      planPacket?: string;\n      patchVerdict?: string;\n      auditFile?: string;\n      reviewPacketsDir?: string;\n    };\n    policy?: {\n      protectedPaths?: string[];\n      immutablePaths?: string[];\n      generatedPaths?: string[];\n      smokeChecks?: string[];\n      reviewThresholds?: {\n        protectedPathWrite?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        unknownImpact?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        contractDrift?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        breakingChange?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        destructiveCommand?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n      };\n    };\n    commands?: {\n      allow?: string[];\n      review?: string[];\n      deny?: string[];\n    };\n    canonPacks?: Array<{ ref: string; readOnly?: boolean }>;\n    studio?: { enabled?: boolean; mode?: 'off' | 'review-bridge'; endpoint?: string; queue?: string };\n    adoption?: {\n      enabled?: boolean;\n      catalog?: {\n        indexPath?: string;\n        overrideManifestPath?: string;\n      };\n      workspaceScan?: {\n        include?: string[];\n        exclude?: string[];\n      };\n      families?: {\n        ui?: boolean;\n        contracts?: boolean;\n        integrations?: boolean;\n        runtime?: boolean;\n        sharedLibs?: boolean;\n        solutions?: boolean;\n      };\n      thresholds?: {\n        workspaceReuse?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        contractspecReuse?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        ambiguous?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        newExternalDependency?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n        newImplementation?: 'permit' | 'rewrite' | 'require_review' | 'deny';\n      };\n    };\n  };\n}\n```\n\n### Builder\n\nThe `builder` section configures preset-driven Builder onboarding without requiring live bootstrap during setup.\n\n```ts\nexport interface ContractsrcConfig {\n  builder?: {\n    enabled?: boolean;\n    runtimeMode?: 'managed' | 'local' | 'hybrid';\n    bootstrapPreset?: 'managed_mvp' | 'local_daemon_mvp' | 'hybrid_mvp';\n    api?: {\n      baseUrl?: string;\n      controlPlaneTokenEnvVar?: string;\n    };\n    localRuntime?: {\n      runtimeId?: string;\n      grantedTo?: string;\n      providerIds?: string[];\n    };\n  };\n}\n```\n\n### LSSM OS\n\nThe optional `lssmOs` V1 section carries provider-neutral goals, contract\nreferences, workload envelopes, provider restrictions, exact minor-unit budgets,\nautonomy, infrastructure ownership, credential references, and evidence profiles.\nProvider-specific extensions are typed JSON escape hatches and reject raw secret\nfields recursively.\n\nScoped policy layers resolve deterministically in this order: platform,\norganization, workspace, environment, deployable, feature, operation, tenant.\nChildren may only tighten inherited constraints. A relaxation requires an\napproved, exact-path, exact-scope, unexpired waiver; inherited immutable rules\ncannot be waived.\n\nUse `resolveLssmOsConfigV1(config, now)` to produce a deterministic policy\nprojection and the exact scopes and waiver identifiers used by the resolution.\n"}},{id:"docs.tech.creative-intelligence.events",exportName:"CreativeIntelligenceEventsDocBlock",sourceModule:"creative-intelligence/events",block:{id:"docs.tech.creative-intelligence.events",title:"Creative intelligence events",summary:"Lifecycle events for signals, trends, hypotheses, outcomes, and benchmarks.",kind:"reference",visibility:"public",route:"/docs/tech/creative-intelligence/events",tags:["creative-intelligence","trends","evidence","benchmarks","events"],body:`# Creative intelligence events
+
+Events retain evidence and causal boundaries without granting campaign authority.`}},{id:"docs.tech.creative-intelligence.operations",exportName:"CreativeIntelligenceOperationsDocBlock",sourceModule:"creative-intelligence/operations",block:{id:"docs.tech.creative-intelligence.operations",title:"Creative intelligence operations",summary:"Evidence-backed trend, hypothesis, outcome, and benchmark operations.",kind:"reference",visibility:"public",route:"/docs/tech/creative-intelligence/operations",tags:["creative-intelligence","trends","evidence","benchmarks"],body:`# Creative intelligence operations
+
+Public-source and owned-performance evidence may produce bounded hypotheses.
+Missing metrics remain missing, causal claims stay explicit, and generated
+suggestions never activate campaigns or select creators.
+`}},{id:"docs.tech.creator-operations",exportName:"CreatorOperationsDocBlock",sourceModule:"creator-operations/operations",block:{id:"docs.tech.creator-operations",title:"Canonical creator operations",summary:"Reusable creator campaigns, immutable agreements, submission review and exact wallet settlement.",visibility:"public",kind:"reference",route:"/docs/tech/creator-operations",tags:["creators","marketing","payments"],body:`# Canonical creator operations
+
+The creator-operations subpath owns provider-neutral creator business contracts.
+lib.creator-operations-runtime implements campaign transitions, immutable acceptance,
+submission review, incremental cumulative accrual, wallet reservations and settlement.
+integration.creator-persistence provides transactional SQL state and immutable history.
+module.creator-operations binds eleven operations into the shared REST/MCP registry.
+
+Money has explicit currency/scale. Accepted terms and ledger credits are immutable.
+Repeated view observations pay only the newly earned difference. Exact tiered CPM
+arithmetic is compared against Hirly's source, while application migration remains
+unqualified. Unknown transfers keep reservations until definitive reconciliation.
+
+provider-payments/creator-settlement adapts existing Stripe/PayPal marketplace
+capabilities and verified manual evidence. Minor-unit conversion rejects fractional
+or out-of-range values. Qualified host bindings authorize exact recipients, amount,
+tenant/workspace and account; package presence does not grant payment authority.
+
+The September 2026 ownership amendment permits reusable business engines without
+sharing application databases. Existing Hirly operations remain unchanged until an
+explicit adapter migration. Manager, training and other creator features remain in
+the full parity program rather than being certified by these financial tests.
+`}},{id:"docs.tech.database.context",exportName:"DatabaseContextDocBlock",sourceModule:"database/capabilities/databaseContext.capability",block:{id:"docs.tech.database.context",title:"Database context",summary:"Schema, migrations, dictionary, read-only query, and governed mutation surfaces.",kind:"reference",visibility:"public",route:"/docs/tech/database/context",tags:["database","context"],body:`# Database context
+
+Database context covers portable schema descriptions, migration artifact provenance, data dictionary entries, governed read-only access, and governed mutation planning/execution envelopes.
+`}},{id:"docs.tech.database.dictionary.get",exportName:"DatabaseDictionaryGetDocBlock",sourceModule:"database/queries/databaseDictionaryGet.query",block:{id:"docs.tech.database.dictionary.get",title:"Get data dictionary entry",summary:"Retrieve a dictionary entry for a schema field.",kind:"reference",visibility:"public",route:"/docs/tech/database/dictionary/get",tags:["database","dictionary"],body:`# database.dictionary.get
+
+Returns semantic descriptions, PII tags, and portable field-to-column references for database fields.
+`}},{id:"docs.tech.database.migrations.list",exportName:"DatabaseMigrationsListDocBlock",sourceModule:"database/queries/databaseMigrationsList.query",block:{id:"docs.tech.database.migrations.list",title:"List database migrations",summary:"List migration history for a database.",kind:"reference",visibility:"public",route:"/docs/tech/database/migrations/list",tags:["database","migrations"],body:`# database.migrations.list
+
+Returns migration registry entries, statuses, target dialects, and generated artifact provenance for auditability.
+`}},{id:"docs.tech.database.mutation.execute",exportName:"DatabaseMutationExecuteDocBlock",sourceModule:"database/commands/databaseMutationExecute.command",block:{id:"docs.tech.database.mutation.execute",title:"Governed database mutation execution",summary:"Execute a pre-planned database mutation through a provider adapter with audit, idempotency, and transaction evidence.",kind:"reference",visibility:"public",route:"/docs/tech/database/mutation/execute",tags:["database","mutation","execute","governance"],body:`# database.mutation.execute
+
+Executes a previously planned portable database mutation through a provider/integration binding. SQL and Drizzle rendering remain outside contracts-spec; this command only defines the governed contract envelope.
+`}},{id:"docs.tech.database.mutation.plan",exportName:"DatabaseMutationPlanDocBlock",sourceModule:"database/commands/databaseMutationPlan.command",block:{id:"docs.tech.database.mutation.plan",title:"Governed database mutation plan",summary:"Plan a portable database mutation with domain-command authority and governance evidence.",kind:"reference",visibility:"public",route:"/docs/tech/database/mutation/plan",tags:["database","mutation","governance"],body:`# database.mutation.plan
+
+Plans portable database mutation intent without generating SQL or importing a provider runtime. Business-state writes must carry the owning domain command reference; generic mutations are reserved for bootstrap, admin, or infrastructure cases and cannot bypass domain invariants.
+`}},{id:"docs.tech.database.query.readonly",exportName:"DatabaseQueryReadonlyDocBlock",sourceModule:"database/queries/databaseQueryReadonly.query",block:{id:"docs.tech.database.query.readonly",title:"Read-only data query",summary:"Perform a governed read-only query via data views.",kind:"reference",visibility:"public",route:"/docs/tech/database/query/readonly",tags:["database","query","readonly"],body:`# database.query.readonly
+
+Executes read-only data access using governed data views over the portable database context with policy and redaction.
+`}},{id:"docs.tech.database.query.relational",exportName:"DatabaseRelationalQueryDocBlock",sourceModule:"database/queries/databaseRelationalQuery.query",block:{id:"docs.tech.database.query.relational",title:"Governed relational read",summary:"Perform a governed relational read that nests FK children per root row.",kind:"reference",visibility:"public",route:"/docs/tech/database/query/relational",tags:["database","query","relational"],body:`# database.query.relational
+
+Executes a governed relational read over the portable database context. The root
+resource selects its allowlisted columns and each declared relation is projected
+as a nested children array via a fail-closed parent→child join. Mirrors the
+provider-database \`GovernedRelationalReadDescriptor\` builder (eq-only filters,
+identifier allowlisting). Additive to \`database.query.readonly\`; it never
+mutates state and returns a \`QueryResultEnvelope\`-shaped result.
+`}},{id:"docs.tech.database.schema.describe",exportName:"DatabaseSchemaDescribeDocBlock",sourceModule:"database/queries/databaseSchemaDescribe.query",block:{id:"docs.tech.database.schema.describe",title:"Describe database schema",summary:"Describe schemas and models with PII signals.",kind:"reference",visibility:"public",route:"/docs/tech/database/schema/describe",tags:["database","schema"],body:`# database.schema.describe
+
+Returns portable database schema/entity summaries for agents and operators, with PostgreSQL target metadata when available.
+`}},{id:"docs.tech.database.schema.index",exportName:"DatabaseSchemasDataViewDocBlock",sourceModule:"database/views/databaseSchemas.dataView",block:{id:"docs.tech.database.schema.index",title:"Database schema index view",summary:"Data view for listing schemas and model counts.",kind:"reference",visibility:"public",route:"/docs/tech/database/schema/index",tags:["database","data-view"],body:`# database.schema.index
+
+List view for database schemas and their metadata.
+`}},{id:"docs.tech.database.tables",exportName:"DatabaseTablesDocBlock",sourceModule:"database/tables/databaseTables",block:{id:"docs.tech.database.tables",title:"defineDatabaseTable — physical-table contracts",summary:"Spec-first declaration of physical tables (columns, PK, FK, tenantColumn).",kind:"reference",visibility:"public",route:"/docs/tech/database/tables",tags:["database","tables","schema","tenant"],body:"# defineDatabaseTable\n\nSpec-first physical-table contracts. Each `DatabaseTableSpec` declares columns\n(type/nullable/default), primary key, foreign-key relations, and the mandatory\n`tenantColumn` anchoring row-level tenant isolation.\n\nUse `defineUnscopedDatabaseTable` when a physical table has no intrinsic\ntenant column and authority is enforced through an owning relation or an\napplication-global boundary. RLS generators must omit these tables rather than\ninventing tenant authority. Text columns may declare `enumValues` so generated\nDrizzle models preserve the closed TypeScript vocabulary.\n\n- Declared as the `DatabaseTableSpecModel` `SchemaModel`; the TS shape is its\n  Zod-inferred form.\n- `defineDatabaseTable(spec)` is fail-closed: it rejects a missing/empty\n  `tenantColumn`, a `tenantColumn` absent from `columns`, and PK/FK columns\n  that reference unknown columns.\n- `registerDatabaseTable`/`listDatabaseTables` expose the canonical registry\n  that the Drizzle generator (F2) and relational read-model (F3) compile against.\n- `listPhysicalDatabaseTables` adds explicitly registered unscoped tables for\n  consumers that need a complete typed query model.\n"}},{id:"docs.tech.docs-examples",exportName:"ExampleCatalogDocBlock",sourceModule:"docs/views/exampleCatalog.dataView",block:{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, templates, and sandbox entrypoints.
+`}},{id:"docs.tech.docs-generator",exportName:"DocsGenerateDocBlock",sourceModule:"docs/commands/docsGenerate.command",block:{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, search metadata, and reference pages from ContractSpecs and DocBlocks.
+`}},{id:"docs.tech.docs-publish",exportName:"DocsPublishDocBlock",sourceModule:"docs/commands/docsPublish.command",block:{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 and release metadata.
+`}},{id:"docs.tech.docs-reference",exportName:"ContractReferenceDocBlock",sourceModule:"docs/queries/contractReference.query",block:{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 and exposed as a docs-ready payload.
+`}},{id:"docs.tech.docs-search",exportName:"DocsIndexDocBlock",sourceModule:"docs/queries/docsIndex.query",block:{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, CLI, and MCP surfaces for filtering and retrieval.
+`}},{id:"docs.tech.docs-system",exportName:"DocsSystemDocBlock",sourceModule:"docs/docs.feature",block:{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 contracts, DocBlocks, manifests, and presentations into a consistent docs surface.
+`}},{id:"docs.tech.graph.cluster",exportName:"GraphClusterDocBlock",sourceModule:"agent/commands/graphOps.command",block:{id:"docs.tech.graph.cluster",title:"graph.cluster — NL cluster grouping",summary:"Generates cluster groupings with labels from a NL strategy query. Budget: 1 500 in / 400 out / $0.011.",kind:"reference",visibility:"public",route:"/docs/tech/graph/cluster",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.cluster
+
+Groups graph nodes into labelled clusters based on a natural-language
+clustering strategy (e.g., "group by team ownership", "cluster by data flow").
+
+## Output shape
+\`clusters: Array<{ id, label, nodeIds, color? }>\`
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=1 500 · maxOutputTokens=400 · hardCapUsd=$0.011`}},{id:"docs.tech.graph.compose",exportName:"GraphComposeDocBlock",sourceModule:"agent/commands/graphCompose.command",block:{id:"docs.tech.graph.compose",title:"graph.compose — build a graph from a NL spec",summary:"Generates a GraphConstruction[] mutation sequence from a natural-language description. Supports dry-run preview. Budget: 2 500 in / 1 200 out / $0.030.",kind:"reference",visibility:"public",route:"/docs/tech/graph/compose",tags:["automation","agent","execution","graph","ai","compose","generation","m5"],body:'# graph.compose\n\nTranslates a natural-language description into a `GraphConstruction[]` mutation\nsequence that the graph runtime can apply to create or extend a graph.\n\n## Construction types\n\n### `create_node`\n```json\n{ "type": "create_node", "nodeId": "n1", "label": "Build", "kind": "task", "metadata": {} }\n```\n\n### `create_edge`\n```json\n{ "type": "create_edge", "edgeId": "e1", "from": "n1", "to": "n2", "label": "triggers", "kind": "flow" }\n```\n\n### `set_metadata`\n```json\n{ "type": "set_metadata", "nodeId": "n1", "metadata": { "owner": "ci-team" } }\n```\n\n## Style hints\n\n- `workflow`   — linear/branching task sequence\n- `sequence`   — time-ordered event chain\n- `hierarchy`  — parent/child containment tree\n- `dependency` — directed dependency graph\n- `freeform`   — no structural bias (default)\n\n## Dry run\n\nPass `dryRun: true` to preview the construction without applying it.\n`applied` is `false` in the response; no state is mutated.\n\n## Budget (M5 P2/W2.3)\nmaxInputTokens=2 500 · maxOutputTokens=1 200 · hardCapUsd=$0.030'}},{id:"docs.tech.graph.edit",exportName:"GraphEditDocBlock",sourceModule:"agent/commands/graphEdit.command",block:{id:"docs.tech.graph.edit",title:"graph.edit — LLM-driven node/edge mutations",summary:"Single command for all structural graph mutations (add/remove/rename node, add/remove edge, edit metadata). Per-call budget: 1 500 in / 500 out / $0.025. Requires confirmation token for destructive ops.",kind:"reference",visibility:"public",route:"/docs/tech/graph/edit",tags:["automation","agent","execution","graph","ai","edit","mutation","m5"],body:`# graph.edit
+
+Executes a batch of structural graph mutations in a single LLM tool call.
+
+## Supported ops (discriminated by \`type\`)
+
+| type | Description |
+|---|---|
+| \`add_node\` | Insert node (id, label?, kind?, metadata?) |
+| \`remove_node\` | Delete node + all incident edges |
+| \`rename_node\` | Update node label |
+| \`edit_metadata\` | Patch metadata on node or edge |
+| \`add_edge\` | Insert directed edge (id, from, to, label?, kind?) |
+| \`remove_edge\` | Delete edge |
+
+Max **20 ops per call** to stay within the token budget.
+
+## Confirmation requirement
+
+Destructive ops (\`remove_node\`, \`remove_edge\`) require a \`confirmationToken\`
+issued by the AI suggestion confirmation UX (W7.4). The command returns
+\`CONFIRMATION_REQUIRED\` (403) when the token is absent or invalid.
+
+## Budget (M5 P2/W2.1)
+maxInputTokens=1 500 · maxOutputTokens=500 · hardCapUsd=$0.025`}},{id:"docs.tech.graph.filter",exportName:"GraphFilterDocBlock",sourceModule:"agent/commands/graphOps.command",block:{id:"docs.tech.graph.filter",title:"graph.filter — NL filter generation",summary:"Translates a NL query into a GraphFilterSpec for the filter rack. Budget: 1 200 in / 300 out / $0.008.",kind:"reference",visibility:"public",route:"/docs/tech/graph/filter",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.filter
+
+Translates a natural-language filter request into a \`GraphFilterSpec\`
+JSON that the filter rack can apply directly.
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=1 200 · maxOutputTokens=300 · hardCapUsd=$0.008`}},{id:"docs.tech.graph.refactor",exportName:"GraphRefactorDocBlock",sourceModule:"agent/commands/graphRefactor.command",block:{id:"docs.tech.graph.refactor",title:"graph.refactor — pattern-level graph transformations",summary:"Four structural refactoring ops: rename-by-pattern, extract-subgraph, merge-nodes, split-node. Supports dryRun preview. Budget: 2 000 in / 600 out / $0.035.",kind:"reference",visibility:"public",route:"/docs/tech/graph/refactor",tags:["automation","agent","execution","graph","ai","refactor","pattern","m5"],body:'# graph.refactor\n\nApplies a single pattern-level structural transformation to a graph. Choose the\noperation type via `operation.type`.\n\n## Supported operations\n\n### `rename_by_pattern`\nRenames node/edge labels matching a JS regex pattern.\n`scope`: `"nodes"` | `"edges"` | `"both"`.\n\n### `extract_subgraph`\nMoves specified nodes (and edges between them) into a new sub-graph.\nCross-boundary edges are preserved as stubs. Returns `resultGraphId`.\n\n### `merge_nodes`\nCollapses `sourceNodeIds` into `targetNodeId`.\n`strategy`: `"union"` (all edges kept) | `"intersect"` (shared edges only).\n\n### `split_node`\nExpands one node into multiple partitions. Edges re-distributed by kind affinity.\n\n## Dry run\n\nPass `dryRun: true` to preview the diff without mutating state.\nThe `preview` field in the output is always populated; `applied` is `false`.\n\n## Budget (M5 P2/W2.2)\nmaxInputTokens=2 000 · maxOutputTokens=600 · hardCapUsd=$0.035'}},{id:"docs.tech.graph.search",exportName:"GraphSearchDocBlock",sourceModule:"agent/commands/graphOps.command",block:{id:"docs.tech.graph.search",title:"graph.search — NL node search",summary:"Natural-language graph search returning ranked node/edge IDs and an optional viewport suggestion. Budget: 1 000 in / 200 out / $0.005.",kind:"reference",visibility:"public",route:"/docs/tech/graph/search",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:"# graph.search\n\nTranslates a natural-language query into ranked `nodeIds` and `edgeIds`.\nAlso returns an optional viewport suggestion `{ centerX, centerY, zoom }`\nthe canvas can animate to.\n\n## Budget (`m3-p0-ai-cost-ceiling.md`)\nmaxInputTokens=1 000 · maxOutputTokens=200 · hardCapUsd=$0.005"}},{id:"docs.tech.graph.suggest",exportName:"GraphSuggestDocBlock",sourceModule:"agent/commands/graphOps.command",block:{id:"docs.tech.graph.suggest",title:"graph.suggest — AI graph-edit suggestions",summary:"Ranked read-only graph-edit suggestions. Mutations require explicit user confirmation. Budget: 2 000 in / 800 out / $0.020.",kind:"reference",visibility:"public",route:"/docs/tech/graph/suggest",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.suggest
+
+Returns ranked suggestions for graph edits based on a natural-language request.
+
+**Read-only**: suggestions are never auto-applied. Each must be confirmed via
+the AI suggestion confirmation UX (W7.4) before any mutation occurs.
+
+## Output shape
+\`suggestions: Array<{ id, label, description, confidence, action }>\`
+
+## Truncation
+Output >800 tokens is halted mid-stream; \`truncated: true\` is returned.
+Users may request expansion.
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=2 000 · maxOutputTokens=800 · hardCapUsd=$0.020`}},{id:"docs.tech.graph.suggest-evolution",exportName:"GraphSuggestEvolutionDocBlock",sourceModule:"agent/commands/graphSuggestEvolution.command",block:{id:"docs.tech.graph.suggest-evolution",title:"graph.suggest_evolution — proactive graph evolution suggestions",summary:"Ranks structural and semantic improvement suggestions for a graph: missing reviewer, missing retry, weak path, isolated node, naming inconsistency, missing feedback loop, circular dependency, high fan-out. Budget: 2 500 in / 1 000 out / $0.028.",kind:"reference",visibility:"public",route:"/docs/tech/graph/suggest-evolution",tags:["automation","agent","execution","graph","ai","evolution","suggestions","m5"],body:`# graph.suggest_evolution
+
+Analyses the current graph and returns ranked proactive improvement suggestions.
+Suggestions are **read-only** — nothing is applied automatically.
+
+## Suggestion kinds
+
+| kind | Description |
+|---|---|
+| \`missing_reviewer\` | A node or flow has no assigned reviewer / approval step |
+| \`missing_retry\`    | An error path has no retry or back-off edge |
+| \`weak_path\`        | A critical path has only one route (no redundancy) |
+| \`isolated_node\`    | A node has neither incoming nor outgoing edges |
+| \`naming_inconsistency\` | Labels diverge from the dominant naming style |
+| \`missing_feedback_loop\` | A workflow has no feedback or notification branch |
+| \`circular_dependency\` | A cycle exists that may indicate a design issue |
+| \`high_fan_out\`     | A node has an unusually large number of outgoing edges |
+
+## focusArea
+
+Narrow the scan to reduce cost and noise:
+- \`"reliability"\` — retry, redundancy, failure-path coverage
+- \`"coverage"\`    — reviewer presence, approval steps, feedback loops
+- \`"connectivity"\` — isolated nodes, weak paths, high fan-out
+- \`"naming"\`      — label consistency
+- \`"all"\`         — full scan (default)
+
+## Acting on suggestions
+
+Each suggestion includes a \`suggestedFix\` string.
+Pass that text back to \`graph.edit\` or \`graph.compose\` to apply the fix
+after confirming through the AI suggestion UX (W7.4).
+
+## Budget (M5 P2/W2.4)
+maxInputTokens=2 500 · maxOutputTokens=1 000 · hardCapUsd=$0.028`}},{id:"docs.tech.observability.database-signals",exportName:"DatabaseSignalsDocBlock",sourceModule:"observability/database-signals",block:{id:"docs.tech.observability.database-signals",title:"Database observability signals",summary:"Canonical database.query / database.mutation duration signals (ms).",kind:"reference",visibility:"public",route:"/docs/tech/observability/database-signals",tags:["observability","signals","database","latency"],body:"# Database signals\n\nCanonical observability signals for governed database access.\n\n- `database.query` — governed read duration metric (`ms`).\n- `database.mutation` — governed write duration metric (`ms`).\n\nBoth ids are stable, locale-free machine strings and reference canonical\ndimension ids only (`tenant.ref`, `database.table`, `database.operation`,\n`database.dialect`). Construct/validate via `defineSignal`.\n"}},{id:"docs.tech.observability.evidence-record",exportName:"EvidenceRecordDocBlock",sourceModule:"observability/evidence-record",block:{id:"docs.tech.observability.evidence-record",title:"EvidenceRecord — persisted signal evidence envelope",summary:"Type-only persisted envelope for observed signals; tenantId is the raw RLS key.",kind:"reference",visibility:"public",route:"/docs/tech/observability/evidence-record",tags:["observability","evidence","cost","usage","tenancy"],body:"# EvidenceRecord\n\nThe persisted envelope for a single observed signal — the shared spine consumed\nby observability and billing.\n\n- Declared as the `EvidenceRecordModel` `SchemaModel`; `EvidenceRecord` is its\n  Zod-inferred TS shape.\n- `tenantId` is stored **raw**, never hashed: it is the row-level-security key.\n- `idempotencyKey` and `occurredAt` are required (at-least-once dedupe + time).\n- `value` or `quantities` carries the payload; `cost`/`usage` signals attach\n  `SignalCostEvidence`.\n- `redactionRef` points at the redaction policy applied to payload values.\n\nThis module is type-only + a validator. Persistence/DB wiring lives in the app\nadapter, not here.\n"}},{id:"docs.tech.observability.signal-spec",exportName:"SignalSpecDocBlock",sourceModule:"observability/signal-spec",block:{id:"docs.tech.observability.signal-spec",title:"SignalSpec — observability/cost/usage signal declarations",summary:"Canonical, locale-free declaration layer for metric/trace/cost/usage signals.",kind:"reference",visibility:"public",route:"/docs/tech/observability/signal-spec",tags:["observability","signals","cost","usage","i18n"],body:"# SignalSpec\n\nThe typed declaration layer for all observability/cost/usage signals. One spine,\ntwo consumers: observability (metric/trace) and billing (cost/usage).\n\n- Declared as the `SignalSpecModel` `SchemaModel`; `SignalSpec` is its\n  Zod-inferred TS shape.\n- `id` and `dimensions` are stable machine strings — never localized, never\n  locale-suffixed (enforced by `i18n/no-localized-machine-contracts` and by\n  `defineSignal` validation).\n- `dimensions` reuse canonical semantic dimension ids from the analytics layer.\n- `costModelVersion` and `redactionPolicyRef` are optional refs consumed by the\n  billing/evidence pipeline.\n\nUse `defineSignal(spec)` to construct a validated `SignalSpec`.\n"}},{id:"docs.tech.osint.job-source-acquisition-routing",exportName:"JobSourceAcquisitionRoutingDocBlock",sourceModule:"osint/job-sources",block:{id:"docs.tech.osint.job-source-acquisition-routing",title:"Direct-first job source acquisition routing",summary:"Exact-plan direct acquisition with qualified, policy-bound provider escalation and append-only attempt evidence.",kind:"reference",visibility:"public",route:"/docs/tech/osint/job-source-acquisition-routing",tags:["osint","jobs","acquisition","routing","evidence"],relatedSpecs:["osint.source.sync","osint.source.revalidate.governed"],body:`# Direct-first job source acquisition routing
+
+Every acquisition plan starts with credential-free direct fetch. A later route
+may execute only when it has an opaque qualified connection reference and the
+preceding failure is explicitly classified as safe to escalate. Authentication,
+policy, source-restriction, rate-limit, cancellation, and ambiguous failures do
+not rotate providers. Every attempt binds the immutable plan, request digest,
+route, timestamps, evidence, and selected result for exact replay.
+The complete execution receipt is persisted with the immutable source snapshot.
+`}},{id:"docs.tech.osint.job-source-live-qualification",exportName:"JobSourceLiveQualificationDocBlock",sourceModule:"osint/job-sources",block:{id:"docs.tech.osint.job-source-live-qualification",title:"Job source live qualification receipts",summary:"Exact-release, scope-, installation-, policy-, request-, response-, and evidence-bound live qualification without promoting fixtures.",kind:"reference",visibility:"public",route:"/docs/tech/osint/job-source-live-qualification",tags:["osint","jobs","qualification","evidence"],relatedSpecs:["osint.source.qualify.governed","osint.source.revalidate.governed"],body:`# Job source live qualification receipts
+
+Live qualification is separate from deterministic fixtures. A passed receipt
+binds the exact release SHA, complete OSINT scope, source capability,
+installation and policy authorization fingerprints, request and response
+digests, immutable evidence, and observation window. Account- or
+permission-gated support remains blocked until an authorized live receipt is
+present. Unsupported capabilities cannot be promoted by a receipt.
+`}},{id:"docs.tech.osint.operational-recovery",exportName:"OsintOperationalRecoveryDocBlock",sourceModule:"osint/operational-contracts",block:{id:"docs.tech.osint.operational-recovery",title:"Governed OSINT Operational Recovery",summary:"Revision-, attempt-, authority-, evidence-, and fingerprint-bound recovery for dead letters, webhook deliveries, and job listing reconciliation.",kind:"reference",visibility:"public",route:"/docs/tech/osint/operational-recovery",tags:["osint","dead-letter","webhook","jobs","replay"],relatedSpecs:["osint.dead_letter.list","osint.dead_letter.replay","osint.webhook.delivery.status","osint.webhook.delivery.replay","osint.job.listing.revalidate","osint.job.listing.closure.reconcile"],body:`# Governed OSINT Operational Recovery
+
+Operator recovery is fail-closed. Mutations bind the complete deployment scope,
+an idempotency key, the exact canonical revision and delivery or work attempt,
+authority and policy fingerprints, the public contract fingerprint, and
+authorized evidence. A stale replay or reconciliation request cannot silently
+repeat an effect. Job closure additionally requires explicit closure evidence,
+or repeated successful scans plus a direct detail recheck; a failed crawl is
+never closure evidence.
+`}},{id:"docs.tech.osint.rights-lifecycle",exportName:"OsintRightsLifecycleDocBlock",sourceModule:"osint/rights-contracts",block:{id:"docs.tech.osint.rights-lifecycle",title:"Governed OSINT Subject Rights",summary:"Effect-free admission and evidence-, revision-, policy-, deletion-, and replay-bound subject-rights processing.",kind:"reference",visibility:"public",route:"/docs/tech/osint/rights-lifecycle",tags:["osint","privacy","rights","deletion","governance"],relatedSpecs:["osint.rights.submit","osint.rights.get","osint.rights.list","osint.rights.verify","osint.rights.decide","osint.rights.complete"],body:`# Governed OSINT Subject Rights
+
+Submission records a received request and has no suppression or deletion
+effect. Verification and decision are separate revision-fenced operations.
+Only an approved deletion-class decision may create monotonic suppression and
+explicit derived-destination work. Every transition binds evidence, actor,
+policy decision, operation request digest, contract fingerprint, and replay.
+`}},{id:"docs.tech.osint.source-lifecycle",exportName:"OsintSourceLifecycleDocBlock",sourceModule:"osint/lifecycle-contracts",block:{id:"docs.tech.osint.source-lifecycle",title:"Governed OSINT Source Lifecycle",summary:"Contract-first authority, replay, lease, and evidence bindings for source qualification, activation, and revalidation.",kind:"reference",visibility:"public",route:"/docs/tech/osint/source-lifecycle",tags:["osint","source-lifecycle","governance","replay"],relatedSpecs:["osint.source.qualify.governed","osint.source.activate","osint.source.revalidate.governed","osint.source.quarantine","osint.source.retire"],body:`# Governed OSINT Source Lifecycle
+
+Lifecycle mutations bind the authenticated actor, scoped overlay authority,
+policy decision, contract fingerprint, canonical request digest, revision,
+evidence, and bounded claim before any evaluator or persistence effect.
+The original generic qualify and revalidate V1 contracts remain available only
+as compatibility surfaces; durable workers use the governed operation keys.
+`}},{id:"docs.tech.provider-ranking.benchmark.custom.completed",exportName:"BenchmarkCustomCompletedDocBlock",sourceModule:"provider-ranking/events/benchmarkCustomCompleted.event",block:{id:"docs.tech.provider-ranking.benchmark.custom.completed",title:"Custom benchmark completed event",summary:"Emitted when a custom benchmark run finishes.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/custom/completed",tags:["ai","ranking","event","custom"],body:`# provider-ranking.benchmark.custom.completed
+
+Emitted when a custom evaluation run completes execution.
+`}},{id:"docs.tech.provider-ranking.benchmark.ingest",exportName:"BenchmarkIngestDocBlock",sourceModule:"provider-ranking/commands/benchmarkIngest.command",block:{id:"docs.tech.provider-ranking.benchmark.ingest",title:"Ingest benchmark data",summary:"Trigger ingestion of external benchmark data.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/ingest",tags:["ai","ranking","ingest"],body:`# provider-ranking.benchmark.ingest
+
+Imports and normalizes benchmark scores from external leaderboards.
+`}},{id:"docs.tech.provider-ranking.benchmark.ingest.form",exportName:"BenchmarkIngestFormDocBlock",sourceModule:"provider-ranking/forms/benchmarkIngest.form",block:{id:"docs.tech.provider-ranking.benchmark.ingest.form",title:"Benchmark ingest form",summary:"Form specification for triggering benchmark ingestion.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/ingest/form",tags:["ai","ranking","form"],body:`# provider-ranking.benchmark.ingest.form
+
+Form surface used by Studio to trigger benchmark data ingestion.
+`}},{id:"docs.tech.provider-ranking.benchmark.ingested",exportName:"BenchmarkIngestedDocBlock",sourceModule:"provider-ranking/events/benchmarkIngested.event",block:{id:"docs.tech.provider-ranking.benchmark.ingested",title:"Benchmark ingested event",summary:"Emitted after external benchmark data is ingested.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/ingested",tags:["ai","ranking","event"],body:`# provider-ranking.benchmark.ingested
+
+Emitted when external benchmark data is successfully imported and stored.
+`}},{id:"docs.tech.provider-ranking.benchmark.results.index",exportName:"BenchmarkResultsDataViewDocBlock",sourceModule:"provider-ranking/views/benchmarkResults.dataView",block:{id:"docs.tech.provider-ranking.benchmark.results.index",title:"Benchmark results view",summary:"Data view for raw benchmark results.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/results/index",tags:["ai","ranking","data-view"],body:`# provider-ranking.benchmark.results.index
+
+List view over individual benchmark data points from all sources.
+`}},{id:"docs.tech.provider-ranking.benchmark.results.list",exportName:"BenchmarkResultsListDocBlock",sourceModule:"provider-ranking/queries/benchmarkResultsList.query",block:{id:"docs.tech.provider-ranking.benchmark.results.list",title:"List benchmark results",summary:"List raw benchmark results.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/results/list",tags:["ai","ranking","results"],body:`# provider-ranking.benchmark.results.list
+
+Returns individual benchmark data points filterable by source, model, and dimension.
+`}},{id:"docs.tech.provider-ranking.benchmark.run-custom",exportName:"BenchmarkRunCustomDocBlock",sourceModule:"provider-ranking/commands/benchmarkRunCustom.command",block:{id:"docs.tech.provider-ranking.benchmark.run-custom",title:"Run custom benchmark",summary:"Launch a custom benchmark evaluation against a model.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/run-custom",tags:["ai","ranking","custom","eval"],body:`# provider-ranking.benchmark.run-custom
+
+Evaluates model performance using internal eval suites with configurable parameters.
+`}},{id:"docs.tech.provider-ranking.benchmark.run-custom.form",exportName:"BenchmarkRunCustomFormDocBlock",sourceModule:"provider-ranking/forms/benchmarkRunCustom.form",block:{id:"docs.tech.provider-ranking.benchmark.run-custom.form",title:"Custom benchmark form",summary:"Form specification for launching custom benchmarks.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/benchmark/run-custom/form",tags:["ai","ranking","form"],body:`# provider-ranking.benchmark.run-custom.form
+
+Form surface used by Studio to launch custom benchmark evaluations.
+`}},{id:"docs.tech.provider-ranking.model.comparison",exportName:"ModelComparisonDocBlock",sourceModule:"provider-ranking/presentations/modelComparison.presentation",block:{id:"docs.tech.provider-ranking.model.comparison",title:"Model comparison presentation",summary:"Presentation spec for side-by-side model comparison.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/model/comparison",tags:["ai","ranking","presentation","comparison"],body:`# provider-ranking.model.comparison
+
+Presentation surface for comparing two or more models across all ranking dimensions.
+`}},{id:"docs.tech.provider-ranking.model.profile.get",exportName:"ModelProfileGetDocBlock",sourceModule:"provider-ranking/queries/modelProfileGet.query",block:{id:"docs.tech.provider-ranking.model.profile.get",title:"Get model profile",summary:"Get detailed profile for a single model.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/model/profile/get",tags:["ai","ranking","model","profile"],body:`# provider-ranking.model.profile.get
+
+Returns comprehensive model information including scores, metadata, cost, context window, and capabilities.
+`}},{id:"docs.tech.provider-ranking.ranking.get",exportName:"ProviderRankingGetDocBlock",sourceModule:"provider-ranking/queries/providerRankingGet.query",block:{id:"docs.tech.provider-ranking.ranking.get",title:"Get provider rankings",summary:"Get ranked list of providers and models.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/ranking/get",tags:["ai","ranking","leaderboard"],body:`# provider-ranking.ranking.get
+
+Returns a paginated, filterable leaderboard of AI models ranked by composite or per-dimension scores.
+`}},{id:"docs.tech.provider-ranking.ranking.index",exportName:"ProviderRankingsDataViewDocBlock",sourceModule:"provider-ranking/views/providerRankings.dataView",block:{id:"docs.tech.provider-ranking.ranking.index",title:"Provider rankings view",summary:"Data view for the model leaderboard.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/ranking/index",tags:["ai","ranking","data-view"],body:`# provider-ranking.ranking.index
+
+List view over ranked models with composite and per-dimension scores.
+`}},{id:"docs.tech.provider-ranking.ranking.refresh",exportName:"RankingRefreshDocBlock",sourceModule:"provider-ranking/commands/rankingRefresh.command",block:{id:"docs.tech.provider-ranking.ranking.refresh",title:"Refresh rankings",summary:"Recompute composite rankings from latest benchmark data.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/ranking/refresh",tags:["ai","ranking","refresh"],body:`# provider-ranking.ranking.refresh
+
+Recomputes weighted composite scores across all dimensions and updates the leaderboard.
+`}},{id:"docs.tech.provider-ranking.ranking.updated",exportName:"RankingUpdatedDocBlock",sourceModule:"provider-ranking/events/rankingUpdated.event",block:{id:"docs.tech.provider-ranking.ranking.updated",title:"Ranking updated event",summary:"Emitted when composite rankings are recomputed.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/ranking/updated",tags:["ai","ranking","event"],body:`# provider-ranking.ranking.updated
+
+Emitted when the leaderboard is refreshed with new composite scores.
+`}},{id:"docs.tech.provider-ranking.system",exportName:"ProviderRankingSystemDocBlock",sourceModule:"provider-ranking/provider-ranking.feature",block:{id:"docs.tech.provider-ranking.system",title:"AI Provider Ranking",summary:"Benchmark ingestion, scoring, and ranking for AI providers and models.",kind:"reference",visibility:"public",route:"/docs/tech/provider-ranking/system",tags:["ai","ranking","benchmark"],body:`# AI Provider Ranking
+
+Defines the core operations, events, and UI surfaces for ingesting benchmark data, computing composite rankings, and comparing AI models across dimensions.
+`}},{id:"docs.tech.report-verification-table",exportName:"reportVerificationTableDocBlocks",sourceModule:"data-views/report/contractVerificationTable",block:{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)
+`}},{id:"docs.tech.review.approve",exportName:"ReviewApproveDocBlock",sourceModule:"operations/review/commands/reviewApprove.command",block:{id:"docs.tech.review.approve",title:"Approve a review record",summary:"Terminal-approve a review record; emits one audit event and dispatches the SEAMS §3.7 subject-kind callee (when applicable).",kind:"reference",visibility:"public",route:"/docs/tech/review/approve",tags:["review","approve","mutation"],body:"# review.approve\n\nApproves a review record. Terminal at the record level — re-opening requires\na fresh review (no `review.reopen` in v1.0).\n\nPer SEAMS §3.7 (S-07): when `subject.kind` resolves a downstream callee\n(`governance.policy.activate` ∨ `workflow.run.resume` ∨\n`agent.set-autonomy`), the handler dispatches it via the\n`lib.companyos-runtime` outbox. The dispatched op runs under the original\nreviewer's auth context (§1.2); the handler pre-checks the reviewer's\ncapability at decide-time per Q-03 and refuses with `FORBIDDEN` when the\ndownstream capability is missing — prevents the \"approved but inert\" state.\n\nCapability: `review.act` (+ implicit downstream capability where dispatch\napplies). Per SEAMS §1.5, missing capability returns `FORBIDDEN` — auditor\npersona sees the button disabled with a read-only tooltip.\n\nIdempotency: `idempotencyKey` is required. Replays return the original\nresult; differing payload on replay → `IDEMPOTENCY_FAIL`.\n"}},{id:"docs.tech.review.assign",exportName:"ReviewAssignDocBlock",sourceModule:"operations/review/commands/reviewAssign.command",block:{id:"docs.tech.review.assign",title:"Assign a review to a reviewer",summary:"Assign (or reassign) a review record to a reviewer; idempotent on (id, assigneeId).",kind:"reference",visibility:"public",route:"/docs/tech/review/assign",tags:["review","assign","mutation"],body:`# review.assign
+
+Assigns (or reassigns) a review to a reviewer. Idempotent on
+\`(id, assigneeId)\` — re-assigning to the same reviewer is a no-op success.
+
+Per SEAMS §1.3 (S-11), emits one \`audit.event.append\` with kind
+\`review.assigned\` (retention class \`operational\`). Per SEAMS §3.6.4,
+downstream notifications to the new assignee are fire-and-forget; failure
+does NOT roll back the assignment.
+
+Capability: \`review.act\`. Idempotency: required.
+`}},{id:"docs.tech.review.comment",exportName:"ReviewCommentDocBlock",sourceModule:"operations/review/commands/reviewComment.command",block:{id:"docs.tech.review.comment",title:"Comment on a review",summary:"Append a thread or private-to-assignee comment to a review record.",kind:"reference",visibility:"public",route:"/docs/tech/review/comment",tags:["review","comment","mutation"],body:"# review.comment\n\nAppends a comment to a review. Does not advance state. `visibility` is one\nof `'thread'` (visible to all participants) | `'private-to-assignee'`\n(visible only to the current assignee and the commenter).\n\nPer SEAMS §1.3 (S-11), emits one `audit.event.append` with kind\n`review.commented` (retention class `operational`).\n\nCapability: `review.act` for posting; `review.read` for thread reads.\nAuditor persona may read but cannot post — the UI renders the post button\ndisabled with a read-only tooltip per SEAMS §1.5.\n"}},{id:"docs.tech.review.escalate",exportName:"ReviewEscalateDocBlock",sourceModule:"operations/review/commands/reviewEscalate.command",block:{id:"docs.tech.review.escalate",title:"Escalate a review to a higher tier",summary:"Escalate a review to a target tier; emits an audit event and (optionally) a governance notification via the outbox.",kind:"reference",visibility:"public",route:"/docs/tech/review/escalate",tags:["review","escalate","mutation","governance","audit"],body:"# review.escalate\n\nPRIMARY cross-domain seam (SEAMS §3.6, S-06). On successful escalation, the\nhandler emits two ordered outbox messages alongside the review's own state\nchange:\n\n1. `audit.event.append { eventKind: 'review.escalated', retentionClass: 'regulatory', payload: { reviewId, fromStatus, toTier, escalationReason, decidedBy, decidedAt } }`. `auditEventId` is returned in the output for traceability.\n2. If `notifyOwners === true`, `governance.notification.dispatch { policyRefs: subject.policyRefs[], escalationContext: { reviewId, tier, auditEventId } }`. `governanceNotificationId` is returned in the output (optional field).\n\nPer SEAMS §1.4 transactional outbox: state change + outbox row commit\natomically; downstream callees are idempotent on\n`(reviewId, escalation-version)` so replays are safe.\n\nCapability: `review.escalate` (+ implicit `review.act`). Per SEAMS §1.5,\nmissing capability returns `FORBIDDEN`. Idempotency: required.\n\nTier vocabulary (`'tier-1' | 'tier-2' | 'admin'`) aligns with\n`lib.identity-rbac` role tiers (DOMAIN_NOTES §9 Q1; coordinated with W5).\n"}},{id:"docs.tech.review.get",exportName:"ReviewGetDocBlock",sourceModule:"operations/review/queries/reviewGet.query",block:{id:"docs.tech.review.get",title:"Get review detail",summary:"Return a full review record with history and attached evidence.",kind:"reference",visibility:"public",route:"/docs/tech/review/get",tags:["review","detail"],body:`# review.get
+
+Returns the full review detail, including decision history and evidence
+references (from the audit append-only log). Read-only.
+
+Capability: \`review.read\`. Per SEAMS §3.4a, this query is the verification
+gate used by \`workflow.step.advance { approvalRef }\` — handlers MUST treat
+the response as authoritative.
+`}},{id:"docs.tech.review.list",exportName:"ReviewListDocBlock",sourceModule:"operations/review/queries/reviewList.query",block:{id:"docs.tech.review.list",title:"List reviews in the queue",summary:"Paginated read of review records, filterable by status, priority, assignee, and subject.",kind:"reference",visibility:"public",route:"/docs/tech/review/list",tags:["review","list","queue"],body:"# review.list\n\nLists review records for the caller's tenant scope. Supports filters\n(`statuses`, `priorities`, `assigneeId`, `subjectKind`, `subjectId`)\nand cursor pagination. Auditor persona may invoke read-only.\n\nCapability: `review.read`. Per SEAMS §1.5, missing capability returns\n`FORBIDDEN` — never silent strip.\n"}},{id:"docs.tech.review.queue.health",exportName:"ReviewQueueHealthDocBlock",sourceModule:"operations/review/queries/reviewQueueHealth.query",block:{id:"docs.tech.review.queue.health",title:"Review queue health probe",summary:"Per-domain health probe consumed by fleet.health.snapshot to surface review-queue saturation, SLA, and pipeline state.",kind:"reference",visibility:"public",route:"/docs/tech/review/queue/health",tags:["review","health","fleet"],body:"# review.queue.health\n\nPer-domain health probe for the review queue, composed by\n`fleet.health.snapshot` (SEAMS §3.10, S-10). Returns a `green` |\n`amber` | `red` status plus a symptoms list; aggregations downgrade to\namber if the probe call itself fails.\n\nThresholds (initial v1.0; tunable via runtime config):\n- `red` when `backlogDepth > 100` OR `oldestPendingAgeMs > 24h` OR\n  `audit-pipeline-degraded` is present.\n- `amber` when `backlogDepth > 25` OR `oldestPendingAgeMs > 4h` OR\n  `escalatedCount > 5`.\n- `green` otherwise.\n\nCapability: `fleet.metrics.read` ∨ `review.read`.\n"}},{id:"docs.tech.review.reject",exportName:"ReviewRejectDocBlock",sourceModule:"operations/review/commands/reviewReject.command",block:{id:"docs.tech.review.reject",title:"Reject a review record",summary:"Terminal-reject a review record; emits one audit event with the reviewer-supplied reason.",kind:"reference",visibility:"public",route:"/docs/tech/review/reject",tags:["review","reject","mutation"],body:"# review.reject\n\nTerminally rejects a review record. Terminal at the record level — re-opening\nrequires a fresh review.\n\nPer SEAMS §1.3 (S-11), emits exactly one `audit.event.append` with kind\n`review.rejected` and retention class `regulatory`. Returns\n`auditEventId` so the UI can deep-link to the record.\n\nCapability: `review.act`. Per SEAMS §1.5, missing capability returns\n`FORBIDDEN` — auditor persona sees the button disabled.\n\nIdempotency: `idempotencyKey` is required.\n"}},{id:"docs.tech.review.request-changes",exportName:"ReviewRequestChangesDocBlock",sourceModule:"operations/review/commands/reviewRequestChanges.command",block:{id:"docs.tech.review.request-changes",title:"Request changes on a review",summary:"Push the review back to changes-requested with a structured list of change requests.",kind:"reference",visibility:"public",route:"/docs/tech/review/request-changes",tags:["review","request-changes","mutation"],body:"# review.request-changes\n\nTransitions the review record to `changes-requested` with a structured\nlist of `changeRequests` (field-scoped). Non-terminal: when the upstream\nsubject is updated, the review system fires an internal `review.resubmit`\nevent (not a public op) that returns the review to `pending`.\n\nPer SEAMS §1.3 (S-11), emits exactly one `audit.event.append` with kind\n`review.changes-requested`.\n\nCapability: `review.act`. Idempotency: required.\n"}},{id:"docs.tech.social-provider-v2",exportName:"SocialProviderV2DocBlock",sourceModule:"feature-hubs/social-provider-v2",block:{id:"docs.tech.social-provider-v2",title:"Scoped social publication providers",summary:"Versioned provider execution carries tenant identity and durable local publication keys.",visibility:"public",kind:"reference",route:"/docs/tech/social-provider-v2",tags:["social","marketing"],body:`# Scoped social publication providers
+
+V2 publication and status ports require tenant identity, account identity and a durable
+local idempotency key. Native API idempotency support is independent of that local key.
+Integrations must bind content, credentials and provider resources to the requested tenant
+before dispatch. Partial or uncertain publication remains ambiguous. Multi-part adapters receive the
+named publishing grant and recheck it before every part. Optional resume crosses fresh
+authority and a fenced canonical continuation claim; status never publishes pending work.
+
+The social runtime supports an explicit providersV2 map while preserving its legacy
+providers map. V2 takes precedence when configured; failures do not fall back to another
+publisher. Resolve legacy ambiguous receipts before switching provider implementations,
+or supply an explicitly authorized compatibility reader. Draft-only remains the default.
+`}},{id:"docs.tech.social-scheduling",exportName:"SocialSchedulingDocBlock",sourceModule:"feature-hubs/social-scheduling-operations",block:{id:"docs.tech.social-scheduling",title:"Durable social scheduling",summary:"Reviewed LinkedIn/X scheduling with canonical publication intents and SQL recovery.",visibility:"public",kind:"reference",route:"/docs/tech/social-scheduling",tags:["social","marketing"],body:`# Durable social scheduling
+
+The feature-hubs/social-scheduling contracts add immutable LinkedIn/X schedules.
+Eight operations cover scheduling, cancellation, due scans, dispatch, continuation,
+reconciliation, scoped reads and bounded worker batches. Publication stays behind the
+existing SocialPublicationRuntime and its grant, digest, policy and effect gates.
+The default remains draft-only until a host explicitly configures publication authority.
+
+SQL adapters preserve schedules, canonical publication intents, append-only history
+and fenced recovery leases. Cancellation cannot erase a claimed publication. Expired
+windows do not dispatch, and confirmed outcomes remain immutable. Interrupted workers
+may continue under fresh authority while canonical idempotency prevents duplicate posts.
+
+Register workers through the existing lifecycle scheduler and persist batch outcomes
+through the supplied host observer. Native LinkedIn/X provider and account qualification,
+real media publication and application cutover remain separate acceptance requirements.
+`}},{id:"docs.tech.translations.i18n-factory",exportName:"I18nFactoryDocBlock",sourceModule:"translations/i18n-factory",block:{id:"docs.tech.translations.i18n-factory",title:"i18n factory",summary:"Package-scoped i18n factory with additive snapshot/hydration support.",kind:"reference",visibility:"public",route:"/docs/tech/translations/i18n-factory",tags:["i18n","translations"],body:"# i18n factory\n\n`createI18nFactory` removes the per-package i18n boilerplate (interpolation,\nregistry management, locale resolution, `t()` wiring).\n\nInstances and factories additionally expose `snapshot()` and\n`hydrationPayload()`, and the module exports\n`createI18nFactoryFromSnapshot` / `createI18nFactoryFromHydrationPayload`\nto rebuild a factory on the client. These additions are **ADDITIVE** and do not\nchange resolution behavior for existing consumers.\n"}},{id:"docs.tech.translations.i18n-factory.snapshot",exportName:"I18nFactorySnapshotDocBlock",sourceModule:"translations/i18n-factory-snapshot",block:{id:"docs.tech.translations.i18n-factory.snapshot",title:"i18n factory snapshot & hydration",summary:"Additive snapshot/serialization/hydration surface for the createI18nFactory stack.",kind:"reference",visibility:"public",route:"/docs/tech/translations/i18n-factory/snapshot",tags:["i18n","translations","ssr","hydration"],body:"# i18n factory snapshot & hydration\n\nThe canonical, additive (behavior-compatible) snapshot/hydration surface on the\n`createI18nFactory` stack.\n\n- `buildI18nFactorySnapshot` produces a **locale-scoped** snapshot containing\n  only the catalogs needed to reproduce identical `t()` results for the locale\n  (the locale plus its declared fallback chain).\n- `createI18nFactoryHydrationPayload` wraps a snapshot in a versioned envelope\n  (`kind` = `contractspec.i18n-factory.hydration`, `version` =\n  `1`) for SSR -> client transport.\n- `parseI18nFactoryHydrationPayload` validates and re-clones the payload.\n\nReconstruct a factory from a snapshot or payload with\n`createI18nFactoryFromSnapshot` / `createI18nFactoryFromHydrationPayload`\n(see the `i18n-factory` module).\n\nCompatibility classification: **ADDITIVE**. No existing exported symbol or\nresolution behavior changes.\n"}},{id:"docs.tech.workflows.overview",exportName:"tech_workflows_overview_DocBlocks",sourceModule:"workflow/spec",block:{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, including runtime adapter capabilities/ports for checkpointing, suspend-resume orchestration, and explicit waiting/retry states. Specs stay inside `@lssm/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 `@lssm/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- `defineWorkflow()` is available from `@lssm/lib.contracts-spec/workflow/spec` for safe workflow authoring in VM-evaluated runtimes.\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 (`@lssm/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).\n6. For Vercel Workflow or other VM-evaluated runtimes, import `defineWorkflow` and `WorkflowSpec` from `@lssm/lib.contracts-spec/workflow/spec`.\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"}},{id:"forms-platform-document",exportName:"formPlatformDocumentDocBlock",sourceModule:"forms/platform-document-doc",block:{id:"forms-platform-document",title:"Shared Forms Platform Document",body:"Portable Forms contracts for Pactena, CompanyOS, and CommunicationOS. Published revisions are immutable, responses pin a revision, creator logic is declarative, AI is off and redacted by default, and product hosts retain authority and storage ownership.",kind:"reference",route:"/docs/specs/forms/platform-document",visibility:"public"}},{id:"forms-platform-events",exportName:"formPlatformEventsDocBlock",sourceModule:"forms/platform-docs",block:{id:"forms-platform-events",title:"Shared Forms events",body:"PII-free lifecycle receipts for definition, response, and verification transitions. Raw answers, contact destinations, and verification codes are never event payloads.",kind:"reference",route:"/docs/specs/forms/platform-events",visibility:"public"}},{id:"forms-platform-operations",exportName:"formPlatformOperationsDocBlock",sourceModule:"forms/platform-docs",block:{id:"forms-platform-operations",title:"Shared Forms operations",body:"Versioned creator and public operations. Creator ownership is derived from authenticated server context; public operations accept opaque tokens and never tenant authority. This experimental foundation does not claim product-host availability until its adapters pass Connect review.",kind:"reference",route:"/docs/specs/forms/platform-operations",visibility:"public"}},{id:"living-sops-v1",exportName:"LivingSopsDocBlock",sourceModule:"sop/sop.feature",block:{id:"living-sops-v1",title:"Living SOPs v1",summary:"Evidence-bound, generated, simulated, qualified, and revision-pinned operational procedures.",kind:"reference",visibility:"public",route:"/docs/platform/living-sops-v1",tags:["sop","knowledge","workflow","health"],body:`# Living SOPs v1
+
+SOP generation, publication, and execution are separate lifecycles. Generated revisions freeze their evidence and compile into WorkflowSpec for effects.`}},{id:"nav-graph-spec",exportName:"navGraphDocBlock",sourceModule:"navigation/nav-graph",block:{id:"nav-graph-spec",title:"NavGraphSpec",body:`Relationship graph over registered navigation surface items with hand-curated product knowledge edges.
+
+## Overview
+
+\`NavGraphSpec\` models the navigation surface as a directed graph where:
+- **Nodes** are \`NavSurfaceItemSpec\` entries (typically auto-derived from \`NavRegistry.list()\`)
+- **Edges** are hand-maintained product relationships describing how surfaces relate
+- **Optional Layout** hints how to render the graph in the Nav Map viewer
+
+## Edge Semantics
+
+Edges use semantic kinds to express relationship intent:
+
+| Kind | Meaning | Example |
+|------|---------|---------|
+| \`related\` | Surfaces are related but not ordered | inbox ↔ threads |
+| \`leads-to\` | Natural workflow progression | workflow → evidence |
+| \`escalates-to\` | Escalation path | support → escalation-queue |
+| \`parent-of\` | Hierarchical containment | analytics → analytics/usage |
+
+Each edge carries an optional \`weight\` (0..∞) indicating usage frequency or affinity.
+
+## Validation
+
+\`validateNavGraph\` ensures:
+- No self-loops
+- Both endpoints resolve to node routes
+- No duplicate (from, to, kind) triples
+
+## Integration with Design-System Graph Templates
+
+\`NavGraphSpec\` integrates with existing DS graph renderers:
+- \`ConversationGraphView\` — render conversation/discussion threads
+- \`WorkflowDagView\` — render workflow DAG
+- \`AgentTreeView\` — render agent hierarchy
+- \`EngineeringLoopView\` — render loop/feedback structures
+
+The Nav Map view at \`/companyos/nav-map\` renders the full \`NavGraphSpec\` to show power users the complete navigation topology.
+
+## Example
+
+\`\`\`typescript
+const navGraph = defineNavGraph({
+  meta: {
+    key: 'companyos-nav',
+    version: '1.0.0',
+    description: 'CompanyOS navigation graph',
+    goal: 'Enable power-user nav-map view and routing suggestions',
+    context: 'Global navigation topology for all personas',
+    owners: ['team-platform'],
+    tags: ['core', 'navigation'],
+  },
+  nodes: navRegistry.list(),
+  edges: [
+    defineNavEdge({
+      from: { web: '/companyos/workflow' },
+      to: { web: '/companyos/evidence' },
+      kind: 'leads-to',
+      weight: 2.5,
+    }),
+    defineNavEdge({
+      from: { web: '/companyos/inbox' },
+      to: { web: '/companyos/threads' },
+      kind: 'related',
+    }),
+  ],
+  layout: { type: 'force-directed', spacing: 200 },
+});
+\`\`\``,kind:"reference",route:"packages/libs/contracts-spec/src/navigation/nav-graph.ts",visibility:"public"}},{id:"nav-registry",exportName:"navRegistryDocBlock",sourceModule:"navigation/registry",block:{id:"nav-registry",title:"NavRegistry",body:"In-memory registry for navigation surface items with persona- and group-aware queries and capability binding validation.\n\n## Overview\n\n`NavRegistry` mirrors the `CapabilityRegistry` API and provides:\n- **Registration**: `register(spec)` with duplicate + capability validation\n- **Queries**: `get(key, version?)`, `list()`, `indexByPersona()`, `indexByGroup()`\n- **Role-aware resolution**: `resolveForRoleMorph(roleMorph, preferences)`\n\n## Registration Flow\n\n1. Create `NavSurfaceItemSpec` entries using `defineNavSurfaceItem()`\n2. Optionally pass a `CapabilityRegistry` to the `NavRegistry` constructor\n3. Call `register(spec)` for each entry\n   - Throws if `meta.key + version` is duplicate\n   - Throws if capability is not registered with `surface: 'navigation'` (when `CapabilityRegistry` is provided)\n4. Use queries to retrieve filtered nav items\n\n## resolveForRoleMorph Semantics\n\n`resolveForRoleMorph(roleMorph, preferences)` filters the registry to:\n1. **Persona intersection**: Keep entries where `personaVisibility` overlaps with `roleMorph.personas`\n2. **Group hiding**: Remove entries in `preferences.hiddenGroups`\n3. **De-duplication**: By `meta.key` (latest version wins)\n\nReturns a flat array of visible `NavSurfaceItemSpec` in insertion order.\n\n## CapabilityRegistry Binding Validation\n\nIf a `CapabilityRegistry` is provided at construction, `register()` validates that:\n- `spec.capability.key` is registered in capabilities with `surface: 'navigation'`\n- If not, throws: `\"Nav item {id} references capability {key} which is not registered with surface 'navigation'\"`\n\nThis ensures all nav items map to real capabilities at build time.\n\n## Index Caching\n\nBoth persona and group indexes are lazy-built and cached; they invalidate on `register()`.\n\n## Example Usage\n\n```typescript\nconst registry = new NavRegistry({ capabilities: capabilityRegistry });\n\nregistry.register(inboxNavSpec);\nregistry.register(workflowNavSpec);\nregistry.register(analyticsNavSpec);\n\n// Get entries visible to a persona\nconst founderNav = registry.indexByPersona('founder_approver');\n\n// Resolve for a role-morph with hidden groups\nconst visibleNav = registry.resolveForRoleMorph(\n  { personas: ['founder_approver', 'operations_manager'] },\n  { hiddenGroups: ['experimental'] }\n);\n\n// Build a NavGraphSpec from the registry\nconst graph = defineNavGraph({\n  meta: { /* ... */ },\n  nodes: registry.list(),\n  edges: [ /* hand-curated */ ],\n});\n```",kind:"how",route:"packages/libs/contracts-spec/src/navigation/registry.ts",visibility:"public"}},{id:"nav-surface-item-spec",exportName:"navSurfaceDocBlock",sourceModule:"navigation/nav-surface",block:{id:"nav-surface-item-spec",title:"NavSurfaceItemSpec",body:`Single navigation entry contract that binds a capability to a web route with persona and grouping semantics. Includes optional mobile-extension fields for Expo Router native navigation (Phase D.0).
+
+## Overview
+
+\`NavSurfaceItemSpec\` mirrors the \`PresentationSpec.capability\` pattern and defines a hard binding between:
+- A registered **capability** that provides the navigation surface (validated against CapabilityRegistry)
+- A **route** (web path + optional API root)
+- **Persona visibility** (which personas can see this entry)
+- **Grouping** (sidebar/nav section)
+- **Icon** (logical key resolved at render time)
+
+## Key Semantics
+
+**Capability Binding**: Every nav item MUST reference a \`CapabilityRef\` so the host can validate at build time that every navigation surface is backed by a real capability registered with \`surface: 'navigation'\`.
+
+**Persona Visibility**: The \`personaVisibility\` array lists personas allowed to see the entry. An empty array means hidden from all personas.
+
+**Optional Policy**: The \`policy\` field adds an additional gate on top of persona visibility (e.g., require a feature flag or explicit permission).
+
+**Optional Density Hint**: The \`densityHint\` field suggests UI density ('compact' | 'comfortable') applied to the rendered entry.
+
+## Mobile Extension Fields (additive, Phase D.0)
+
+Three optional fields enable native Expo Router navigation without app-level hard-coding:
+
+**\`tabBarIcon?\`**: Logical icon key for native tab bar rendering, separate from the web sidebar \`iconKey\`. When absent the host may fall back to \`iconKey\` or a platform default. Only meaningful on tab-root items (\`parentGroupKey\` absent).
+
+**\`gestureHint?\`** (\`NativeGestureHint\`): Declares the primary gesture affordance for this screen. Use \`'none'\` to explicitly disable back/dismiss gestures (e.g. auditor audit-log where accidental swipe-dismiss would lose evidence context).
+
+**\`parentGroupKey?\`**: Expresses the tab-vs-stack hierarchy. Absent = item IS a tab-bar root. Present = item is a stack-child pushed onto the named tab's navigator and does NOT appear in the tab bar.
+
+Tab/stack hierarchy example:
+- \`cockpit\` → \`parentGroupKey: undefined\` → tab bar root
+- \`work-graph\` → \`parentGroupKey: 'cockpit'\` → stack child under cockpit tab
+- \`inbox\` → \`parentGroupKey: undefined\` → tab bar root
+- \`threads/[id]\` → \`parentGroupKey: 'inbox'\` → stack child under inbox tab
+
+Web shells ignore these fields (absent optional fields produce no effect).
+
+## Usage in NavRegistry
+
+The \`NavRegistry\` consumes \`NavSurfaceItemSpec\` entries and provides:
+- \`indexByPersona(persona)\`: Get all entries visible to a persona
+- \`indexByGroup(groupKey)\`: Get all entries in a nav group
+- \`resolveForRoleMorph(roleMorph, preferences)\`: Resolve visible entries for a role-morph projection (filtered by persona + hidden groups)
+
+## Example
+
+\`\`\`typescript
+const inboxNav = defineNavSurfaceItem({
+  meta: {
+    key: 'inbox',
+    version: '1.0.0',
+    description: 'Inbox navigation entry',
+    goal: 'Direct users to their messages and notifications',
+    context: 'Core workflow entry point for all personas',
+    owners: ['team-platform'],
+    tags: ['core', 'workflow'],
+  },
+  capability: { key: 'inbox.read' },
+  route: { web: '/companyos/inbox', api: '/api/companyos/inbox' },
+  personaVisibility: ['founder_approver', 'operations_manager', 'frontline_staff'],
+  groupKey: 'workflow',
+  iconKey: 'icon.inbox',
+  densityHint: 'comfortable',
+  // Mobile extension fields (optional — web shell ignores these)
+  tabBarIcon: 'tab.inbox',
+  gestureHint: 'swipe-back',
+});
+\`\`\``,kind:"reference",route:"packages/libs/contracts-spec/src/navigation/nav-surface.ts",visibility:"public"}},{id:"osint-v0-capability-matrix",exportName:"OsintCapabilityMatrixDocBlock",sourceModule:"osint/capability-matrix",block:{id:"osint-v0-capability-matrix",title:"OSINT v0 capability and qualification matrix",summary:"Typed delivery truth for OSINT systems, provider surfaces, evidence, blockers, and production qualification.",kind:"reference",visibility:"public",route:"/docs/platform/osint-v0-capability-matrix",tags:["osint","delivery","qualification","providers"],body:`# OSINT v0 capability matrix
+
+The matrix separates implemented behavior, deterministic qualification, live qualification, explicit unsupported vendor surfaces, and external production blockers. Unsupported methods are never simulated, and source or test definitions never count as live receipts.`}},{id:"quality-environment-v1",exportName:"qualityEnvironmentV1DocBlock",sourceModule:"quality/environment",block:{id:"quality-environment-v1",title:"Explicit QA environment dependencies",body:"QualityEnvironmentV1 distinguishes mocked, integrated and deployed test environments. Its digest binds fixtures, required readiness capabilities, a network policy and a bounded setup deadline. Unhandled requests must fail. Runners enforce network policy and verify fixtures before executing any test; environment configuration is never execution authority. Existing quality plans opt in through a digest-bound environment reference.",kind:"reference",route:"/docs/contracts/quality/environment-v1",visibility:"public"}},{id:"self-improving-system-v1",exportName:"selfImprovingSystemV1DocBlock",sourceModule:"self-improving-system/types",block:{id:"self-improving-system-v1",title:"Governed self-improving system V1",body:"Additive contracts bind improvement programs and candidates to immutable goals, budgets, policy, offline and independent evaluation, G01-G25 evidence, shadow and canary comparisons, Connect decisions, Builder receipts, LSSM plans, Runtime Node V2 work orders, observation, rollback, and exact replay. Runtime artifacts may use qualified automation; repository, schema, data-authority, security, and infrastructure changes remain approval-bound and repository work never self-applies.",kind:"reference",route:"packages/libs/contracts-spec/src/self-improving-system/types.ts",visibility:"public"}}]};