# ContractSpec — LLM Guide (Full)

> Aggregated content from all packages. For summary, see /llms

Generated: stable
Packages: 312

---

## @lssm-tech/lib.accessibility

Description: WCAG compliance utilities and validators
Path: packages/libs/accessibility
URL: /llms/lib.accessibility

# @lssm-tech/lib.accessibility

Website: https://contractspec.io

**WCAG compliance utilities and validators.**

## What It Provides

- **Layer**: lib.
- **Consumers**: design-system, example apps.
- Related ContractSpec packages include `@lssm-tech/lib.design-system`, `@lssm-tech/lib.ui-kit`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.design-system`, `@lssm-tech/lib.ui-kit`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.accessibility`

or

`bun add @lssm-tech/lib.accessibility`

## Usage

Import the root entrypoint from `@lssm-tech/lib.accessibility`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/AccessibilityPanel.tsx` is part of the package's public or composition surface.
- `src/AccessibilityProvider.tsx` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/nativewind-env.d.ts` is part of the package's public or composition surface.
- `src/next-route-announcer.tsx` is part of the package's public or composition surface.
- `src/preferences.tsx` is part of the package's public or composition surface.
- `src/styles.css` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./AccessibilityPanel` resolves through `./src/AccessibilityPanel.tsx`.
- Export `./AccessibilityProvider` resolves through `./src/AccessibilityProvider.tsx`.
- Export `./nativewind-env.d` resolves through `./src/nativewind-env.d.ts`.
- Export `./next-route-announcer` resolves through `./src/next-route-announcer.tsx`.
- Export `./preferences` resolves through `./src/preferences.tsx`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- WCAG compliance standards must be preserved; changes affect all UI surfaces.
- Do not weaken or remove existing validators without coordinating with design-system consumers.


---

## @lssm-tech/lib.ai-agent

Description: AI agent orchestration with MCP and tool support
Path: packages/libs/ai-agent
URL: /llms/lib.ai-agent

# @lssm-tech/lib.ai-agent

Website: https://contractspec.io

**Core AI agent runtime for ContractSpec with tool orchestration, MCP integration, session state, memory, and telemetry.**

## What It Provides

- Provides the central agent runtime used by chat, automation, and higher-level orchestration packages.
- Supports tools, sessions, memory, approvals, providers, telemetry, and MCP-aware workflows.
- Acts as the stable public API for agent execution across multiple runtimes and delivery surfaces.
- Consumes agent definitions from `@lssm-tech/lib.contracts-spec/agent`.
- `src/providers/` contains provider integrations and provider-facing adapters.

## Installation

`npm install @lssm-tech/lib.ai-agent`

or

`bun add @lssm-tech/lib.ai-agent`

## Usage

Define agents in `@lssm-tech/lib.contracts-spec/agent`, then run or export them with `@lssm-tech/lib.ai-agent`.

```ts
import { defineAgent } from "@lssm-tech/lib.contracts-spec/agent";
import { createUnifiedAgent } from "@lssm-tech/lib.ai-agent/agent/unified-agent";

const SupportBot = defineAgent({
  meta: {
    key: "support.bot",
    version: "1.0.0",
    description: "Customer support assistant",
    owners: ["support"],
    tags: ["support"],
    stability: "experimental",
  },
  instructions: "Resolve tickets and escalate low-confidence cases.",
  tools: [{ name: "support.resolve" }],
});

const agent = createUnifiedAgent(SupportBot, {
  backend: "ai-sdk",
});
```

Runtime portability stays adapter-first:

- `AgentSpec.runtime` can declare checkpointing, suspend/resume, and approval-gateway capabilities.
- `AgentFactory` and `ContractSpecAgent` accept optional runtime adapter bundles for LangGraph/LangChain-style integrations.
- Session state now persists workflow, thread, trace, checkpoint, and approval metadata for replay-safe resumes.
- Escalation policies can raise approval requests on timeout, tool failure, or confidence thresholds without coupling core contracts to a vendor runtime.

## Architecture

- `src/agent/`, `src/session/`, and `src/memory/` contain the runtime core for execution state and persistence hooks.
- `src/tools/`, `src.providers/`, and `src.interop/` connect providers, tools, and MCP-aware runtime surfaces.
- `src.telemetry/`, `src.approval/`, `src.knowledge/`, and `src.schema/` round out runtime policy and observability surfaces.
- `src/telemetry/economic-evidence.ts` captures safe agent-run usage/cost refs without persisting prompts, messages, or tool payloads.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Large multi-subpath library exporting agent runtime, approval, memory, knowledge, providers, schema, telemetry, tools, and types.
- Export `.` resolves through `./src/index.ts`.
- Export `./agent` resolves through `./src/agent/index.ts`.
- Export `./agent/agent-factory` resolves through `./src/agent/agent-factory.ts`.
- Export `./agent/contract-spec-agent` resolves through `./src/agent/contract-spec-agent.ts`.
- Export `./agent/json-runner` resolves through `./src/agent/json-runner.ts`.
- Export `./agent/unified-agent` resolves through `./src/agent/unified-agent.ts`.
- Export `./approval` resolves through `./src/approval/index.ts`.
- Export `./approval/workflow` resolves through `./src/approval/workflow.ts`.
- Export `./exporters` resolves through `./src/exporters/index.ts`.
- Export `./exporters/claude-agent-exporter` resolves through `./src/exporters/claude-agent-exporter.ts`.
- Export `./telemetry/economic-evidence` resolves through `./src/telemetry/economic-evidence.ts`.
- Additional runtime subpaths are published through `package.json`; keep docs aligned with the manifest.

## Economic Evidence

Agent runs now emit neutral `@lssm-tech/lib.economic-evidence` refs for token usage, provider receipts, model-cost estimates, budget decisions, lifecycle phases, and redaction decisions. Configure `economicEvidence` on `ContractSpecAgent` to attach provider/model/operation/budget context; generated run results and `agent.step.completed` events carry `economicEvidenceRefs`. `UnifiedAgent` forwards AI SDK provider context and creates external-provider run-completion refs. Budget policy blocks only explicit `pre_execution` gates; post-execution overages and pricing-unavailable paths remain reviewable evidence. Prompt text, messages, tool call arguments, and tool outputs remain redacted/reference-only.

## Migration Note

`@lssm-tech/lib.ai-agent` no longer owns the agent-definition contract layer.

- Removed: `@lssm-tech/lib.ai-agent/spec`
- Removed: `@lssm-tech/lib.ai-agent/spec/spec`
- Removed: `@lssm-tech/lib.ai-agent/spec/registry`
- Use `@lssm-tech/lib.contracts-spec/agent` for `AgentSpec`, `AgentToolConfig`,
  `AgentRegistry`, `createAgentRegistry`, and `defineAgent`

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Missing dependencies (thanks to knip).
- Replace eslint+prettier by biomejs to optimize speed.
- Agentic workflows — subagents, memory tools, and next steps.
- Vnext ai-native.
- Backend operations + frontend rendering support.
- Add latest models and align defaults.
- Add first-class agent-run economic evidence capture for usage, cost estimates, provider receipts, and replay-safe redaction refs.

## Notes

- High blast radius — used by multiple bundles and libs.
- Agent definitions are owned by `@lssm-tech/lib.contracts-spec/agent`.
- This package is runtime-focused: execution, exporters, MCP/tool bridges, sessions, memory, approvals, providers, and telemetry.
- MCP transport adapters must stay runtime-agnostic (no Node/browser-specific globals).


---

## @lssm-tech/lib.ai-providers

Description: Unified AI provider abstraction layer
Path: packages/libs/ai-providers
URL: /llms/lib.ai-providers

# @lssm-tech/lib.ai-providers

Website: https://contractspec.io

**Unified AI provider abstraction layer.**

## What It Provides

- **Layer**: lib.
- **Consumers**: ai-agent, content-gen, image-gen, voice.
- Related ContractSpec packages include `@lssm-tech/lib.provider-ranking`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.provider-ranking`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.ai-providers`

or

`bun add @lssm-tech/lib.ai-providers`

## Usage

Import the root entrypoint from `@lssm-tech/lib.ai-providers`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/factory.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/legacy.ts` is part of the package's public or composition surface.
- `src/models.test.ts` is part of the package's public or composition surface.
- `src/models.ts` is part of the package's public or composition surface.
- `src/selector-types.ts` is part of the package's public or composition surface.
- `src/selector.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./economic-evidence` resolves through `./src/economic-evidence.ts`.
- Export `./factory` resolves through `./src/factory.ts`.
- Export `./legacy` resolves through `./src/legacy.ts`.
- Export `./models` resolves through `./src/models.ts`.
- Export `./selector` resolves through `./src/selector.ts`.
- Export `./selector-types` resolves through `./src/selector-types.ts`.
- Export `./types` resolves through `./src/types.ts`.
- Export `./validation` resolves through `./src/validation.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Economic Evidence

`@lssm-tech/lib.ai-providers/economic-evidence` estimates provider token costs from the model catalog and creates neutral economic cost evidence refs. The helper returns reference-only evidence for downstream metering, billing, observability, and replay surfaces; it does not execute invoices, payments, or finance projections.

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add latest models and align defaults.
- Resolve lint, build, and type errors across nine packages.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add AI provider ranking system with ranking-driven model selection.
- Add first-class mistral provider support.
- Add provider/model token cost evidence helpers backed by `@lssm-tech/lib.economic-evidence`.

## Notes

- Provider interface is consumed by all AI-powered libs; breaking changes cascade widely.
- Adding new providers must not break existing factory signatures.


---

## @lssm-tech/lib.analytics

Description: Product analytics and growth metrics
Path: packages/libs/analytics
URL: /llms/lib.analytics

# @lssm-tech/lib.analytics

Website: https://contractspec.io

**Product analytics and growth metrics.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, apps.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.analytics`

or

`bun add @lssm-tech/lib.analytics`

## Usage

Import the root entrypoint from `@lssm-tech/lib.analytics`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/churn` is part of the package's public or composition surface.
- `src/cohort` is part of the package's public or composition surface.
- `src/funnel` is part of the package's public or composition surface.
- `src/growth` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/lifecycle` is part of the package's public or composition surface.
- `src/posthog` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./churn` resolves through `./src/churn/index.ts`.
- Export `./churn/predictor` resolves through `./src/churn/predictor.ts`.
- Export `./cohort` resolves through `./src/cohort/index.ts`.
- Export `./cohort/tracker` resolves through `./src/cohort/tracker.ts`.
- Export `./funnel` resolves through `./src/funnel/index.ts`.
- Export `./funnel/analyzer` resolves through `./src/funnel/analyzer.ts`.
- Export `./growth` resolves through `./src/growth/index.ts`.
- Export `./growth/hypothesis-generator` resolves through `./src/growth/hypothesis-generator.ts`.
- Export `./lifecycle` resolves through `./src/lifecycle/index.ts`.
- The package publishes 16 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Event naming conventions must stay consistent with PostHog taxonomy.
- Metric calculations affect live dashboards; verify formulas before changing.


---

## @lssm-tech/lib.app-submission-readiness-runtime

Description: Pure, deterministic runtime audit engine for mobile app submission readiness (ReviewReady). No network calls; integrations feed it snapshots to audit.
Path: packages/libs/app-submission-readiness-runtime
URL: /llms/lib.app-submission-readiness-runtime

# @lssm-tech/lib.app-submission-readiness-runtime

Pure, deterministic runtime audit engine for mobile app submission readiness
(ReviewReady). It composes on top of the
`@lssm-tech/lib.contracts-spec/app-submission-readiness` contract domain and
provides the fuller audit engine described in the ReviewReady PRD (Phase 2).

## No network calls

This package performs **no** network I/O. Integrations (App Store Connect,
Google Play Developer) are responsible for fetching and handing in submission
snapshots; this runtime only audits the materials it is given. Timestamps and
ids must be supplied by the caller (no `Date.now()` / `Math.random()`).

## Public API

- `normalizeSubmissionInput(materials)` — normalize raw/partial submission
  materials (assets, legal links, privacy disclosures, manifests, SDK inventory,
  reviewer access refs) into a canonical `AppSubmissionReadinessAuditInput`.
- `buildDisclosureMatrix(materials)` — cross-reference SDK collection, manifest
  permissions, privacy-policy declarations, Apple App Privacy answers, and Google
  Data Safety answers; returns a typed matrix with per-cell consistency state and
  evidence refs.
- `runReadinessAudit(materials, policy?)` — orchestrate normalize -> disclosure
  matrix -> findings -> score -> decision into a full report plus matrix and
  per-store checklists. Composes the contracts-spec audit primitive.
- `scoreReadiness(report)` — readiness score wrapper over contracts-spec scoring.
- `buildStoreChecklists(report)` — per-store (Apple / Google Play) ordered
  blocker/warning/improvement checklists.
- `draftRejectionResponse(rejectionMessage, report)` — structured, evidence-cited
  resubmission draft. Avoids legal-advice and approval-guarantee phrasing.
- `redactSubmissionReport(report, policy?)` — canonical redaction entrypoint;
  never serializes raw secret values.

## Fixtures

`@lssm-tech/lib.app-submission-readiness-runtime/fixtures` exports
`SampleSubmissionMaterials` (with a known disclosure inconsistency) and
`ReadySubmissionMaterials` (a passing baseline).


---

## @lssm-tech/lib.assurance-spec

Description: Provider-neutral assurance and compliance evidence correlation contracts for autonomous-company actions.
Path: packages/libs/assurance-spec
URL: /llms/lib.assurance-spec

# `@lssm-tech/lib.assurance-spec`

Provider-neutral assurance and compliance evidence correlation contracts for autonomous-company actions.

This package closes the P1 assurance gap as a **correlation-only** contract/evidence layer. It does not store audit events, query logs, run anomaly detection, execute providers, evaluate policy, or replace ContractSpec Connect.

## Public entrypoints

- `@lssm-tech/lib.assurance-spec`
- `@lssm-tech/lib.assurance-spec/types`
- `@lssm-tech/lib.assurance-spec/fixtures`
- `@lssm-tech/lib.assurance-spec/validation`

## Boundary

Adjacent systems are referenced through branded refs only: audit events, observability telemetry/anomalies, ai-agent model/tool/session receipts, integration calls, CompanyOS work/policy decisions, Connect reviews, orchestration workflows, and infra-ops deployment/incident refs.


---

## @lssm-tech/lib.authos-runtime

Description: Pure deterministic AuthOS runtime projections and security gates over AuthOS contracts.
Path: packages/libs/authos-runtime
URL: /llms/lib.authos-runtime

# `@lssm-tech/lib.authos-runtime`

Pure deterministic AuthOS runtime projections and security gates over `@lssm-tech/lib.authos-spec`.

This package does not authenticate users, call Better Auth, access databases, or execute providers. It converts AuthOS contracts into safe runtime-facing projections for RBAC, RoleMorph, personalization, data-transmission, database/form metadata, Connect with LSSM, redaction, and production IdP readiness.


The runtime also includes a deterministic domain-command persistence helper. It turns approved or approval-required AuthOS command contracts into immutable local runtime events with governance metadata, while returning `canExecute: false` plans so provider, database, and Better Auth execution remains outside this package.

## Subject providers and subject modes

The `./subject` subpath ships the production-grade `SubjectProvider` port implementation consumed by `@lssm-tech/lib.contracts-spec/rich-reference` (S-3) and the per-call subject-mode factories used by the AI-agent surface (S-9):

- `createSubjectProvider({ resolve, cache })` — request-scoped resolver with optional dual-key tenant-scoped LRU cache. Returns `undefined` (deny-closed) when the strategy throws or yields a malformed shape.
- `createDelegatedSubject({ userSession, agentId, signature }, verifier)` — builds an agent-on-behalf-of-user `Subject` with `kind='user'` and `delegationChain=[userId, agentId]` so the audit record carries both identities. Throws on bad signature; `resolveSubjectMode` turns that into a deny-closed `undefined`.
- `createAgentSubject(identity)` — first-class agent identity (`kind='agent'`, no delegation chain).
- `resolveSubjectMode(ctx)` — per-call dispatcher selected by the caller via `ctx.mode`.

The `createHmacDelegationVerifier(secret)` helper produces a server-side HMAC-SHA-256 verifier; secrets must come from the orchestration boundary that issues delegation contracts.


---

## @lssm-tech/lib.authos-spec

Description: Contract-first AuthOS specifications for identity, authentication, federation, and security-gated account surfaces.
Path: packages/libs/authos-spec
URL: /llms/lib.authos-spec

# `@lssm-tech/lib.authos-spec`

Contract-first AuthOS specifications for identity, authentication, account federation, and security-gated account surfaces.

AuthOS V0 deliberately covers a broad identity/auth surface while staying provider-neutral. Runtime execution is delegated to integrations such as Better Auth; this package defines the contracts, fixtures, maturity tags, and semantic validation that other packages must preserve.

## Scope

- identities, accounts, profiles, sessions, credentials, devices, and factors;
- organization, team, admin, invitation, and membership references;
- OAuth/OIDC, SSO/SAML, SCIM, email/phone verification, OTP, magic-link, passkey, one-tap, and MFA descriptors;
- Connect with LSSM account-link federation and LSSM-as-IdP descriptors;
- auth events, audit evidence, maturity tags, semantic validation, and agent domain-command authority contracts.

## Non-goals

- No bespoke auth engine.
- No Better Auth dependency or provider SDK imports.
- No production LSSM-as-IdP enablement without security-review evidence.
- No credential secret serialization in fixtures, errors, events, command payloads, or replay evidence.


## Domain-command authority

Agent-facing AuthOS commands are contracts only: they classify read, draft, approval-required, and reserved-human actions without executing identity, session, credential, organization, or IdP mutations. High-impact commands such as session start, factor verification, LSSM account linking, credential rotation, SSO configuration, organization role changes, and LSSM-as-IdP enablement require explicit approval evidence before any host-owned integration may execute them.

## Public entrypoints

- `@lssm-tech/lib.authos-spec`
- `@lssm-tech/lib.authos-spec/types`
- `@lssm-tech/lib.authos-spec/fixtures`
- `@lssm-tech/lib.authos-spec/validation`


---

## @lssm-tech/lib.billing-france

Description: France-specific BillingOS readiness contracts and deterministic e-invoicing/e-reporting checks.
Path: packages/libs/billing-france
URL: /llms/lib.billing-france

# `@lssm-tech/lib.billing-france`

France-specific BillingOS readiness contracts, deterministic checks, fixtures, exports, and tests.

This package may import country-neutral BillingOS contracts from `@lssm-tech/lib.billing-spec`. The reverse dependency is forbidden: France identifiers, routing, e-invoicing, and e-reporting readiness must not leak into `@lssm-tech/lib.billing-spec` or `@lssm-tech/lib.billing-runtime`.

## Scope

- French SME, ETI, and enterprise fiscal-profile readiness inputs.
- B2B domestic e-invoicing, B2C e-reporting, international e-reporting, public-sector readiness, and out-of-scope flow classification.
- 2026/2027 readiness schedule metadata.
- Factur-X, UBL, and CII format-readiness metadata only; this package does not generate invoice documents.
- PA/PDP/provider routing profiles as deterministic mocks/adapters only.
- Financial data-vault evidence contracts for redaction, retention, extraction confidence, evidence chains, and duplicate candidates.
- Replayable fixtures for package tests and examples.

## Legal engine

The France pack hosts the deterministic legal engine that core/runtime must not contain:

- TVA rate table — 20 / 10 / 5.5 / 2.1 plus exemption, autoliquidation, and intra-EU, each carrying `validFrom`/`validTo` and failing closed on an unknown rate.
- Per-rate-group half-up rounding of tax totals.
- Mandatory-mentions validator for required French invoice legal mentions.
- Gapless numbering scoped to a `Europe/Paris` fiscal period.
- NF203 inalterability hash-chain computed over the canonical invoice bytes.
- Credit-note/avoir derivation with an immutability guard that blocks mutation of issued documents.
- `SirenSiretVatValidationPort` for INSEE/VIES identifier validation (adapter supplied by the host; live INSEE/VIES is a documented follow-up).

## Public entrypoints

- `@lssm-tech/lib.billing-france` — root barrel.
- `@lssm-tech/lib.billing-france/readiness` — France flow, schedule, fiscal identifier, format, and readiness-evidence helpers.
- `@lssm-tech/lib.billing-france/provider` — provider-neutral mock routing profile and readiness contracts.
- `@lssm-tech/lib.billing-france/data-vault` — redacted evidence, retention, extraction, and duplicate-detection contracts.
- `@lssm-tech/lib.billing-france/fixtures` — deterministic fixtures.
- `@lssm-tech/lib.billing-france/types` — grouped type-only surface.
- `@lssm-tech/lib.billing-france/docs` — package boundary doc metadata.

## Non-goals

Readiness and routing metadata are **not** PA accreditation, production PA submission, legal advice, or tax advice. This package contains no provider credentials, network calls, provider SDKs, raw document payload storage, production submission path, or autonomous production billing execution.


---

## @lssm-tech/lib.billing-runtime

Description: Pure backend-neutral BillingOS runtime helpers for deterministic quote-to-cash lifecycle projections.
Path: packages/libs/billing-runtime
URL: /llms/lib.billing-runtime

# `@lssm-tech/lib.billing-runtime`

Pure, backend-neutral BillingOS runtime helpers over `@lssm-tech/lib.billing-spec`.

France readiness metadata is not PA accreditation, production PA submission, legal advice, or tax advice.

## Runtime helpers

`@lssm-tech/lib.billing-runtime` provides pure helper engines over `@lssm-tech/lib.billing-spec`:

- quote/order/invoice/payment/reconciliation lifecycle projections;
- deterministic pricing totals with an injected synchronous tax-calculation port;
- local workflow event creation/appending;
- payment-state reconciliation hints;
- draft accounting export shaping;
- deterministic quote-to-cash cockpit projections with lifecycle, approval-packet, surface, and finance-review handoff metadata; and
- agent planning guards that produce approval packets instead of executing high-impact billing actions.

The package performs no network calls, filesystem access, provider SDK calls, credential handling, persistence writes, PA submission, or autonomous production billing execution.

## Persistence ports (additive)

Backend-neutral port interfaces that a host implements against its store; the package defines the contracts, never the adapters:

- `InvoiceRepositoryPort` — persist and read issued invoices.
- `EventLogAppendPort` — append-only billing workflow event log.
- `InvoiceChainAppendPort` — append entries to the per-period invoice hash-chain.
- `CreditNoteRepositoryPort` — persist and read credit notes (avoir).

## Observability (additive)

- `BillingObservabilityPort` — structured, correlation-id-propagating observability hook for issuance and submission.
- Field-level redaction of SIREN/SIRET/VAT identifiers, secrets, and amounts so no sensitive payload is logged; redaction is applied before any sink receives the record.


---

## @lssm-tech/lib.billing-spec

Description: Country-neutral BillingOS quote-to-cash contracts, invariants, and agent action governance types.
Path: packages/libs/billing-spec
URL: /llms/lib.billing-spec

# `@lssm-tech/lib.billing-spec`

Country-neutral BillingOS contracts for quote-to-cash primitives, lifecycle evidence, policy metadata, and agent-facing operation descriptions.

This package is the canonical core contract surface. It intentionally does **not** contain France-only readiness, PA routing, provider credentials, production submission APIs, persistence adapters, UI, or runtime side effects.

## Scope

Use this package to model reusable BillingOS concepts before choosing a country pack or runtime implementation:

- commercial parties, billing accounts, seller/buyer/vendor/customer roles, and fiscal references;
- catalog, price book, offer, quote, order/commitment, invoice, credit-note, payment, reconciliation, and tax-treatment references;
- workflow/event/audit/source metadata for quote-to-cash replay;
- accounting-export, revenue-memory, connector-profile, financial-data-vault, and product-surface projection contracts when they are country-neutral;
- agent operation catalog and safety metadata for read/draft/recommend/approval-only billing actions;
- role-aware quote-to-cash cockpit packets, persona-to-managed-role bindings, action availability, and evidence references for downstream bundle/app seams.

## Invoice-issuance contracts (additive)

The following additive operation/event contracts describe the France-ready issuance path. They sit alongside the original eight billing contract keys, which are unchanged:

- `billing.invoice.issue` — issue an invoice from a quote/order, producing the canonical invoice record.
- `billing.invoice.submit` — submit an issued invoice to a PDP (Plateforme de Dématérialisation Partenaire) / e-reporting target.
- `billing.invoice.submitted` — event emitted once submission is accepted.
- `billing.creditNote.issue` — issue a credit note (avoir) derived from a prior invoice.

These contracts stay country-neutral: France legal behavior (TVA, mandatory mentions, gapless numbering, NF203, avoir immutability) lives in `@lssm-tech/lib.billing-france`, and Factur-X/EN16931 generation plus PDP submission live in `@lssm-tech/integration.provider-einvoicing`.

## Boundary

BillingOS core remains country-neutral. France e-invoicing/e-reporting readiness lives in `@lssm-tech/lib.billing-france`; deterministic helper behavior lives in `@lssm-tech/lib.billing-runtime`; CompanyOS/operator composition belongs in examples or an explicit module surface.

Core contracts may describe high-impact operations, but they must carry authority/autonomy and operator-approval metadata. They must not represent silent authorized execution.

## Public entrypoints

- `@lssm-tech/lib.billing-spec` — root barrel
- `@lssm-tech/lib.billing-spec/types` — country-neutral BillingOS contract types
- `@lssm-tech/lib.billing-spec/validation` — contract validation helpers
- `@lssm-tech/lib.billing-spec/fixtures` — safe synthetic quote-to-cash cockpit fixtures

## Production-readiness safety boundaries

- No France-specific fields, readiness schedules, PA claims, or provider routing in core.
- No provider credentials, API keys, network calls, filesystem/database adapters, or production billing processor behavior.
- No production PA submission, e-reporting submission, invoice send, mark-paid, refund, write-off, or VAT/tax-treatment mutation without an explicit approval packet.
- No legal advice, tax advice, PA accreditation claim, or full accounting/general-ledger claim.

See `docs/billingos-production-readiness.md` and `docs/billingos-v0-release-verification.md` for prompt coverage, release gates, and remaining non-goals.


---

## @lssm-tech/lib.builder-runtime

Description: Backend-neutral Builder runtime, ingestion, fusion, readiness, and replay services.
Path: packages/libs/builder-runtime
URL: /llms/lib.builder-runtime

# @lssm-tech/lib.builder-runtime

Website: https://contractspec.io

Backend-neutral Builder runtime primitives for source ingestion, omnichannel normalization, fusion, planning, previews, readiness, and replay.

## What It Provides

- In-memory and interface-based Builder stores.
- Omnichannel ingestion pipeline for chat, voice, file, zip, Studio, Telegram, and WhatsApp inputs.
- Specs-pack V0 runtime for safe zip/folder import, deterministic file classification, source refs, analysis, readiness, implementation planning, delivery-loop projection, and Connect-gated task-ledger/apply evidence that fails closed before repository writes.
- The repository canonical Builder v3 specs pack is covered by runtime regression tests so release evidence proves realistic packs stay read-only, traceable, and fail-closed when their structure needs review.
- Pure RoleMorph preview helpers for AirDesk role selectors, policy variant previews, surface inspections, diffs, safe missing-binding suggestions, Workbench packets, preference snapshots, authorization summaries, replay bundles, and assurance/audit evidence checks.
- Deterministic precedence-based fusion and blueprint compilation.
- Execution-lane plan compilation and lightweight execution lifecycle helpers.
- Preview, readiness, replay bundle, automatic economic evidence packet, safe replay sink serialization, and customer-delivery-loop projection helpers.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./builder-intelligence` resolves through `./src/builder-intelligence/index.ts`
- `./stores` resolves through `./src/stores/index.ts`
- `./ingestion` resolves through `./src/ingestion/index.ts`
- `./specs-pack` resolves through `./src/specs-pack/index.ts`
- `./fusion` resolves through `./src/fusion/index.ts`
- `./planning` resolves through `./src/planning/index.ts`
- `./preview` resolves through `./src/preview/index.ts`
- `./rolemorph-preview` resolves through `./src/rolemorph-preview/index.ts`
- `./readiness` resolves through `./src/readiness/index.ts`
- `./replay` resolves through `./src/replay/index.ts`

## Notes

- This package stays backend-neutral. Durable database storage belongs in integration and app layers.
- Channel dispatch is bridged through an injected outbox adapter so Builder can reuse host messaging infrastructure without depending on app shells.
- PDF and OCR extraction are adapter-backed and can be swapped or disabled by hosts.


## Economic Evidence Replay

When all production workflow lanes complete, Builder runtime creates `economicReplayPacket` automatically, including explicit packets for workflows with no child economic refs yet. Consumers should send replay packets to logs or replay indexes through `serializeBuilderWorkflowEconomicEvidencePacketForSink()` from `@lssm-tech/lib.builder-runtime/replay`, which exposes safe packet metadata, child ref counts, allowlisted evidence refs, replay bundle metadata, and redaction decisions without raw provider receipts, prompts, operation payloads, or replay payloads.

## Model routing evidence

Builder runtime consumes the provider-ranking router during plan compilation and carries routing summaries into readiness and replay. The runtime remains backend-neutral: it records selected provider/model, policy, risk flags, reason codes, review requirements, and evidence references, but host runtimes execute the chosen model.

## Contract Intelligence runtime

Builder-runtime exposes the first dry-run Contract Intelligence helpers for fixture-backed brownfield analysis, redacted bundle export/import validation, reconciliation, and selective adoption planning. Apply-capable flows remain blocked until Connect decision and replay evidence exist.
## Builder Intelligence runtime

Builder-runtime exposes pure Builder Intelligence helpers for Phase 1 indexing/retrieval and Phase 2 memory/trajectory projection. `buildBuilderIndex()` creates deterministic `BuilderIndexManifestV1` and `BuilderChunkV1` artifacts from caller-provided refs without writing stores. `queryBuilderIndex()` performs in-memory exact lookup, graph-ref expansion, symbol matching, sparse text scoring, stale filtering, reranking, and `BuilderContextPacketV1` packing with selection reasons. `projectBuilderMemoryItems()`, `createStaleMemoryReport()`, `proposeBuilderMemoryConsolidation()`, and `captureBuilderTrajectory()` keep durable memory review-gated, hash-invalidated, provenance-backed, and free of raw hidden reasoning. Later-phase helpers add draft-only ReasoningBank strategy cards, SONA-lite route explanations, non-authoritative GraphRAG community summaries, and neural-adaptation readiness gates without automatic mutation or training.

## RoleMorph preview runtime

Builder-runtime exposes `./rolemorph-preview` for backend-neutral RoleMorph preview artifacts. The helpers build AirDesk role/policy selector previews, inspect resolved surfaces, diff default versus VIP policy outcomes, produce safe repair suggestions for missing component/data bindings, create Workbench packets, snapshot host-referenced preferences, summarize authorization, assemble replay bundles, and validate branded assurance/audit evidence. They depend on `@lssm-tech/lib.surface-runtime/rolemorph` and `@lssm-tech/lib.builder-spec` only; they do not render React, write stores, call providers, or bypass Connect-gated apply paths.

## Builder customer-delivery-loop runtime

Builder-runtime exposes pure customer-delivery-loop helpers from the root entry point. `createBuilderCustomerDeliveryLoop()` assembles the ref/evidence aggregate, `evaluateBuilderDeliveryReadiness()` projects validation blockers, `projectBuilderDeliveryHandoff()` fails closed until acceptance, release, and customer-handoff evidence exists, and `createBuilderDeliveryReplaySummary()` collects Connect/replay/release refs for audit and release evidence.

The helpers do not write repositories, call providers, persist stores, dispatch messages, or send customer communications. Host apps and integrations own durable storage and production delivery.


---

## @lssm-tech/lib.builder-spec

Description: Builder control-plane contracts, capabilities, and validation for ContractSpec.
Path: packages/libs/builder-spec
URL: /llms/lib.builder-spec

# @lssm-tech/lib.builder-spec

Website: https://contractspec.io

Typed Builder control-plane contracts, capabilities, operations, events, and validation for governed omnichannel authoring.

## What It Provides

- Builder workspace, conversation, source, directive, blueprint, plan, preview, readiness, and export types.
- Specs-pack import, analysis, readiness, implementation-plan, task-ledger, Connect decision, apply receipt, trace, progress, alignment, verifier decision, replay, and customer-delivery-loop types for external product-intent packs.
- RoleMorph preview, surface-inspection, policy-diff, policy-variant, missing-binding repair, Workbench packet, preference snapshot/store-port, authorization summary, replay bundle, and assurance/audit evidence types for adaptive operating surfaces.
- Full Builder command/query/event surface aligned with the Builder layer spec pack.
- Capability specs for chat, voice, ingestion, fusion, planning, preview, harness, and export workflows.
- Validation helpers for runtime and host layers, including fail-closed delivery-loop evidence checks.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./capabilities` resolves through `./src/capabilities/index.ts`
- `./commands` resolves through `./src/commands/index.ts`
- `./events` resolves through `./src/events/index.ts`
- `./queries` resolves through `./src/queries/index.ts`
- `./types` resolves through `./src/types/index.ts`
- `./validation` resolves through `./src/validation/index.ts`

## Notes

- This package is a compatibility surface. Additive evolution is preferred.
- Builder orchestration reuses execution-lane identifiers and harness evidence references instead of introducing a second runtime taxonomy.
- Generated-app runtime channels are out of scope here; this package models the Builder control plane only.


## Builder v2 control-plane records

`@lssm-tech/lib.builder-spec` publicly exports the Builder v2 control-plane alignment records from both the root entry point and `./types`:

- `BuilderIntentDecisionRecord` captures IntentGate ambiguity classification, selected execution lane, escalation decision, and evidence refs before Builder execution proceeds.
- `BuilderToolCapabilityManifest` captures scoped tool availability, supported operations, runtime modes, degraded/blocker state, and evidence refs without depending on a concrete MCP/runtime implementation.
- `BuilderToolActivationReceipt` records why a scoped tool was activated, the permissions actually used, produced evidence, and optional Connect review packet refs.
- `BuilderTaskLedgerEntry` maps Builder-visible task state to leased/running/blocked/completed/stale ledger entries with heartbeat, recovery-rule, and evidence refs.

`BUILDER_V2_CONTROL_PLANE_ARTIFACT_KEYS` lists the canonical artifact keys for these records.

## Contract Intelligence types

Builder-spec now includes additive Contract Intelligence types for contractization reports, portable bundle manifests, selective import decisions, and thin portfolio envelopes. These types are dry-run/advisory surfaces and preserve graph/repo-reality/adoption/replay refs instead of defining a second graph.

## Contract Intelligence contracts

`@lssm-tech/lib.builder-spec` now includes additive Contract Intelligence types for contractization reports, portable bundle manifests, import reconciliation, selective dry-run adoption, portfolio envelopes, vertical patch notes, and recurrent radar reports. These contracts are additive and dry-run oriented.

## Builder Intelligence contracts

`@lssm-tech/lib.builder-spec` now includes additive Builder Intelligence contracts for index manifests, chunks, context packets, durable memory items, trajectories, ReasoningBank-style patterns, SONA-lite routing policies, and stale-memory reports. These contracts are dry-run first: graph refs, source hashes, provenance, `path-only` redaction, review status, and rollback metadata stay authoritative while embeddings, stores, and adaptive routing remain optional later layers.

## RoleMorph preview contracts

`@lssm-tech/lib.builder-spec` includes additive RoleMorph Builder contracts for serializable role selectors, policy variants, surface summaries, inspection packets, surface diffs, safe missing-binding repair suggestions, Workbench panel packets, preference snapshots/store ports, authorization summaries, replay bundles, and branded assurance/audit evidence requirements. These contracts describe Builder preview, inspection, replay, and evidence surfaces; rendering, durable storage, provider calls, and production authorization remain in host/runtime layers.

## Builder customer-delivery-loop contracts

`@lssm-tech/lib.builder-spec` includes additive interface-first delivery-loop contracts for quote/order/acceptance/account/source refs from BillingOS, customer commitment/work/authority/policy-gate refs from CompanyOS, scoped PRD/test-spec/specs-pack artifacts, implementation plans, task ledgers, Connect/replay refs, acceptance evidence, release capsules, and customer-handoff refs. Validators keep commercial amount-like data in BillingOS refs and block execution-approved, verified, or handed-off states until required evidence exists.

These contracts are evidence/ref aggregates only: provider execution, durable storage, repository writes, app shells, and customer sends remain in host/runtime layers.


---

## @lssm-tech/lib.bus

Description: Event bus and messaging primitives
Path: packages/libs/bus
URL: /llms/lib.bus

# @lssm-tech/lib.bus

Website: https://contractspec.io

**Event bus and messaging primitives.**

## What It Provides

- **Layer**: lib.
- **Consumers**: personalization, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.bus`

or

`bun add @lssm-tech/lib.bus`

## Usage

Import the root entrypoint from `@lssm-tech/lib.bus`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/auditableBus.ts` is part of the package's public or composition surface.
- `src/eventBus.ts` is part of the package's public or composition surface.
- `src/filtering.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/inMemoryBus.ts` is part of the package's public or composition surface.
- `src/metadata.ts` is part of the package's public or composition surface.
- `src/subscriber.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./auditableBus` resolves through `./src/auditableBus.ts`.
- Export `./eventBus` resolves through `./src/eventBus.ts`.
- Export `./filtering` resolves through `./src/filtering.ts`.
- Export `./inMemoryBus` resolves through `./src/inMemoryBus.ts`.
- Export `./metadata` resolves through `./src/metadata.ts`.
- Export `./subscriber` resolves through `./src/subscriber.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- `EventBus` interface is a core contract; changes affect all event-driven communication.
- Do not alter the subscriber/publish protocol without coordinating with all consumers.


---

## @lssm-tech/lib.cockpit-kit-native

Description: Native lane for cockpit primitives — React Native implementations with cockpit-kit type contracts
Path: packages/libs/cockpit-kit-native
URL: /llms/lib.cockpit-kit-native

# @lssm-tech/lib.cockpit-kit-native

Native lane (React Native / Expo) for cockpit primitives. Implements the `CockpitFrame`, `NavRail`, `GraphCanvas`, and `MetricPanel` contracts from `@lssm-tech/lib.cockpit-kit` using React Native primitives.

## Overview

```
cockpit-kit-native  →  cockpit-kit  (type contracts + variant unions)
```

Variant unions (`Density`, `Expansion`) are owned by `cockpit-kit` and re-exported here for convenience.

## Usage

```tsx
import { CockpitFrame } from "@lssm-tech/lib.cockpit-kit-native/ui/CockpitFrame";

function MyCockpit() {
  const [active, setActive] = React.useState("dashboard");
  return (
    <CockpitFrame density="comfortable" expansion="expanded">
      <CockpitFrame.Nav>
        {/* NavRailNative goes here */}
      </CockpitFrame.Nav>
      {active === "dashboard" && (
        <CockpitFrame.Screen for="dashboard">
          <DashboardScreen />
        </CockpitFrame.Screen>
      )}
      <CockpitFrame.Footer>
        <StatusBar />
      </CockpitFrame.Footer>
    </CockpitFrame>
  );
}
```

## Subpath exports

| Import | Contents |
|--------|----------|
| `@lssm-tech/lib.cockpit-kit-native` | Type contracts + variant unions |
| `@lssm-tech/lib.cockpit-kit-native/variants` | Density + Expansion re-exports |
| `@lssm-tech/lib.cockpit-kit-native/types` | Prop interface re-exports |
| `@lssm-tech/lib.cockpit-kit-native/ui/CockpitFrame` | Compound layout container |

## Rules

- Do NOT import from `@lssm-tech/lib.personalized-presentation` (cycle prevention)
- Do NOT use web-only APIs (`div`, `className`, `cva`, `clsx`)
- Use `StyleSheet.create` for all styles
- Variant types MUST come from `@lssm-tech/lib.cockpit-kit/variants`


---

## @lssm-tech/lib.cockpit-kit-web

Description: Web lane for cockpit primitives — re-exports cockpit-kit types with web-specific ui/ subpath convention
Path: packages/libs/cockpit-kit-web
URL: /llms/lib.cockpit-kit-web

# @lssm-tech/lib.cockpit-kit-web

Web lane for cockpit UI primitives. Mirrors `@lssm-tech/lib.ui-kit-web` in structure.

## Overview

`cockpit-kit-web` provides the web-specific surface for cockpit primitives, re-exporting type contracts from `@lssm-tech/lib.cockpit-kit` and (in Phase 1) adding React/DOM component implementations.

## Subpath exports

| Import | What you get |
|---|---|
| `@lssm-tech/lib.cockpit-kit-web` | All types + variants |
| `@lssm-tech/lib.cockpit-kit-web/variants` | `Density`, `Expansion` + schema descriptors |
| `@lssm-tech/lib.cockpit-kit-web/types` | Component prop interfaces |

Phase 1 will add:

| Import | What you get |
|---|---|
| `@lssm-tech/lib.cockpit-kit-web/ui/CockpitFrame` | Web CockpitFrame component |
| `@lssm-tech/lib.cockpit-kit-web/ui/NavRail` | Web NavRail component |
| `@lssm-tech/lib.cockpit-kit-web/ui/GraphCanvas` | Web GraphCanvas component |
| `@lssm-tech/lib.cockpit-kit-web/ui/MetricPanel` | Web MetricPanel component |

## Usage

```ts
// Types (scaffold — Phase 1 adds implementations)
import type { CockpitFrameProps } from '@lssm-tech/lib.cockpit-kit-web';

// Canonical variants (owned by cockpit-kit, re-exported here)
import { Density, densityVariantSchema } from '@lssm-tech/lib.cockpit-kit-web/variants';
```

## Dependency rules

- `cockpit-kit-web` depends on `cockpit-kit` — not the reverse
- `Density` and `Expansion` unions are owned by `cockpit-kit`; this package re-exports them
- Do not add native/React Native code here


---

## @lssm-tech/lib.cockpit-kit

Description: Cross-platform type contracts and canonical variant unions for cockpit primitives
Path: packages/libs/cockpit-kit
URL: /llms/lib.cockpit-kit

# @lssm-tech/lib.cockpit-kit

Cross-platform type contracts and canonical variant unions for cockpit UI primitives.

## Overview

`cockpit-kit` is the shared foundation for the four cockpit primitives:

| Primitive | Purpose |
|---|---|
| `CockpitFrame` | Top-level layout shell for the cockpit surface |
| `NavRail` | Vertical navigation sidebar |
| `GraphCanvas` | Dependency/workflow graph view |
| `MetricPanel` | Metric and KPI display panel |

This package ships **type contracts only**. Component implementations land in Phase 1.

## Canonical variant unions

Two variant unions are defined and owned here:

```ts
import { Density, Expansion } from '@lssm-tech/lib.cockpit-kit/variants';

// Density: 'comfortable' | 'compact'
// Expansion: 'collapsed' | 'expanded'
```

**Rule:** `lib.personalized-presentation` imports these FROM here. Never the other way around.

## Subpath exports

| Import | What you get |
|---|---|
| `@lssm-tech/lib.cockpit-kit` | All types + variants |
| `@lssm-tech/lib.cockpit-kit/variants` | `Density`, `Expansion` + schema descriptors |
| `@lssm-tech/lib.cockpit-kit/variants/density` | `Density` only |
| `@lssm-tech/lib.cockpit-kit/variants/expansion` | `Expansion` only |
| `@lssm-tech/lib.cockpit-kit/types` | Component prop interfaces |

## Usage

```ts
import type { CockpitFrameProps, NavRailProps } from '@lssm-tech/lib.cockpit-kit';
import { densityVariantSchema, expansionVariantSchema } from '@lssm-tech/lib.cockpit-kit/variants';
```

## Dependency rules

- This package has **no UI framework dependencies** — it is purely types and constants
- Web-specific implementations live in `@lssm-tech/lib.cockpit-kit-web`
- `lib.personalized-presentation` imports FROM this package, not vice versa


---

## @lssm-tech/lib.communication-runtime

Description: Backend-neutral CommunicationOS runtime, governance, lifecycle, state, ingestion, records, and replay helpers.
Path: packages/libs/communication-runtime
URL: /llms/lib.communication-runtime

# @lssm-tech/lib.communication-runtime

Backend-neutral CommunicationOS runtime for lifecycle validation, governance decisions, in-memory state, ingestion normalization, records, and replay-oriented helpers.

The runtime also exposes `persistAgentCommunicationCommand`, a provider-free
domain-command persistence helper. It turns named CommunicationOS commands (for
example `communication.reply.send`) into immutable in-memory runtime events with
`read_persisted`, `draft_persisted`, or `approval_packet_persisted` status. The
helper records the command plan and approval violations only; it does not send
messages, call providers, open database connections, or mutate external systems.

`createCommunicationCommandInboxItem` projects message-originated commands into
a command inbox item with `canExecute: false`, AIP control refs, persisted event
evidence, and optional CompanyOS bridge review state. Production-send and
high-impact CompanyOS bypass signals fail closed as `blocked`; approval-gated
commands remain evidence packets until an external human/policy path acts.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./governance` resolves through `./src/governance/index.ts`
- `./ingestion` resolves through `./src/ingestion/index.ts`
- `./lifecycle` resolves through `./src/lifecycle/index.ts`
- `./records` resolves through `./src/records/index.ts`
- `./replay` resolves through `./src/replay/index.ts`
- `./state` resolves through `./src/state/index.ts`
- `./runtime` includes domain-command planning and persistence helpers
- `./command-inbox` exposes the fail-closed command inbox projection helper

## Boundary

This package depends on `@lssm-tech/lib.communication-spec` and lower-level libs only. It must not import `@lssm-tech/example.communication-os`, `packages/examples/*`, or module packages.

## Matrix runtime channel

The runtime recognizes `matrix` as a backend-neutral channel type with default send capability and human-review expectations for sensitive replies. Matrix SDK behavior belongs in integration provider packages, not in this runtime package.


---

## @lssm-tech/lib.communication-spec

Description: Canonical communication contracts, operations, events, and validation helpers for ContractSpec.
Path: packages/libs/communication-spec
URL: /llms/lib.communication-spec

# @lssm-tech/lib.communication-spec

Canonical CommunicationOS contracts for threads, messages, participants, reply drafts, handoffs, operations, queries, events, capabilities, and validation helpers.

Domain-command helpers classify agent-callable CommunicationOS actions such as
reply drafting, reply sending, handoff creation, and escalation requests. These
helpers are contract-only: they describe authority, autonomy, approval
requirements, and semantic violations without provider adapters, persistence
drivers, outbound sends, or runtime side effects.

Command-inbox contracts extend domain-command planning with non-executing inbox
items, fail-closed status, AIP control refs, and CompanyOS bridge evidence.
These contracts describe review/approval state only; they do not grant send or
work-execution authority.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./types` resolves through `./src/types/index.ts`
- `./types/domain-command` resolves through `./src/types/domain-command.ts` and includes command-inbox contracts
- `./commands` resolves through `./src/commands/index.ts`
- `./queries` resolves through `./src/queries/index.ts`
- `./events` resolves through `./src/events/index.ts`
- `./capabilities` resolves through `./src/capabilities/index.ts`
- `./validation` resolves through `./src/validation/index.ts`

## Persistence wave

CommunicationOS persistence stays contract-first. `communicationOsSchemaContribution`, `communicationOsPersistencePlans`, and `createCommunicationOsMutationDescriptor` expose portable schema and governed `database.mutation.execute@2.0.0` envelopes for managed/BYOK providers. The domain command reference remains the write authority; provider packages execute SQL/Drizzle outside this spec package. Local/PgLite support is compatibility binding metadata, not an ownership mode.

## Boundary

This package owns canonical communication contracts. Runtime behavior, examples, fixtures, proof/replay, and product composition live in separate packages. Deprecated module shims may re-export this surface for compatibility only.

## Matrix channel

`ChannelTypeEnum` includes `matrix` for deployments that ingest Matrix room events or send governed replies to Matrix rooms. Matrix bridge metadata is owned by integration contracts; this package only owns the canonical channel value.


---

## @lssm-tech/lib.companyos-runtime

Description: Pure CompanyOS V0 runtime helpers for authority, autonomy, inbox routing, and operating review projections.
Path: packages/libs/companyos-runtime
URL: /llms/lib.companyos-runtime

# `@lssm-tech/lib.companyos-runtime`

Pure, backend-neutral CompanyOS runtime helpers for deterministic V0 replay and V1 operating-loop projections.

This package consumes public contracts from `@lssm-tech/lib.companyos-spec` and provides reusable helpers for:

- explaining authority for an action proposal
- classifying autonomy requests into safe policy decisions
- routing approval/reserved-risk decisions into operator inbox items
- summarizing a CompanyOS V0 operating review
- projecting V1 objectives, temporal memory, operating cadence review packets, agent handoffs, execution readiness/dispatch/receipt evidence, correction/outcome receipt linkage, agent-native operation access, surface profile selection, CompanyOS operating graph views, and evidence-backed outcome value reports

## Positioning

Long-term governance/runtime layer behind proofs like CompanyOS VoiceOps.

## Boundary

The runtime package has no providers, I/O, modules, bundles, apps, integrations, or UI. It does not execute actions. It only projects deterministic decisions, packets, selections, dispatch drafts, receipts, inbox items, and summaries over CompanyOS spec objects.

## Public entrypoints

- `@lssm-tech/lib.companyos-runtime` — root barrel
- `@lssm-tech/lib.companyos-runtime/authority` — authority explanation helpers
- `@lssm-tech/lib.companyos-runtime/autonomy` — autonomy classification helpers
- `@lssm-tech/lib.companyos-runtime/inbox` — operator inbox routing helpers
- `@lssm-tech/lib.companyos-runtime/review` — operating review summarization helpers
- `@lssm-tech/lib.companyos-runtime/objectives` — V1 objective health and drift projections
- `@lssm-tech/lib.companyos-runtime/memory` — V1 temporal memory snapshot projections
- `@lssm-tech/lib.companyos-runtime/cadence` — V1 operating cadence review packet builders
- `@lssm-tech/lib.companyos-runtime/execution` — V1 execution readiness, dispatch draft, policy-gate, receipt, and inbox projections
- `@lssm-tech/lib.companyos-runtime/execution-receipts` — deterministic execution receipt summaries and correction/outcome linkage projections
- `@lssm-tech/lib.companyos-runtime/agent-org` — V1 agent delegation and handoff planners
- `@lssm-tech/lib.companyos-runtime/operations` — V1 agent-native operation access classifiers
- `@lssm-tech/lib.companyos-runtime/surfaces` — V1 dynamic surface profile selectors
- `@lssm-tech/lib.companyos-runtime/operating-graph` — deterministic graph snapshot, source-record replay, and idempotent change helpers over CompanyOS spec node kinds
- `@lssm-tech/lib.companyos-runtime/identity-resolution` — cross-source identity candidate and link decision projections
- `@lssm-tech/lib.companyos-runtime/graph-permissions` — actor-bound graph filtering and required-field redaction projections
- `@lssm-tech/lib.companyos-runtime/graph-realtime` — data-transmission-compatible event envelope and replay projections
- `@lssm-tech/lib.companyos-runtime/runbooks` — fail-closed runbook readiness projections for stale, conflicted, unauthorized, or low-confidence graph evidence
- `@lssm-tech/lib.companyos-runtime/substrate-adapters` — thin adapter-shaped projections for AuthOS/RBAC decisions and data-transmission refs
- `@lssm-tech/lib.companyos-runtime/outcome-value-projections` — deterministic business value reports, review queues, readiness signals, sales reports, and prompt/skill influence grouping over ContractSpec outcome claim refs

## Operating graph / AI OS projections

The operating graph helpers consume CompanyOS spec-compatible node kinds and stay provider-free. They preserve source-record evidence during realtime replay, bind permission decisions to the requesting actor, and union required redactions before returning graph fields. Permissioned graph query projections filter requested nodes, deny or redline unsafe nodes before agent use, and expose only redacted fields plus evidence refs. Runbook conformance helpers derive pass/fail evidence from procedures, readiness records, and conformance cases without provider execution. Examples should call these runtime helpers and keep deterministic sandbox adapters only at execution boundaries.

## Outcome value projections

`projectBusinessValueReport` and `projectSalesValueReport` consume structural ContractSpec outcome claim data without owning the generic claim schema. Claims with no evidence are excluded, low-confidence/high-impact/unreviewed claims enter the review queue, corrections reduce readiness, and prompt/skill attribution groups are reported as correlation unless upstream claims explicitly prove causality. The helpers are deterministic and side-effect-free.

## Safety model

Authority and autonomy remain separate. Authority explains whether a principal has a matching capability grant and accountable owner path. Autonomy classifies how far a proposed operation may proceed. Customer-facing, approval-required, and reserved-human-only operations are never escalated to autonomous execution by this package. Execution helpers preserve policy-gate verdicts and only return dispatch drafts or operator inbox projections.

## Policy Runtime Projections

`@lssm-tech/lib.companyos-runtime/policy-runtime` provides pure fail-closed projections for CompanyOS policy evaluation packets: readiness, missing evidence, next operator action, reserved-human-only enforcement, dry-run-before-execute state, assurance coverage, and fallback/failure explanations.

These helpers are deterministic and side-effect-free. They do not call providers, storage, queues, modules, or adapters.


---

## @lssm-tech/lib.companyos-spec

Description: Contract-first CompanyOS V0/V1 specifications for bounded company operations.
Path: packages/libs/companyos-spec
URL: /llms/lib.companyos-spec

# `@lssm-tech/lib.companyos-spec`

## VoiceOps governed-action scenario

CompanyOS VoiceOps is represented as a governed-action scenario, not as a provider runtime. The canonical Voice-to-Product-Gap path starts from CommunicationOS voice/transcript evidence, redacts customer identifiers, proposes an internal product-gap work item, blocks the next-day customer promise, routes PM approval for internal work, and emits replay/receipt material with no production-write claim.

This package owns the CompanyOS side of that story: action origin, authority explanation, policy verdict, approval gate, governed-action lifecycle, replay trace, and evidence receipt material. CommunicationOS owns the source thread/transcript evidence and proposed-action extraction. Provider STT/TTS adapters, live customer sends, CRM writes, and compliance claims stay outside the spec boundary.

Canonical CompanyOS V0 contracts for ContractSpec.

CompanyOS models company operations as explicit, inspectable, and bounded contracts:

- company identity and operating model
- authority, roles, principals, and accountable owners
- autonomy policies and approval boundaries
- company brain entries and knowledge gaps
- decisions, commitments, work items, and graph edges
- provider-agnostic operating connector capabilities
- operator inbox items and operating review summaries

## Positioning

Long-term governance/runtime layer behind proofs like CompanyOS VoiceOps.

## V0 scope

This package intentionally implements contracts only. It does not include runtime execution, real providers, UI, app shells, modules, or autonomous customer sends.

The V0 fixture proves one deterministic loop:

```txt
customer onboarding-confusion conversation
-> product feedback item
-> customer commitment
-> company brain entry / knowledge gap
-> work graph decision/work item/edges
-> ContractSpec proposal reference
-> agent action proposal
-> autonomy policy decision
-> operator inbox item
-> operating review summary
```

## V1 operating loop

The additive V1 surface extends the V0 loop with contract-only operating review primitives:

- objectives, metrics, observations, outcomes, and drift signals
- temporal company memory snapshots, facts, procedures, policies, and supersession refs
- operating cadence specs, review input sets, and review output plans
- bounded agent organization: roles, teams, delegation rules, handoff policies, conflict resolution policies, and tool assignments
- agent-native operation/tool descriptors with dry-run and approval semantics
- dynamic surface profiles for role, locale, risk, data-density, and guidance-mode descriptors
- execution lifecycle, claim/lease, idempotency, policy-gate envelope, dispatch, receipt, checkpoint/replay, and outcome descriptors

V1 remains provider-free and side-effect-free. It describes executable work semantics and evidence, but does not execute those operations.

## Operating graph / AI OS contracts

The additive operating graph surface keeps Company Brain semantics inside CompanyOS without creating a separate package. It includes contract-only schemas for:

- source systems and source record refs with evidence, freshness, ACL, and Knowledge fragment refs
- graph nodes, edges, conflicts, tombstones, supersession, confidence, and review state
- cross-source identity candidates and reviewed link decisions
- actor/session/source ACL/policy permission requests, decisions, and redactions
- data-transmission-compatible realtime room refs, idempotent change events, replay cursors
- runbook procedures, readiness checks, and conformance cases that fail closed for stale, unauthorized, conflicted, or low-confidence evidence

The package still does not ingest Knowledge, evaluate AuthOS/RBAC, open realtime transports, execute runbooks, or mutate providers. Those are substrate/runtime responsibilities.

## Agentic Company Brain contract surfaces

The V2 operating graph packet also carries additive agentic Company Brain contracts for compiled, versioned skill/runbook artifacts; source/identity/ACL readiness checks; conformance evidence; and correction/outcome receipts. These surfaces prove that a Company Brain procedure can become an agent-readable artifact only when source records, identity decisions, ACL decisions, freshness, runbook readiness, and conformance evidence are explicit. They remain references and receipts only: no runtime execution, provider SDK, credential material, source mutation, or production write is introduced here.

## Managed CompanyOS contract inventory

The additive managed CompanyOS surface classifies the public contracts and release anchors needed by managed app/API/worker lanes before those lanes depend on them: tenant profiles, managed/BYOK credential refs, workflow correlation, WebSocket job events, runtime health/degraded state, evidence receipts, package export, and docs-release evidence. The contracts remain provider-neutral, use redacted credential refs only, and fail closed when worker/WebSocket/replay/evidence degradation would otherwise be hidden behind green API health.


## Outcome value projection contracts

`@lssm-tech/lib.companyos-spec/types/outcome-value` defines CompanyOS-only business value contracts over ContractSpec outcome claim refs: `BusinessValueEvent`, `OperationalValueClaim`, `BusinessValueReport`, `SalesValueReport`, `ReviewQueue`, `AutonomyReadinessSignal`, and `PromptSkillInfluenceReport`. These contracts do not redefine the generic `OutcomeClaim` kernel. Business meaning stays in CompanyOS, while the source claim, evidence, review, correction, and attribution identity remains a portable ContractSpec claim ref. No evidence means no business value event.

## Public entrypoints

- `@lssm-tech/lib.companyos-spec` — root barrel
- `@lssm-tech/lib.companyos-spec/types` — schemas and inferred types
- `@lssm-tech/lib.companyos-spec/validation` — validation helpers
- `@lssm-tech/lib.companyos-spec/fixtures` — deterministic V0 fixture
- `@lssm-tech/lib.companyos-spec/docs` — documentation-facing DocBlocks

- `@lssm-tech/lib.companyos-spec/types/operating-graph` — operating graph, identity, permission, realtime, and runbook schemas
- `@lssm-tech/lib.companyos-spec/fixtures/v2-operating-graph` — deterministic operating graph fixture
- `@lssm-tech/lib.companyos-spec/validation/semantic-operating-graph` — semantic validation for graph refs, fail-closed runbook readiness, compiled agentic artifacts, readiness checks, conformance evidence, and correction receipts
- `@lssm-tech/lib.companyos-spec/docs/companyos-operating-graph.docblock` — documentation-facing operating graph DocBlock

- `@lssm-tech/lib.companyos-spec/types/v1` — V1 operating loop schema/type
- `@lssm-tech/lib.companyos-spec/types/objectives` — objective and metric contracts
- `@lssm-tech/lib.companyos-spec/types/memory` — temporal memory contracts
- `@lssm-tech/lib.companyos-spec/types/cadence` — operating cadence contracts
- `@lssm-tech/lib.companyos-spec/types/agent-org` — bounded agent organization contracts
- `@lssm-tech/lib.companyos-spec/types/agent-interfaces` — agent-native operation descriptors
- `@lssm-tech/lib.companyos-spec/types/agentic-contracts` — compiled skill/runbook artifacts, agentic readiness, conformance evidence, and correction/outcome receipt contracts
- `@lssm-tech/lib.companyos-spec/types/dynamic-surfaces` — dynamic surface profile descriptors
- `@lssm-tech/lib.companyos-spec/types/execution` — execution lifecycle, policy-gate envelope, dispatch, receipt, and outcome descriptors
- `@lssm-tech/lib.companyos-spec/types/managed-companyos` — managed tenant, integration ownership, workflow correlation, WebSocket, health, evidence receipt, and public-surface inventory contracts
- `@lssm-tech/lib.companyos-spec/types/outcome-value` — CompanyOS business value projection contracts over ContractSpec OutcomeClaim refs
- `@lssm-tech/lib.companyos-spec/fixtures/v1-operating-loop` — deterministic V1 fixture
- `@lssm-tech/lib.companyos-spec/fixtures/v1-execution.parts` — deterministic execution/evidence fixture parts
- `@lssm-tech/lib.companyos-spec/validation/semantic-v1-execution` — semantic validation for execution refs and fail-closed invariants

## Safety model

Authority answers who may act and who is accountable. Autonomy answers how independently the action may proceed. They are related but not interchangeable.

Customer-facing sends, legal/financial changes, and production-impacting work should default to approval-required or reserved-human-only until a future runtime explicitly proves stricter policy gates. V1 agent-native descriptors must require dry-run and approval semantics for execute-capable operations.

Execution descriptors are evidence contracts, not runtime permission. A later CompanyOS module may coordinate agent, job, integration, human, dry-run, or manual-record lanes only after policy-gate evidence, idempotency, claim/lease, approval, and replay requirements are satisfied.

Managed CompanyOS credential refs never carry raw secrets (`secretMaterialAvailable` is contractually false). Managed provider defaults, SDK wiring, procurement, and credential custody claims remain approval-gated outside this spec package.

Dispatch authorization is modeled as an explicit substrate contract. `CompanyOsExecutionDispatchAuthorizationSchema` binds a dispatch lane to a policy-gate decision, accountable owner, approvals, and optional fail-closed `CompanyOsDispatchAuthorizationFailureSchema`. `CompanyOsSourceEvidenceRefSchema` records AIP, command-inbox, dry-run, operator, and outcome provenance with `authorizationAuthority: false`; source evidence can explain a request, but it cannot authorize dispatch. `CompanyOsPolicyReplayPacketSchema`, `CompanyOsReplayDeterminismCaseSchema`, `CompanyOsOperatorInboxRouteSchema`, and `CompanyOsOutcomeLinkageSchema` complete the deterministic replay, operator handoff, and outcome trace without introducing provider or module execution.

## Policy Runtime Hardening

This package now includes additive policy-runtime contracts under `@lssm-tech/lib.companyos-spec/types/policy-runtime`, fixtures under `./fixtures/v1-policy-runtime`, and validation under `./validation/semantic-v1-policy-runtime`.

These contracts extend existing CompanyOS policy gate request/decision semantics with authority, RBAC, risk, budget, tool-scope, dry-run, approval workflow, fallback, explanation, and assurance packet refs. They do not replace autonomy levels, authority graphs, execution plans, receipts, or outcome contracts.


---

## @lssm-tech/lib.content-gen

Description: AI-powered content generation for blog, email, and social
Path: packages/libs/content-gen
URL: /llms/lib.content-gen

# @lssm-tech/lib.content-gen

Website: https://contractspec.io

**AI-powered content generation for blog, email, and social.**

## What It Provides

- **Layer**: lib.
- **Consumers**: image-gen, voice, video-gen, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.content-gen`

or

`bun add @lssm-tech/lib.content-gen`

## Usage

Import the root entrypoint from `@lssm-tech/lib.content-gen`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/generators` is part of the package's public or composition surface.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/seo` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./generators` resolves through `./src/generators/index.ts`.
- Export `./generators/blog` resolves through `./src/generators/blog.ts`.
- Export `./generators/email` resolves through `./src/generators/email.ts`.
- Export `./generators/landing-page` resolves through `./src/generators/landing-page.ts`.
- Export `./generators/social` resolves through `./src/generators/social.ts`.
- Export `./i18n` resolves through `./src/i18n/index.ts`.
- Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`.
- Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`.
- Export `./i18n/catalogs/es` resolves through `./src/i18n/catalogs/es.ts`.
- The package publishes 17 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and test failures across voice, workspace, library, and composio.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add AI provider ranking system with ranking-driven model selection.
- Add full i18n support across all 10 packages (en/fr/es, 460 keys).

## Notes

- Generator interface is shared across media libs (image-gen, voice, video-gen); keep it stable.
- i18n keys must stay in sync with consuming packages.


---

## @lssm-tech/lib.context-storage

Description: Context pack and snapshot storage primitives
Path: packages/libs/context-storage
URL: /llms/lib.context-storage

# @lssm-tech/lib.context-storage

Website: https://contractspec.io

**Context pack and snapshot storage primitives.**

## What It Provides

- **Layer**: lib.
- **Consumers**: module.context-storage.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.context-storage`

or

`bun add @lssm-tech/lib.context-storage`

## Usage

Import the root entrypoint from `@lssm-tech/lib.context-storage`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/in-memory-store.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/store.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./in-memory-store` resolves through `./src/in-memory-store.ts`.
- Export `./store` resolves through `./src/store.ts`.
- Export `./types` resolves through `./src/types.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- `Store` interface is the contract boundary for persistence adapters; do not change its shape without updating all adapters.


---

## @lssm-tech/lib.contracts-integrations

Description: Integration contract definitions for external services
Path: packages/libs/contracts-integrations
URL: /llms/lib.contracts-integrations

# @lssm-tech/lib.contracts-integrations

`@lssm-tech/lib.contracts-integrations` defines provider-agnostic contracts for integration specs, connection/runtime handling, secret resolution, health and telemetry, and capability-level provider interfaces such as LLM, embeddings, vector stores, email, and storage.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.contracts-integrations`

or

`npm install @lssm-tech/lib.contracts-integrations`

## What belongs here

This package owns the contract layer for external integrations:

- Integration spec model and registries.
- Connection, auth, transport, versioning, and BYOK contracts.
- Runtime guards and health/telemetry helpers.
- Secret provider abstraction and secret-provider manager.
- Capability-level provider interfaces such as `LLMProvider` and `VectorStoreProvider`.
- Provider delta contracts for cursor, lease, webhook, replay, dedupe, idempotency, and tombstone state.
- Shipped provider/domain spec registrations.
- Integration connection operations contracts.

Use this package when you need shared integration contracts. Do not use it as the SDK-backed implementation layer or as the integration persistence runtime.

## Core workflows

### Define and register an integration spec

```ts
import {
  defineIntegration,
  IntegrationSpecRegistry,
} from "@lssm-tech/lib.contracts-integrations";

const registry = new IntegrationSpecRegistry();

const spec = defineIntegration({
  meta: {
    key: "payments.example",
    version: 1,
    title: "Example Payments",
    owners: ["@platform.integrations"],
    tags: ["payments"],
    category: "payments",
  },
  supportedModes: ["managed", "byok"],
  capabilities: {
    provides: [{ key: "payments.process" }],
  },
  configSchema: {
    schema: { type: "object" },
  },
  secretSchema: {
    schema: { type: "object" },
  },
});

registry.register(spec);
```

### Consume runtime contracts with secrets and guards

```ts
import {
  IntegrationCallGuard,
} from "@lssm-tech/lib.contracts-integrations/integrations/runtime";
import {
  EnvSecretProvider,
  SecretProviderManager,
} from "@lssm-tech/lib.contracts-integrations/integrations/secrets";

const secretProvider = new SecretProviderManager({
  providers: [
    { provider: new EnvSecretProvider(), priority: 100 },
  ],
});

const guard = new IntegrationCallGuard(secretProvider);

const result = await guard.executeWithGuards(
  "primary-llm",
  "chat",
  {},
  resolvedAppConfig,
  async (connection, secrets) => {
    return llmAdapter.chat(connection, secrets, input);
  }
);
```

Typical flow:

1. Declare an `IntegrationSpec` that describes config, secrets, auth, transport, and version policy.
2. Register specs in an `IntegrationSpecRegistry` or use `createDefaultIntegrationSpecRegistry()`.
3. Bind tenant connections and secret references outside this package.
4. Resolve secrets and execute guarded runtime calls through `IntegrationCallGuard`.

Default shipped provider specs are additive catalog entries. Most providers in
`createDefaultIntegrationSpecRegistry()` advertise both `managed` and `byok`,
while BYOK-only providers carry explicit credential-manifest exemption metadata
for unsupported managed mode. Consumers can still narrow a concrete tenant
connection through app-config slot `allowedModes` or connection ownership mode
validation.

### Publish and query the integration catalog

The production registry is split into two layers:

1. **Static catalog definitions** describe what can appear in an integration
   catalog: shipped integration specs, integration package wrappers, provider
   implementation manifests, and explicit exception records for helper modules
   that are not user-facing integrations.
2. **Tenant overlays** describe runtime state outside this package: catalog
   availability (`available`, `hidden`, `disabled`, or `exception`) and
   connection activation (`not-connected`, `active`, `inactive`, `pending`,
   `disabled`, `error`, or `unknown`).

Keep these layers separate. Static definitions must be deterministic metadata
only; they must not contain tenant connection state, raw credentials, provider
SDK clients, network calls, filesystem discovery, or app/example imports. Apps
and bundles should join catalog definitions with overlays through provider-neutral
view records before rendering or filtering.

When adding a provider:

1. Add or update the `IntegrationSpec` and register it in
   `createDefaultIntegrationSpecRegistry()` when the contracts package owns the
   spec.
2. Add package-local catalog contribution metadata in the implementation package
   when the record represents a provider implementation or package wrapper.
3. Include managed/BYOK support metadata for every user-facing record. If a
   module is helper-only or a mode is unsupported, add an explicit exception
   rationale rather than letting guard checks infer intent.
4. Run the registry completeness guard plus the package tests/typecheck before
   promotion.

The expected verification set for registry changes is:

```bash
bun test packages/libs/contracts-integrations/src/integrations/catalog.test.ts packages/libs/contracts-integrations/src/integrations/providers/providers.test.ts packages/libs/contracts-integrations/src/integrations/providers/provider-modes-coverage.test.ts
bun run --cwd packages/libs/contracts-integrations typecheck
bun scripts/check-integration-registry-completeness.ts
```

### Model provider delta sync state

```ts
import type {
  ProviderDeltaSyncState,
} from "@lssm-tech/lib.contracts-integrations/integrations/providers/provider-delta";

const delta: ProviderDeltaSyncState = {
  lease: {
    holder: "knowledge-sync-worker",
    expiresAt: "2026-04-30T13:00:00.000Z",
    renewalWindowMs: 60_000,
  },
  cursor: {
    cursor: "gmail-history-123",
    watermarkVersion: "history-v1",
  },
  webhookChannel: {
    channelId: "google-channel-1",
    resourceId: "google-resource-1",
    expiresAt: "2026-04-30T14:00:00.000Z",
  },
  providerEventId: "provider-event-1",
  dedupeKey: "gmail:provider-event-1",
  idempotencyKey: "tenant:gmail:provider-event-1",
  replayCheckpoint: {
    checkpointId: "replay-1",
  },
};
```

Delta-aware providers should attach this state before runtime sync starts so callers can renew leases, resume from provider cursors/watermarks, preserve webhook expiry, dedupe provider events, run idempotently, replay from checkpoints, and skip tombstoned source records.

## API map

### Spec model and registries

- `IntegrationSpec`: provider-agnostic contract for a shipped or custom integration.
- `IntegrationSpecRegistry`: registry for integration specs with category-based lookup.
- `defineIntegration`: helper for authoring specs.
- `makeIntegrationSpecKey`: canonical key formatter for spec identity.
- `createDefaultIntegrationSpecRegistry`: registry builder for shipped provider specs.
- `filterByTransport`, `filterByAuthMethod`, `filterVersioned`, `filterByokRotatable`: spec filtering helpers.


### Newly registered AI and web-research providers

- `ai-voice.slng`: SLNG API-key HTTP/WebSocket contract for TTS, STT, and voice-agent infrastructure. Public docs do not currently expose official MCP or OAuth app support.
- `ai-voice.gradium`: Gradium REST/WebSocket contract for realtime TTS/STT. Public docs expose API-key access and Python SDK; no public JS SDK, MCP, or OAuth app surface is documented.
- `ai-voice.fal`: Fal generative-media contract with official `@fal-ai/client`, REST, hosted MCP, queue, realtime, storage, and media capabilities. Public MCP auth is API-key based.
- `web-research.tavily`: Tavily search/extract/crawl/research contract with official `@tavily/core`, REST, local/remote MCP, and OAuth-enabled remote MCP.

### Connections, auth, transport, versioning, and BYOK

- `IntegrationConnection` and `ConnectionStatus`: tenant-bound connection shape and readiness state.
- `IntegrationAuthConfig`, `findAuthConfig`, `supportsAuthMethod`: auth contract and helpers.
- `IntegrationTransportConfig`, `findTransportConfig`, `supportsTransport`: transport contract and helpers.
- `IntegrationVersionPolicy`, `resolveApiVersion`, `getVersionInfo`, `isVersionDeprecated`, `getActiveVersions`: API-version policy helpers.
- `ByokKeyLifecycle` and BYOK metadata/result types: key validation and rotation contracts.
- `IntegrationCredentialManifest` and helpers from `./integrations/credentials`: managed/BYOK credential requirements, env aliases, validation strategy, rotation policy, and compatibility mapping from legacy schemas.

### Runtime, health, and telemetry

- `IntegrationCallGuard`: guarded execution with secret resolution, retries, and telemetry. Exported from `./integrations/runtime`.
- `IntegrationCallResult`, `IntegrationCallError`, `IntegrationTelemetryEvent`: runtime result/telemetry contracts.
- `IntegrationHealthService`: structured health checks and telemetry emission.
- `resolveIntegrationRequestContext`, `resolveAuthMethod`, `DefaultTransportResolver`, and related helpers: runtime resolution utilities.

### Secrets

- `SecretProvider`: provider-agnostic secret backend interface. Exported from `./integrations/secrets/provider`.
- `SecretProviderManager`: priority-ordered composite secret provider. Exported from `./integrations/secrets` or `./integrations/secrets/manager`.
- `SecretProviderError`: structured secret-provider error.
- `parseSecretUri`: parse `provider://path?...` references.
- `normalizeSecretPayload`: normalize text/binary/base64 payloads before writes.

### Operations and provider interfaces

- Integration connection operations: `CreateIntegrationConnection`, `UpdateIntegrationConnection`, `DeleteIntegrationConnection`, `ListIntegrationConnections`, `TestIntegrationConnection`.
- Frequently consumed provider contracts:
  - `LLMProvider`
  - `EmbeddingProvider`
  - `VectorStoreProvider`
  - `EmailInboundProvider`
  - `EmailOutboundProvider`
  - `GoogleDriveProvider`
  - `ObjectStorageProvider`
- Delta-aware provider contracts:
  - `ProviderDeltaSyncState`
  - `ProviderDeltaEnvelope`
  - `isProviderDeltaTombstoned`

## Public surface

The root barrel re-exports common integration contracts from:

- spec and registry helpers
- auth, binding, BYOK, connection, transport, and versioning
- health helpers
- operations contracts
- provider interfaces
- selected domain contracts such as `health`, `meeting-recorder`, and `openbanking`

Runtime and secret-management helpers live under `./integrations/runtime` and `./integrations/secrets*`.

The exhaustive public surface lives under `./integrations/*` in `package.json`.

Use the README as a guide to the main clusters. Use `package.json` as the authoritative export map for all subpaths, including the many provider and domain-specific entrypoints.

## Operational semantics and gotchas

- `IntegrationCallGuard` fails fast when a slot is missing or a connection is not ready.
- `IntegrationCallGuard` defaults to `3` attempts with `250 ms` backoff.
- Retry only happens when `shouldRetry()` returns true; the default implementation looks for a truthy `retryable` field on the error.
- `IntegrationSpec` carries config and secret schemas, but raw secrets live behind `secretRef` and `SecretProvider`.
- `SecretProviderManager` delegates in descending priority order and preserves registration order for ties.
- `resolveApiVersion()` uses connection override first, then policy default.
- `IntegrationHealthService.check()` returns structured results instead of throwing health failures upward.
- Registry filters only match specs that explicitly declare auth methods, transports, version policies, or BYOK support.
- Credential manifests describe required config and secret references per ownership mode; they do not carry raw credential values.
- `ProviderDeltaSyncState` is the shared contract for sync leases, provider cursors/watermarks, webhook channel expiry, replay checkpoints, dedupe/idempotency keys, provider event IDs, and tombstones.
- Gmail and Google Drive specs advertise `provider.delta.watch`; Drive also advertises `knowledge.ingestion.drive`.
- This package defines contracts and shipped spec registrations. SDK-backed implementations live elsewhere.

## When not to use this package

- Do not use it as a provider SDK implementation layer.
- Do not use it as the secret storage backend itself.
- Do not use it as the integration persistence database layer.
- Do not use it as the app-config slot/binding resolver.

## Related packages

- `@lssm-tech/lib.contracts-spec`: upstream spec system consumed by integration contracts and operations.
- `@lssm-tech/lib.schema`: schema types used by operation and config shapes.
- `@lssm-tech/integration.runtime`: runtime composition layer built on top of these contracts.
- `@lssm-tech/integration.providers-impls`: SDK-backed provider implementations for many of these interfaces.
- `@lssm-tech/lib.knowledge`: major consumer of embedding, vector-store, email, storage, and LLM provider interfaces.

## Local commands

- `bun run lint:check`
- `bun run typecheck`
- `bun test`

### Matrix and bridge-aware messaging

`messaging.matrix` models Matrix as an additive managed/BYOK messaging integration. It declares `matrix-js-sdk` as the preferred SDK transport with REST/WebSocket hints, Matrix homeserver and room configuration, bearer token secrets, and optional bridge metadata.

Bridge metadata is descriptive and provider-agnostic: it can explain that Matrix rooms bridge to Slack, Telegram, WhatsApp, Discord, email, SMS, IRC, XMPP, or other channels, but it must not replace direct provider specs when first-party integrations are configured. This package does not provision homeservers, automate hosted provider signup, install bridges, or endorse a hosting provider.


---

## @lssm-tech/lib.contracts-library

Description: (none)
Path: packages/libs/contracts-library
URL: /llms/lib.contracts-library

# @lssm-tech/lib.contracts-library

**Contract definitions for library templates and local runtime.**

## What It Provides

- **Layer**: lib.
- **Consumers**: `bundle.library`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.contracts-library`

or

`bun add @lssm-tech/lib.contracts-library`

## Usage

Import the root entrypoint from `@lssm-tech/lib.contracts-library`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/templates` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./templates` resolves through `./src/templates/index.ts`.
- Export `./templates/messaging` resolves through `./src/templates/messaging.ts`.
- Export `./templates/recipes` resolves through `./src/templates/recipes.ts`.
- Export `./templates/todos` resolves through `./src/templates/todos.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Template contracts define the shape consumed by bundle.library — breaking changes cascade to all template renderers.
- Keep contract schemas additive; avoid removing or renaming fields without a migration path.


---

## @lssm-tech/lib.contracts-runtime-client-react

Description: React runtime adapters for ContractSpec contracts
Path: packages/libs/contracts-runtime-client-react
URL: /llms/lib.contracts-runtime-client-react

# @lssm-tech/lib.contracts-runtime-client-react

**React runtime adapters for ContractSpec contracts.**

## What It Provides

- **Layer**: lib.
- **Consumers**: design-system, presentation-runtime-react, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.contracts-runtime-client-react`

or

`bun add @lssm-tech/lib.contracts-runtime-client-react`

## Usage

Import the root entrypoint from `@lssm-tech/lib.contracts-runtime-client-react`, or choose a documented subpath when you only need one part of the package surface.

The form renderer supports the expanded FormSpec field set: readonly inputs, email, autocomplete, address, phone, date, time, datetime, semantic groups, repeated grouped arrays, grid layout hints, progressive `layout.flow` sections/steps, and text/textarea/email input groups. Drivers are expected to provide dedicated slots for rich widgets plus shadcn/Radix-style `Field*` and optional `InputGroup*` slots. Email fields render through the standard input slot with native email input behavior. When input-group slots are absent, text, email, and textarea fields fall back to plain controls.

Autocomplete fields support local filtering and resolver-backed search. Resolver
calls receive the current query, watched dependency values, field name, and an
`AbortSignal` through the existing resolver args object; stale responses are
ignored and selected remote options remain visible when later searches return a
different result set. Custom autocomplete driver slots can read optional
`loading`, `error`, `emptyText`, `loadingText`, and `errorText` props to expose
async state.

### PWA update checks

`usePwaUpdateChecker` from `@lssm-tech/lib.contracts-runtime-client-react/pwa-update-client` checks the `pwa.update.check` API, exposes required/blocking versus optional update state, supports polling, and delegates actual service worker activation to a host-provided `onApply` callback.

### Adaptive form support

`resolveAdaptiveFormExperience` from `@lssm-tech/lib.contracts-runtime-client-react/adaptive-form` maps `ResolvedAdaptiveExperience` into generic form guidance, density, control, and recovery defaults. It is a lightweight adapter for form renderers and vertical applications that want adaptive behavior without coupling forms to analytics or product-specific labels.

Use the result as an editable runtime recommendation. It should not override permissions, validation, authorization, or business rules.

### Query and mutation hooks

`useContractQuery(envelope, options?)` and `useContractMutation(options?)` are
**thin bindings over the in-house engine** in
[`@lssm-tech/lib.contracts-runtime-core`](../contracts-runtime-core) — no
`@tanstack/*`. Wrap the surface in `ContractDataEngineProvider` with a
`createDataEngine({ transport })`, then:

- `useContractQuery` returns the canonical `QueryState<TData>` verbatim
  (`status`, `fetchStatus`, `data`, `error`, `cacheStatus`, `isStale`,
  `isOffline`, `conflict`, `versionToken`) plus `refetch` — so it flows straight
  into the I/O-free design-system `QueryState` components with zero adapter.
- `useContractMutation` returns the canonical mutation state (`status`, `data`,
  `problem`, `conflictOutcome`, `isPending`) plus `mutate(request, { optimistic? })`.

The engine owns the cache, request dedup, durable offline queue + replay, etag
conflict resolution, optimistic apply/rollback, and recoverable auth-expiry.
This package no longer ships cache-key/storage/policy helpers or a
`./query-client` subpath — they were removed in the data-fetching ecosystem
reset (the engine owns all of it). `parseContractResponse` (structuredContent-first
MCP/GraphQL decode) remains for non-engine response interpretation.

## Architecture

- `src/adaptive-form.ts` is part of the package's public or composition surface.
- `src/drivers` is part of the package's public or composition surface.
- `src/feature-render.ts` is part of the package's public or composition surface.
- `src/form-render.impl.tsx` is part of the package's public or composition surface.
- `src/form-render.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./adaptive-form` resolves through `./src/adaptive-form.ts`.
- Export `./drivers/rn-reusables` resolves through `./src/drivers/rn-reusables.ts`.
- Export `./drivers/shadcn` resolves through `./src/drivers/shadcn.ts`.
- Export `./feature-render` resolves through `./src/feature-render.ts`.
- Export `./form-render` resolves through `./src/form-render.ts`.
- Export `./form-render.impl` resolves through `./src/form-render.impl.tsx`.
- Export `./pwa-update-client` resolves through `./src/pwa-update-client.tsx`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add generic adaptive form experience helpers for runtime guidance defaults.

## Notes

- Driver interface must stay compatible with both shadcn and RN Reusables.
- Form rendering pipeline is a critical path; test thoroughly before changing.


---

## @lssm-tech/lib.contracts-runtime-core

Description: Framework-neutral in-house query/cache/offline engine and Transport port for ContractSpec data fetching
Path: packages/libs/contracts-runtime-core
URL: /llms/lib.contracts-runtime-core

# @lssm-tech/lib.contracts-runtime-core

Framework-neutral, in-house runtime for the canonical ContractSpec
data-fetching protocol. It depends only on
[`@lssm-tech/lib.contracts-spec`](../contracts-spec) — the frozen protocol
primitives (`QueryEnvelope`, `QueryResultEnvelope`, `ContractResult`,
`CacheStatus`, `InvalidationTag`, `ConflictPolicy`, `VersionToken`,
`QueryConsistency`, `QueryState`).

## Scope

This package hosts:

- the `Transport` port (`execute()` + optional `subscribe()` realtime seam),
- the in-house query/cache engine (`createDataEngine`: store, dedup,
  retry/backoff, background revalidation, GC) — **no `@tanstack/*` dependency**,
- the durable offline mutation queue + replay-on-reconnect,
- the conflict-resolver registry (server-wins default, field-merge,
  client-wins, surface, CRDT-via-injection, custom),
- the storage port + shipped platform defaults (IndexedDB `.web` /
  AsyncStorage `.native`),
- the reachability **input** port (the engine never imports `integrations/*`),
- tag-invalidation runtime, observability, persisted-state redaction,
- `economic-evidence-attached` engine events and observability bindings that carry provider-neutral usage/cost/budget/replay/projection refs without importing billing, finance, provider, or analytics SDKs,
- the re-homed `Collaboration*` envelopes (consumed by `integration.crdt-loro`).

## Usage

Native apps can wire durable storage through the published Expo/React Native subpath:

```ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { createAsyncStorage } from "@lssm-tech/lib.contracts-runtime-core/storage/async-storage";

const storage = createAsyncStorage(AsyncStorage);
```

`createDataEngine({ transport })` returns a `DataEngine` exposing
`query`/`getState`/`subscribe`/`invalidateTags`/`refresh`/`emitConflict`/
`mutate`/`drain`/`resume`/`dispose` over one shared cache. The React binding
(`useContractQuery`/`useContractMutation` in
`@lssm-tech/lib.contracts-runtime-client-react`) is thin; this core stays
framework-neutral and is also consumed by the realtime worker and the
provider resolver.

## Local/offline capability mode

`createDataEngine` now owns the semantic local/offline toggle through
`localOffline`. The safe default is `online-only`: online queries and direct
online mutations work, but the engine does not persist local data, serve prior
local data while offline, or enqueue offline mutations.

| Mode | Cache/read behavior | Offline mutations |
| --- | --- | --- |
| `online-only` | No local/offline cache; offline reads return the canonical offline/no-data state. | Disabled; returns `OFFLINE_QUEUE_DISABLED` without queueing. |
| `memory-cache` | Same-engine in-memory cache only; nothing persists across engine instances. | Disabled while offline. |
| `offline-capable` | Uses the supplied storage/cache seams for warm offline reads, queue/replay, conflicts, and maintenance. | Queued and replayed when reachability returns. |

Use the pure resolver when policy comes from env/config/feature flags:

```ts
import {
  createDataEngine,
  createMemoryStorage,
  resolveLocalOfflinePolicy,
} from "@lssm-tech/lib.contracts-runtime-core";

const localOffline = resolveLocalOfflinePolicy({
  env: process.env.CONTRACTSPEC_LOCAL_OFFLINE,
  flag: featureFlags.localOffline,
});

const engine = createDataEngine({
  transport,
  localOffline,
  advanced:
    localOffline.mode === "offline-capable"
      ? { storage: createMemoryStorage() /* use IndexedDB/AsyncStorage in apps */ }
      : undefined,
});
```

`localOffline` is the source of truth. Low-level composition seams now live
under `advanced`; `online-only` rejects `advanced.storage` and
`advanced.cacheStore`, while `advanced.reachability` remains valid in every
mode. `offline-capable` requires an explicit `advanced.storage` so durable
local persistence is never enabled accidentally.


## Economic Evidence Observability

`attachObservability()` consumes `economic-evidence-attached` events automatically. It increments `contracts_runtime_economic_evidence_refs_total` and logs `economic.evidence.attached` with only operation key, latency, ref count, and allowlisted ref fields (`id`, `kind`, optional `source`). Raw provider receipts, prompts, database payloads, replay payloads, and unsafe ref IDs containing PII/secret-shaped values are rejected or dropped before logs consume the event.

## Status

Engine landed (B1a synchronous + B1b offline/conflict). Full WebSocket realtime
delivery on `subscribe()` is a follow-on; the seam is defined and the realtime
worker runs on it. This package absorbed the former
`@lssm-tech/lib.data-transmission-{spec,runtime}` concepts.


---

## @lssm-tech/lib.contracts-runtime-server-graphql

Description: GraphQL server runtime adapters for ContractSpec contracts
Path: packages/libs/contracts-runtime-server-graphql
URL: /llms/lib.contracts-runtime-server-graphql

# @lssm-tech/lib.contracts-runtime-server-graphql

**GraphQL server runtime adapters for ContractSpec contracts.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, apps with GraphQL.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-runtime-server-rest`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-runtime-server-rest`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.contracts-runtime-server-graphql`

or

`bun add @lssm-tech/lib.contracts-runtime-server-graphql`

## Usage

Import the root entrypoint from `@lssm-tech/lib.contracts-runtime-server-graphql`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/graphql-pothos.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./graphql-pothos` resolves through `./src/graphql-pothos.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Pothos builder integration must stay compatible with graphql-core and graphql-prisma.
- Do not introduce direct schema mutations outside the Pothos pipeline.


---

## @lssm-tech/lib.contracts-runtime-server-mcp

Description: MCP server runtime adapters for ContractSpec contracts
Path: packages/libs/contracts-runtime-server-mcp
URL: /llms/lib.contracts-runtime-server-mcp

# @lssm-tech/lib.contracts-runtime-server-mcp

**MCP server runtime adapters for ContractSpec contracts.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, CLI, VS Code extension.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.

## Installation

`npm install @lssm-tech/lib.contracts-runtime-server-mcp`

or

`bun add @lssm-tech/lib.contracts-runtime-server-mcp`

## Usage

Import the root entrypoint from `@lssm-tech/lib.contracts-runtime-server-mcp`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.
- `src/provider-mcp.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./mcp/createMcpServer` resolves through `./src/mcp/createMcpServer.ts`.
- Export `./mcp/mcpTypes` resolves through `./src/mcp/mcpTypes.ts`.
- Export `./mcp/registerPresentations` resolves through `./src/mcp/registerPresentations.ts`.
- Export `./mcp/registerPrompts` resolves through `./src/mcp/registerPrompts.ts`.
- Export `./mcp/registerResources` resolves through `./src/mcp/registerResources.ts`.
- Export `./mcp/registerTools` resolves through `./src/mcp/registerTools.ts`.
- Export `./provider-mcp` resolves through `./src/provider-mcp.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add changesets and apply pending fixes.

## Notes

- MCP protocol compliance is critical; transport layer must stay spec-compliant.
- Do not introduce runtime-specific (Node/browser) dependencies in the transport layer.


---

## @lssm-tech/lib.contracts-runtime-server-rest

Description: REST server runtime adapters for ContractSpec contracts
Path: packages/libs/contracts-runtime-server-rest
URL: /llms/lib.contracts-runtime-server-rest

# @lssm-tech/lib.contracts-runtime-server-rest

**REST server runtime adapters for ContractSpec contracts.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, all REST apps.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.contracts-runtime-server-rest`

or

`bun add @lssm-tech/lib.contracts-runtime-server-rest`

## Usage

Import the root entrypoint from `@lssm-tech/lib.contracts-runtime-server-rest`, or choose a documented subpath when you only need one part of the package surface.

### PWA update checks

`createPwaUpdateCheckHandler` from `@lssm-tech/lib.contracts-runtime-server-rest/pwa-update` turns a manifest resolver into a handler for the `pwa.update.check` contract. It merges app defaults with release overrides and returns `none`, `optional`, or `required` update decisions.

## Architecture

- `src/contracts-adapter-hydration.ts` is part of the package's public or composition surface.
- `src/contracts-adapter-input.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/rest-elysia.ts` is part of the package's public or composition surface.
- `src/rest-express.ts` is part of the package's public or composition surface.
- `src/rest-generic.ts` is part of the package's public or composition surface.
- `src/rest-next-app.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts-adapter-hydration` resolves through `./src/contracts-adapter-hydration.ts`.
- Export `./contracts-adapter-input` resolves through `./src/contracts-adapter-input.ts`.
- Export `./rest-elysia` resolves through `./src/rest-elysia.ts`.
- Export `./rest-express` resolves through `./src/rest-express.ts`.
- Export `./rest-generic` resolves through `./src/rest-generic.ts`.
- Export `./rest-next-app` resolves through `./src/rest-next-app.ts`.
- Export `./rest-next-pages` resolves through `./src/rest-next-pages.ts`.
- Export `./pwa-update` resolves through `./src/pwa-update.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- High blast radius — all REST APIs depend on this package.
- Framework adapters (Elysia, Express, Next.js) must stay independent of each other.
- Do not introduce cross-adapter coupling.


---

## @lssm-tech/lib.contracts-spec

Description: Spec definitions and registries for ContractSpec
Path: packages/libs/contracts-spec
URL: /llms/lib.contracts-spec

# @lssm-tech/lib.contracts-spec

Core contract declarations, registries, and shared execution primitives for ContractSpec.

Website: https://contractspec.io/

## Why this package exists

`@lssm-tech/lib.contracts-spec` is the foundation of the split from `@lssm-tech/lib.contracts`.

It gives you one place to define behavior before implementation:

1. Declare specs (operations, events, forms, resources, policies).
2. Bind handlers.
3. Project the same contracts into REST, GraphQL, MCP, and React runtimes.

This spec-first flow improves determinism, regeneration safety, and multi-surface consistency.

## Package boundary (important)

Use this package for:

- Contract declarations (`defineCommand`, `defineQuery`, `defineEvent`, `defineResourceTemplate`, etc.).
- Agent definition contracts (`defineAgent`, `AgentRegistry`, `AgentSpec`, `AgentToolConfig`).
- Agentpacks dual-variant guidance-unit contracts (`defineAgentpackGuidanceUnit`, `AgentpackGuidanceUnit`) via `@lssm-tech/lib.contracts-spec/agentpacks`.
- Agentic interaction safety contracts via `@lssm-tech/lib.contracts-spec/agentic-interaction`; keep this subpath out of the root barrel so adopters opt into fail-closed AIP mappings explicitly.
- Portable agent-step observability contracts (`AgentStepSpec`, `AgentStepArtifact`, `AgentStepEvidencePointer`, `AgentStepTweakableVariable`, `AgentStepReplayBundleRef`, `AgentStepImprovementProposal`) via `@lssm-tech/lib.contracts-spec/agent-step-observability`; this surface links to evidence/replay/approval owners by ref and never stores raw model chain-of-thought.
- Evidence-backed outcome-claim contracts (`OutcomeClaim`, `ClaimEvidence`, `ClaimReview`, `ClaimCorrection`) via `@lssm-tech/lib.contracts-spec/outcome-claims`; no evidence means no valid claim.
- Marketing page/site narrative contracts (`MarketingSiteContract`, `MarketingPageContract`, `MarketingSectionContract`) via `@lssm-tech/lib.contracts-spec/marketing`; this additive subpath declares route strategy, narrative intent, density budgets, CTAs, evidence refs, and presentation-binding requirements without owning product copy or React rendering.
- Core registries (`OperationSpecRegistry`, `EventRegistry`, `FormRegistry`, `ResourceRegistry`).
- Experimental, versioned graph artifact contracts for contract graphs, codebase graphs, contract-code links, generation plans, drift reports, repair proposals, and provenance.
- Shared execution/runtime-neutral types (`HandlerCtx`, policy decision types, telemetry trigger types).
- Typed success/failure/result contracts (`ContractResult`, `ContractSuccess`, `ContractProblem`, `ContractSpecError`) via `@lssm-tech/lib.contracts-spec/results`.
- Contract installation helpers (`installOp`, `op`, `makeEmit`).

Do not use this package for framework adapters:

- REST adapters -> `@lssm-tech/lib.contracts-runtime-server-rest`
- GraphQL adapters -> `@lssm-tech/lib.contracts-runtime-server-graphql`
- MCP adapters -> `@lssm-tech/lib.contracts-runtime-server-mcp`
- React runtime rendering -> `@lssm-tech/lib.contracts-runtime-client-react`
- Integration provider/secret catalogs -> `@lssm-tech/lib.contracts-integrations`

## Installation

```bash
npm install @lssm-tech/lib.contracts-spec @lssm-tech/lib.schema
# or
bun add @lssm-tech/lib.contracts-spec @lssm-tech/lib.schema
```

## Core concepts

- `defineCommand` / `defineQuery`: typed operation specs with metadata, I/O schema, policy, transport hints, and side effects.
- `@lssm-tech/lib.contracts-spec/marketing`: contract-first marketing-site modeling. Shared validation rejects missing dominant questions, primary intents, CTAs, disclosure strategy, unsupported section kinds, missing presentation bindings, unresolved evidence refs, and over-dense homepage contracts before bundle/app renderers consume them.
- `PolicyRequirement` and `SurfacePolicyRequirement`: additive role/permission/flag/policy-ref requirements for operations, presentations, data views, forms, and knowledge access metadata.
- `defineAgent` + `AgentRegistry`: typed agent-definition contracts that runtime packages execute, export, or adapt.
- `defineAgentpackGuidanceUnit` + `defineAgentpackGuidancePack`: typed agentpacks authoring contracts that require Claude and Codex/GPT variants for meaningful guidance units, map OpenCode to the Codex/GPT variant, and carry Connect parity evidence declarations.
- `OperationSpecRegistry`: registers specs, binds handlers, and executes with validation/policy/event guards.
- `AgentStepSpec` + `AgentStepArtifact`: portable, artifact-first observability for chained agent steps. The contracts expose step specs, structured artifacts, evidence pointers, confidence, review state, tweakable variables, replay refs, diffs, and improvement proposals without exposing raw hidden reasoning.
- `OutcomeClaim`: domain-neutral, reviewable claim kernel for agentic workflow outcomes. Claims require typed subject/source refs, evidence refs, reason, provenance producer/timestamp, review state, and correction history; business projections live outside this package.
- `ContractResult`: canonical success/failure envelope used by operation, workflow, job, API, MCP, GraphQL, and React runtimes while preserving raw-response compatibility for adapters.
- Canonical data-fetching protocol (`@lssm-tech/lib.contracts-spec/query`): one `QueryEnvelope` / `QueryResultEnvelope` / `createQueryKey`, plus `CacheStatus`, `InvalidationTag`, `ConflictPolicy`, `VersionToken`, typed `QueryConsistency`, and the render-ready `QueryState`. These I/O-free primitives are carried unchanged by every transport (REST/MCP/in-memory) and executed by the in-house engine in `@lssm-tech/lib.contracts-runtime-core`. They replace the removed `data-transmission-{spec,runtime}` packages.
- `defineEvent` + `EventRegistry`: typed event contracts and lookup.
- `defineAdaptiveShellSpec` / `defineAdaptiveShellResolution`: additive role-adaptive app-shell contracts for shell regions, navigation, breadcrumbs, layout variants, signals, compatibility posture, fail-closed resolver output, explanations, and invariant evidence.
- `defineResourceTemplate` + `ResourceRegistry`: URI-template-based resource contracts.
- `FormRegistry`: contract-first form declarations consumed by UI runtimes, including readonly, email, password, autocomplete, address, phone, number, percent, currency, date, time, datetime, duration, grouped array authoring, semantic legends/descriptions, grid layout hints, progressive `layout.flow` sections/steps, mobile-safe `responsiveFormColumns(...)`, entity-bound projection/intake guidance, and text/textarea/email input-group addons through `@lssm-tech/lib.contracts-spec/forms`.
- `installOp`: one-call helper to register + bind operation handlers.
- `makeEmit`: typed helper for declared event emission in handlers.

FormSpec autocomplete fields support local option filtering or
resolver-backed search through `resolverKey`, dependency paths, debounce, and
minimum-query metadata. The contract stays transport-neutral: host renderers
provide the resolver/fetcher, and value submission is controlled by
`valueMapping` (`scalar`, `object`, or `pick`).

FormSpec phone fields support first-class country metadata. On a
`kind: "phone"` field, use `input` to choose a single linked input or split
country/national inputs, `output` to store a `PhoneFormValue`, one E.164
string, or split linked paths, and `display`/`country` to control flags,
calling codes, default country, and automatic country detection.

Entity-bound form projections are documented through
`@lssm-tech/lib.contracts-spec/forms/entity-bound`. The guidance keeps
canonical identity on entities, treats quick/full/edit/intake/part forms as
renderable projections, separates permissive capture from strict readiness,
and records skipped fields as completion debt instead of blocking intake.
Use `EdgeSpec` only for true entity-to-entity relations; model form parts
with form-specific binding metadata.

## ReviewReady app-submission-readiness contracts

`@lssm-tech/lib.contracts-spec/app-submission-readiness` is the ReviewReady contract surface for auditing mobile app submissions before Apple App Store or Google Play. It exposes 27 typed operation contracts (project/app identity, asset packs, legal links, Apple App Privacy + Google Data Safety disclosures, iOS/Android manifest snapshots, SDK inventory, reviewer access, store integrations, admin rules, audit run, findings/report queries, and rejection-response drafts) plus 3 domain events (`app-submission.audit-completed`, `app-submission.rule-updated`, `app-submission.integration-connected`).

Resolve operations through `appSubmissionReadinessOperationRegistry` and events through `appSubmissionReadinessEventRegistry` (both keyed by `meta.key`). Invariants: reviewer/provider credentials are secret-ref-only (`secretRefId` / `credentialRef`) and never carry raw secret values; admin rule contracts require `sourceUrl`, `retrievedAt`, `effectiveDate`, and `reviewState`; findings/report contracts carry evidence and provenance; and store fields differentiate `apple-app-store`, `google-play`, or `both`. Additive subpaths: `./app-submission-readiness/{contracts,registry,events,constants,fixtures,runtime,types}`.

## Economic evidence operation seams

Operations may carry optional `economicEvidence` refs for provider-neutral usage, cost, budget, replay, and projection evidence. Database mutation plan/execute contracts also expose optional `economicEvidenceRefs` on input and output envelopes so provider adapters can cite evidence without turning usage/cost facts into BillingOS invoices, FinanceOps advice, payment execution, or provider SDK coupling.

## Outcome claim contracts

`@lssm-tech/lib.contracts-spec/outcome-claims` defines the generic evidence-backed claim kernel for agentic workflows. The package owns only portable refs, evidence, provenance, review state, correction history, validators, and factories; runtime emission belongs in `@lssm-tech/lib.ai-agent`, and business/product value interpretation belongs in CompanyOS packages.

The invariant is **No evidence, no claim**: `outcomeClaimSchema`, `defineOutcomeClaim`, and `validateOutcomeClaim` reject an `OutcomeClaim` when `evidenceRefs` is empty, when `reason` is missing, or when provenance lacks a producer and timestamp. Corrections are append-only records that update review/supersession state without silently rewriting the original claim.

```ts
import { defineOutcomeClaim } from '@lssm-tech/lib.contracts-spec/outcome-claims';

const claim = defineOutcomeClaim({
  id: 'claim.workflow.completed.1',
  claimType: 'workflow.outcome.completed',
  subjectRefs: [{ kind: 'subject', id: 'workspace.acme' }],
  sourceRefs: [{ kind: 'run', id: 'agent-run-1' }],
  evidenceRefs: [{ id: 'evidence.task-history.1', kind: 'artifact', ref: 'fixture://task-history/1' }],
  confidence: 0.82,
  reason: 'The task history shows the workflow completed with linked evidence.',
  provenance: {
    producer: { kind: 'agent-step', id: 'agent-step.summarize-outcome' },
    producedAt: '2026-05-31T10:01:00.000Z',
  },
  review: { state: 'needs-review' },
  corrections: [],
});
```

## Agent-step observability contracts

`@lssm-tech/lib.contracts-spec/agent-step-observability` defines the portable kernel for observing and safely tweaking chained agent workflows. It is intentionally additive and package-boundary aware:

- ContractSpec owns the generic contract types and validators for `AgentStepSpec`, `AgentStepArtifact`, evidence pointers, confidence, review state, tweakable variables, replay refs, artifact diffs, and improvement proposals.
- Runtime execution, telemetry, prompt/tool/model receipts, and approvals remain in `@lssm-tech/lib.ai-agent`.
- Workflow graph lifecycle, step transitions, reruns, and lineage remain in workflow-orchestration packages.
- Durable replay/eval/proof bundles remain in harness and execution-lanes packages; ContractSpec stores `AgentStepReplayBundleRef` and other refs rather than duplicating evidence stores.
- CompanyOS owns manager-facing sales workflow projections, review queues, autonomy readiness, and business value interpretation.

The observability invariant is **artifacts and refs, not raw chain-of-thought**. `validateAgentStepArtifact` rejects known raw-reasoning field names such as `chainOfThought`, `rawReasoning`, `stepReasoningText`, and `contractspec_step_reasoning_text` anywhere inside the artifact payload. Verified confidence additionally requires non-empty evidence pointers and `evidenceComplete=true`.

```ts
import {
  validateAgentStepArtifact,
  type AgentStepArtifact,
} from '@lssm-tech/lib.contracts-spec/agent-step-observability';

const artifact: AgentStepArtifact = {
  id: 'artifact.classify-intent.1',
  stepSpecRef: { kind: 'agent-step-spec', id: 'classify_intent', version: '1.0.0' },
  runRef: { kind: 'run', id: 'sales-agent-run-1' },
  attempt: 1,
  artifactKind: 'sales_intent_classification',
  payload: { data: { intent: 'security_review_request' } },
  summary: 'Classified the prospect reply as a security-review request.',
  createdAt: '2026-05-31T23:02:00.000Z',
  producerRef: { kind: 'agent', id: 'sales_agent' },
  evidencePointers: [
    {
      id: 'evidence.prospect-reply.1',
      kind: 'source_message',
      ref: { kind: 'evidence', id: 'prospect-reply-1' },
      sourcePackage: '@lssm-tech/lib.ai-agent',
      observedAt: '2026-05-31T23:01:00.000Z',
      redaction: { status: 'redacted', reason: 'Prospect PII withheld' },
    },
  ],
  confidence: { level: 'medium', evidenceComplete: true },
  review: { current: 'not_required', history: [] },
  redaction: { status: 'redacted', reason: 'Prospect PII withheld' },
};

validateAgentStepArtifact(artifact);
```

## Adaptive shell contracts

`@lssm-tech/lib.contracts-spec/adaptive-shell` defines the contract/source-of-truth layer for role-adaptive app shells before runtime or UI packages render them. Use it when a bundle or app needs a serializable shell contract that can be validated independently from React, Next.js, provider SDKs, or persistence.

The contract is intentionally additive and platform-neutral:

- `AdaptiveShellSpec` declares regions, navigation nodes, breadcrumbs, layout variants, adaptation signals, required invariants, ontology refs, and compatibility classification.
- `AdaptiveShellResolution` is the resolver view-model contract: selected layout, visible/disabled/suppressed navigation, action availability, graph drilldown targets, applied/suppressed adaptations, explanations, diagnostics, and invariant statuses.
- `validateAdaptiveShellSpec` catches duplicate or unresolved shell refs, missing route/action/graph targets, missing required fail-closed invariants, and breaking compatibility records without migration refs.
- `validateAdaptiveShellResolution` proves runtime output preserves workspace intent, has a RoleMorph resolution ref, keeps unsafe actions unavailable, requires evidence-backed adaptations, and keeps graph drilldown routing owned by the app/router layer.

Required invariants are: RoleMorph first, personalization after policy, fail-closed missing RoleMorph, deny/hidden actions, workspace intent preservation, explanation for every adaptation, router-owned graph drilldown, and deterministic output.

```ts
import {
  defineAdaptiveShellResolution,
  defineAdaptiveShellSpec,
} from '@lssm-tech/lib.contracts-spec/adaptive-shell';

const shell = defineAdaptiveShellSpec({
  id: 'companyos.shell',
  version: '1.0.0',
  surfaceId: 'managed-companyos',
  title: 'Managed CompanyOS shell',
  regions: [{ id: 'nav', kind: 'sidebar', label: 'Navigation', componentRef: 'shell.nav' }],
  navigation: [{ id: 'cockpit', kind: 'route', label: 'Cockpit', href: '/companyos/cockpit', regionRef: 'nav' }],
  layoutVariants: [{ id: 'sidebar', label: 'Sidebar', regionRefs: ['nav'] }],
  signals: [{ id: 'role', kind: 'role', label: 'Role', sourceRef: 'rolemorph.actor' }],
  invariants: [
    'rolemorph-first',
    'personalization-after-policy',
    'fail-closed-missing-rolemorph',
    'deny-hidden-actions',
    'workspace-intent-preserved',
    'explain-every-adaptation',
    'graph-router-owned-drilldown',
    'deterministic-output',
  ].map((kind) => ({ kind, required: true, description: `${kind} invariant` })),
});

defineAdaptiveShellResolution(shell, {
  specId: shell.id,
  surfaceId: shell.surfaceId,
  roleMorphResolutionRef: 'rolemorph.resolution.founder',
  workspaceIntentRef: 'workspace.intent.operating-cockpit',
  layoutVariantRef: 'sidebar',
  regions: [{ regionRef: 'nav', visible: true, componentRef: 'shell.nav' }],
  navigation: [{ navigationNodeRef: 'cockpit', visible: true, safetyLevel: 'safe' }],
  breadcrumbs: [],
  adaptations: [],
  explanations: [],
  invariants: shell.invariants.map((invariant) => ({
    kind: invariant.kind,
    status: 'passed',
    reason: 'Verified by resolver tests.',
    evidenceRefs: ['adaptive-shell.resolver.test'],
  })),
});
```

## Generative Core Graph Artifacts

Generative Core graph artifacts are additive experimental public surfaces. Import them through subpath-scoped exports such as `@lssm-tech/lib.contracts-spec/graph-artifacts` rather than broad root-barrel imports.

Use artifact contracts to describe:

- contract graph nodes/edges and source provenance;
- codebase graph nodes/edges for packages, files, imports, exports, docs, tests, and generated outputs;
- contract-code links with confidence, reason codes, hashes, and missing-ref diagnostics;
- generation plans, drift reports, repair proposals, and Connect evidence refs.

These contracts are runtime-neutral. Workspace analyzers build them, bundle services persist/classify them, and CLI/CI/Builder surfaces consume the schema-versioned JSON. Apply/write workflows remain Connect-gated.

## Typed Results

`@lssm-tech/lib.contracts-spec/results` is the canonical success/failure
surface for operations, workflows, jobs, API adapters, MCP tools, GraphQL
resolvers, and React clients.

Handlers can keep returning raw output for ordinary `OK` results. Use
`contractOk`, `contractAccepted`, `contractQueued`, `contractNoContent`,
`contractPartial`, and `contractFail` when an operation needs explicit status,
headers, retry metadata, warnings, partial problems, or typed error args.

```ts
import {
  contractAccepted,
  createContractError,
  defineResultCatalog,
  failure,
  standardErrors,
  standardSuccess,
  success,
} from "@lssm-tech/lib.contracts-spec/results";

const results = defineResultCatalog({
  success: {
    ...standardSuccess.pick("OK", "CREATED"),
    QUEUED_FOR_REVIEW: success.queued<{ reviewId: string }>(),
  },
  errors: {
    ...standardErrors.pick("UNAUTHENTICATED", "FORBIDDEN"),
    INTENT_NOT_FOUND: failure.notFound<{ intentId: string }>({
      description: "The referenced intent does not exist.",
      gqlCode: "INTENT_NOT_FOUND",
    }),
  },
});
```

`OperationSpecRegistry.executeResult(...)` returns a `ContractResult`.
Legacy `execute(...)` remains compatible: it unwraps success data and throws
`ContractSpecError` on failure. Custom success and failure codes should be
declared in `spec.results` or `io.success`/`io.errors`; undeclared custom
failure codes normalize to `INTERNAL_ERROR`.

Adapter defaults:

- REST/Fetch keeps raw success bodies by default and emits failures as
  `application/problem+json`; set `resultEnvelope: true` for `{ ok, data }`
  success envelopes.
- Next.js can use the injected `NextResponse.json(...)` helper from the REST
  runtime.
- NestJS support is exposed as duck-typed exception filter/interceptor helpers
  without adding `@nestjs/common` as a hard dependency.
- GraphQL keeps field success payloads unchanged by default; enable
  `resultExtensions` to collect success metadata, while failures use
  `extensions.contractspec.problem`.
- MCP tools return normal content for success and `isError: true` with a safe
  problem payload for failures.
- React runtime helpers normalize REST, GraphQL, MCP, workflow, job, and legacy
  error shapes into a `ContractResult`.

Migration note: prefer `ContractSpecError`, `createContractError`, and
`contractFail` over `@lssm-tech/lib.error/AppError`. `@lssm-tech/lib.error`
is kept as a compatibility bridge.


## Experimental graph artifact contracts

The generative-core graph artifact surface is exported through narrow experimental subpaths only; it is not re-exported from the root barrel. Use these versioned contracts for graph, generation-plan, and drift-report DTOs while the analyzer and orchestration layers evolve:

- `@lssm-tech/lib.contracts-spec/graph-artifacts`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/contracts`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/codebase`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/links`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/generation`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/drift`

These schemas are additive and versioned with `contractspec.graph-artifacts.v1` / `1.0.0`; consumers should persist the schema and artifact versions with every generated artifact.

## Validation And Authoring Entry Points

Recent authoring and setup flows use package-level validation APIs directly instead of relying on ad hoc template or registry assumptions.

- `@lssm-tech/lib.contracts-spec/app-config/validation`
  - `validateBlueprint`
  - `validateTenantConfig`
  - `validateResolvedConfig`
  - `assertBlueprintValid`
  - `assertTenantConfigValid`
  - `assertResolvedConfigValid`
- `@lssm-tech/lib.contracts-spec/features/validation`
  - `validateFeatureSpec`
  - `assertFeatureSpecValid`
  - `validateFeatureTargetsV2`
- `@lssm-tech/lib.contracts-spec/themes.validation`
  - `validateThemeSpec`
  - `assertThemeSpecValid`

These entrypoints are the current public surface for workspace setup, CLI scaffolding, CI, and docs to verify `app-config`, `feature`, and `theme` authoring consistently.

## Translation contracts and runtime i18n

`@lssm-tech/lib.contracts-spec/translations` is the canonical translation contract surface. Keep stable bundle identity in `TranslationSpec.meta.key`, keep locale variants in `TranslationSpec.locale`, and use optional metadata such as `defaultLocale`, `supportedLocales`, `fallbacks`, `direction`, `formatter`, `channels`, `audience`, `modality`, `safety`, and `rendering` to describe runtime behavior without making a UI framework canonical. Managed CompanyOS catalogs can declare those metadata blocks at bundle or message granularity so UI IA, CommunicationOS, workflows, LLM prompts, voice scripts, agent responses, redaction, and degraded-copy paths remain contract-authored.

Production translation resolution lives in `@lssm-tech/lib.translation-runtime`. That package consumes `TranslationSpec[]` and provides locale negotiation, BCP 47 canonicalization, fallback chains, override layers, diagnostics, async catalog loading, compiled-message caching, and SSR snapshot serialization. Its default formatter is backed by FormatJS/`intl-messageformat` behind a small `MessageFormatter` abstraction so ContractSpec does not implement a custom ICU parser and can adopt MessageFormat 2 later.

```ts
import { defineTranslation } from "@lssm-tech/lib.contracts-spec/translations";
import { createTranslationRuntime } from "@lssm-tech/lib.translation-runtime";

const messages = defineTranslation({
  meta: {
    key: "commerce.cart.messages",
    version: "1.0.0",
    domain: "commerce",
    owners: ["platform"],
  },
  locale: "en-US",
  defaultLocale: "en-US",
  supportedLocales: ["en-US", "ar-EG", "zh-Hans"],
  channels: ["ui", "agent"],
  audience: { roles: ["operator"], tiers: ["managed"] },
  modality: { primary: "text", supported: ["voice"] },
  safety: {
    classification: "internal",
    containsSensitiveData: true,
    redaction: "mask",
    degradedFallbackKey: "cart.items.degraded",
  },
  rendering: { surface: "web", target: "cart.summary", richText: "plain" },
  messages: {
    "cart.items": {
      value: "{count, plural, =0 {No items} one {One item} other {{count} items}}",
      placeholders: [{ name: "count", type: "plural" }],
      channels: ["ui"],
      rendering: { target: "cart.summary.count" },
    },
    "cart.items.degraded": {
      value: "Cart summary unavailable.",
      safety: { classification: "public", redaction: "none" },
    },
  },
});

const runtime = createTranslationRuntime({
  defaultLocale: "en-US",
  requestedLocales: ["en-US"],
  specs: [messages],
});

runtime.tUnknown("cart.items", { count: 3 }); // "3 items"
```

### Static translation diagnostics

Static catalog diagnostics are exported from `@lssm-tech/lib.contracts-spec/translations/diagnostics` for CI tools and downstream consumers that need reusable checks without depending on the CLI shell.

```ts
import { analyzeTranslationCatalogGroups } from "@lssm-tech/lib.contracts-spec/translations/diagnostics";

const report = analyzeTranslationCatalogGroups([
  {
    packagePath: "packages/libs/example",
    catalogDir: "packages/libs/example/src/i18n/catalogs",
    catalogs: [enMessages, frMessages, esMessages],
    baseLocale: "en",
    expectedLocales: ["en", "fr", "es"],
  },
]);

if (!report.ok) {
  console.error(report.issues);
}
```

The report shape is intentionally CI-friendly: `{ ok, summary, issues }`. Issue codes include missing catalogs/keys, extra keys, blank values, invalid ICU messages, placeholder non-parity, invalid shapes, locale non-parity, duplicate bundle identities, `unsupported_locale_claim` (a catalog's `supportedLocales` declares a locale with no matching catalog in the group), and `manifest_spec_key_missing` (a manifest route entry references a specKey absent from the registered catalog set). Use `validateManifestCatalogDrift(entries, knownSpecKeys)` with a `ManifestRouteEntry[]` list to surface drift between route shard manifests and the registered catalog. The `contractspec i18n check` command is the CLI wrapper around this API, and `.contractsrc.json` can include an optional top-level `i18n` diagnostics block with `catalogGlob`, `baseLocale`, `locales`, `allowExtraKeys`, `checkPlaceholders`, `checkIcu`, and `strict`.

### Migration notes

- Prefer `meta.key: "bundle.messages"` plus `locale: "fr-FR"` over keys like `bundle.messages.fr-FR`.
- Use `channels`, `audience`, `modality`, `safety`, and `rendering` metadata for Managed CompanyOS copy selection and policy-aware rendering; keep values descriptive and non-empty so validation can catch unsafe catalog gaps.
- `createI18nFactory` now supports SSR snapshot/hydration directly via `.snapshot()` / `.hydrationPayload()` on the factory instance and `createI18nFactoryFromHydrationPayload(payload)` for client rehydration — prefer this over the deprecated `createTranslationRuntime` for new integrations.
- `resolveLocaleWithin(supportedLocales, defaultLocale, runtimeLocale?, optionsLocale?)` is exported for callers that resolve locale outside a factory instance.
- `RouteShardManifest` and `defineRouteShardManifest` live in the bundle/app layer (not `contracts-spec`) — the contract layer stays route-agnostic. Use `validateManifestCatalogDrift` to catch drift between manifests and registered catalogs.
- i18next adapter support lives downstream at `@lssm-tech/lib.translation-runtime/i18next`. It projects ContractSpec specs/snapshots to i18next resources and metadata manifests, but ContractSpec specs remain canonical.
- Do not encode locale in i18next namespaces or stable translation keys. Use `TranslationSpec.locale` for the language and `TranslationSpec.meta.key` (or an explicit namespace strategy) for the namespace.
- ICU messages are exported intact for i18next. Configure an ICU-capable i18next format plugin when using i18next to render ContractSpec ICU plural/select/selectordinal messages.
- For SSR, use the factory-stack snapshot/hydration surface (`createI18nFactory` → `.hydrationPayload()` → `createI18nFactoryFromHydrationPayload`). The deprecated `createTranslationRuntime` engine is dead-but-present; its removal is a residual follow-up.
- For React Native, the core runtime uses no DOM APIs; hosts are responsible for locale detection and any required `Intl` polyfills.
- **Optimization wave (Model A — per-request inline payload):** O2+O3 reduce the per-request inline `<script>` hydration payload by ~61% (en: `/` 96.6 KB → 37.8 KB; `/companyos/founder` 93.9 KB → 35.6 KB; fr: ~−60%). Catalogs remain bundled+cached in the JS bundle — this is a per-request inline-HTML reduction, NOT total-transferred-bytes elimination. O4 (`@lssm-tech/lib.translation-runtime/precompile` subpath) adds a build-time ICU AST precompile step and `createIntlMessageFormatter` fast-path for formatter-path latency; no payload size change; factory proof routes are unaffected (they use `{placeholder}` interpolation, no ICU). O5 (`@lssm-tech/tool.i18n-prune`) is a CI audit tool for dead-key drift, not a payload driver. O5b intersection is wired and fail-safe but currently no-op. The ~90% total-bytes win requires Model B (catalog code-splitting); see `.omc/plans/ralplan-translation-catalog-sharding-ssr.md` § "Optimization Wave — ARCHITECTURE DECISION: Model A".

## Agent Definitions

Agent declarations now live in `@lssm-tech/lib.contracts-spec/agent`.

```ts
import { AgentRegistry, defineAgent } from "@lssm-tech/lib.contracts-spec/agent";

const SupportBot = defineAgent({
  meta: {
    key: "support.bot",
    version: "1.0.0",
    description: "Customer support assistant",
    owners: ["support"],
    tags: ["support"],
    stability: "experimental",
  },
  instructions: "Resolve tickets and escalate low-confidence cases.",
  tools: [{ name: "support.resolve" }],
});

const registry = new AgentRegistry().register(SupportBot);
```

Runtime execution, exporters, MCP bridges, and provider adapters stay in
`@lssm-tech/lib.ai-agent`.

## Workspace Config Notes

`@lssm-tech/lib.contracts-spec/workspace-config` now includes first-class setup support for:

- `connect` configuration
- `connect.adoption` configuration for local catalog paths, workspace scan rules, family toggles, and verdict thresholds
- `builder` configuration with `runtimeMode: "managed" | "local" | "hybrid"`
- canonical Builder bootstrap presets:
  - `managed_mvp`
  - `local_daemon_mvp`
  - `hybrid_mvp`
- Builder API fields:
  - `builder.api.baseUrl`
  - `builder.api.controlPlaneTokenEnvVar`
- Builder local runtime fields:
  - `builder.localRuntime.runtimeId`
  - `builder.localRuntime.grantedTo`
  - `builder.localRuntime.providerIds`
- Published typed entrypoints:
  - `@lssm-tech/lib.contracts-spec/workspace-config`
  - `@lssm-tech/lib.contracts-spec/workspace-config/contractsrc-schema`
  - `@lssm-tech/lib.contracts-spec/workspace-config/contractsrc-types`

Those settings are consumed by the shared setup layer used by the CLI, VS Code extension, and JetBrains plugin.

## Current Authoring Workflow

- Use `defineTheme(...)` plus `contractspec create theme` for first-class theme scaffolding; keep `tokens` as the default/light-compatible bag and add `modes.dark.tokens` for dark-mode overlays.
- Theme color tokens may carry `format` metadata such as `oklch`, with CSS color strings passed through to design-system bridges.
- Route `app-config`, `feature`, and `theme` checks through the package-level validators above when building setup, editor, or CI automation.
- Use `connect.adoption` and the broader authoring-target discovery flows when the CLI or editors should prefer existing workspace or ContractSpec surfaces before scaffolding new code.
- Use `knowledge.mutation.evaluateGovernance` when provider-backed knowledge writes need a contracted dry-run, approval, idempotency, audit-evidence, or outbound-send decision surface before runtime mutation.
- Use optional portable database metadata on DataView, FormSpec, PolicySpec, and KnowledgeSpace contracts to describe table/view/entity bindings, lookups, policy evidence, checkpoints, and provenance before wiring runtime adapters. These descriptors stay adapter-neutral; Drizzle/PostgreSQL imports belong in integration, app, tool, or server packages.
- Use `database.mutation.plan` and `database.mutation.execute` descriptors only as governed, domain-command-owned write envelopes. A valid mutation envelope carries actor, tenant, domain command, policy decision, idempotency key, transaction boundary, expected write set, audit event refs, replay ref, and correlation ref before an integration adapter may execute it. `@lssm-tech/lib.contracts-spec` defines the portable contract shape; `@lssm-tech/integration.provider-database/governed-mutation` owns SQL/Drizzle execution.

## Migration Note

If you previously imported agent-definition contracts from
`@lssm-tech/lib.ai-agent/spec`, migrate to:

- `@lssm-tech/lib.contracts-spec/agent`
- `@lssm-tech/lib.contracts-spec/agent/spec`
- `@lssm-tech/lib.contracts-spec/agent/registry`

## Bundle requires alignment

When using `@lssm-tech/lib.surface-runtime`, bundle specs declare required features via `ModuleBundleSpec.requires` (e.g. `{ key: 'ai-chat', version: '1.0.0' }`). These entries should match `FeatureModuleSpec.meta` from `defineFeature`. Register features (e.g. `AiChatFeature` from `@lssm-tech/module.ai-chat`) in a `FeatureRegistry` when validating bundle requirements. The bundle runtime can call `registry.get(key)` to verify each required feature exists before resolution.

## Canonical self-contained examples by contract type

Use these example packages when you want one focused, importable reference per contract layer. `knowledge` and `type` are covered through the exported knowledge bindings/source configs and schema models. `agent` definitions now live directly in this package via `@lssm-tech/lib.contracts-spec/agent`.

- `operation`, `feature`, `example`, `type`: [`@lssm-tech/example.minimal`](../../examples/minimal/README.md)
- `event`, `presentation`, `capability`, `test-spec`: [`@lssm-tech/example.workflow-system`](../../examples/workflow-system/README.md)
- `data-view`: [`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md)
- `visualization`: [`@lssm-tech/example.visualization-showcase`](../../examples/visualization-showcase/README.md)
- `agent`: [`@lssm-tech/example.agent-console`](../../examples/agent-console/README.md)
- `harness-scenario`, `harness-suite`: focused reference [`@lssm-tech/example.harness-lab`](../../examples/harness-lab/README.md) covering sandbox, Playwright, agent-browser, auth refs, and visual evidence; product/business proof [`@lssm-tech/example.agent-console`](../../examples/agent-console/README.md)
- `knowledge`, `knowledge-space`, lightweight `app-config`: [`@lssm-tech/example.knowledge-canon`](../../examples/knowledge-canon/README.md)
- `integration`, `workflow`, integration-oriented `app-config`: [`@lssm-tech/example.integration-stripe`](../../examples/integration-stripe/README.md)
- `policy`, `form`, `translation`: [`@lssm-tech/example.locale-jurisdiction-gate`](../../examples/locale-jurisdiction-gate/README.md)
- `product-intent`: [`@lssm-tech/example.product-intent`](../../examples/product-intent/README.md)
- `experiment`, `theme`: [`@lssm-tech/example.personalization`](../../examples/personalization/README.md)
- `job`: [`@lssm-tech/example.openbanking-powens`](../../examples/openbanking-powens/README.md)
- `migration`: [`@lssm-tech/example.versioned-knowledge-base`](../../examples/versioned-knowledge-base/README.md)
- `telemetry`: [`@lssm-tech/example.pocket-family-office`](../../examples/pocket-family-office/README.md)

## Data table contract example

The canonical data-table example lives in
[`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md)
and starts with a declarative `DataViewSpec` in this package:

DataView filters now distinguish user-editable filters from scoped constraints.
Use `view.filterScope.initial` to seed removable filters and
`view.filterScope.locked` for constraints that always apply but are not
serialized into URL state. Locked filters render as disabled chips by default
so embedded views, such as a category-scoped posts list, stay explainable while
reusing the same base DataView contract.

DataView `source.database` can declare a portable read binding with a source key, table/view/entity ref, field-to-column mapping, pagination, policy refs, and provenance. `DataViewQueryGenerator` preserves the existing operation input and also emits an optional `database.query.readonly` descriptor for provider adapters; it does not emit SQL or import database runtimes.

Table fields and columns can declare `overflow` as `truncate`, `wrap`,
`expand`, `hideColumn`, or `none`. Column overflow overrides field overflow,
and unspecified values use type-aware defaults: markdown wraps, while text,
badges, numbers, currency, percentages, dates, times, durations, and booleans
truncate. `expand` keeps the compact cell but adds the field to row expansion;
`hideColumn` starts the column hidden when column visibility is enabled.

Collection data views (`list`, `grid`, and `table`) can now share production
listing defaults under `view.collection`. Use `collection.viewModes` to declare
which modes a renderer may project between, `collection.pagination.pageSize` to
seed query generation, `collection.toolbar` to describe search/filter/view-mode
controls, `collection.density` for cross-mode spacing defaults, and
`collection.dataDepth` for summary/standard/detailed/exhaustive field
projection. Fields can declare `visibility.minDataDepth` so richer fields are
available to detailed experiences without forking the base spec. The authored
`view.kind` remains the canonical shape; renderers derive alternate collection
projections without mutating the source spec. Table `density` remains supported
as a permanent compatibility alias.

```ts
import { defineDataView } from '@lssm-tech/lib.contracts-spec/data-views';
import { ListDataGridShowcaseRowsQuery } from '@lssm-tech/example.data-grid-showcase/contracts/data-grid-showcase.operation';

export const DataGridShowcaseDataView = defineDataView({
  meta: {
    key: 'examples.data-grid-showcase.table',
    version: '1.0.0',
    entity: 'account',
    title: 'Data Grid Showcase Table',
    description:
      'Declarative DataViewSpec for the ContractSpec table showcase.',
    domain: 'examples',
    owners: ['@platform.core'],
    tags: ['examples', 'table', 'data-grid'],
    stability: 'experimental',
  },
  source: {
    primary: {
      key: ListDataGridShowcaseRowsQuery.meta.key,
      version: ListDataGridShowcaseRowsQuery.meta.version,
    },
  },
  view: {
    kind: 'table',
    collection: {
      viewModes: {
        defaultMode: 'table',
        allowedModes: ['list', 'grid', 'table'],
      },
      pagination: { pageSize: 20 },
      toolbar: {
        search: true,
        viewMode: true,
        filters: true,
        density: true,
        dataDepth: true,
      },
      density: 'comfortable',
      dataDepth: 'standard',
      personalization: {
        enabled: true,
        persist: {
          viewMode: true,
          density: true,
          dataDepth: true,
        },
      },
    },
    executionMode: 'client',
    selection: 'multiple',
    columnVisibility: true,
    columnResizing: true,
    columnPinning: true,
    rowExpansion: {
      fields: ['notes', 'renewalDate', 'lastActivityAt'],
    },
    initialState: {
      pageSize: 4,
      hiddenColumns: ['notes'],
      pinnedColumns: {
        left: ['account'],
      },
      sorting: [{ field: 'arr', desc: true }],
    },
    fields: [
      { key: 'account', label: 'Account', dataPath: 'account', sortable: true },
      { key: 'owner', label: 'Owner', dataPath: 'owner', sortable: true },
      { key: 'status', label: 'Status', dataPath: 'status', sortable: true },
      { key: 'notes', label: 'Notes', dataPath: 'notes', overflow: 'expand' },
    ],
    columns: [
      { field: 'account' },
      { field: 'owner' },
      { field: 'status', overflow: 'truncate' },
      { field: 'notes', overflow: 'hideColumn' },
    ],
  },
});
```

See the live example in `/docs/examples/data-grid-showcase` and the browser sandbox in `/sandbox?template=data-grid-showcase`.

## Full contract inventory (explicit map)

<!-- CONTRACT_INVENTORY:START -->

The package currently exposes **397 total exports** in `package.json`, including the root `.` barrel and **396 subpath exports**. This summary is kept here for high-context navigation and AI grounding.

### 1) Registry-level contract types (semantic model)

From `src/types.ts`, `ContractSpecType` currently includes:

- `agent`
- `app-config`
- `capability`
- `data-view`
- `event`
- `example`
- `experiment`
- `feature`
- `form`
- `harness-scenario`
- `harness-suite`
- `integration`
- `job`
- `knowledge`
- `knowledge-space`
- `migration`
- `operation`
- `policy`
- `presentation`
- `product-intent`
- `telemetry`
- `test-spec`
- `theme`
- `translation`
- `type`
- `visualization`
- `workflow`

### 2) Export/file artifact kinds (suffix-based, subpaths only)

These are the concrete contract artifact kinds visible in package exports:

- `.capability` (17)
- `.feature` (10)
- `.command` (34)
- `.event` (28)
- `.query` (26)
- `.form` (6)
- `.presentation` (6)
- `.dataView` (11)
- `.docs` (0)
- `.contracts` (1)
- `.docblock` (0)

### 3) Category -> kinds matrix

- `acp`: `capability(1)`, `feature(1)`, `command(7)`, `plain(5)`
- `agent`: `capability(1)`, `feature(1)`, `command(3)`, `event(4)`, `query(2)`, `form(1)`, `presentation(1)`, `dataView(1)`, `plain(12)`
- `app-config`: `capability(1)`, `feature(1)`, `contracts(1)`, `plain(9)`
- `capabilities`: `plain(7)`
- `context`: `capability(1)`, `feature(1)`, `command(1)`, `event(1)`, `query(2)`, `form(1)`, `presentation(1)`, `dataView(1)`, `plain(10)`
- `contract-registry`: `plain(3)`
- `control-plane`: `capability(5)`, `feature(1)`, `command(15)`, `event(10)`, `query(8)`, `plain(16)`
- `data-views`: `plain(8)`
- `database`: `capability(1)`, `feature(1)`, `query(4)`, `dataView(1)`, `plain(6)`
- `docs`: `capability(1)`, `feature(1)`, `command(2)`, `event(2)`, `query(2)`, `form(1)`, `presentation(2)`, `dataView(3)`, `plain(15)`
- `events`: `plain(1)`
- `examples`: `plain(6)`
- `experiments`: `plain(3)`
- `features`: `plain(6)`
- `forms`: `form(1)`, `plain(2)`
- `harness`: `capability(4)`, `feature(1)`, `command(3)`, `event(8)`, `query(5)`, `presentation(1)`, `dataView(3)`, `plain(11)`
- `install`: `plain(1)`
- `jobs`: `plain(4)`
- `jsonschema`: `plain(1)`
- `knowledge`: `capability(1)`, `feature(1)`, `plain(12)`
- `llm`: `plain(4)`
- `markdown`: `plain(1)`
- `migrations`: `plain(1)`
- `model-registry`: `plain(1)`
- `onboarding-base`: `plain(1)`
- `openapi`: `plain(1)`
- `operations`: `plain(5)`
- `ownership`: `plain(1)`
- `policy`: `plain(8)`
- `presentations`: `plain(4)`
- `product-intent`: `plain(16)`
- `prompt`: `plain(1)`
- `promptRegistry`: `plain(1)`
- `provider-ranking`: `capability(1)`, `feature(1)`, `command(3)`, `event(3)`, `query(3)`, `form(2)`, `presentation(1)`, `dataView(2)`, `plain(10)`
- `regenerator`: `plain(7)`
- `registry`: `plain(1)`
- `registry-utils`: `plain(1)`
- `release`: `plain(1)`
- `resources`: `plain(1)`
- `schema-to-markdown`: `plain(1)`
- `serialization`: `plain(3)`
- `telemetry`: `plain(4)`
- `tests`: `plain(3)`
- `themes`: `plain(1)`
- `themes.validation`: `plain(1)`
- `translations`: `plain(7)`
- `types`: `plain(1)`
- `utils`: `plain(1)`
- `versioning`: `plain(7)`
- `visualizations`: `plain(4)`
- `workflow`: `plain(14)`
- `workspace-config`: `plain(3)`

### 4) DocBlock coverage map (for AI context retrieval)

DocBlocks are authored as same-file exports in their owner modules and loaded through generated manifests, not standalone `*.docblock` package exports.

The entity-bound forms guidance is available as a package subpath,
`@lssm-tech/lib.contracts-spec/forms/entity-bound`, and as a generated
DocBlock route at `/docs/tech/contracts/forms/entity-bound`.


<!-- CONTRACT_INVENTORY:END -->

## End-to-end quick start

### 1) Define schema models and specs

```ts
import { SchemaModel, ScalarTypeEnum } from "@lssm-tech/lib.schema";
import {
  defineCommand,
  defineEvent,
  defineQuery,
} from "@lssm-tech/lib.contracts-spec";

const WorkspaceInput = new SchemaModel({
  name: "WorkspaceInput",
  fields: {
    workspaceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
  },
});

const WorkspaceOutput = new SchemaModel({
  name: "WorkspaceOutput",
  fields: {
    workspaceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
  },
});

const WorkspaceCreatedPayload = new SchemaModel({
  name: "WorkspaceCreatedPayload",
  fields: {
    workspaceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
  },
});

export const WorkspaceCreated = defineEvent({
  meta: {
    key: "workspace.created",
    version: "1.0.0",
    title: "Workspace created",
    description: "Emitted after a workspace is created.",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["workspace", "event"],
  },
  payload: WorkspaceCreatedPayload,
});

export const GetWorkspace = defineQuery({
  meta: {
    key: "workspace.get",
    version: "1.0.0",
    title: "Get workspace",
    description: "Returns workspace metadata for the current tenant.",
    goal: "Expose read-only workspace state to the UI.",
    context: "Used by dashboard bootstrap.",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["workspace", "query"],
  },
  io: { input: WorkspaceInput, output: WorkspaceOutput },
  policy: { auth: "user" },
});

Operations can also declare stronger policy requirements without replacing the legacy `auth`, `flags`, or `pii` fields:

```ts
export const ReadInvoice = defineQuery({
  // ...meta and io...
  policy: {
    auth: "user",
    permissions: { any: ["invoice.read"] },
    roles: { any: ["billing.viewer", "billing.admin"] },
    fieldPolicies: [
      { field: "internalNotes", actions: ["read"], permissions: ["invoice.notes.read"] },
    ],
  },
});
```

`OperationSpecRegistry.execute()` normalizes those requirements and passes them to `ctx.decide` with subject, resource, tenant/workspace, policy refs, and field-policy context before the handler runs. UI surfaces may reuse the same requirement shape for adaptation, but authoritative enforcement belongs in the runtime decider or server-side RBAC engine.

export const CreateWorkspace = defineCommand({
  meta: {
    key: "workspace.create",
    version: "1.0.0",
    title: "Create workspace",
    description: "Creates a new workspace.",
    goal: "Provision a workspace for a tenant.",
    context: "Triggered by onboarding flows.",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["workspace", "command"],
  },
  io: { input: WorkspaceInput, output: WorkspaceOutput },
  policy: { auth: "admin" },
  sideEffects: {
    emits: [{ ref: WorkspaceCreated.meta, when: "after_create" }] as const,
  },
});
```

### 2) Register specs and bind handlers

```ts
import {
  EventRegistry,
  installOp,
  makeEmit,
  OperationSpecRegistry,
} from "@lssm-tech/lib.contracts-spec";
import {
  CreateWorkspace,
  GetWorkspace,
  WorkspaceCreated,
} from "./workspace.spec";

export const events = new EventRegistry().register(WorkspaceCreated);
export const operations = new OperationSpecRegistry();

installOp(operations, GetWorkspace, async (input) => ({
  workspaceId: input.workspaceId,
  name: "Acme Workspace",
}));

installOp(operations, CreateWorkspace, async (input, ctx) => {
  const result = {
    workspaceId: input.workspaceId,
    name: "Acme Workspace",
  };

  const emit = makeEmit(CreateWorkspace, ctx);
  await emit.ref(WorkspaceCreated, { workspaceId: input.workspaceId });
  return result;
});
```

### 3) Execute from runtime context

```ts
import type { HandlerCtx } from "@lssm-tech/lib.contracts-spec";
import { operations, events } from "./registry";

const ctx: HandlerCtx = {
  actor: "admin",
  channel: "web",
  eventSpecResolver: events,
  eventPublisher: async (envelope) => {
    console.log("published", envelope.key, envelope.version);
  },
};

const output = await operations.execute(
  "workspace.create",
  "1.0.0",
  { workspaceId: "wk_123" },
  ctx
);

console.log(output);
```

## Execution behavior (why this is AI-friendly)

`OperationSpecRegistry.execute(...)` runs predictable steps:

1. Resolve spec/version.
2. Parse input.
3. Apply policy hooks when provided (`ctx.decide`, `ctx.rateLimit`).
4. Guard event emission against declared side effects.
5. Execute handler.
6. Parse output when output is a schema model.
7. Emit telemetry when configured.

This deterministic contract -> runtime flow is a strong base for code generation and AI-driven refactors.

## AI assistant guidance

When writing code:

- Start here when asked to "add a new operation/event/form/resource contract".
- Keep `meta.key` stable and increment versions for behavior changes.
- Define spec first, then bind handler, then expose transport.

When reading code:

- Treat `<meta.key, meta.version>` as the canonical identity.
- Expect one operation contract to project into multiple transports.

## Split migration from deprecated monolith

- `@lssm-tech/lib.contracts` -> `@lssm-tech/lib.contracts-spec`
- `@lssm-tech/lib.contracts/operations/*` -> `@lssm-tech/lib.contracts-spec/operations/*`
- `@lssm-tech/lib.contracts/events` -> `@lssm-tech/lib.contracts-spec/events`
- `@lssm-tech/lib.contracts/resources` -> `@lssm-tech/lib.contracts-spec/resources`
- `@lssm-tech/lib.contracts/forms/*` -> `@lssm-tech/lib.contracts-spec/forms/*`

Runtime packages moved out:

- REST runtime -> `@lssm-tech/lib.contracts-runtime-server-rest`
- GraphQL runtime -> `@lssm-tech/lib.contracts-runtime-server-graphql`
- MCP runtime -> `@lssm-tech/lib.contracts-runtime-server-mcp`
- React runtime -> `@lssm-tech/lib.contracts-runtime-client-react`
- Integration contracts -> `@lssm-tech/lib.contracts-integrations`

## PWA Update Contracts

Use `@lssm-tech/lib.contracts-spec/pwa` to declare app-level PWA update policy and the `pwa.update.check` query. `defaultUpdatePolicy` sets the application behavior, while each release can override it for required/blocking updates or heavily offline-compatible optional updates.

The contract standardizes update decisions and prompt telemetry; host apps still own service worker registration and activation.

## Monorepo environment configuration

Use `@lssm-tech/lib.contracts-spec/workspace-config/environment` to declare logical environment variables for monorepos before framework-specific materialization.

- `EnvironmentVariableDefinition` separates logical keys, sensitivity, lifecycle, allowed surfaces, defaults, value sources, and aliases.
- `AppEnvironmentTarget` maps a logical app/package target to a framework such as Next, Expo, Node, or worker runtimes.
- `EnvVariableAlias` maps one logical variable to concrete names such as `NEXT_PUBLIC_API_URL` or `EXPO_PUBLIC_API_URL`.
- Validation rejects secret/sensitive variables exposed through public client aliases or Next config bundle env.

Raw secrets still belong behind secret references and providers, never in `.contractsrc.json`.


## Ontology-led Company Work Graph

`@lssm-tech/lib.contracts-spec/ontology` is the canonical semantic graph surface for CompanyOS work, surfaces, resources, actors, adaptation, and safety evidence. It is intentionally the semantic spine for graph authoring; existing entity, DataView graph, CompanyOS, control-plane, policy, AI-improvement, RoleMorph, and personalization contracts should project to or from ontology refs instead of defining competing taxonomies.

The Autonomous Work Order proof slice uses six node domains:

- `actor` — human, agent, team, customer, role, permission, and authority-scope nodes.
- `work` — goals, orders, workflows, commands, queries, mutations, decisions, blockers, and outcomes.
- `resource` — specs, documents, records, files, pages, memories, evidence, and external resources.
- `surface` — apps, pages, navigation, menus, panels, DataViews, actions, routes, and feature surfaces.
- `adaptation` — preferences, behavior signals, RoleMorph decisions, adaptive hints, analytics signals, and explanations.
- `safety` — policy decisions, approvals, rejections, audit receipts, redaction, replay, risk, and consent.

High-impact `orders` and `mutates` edges are fail-closed by contract: a committed transition must include a policy decision ref, authority scope ref, actor ref, approval-or-refusal ref, audit receipt ref, redaction status, replay-or-evidence ref, risk tier, and timestamp. Low-risk query/render/adaptation edges may be policy-optional, but they still need to remain audit/evidence-addressable when emitted into the Autonomous Work Order slice.

Migration note: the ontology release is a breaking semantic alignment. Prefer `@lssm-tech/lib.contracts-spec/ontology` and ontology-aware projections for new graph work. Treat older unconstrained CompanyOS graph `type` strings, DataView graph mutation refs without safety requirements, and local RoleMorph/personalization taxonomies as migration targets rather than new authoring patterns.

## Experimental graph artifacts

`@lssm-tech/lib.contracts-spec` exposes additive, versioned graph artifact contracts through narrow subpaths:

- `@lssm-tech/lib.contracts-spec/graph-artifacts`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/contracts`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/codebase`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/links`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/generation`
- `@lssm-tech/lib.contracts-spec/graph-artifacts/drift`

These schemas are experimental public additions for read-only graph inspection, generation planning, drift reporting, and future Connect-gated repair workflows. They default to path-only provenance and preview-first generation plans; apply/repair flows must remain gated by Connect policy.

## AI Improvement Envelope

`@lssm-tech/lib.contracts-spec/ai-improvement` provides the neutral evidence, policy, replay, risk, and kill-switch envelope for AI self-improvement workflows. Pioneer and future vendors must adapt to this surface rather than owning core domain types.

## Rich code and diff content

`@lssm-tech/lib.contracts-spec/rich-content` defines the portable model used by governed `CodeBlock` and `DiffBlock` surfaces. It represents rich text segments, references, sensitivity, visibility, explanations, action boundaries, code lines, and diff hunks without depending on a renderer.

Use `redactRichCodeBlock` and `redactRichDiffBlock` on the server before serializing payloads to clients. Redaction replaces denied segment text, strips reference values/hrefs, and preserves safe labels/explanations so UI surfaces can explain what was hidden without leaking the original value.

## RichReference (canonical reference surface)

`@lssm-tech/lib.contracts-spec/rich-reference` is the canonical transport for governed, kind-typed references rendered across REST, GraphQL, MCP, and agent surfaces.

- `defineReferenceKind({ id, schema, sensitiveFields, defaultPreview, defaultPanel, icon, parser? })` registers one kind. `sensitiveFields` is **required** at the type level (`Required<…>`) and at runtime — a missing or non-array value throws. Kinds with no sensitive fields must pass an explicit `[]` with the `// confirmed: no sensitive fields` comment (enforced by `@lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields`).
- `ReferenceKindRegistry` (`registerKind` / `getKind` / `listKinds`) is process-global with zero side-effects on import; apps opt in via `registerBuiltInReferenceKinds()` from `./rich-reference/kinds`.
- `DenialToken` is a TypeScript-**branded string** (not a Symbol — Symbols don't survive JSON). Wire form: `redacted:{kindId}:{hex(hmacSha256(message=kindId, key=salt))}`. Mint and verify through `createDenialTokenSigner(createSessionSalt())`; the per-resolve-request salt prevents forgery via markdown re-ingestion (invalid signatures fail closed via `verify()` returning `undefined`).
- Four governance ports live under `./rich-reference/ports`: `SubjectProvider` (implemented by `authos-runtime`, fail-closed on missing subject), `CoarsePreferencesProvider` (implemented by `personalization`, tenant-scoped cache key), `KindPolicyProvider` (implemented by `surface-runtime`'s RoleMorph adapter), and `AuditSink` (payload-free audit records).
- `applyKindRedaction(kind, instance, decision, signer)` walks the kind's `sensitiveFields` at read-time (not detector-time) so schema-evolution events honor new sensitive fields on the next read.
- Six built-in kinds ship out of the box: `database-record`, `object`, `link`, `file`, `media`, `code-symbol`.

The runtime (`./rich-reference/runtime` — added by S-2) enforces post-handler redaction so handlers cannot ship a `RichReference` whose payload contains undeclared fields or unredacted sensitive fields.

### AI-agent surface (S-9)

- `./rich-reference/agent-export` — `toAgentJson(ref, prefs?)` is a strict **passthrough** of the canonical serializer (`body === canonicalJsonString(serializeRichReference(ref))`). Preferences only affect envelope `meta` (request id, redaction-state summary, issued-at); they never reshape the wire body. There is exactly one serialization pipeline (P-3).
- `./rich-reference/markdown-envelope` — symmetric markdown round-trip. `toMarkdown(block, prefs?)` renders reference segments as `[label](rich-ref:{kindId}/{refId})`; denied refs render as `[redacted:{kindId}]({hmac-wire-form})`. `fromMarkdown(md, ctx)` re-validates every `redacted:` token via `DenialTokenSigner.verify` and FAILS CLOSED on forged HMAC (the link is dropped and replaced with an `[invalid-redaction]` marker; the function never auto-unredacts). The detector is re-applied to text regions so freshly pasted ref-like patterns become annotations again on read. `defaultCopyMarkdownHandler` is the wire used by `<RichBlock onCopyMarkdown>` in ui-kit-web / ui-kit.

## Graph & Timeline Primitives

`@lssm-tech/lib.contracts-spec` ships the spec layer for graph and timeline data views as part of the graph-timeline-primitives milestone.

### Data view spec authoring

Three new `DataViewKind` values — `"graph"`, `"timeline"`, `"timeline-graph"` — extend the existing spec system. `defineDataView` accepts a `DataViewGraphSpec` (sibling type to `DataViewSpec`) via overload. Source variants:

- `"inline-op"` — single operation returns `{ nodes, edges }`
- `"two-op"` — separate node and edge operations
- `"entity-declarative"` — driven by `EntityRegistry` (C12: must be loaded before renderer)

### Entity contract authoring (Layer 1 and Layer 2)

`defineContractEntity` supports two authoring layers:

**Layer 1** — declare an entity key and version without a schema:

```ts
import { defineContractEntity } from "@lssm-tech/lib.contracts-spec";

const UserEntity = defineContractEntity({
  meta: { key: "user", version: "1.0.0", description: "User entity", owners: ["team-auth"] },
});
```

**Layer 2** — pair with `defineEntity` from `@lssm-tech/lib.schema` to add typed fields:

```ts
import { defineContractEntity } from "@lssm-tech/lib.contracts-spec";
import { defineEntity, field } from "@lssm-tech/lib.schema/entity/defineEntity";

const UserEntity = defineContractEntity({
  meta: { key: "user", version: "1.0.0", description: "User entity", owners: ["team-auth"] },
  entity: defineEntity({
    name: "User",
    fields: { id: field.id(), email: field.email(), name: field.string({ isOptional: true }) },
  }),
});
```

Use `defineContractEdge` to declare typed graph edges (`from`, `to`, `relation`, `cardinality`, `directed`). Load entities and edges into `EntityRegistry` before the renderer mounts.

See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for the full exported symbol list and import rules.

## Translation diagnostics

`@lssm-tech/lib.contracts-spec/translations/diagnostics` exposes static catalog analysis helpers for CI and CLI consumers. Use `analyzeTranslationCatalogGroup` or `analyzeTranslationCatalogGroups` to produce `{ ok, summary, issues }` reports for missing catalogs/keys, extra keys, invalid catalog/message shapes, blank values, ICU syntax, placeholder parity, and duplicate bundle identities.


---

## @lssm-tech/lib.contracts-transformers

Description: Contract format transformations: import/export between ContractSpec and external formats (OpenAPI, AsyncAPI, etc.)
Path: packages/libs/contracts-transformers
URL: /llms/lib.contracts-transformers

# @lssm-tech/lib.contracts-transformers

Website: https://contractspec.io

**Contract format transformations: import/export between ContractSpec and external formats (OpenAPI, AsyncAPI, etc.).**

## What It Provides

- **Layer**: lib.
- **Consumers**: `lib.contracts-spec`, bundles, CLI.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.contracts-transformers`

or

`bun add @lssm-tech/lib.contracts-transformers`

## Usage

Import the root entrypoint from `@lssm-tech/lib.contracts-transformers`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/common` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/openapi` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./common` resolves through `./src/common/index.ts`.
- Export `./openapi` resolves through `./src/openapi/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Core logic must be pure functions with no I/O.
- Preserve original transport metadata (path/query/header params) for accurate round-trips.
- Track provenance — where specs came from — for sync operations.
- `@lssm-tech/lib.contracts-spec` re-exports this library for existing consumers; avoid breaking that contract.


---

## @lssm-tech/lib.contracts

Description: Deprecated monolith package split into contracts-spec, contracts-integrations, and contracts-runtime-* packages
Path: packages/libs/contracts
URL: /llms/lib.contracts

# @lssm-tech/lib.contracts

Website: https://contractspec.io

**DEPRECATED** monolith package. Exists only as a re-export shim for legacy consumers.**

## What It Provides

- **Layer**: lib (deprecated)
- **Consumers**: legacy code only

## Installation

`npm install @lssm-tech/lib.contracts`

or

`bun add @lssm-tech/lib.contracts`

## Local Commands

- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Release video edition tools
- Refactor contracts libs to split them reducing bundle size and load

## Notes

- **Do NOT add new code here.** Migrate consumers to `contracts-spec`, `contracts-integrations`, or `contracts-runtime-*` packages instead.
- This package exists solely for backward compatibility.


---

## @lssm-tech/lib.cost-tracking

Description: API cost tracking and budgeting
Path: packages/libs/cost-tracking
URL: /llms/lib.cost-tracking

# @lssm-tech/lib.cost-tracking

Website: https://contractspec.io

**API cost tracking and budgeting.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.cost-tracking`

or

`bun add @lssm-tech/lib.cost-tracking`

## Usage

Import the root entrypoint from `@lssm-tech/lib.cost-tracking`. The current package export map exposes only the root `.` entrypoint, so consumers should avoid undocumented subpath imports.

## Architecture

- `src/budget-alert-manager.ts` is part of the package's public or composition surface.
- `src/cost-model.ts` is part of the package's public or composition surface.
- `src/cost-tracker.ts` is part of the package's public or composition surface.
- `src/economic-evidence*.ts` provides additive neutral economic evidence helpers backed by `@lssm-tech/lib.economic-evidence`.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/optimization-recommender.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Economic evidence helpers are exported from the root entrypoint; keep subpath imports undocumented until the package export map intentionally changes.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Add neutral economic evidence bridge helpers that emit usage, cost, budget, and optimization projection refs without changing existing cost calculation semantics.
- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Cost calculation logic must stay deterministic — no side effects or external calls during computation.
- Budget threshold types are shared across consumers; changes require coordination.
- Do not introduce floating-point arithmetic where precision matters; use integer cents or a decimal library.
- Existing number-based cost totals are exposed to economic evidence as `estimated_decimal_string` values so downstream billing/finance surfaces cannot mistake them for exact money ledgers.


---

## @lssm-tech/lib.crypto-payments-spec

Description: Provider-neutral crypto wallet governance and HTTP-native agent payment protocol contracts.
Path: packages/libs/crypto-payments-spec
URL: /llms/lib.crypto-payments-spec

# `@lssm-tech/lib.crypto-payments-spec`

Provider-neutral contracts for crypto wallet governance and HTTP-native agent/API payment protocol evidence.

This package closes the first canonical ContractSpec slice for wallet-governed agent payments. It defines reviewable contracts for wallet policies, HTTP payment challenges, agent payment authorizations, settlement evidence refs, failure/idempotency semantics, and CompanyOS/finance-ops/assurance approval composition. It does not sign, custody, broadcast, settle, or call provider SDKs.

## Scope

Use this package to model:

- wallet refs, custody modes, signer-policy refs, chain/network refs, asset refs, spend limits, allowlists, revocation, and rotation;
- HTTP `402 Payment Required` and x402-style payment challenge metadata;
- agent payment authorizations that require CompanyOS authority, finance-ops spend policy/approval, and assurance evidence;
- settlement, failure, refund, dispute, replay, and audit evidence refs;
- x420 as an opaque placeholder/variant reference only until primary-source semantics are reviewed.

## Boundary

BillingOS owns quote-to-cash artifacts such as quotes, orders, invoices, payments, refunds, write-offs, and reconciliation. Crypto payments may reference those artifacts but must not redefine or execute them. Provider-payment integrations own concrete SDK/runtime execution and must depend on this contract surface rather than inventing their own policy envelope.

This package never stores private keys, seed phrases, API keys, bearer tokens, webhook secrets, provider secrets, raw signatures, or executable transfer instructions.

## Public entrypoints

- `@lssm-tech/lib.crypto-payments-spec` — root barrel
- `@lssm-tech/lib.crypto-payments-spec/types` — contract schemas and types
- `@lssm-tech/lib.crypto-payments-spec/validation` — semantic validation helpers
- `@lssm-tech/lib.crypto-payments-spec/fixtures` — safe synthetic fixtures

## Commands

- `bun run test`
- `bun run typecheck`
- `bun run lint:check`
- `bun run build`


---

## @lssm-tech/lib.crypto-utils

Description: Zero-dependency browser and React Native compatible crypto helpers
Path: packages/libs/crypto-utils
URL: /llms/lib.crypto-utils

# @lssm-tech/lib.crypto-utils

Zero-dependency browser, React Native, Expo, and Bun compatible helpers for SHA hashing, HMAC signatures, random bytes, and UUIDs.

This package intentionally avoids Node core modules and Node polyfill packages.


---

## @lssm-tech/lib.data-exchange-client

Description: Shared controllers plus web and native UI surfaces for data interchange
Path: packages/libs/data-exchange-client
URL: /llms/lib.data-exchange-client

# @lssm-tech/lib.data-exchange-client

Website: https://contractspec.io

**Shared controllers plus web and native UI surfaces for mapping, preview, validation, and audit review.**

## What It Provides

- Shared data-exchange view models and stateful controllers.
- Web mapping studio components built on the existing web data-table stack.
- Native mapping studio components built on the existing mobile data-table stack.

## Template Mapping UI State

The shared controller exposes template-aware rows so web and native surfaces can show recommended columns, matched source columns, confidence, formatting summaries, required gaps, and ignored source columns.

```tsx
import { useDataExchangeController } from "@lssm-tech/lib.data-exchange-client";

function ImportReview({ preview }) {
	const controller = useDataExchangeController({ preview });

	return (
		<ul>
			{(controller.model.templateRows ?? []).map((row) => (
				<li key={row.id}>
					{row.label}: {row.sourceField || "Unmatched"} -&gt;{" "}
					{row.targetField}
					{row.formatLabel ? ` (${row.formatLabel})` : ""}
				</li>
			))}
		</ul>
	);
}
```

Users can remap columns, select aliases, update field formats, reset to the developer template, or accept inferred mappings through controller actions.


---

## @lssm-tech/lib.data-exchange-core

Description: SchemaModel-first core primitives for data import/export and mapping
Path: packages/libs/data-exchange-core
URL: /llms/lib.data-exchange-core

# @lssm-tech/lib.data-exchange-core

Website: https://contractspec.io

**SchemaModel-first core primitives for data import, export, mapping, preview, and reconciliation planning.**

## What It Provides

- Headless CSV, JSON, and XML codecs.
- Normalized `RecordBatch` contracts for runtime data interchange.
- `SchemaModel` mapping inference, coercion, and validation helpers.
- Import/export planning and preview diff APIs.

## Installation

`npm install @lssm-tech/lib.data-exchange-core`

or

`bun add @lssm-tech/lib.data-exchange-core`

## Usage

Import the root entrypoint from `@lssm-tech/lib.data-exchange-core`, or use subpaths such as `./codecs`, `./mapping`, `./plans`, `./preview`, `./records`, `./schema`, and `./types`.

SQL sources and targets may include optional portable database metadata (`database.resource`, `fieldMapping`, `policyRefs`, and provenance). The core package remains runtime-agnostic; server adapters and provider integrations decide how to execute PostgreSQL, SQLite, or MySQL work.

## Import Templates

Developers can define the recommended import shape once, then let users upload files with different column labels or value formats:

```ts
import {
	createImportPlan,
	createRecordBatch,
	defineDataExchangeTemplate,
	previewImport,
} from "@lssm-tech/lib.data-exchange-core";

const template = defineDataExchangeTemplate({
	key: "accounts.import",
	version: "1.0.0",
	columns: [
		{
			key: "id",
			label: "Account ID",
			targetField: "id",
			required: true,
			sourceAliases: ["Account Identifier", "External ID"],
		},
		{
			key: "amount",
			label: "Amount",
			targetField: "amount",
			format: {
				kind: "number",
				decimalSeparator: ",",
				thousandsSeparator: ".",
			},
		},
	],
});

const sourceBatch = createRecordBatch([
	{ "Account Identifier": "acc-1", Amount: "1.234,50" },
]);

const preview = previewImport(
	createImportPlan({
		source: { kind: "memory", batch: sourceBatch, format: "csv" },
		target: { kind: "memory", format: "json" },
		schema: AccountImportSchema,
		sourceBatch,
		template,
	})
);
```

Template resolution uses exact headers, aliases, normalized labels, and SchemaModel fallback inference. Explicit `mappings` still override template mappings.
`defineImportTemplate` remains available as a backwards-compatible import-specific alias.


---

## @lssm-tech/lib.data-exchange-server

Description: Server-side adapters and execution services for SchemaModel-first data interchange
Path: packages/libs/data-exchange-server
URL: /llms/lib.data-exchange-server

# @lssm-tech/lib.data-exchange-server

Website: https://contractspec.io

**Server-side adapters, execution services, and workflow templates for SchemaModel-first data interchange.**

## What It Provides

- File, HTTP, SQL, and storage adapter families.
- SQL adapters that preserve portable database endpoint metadata while delegating execution to injected clients/provider boundaries.
- Dry-run, validation, preview, execute, retry, and audit services.
- `WorkflowSpec` templates for interchange orchestration.

## Usage

Import the root entrypoint from `@lssm-tech/lib.data-exchange-server`, or use `./adapters`, `./services`, and `./workflow`.

## Template-Aware Imports

Server dry-runs and executions accept the same import templates as core. This lets users upload partner-specific CSV/JSON/XML layouts while the server previews normalized records before writing them.

```ts
import { defineDataExchangeTemplate } from "@lssm-tech/lib.data-exchange-core";
import { dryRunImport, executeImport } from "@lssm-tech/lib.data-exchange-server";

const template = defineDataExchangeTemplate({
	key: "invoices.import",
	version: "1.0.0",
	columns: [
		{
			key: "id",
			label: "Invoice ID",
			targetField: "id",
			required: true,
			sourceAliases: ["Invoice Number", "No facture"],
		},
		{
			key: "amount",
			label: "Amount",
			targetField: "amount",
			format: {
				kind: "number",
				decimalSeparator: ",",
				thousandsSeparator: ".",
			},
		},
	],
});

const preview = await dryRunImport({
	source: {
		kind: "file",
		path: "partner.csv",
		format: "csv",
		codecOptions: { csv: { delimiter: ";", skipRows: 1 } },
	},
	target: { kind: "memory", format: "json" },
	schema: InvoiceImportSchema,
	template,
});

if (preview.issues.every((issue) => issue.severity !== "error")) {
	await executeImport({
		source: {
			kind: "file",
			path: "partner.csv",
			format: "csv",
			codecOptions: { csv: { delimiter: ";", skipRows: 1 } },
		},
		target: { kind: "memory", format: "json" },
		schema: InvoiceImportSchema,
		template,
	});
}
```

Execution audit entries record whether mappings came from explicit mappings, template resolution, or inference.


---

## @lssm-tech/lib.design-system

Description: Design tokens and theming primitives
Path: packages/libs/design-system
URL: /llms/lib.design-system

# @lssm-tech/lib.design-system

`@lssm-tech/lib.design-system` provides higher-level design-system components, tokens, platform adapters, renderers, and composed layouts used across web, native, marketing, legal, agent, and application surfaces.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.design-system`

or

`npm install @lssm-tech/lib.design-system`

## What belongs here

This package owns the higher-level design-system layer:

- Theme tokens and token bridging.
- Platform helpers and responsive hooks.
- Renderers and form-contract integration.
- Higher-level atoms, molecules, organisms, templates, and visualization components.
- Registry metadata and shadcn-style component registry support.

Use this package when you want the composed design-system layer. Do not use it when a lower-level primitive from `ui-kit` or `ui-kit-web` is enough.

## Core workflows

### Import a higher-level design-system component

```ts
import { AppLayout, Button, HeroSection } from "@lssm-tech/lib.design-system";
```

### Work with tokens and platform helpers

```ts
import {
  createTranslationResolver,
  defaultTokens,
  mapTokensForPlatform,
  resolvePlatformTheme,
  resolveThemeRefTokens,
  withPlatformUI,
} from "@lssm-tech/lib.design-system";

const nativeTokens = mapTokensForPlatform("native", defaultTokens);
const ui = withPlatformUI({
  tokens: defaultTokens,
  platform: "web",
});
```

Focused public subpaths are available when consumers do not need the full root
barrel:

```ts
import { themeSpecToTailwindPreset } from "@lssm-tech/lib.design-system/theme";
import { Select } from "@lssm-tech/lib.design-system/controls";
import { FormDialog } from "@lssm-tech/lib.design-system/forms";
import { HStack } from "@lssm-tech/lib.design-system/layout";
import { inputValue } from "@lssm-tech/lib.design-system/primitives";
```

### Editorial radius tokens

The ContractSpec editorial theme publishes an additive radius taxonomy from the
contracts source of truth: scale keys `xs/sm/md/lg/xl/full/default` and semantic
aliases `control/card/panel/overlay/pill`. Existing design-system
`RadiusTokens` (`sm/md/lg/xl/full`) remain supported; resolved ThemeSpec radii
also flow through the generic bridge as `--ds-radius-*` variables and Tailwind
`borderRadius` entries.

Use smaller radii (`xs/sm`) for dense indicators, compact chips, and more
precise or assertive affordances. Use `md/control` for standard controls. Use
`lg/card`, `default/panel`, and `xl/overlay` for progressively softer editorial
surfaces and lower-pressure reading contexts. Reserve `full/pill` for avatars,
status dots, and explicit capsule forms.

Personalization and RoleMorph may later choose radius profiles by persona, tone,
or density, but this pass is documentation-only: no runtime persona radius
switching or action-boundary changes are implemented.

### Motion, elevation, and density tokens

`defaultTokens` includes `motion` (durations in ms + easing as cubic-bezier
control-point tuples), structured `elevation` (a web `box-shadow` string plus a
React Native shadow object), and `density` (compact/comfortable spacing/size
multipliers). They flow `tokens.ts` → web CSS vars
(`--ds-motion-*` / `--ds-elevation-*` / `--ds-density-*`, surfaced as Tailwind
`transitionDuration` / `transitionTimingFunction` / `boxShadow` utilities) → the
native `tokenBridge` (which maps the RN shadow branch and keeps easing as numeric
tuples — a CSS string is never pushed into RN style). `dsBaseVariants` tone and
density variants are token-backed.

Animation is reduced-motion-first. Use the `useMotion` hook
(`@lssm-tech/lib.design-system/platform/useMotion`, native:
`platform/useMotion.native`); it returns a transition config gated by
`useReducedMotion`, collapsing to an instant, no-displacement transition when the
OS/user prefers reduced motion. Native skeletons (`SkeletonBlock` /
`SkeletonCircle` / `SkeletonList`) animate via reanimated and fall back to a
static view under reduced motion. Animation libraries are declared as
split-by-lane peers — `framer-motion` (web, resolves via `ui-kit-web`) and
optional `react-native-reanimated` / `-gesture-handler` / `-svg` (native).

### Compose full-page marketing surfaces

Marketing page foundations live in the design system so product bundles can own
story/content while sharing page structure. Use `MarketingLandingPage` for a
typed section sequence, `MarketingHero` / `MarketingCtaBand` /
`MarketingProseSection` / `MarketingIconGridSection` for reusable sections,
`MarketingPricingCalculator` / `MarketingPricingTable` / `MarketingFaqSection` /
`MarketingTestimonialSection` plus `MarketingLeadCapture`, `MarketingFeatureTabs`,
`MarketingTimeline`, `MarketingTrustBadges`, `MarketingVideo`, and
`MarketingAnnouncementBar` for rich prop-driven marketing blocks, and
`MarketingCtaRow` / `MarketingProofStrip` for molecule-level pieces.

```tsx
import { MarketingLandingPage } from "@lssm-tech/lib.design-system";

<MarketingLandingPage
  sections={[
    { kind: "hero", id: "hero", title: "CompanyOS", ctas: [] },
    { kind: "ctaBand", id: "final", title: "Start" },
  ]}
/>;
```

The section union is intentionally closed to the first-pass marketing taxonomy;
content mapping, icon lookup, and product-specific copy remain in the consuming
bundle/app. Static tone/alignment variants are supported, but no runtime
personalization or bundle imports belong in design-system marketing components.

### Reuse form configuration surfaces

Form configuration chrome is centralized under
`@lssm-tech/lib.design-system/forms`:

```tsx
import {
  FormConfigMenuBar,
  FormConfigPanel,
  FormConfigShell,
} from "@lssm-tech/lib.design-system/forms";
```

Use `FormConfigShell` when a screen needs a shared category menu plus adaptive
panel. Use `FormConfigMenuBar` or `FormConfigPanel` directly only when a host
already owns one side of the layout. The category and entry objects are display
metadata; callers own the active category state and any submit/apply behavior.

`FormConfig` components do not persist preferences, drafts, credentials, or form
submissions. Product, example, and docs surfaces such as the form-showcase proof
should reuse these exports instead of forking local configuration shells, and
must keep storage or governed mutation behavior in the host/runtime layer.

### Compose contract-driven entity workspaces

`EntityWorkspace` is the public entity-surface façade for DataView-backed
product flows. It keeps `DataViewSpec` as the canonical contract input and
delegates list/grid/table rendering to `DataViewRenderer`, while adding neutral
workspace chrome for result counts, search/filter framing, metric cards,
card/row/detail-action open-detail semantics, AdaptivePanel detail/edit shells,
RichReference-aware field values, visible RoleMorph summaries, and
personalization chips.

```tsx
import { EntityWorkspace } from "@lssm-tech/lib.design-system";
// or the focused subpath:
import { EntityActionBar } from "@lssm-tech/lib.design-system/components/entity-workspace";

<EntityWorkspace
  spec={agentDataViewSpec}
  items={agents}
  selectedItem={selectedAgent}
  selectedItemId={selectedAgent?.id ?? null}
  selectedIds={selectedAgentIds}
  getItemId={(agent) => agent.id}
  preferences={{ viewMode: "list", density: "compact", dataDepth: "summary" }}
  adaptiveModel={{
    layout: "master-detail",
    hiddenFields: ["internalNotes"],
    summary: "Manager-safe projection",
  }}
  actionStates={{}}
  search={search}
  filters={{}}
  sort={null}
  pagination={undefined}
  metrics={[{ key: "allowed", label: "Allowed", value: 12, tone: "success" }]}
  showMetrics={true}
  evidence={[]}
  onOpenDetail={({ itemId, interaction }) => {
    // `interaction.action === "opened"` and includes the DataView key/version.
    console.log(itemId, interaction);
  }}
  onNavigateToDetailPage={({ detailPageHref }) => {
    if (detailPageHref) router.push(detailPageHref);
  }}
  buildDetailPageLink={({ itemId }) => `/entities/${itemId}`}
  detailPageActionLabel="Open full page"
  onSelectedItemChange={setSelectedAgent}
  onSelectedIdsChange={setSelectedAgentIds}
  onAction={handleAgentAction}
  renderAction={renderAgentAction}
  renderFormSlot={null}
  onSearchChange={setSearch}
  onFilterChange={setFilters}
  onPageChange={setPage}
  viewMode="list"
  onViewModeChange={setViewMode}
  density="compact"
  onDensityChange={setDensity}
  dataDepth="summary"
  onDataDepthChange={setDataDepth}
  onSortChange={setSort}
  headerActions={null}
  toolbarActions={null}
  renderResultCard={undefined}
  renderFieldValue={undefined}
  getFieldClassName={undefined}
  getFieldLabelClassName={undefined}
  renderDetail={undefined}
  detailOpen={Boolean(selectedAgent)}
  onDetailOpenChange={setDetailOpen}
  editOpen={false}
  onEditOpenChange={setEditOpen}
  loading={false}
  emptyState="No agents yet"
  noResultsState="No agent selected"
/>;
```

Use the default `querySource="local"` when the workspace receives an in-memory
collection and should apply DataView search/filter/sort controls itself. Use
`querySource="remote"` when `items` already came from `spec.source.primary`
(for example `agent.list` with cursor pagination); the workspace still renders
the same controls and emits host callbacks, but it does not re-apply search,
filters, or sort locally. This prevents double filtering when a server or
governed DataView query source has already projected the result set.

These surfaces are `QueryState`-aware and remain **I/O-free**: they accept the
canonical `QueryState` (from `@lssm-tech/lib.contracts-spec/query`) and render
loading / error / offline / stale / empty / conflict / retry states, but never
fetch. Hosts wire `useContractQuery` (from
`@lssm-tech/lib.contracts-runtime-client-react`, over the
`contracts-runtime-core` engine) and pass the returned `QueryState` straight in
with zero adapter.

When `onNavigateToDetailPage` is provided, the workspace renders a standard
"Open full page" detail-panel action. Hosts can pair it with
`buildDetailPageLink` to keep route construction standardized while still owning
the actual router call, such as Expo Router or React Navigation.

The focused subpath exports the workspace and neutral primitives:
`EntityWorkspace`, `EntityResultsToolbar`, `EntityResultCard`,
`EntityResultRow`, `EntityDetailPanel`, `EntityEditPanel`, `EntityFieldValue`,
`EntityActionBar`, `EntityMetricStrip`, and `EntityEvidenceBlock`. The neutral
metric and evidence primitives are backed by ThemeSpec component token hooks and
compose design-system `StatCard`, `Text`, and card primitives instead of
domain-specific AgentFleet surfaces. Every public component is covered by the native parity matrix at
`src/components/entity-workspace/native-parity.ts`; public entries must be
platform-safe shared or have paired `.tsx` / `.native.tsx` implementations.
"Native later" is not an accepted public status.

Run the focused gate with:

```bash
bun test src/components/entity-workspace/EntityWorkspace.test.tsx src/components/entity-workspace/native-parity.test.ts
```

### Resolve contract-backed themes

```ts
import { ThemeRegistry } from "@lssm-tech/lib.contracts-spec/themes";
import { resolvePlatformTheme } from "@lssm-tech/lib.design-system";

const registry = new ThemeRegistry([themeSpec]);

const webTokens = resolvePlatformTheme(
  registry,
  { key: "design.brand", version: "1.0.0" },
  "web",
  { targets: ["tenant:acme"] }
);
```

### Translate ThemeSpec into Tailwind tokens

Use the Tailwind bridge when a `ThemeSpec` should drive CSS variables and
utility names without requiring a generated file:

```ts
import {
  resolveThemeModeTokens,
  themeSpecToCssVariables,
  themeSpecToTailwindCss,
  themeSpecToTailwindPreset,
} from "@lssm-tech/lib.design-system";

const tokens = resolveThemeModeTokens(themeSpec, "light", {
  targets: ["tenant:acme"],
});

export default themeSpecToTailwindPreset(tokens);

const variables = themeSpecToCssVariables(themeSpec, {
  targets: ["tenant:acme"],
});

const cssText = themeSpecToTailwindCss(variables, {
  includeCustomVariant: true,
});
```

The bridge emits stable variables such as `--ds-color-primary`,
`--ds-radius-md`, and `--ds-space-sm`, plus Tailwind v4 `@theme inline`
aliases like `--color-primary: var(--ds-color-primary)`. Color values are
passed through unchanged, so OKLCH tokens such as
`oklch(0.72 0.11 221.19)` can be authored directly in `ThemeSpec`.

### Compose rich-reference layouts (replaces legacy CodeBlock / DiffBlock / object-reference)

> **BREAKING (S-8):** the legacy `CodeBlock`, `DiffBlock`, and
> `object-reference` components were deleted from this package without a shim
> phase. Composition now flows through `<RichRef>` / `<PreviewPanel>` /
> `<RichBlock>` from `@lssm-tech/lib.ui-kit-web` (web) or
> `@lssm-tech/lib.ui-kit` (native), combined with per-kind layouts shipped
> from this package under `components/rich-reference/layouts/{kind}`.

Each of the six built-in `RichReference` kinds — `database-record`, `object`,
`link`, `file`, `media`, and `code-symbol` — has a paired `Preview` (inline
trigger) and `Panel` (expanded body) layout that consumes the canonical
`RichReference<TPayload>` shape and routes redacted fields through a uniform
`(redacted)` indicator (`DenialAwareValue`).

```tsx
import {
  builtInRichReferenceLayouts,
  getRichReferenceLayout,
} from "@lssm-tech/lib.design-system";
import { RichRef } from "@lssm-tech/lib.ui-kit-web/rich-ref";

function GovernedReference({ kindId, refId }: { kindId: ReferenceKindId; refId: ReferenceInstanceId }) {
  const layout = getRichReferenceLayout(builtInRichReferenceLayouts, kindId);
  if (!layout) return null;
  return (
    <RichRef
      kindId={kindId}
      refId={refId}
      renderPreview={({ reference }) => <layout.Preview reference={reference} />}
      renderPanel={({ reference }) => <layout.Panel reference={reference} />}
    />
  );
}
```

Apps that ship custom kinds merge them into the registry at the composition
root via `registerRichReferenceLayouts({...})`. Code-symbol layouts respect
the `DiffHighlightTokenizer` contract from `@lssm-tech/lib.ui-kit-core`; the
real Shiki/WASM implementation lives in `@lssm-tech/lib.ui-kit-web` and a
plain-text equivalent lives in `@lssm-tech/lib.ui-kit` (Hermes is
WASM-incompatible).

### Provide translations to contract-driven renderers

```tsx
import {
  createTranslationResolver,
  DesignSystemTranslationProvider,
} from "@lssm-tech/lib.design-system";

const resolver = createTranslationResolver({
  registry: translationRegistry,
  locale: "fr",
  specKeys: ["design-system.form", "design-system.data-view"],
});

<DesignSystemTranslationProvider resolver={resolver}>
  {children}
</DesignSystemTranslationProvider>;
```

### Provide contract-backed themes to controls

```tsx
import {
  DesignSystemThemeProvider,
  Input,
  Select,
} from "@lssm-tech/lib.design-system";

<DesignSystemThemeProvider
  theme={themeSpec}
  targets={["tenant:acme"]}
  mode="dark"
  applyCssVariables
>
  <Input
    componentKey="Input"
    themeVariant="default"
    placeholderI18n="form.customerName.placeholder"
  />
  <Select
    componentKey="Select"
    options={[{ labelI18n: "status.draft", value: "draft" }]}
  />
  <Select
    componentKey="Select"
    groups={[
      {
        labelI18n: "status.lifecycle",
        options: [{ labelI18n: "status.draft", value: "draft" }],
      },
      {
        labelI18n: "status.release",
        options: [{ labelI18n: "status.published", value: "published" }],
      },
    ]}
  />
</DesignSystemThemeProvider>;
```

When both `options` and `groups` are provided to `Select`, grouped options are
used and the flat `options` list is ignored.

### Use form controls from the design-system boundary

The root barrel exposes themed and translation-aware controls for product
surfaces: `Button`, `Input`, `Textarea`, `Select`, `NativeSelect`,
`Autocomplete`, `Combobox`, `Checkbox`, `RadioGroup`, `Switch`, `DatePicker`,
`TimePicker`, `DateTimePicker`, `DateRangePicker`, `Field*`, `InputGroup`,
`InputOTP`, `LoadingButton`, plus `Box`, `HStack`, and `VStack`.

`Field*` includes semantic `FieldSet`, `FieldLegend`, `FieldGroup`,
`FieldContent`, `FieldLabel`, `FieldDescription`, `FieldError`, and
`FieldSeparator` wrappers so contract-driven forms can preserve accessible
legend, description, invalid, and grouped-control structure.

The `Autocomplete` control renders through the shared combobox primitive on web
and keeps native rendering aligned for query, selected options, loading, error,
and empty states. FormSpec renderers pass resolver-backed async state through
these props without requiring product surfaces to know the underlying transport.

### Use neutral primitive helpers

Use `@lssm-tech/lib.design-system/primitives` for design-system-neutral
helpers shared by web and native controls, such as themed primitive hooks,
translated placeholder helpers, and safe `inputValue` / `optionValue` event
normalization. The root barrel re-exports this surface for compatibility, while
the focused subpath keeps lower-level control code from depending on a full
component import.

### Compose application shells

Use the shell subpath for app frames that need sidebar navigation, topbar
breadcrumbs, command search, account actions, and a right-side page outline.
The same typed shell contract has web and native entrypoints.

```tsx
import { AppShell } from "@lssm-tech/lib.design-system/shell";

<AppShell
  brand={null}
  logo={null}
  title="Workspace"
  homeHref="/"
  commands={[
    {
      heading: "Actions",
      items: [{ id: "new-project", label: "New project" }],
    },
  ]}
  notifications={null}
  navigation={[
    {
      title: "Main",
      items: [
        {
          label: "Projects",
          href: "/projects",
          children: [{ label: "Active", href: "/projects/active" }],
        },
      ],
    },
  ]}
  notifications={undefined}
  breadcrumbs={[{ href: "/", label: "Home" }, { label: "Projects" }]}
  pageOutline={[
    { id: "summary", label: "Summary" },
    { id: "details", label: "Details", level: 2 },
    { id: "audit", label: "Audit trail", level: 3 },
  ]}
  activeHref="/projects"
  activeOutlineId="summary"
  userMenu={null}
  topbarStart={null}
  topbarEnd={null}
  aiPanel={null}
  onNavigate={(item) => {
    if (item.href) router.push(item.href);
  }}
>
  {children}
</AppShell>;
```

On desktop web, `AppShell` renders a collapsible sidebar, sticky topbar, content
region, and optional floating `PageOutline`. The outline does not reserve a
right-side content column: it reduces to a slim rail while inactive and expands
on hover or keyboard focus, keeping wide page content centered. The desktop
topbar is inset beside the sidebar and includes a sidebar toggle. On small web
screens, navigation moves behind an accessible menu trigger and AppShell hides
the page outline to preserve layout stability. On native, `AppShell` is an Expo
Router NativeTabs layout adapter intended for an Expo Router layout boundary such
as `app/_layout.tsx`. Native primary navigation is rendered through Expo's alpha
`expo-router/unstable-native-tabs` system tab bar, while overflow navigation,
actions, user content, and page outline stay reachable from a header menu button
that opens a sheet (rendered only when such overflow content exists). `children`
render outside the NativeTabs navigator as an overlay/utility slot for source
compatibility; routed tab screens remain owned by Expo Router. The tab bar is
themed from design-system tokens: active label and icon use the `primary` color
and inactive items use `mutedForeground`, with background, indicator, ripple, and
badge colors resolved from the active theme (falling back to default tokens when
no `DesignSystemThemeProvider` is mounted). Primary native tab triggers render a
governed native-safe tab icon when a host supplies `nativeIcon` (`sf` SF Symbol on
iOS, `md` Material icon or `drawable` on Android) and fall back to label and
string/number badge only when no icon is provided; the platform-agnostic
ReactNode `icon` remains for overflow/menu navigation.
Native tab route inference is deliberately narrow: use `/` for the `index` tab
and single-segment hrefs such as `/settings` for route names. Missing, empty,
external, nested, dynamic, duplicate, or denied/disabled primary tab hrefs throw
developer errors instead of falling back to custom tabs.

`AppShell` also accepts a prop-driven `notifications` center for in-app
notifications. Hosts provide structural `items`, `unreadCount`, loading/empty
state, and callbacks such as `onSelect`, `onMarkRead`, and `onMarkAllRead`; the
design-system shell renders the web topbar trigger and a native header bell button
(with an unread-count badge) that opens the notifications sheet, without importing
or owning any notification runtime package. On web, the
notification panel closes when users select an item, press the close button,
click outside the panel, press Escape, or click the notification trigger again.

Shell navigation and command items may carry optional `policy` metadata plus a `policyBehavior` of `hide`, `disable`, or `show-with-lock`. Use `filterShellNavigationForPolicy()` / `annotateShellCommandsDecisions()` with decisions produced by your application runtime; AppShell only adapts affordances and does not fetch permissions or enforce backend access.

### Render forms on mobile through the shared renderer

Use the focused shared renderer subpath when rendering `FormSpec` contracts in
Expo or React Native apps:

```tsx
import { formRenderer } from "@lssm-tech/lib.design-system/renderers";
```

The shared FormSpec renderer includes a first-class phone field implementation
that displays country flags, parses international input with
`libphonenumber-js`, and keeps single-input or split country/national controls
linked. Contracts can configure behavior through a phone field's `input`,
`output`, `country`, and `display` options; host apps can set package-wide
defaults by passing `phone` overrides to `createFormRenderer`.

Expo apps must keep the presentation Metro aliases enabled so design-system
imports of `@lssm-tech/lib.ui-kit-web/ui/*` are remapped to
`@lssm-tech/lib.ui-kit/ui/*` at bundle time:

```js
const {
  withPresentationMetroAliases,
} = require("@lssm-tech/lib.presentation-runtime-core");

module.exports = withPresentationMetroAliases(config, { monorepoRoot });
```

### Render the canonical account grid

The canonical data-table example lives in
[`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
Its composed lane uses `DataTable`, `DataTableToolbar`, and `DataViewTable`
from this package:

```tsx
import {
  Button,
  DataTable,
  DataTableToolbar,
  DataViewTable,
} from '@lssm-tech/lib.design-system';
import { useContractTable } from '@lssm-tech/lib.presentation-runtime-react';

import { DataGridShowcaseDataView } from '@lssm-tech/example.data-grid-showcase/contracts/data-grid-showcase.data-view';
import { SHOWCASE_ROWS } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.data';
import { useShowcaseColumns } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.columns';
import {
  ExpandedRowContent,
} from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.parts';

export function AccountHealthTable() {
  const columns = useShowcaseColumns();

  const controller = useContractTable({
    data: SHOWCASE_ROWS,
    columns,
    selectionMode: 'multiple',
    initialState: {
      sorting: [{ id: 'arr', desc: true }],
      pagination: { pageIndex: 0, pageSize: 4 },
      columnVisibility: { notes: false },
      columnPinning: { left: ['account'], right: [] },
    },
    renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
    getCanExpand: () => true,
  });

  return (
    <>
      <DataTable
        controller={controller}
        title="Account health"
        description="Composed table surface for the canonical account grid."
        headerActions={<Button variant="outline">Reset</Button>}
        toolbar={
          <DataTableToolbar
            controller={controller}
            searchPlaceholder="Search accounts"
            actionsStart={
              <Button variant="outline" size="sm">
                Risk Only
              </Button>
            }
          />
        }
        loading={false}
        emptyState={<div>No rows available.</div>}
        footer={\`Page \${controller.pageIndex + 1} of \${controller.pageCount}\`}
      />

      <DataViewTable
        spec={DataGridShowcaseDataView}
        items={SHOWCASE_ROWS}
      />
    </>
  );
}
```

`DataTable` remains the composed card/container surface. `DataTableToolbar` is
the recommended ergonomic layer for search, chips, selection summary, and
hidden-column recovery without widening the primitive table API.
DataView-driven tables also honor field and column overflow hints from
`DataViewSpec`: column hints override field hints, markdown wraps by default,
compact scalar formats truncate, `expand` adds detail to the row expansion
surface, and `hideColumn` starts hidden when column visibility is enabled.
Collection `DataViewSpec` contracts can also declare `view.collection` defaults
for list/grid/table mode switching, toolbar controls, query page size, and
density. They can also declare `collection.dataDepth` and field-level
`visibility.minDataDepth` so one spec can project summary, standard, detailed,
or exhaustive fields. `DataViewRenderer` uses those defaults for web and native
renderers while keeping caller props authoritative through `viewMode`,
`density`, `dataDepth`, `onViewModeChange`, `onDensityChange`, and
`onDataDepthChange`. Personalization integrations should resolve preferences in
the host app and pass ordinary renderer props; the design system intentionally
does not import `@lssm-tech/lib.personalization`.

### Compose CommunicationOS presentational primitives

Use the focused communication subpath when CommunicationOS screens need neutral
presentational blocks without pulling in example fixtures or module workflow
state:

```tsx
import {
  ActionCandidateList,
  CommunicationWorkQueue,
  ReplyDraftReviewPanel,
} from "@lssm-tech/lib.design-system/components/communication-os";
```

These blocks are UI-only: callers provide work items, source evidence, policy
decisions, handoff packets, and action candidates. Workflow behavior and rich
screen composition live in `@lssm-tech/module.communication-os/ui`; deterministic
sample data lives in example packages such as
`@lssm-tech/example.communication-os` and `@lssm-tech/example.messaging-app`.

## API map

### Theme and platform

- `defaultTokens` and token interfaces from `./theme/tokens`
- `mapTokensForPlatform` from `./theme/tokenBridge`
- `resolveThemeSpecTokens`, `resolveThemeRefTokens`, and `resolvePlatformTheme` from `./theme/contracts`
- `resolveThemeModeTokens`, `themeSpecToCssVariables`, `themeSpecToTailwindTheme`, `themeSpecToTailwindPreset`, and `themeSpecToTailwindCss`
- `DesignSystemThemeProvider`, `useDesignSystemTheme`, and `useComponentTheme`
- theme variants
- `withPlatformUI`
- `useColorScheme`
- `useReducedMotion`
- `useResponsive`

### Renderers and hooks

- renderer exports from `./renderers`
- form-contract renderer support, including readonly, email, password, autocomplete, address, phone, date, time, datetime, semantic FormSpec groups, grid layout hints, progressive FormSpec sections/steps, mobile-safe FormSpec column helper output, and text/textarea/email input groups
- translation-aware rendering through `DesignSystemTranslationProvider` and `createTranslationResolver`
- theme-aware form controls, neutral primitive helpers, and stack primitives that consume ThemeSpec component variant props
- hooks such as `useListUrlState`, including scoped list filters where locked constraints are excluded from user-editable URL state
- DataViewRenderer filter chips for scoped DataView filters, including disabled locked chips on web and native surfaces
- navigation-related shared types

### Component composition layers

- atoms
- forms
- legal
- marketing
- molecules
- organisms
- templates
- visualization
- agent and approval components

The root barrel is the primary API and already groups these exports in one place.

## Public surface

The root barrel at `src/index.ts` is the main public API for this package.

The export map is broad, but it is centralized:

- `.` for backward-compatible root imports across theme, platform, renderers, controls, and composed components
- `./theme` for ThemeSpec runtime, platform token mapping, and Tailwind bridge helpers
- `./controls` for themed and translated controls
- `./forms` for form controls, layouts, and `ZodForm`
- `./layout` for `Box`, `HStack`, and `VStack`
- `./primitives` for themed primitive hooks, translated value helpers, and input/option value normalization
- `./renderers` for focused renderer imports such as `formRenderer`
- hooks and shared types

The package also ships registry metadata and build support:

- `components.json`
- `registry/registry.json`
- `bun run registry:build`

## Operational semantics and gotchas

- Token names and token shapes are compatibility surface.
- `mapTokensForPlatform()` deliberately returns different token shapes for web and native, and can now map resolved contract-backed tokens.
- `withPlatformUI()` is a lightweight adapter, not a full runtime framework.
- `DesignSystemThemeProvider` resolves `ThemeSpec` / `ThemeRef` tokens, scoped overrides, and component variant default props. Explicit caller props win over theme defaults.
- The root barrel is broad and therefore high-blast-radius.
- This package depends on both `ui-kit` and `ui-kit-web`.
- The package includes legal, marketing, agent, app-shell, and visualization compositions, not just low-level primitives.

## When not to use this package

- Do not use it for tiny low-level utilities.
- Do not use it for router-agnostic links.
- Do not use it when a single lower-level primitive from `ui-kit` or `ui-kit-web` is enough.

## Related packages

- `@lssm-tech/lib.ui-kit`
- `@lssm-tech/lib.ui-kit-web`
- `@lssm-tech/lib.ui-kit-core`
- `@lssm-tech/lib.ui-link`

## Local commands

- `bun run lint:check`
- `bun run typecheck`
- `bun run test`

### Render governed rich code and diffs

Code-symbol and diff rendering flows through the per-kind rich-reference
layouts (`components/rich-reference/layouts/code-symbol`) and the
`DiffHighlightTokenizer` contract from `@lssm-tech/lib.ui-kit-core`. Web apps
get Shiki dual-theme highlighting via
`@lssm-tech/lib.ui-kit-web/rich-block/diff/highlight`; native apps get a
plain-text equivalent via `@lssm-tech/lib.ui-kit/rich-block/diff/highlight`
(Hermes cannot execute Shiki/WASM).

Server surfaces redact sensitive payload fields before passing
`RichReference<TPayload>` to the client. The per-kind layouts render the
canonical denial-token wire form through `DenialAwareValue`; the design-system
does not decide authorization by itself.

## Graph & Timeline Primitives

`@lssm-tech/lib.design-system` routes graph, timeline, and timeline-graph data views through `DataViewRenderer`. The switch has been updated to handle three new kinds:

- `"graph"` → `DataViewRendererGraph` (P3/W3.2 stub; renders `emptyState` until real renderer lands)
- `"timeline"` → `DataViewRendererTimeline`
- `"timeline-graph"` → `DataViewRendererTimelineGraph`

Product code should always use `DataViewRenderer` — the sub-renderers are internal:

```ts
import { DataViewRenderer } from "@lssm-tech/lib.design-system";

<DataViewRenderer spec={voiceOpsOperatingGraphView} items={[]} />
```

See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for layer placement and import rules.

## Marketing page foundation

`@lssm-tech/lib.design-system` owns the generic marketing page primitives used by full-page landing surfaces:

- `MarketingCtaRow`, `MarketingBadge`, and `MarketingProofStatStrip` for atoms/molecules.
- `MarketingHeroSection`, `MarketingProseSection`, `MarketingIconGridSection`, `MarketingSummarySection`, and `MarketingCtaBand` for reusable sections.
- `MarketingPricingCalculator`, `MarketingPricingTable`, `MarketingFaqSection`, and `MarketingTestimonialSection` for prop-driven pricing, FAQ, and social-proof blocks. Pricing logic, formatting, copy, analytics callbacks, FAQ JSON-LD, and product-specific content stay in the consuming bundle/app.
- `MarketingLeadCapture`, `MarketingFeatureTabs`, `MarketingTimeline`, `MarketingTrustBadges`, `MarketingVideo`, and `MarketingAnnouncementBar` for generic lead capture, use-case tabs, process, trust/compliance, media, and campaign banner surfaces. Forms, media embeds, analytics, validation, and provider logic stay caller-owned. `MarketingFeatureTabs` is a client component; import its focused subpath in RSC-sensitive apps when you want the client boundary to stay explicit.
- `MarketingLandingPage` plus the `MarketingPageSection` discriminated union for ordered, typed page composition.

Product bundles keep copy, icon mapping, and content-model conversion. The design system must not import bundle, app, or personalization runtime modules.


---

## @lssm-tech/lib.economic-evidence

Description: Provider-neutral economic evidence primitives for usage, cost, budget, replay, and projection refs.
Path: packages/libs/economic-evidence
URL: /llms/lib.economic-evidence

# @lssm-tech/lib.economic-evidence

Provider-neutral economic evidence primitives for ContractSpec applications.

This package is the neutral spine selected by Ultragoal G002 for usage-based and commission-based systems. It records replayable facts and refs for cost, usage, budget decisions, redaction, replay, and projection consumers without owning provider SDKs, BillingOS invoices/payments, FinanceOps advice, or observability implementations.

## Exports

- `@lssm-tech/lib.economic-evidence`
- `@lssm-tech/lib.economic-evidence/cost`
- `@lssm-tech/lib.economic-evidence/usage`
- `@lssm-tech/lib.economic-evidence/budget`
- `@lssm-tech/lib.economic-evidence/replay`
- `@lssm-tech/lib.economic-evidence/seam-kind`
- `@lssm-tech/lib.economic-evidence/projection-policy`
- `@lssm-tech/lib.economic-evidence/projection-refs`

## Boundary

Producer packages may emit or cite these records. Projection packages may cite refs. This package must remain side-effect free and must not import provider, billing, finance, observability, or runtime implementations.

## Projection And Seam Policy

Use `createStandardEconomicProjectionRefs()` from `@lssm-tech/lib.economic-evidence/projection-policy` to produce reference-only projections for BillingOS, FinanceOps, observability, and replay reports. Billing projections carry `not_an_invoice`; FinanceOps projections carry `not_accounting_export`; observability and replay projections are display-only.

## Monorepo Enforcement

`src/adoption-enforcement.test.ts` guards the current vertical slice: cost-tracking, ai-providers, ai-agent, and builder-runtime must depend on the neutral evidence package; ai/chat/builder public evidence entrypoints must remain exported; and the neutral package must stay free of runtime, provider, billing, finance, observability, and payment dependencies.

The `seam-kind` bridge maps canonical `economic_*` evidence ref kinds into the short contract/runtime seam categories (`usage`, `cost`, `budget`, `replay`, `projection`). This keeps OperationSpec and runtime events compact while preserving the canonical neutral ref taxonomy for persisted evidence.


---

## @lssm-tech/lib.email

Description: (none)
Path: packages/libs/email
URL: /llms/lib.email

# @lssm-tech/lib.email

**Email sending via Scaleway SDK. Provides a provider-agnostic client interface for transactional email.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- Related ContractSpec packages include `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.email`

or

`bun add @lssm-tech/lib.email`

## Usage

Import the root entrypoint from `@lssm-tech/lib.email`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/client.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.
- `src/utils.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./client` resolves through `./src/client.ts`.
- Export `./types` resolves through `./src/types.ts`.
- Export `./utils` resolves through `./src/utils.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Client interface abstracts the provider; do not leak Scaleway-specific types into the public API.
- Keep the adapter boundary clean so the provider can be swapped without consumer changes.


---

## @lssm-tech/lib.evolution

Description: AI-powered contract evolution engine
Path: packages/libs/evolution
URL: /llms/lib.evolution

# @lssm-tech/lib.evolution

Website: https://contractspec.io

**AI-powered contract evolution engine.**

## What It Provides

- **Layer**: lib.
- **Consumers**: example-shared-ui, bundles.
- **Key dependencies**: ai-agent, contracts-spec, lifecycle, observability, schema.
- Related ContractSpec packages include `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/lib.observability`, ...

## Installation

`npm install @lssm-tech/lib.evolution`

or

`bun add @lssm-tech/lib.evolution`

## Usage

Import the root entrypoint from `@lssm-tech/lib.evolution`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/analyzer` is part of the package's public or composition surface.
- `src/approval` is part of the package's public or composition surface.
- `src/generator` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add changesets and apply pending fixes.
- Resolve lint, build, and type errors across nine packages.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- Evolution strategies affect contract migration paths; changes can break existing migrations.
- Depends on multiple core libs — verify compatibility when updating any dependency.
- Strategy selection logic must remain deterministic and auditable.


---

## @lssm-tech/lib.example-shared-ui

Description: (none)
Path: packages/libs/example-shared-ui
URL: /llms/lib.example-shared-ui

# @lssm-tech/lib.example-shared-ui

**Shared React components and hooks for ContractSpec example apps. Provides the common layout, editors, and overlays used across all examples.**

## What It Provides

- **Layer**: lib.
- **Consumers**: example apps.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.surface-runtime`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.surface-runtime`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.example-shared-ui`

or

`bun add @lssm-tech/lib.example-shared-ui`

## Usage

Import the root entrypoint from `@lssm-tech/lib.example-shared-ui`, or choose a documented subpath when you only need one part of the package surface. Use `NestedCommandShell` for embedded example previews that need command search and sectional navigation without mounting the app-level design-system `AppShell`/sidebar provider.

## Architecture

- `src/bundles/` contains bundle definitions and composition entrypoints.
- `src/EvolutionDashboard.tsx` is part of the package's public or composition surface.
- `src/EvolutionSidebar.tsx` is part of the package's public or composition surface.
- `src/hooks/` contains custom hooks for host applications.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/lib/` contains package-local helper utilities and adapters.
- `src/LocalDataIndicator.tsx` is part of the package's public or composition surface.
- `src/NestedCommandShell.tsx` provides an embedded, nested-safe command/navigation shell for examples that must not mount the app-level `AppShell` sidebar.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./bundles` resolves through `./src/bundles/index.ts`.
- Export `./bundles/ExampleTemplateBundle` resolves through `./src/bundles/ExampleTemplateBundle.ts`.
- Export `./EvolutionDashboard` resolves through `./src/EvolutionDashboard.tsx`.
- Export `./EvolutionSidebar` resolves through `./src/EvolutionSidebar.tsx`.
- Export `./hooks` resolves through `./src/hooks/index.ts`.
- Export `./hooks/useBehaviorTracking` resolves through `./src/hooks/useBehaviorTracking.ts`.
- Export `./hooks/useEvolution` resolves through `./src/hooks/useEvolution.ts`.
- Export `./hooks/useRegistryTemplates` resolves through `./src/hooks/useRegistryTemplates.ts`.
- Export `./hooks/useSpecContent` resolves through `./src/hooks/useSpecContent.ts`.
- The package publishes 30 total export subpaths; keep docs aligned with `package.json`.

## Public Shell Contract

`TemplateShell` is the reusable, nested-safe preview shell for example packages. It renders only content-scoped header, main, and optional aside regions, so embedded previews can sit inside host apps such as `ExampleWebPreview` or `web-landing` without creating another app-level `AppShell`, `SidebarProvider`, fixed application sidebar, or global navigation frame.

Import it from either the root package or the documented subpath:

```tsx
import { TemplateShell } from '@lssm-tech/lib.example-shared-ui';
// or
import { TemplateShell } from '@lssm-tech/lib.example-shared-ui/TemplateShell';
```

Public props:

- `title` and optional `description` fill the content-scoped preview header.
- `actions` renders header actions without taking ownership of host navigation.
- `sidebar` renders a bounded in-card aside beside the preview content.
- `showRuntimeIndicator` toggles the local-data indicator for sandboxes that already provide equivalent status chrome.
- `showSaveAction` and `saveProps` control the optional Studio save affordance.
- `children` render inside the preview main region.

Use `SpecDrivenTemplateShell` when a preview needs a `surface-runtime` bundle plan, but keep the same containment rule: shared example shells own preview content only, not app-level navigation.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add changesets and apply pending fixes.
- Contracts context, bundle exports, surface-runtime docs.

## Notes

- Low blast radius — only example apps depend on this package.
- `TemplateShell` is the shared layout for all examples; structural changes affect every example app.


---

## @lssm-tech/lib.execution-lanes

Description: Execution lanes orchestration contracts and runtime for ContractSpec.
Path: packages/libs/execution-lanes
URL: /llms/lib.execution-lanes

# @lssm-tech/lib.execution-lanes

Website: https://contractspec.io

Typed execution-lane contracts, registries, runtimes, evidence gating, and backend adapter ports for ContractSpec.

## What It Provides

- Lane contracts for `clarify`, `plan.consensus`, `complete.persistent`, and `team.coordinated`.
- Typed handoff artifacts including clarification artifacts, plan packs, completion records, team snapshots, and lane runtime state.
- Runtime primitives for consensus planning, persistent completion loops, coordinated team runs, lane selection, evidence gating, and in-memory persistence.
- Backend-neutral adapter ports for in-process, subagent, tmux, queue, and workflow-engine execution.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./types` resolves through `./src/types/index.ts`
- `./defaults` resolves through `./src/defaults/index.ts`
- `./interop` resolves through `./src/interop/index.ts`

## Notes

- The package stays runtime- and backend-neutral; storage-backed operator persistence belongs in integration and app layers.
- Evidence normalization and replay references align with `@lssm-tech/lib.harness`; this package does not introduce a second proof model.
- Role semantics live in typed role profiles, not prompt prose.
- Canonical artifact and evidence identifiers use spec-style snake_case names; readers normalize older hyphenated aliases for persisted compatibility.
- Command semantics for `/clarify`, `/plan`, `/plan --consensus`, `/complete`, and `/team` live in the typed `./interop` surface rather than in prompt prose alone.


---

## @lssm-tech/lib.exporter

Description: Compatibility exporter shim backed by the data-exchange core.
Path: packages/libs/exporter
URL: /llms/lib.exporter

# @lssm-tech/lib.exporter

Website: https://contractspec.io

**Compatibility exporter shim backed by the SchemaModel-first data exchange core.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- Legacy `toCsvGeneric(...)` and `toXmlGeneric(...)` wrappers preserved for compatibility.
- New `toJsonGeneric(...)` wrapper for the same legacy payload shape.
- Internally delegates to `@lssm-tech/lib.data-exchange-core`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.exporter`

or

`bun add @lssm-tech/lib.exporter`

## Usage

Import the root entrypoint from `@lssm-tech/lib.exporter`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- This package is now a compatibility surface; prefer `@lssm-tech/lib.data-exchange-core` for new work.
- Export format must stay consistent for downstream consumers; column order and encoding are part of the contract.
- Do not introduce platform-specific APIs (Node-only or browser-only) without a universal fallback.


---

## @lssm-tech/lib.feature-flags

Description: Feature flags and experiments module for ContractSpec applications
Path: packages/libs/feature-flags
URL: /llms/lib.feature-flags

# @lssm-tech/lib.feature-flags

Website: https://contractspec.io

**Feature flags and experiments module for ContractSpec applications.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, apps.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/lib.feature-flags`

or

`bun add @lssm-tech/lib.feature-flags`

## Usage

Import the root entrypoint from `@lssm-tech/lib.feature-flags`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/evaluation` is part of the package's public or composition surface.
- `src/events.ts` is package-level event definitions.
- `src/feature-flags.capability.ts` defines a capability surface.
- `src/feature-flags.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/feature-flags.docblock` resolves through `./src/docs/feature-flags.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./evaluation` resolves through `./src/evaluation/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./feature-flags.capability` resolves through `./src/feature-flags.capability.ts`.
- Export `./feature-flags.feature` resolves through `./src/feature-flags.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Flag evaluation logic must be deterministic — same input always produces same output.
- Capability and feature contracts are public API; changes are breaking.
- Follow the PostHog naming conventions defined in workspace rules for new flag names.


---

## @lssm-tech/lib.files

Description: Files, documents and attachments module for ContractSpec applications
Path: packages/libs/files
URL: /llms/lib.files

# @lssm-tech/lib.files

Website: https://contractspec.io

**Files, documents and attachments module for ContractSpec applications.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/lib.files`

or

`bun add @lssm-tech/lib.files`

## Usage

Import the root entrypoint from `@lssm-tech/lib.files`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/files.capability.ts` defines a capability surface.
- `src/files.feature.ts` defines a feature entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/files.docblock` resolves through `./src/docs/files.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./files.capability` resolves through `./src/files.capability.ts`.
- Export `./files.feature` resolves through `./src/files.feature.ts`.
- Export `./storage` resolves through `./src/storage/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Storage interface is the adapter boundary — do not couple consumers to a specific storage provider.
- File entity schema is shared; field changes require migration coordination.
- Capability contract is public API.


---

## @lssm-tech/lib.finance-ops-spec

Description: Provider-neutral internal finance operations contracts beyond BillingOS quote-to-cash.
Path: packages/libs/finance-ops-spec
URL: /llms/lib.finance-ops-spec

# `@lssm-tech/lib.finance-ops-spec`

Provider-neutral internal finance operations contracts beyond BillingOS quote-to-cash.

This package closes the first canonical ContractSpec slice for internal finance operations. It defines reviewable contracts and handoff packets; it does not execute provider actions or provide financial advice.

## Scope

Use this package to model:

- budgets, spend policies, and financial commitments;
- procurement requests and vendor compliance review;
- expenses and reimbursement handoffs;
- payroll, tax, and compliance handoffs;
- cashflow/runway policies, non-advisory runway hints, and accounting export review gates;
- CompanyOS authority, assurance evidence, and approval gates.

## Boundary

BillingOS owns quote-to-cash artifacts such as quotes, orders, invoices, payments, refunds, write-offs, accounting exports, and reconciliation. Finance ops may reference those artifacts for cashflow/runway and review context but must not redefine or execute them. This package also avoids bank, accounting, payroll, and tax provider execution.

## Public entrypoints

- `@lssm-tech/lib.finance-ops-spec` — root barrel
- `@lssm-tech/lib.finance-ops-spec/types` — contract schemas and types
- `@lssm-tech/lib.finance-ops-spec/validation` — semantic validation helpers
- `@lssm-tech/lib.finance-ops-spec/fixtures` — safe synthetic fixtures

## Commands

- `bun run test`
- `bun run typecheck`
- `bun run lint:check`
- `bun run build`


---

## @lssm-tech/lib.graphql-core

Description: Shared GraphQL core: Pothos builder factory, scalars, tracing & complexity
Path: packages/libs/graphql-core
URL: /llms/lib.graphql-core

# @lssm-tech/lib.graphql-core

Website: https://contractspec.io

**Shared GraphQL core: Pothos builder factory, scalars, tracing & complexity.**

## What It Provides

- **Layer**: lib.
- **Consumers**: graphql-federation, graphql-prisma, contracts-runtime-server-graphql, bundles.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.graphql-core`

or

`bun add @lssm-tech/lib.graphql-core`

## Usage

Import the root entrypoint from `@lssm-tech/lib.graphql-core`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run prebuild` — contractspec-bun-build prebuild
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Builder factory is consumed by all GraphQL packages — interface changes have high blast radius.
- Scalar definitions must stay aligned with the schema lib.
- Tracing and complexity plugins must not introduce runtime overhead in production without opt-in.


---

## @lssm-tech/lib.graphql-federation

Description: Pothos federation helpers and subgraph schema export utilities
Path: packages/libs/graphql-federation
URL: /llms/lib.graphql-federation

# @lssm-tech/lib.graphql-federation

Website: https://contractspec.io

**Pothos federation helpers and subgraph schema export utilities.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles with federated GraphQL.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.graphql-federation`

or

`bun add @lssm-tech/lib.graphql-federation`

## Usage

Import the root entrypoint from `@lssm-tech/lib.graphql-federation`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run prebuild` — contractspec-bun-build prebuild
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Federation directives must comply with the Apollo Federation spec; non-compliant changes break gateway composition.
- Depends on graphql-core — keep builder factory usage aligned.


---

## @lssm-tech/lib.graphql-prisma

Description: Pothos + Prisma builder factory with injectable client/DMMF
Path: packages/libs/graphql-prisma
URL: /llms/lib.graphql-prisma

# @lssm-tech/lib.graphql-prisma

Website: https://contractspec.io

**Pothos + Prisma builder factory with injectable client/DMMF.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles with Prisma.
- Related ContractSpec packages include `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.graphql-prisma`

or

`bun add @lssm-tech/lib.graphql-prisma`

## Usage

Import the root entrypoint from `@lssm-tech/lib.graphql-prisma`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run prebuild` — contractspec-bun-build prebuild
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Prisma client injection must stay lazy — eagerly importing the client breaks tree-shaking and test isolation.
- DMMF handling is version-sensitive; Prisma major upgrades require validation here first.
- Depends on graphql-core — keep builder factory usage aligned.


---

## @lssm-tech/lib.growth-spec

Description: Provider-neutral growth and marketing operation contracts for autonomous-company campaign, lifecycle, and publishing handoffs.
Path: packages/libs/growth-spec
URL: /llms/lib.growth-spec

# `@lssm-tech/lib.growth-spec`

Provider-neutral growth and marketing operation contracts for autonomous-company campaign, lifecycle, and publishing handoffs.

This package closes the first canonical ContractSpec slice for acquisition and lifecycle growth planning. It defines reviewable contract packets; it does not execute provider actions.

## Scope

Use this package to model:

- audience segments and consent/preference boundaries;
- campaigns, experiments, content blocks, landing pages, copy variants, and SEO metadata;
- lifecycle message plans as draft/review handoffs;
- attribution model references and measurable objectives;
- brand/safety review, CompanyOS authority, assurance evidence, and approval gates;
- provider/channel bindings as non-secret references only.

## Boundary

This package does not deliver messages, publish CMS pages, buy ads, write CRM records, compute analytics dashboards, or own in-product personalization runtime decisions. Use branded references to analytics, personalization, communication, CompanyOS, assurance, integrations, and orchestration surfaces.

## Public entrypoints

- `@lssm-tech/lib.growth-spec` — root barrel
- `@lssm-tech/lib.growth-spec/types` — contract schemas and types
- `@lssm-tech/lib.growth-spec/validation` — semantic validation helpers
- `@lssm-tech/lib.growth-spec/fixtures` — safe synthetic fixtures

## Commands

- `bun run test`
- `bun run typecheck`
- `bun run lint:check`
- `bun run build`


---

## @lssm-tech/lib.harness

Description: Harness orchestration, policy, evidence, and evaluation runtime.
Path: packages/libs/harness
URL: /llms/lib.harness

# @lssm-tech/lib.harness

Website: https://contractspec.io

**Harness orchestration, policy, evidence normalization, replay bundling, and evaluation runtime for controlled inspection and proof generation.**

## What It Provides

- Provides the mode-agnostic harness core used by higher-level runtime adapters and harness-aware workflows.
- Exports focused surfaces for assertions, evidence normalization, orchestration, policy classification, replay bundles, and shared types.
- Acts as the central execution model for controlled evaluation, proof generation, and inspection flows.
- Executes scenario `setup` and `reset` hooks through an explicit `HarnessScenarioHookExecutor`, enforces required evidence, and applies scenario success rules during evaluation.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.

## Installation

`npm install @lssm-tech/lib.harness`

or

`bun add @lssm-tech/lib.harness`

## Usage

Import the root entrypoint from `@lssm-tech/lib.harness`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/assertions/` contains assertion-engine logic.
- `src/evidence/` normalizes harness evidence into runtime-friendly shapes.
- `src/orchestration/` runs suites and evaluation pipelines.
- `src/policy/` classifies and applies harness policies.
- `src/replay/` packages replay bundles and reproducible outputs.
- `src/types.ts` contains shared public types.

## Public Entry Points

- Exports the root harness runtime plus assertion, evidence, orchestration, policy, replay, and type subpaths.
- Export `.` resolves through `./src/index.ts`.
- Export `./assertions/engine` resolves through `./src/assertions/engine.ts`.
- Export `./evidence/normalizer` resolves through `./src/evidence/normalizer.ts`.
- Export `./orchestration/evaluation-runner` resolves through `./src/orchestration/evaluation-runner.ts`.
- Export `./orchestration/runner` resolves through `./src/orchestration/runner.ts`.
- Export `./policy/classifier` resolves through `./src/policy/classifier.ts`.
- Export `./replay/bundle` resolves through `./src/replay/bundle.ts`.
- Export `./types` resolves through `./src/types.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add a first-class harness system for controlled inspection, testing, evaluation, and proof generation.
- Implement scenario setup/reset hooks, required evidence checks, success-rule evaluation, and suite mode/target propagation.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Hook execution is intentionally injected through `HarnessScenarioHookExecutor`; the harness core does not import operation registries or application runtimes implicitly.

## Canonical Names and Shim Mapping

> **For VoiceOps hackathon consumers** — this section explains the canonical export names and shows how to create local shims when your codebase uses different names.

`src/index.ts` uses `export *` barrels, so all canonical names are importable directly from `@lssm-tech/lib.harness`.

### Name Map

| Wished-for name | Canonical export | Source file |
|---|---|---|
| `classifyAction` | `classifyHarnessStep` | `src/policy/classifier.ts` |
| `buildReplayBundle` | `createHarnessReplayBundle` | `src/replay/bundle.ts` |
| `normalizeEvidence` | `normalizeArtifact` / `normalizeArtifacts` | `src/evidence/normalizer.ts` |

**`classifyHarnessStep`** — evaluates a single scenario step against policy rules and returns a `HarnessPolicyDecision` (`verdict: 'autonomous' | 'assist' | 'blocked'`, `requiresApproval`, `reasons`).

**`createHarnessReplayBundle`** — assembles a `HarnessReplayBundle` from a completed run record, assertion results, and captured artifacts. Body bytes are stripped from the artifact list so bundles are safe to serialize and store.

**`normalizeArtifact` / `normalizeArtifacts`** — converts raw `HarnessCapturedArtifact` inputs into fully-formed `HarnessStoredArtifact` values, generating stable ids, timestamps, and SHA-256 content hashes when callers do not supply them. `normalizeArtifacts` is the batch wrapper over `normalizeArtifact`.

### Copy-pastable shim file

Create `src/lssm-shims.ts` in your hackathon repo to re-export the canonical names under the aliases your team already uses:

```typescript
// src/lssm-shims.ts
// Local aliases for @lssm-tech/lib.harness canonical exports.
// DO NOT change the canonical package — add aliases here instead.

export {
  classifyHarnessStep as classifyAction,
  canFallbackToVisual,
} from "@lssm-tech/lib.harness";

export {
  createHarnessReplayBundle as buildReplayBundle,
  summarizeHarnessReplayBundle,
} from "@lssm-tech/lib.harness";

export {
  normalizeArtifact as normalizeEvidence,
  normalizeArtifacts,
} from "@lssm-tech/lib.harness";

// Re-export shared types so consumers only import from one shim path.
export type {
  HarnessPolicyDecision,
  HarnessReplayBundle,
  HarnessStoredArtifact,
} from "@lssm-tech/lib.harness";
```

Then in your hackathon code, import from the shim instead of the package directly:

```typescript
import { classifyAction, buildReplayBundle, normalizeEvidence } from "./lssm-shims";
```

This keeps your team's preferred names without modifying the upstream package or touching `src/index.ts`.


---

## @lssm-tech/lib.identity-rbac

Description: Identity, Organizations, and RBAC module for ContractSpec applications
Path: packages/libs/identity-rbac
URL: /llms/lib.identity-rbac

# @lssm-tech/lib.identity-rbac

Website: https://contractspec.io

**Identity, Organizations, and RBAC module for ContractSpec applications.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, apps.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.

## Installation

`npm install @lssm-tech/lib.identity-rbac`

or

`bun add @lssm-tech/lib.identity-rbac`

## Usage

Import the root entrypoint from `@lssm-tech/lib.identity-rbac`, or choose a documented subpath when you only need one part of the package surface.

The `RBACPolicyEngine` can evaluate shared ContractSpec `PolicyRequirement` objects against static role templates, dynamic role/binding sources, or a hybrid of both. Dynamic persistence is intentionally app-owned; the library consumes provider results and applies deterministic precedence (source unavailable fails closed, expired/out-of-scope bindings are ignored, explicit deny wins, dynamic grants extend static templates).
`DatabaseRolePermissionSource` is the additive database-backed source helper: hosts load role bindings through their own provider/adapter, while this package applies the same deterministic deny precedence and fail-closed default without depending on Drizzle or PostgreSQL.

```ts
import { RBACPolicyEngine, StaticRolePermissionSource } from "@lssm-tech/lib.identity-rbac/policies";

const source = new StaticRolePermissionSource({
  roles: [
    { key: "billing.viewer", permissions: ["invoice.read"], source: "static" },
  ],
});

const engine = new RBACPolicyEngine();
const decision = await engine.evaluateRequirement({
  mode: "static",
  requirements: { permissions: { any: ["invoice.read"] } },
  subject: { id: "user-1", roles: ["billing.viewer"] },
  source,
});
```

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/identity-rbac.capability.ts` defines a capability surface.
- `src/identity-rbac.feature.ts` defines a feature entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/policies` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./contracts/organization` resolves through `./src/contracts/organization.ts`.
- Export `./contracts/rbac` resolves through `./src/contracts/rbac.ts`.
- Export `./contracts/user` resolves through `./src/contracts/user.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./entities/organization` resolves through `./src/entities/organization.ts`.
- Export `./entities/rbac` resolves through `./src/entities/rbac.ts`.
- Export `./entities/user` resolves through `./src/entities/user.ts`.
- Export `./events` resolves through `./src/events.ts`.
- The package publishes 14 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- **Security-critical** — RBAC policies control access across the platform.
- Role and permission schemas must stay backward-compatible; removals are breaking.
- Capability contract is public API; policy evaluation must be deterministic.


---

## @lssm-tech/lib.image-gen

Description: AI-powered image generation for hero, social, thumbnail, OG, and illustration
Path: packages/libs/image-gen
URL: /llms/lib.image-gen

# @lssm-tech/lib.image-gen

Website: https://contractspec.io

**AI-powered image generation for hero, social, thumbnail, OG, and illustration.**

## What It Provides

- **Layer**: lib.
- **Consumers**: video-gen, bundles.
- `src/docs/` contains docblocks and documentation-facing exports.
- Related ContractSpec packages include `@lssm-tech/lib.content-gen`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/lib.image-gen`

or

`bun add @lssm-tech/lib.image-gen`

## Usage

Import the root entrypoint from `@lssm-tech/lib.image-gen`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/generators` is part of the package's public or composition surface.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/presets` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs/generators.docblock` resolves through `./src/docs/generators.docblock.ts`.
- Export `./docs/image-gen.docblock` resolves through `./src/docs/image-gen.docblock.ts`.
- Export `./generators` resolves through `./src/generators/index.ts`.
- Export `./generators/image-generator` resolves through `./src/generators/image-generator.ts`.
- Export `./generators/prompt-builder` resolves through `./src/generators/prompt-builder.ts`.
- Export `./generators/style-resolver` resolves through `./src/generators/style-resolver.ts`.
- Export `./i18n` resolves through `./src/i18n/index.ts`.
- Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`.
- Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`.
- The package publishes 20 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add @lssm-tech/lib.image-gen package with full test suite.

## Notes

- Generator interface is shared with the content-gen pattern; keep the adapter shape consistent.
- Preset schemas affect all generated images; field changes require validation across consumers.
- Do not hardcode locale-specific strings outside the i18n subpath.


---

## @lssm-tech/lib.infra-ops-spec

Description: Provider-neutral infrastructure operations contracts and evidence for autonomous-company deployment and incident loops.
Path: packages/libs/infra-ops-spec
URL: /llms/lib.infra-ops-spec

# `@lssm-tech/lib.infra-ops-spec`

Provider-neutral infrastructure operations contracts and evidence for autonomous-company deployment and incident loops.

This package closes the Phase 2 infra-ops gap as a **contract/evidence** layer. It does not deploy services, page humans, resolve secrets, run migrations, or call provider APIs.

## Public entrypoints

- `@lssm-tech/lib.infra-ops-spec` — root barrel
- `@lssm-tech/lib.infra-ops-spec/types` — schemas and TypeScript types
- `@lssm-tech/lib.infra-ops-spec/fixtures` — canonical deployment and incident fixtures
- `@lssm-tech/lib.infra-ops-spec/validation` — semantic validation helpers

## Contract families

The package models:

- environments, runtime targets, and services;
- deployments, releases, migration windows, rollbacks, and pipelines;
- health/readiness/liveness checks, SLOs, monitors, and alerts;
- incidents, on-call ownership, escalation, mitigation, and postmortems;
- capacity plans, cost budgets, secret refs, operational risks, approvals, and evidence receipts.

## Boundary

Adjacent systems are referenced through branded refs only:

- progressive delivery rollout/rollback refs;
- observability metric/trace/log refs;
- job schedule refs;
- integration capability refs;
- CompanyOS policy/owner refs;
- orchestration workflow refs;
- cost budget and metering usage refs.

No provider SDKs, credentials, live provider config, network calls, deployment runners, incident automation, queues, or secret resolution are included.


---

## @lssm-tech/lib.jobs

Description: Background jobs and scheduler module for ContractSpec applications
Path: packages/libs/jobs
URL: /llms/lib.jobs

# @lssm-tech/lib.jobs

Website: https://contractspec.io

**Background jobs and scheduler module for ContractSpec applications.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Installation

`npm install @lssm-tech/lib.jobs`

or

`bun add @lssm-tech/lib.jobs`

## Usage

Import the root entrypoint from `@lssm-tech/lib.jobs`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/jobs.capability.ts` defines a capability surface.
- `src/jobs.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./handlers/gmail-sync-handler` resolves through `./src/handlers/gmail-sync-handler.ts`.
- Export `./handlers/ping-job` resolves through `./src/handlers/ping-job.ts`.
- Export `./handlers/storage-document-handler` resolves through `./src/handlers/storage-document-handler.ts`.
- Export `./jobs.capability` resolves through `./src/jobs.capability.ts`.
- Export `./jobs.feature` resolves through `./src/jobs.feature.ts`.
- The package publishes 18 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Queue and scheduler interfaces are adapter boundaries — do not leak implementation details.
- Job entity schema is shared across consumers; changes require migration awareness.
- Capability contract (`jobs.capability`) is public API — treat as a breaking-change surface.


---

## @lssm-tech/lib.knowledge

Description: RAG and knowledge base primitives
Path: packages/libs/knowledge
URL: /llms/lib.knowledge

# @lssm-tech/lib.knowledge

`@lssm-tech/lib.knowledge` provides the retrieval, ingestion, query, and access-control primitives used to turn documents and external content into searchable knowledge for agents and workflows.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.knowledge`

or

`npm install @lssm-tech/lib.knowledge`

## What belongs here

This package currently owns these related concerns:

- Retrieval contracts and implementations: `KnowledgeRetriever`, `StaticRetriever`, and `VectorRetriever`.
- Ingestion and indexing pipeline pieces: `DocumentProcessor`, `EmbeddingService`, `VectorIndexer`, and ingestion adapters.
- Retrieval-augmented query flow: `KnowledgeQueryService` and `KnowledgeQueryOptions`.
- Runtime convenience for OSS consumers: `KnowledgeRuntime` and `createKnowledgeRuntime`.
- First-class Gmail and Google Drive orchestration for ingestion/query flows.
- Mutation governance helpers for dry-runs, approvals, idempotency, audit evidence, and outbound-send gates.
- CompanyOS connector readiness manifests for deterministic support desk, CRM, warehouse, collaboration, project, docs, email, and meeting coverage without live provider calls or production writes.
- Access guardrails and localization: `KnowledgeAccessGuard` and the `i18n` surface.

Use this package when you need the knowledge-layer primitives inside ContractSpec. It is not the source of truth for knowledge-space specs, tenant bindings, provider SDKs, or background job orchestration.

## Core workflows

### Quickstart: one runtime for ingest + retrieve + answer

```ts
import { createKnowledgeRuntime } from "@lssm-tech/lib.knowledge";

const knowledge = createKnowledgeRuntime({
  collection: "knowledge-support-faq",
  namespace: "tenant-acme",
  spaceKey: "support-faq",
  embeddings: embeddingProvider,
  vectorStore: vectorStoreProvider,
  llm: llmProvider,
});

await knowledge.ingestDocument({
  id: "faq-rotate-key",
  mimeType: "text/plain",
  data: new TextEncoder().encode("Rotate API keys from Settings > API."),
  metadata: { locale: "en", category: "canonical" },
});

const snippets = await knowledge.retrieve("How do I rotate a key?", {
  spaceKey: "support-faq",
  tenantId: "tenant-acme",
  locale: "en",
  category: "canonical",
});

const answer = await knowledge.query("How do I rotate a key?", {
  namespace: "tenant-acme",
  filter: { locale: "en" },
});
```

### Sync Gmail and Google Drive into knowledge

```ts
import { createKnowledgeRuntime } from "@lssm-tech/lib.knowledge";

const knowledge = createKnowledgeRuntime({
  collection: "knowledge-workspace",
  namespace: "tenant-acme",
  spaceKey: "workspace",
  embeddings: embeddingProvider,
  vectorStore: vectorStoreProvider,
  gmail: gmailProvider,
  drive: googleDriveProvider,
  deltaCheckpointStore,
});

await knowledge.syncGmail(
  { label: "support" },
  {
    sourceId: "src_gmail_support",
    evidenceRef: "audit://sync/gmail/support",
  },
);

await knowledge.syncDriveFiles(
  { query: "mimeType = 'text/plain' and trashed = false" },
  {
    sourceId: "src_drive_support",
    evidenceRef: "audit://sync/drive/support",
  },
);

await knowledge.watchDriveChanges(
  {
    channelId: "drive-support-watch",
    webhookUrl: "https://app.example.com/webhooks/google-drive",
  },
  { sourceId: "src_drive_support" },
);
```

Gmail and Drive sync use provider contracts from `@lssm-tech/lib.contracts-integrations`. Delta-aware callers can pass and receive lease, cursor/watermark, webhook channel, provider-event, dedupe, idempotency, replay-checkpoint, and tombstone state through `ProviderDeltaSyncState`. When `deltaCheckpointStore` is configured, `syncGmail()`, `syncDriveFiles()`, and `watchDriveChanges()` load the last checkpoint by source ID before calling the provider, then save the returned provider delta before the caller acknowledges sync work.

### Govern knowledge mutations

```ts
import {
  executeGovernedKnowledgeMutation,
} from "@lssm-tech/lib.knowledge/governance";

const result = await executeGovernedKnowledgeMutation(
  {
    operation: "gmail.message.send",
    requiresApproval: true,
    outboundSend: true,
    governance: {
      idempotencyKey: "tenant:gmail-send:123",
      auditEvidence: { evidenceRef: "audit://gmail-send/123" },
      approvalRefs: [{ id: "approval-123" }],
      outboundSendGate: {
        status: "approved",
        evidenceRef: "gate://gmail-send/123",
      },
    },
  },
  () => gmailProvider.sendMessage(message),
  { audit: (envelope) => auditTrail.write(envelope) },
);
```

Set `governance.dryRun` to inspect the plan without executing. Non-dry-run mutations require an idempotency key and audit evidence; approval-required and outbound-send operations require approval refs, and outbound sends require an approved send gate. Every result includes an `auditEnvelope` so app runtimes, Connect review packets, and provider replay tooling can reference the same decision evidence.

### Ingest documents into a vector index

```ts
import {
  DocumentProcessor,
  EmbeddingService,
  StorageIngestionAdapter,
  VectorIndexer,
} from "@lssm-tech/lib.knowledge";

const processor = new DocumentProcessor();
const embeddings = new EmbeddingService(embeddingProvider);
const indexer = new VectorIndexer(vectorStoreProvider, {
  collection: "knowledge-docs",
  namespace: "tenant-acme",
});

const adapter = new StorageIngestionAdapter(processor, embeddings, indexer);
await adapter.ingestObject(objectFromStorageProvider);
```

### Run retrieval or RAG queries

```ts
import {
  KnowledgeQueryService,
  createVectorRetriever,
} from "@lssm-tech/lib.knowledge";

const retriever = createVectorRetriever({
  embeddings: embeddingProvider,
  vectorStore: vectorStoreProvider,
  spaceCollections: {
    "support-faq": "knowledge-support-faq",
  },
});

const snippets = await retriever.retrieve("How do I rotate a key?", {
  spaceKey: "support-faq",
  topK: 3,
  locale: "en",
  category: "canonical",
});

const queryService = new KnowledgeQueryService(
  embeddingProvider,
  vectorStoreProvider,
  llmProvider,
  {
    collection: "knowledge-support-faq",
    namespace: "tenant-acme",
    topK: 5,
  }
);
const answer = await queryService.query("How do I rotate a key?", {
  namespace: "tenant-acme",
  topK: 3,
  filter: { locale: "en" },
});
```

### Use static knowledge for tests or lightweight examples

```ts
import { createStaticRetriever } from "@lssm-tech/lib.knowledge";

const retriever = createStaticRetriever({
  "product-canon": [
    "Rotate API keys from Settings > API.",
    "Only cite reviewed canon content in answers.",
  ].join("\n"),
});

const snippets = await retriever.retrieve("rotate", {
  spaceKey: "product-canon",
  topK: 1,
});
```

### Localize prompts and access messages

```ts
import { createKnowledgeI18n } from "@lssm-tech/lib.knowledge/i18n";

const i18n = createKnowledgeI18n("fr");
const noResults = i18n.t("query.noResults");
```

Typical flow:

1. Extract fragments from raw content.
2. Embed fragments and upsert them into a vector collection.
3. Use `GmailIngestionAdapter`, `DriveIngestionAdapter`, or runtime sync helpers when content originates from workspace providers.
4. Retrieve snippets through a retriever or generate an answer through `KnowledgeQueryService`.
5. Gate reads and writes with `KnowledgeAccessGuard`, and gate mutations with the governance helpers when operating against external systems.

## API map

### Retrieval

- `KnowledgeRetriever`: shared retrieval interface for semantic and static retrieval.
- `RetrieverConfig`: shared defaults for retriever implementations.
- `StaticRetriever` and `createStaticRetriever`: in-memory, line-oriented retrieval for simple spaces and tests.
- `VectorRetriever` and `createVectorRetriever`: embedding + vector-store backed retrieval.
- `RetrievalOptions`: query filters such as `spaceKey`, `topK`, `minScore`, `tenantId`, `locale`, `category`, and provider filter metadata.
- `RetrievalResult`: returned content, source, score, and optional metadata.

### Query

- `KnowledgeQueryService`: embed -> search -> prompt -> LLM chat flow for knowledge-backed answers.
- `KnowledgeQueryConfig`: collection, namespace, prompt, filter, `topK`, and locale defaults.
- `KnowledgeQueryOptions`: per-query overrides for namespace, `topK`, filter, locale, and prompt.
- `KnowledgeAnswer`: answer text, references, and optional token usage.

### Ingestion

- `RawDocument`, `DocumentFragment`, and `DocumentProcessor`: extract raw document content into indexable fragments.
- `EmbeddingService`: batch fragment embeddings through an `EmbeddingProvider`.
- `VectorIndexer` and `VectorIndexConfig`: map embeddings to `VectorStoreProvider.upsert()` requests and persist canonical `payload.text` content for later retrieval/query use.
- `GmailIngestionAdapter`: convert email threads into plaintext documents and index them.
- `DriveIngestionAdapter`: convert Google Drive files into raw documents, skip tombstones, and index them.
- `StorageIngestionAdapter`: fetch object content and run the same process/index pipeline.
- `KnowledgeRuntime` and `createKnowledgeRuntime`: convenience composition for the common ingest -> sync -> retrieve -> answer path.
- `KnowledgeProviderDeltaCheckpointStore`: optional runtime checkpoint store for loading and saving Gmail/Drive provider delta state per source.
- `KnowledgePersistencePort`: optional database persistence port for fragments, sync checkpoints, and query evidence. It records provenance without changing retriever or `KnowledgeAnswer` shapes.

### Mutation governance

- `KnowledgeMutationRequest`: describes a proposed mutation, whether it needs approval, and whether it sends outbound content.
- `KnowledgeMutationGovernance`: carries dry-run, approval refs, idempotency key, audit evidence, and outbound-send gate state.
- `evaluateKnowledgeMutationGovernance`: returns the plan, missing evidence, and block reasons without executing.
- `executeGovernedKnowledgeMutation`: executes only when the plan is allowed; otherwise returns `dry_run` or `blocked`.

### Guardrails and i18n

- `KnowledgeAccessGuard` and `KnowledgeAccessGuardOptions`: policy-aware checks for read/write/search operations.
- `KnowledgeAccessContext` and `KnowledgeAccessResult`: runtime input/output contracts for access checks.
- `createKnowledgeI18n` and `getDefaultI18n`: localization entrypoints for prompts, guard messages, and ingestion formatting.
- `./i18n`, `./i18n/catalogs/*`, `./i18n/keys`, `./i18n/locale`, and `./i18n/messages`: public i18n subpaths.

## Public entrypoints

The root barrel at `src/index.ts` re-exports public symbols from:

- `./access`
- `./ingestion`
- `./knowledge.feature`
- `./query`
- `./runtime`
- `./retriever`
- `./types`
- `./vector-payload`

Published subpaths from `package.json` are grouped around:

- access: `./access`, `./access/guard`
- retrieval: `./retriever`, `./retriever/interface`, `./retriever/static-retriever`, `./retriever/vector-retriever`
- query: `./query`, `./query/service`
- ingestion: `./ingestion`, `./ingestion/document-processor`, `./ingestion/drive-adapter`, `./ingestion/embedding-service`, `./ingestion/gmail-adapter`, `./ingestion/storage-adapter`, `./ingestion/vector-indexer`
- governance: `./governance`
- feature/runtime helpers: `./knowledge.feature`, root `KnowledgeRuntime` / `createKnowledgeRuntime`
- i18n: `./i18n`, `./i18n/catalogs`, `./i18n/catalogs/en`, `./i18n/catalogs/es`, `./i18n/catalogs/fr`, `./i18n/keys`, `./i18n/locale`, `./i18n/messages`
- shared types/helpers: `./types`, `./vector-payload`

Use `package.json` as the exhaustive source of truth for subpaths; the README calls out the clusters that matter most to consumers.

## Operational semantics and gotchas

- `DocumentProcessor` only ships built-in extractors for `text/plain` and `application/json`.
- If no extractor matches, `DocumentProcessor.process()` throws unless you registered a fallback such as `*/*`.
- If an extractor returns no fragments, `DocumentProcessor.process()` returns one empty fragment for the document.
- `EmbeddingService` batches fragments; the default batch size is `16`.
- `StaticRetriever.retrieve()` does simple line-level substring matching. It is not semantic retrieval.
- `StaticRetriever` honors `topK` and `minScore`, but its scores are always `1.0` for matching lines.
- `VectorRetriever.retrieve()` returns `[]` when the requested `spaceKey` is not mapped to a collection.
- `VectorRetriever` uses `tenantId` as the vector-store namespace when provided and automatically merges typed `locale` / `category` filters into the provider filter payload.
- `VectorIndexer.upsert()` stores fragment text under `payload.text`, together with merged fragment/config metadata and `documentId`. Fragment metadata wins over config metadata when keys collide.
- `KnowledgeQueryService` always runs embed -> vector search -> prompt build -> `LLMProvider.chat()`, using indexed `payload.text` as the primary context source and falling back to legacy `payload.content` when needed. Per-query overrides let you change namespace, `topK`, filter, locale, and prompt without rebuilding the service.
- `KnowledgeAccessGuard` defaults to blocking writes to `external` and `ephemeral` knowledge categories.
- `KnowledgeAccessGuard` also blocks writes when `ResolvedKnowledge.space.access.automationWritable` is `false`.
- `KnowledgeAccessGuard` defaults to requiring workflow binding and not requiring agent binding. If a scoped workflow or agent allow-list exists, missing names are denied rather than silently bypassed.
- `GmailIngestionAdapter` converts threads into plaintext and strips HTML when text bodies are missing.
- `DriveIngestionAdapter` indexes Google Drive files through the same processor -> embedding -> indexer path and skips tombstoned metadata or file records before indexing.
- `KnowledgeRuntime.syncGmail()`, `KnowledgeRuntime.syncDriveFiles()`, and `KnowledgeRuntime.watchDriveChanges()` are convenience orchestration methods; provider scheduling, credential refresh, and long-running background sync remain outside this package.
- Runtime sync helpers load and save `ProviderDeltaSyncState` through the optional checkpoint store when a source ID is provided.
- `KnowledgeRuntime` can call an optional persistence port after ingestion/query to store fragments and query evidence; failures are explicit host-adapter concerns rather than hidden vector-store behavior.
- `executeGovernedKnowledgeMutation()` never executes dry-runs or blocked mutations.
- Non-dry-run mutations require `idempotencyKey` and `auditEvidence.evidenceRef`.
- Mutation execution returns an audit envelope and can call an audit sink before returning.
- Outbound sends require an approved `outboundSendGate` and at least one approval ref.
- This package localizes access messages, query prompts, and Gmail formatting through the `i18n` surface.

## When not to use this package

- Do not use it as a vector store implementation.
- Do not use it as an embedding-model implementation.
- Do not use it as a full sync scheduler or background job system.
- Do not use it as the source of truth for `KnowledgeSpaceSpec`, knowledge sources, or tenant bindings.

## Related packages

- `@lssm-tech/lib.contracts-integrations`: provider interfaces used by vector, embedding, LLM, email, and storage integrations.
- `@lssm-tech/lib.contracts-spec`: source of knowledge-space specs, resolved bindings, and shared translation helpers.
- `@lssm-tech/lib.ai-agent`: major consumer of retrieval and query contracts.
- `@lssm-tech/example.knowledge-canon`: runnable package-level example of binding knowledge spaces and answering through `lib.knowledge`.
- Context-storage modules and bundles in the repo reuse the ingestion pipeline primitives for document indexing flows.

## Local commands

- `bun run lint:check`
- `bun run typecheck`
- `bun run test`

## Provider-free release guardrails

CompanyOS AI OS release narratives rely on this package as provider-free knowledge evidence. Stale runbook or low-confidence evidence must remain blocked before action, and non-dry-run knowledge mutations require approval or audit references before execution.


---

## @lssm-tech/lib.lifecycle

Description: Contract lifecycle management primitives
Path: packages/libs/lifecycle
URL: /llms/lib.lifecycle

# @lssm-tech/lib.lifecycle

Website: https://contractspec.io

**Contract lifecycle management primitives.**

## What It Provides

- **Layer**: lib.
- **Consumers**: analytics, evolution, observability, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.lifecycle`

or

`bun add @lssm-tech/lib.lifecycle`

## Usage

Import the root entrypoint from `@lssm-tech/lib.lifecycle`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types` is part of the package's public or composition surface.
- `src/utils/` contains internal utility functions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Fix small issues.
- Add full i18n support across all 10 packages (en/fr/es, 460 keys).

## Notes

- Lifecycle stage definitions are shared across the platform — changes are high-impact.
- Stage transitions must be deterministic; no side effects in transition logic.
- Consumed by analytics and observability — schema changes affect downstream telemetry.


---

## @lssm-tech/lib.logger

Description: Comprehensive logging library optimized for Bun with ElysiaJS integration
Path: packages/libs/logger
URL: /llms/lib.logger

# @lssm-tech/lib.logger

Website: https://contractspec.io

**Comprehensive logging library optimized for Bun with ElysiaJS integration.**

## What It Provides

- **Layer**: lib.
- **Consumers**: email, jobs, contracts-runtime-server-mcp, bundles, apps.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.logger`

or

`bun add @lssm-tech/lib.logger`

## Usage

Import the root entrypoint from `@lssm-tech/lib.logger`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/context.browser.ts` is part of the package's public or composition surface.
- `src/context.node.ts` is part of the package's public or composition surface.
- `src/context.ts` is part of the package's public or composition surface.
- `src/elysia-plugin.ts` is part of the package's public or composition surface.
- `src/formatters.ts` is part of the package's public or composition surface.
- `src/index.browser.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `types`, `browser`, `default`.
- Export `./context` resolves through `types`, `browser`, `node`, ...
- Export `./context.browser` resolves through `./src/context.browser.ts`.
- Export `./context.node` resolves through `./src/context.node.ts`.
- Export `./elysia-plugin` resolves through `./src/elysia-plugin.ts`.
- Export `./formatters` resolves through `./src/formatters.ts`.
- Export `./index.browser` resolves through `./src/index.browser.ts`.
- Export `./logger` resolves through `types`, `browser`, `node`, ...
- Export `./logger.browser` resolves through `./src/logger.browser.ts`.
- Export `./logger.node` resolves through `./src/logger.node.ts`.
- The package publishes 15 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Logger interface is used across the entire stack — breaking changes affect everything.
- Structured log format must stay JSON-compatible for log aggregation pipelines.
- Elysia plugin must not break the middleware chain; preserve `onRequest`/`onAfterHandle` order.


---

## @lssm-tech/lib.metering

Description: Usage metering and billing core module for ContractSpec applications
Path: packages/libs/metering
URL: /llms/lib.metering

# @lssm-tech/lib.metering

Website: https://contractspec.io

**Usage metering and billing core module for ContractSpec applications.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/lib.metering`

or

`bun add @lssm-tech/lib.metering`

## Usage

Import the root entrypoint from `@lssm-tech/lib.metering`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/aggregation` is part of the package's public or composition surface.
- `src/analytics` is part of the package's public or composition surface.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./aggregation` resolves through `./src/aggregation/index.ts`.
- Export `./analytics/posthog-metering` resolves through `./src/analytics/posthog-metering.ts`.
- Export `./analytics/posthog-metering-reader` resolves through `./src/analytics/posthog-metering-reader.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/metering.docblock` resolves through `./src/docs/metering.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./metering.capability` resolves through `./src/metering.capability.ts`.
- The package publishes 11 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Resolve lint, build, and type errors across nine packages.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- Aggregation logic must stay deterministic — non-determinism causes billing discrepancies.
- Billing-related schemas are compliance-sensitive; changes require review.
- Capability contract (`metering.capability`) is public API — treat as a breaking-change surface.


---

## @lssm-tech/lib.mobile-control

Description: Builder mobile-control primitives for review cards, parity, and deep-link-safe actions.
Path: packages/libs/mobile-control
URL: /llms/lib.mobile-control

# @lssm-tech/lib.mobile-control

Website: https://contractspec.io

Typed Builder mobile-control primitives for review cards, parity aggregation, and channel-safe deep-link actions.

## What It Provides

- Mobile parity aggregation for Builder blueprints and review workflows.
- Mobile review card factories shared by Builder runtime and UI surfaces.
- Default card actions that preserve a card/deep-link inspection path for critical review flows.

## Public Entry Points

- `.` resolves through `./src/index.ts`

## Notes

- This package is a compatibility surface. Prefer additive evolution.
- It exists to keep mobile-specific control-plane behavior reusable without duplicating Builder runtime logic.


---

## @lssm-tech/lib.notification

Description: Library-first notification contracts, schema, channels, templates, and i18n for ContractSpec applications
Path: packages/libs/notification
URL: /llms/lib.notification

# `@lssm-tech/lib.notification`

Library-first notification helpers for ContractSpec applications.

This package owns reusable notification entities, schema contributions, channels, templates, and i18n catalogs. Canonical notification contracts, capability metadata, and feature metadata are re-exported from `@lssm-tech/lib.contracts-spec/notifications`.

## Compatibility

- `notificationsSchemaContribution.moduleId` is `@lssm-tech/lib.notification`.
- `legacyNotificationsSchemaContribution.moduleId` is `@lssm-tech/module.notifications`.
- The deprecated `@lssm-tech/module.notifications` package remains available as a compatibility shim for existing consumers.


---

## @lssm-tech/lib.observability

Description: OpenTelemetry-based observability primitives
Path: packages/libs/observability
URL: /llms/lib.observability

# @lssm-tech/lib.observability

Website: https://contractspec.io

**OpenTelemetry-based observability primitives.**

## What It Provides

- **Layer**: lib.
- **Consumers**: evolution, progressive-delivery, bundles.
- `src/pipeline/` contains pipeline stages and orchestration helpers.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/pipeline/` contains pipeline stages and orchestration helpers.

## Installation

`npm install @lssm-tech/lib.observability`

or

`bun add @lssm-tech/lib.observability`

## Usage

Import the root entrypoint from `@lssm-tech/lib.observability`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/anomaly` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/intent` is part of the package's public or composition surface.
- `src/logging` is part of the package's public or composition surface.
- `src/metrics` is part of the package's public or composition surface.
- `src/pipeline/` contains pipeline stages and orchestration helpers.
- `src/telemetry` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./anomaly/alert-manager` resolves through `./src/anomaly/alert-manager.ts`.
- Export `./anomaly/anomaly-detector` resolves through `./src/anomaly/anomaly-detector.ts`.
- Export `./anomaly/baseline-calculator` resolves through `./src/anomaly/baseline-calculator.ts`.
- Export `./anomaly/root-cause-analyzer` resolves through `./src/anomaly/root-cause-analyzer.ts`.
- Export `./intent/aggregator` resolves through `./src/intent/aggregator.ts`.
- Export `./intent/detector` resolves through `./src/intent/detector.ts`.
- Export `./logging` resolves through `./src/logging/index.ts`.
- Export `./metrics` resolves through `./src/metrics/index.ts`.
- Export `./pipeline/evolution-pipeline` resolves through `./src/pipeline/evolution-pipeline.ts`.
- The package publishes 18 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Circular import issue.
- Normalize formatting across contracts-integrations, composio, and observability.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- OTel span and metric naming conventions must stay consistent across the platform.
- Pipeline interfaces are adapter boundaries — do not leak vendor-specific details.
- Anomaly detection thresholds affect alerting; changes require validation.


---

## @lssm-tech/lib.opportunity-runtime

Description: Pure deterministic scoring, gate, simulation, and portfolio projections for autonomous-company opportunities.
Path: packages/libs/opportunity-runtime
URL: /llms/lib.opportunity-runtime

# `@lssm-tech/lib.opportunity-runtime`

Pure deterministic scoring, gate, simulation, and portfolio projections for autonomous-company opportunities.

This package consumes `@lssm-tech/lib.opportunity-spec` contracts and provides input-only helpers for normalizing scorecards, computing weighted scores, projecting verdicts, summarizing simulation bottlenecks, and ranking portfolios.

## Scope

Use this package to:

- normalize `0..5` scores to `0..100`;
- verify the canonical opportunity score weights sum to `100%`;
- compute weighted opportunity scores;
- apply hard-gate and evidence-threshold verdict overrides;
- summarize autonomous-operation simulation bottlenecks;
- produce deterministic portfolio selections with explainable reasons.

## Boundary

This runtime is side-effect-free. It does not fetch research, synthesize claims with LLMs, call providers, persist data, mutate files, create CompanyOS/Builder workflows, contact customers, or execute production actions. It only projects over caller-provided spec objects.

## Public entrypoints

- `@lssm-tech/lib.opportunity-runtime` — root barrel
- `@lssm-tech/lib.opportunity-runtime/scoring` — normalization and weighted scoring helpers
- `@lssm-tech/lib.opportunity-runtime/gates` — verdict and bottleneck projections
- `@lssm-tech/lib.opportunity-runtime/portfolio` — deterministic portfolio ranking

## Commands

- `bun run test`
- `bun run typecheck`
- `bun run lint:check`
- `bun run build`


---

## @lssm-tech/lib.opportunity-spec

Description: Provider-neutral opportunity scoring and selection contracts for autonomous-company candidates.
Path: packages/libs/opportunity-spec
URL: /llms/lib.opportunity-spec

# `@lssm-tech/lib.opportunity-spec`

Provider-neutral opportunity scoring and selection contracts for autonomous-company candidates.

This package closes the first canonical ContractSpec slice for the Autonomous Company Opportunity Engine. It defines reviewable candidate, scorecard, evidence, gate, validation, simulation, portfolio, and handoff contracts; it does not research markets, call providers, mutate CompanyOS/Builder state, or approve production implementation.

## Scope

Use this package to model:

- autonomous-company opportunity candidates;
- core scorecards: AFS, BVS, GFS, CES, DMS, RTS, RCS, SFS, and TMS;
- diagnostic scores: QAS, DRS, TVS, VCS, and OTS;
- per-score and per-estimate evidence claims from hypothesis to live customer metrics;
- hard kill gates, downgrade gates, HITL load, GTM/CAC/budget assumptions, validation experiments, simulations, and portfolio decisions;
- branded refs to CompanyOS, Builder, ProductIntent, growth, finance, assurance, and orchestration surfaces.

## Boundary

This package is contract-only. It must not contain provider credentials, network calls, filesystem mutation, live research, customer-facing sends, production workflow creation, or module imports. High opportunity scores are decision evidence, not implementation approval.

## Public entrypoints

- `@lssm-tech/lib.opportunity-spec` — root barrel
- `@lssm-tech/lib.opportunity-spec/types` — Zod schemas and inferred types
- `@lssm-tech/lib.opportunity-spec/validation` — semantic validation helpers
- `@lssm-tech/lib.opportunity-spec/validation-rules` — reusable validation rule primitives for score coverage and evidence ref checks
- `@lssm-tech/lib.opportunity-spec/fixtures` — safe synthetic fixtures

## Evidence thresholds

- `customer_validated` requires evidence level `3` or higher.
- `pilot_validated` requires evidence level `4` or higher.
- `live_proven` requires evidence level `5`.

## Commands

- `bun run test`
- `bun run typecheck`
- `bun run lint:check`
- `bun run build`


---

## @lssm-tech/lib.orchestration-spec

Description: Provider-neutral cross-domain orchestration semantics for autonomous-company workflows.
Path: packages/libs/orchestration-spec
URL: /llms/lib.orchestration-spec

# `@lssm-tech/lib.orchestration-spec`

Cross-domain orchestration semantics for autonomous-company workflows.

This package does **not** define a new generic workflow engine. It binds existing `@lssm-tech/lib.contracts-spec/workflow` workflow IDs, step IDs, and transition IDs to domain refs, evidence links, policy gates, dispatch/receipt/outcome obligations, replay checkpoints, and saga/compensation requirements.

## Public entrypoints

- `@lssm-tech/lib.orchestration-spec` — root barrel

## Boundary

- Provider-neutral contracts only.
- No module imports.
- No provider SDKs, I/O, runner, queue, state store, retry runner, or compensation executor.
- Phase 2 infra-ops workflows are deferred and may only appear as deferred refs.


---

## @lssm-tech/lib.organization-planning-runtime

Description: Organization Planning & Agenda (OPA) execution runtime: wires the organization-planning module's adapter ports to real adapters while preserving fail-closed approval gates. Provider SDKs stay in integrations/.
Path: packages/libs/organization-planning-runtime
URL: /llms/lib.organization-planning-runtime

# @lssm-tech/lib.organization-planning-runtime

Website: https://contractspec.io

**Execution runtime for Organization Planning & Agenda (OPA).**

## What It Provides

- **Layer**: `lib.` (foundational runtime).
- Wires the typed adapter ports declared in
  `@lssm-tech/module.organization-planning` (`./adapter-ports`) to real adapters,
  turning OPA agenda/booking/auto-scheduling plans into real-world side-effects.
- Composes contracts from `@lssm-tech/lib.organization-planning-spec` and the
  module composition surface.

## Boundaries

- **No provider SDKs inside this lib.** Provider bridges (Google Calendar, Twilio
  SMS, email outbound, durable queues) live in `packages/integrations/*`. This
  runtime only composes their ports.
- **Fail-closed.** Missing adapters, unresolved authority, or unmet approval gates
  reject — the runtime never silently escalates or proceeds.
- **Approval gates preserved.** Governed-action and approval-required semantics
  from the spec/module layers flow through unchanged.

## Installation

`npm install @lssm-tech/lib.organization-planning-runtime`

or

`bun add @lssm-tech/lib.organization-planning-runtime`

## Usage

Import the root entrypoint from `@lssm-tech/lib.organization-planning-runtime`.

## Public Entry Points

- `.` — root barrel; `buildOpaOps(deps)` (with `OpaBuildDeps`) builds the OPA
  operation registry, plus `opaOpSpecs`.
- `./authz` — fail-closed authorization checks (`isOpaExecutionAllowed` path).
- `./crypto` — BYOK envelope crypto primitives.
- `./vault` — BYOK secret vault over the crypto layer.
- `./database` — `opa_*` schema, RLS-scoped pools, and migration helpers
  (node-only; reach via this subpath, never the root barrel in client code).
- `./outbox` — transactional outbox dispatch.
- `./scheduler` — scheduler / optimizer worker.
- `./governance` — runtime governance + RGPD enforcement.
- `./install` — the reusable install kit (`createOpaRuntime`). See below.

## Install kit — `./install`

`createOpaRuntime(config)` is the drop-in entrypoint: one call assembles
`buildOpaOps` with every OPA dependency and safe fail-closed production defaults
for anything unconfigured.

```ts
import { createOpaRuntime, opaHandlerCtx } from '@lssm-tech/lib.organization-planning-runtime/install';

const runtime = createOpaRuntime({
  rbac,                       // identity-rbac authorizer (omit → fail-closed unless localDefaults)
  calendar,                   // opa-calendar-bridge CalendarExecutionAdapterPort
  communication,              // opa-notification-bridge CommunicationSendAdapterPort
  schedulingLinks,            // public scheduling-link resolver
  publicBookingAudit,         // audit sink for public booking attempts
  publicBookingAbuseGuard,    // abuse guard for the public confirm endpoint
  governanceErasure,          // RGPD erasure store (defaults from sqlExecutor when omitted)
  observability,              // lib.observability Instrumentation sink
  sqlExecutor,                // backs the default service-role erasure store
});

// runtime.registry → mount on REST/GraphQL/MCP
// runtime.deps     → resolved deps, exposed for inspection/composition
const ctx = opaHandlerCtx({ userId, tenantId, workspaceId, roles });
await runtime.runManualLoop(input, ctx);   // through the authorized registry op
runtime.runManualLoopDetailed(input);      // deterministic full projection (proof/demo)
```

- **Returns** `{ registry, deps, runManualLoop, runManualLoopDetailed }`.
- The barrel also exports `opaHandlerCtx(scope)` (builds a tenant/auth-scoped
  `HandlerCtx`) and `createLocalOpaAuthorizer()` (demo-only permissive authorizer).
- **Fail-closed by default.** Unconfigured providers stay unbound in production.
  Opt in to `localDefaults: true` for a permissive LOCAL authorizer + fake
  calendar/communication adapters — **DEMO/LOCAL ONLY, never production.**

## Internals (not public subpaths)

- `src/observability/` — null-safe OPA observability hooks + `withOpaObservability`.
- Public booking + notification handlers (`public-confirm-handler.ts`,
  `notify-confirmation.ts`, …) wire the public booking flow and notification bridge.

## Local Commands

- `bun run test` — package tests
- `bun run typecheck` — TypeScript check
- `bun run build` — bundle + types
- `bun run lint:check` — Biome check


---

## @lssm-tech/lib.organization-planning-spec

Description: Provider-neutral organization, planning, agenda, booking, and auto-scheduling contracts for autonomous-company operations.
Path: packages/libs/organization-planning-spec
URL: /llms/lib.organization-planning-spec

# @lssm-tech/lib.organization-planning-spec

Provider-neutral contracts for organization, planning, agenda, booking, capacity, and auto-scheduling decisions across autonomous-company verticals.

## Owns

- organization/team/member/resource/calendar refs;
- availability, focus, meeting, blackout, buffer, no-meeting, privacy, and capacity policies;
- booking intents, routing, polls, agenda blocks, commitments, habits, planning windows, and schedule decisions;
- cross-domain handoff refs to CompanyOS, CommunicationOS, jobs, integrations, assurance, growth, finance, and orchestration evidence;
- cross-module types for `OrganizationPlanningCrossModulePlan`, module handoffs, and adapter-port obligations;
- pure projection helpers for mapping packets to cross-module intent projections;
- cross-module fixtures demonstrating end-to-end integration without provider writes.
- local/manual OPA v0 functions for availability, day planning, agendas,
  booking proposals, markdown export, and audit payloads.

## Does not own

- live calendar/provider writes;
- notification delivery;
- payment collection;
- workflow execution engines;
- CompanyOS authority/work execution;
- provider credentials, API keys, private URLs, or SDK imports.

## Entrypoints

- `@lssm-tech/lib.organization-planning-spec` — root barrel
- `@lssm-tech/lib.organization-planning-spec/cross-module-fixtures` — cross-module fixtures
- `@lssm-tech/lib.organization-planning-spec/fixtures` — base fixtures
- `@lssm-tech/lib.organization-planning-spec/operations` — OPA operation contracts
  (`defineCommand`/`defineQuery`), events, models, governance operations, and the
  public booking/confirm contracts
- `@lssm-tech/lib.organization-planning-spec/opa` — OPA v0 local/manual primitives
- `@lssm-tech/lib.organization-planning-spec/opa/*` — individual OPA helper
  subpaths for schemas, contracts, fixtures, availability, planner, agenda,
  booking, markdown export, plus the production surfaces below
- `@lssm-tech/lib.organization-planning-spec/opa/time` — DST-safe `Europe/Paris`
  time helpers (timezone-correct slotting across spring/autumn transitions)
- `@lssm-tech/lib.organization-planning-spec/opa/public-booking` — public booking
  availability + confirmation contracts
- `@lssm-tech/lib.organization-planning-spec/opa/governance` — RGPD/governance
  contracts (consent, retention, erasure, audit obligations)
- `@lssm-tech/lib.organization-planning-spec/opa/optimizer` — continuous optimizer
  model (constraint model, model builder, recurrence expander, placement, solver)
- `@lssm-tech/lib.organization-planning-spec/opa/context` — OPA execution context
- `@lssm-tech/lib.organization-planning-spec/opa/rich-calendar` — rich calendar view model
- `@lssm-tech/lib.organization-planning-spec/translations` — fr/en i18n catalogs,
  keys, and messages for OPA user-facing surfaces
- `@lssm-tech/lib.organization-planning-spec/projections` — pure projection helpers
- `@lssm-tech/lib.organization-planning-spec/types` — all type exports
- `@lssm-tech/lib.organization-planning-spec/validation` — validation functions

## Production OPA surfaces

Beyond the v0 manual loop, the spec now declares the contract layer that the OPA
runtime executes:

- **Operations** (`/operations`) — `defineCommand`/`defineQuery` contracts for the
  OPA agenda/booking/scheduling operations, their events, and governance
  operations, registered for multi-surface hosting (REST/GraphQL/MCP).
- **Public booking** (`/opa/public-booking`, `/operations`) — anonymous-facing
  availability + confirm contracts that back the public booking page.
- **Optimizer** (`/opa/optimizer`) — a deterministic constraint model and solver
  for continuous schedule optimization (objective weights flow in from
  personalization).
- **Time** (`/opa/time`) — DST-safe `Europe/Paris` arithmetic so slot boundaries
  stay correct across daylight-saving transitions.
- **Governance** (`/opa/governance`) — RGPD-facing obligations kept explicit and
  testable.
- **Translations** (`/translations`) — fr/en catalogs; no hardcoded user-facing
  copy in presentation code.

These are still contract-only: the spec declares them, the runtime executes them.

## OPA v0 local/manual loop

```typescript
import {
	computeAvailability,
	exportOpaMarkdown,
	generateAgenda,
	generateDayPlan,
	proposeBookingSlots,
} from '@lssm-tech/lib.organization-planning-spec/opa';
```

These helpers implement the spec-pack v0 loop. Availability, planning, and booking use one `primary_policy` in v0; multi-policy merge/routing remains a later adapter concern:

```text
tasks + commitments + meetings + policies
  -> plan / agenda / booking proposal
  -> human review
  -> markdown / Notion export from audited artifacts
  -> audit event payload on generated proposals
```

External-facing booking or agenda artifacts are proposals only and include
required approvals. The package does not write calendars, send client messages,
or import provider SDKs.


---

## @lssm-tech/lib.overlay-engine

Description: Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.
Path: packages/libs/overlay-engine
URL: /llms/lib.overlay-engine

# @lssm-tech/lib.overlay-engine

Website: https://contractspec.io

**Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.**

## What It Provides

- **Layer**: lib.
- **Consumers**: personalization, example-shared-ui, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.overlay-engine`

or

`bun add @lssm-tech/lib.overlay-engine`

## Usage

Import the root entrypoint from `@lssm-tech/lib.overlay-engine`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/merger.ts` is part of the package's public or composition surface.
- `src/react.ts` is part of the package's public or composition surface.
- `src/registry.ts` is part of the package's public or composition surface.
- `src/runtime.ts` is part of the package's public or composition surface.
- `src/signer.ts` is part of the package's public or composition surface.
- `src/spec.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./merger` resolves through `./src/merger.ts`.
- Export `./react` resolves through `./src/react.ts`.
- Export `./registry` resolves through `./src/registry.ts`.
- Export `./runtime` resolves through `./src/runtime.ts`.
- Export `./signer` resolves through `./src/signer.ts`.
- Export `./spec` resolves through `./src/spec.ts`.
- Export `./types` resolves through `./src/types.ts`.
- Export `./validator` resolves through `./src/validator.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Overlay spec schema is a contract — changes are breaking for all consumers.
- Signer must preserve cryptographic integrity; do not alter signing algorithm without migration.
- Merger logic must be idempotent — applying the same overlay twice must produce identical results.


---

## @lssm-tech/lib.personalization

Description: Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.
Path: packages/libs/personalization
URL: /llms/lib.personalization

# @lssm-tech/lib.personalization

`@lssm-tech/lib.personalization` tracks behavior events, summarizes them into actionable insights, and converts those insights into transparent personalization outputs such as overlay suggestions, preference recommendations, and runtime adaptive-experience decisions. It also defines the shared preference-dimensions model consumed by runtime layers.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.personalization`

or

`npm install @lssm-tech/lib.personalization`

## What belongs here

This package currently has three jobs:

- Behavior telemetry and analysis: `tracker`, `store`, `analyzer`, `adapter`, and `types` handle event capture, storage, summarization, and conversion into adaptation hints.
- Shared adaptive contracts: `preference-dimensions`, behavior support, behavior signals, and runtime resolution define the generic adaptive-experience model consumed by runtime layers.
- Ontology trace alignment: adaptive events, behavior signals, DataView interactions, and sanitized fine-tuning receipts can carry graph/evidence references without storing raw user context as training data.
- Practical adoption: curated presets, onboarding recommendation, and safe evolution suggestions help applications offer a better starting point without creating rigid personas.

Use this package when you need a thin personalization layer inside ContractSpec. Do not use it as a general analytics platform or as the full overlay runtime.

## Core workflow

```ts
import {
  BehaviorAnalyzer,
  createBehaviorTracker,
  insightsToOverlaySuggestion,
  InMemoryBehaviorStore,
} from "@lssm-tech/lib.personalization";

const store = new InMemoryBehaviorStore();

const tracker = createBehaviorTracker({
  store,
  context: {
    tenantId: "acme",
    userId: "user-123",
    role: "manager",
    roles: ["manager"],
    permissions: ["billing.order.read"],
    policyDecisions: {
      internalNotes: {
        effect: "deny",
        fields: ["internalNotes"],
        missing: { permissions: ["billing.notes.read"] },
      },
    },
  },
  autoFlushIntervalMs: 5000,
});

tracker.trackFieldAccess({
  operation: "billing.createOrder",
  field: "internalNotes",
});
tracker.trackFieldAccess({
  operation: "billing.createOrder",
  field: "customerReference",
});
tracker.trackFeatureUsage({
  feature: "workflow-editor",
  action: "opened",
});
tracker.trackWorkflowStep({
  workflow: "invoice-approval",
  step: "review",
  status: "entered",
});

await tracker.flush();
await tracker.dispose();

const analyzer = new BehaviorAnalyzer(store, {
  fieldInactivityThreshold: 2,
});

const insights = await analyzer.analyze({
  tenantId: "acme",
  userId: "user-123",
  windowMs: 7 * 24 * 60 * 60 * 1000,
});

const overlay = insightsToOverlaySuggestion(insights, {
  overlayId: "acme-order-form",
  tenantId: "acme",
  capability: "billing.createOrder",
});
```

Typical flow:

1. Record behavior events through `BehaviorTracker`.
2. Persist and summarize those events through a `BehaviorStore`.
3. Analyze the summary with `BehaviorAnalyzer`.
4. Convert insights into an `OverlaySpec` suggestion or workflow adaptation hints.

## DataView preferences

Use the data-view preference helpers when a collection `DataViewSpec` should
honor preferred list/grid/table mode, density, or data depth without coupling
the design-system renderer to personalization:

```tsx
import { DataViewRenderer } from "@lssm-tech/lib.design-system";
import { resolveDataViewPreferences } from "@lssm-tech/lib.personalization/data-view-preferences";

const resolved = resolveDataViewPreferences({
  spec: AccountsDataView,
  preferences: profile.canonical,
  insights,
  record: savedDataViewPreference,
});

<DataViewRenderer
  spec={AccountsDataView}
  items={rows}
  defaultViewMode={resolved.viewMode}
  defaultDensity={resolved.density}
  defaultDataDepth={resolved.dataDepth}
/>;
```

The helper returns plain data and never imports React or the design-system
package. Stored data-view preference records win over behavior insights,
preference dimensions, and authored contract defaults. Disallowed inferred view
modes are ignored so the renderer only receives modes allowed by the spec.

## Adaptive shell projection

Use `@lssm-tech/lib.personalization/adaptive-shell` when a product shell needs
to translate the existing seven preference dimensions into plain layout,
navigation, density, data-depth, and control hints. The projection is
runtime-only, has no persistence store, and accepts RoleMorph/policy/workspace
safety boundaries so preferences can tune presentation without granting hidden
routes, restricted evidence, or actions.

```ts
import { resolveAdaptiveShellProjection } from "@lssm-tech/lib.personalization/adaptive-shell";

const shell = resolveAdaptiveShellProjection({
  resolvedExperience,
  safetyBoundaries: [
    {
      id: "policy:auditor-read-only",
      target: "actions",
      effect: "read-only",
      reason: "Auditor shell actions stay read-only.",
    },
  ],
});

console.log(shell.navigation, shell.layoutVariant, shell.control);
```

Every applied or suppressed shell adaptation carries a reason, evidence IDs,
ontology refs, and a safety level. Use
`createAdaptiveShellRuntimeActionEvents()` to emit these records through the
existing adaptive runtime-action event channel.

Record renderer interactions with the behavior tracker so later analysis can
derive scoped preferred modes:

```ts
tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  dataViewVersion: AccountsDataView.meta.version,
  action: "view_mode_changed",
  viewMode: "grid",
});

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  action: "data_depth_changed",
  dataDepth: "detailed",
});
```

Agent prompt for a DataView preference integration:

```md
Add DataView personalization for <screen>.

- Resolve viewMode, density, dataDepth, and pageSize with resolveDataViewPreferences.
- Apply resolved values to DataViewRenderer as default or controlled props.
- Track opened, view_mode_changed, density_changed, data_depth_changed, search_changed, filter_changed, sort_changed, and page_changed actions with trackDataViewInteraction.
- Persist only the dimensions enabled by view.collection.personalization.persist.
- Ignore behavior-derived modes not allowed by view.collection.viewModes.allowedModes.
- Keep @lssm-tech/lib.personalization free of React and design-system imports.
```

## Adaptive application integration

Applications should keep product-specific rules in their own packages and
reuse the ContractSpec adaptive foundation for the generic wiring:

- Use `@lssm-tech/lib.personalization` for low-level contracts, event
  builders, emitters, behavior signals, and runtime adaptive resolution.
- Use `@lssm-tech/lib.presentation-runtime-core/adaptive-experience` to map
  `ResolvedAdaptiveExperience` into platform-neutral presentation defaults.
- Use `@lssm-tech/lib.presentation-runtime-react/useAdaptiveDataView` to
  resolve DataView defaults and translate manual renderer changes into
  `data_view_interaction` events.
- Use `@lssm-tech/lib.contracts-runtime-client-react/adaptive-form` to derive
  form guidance, density, recovery, and reflection hints from the same runtime
  adaptive result.

`DataViewRenderer` and `DataTableToolbar` remain generic design-system
components. They accept plain adaptive/default props and generic interaction
callbacks, but they do not import personalization or store behavior data.

```tsx
import { DataViewRenderer } from "@lssm-tech/lib.design-system";
import { useAdaptiveDataView } from "@lssm-tech/lib.presentation-runtime-react/useAdaptiveDataView";

const adaptive = useAdaptiveDataView({
  spec: AccountsDataView,
  preferences,
  behaviorSupport,
  behaviorSignals,
  behaviorEventBase: {
    tenantId,
    userId,
  },
  onBehaviorEvent: (event) => tracker.trackDataViewInteraction(event),
});

<DataViewRenderer
  spec={AccountsDataView}
  items={rows}
  {...adaptive.dataViewRendererProps}
/>;
```

Recommended application layering:

- Backend: persist explicit preference records, accepted suggestions, and
  behavior events. Do not persist `ResolvedAdaptiveExperience` as a hidden user
  identity.
- Runtime adapter: combine product policy, permissions, current context,
  preferences, behavior support, and signals into a resolved runtime result.
- Design-system surface: consume plain props, emit generic interaction callbacks,
  and let the runtime adapter translate them into behavior evidence.
- Application package: add only product-specific wording, policy, permissions,
  persistence, and workflow decisions.

### Ontology refs and sanitized fine-tuning receipts

Adaptive traces can reference the canonical Company Work Graph by ID while
remaining payload-safe:

```ts
import {
  createSanitizedAdaptiveFineTuningReceipt,
  resolveAdaptiveExperience,
} from "@lssm-tech/lib.personalization";

const resolved = resolveAdaptiveExperience({
  preferences,
  behaviorSupport,
  behaviorSignals,
  context: {
    ontologyRefs: {
      graphId: "company-work-graph",
      nodes: [{ id: "surface:approval-panel", domain: "surface" }],
      evidence: [{ id: "receipt:audit-1", kind: "auditReceipt" }],
    },
  },
  trace: { traceId: "trace-1", trainingJobId: "train-1" },
});

const receipt = createSanitizedAdaptiveFineTuningReceipt({
  id: "receipt:train-1",
  createdAt: new Date().toISOString(),
  trace: resolved.trace,
  ontologyRefs: resolved.ontologyRefs,
  policy: {
    policyDecisionRef: "policy:allow-sanitized-training",
    exportAllowed: true,
    trainingAllowed: true,
    reason: "Only redacted graph/evidence refs and trace IDs are exported.",
  },
  redaction: {
    status: "redacted",
    redactionDecisionId: "redaction:1",
    excludedFields: ["metadata", "context.userIntent"],
  },
});
```

Receipts contain trace IDs, ontology refs, policy/redaction refs, and explicit
prohibited conclusions. They do not include raw event metadata, free-form user
intent, or hidden profile data.


Autonomous Work Order traces use the same rule: adaptive events and behavior signals may identify the work order, surface DataView/page, RoleMorph decision, evidence receipt, policy decision, and redaction receipt by ref. They must not store raw user intent, hidden profile claims, or sensitive payloads as training data. Fine-tuning receipts export only sanitized trace IDs, ontology refs, policy/redaction refs, and prohibited-conclusion metadata.

## API map

### Main runtime APIs

- `BehaviorStore`: persistence boundary for recording, querying, and summarizing `BehaviorEvent` data.
- `InMemoryBehaviorStore`: simple in-memory implementation for tests, demos, and local composition.
- `BehaviorTracker` and `createBehaviorTracker`: buffered event capture with tenant/user context and OpenTelemetry instrumentation.
- `BehaviorAnalyzer`: converts `BehaviorSummary` data into `BehaviorInsights`.
- Authorization context: events may carry `roles`, `permissions`, and policy decision summaries so analyzers can suppress denied fields/actions without granting access.
- `insightsToOverlaySuggestion`: turns analysis output into an overlay-engine `OverlaySpec`.
- `insightsToWorkflowAdaptations`: turns workflow bottlenecks into lightweight adaptation notes.

### Core data contracts

- `BehaviorEvent`: discriminated union with four event kinds: `field_access`, `feature_usage`, `workflow_step`, and `data_view_interaction`.
- `BehaviorQuery`: filter shape used by `BehaviorStore.query()` and `BehaviorStore.summarize()`.
- `BehaviorSummary`: aggregated counts returned by store summarization.
- `BehaviorInsights`: analyzer output including hidden-field candidates, bottlenecks, and layout preference hints.
  When authorization decisions are supplied, denied fields/actions are surfaced for suppression and are not promoted in overlay reorder suggestions.
- `BehaviorAnalyzerOptions`: tuning knobs for inactivity threshold and minimum workflow sample size.
- `OverlaySuggestionOptions`: metadata required to build an overlay suggestion.
- `WorkflowAdaptation`: workflow, step, and note triple derived from bottlenecks.
- DataView preference helpers: `resolveDataViewPreferences`, `DataViewPreferenceRecord`, `DataViewPreferencePatch`, and mapping helpers for density and view-mode patches.
- Adaptive integration helpers: `AdaptiveExperienceEmitter`, adaptive event builders, `resolveAdaptiveDataViewState`, `createDataViewInteractionEvent`, `resolveAdaptiveShellProjection`, `createAdaptiveShellRuntimeActionEvents`, ontology trace refs, and sanitized fine-tuning receipt builders.

### Preference model contracts

- `PreferenceDimensions`: the shared 7-dimension personalization model.
- `BehaviorSupportDimensions`: the support-strategy model for helping users act, recover, and review progress.
- `BehaviorSignalModel`: scoped behavior evidence used to explain adaptation suggestions without profiling users.
- `ResolvedAdaptiveExperience`: runtime-only result describing what the application should do now.
- Preset helpers: `PREFERENCE_DIMENSION_PRESETS`, `PREFERENCE_PRESET_DEFINITIONS`, `getPreferencePresetDimensions`, and `createPreferencePresetCatalog`.
- Behavior support preset helpers: `BEHAVIOR_SUPPORT_PRESETS`, `BEHAVIOR_SUPPORT_PRESET_DEFINITIONS`, and `getBehaviorSupportPresetDimensions`.
- Onboarding helpers: `recommendPreferencePreset`, `recommendBehaviorSupportPreset`, `recommendAdaptiveExperience`, and related recommendation types.
- Adoption helpers: adaptive templates, UI-agnostic onboarding flows, explanation templates, risk helpers, recipes, scenarios, and migration paths.
- Evolution helpers: `suggestPreferenceEvolution`, `suggestAdaptiveExperienceEvolution`, and related suggestion types.
- `PreferenceScope`: source scope used when a preference value is resolved.
- `ResolvedPreferenceProfile`: canonical resolved preferences plus source attribution and constraint notes.
- `PreferenceResolutionContext`: minimal runtime context required to resolve a preference profile.
- `BundlePreferenceAdapter`: contract for resolving and persisting preference patches in runtime consumers.

## Adaptive experience toolkit

Use ContractSpec personalization to give builders a transparent adaptation layer. The package separates how software presents itself from how the system supports user action:

- `PreferenceDimensions` decide how the software adapts as a tool.
- `BehaviorSupportDimensions` decide how the system supports human action.
- `BehaviorSignalModel` records what evidence is strong enough to suggest a change.
- `ResolvedAdaptiveExperience` describes what should happen now, at runtime.

This is not a profiling engine, user-personality classifier, behavioral manipulation toolkit, analytics platform, or authorization system. It is a small set of contracts for saying: "The system noticed this scoped pattern and can adjust the experience in a way the user can inspect and override."

### Interaction preferences

`PreferenceDimensions` describes how a person wants to experience an application across seven independent dimensions:

- `guidance`: how much help the interface offers.
- `density`: how much information appears at once.
- `dataDepth`: whether the app starts from summaries, details, or exhaustive evidence.
- `control`: how much configuration and direct manipulation is exposed.
- `media`: whether the experience prefers text, visuals, voice, or a hybrid.
- `pace`: whether interactions should feel deliberate, balanced, or rapid.
- `narrative`: whether content starts top-down, bottom-up, or adapts by context.

These dimensions are software interaction preferences, not behavior labels and not permissions. `control: "full"` never grants access to features a user is not authorized to use.

### Behavior support dimensions

`BehaviorSupportDimensions` describes how the system supports action, momentum, recovery, and decision-making:

- `attention`: how the system helps the user notice what matters next.
- `activation`: how the system helps the user start.
- `actionScale`: how large the next useful action should be.
- `rhythm`: how work fits time, energy, urgency, or changing context.
- `environment`: what surrounding structure makes action easier.
- `challenge`: how much stretch or pressure is appropriate.
- `meaningFrame`: what makes the action feel worthwhile.
- `permission`: what helps the user begin, reduce, pause, or renegotiate.
- `selfAuthority`: how the system supports confidence, composure, structure, and follow-through.
- `accountability`: how much external structure or review the user wants.
- `recovery`: what should happen after skipped actions, misses, contradictions, or failed attempts.
- `reflection`: how much learning or review should happen after action.

This layer is support strategy, not identity. Use language such as "start support", "smaller first step", "repair first", "private review", or "brief reflection". Avoid moral, clinical, or manipulative labels such as "lazy", "avoidant", "low motivation", "approval-seeking", "low-value user", or "manipulable user".

### Presets are starting points

The package exports a small interaction preset catalog that application builders can ship directly:

- `balanced`: safe default for general use.
- `guideMe`: slower, guided onboarding for new or uncertain users.
- `summaryFirst`: compact, fast, dashboard-style usage.
- `deepAnalyst`: data-rich, evidence-first investigation mode.
- `builder`: fast, configurable mode for creating and adjusting workflows.
- `opsWarRoom`: dense, visual, rapid mode for live operational surfaces.
- `auditReview`: deliberate, traceable, detail-heavy review mode.
- `minimalFocus`: low-noise, focused, simple experience.

Presets are not identities. Use labels such as "Summary-first" or "Minimal focus", not labels such as "manager mode" or "skill level".

```ts
import {
  getPreferencePresetDimensions,
  PREFERENCE_PRESET_DEFINITIONS,
} from "@lssm-tech/lib.personalization";

const startingPreferences = getPreferencePresetDimensions("summaryFirst");
const presetIntent = PREFERENCE_PRESET_DEFINITIONS.summaryFirst.intent;
```

Override or extend the catalog by merging your own named bundles of `PreferenceDimensions`:

```ts
import {
  createPreferencePresetCatalog,
  PREFERENCE_PRESET_DEFINITIONS,
} from "@lssm-tech/lib.personalization";

const catalog = createPreferencePresetCatalog({
  calmReview: {
    id: "calmReview",
    label: "Calm review",
    intent: "A slower review flow with fewer visual interruptions.",
    dimensions: {
      ...PREFERENCE_PRESET_DEFINITIONS.auditReview.dimensions,
      media: "text",
      pace: "deliberate",
    },
  },
});
```

Behavior support presets are also editable starting points, not user types:

- `steadyMomentum`: consistent progress with moderate support.
- `activationFirst`: reduce start friction and help users begin.
- `permissionFirst`: make smaller starts, pauses, or renegotiation easy.
- `deepWorkBuilder`: protect focus, mastery, and intentional work.
- `recoveryFirst`: help users resume after misses or interruptions.
- `identityBuilder`: connect action to user-defined values or commitments.
- `selfAuthorityBuilder`: build confidence, composure, structure, and follow-through.
- `socialMomentum`: support shared rhythm or review when explicitly wanted.
- `deadlineSprint`: support short-term urgency and focused execution.
- `minimalNudge`: keep support low-noise with minimal intervention.

Good UI wording: "Suggested support style: Recovery-first." Bad UI wording: "You are a recovery-first user."

### Templates

Adaptive experience templates combine an interaction preset, behavior support preset, onboarding path, evolution policy, recommended scopes, safety notes, explanation copy, and generic product intent.

Templates are starting points for builders. They are not user identities, not permanent classifications, and not product domains.

Available templates:

- `balancedAdaptive`: safe default for most applications.
- `guidedFirstRun`: more guidance, smaller first actions, and safe first-run defaults.
- `expertOperator`: compact UI, faster pace, more control, and fewer interruptions when explicitly wanted.
- `summaryDecision`: summary-first dashboards, overviews, triage, and decision surfaces.
- `deepReview`: detailed, deliberate, evidence-heavy review workflows.
- `focusExecution`: action-oriented workflows where start, focus, and recovery matter.
- `recoverySupport`: neutral repair-first defaults after missed steps or interruptions.
- `collaborativeMomentum`: shared rhythm and review support with consent boundaries.
- `minimalAssist`: low-noise adaptation with minimal intervention.
- `learningBuilder`: guided capability growth and mastery support.

```ts
import {
  getAdaptiveExperienceTemplate,
  recommendAdaptiveTemplate,
} from "@lssm-tech/lib.personalization/adaptive-templates";

const template = getAdaptiveExperienceTemplate("guidedFirstRun");

const recommendation = recommendAdaptiveTemplate({
  selectedInteractionPreset: "guideMe",
  selectedBehaviorSupportPreset: "activationFirst",
});

console.log(template.productIntent);
console.log(recommendation.reasons);
```

Template categories help builders browse defaults by product intent: `general`, `onboarding`, `expert`, `decision`, `review`, `execution`, `recovery`, `collaboration`, `minimal`, and `learning`. Each category describes when to use it, when not to use it, the experience it creates, and the safety concerns that matter.

### UI-agnostic onboarding flows

The package exports onboarding definitions that applications can render in any UI. They contain flow IDs, titles, descriptions, recommended templates, human-readable questions, options, answer mappings, skip behavior, fallback behavior, and result summaries.

Available flows:

- `quickStartAdaptive`: short flow with a few questions for most apps.
- `fullAdaptiveSetup`: longer setup when adaptation matters deeply.
- `interactionOnlySetup`: configures only `PreferenceDimensions`.
- `behaviorSupportSetup`: configures only `BehaviorSupportDimensions`.
- `expertSetup`: lets advanced users inspect and directly select dimensions.
- `progressiveSetup`: starts from a template and asks questions when confidence is low.

```ts
import {
  ADAPTIVE_ONBOARDING_FLOWS,
  ADAPTIVE_ONBOARDING_QUESTIONS,
  resolveAdaptiveOnboardingRecommendation,
} from "@lssm-tech/lib.personalization/adaptive-onboarding-flows";

const flow = ADAPTIVE_ONBOARDING_FLOWS.quickStartAdaptive;
const questions = flow.questionIds.map(
  (id) => ADAPTIVE_ONBOARDING_QUESTIONS[id]
);

const result = resolveAdaptiveOnboardingRecommendation("quickStartAdaptive", {
  guidancePreference: "walkthrough",
  dataDepthPreference: "standard",
  actionScalePreference: "small",
  recoveryPreference: "repair",
});

console.log(result.selectedAdaptiveTemplate);
console.log(result.dimensionsInferredFromAnswers);
console.log(result.dimensionsUsingFallbackDefaults);
```

The recommendation result includes the selected interaction preset, behavior support preset, adaptive template, confidence, reasons, alternative templates, inferred dimensions, explicitly selected dimensions, fallback dimensions, safety notes, and a suggested next step.

Skipped onboarding uses safe defaults with low confidence. Role text can be passed for context, but role alone does not determine a template.

### Onboarding recommendation

Recommend first settings from intent and product questions, not role stereotypes. Ask simple questions such as:

- What kind of guidance do you prefer?
- Do you prefer summaries or details?
- Do you prefer simple controls or advanced controls?
- What helps you start?
- What action size feels easiest to trust?
- What should happen when something is missed?
- Do you want private progress, self-review, or shared review?
- What makes progress meaningful?

```ts
import {
  getPreferencePresetDimensions,
  getBehaviorSupportPresetDimensions,
  recommendAdaptiveExperience,
} from "@lssm-tech/lib.personalization";

const recommendation = recommendAdaptiveExperience({
  interaction: {
    primaryIntent: "reviewing",
    detailPreference: "evidence",
    controlPreference: "advanced",
    role: "Manager", // recorded for context, not used for scoring
  },
  behaviorSupport: {
    startSupport: "guided",
    actionSize: "small",
    recoveryPreference: "repair",
  },
});

const preferences = getPreferencePresetDimensions(
  recommendation.selectedInteractionPreset
);
const behaviorSupport = getBehaviorSupportPresetDimensions(
  recommendation.selectedBehaviorSupportPreset
);

console.log(recommendation.reasons);
console.log(recommendation.alternativeInteractionPresets);
console.log(recommendation.alternativeBehaviorSupportPresets);
```

The recommendation returns selected interaction and behavior support presets, confidence, human-readable reasons, alternatives, and editable dimension lists. Role text may be recorded as context, but it does not score presets because a job title should not decide the experience.

### Explanation templates and risk levels

Applications should explain adaptive changes in product language:

- observed pattern
- suggested change
- scope
- reversibility
- confidence when useful
- no shame or moral judgment

```ts
import {
  ADAPTIVE_EXPLANATION_TEMPLATES,
  getAdaptiveSuggestionRisk,
  shouldRequireAdaptiveConfirmation,
} from "@lssm-tech/lib.personalization/adaptive-explanations";

const explanation = ADAPTIVE_EXPLANATION_TEMPLATES.find(
  (item) => item.id === "smaller-first-steps"
);

const risk = getAdaptiveSuggestionRisk({
  target: "behaviorSupport",
  dimension: "accountability",
  impact: "medium",
});

const needsConfirmation = shouldRequireAdaptiveConfirmation({
  target: "preference",
  dimension: "control",
  impact: "low",
});
```

Risk levels:

- `low`: safe surface-level interaction changes such as view mode, density, or brief hints.
- `medium`: workflow structure or behavior support changes such as action scale, reflection, or recovery defaults.
- `high`: changes affecting control, accountability, challenge, social exposure, data depth, or user trust.

Never silently increase social accountability, external accountability, challenge, pressure, data exposure, control level, social visibility, or commitment strength.

Good explanation copy:

- "You often complete smaller actions."
- "This workflow seems to work better with brief reflection."
- "You can change this anytime."
- "This only applies to this surface."
- "This suggestion is based on repeated behavior."

Bad explanation copy:

- "You procrastinate."
- "You failed."
- "You lack discipline."
- "You need more accountability."
- "The system classified you."
- "This is your type."
- "We detected your personality."

### Evolution lifecycle

Use this lifecycle for behavior-driven adaptation:

1. Observe scoped behavior signals.
2. Normalize events into safe signal summaries.
3. Compare evidence with current preferences and support dimensions.
4. Detect repeated patterns, deviations, and clusters.
5. Suggest explainable adaptations.
6. Confirm or apply based on risk and scope.
7. Record accept, reject, ignore, or revert feedback.
8. Reduce confidence after rejected suggestions.
9. Let users revert changes.
10. Promote from narrow scope only with stronger evidence.

Rejected suggestions should reduce future confidence. Explicit user choices beat inferred behavior. High-risk suggestions require confirmation.

### Behavior signals are evidence

`BehaviorSignalModel` records observations that may support an adaptation. A signal is not a conclusion about the user.

Safe examples:

- user repeatedly switches one table to a more detailed view
- user completes smaller actions more often than large ones
- user skips long reflections but completes short ones
- user dismisses social/accountability prompts
- user uses advanced controls often
- user repeatedly chooses repair over reset

Unsafe interpretations:

- user is lazy
- user lacks discipline
- user wants to be controlled
- user is unreliable
- user has a psychological condition
- user is low-performing

```ts
import { createBehaviorSignalModel } from "@lssm-tech/lib.personalization";

const signal = createBehaviorSignalModel({
  id: "brief-reflection-pattern",
  kind: "repeated_pattern",
  summary: "User completes brief reflections more often than long reflections.",
  evidence: {
    repeatedPattern: "Brief reflections completed in three sessions.",
    timeWindow: { start: "2026-04-01T00:00:00Z" },
    scope: { level: "workflow", id: "review" },
    confidence: "high",
    source: "system-observation",
    userFeedback: "not-asked",
    safetyLevel: "safe",
    observations: [
      "Completed brief reflection in session 1.",
      "Completed brief reflection in session 2.",
      "Completed brief reflection in session 3.",
    ],
    suggestedAdaptation: {
      id: "brief-reflection-default",
      label: "Use brief reflection",
      description: "Use brief reflection by default for this workflow.",
      target: "behaviorSupport",
      dimension: "reflection",
      value: "brief",
      scope: { level: "workflow", id: "review" },
      impact: "low",
    },
  },
});
```

The helper rejects common unsafe labels so tests and logs stay observation-oriented.

### Runtime resolution

`ResolvedAdaptiveExperience` combines preferences, behavior support, signals, current context, surface, intent, product constraints, permissions, policies, and explicit overrides. It answers: "What should the application do now?"

```ts
import {
  resolveAdaptiveExperience,
  PREFERENCE_DIMENSION_PRESETS,
  BEHAVIOR_SUPPORT_PRESETS,
} from "@lssm-tech/lib.personalization";

const resolved = resolveAdaptiveExperience({
  preferences: PREFERENCE_DIMENSION_PRESETS.balanced,
  behaviorSupport: BEHAVIOR_SUPPORT_PRESETS.steadyMomentum,
  behaviorSignals: [signal],
  context: { workflowId: "review" },
  permissions: [
    {
      key: "advanced-controls",
      allowed: false,
      reason: "Advanced controls are not permitted.",
    },
  ],
});
```

The resolved result is `runtime-only`. Do not persist it as a hidden user profile. Persist explicit choices, accepted suggestions, or scoped preference records instead.

### Preference evolution

Evolution suggestions are deterministic and explainable. They do not mutate preferences by themselves.

Start with surface-level suggestions, then promote to workflow, workspace, or user scope only when behavior is consistent across multiple sessions and surfaces. Explicit user choices beat inferred behavior. Changes that affect `control`, `dataDepth`, `challenge`, `accountability`, or social exposure require confirmation because they can change perceived power, data exposure, pressure, or visibility.

```ts
import { suggestAdaptiveExperienceEvolution } from "@lssm-tech/lib.personalization";

const result = suggestAdaptiveExperienceEvolution({
  currentPreferences: preferences,
  currentBehaviorSupport: behaviorSupport,
  preferenceObservations: [
    {
      dimension: "density",
      value: "detailed",
      signal: "setting_changed",
      surfaceId: "orders",
      sessionId: "s1",
      reason: "Changed orders density to detailed.",
    },
    {
      dimension: "density",
      value: "detailed",
      signal: "setting_changed",
      surfaceId: "orders",
      sessionId: "s2",
    },
    {
      dimension: "density",
      value: "detailed",
      signal: "setting_changed",
      surfaceId: "orders",
      sessionId: "s3",
    },
  ],
  behaviorSignals: [signal],
});

console.log(result.preferenceSuggestions);
console.log(result.behaviorSupportSuggestions);
```

Recommended UI wording:

- "You often switch this table to detailed mode. Remember detailed mode here?"
- "You complete more actions when they start small. Use smaller first steps for this workflow?"
- "You often choose repair instead of reset. Suggest repair first after missed actions?"
- "You often skip long reflections. Use brief reflection by default?"
- "You regularly dismiss shared review prompts. Keep accountability private by default?"

Avoid wording that implies an identity profile or hidden optimization.

### Scope and examples

Adapt narrowly first. If a user repeatedly changes one table to detailed mode, do not make every product screen detailed. If a user repeatedly asks for smaller actions in one workflow, do not shrink every task globally. Promote from surface to workflow, workspace, or user scope only with stronger evidence and confirmation.

Generic integration examples:

- Adaptive dashboard: compact UI with detailed mode remembered for one table after repeated explicit switches.
- Guided onboarding: walkthrough interaction preset with activation-first support for the first setup flow.
- Review workflow: detailed audit mode with brief reflection and neutral recovery language.
- Focus workflow: minimal UI with protected focus blocks and self-review.
- Recovery after skipped action: suggest repair first, not shame or reset by default.
- Compact expert mode with gentle support: advanced controls stay visible, but first actions remain small and reversible.
- Detailed audit mode with minimal nudging: exhaustive data remains available while behavior support stays private and low-noise.

### Adoption recipes

Use the exported recipes when choosing an integration path:

- Use presets only.
- Use templates without onboarding.
- Use onboarding to choose a template.
- Use behavior signals to suggest changes.
- Use interaction preferences only.
- Use behavior support only.
- Resolve an adaptive experience for a surface.
- Show users why something changed.
- Handle rejected suggestions.
- Promote surface preferences safely.
- Disable behavior adaptation.
- Keep adaptation transparent.

```ts
import {
  ADAPTIVE_ADOPTION_RECIPES,
  ADAPTIVE_MIGRATION_PATHS,
  ADAPTIVE_SCENARIO_EXAMPLES,
} from "@lssm-tech/lib.personalization/adaptive-recipes";

const recipe = ADAPTIVE_ADOPTION_RECIPES.find(
  (item) => item.id === "use-onboarding-to-choose-template"
);

console.log(recipe?.integrationFlow);
console.log(ADAPTIVE_SCENARIO_EXAMPLES.map((scenario) => scenario.title));
console.log(ADAPTIVE_MIGRATION_PATHS.map((path) => path.title));
```

### Extension guide

Products can define their own templates, onboarding flows, behavior signals, explanation messages, evolution policies, risk policies, and domain-specific mappings. Keep those extensions outside ContractSpec OSS when they depend on domain language or product policy.

Use ContractSpec defaults as reusable patterns:

- Reuse `PreferenceDimensions` for how software presents itself.
- Reuse `BehaviorSupportDimensions` for how the system supports action.
- Reuse `BehaviorSignalModel` for scoped evidence.
- Reuse `ResolvedAdaptiveExperience` for runtime decisions.
- Add product-specific templates and mappings in application packages.
- Keep safety rules: explainable, reversible, scoped, and bounded by permissions.

### Migration paths

Existing consumers do not need to adopt the full model at once:

1. Continue using only `PreferenceDimensions`.
2. Add behavior support presets, but no behavior signals.
3. Add onboarding recommendation.
4. Add evolution suggestions.
5. Use full resolved adaptive experience.

The model is additive. Existing users can keep interaction preferences only and add behavior support, onboarding, templates, or evolution when the product needs them.

### Safety boundaries

- Preferences do not grant authorization.
- Behavior support does not replace business rules or permissions.
- Behavior observations are evidence, not psychological explanations.
- Resolved adaptive experiences are runtime outputs, not stored identities.
- No black-box machine learning is used.
- High-impact changes require confirmation.
- Suggestions are reversible and scoped.
- Applications should log or display what changed, why it changed, what evidence supported it, whether it was automatic or suggested, and how to undo or disable adaptation.
- Adaptation should never silently increase pressure, accountability, challenge, or social exposure.

## Public entrypoints

The root barrel at `src/index.ts` re-exports public symbols from:

- `adapter`
- `adaptive-events`
- `adaptive-evolution`
- `adaptive-explanations`
- `adaptive-experience`
- `adaptive-onboarding`
- `adaptive-onboarding-flows`
- `adaptive-recipes`
- `adaptive-surface`
- `adaptive-templates`
- `analyzer`
- `behavior-signals`
- `behavior-support`
- `data-view-preferences`
- `preference-dimensions`
- `preference-evolution`
- `preference-evolution-types`
- `preference-onboarding`
- `preference-presets`
- `store`
- `tracker`
- `types`

Published subpaths from `package.json`:

- `.`
- `./adapter`
- `./adaptive-events`
- `./adaptive-evolution`
- `./adaptive-explanations`
- `./adaptive-experience`
- `./adaptive-onboarding`
- `./adaptive-onboarding-flows`
- `./adaptive-onboarding-scores`
- `./adaptive-recipes`
- `./adaptive-surface`
- `./adaptive-templates`
- `./analyzer`
- `./behavior-signals`
- `./behavior-support`
- `./behavior-support-preset-definitions`
- `./behavior-support-presets`
- `./data-view-preferences`
- `./docs`
- `./docs/behavior-tracking.docblock`
- `./docs/overlay-engine.docblock`
- `./docs/workflow-composition.docblock`
- `./personalization.feature`
- `./preference-dimensions`
- `./preference-evolution`
- `./preference-evolution-types`
- `./preference-onboarding`
- `./preference-presets`
- `./store`
- `./tracker`
- `./types`

For application code, prefer `.` or the focused subpaths above. The `./docs*` subpaths exist for docblock registration and documentation surfaces.

## Operational semantics and gotchas

- `BehaviorTracker` buffers events in memory and flushes when the buffer reaches the configured size or when `autoFlushIntervalMs` is enabled.
- `flush()` persists the current buffer with `BehaviorStore.bulkRecord()`.
- `dispose()` clears the interval timer, then flushes any remaining buffered events.
- Each enqueue also emits OpenTelemetry metrics and tracing through `@opentelemetry/api`.
- `BehaviorAnalyzer` uses deterministic threshold heuristics. It does not do ranking, learning, or probabilistic inference.
- `insightsToOverlaySuggestion()` currently emits only `hideField` and `reorderFields` modifications.
- `layoutPreference` is still inferred from field-count thresholds. Data-view-specific preferred modes are derived from `data_view_interaction` events when those events include a valid collection `viewMode`.
- `PreferenceDimensions` and related types are contracts. Durable persistence and runtime resolution live elsewhere.
- Preset recommendation and preference evolution helpers are deterministic utilities. They return explainable data for applications to display, log, confirm, or ignore.

## When not to use this package

- Do not use it as a full analytics warehouse or reporting system.
- Do not use it as the durable preference persistence layer.
- Do not use it as the overlay runtime or overlay registry implementation.
- Do not use it when you need workflow composition itself; this package only emits adaptation hints.

## Related packages

- `@lssm-tech/lib.overlay-engine`: runtime for registering, validating, and applying overlays.
- `@lssm-tech/lib.surface-runtime`: runtime consumer of preference resolution and adaptive surface behavior.
- `@lssm-tech/lib.workflow-composer`: workflow extension and composition runtime.
- `@lssm-tech/lib.contracts-spec`: shared spec and docblock contracts used across ContractSpec.

## Local commands

- `bun run lint:check`
- `bun run typecheck`
- `bun run test`
- `bun run build`

## Rich code and diff preferences

`resolveRichCodePreferences` maps preference dimensions to governed code/diff presentation defaults: density, data depth, reference verbosity, context lines, and default expansion. The resolver is deterministic and runtime-only; it does not persist hidden profiles or bypass permissions.

Import it from the RichReference subpath introduced in slice S-4:

```ts
import { resolveRichCodePreferences } from "@lssm-tech/lib.personalization/rich-reference/preferences";
```

The legacy `./rich-code-preferences` subpath has been removed; the slice S-10 codemod handles the import rename.

## RichReference hybrid personalization

`@lssm-tech/lib.personalization/rich-reference` implements the `CoarsePreferencesProvider` port owned by `@lssm-tech/lib.contracts-spec/rich-reference/ports`. The model is two-layer by design:

- **Server-coarse** (`enrichedKinds`, `density`) resolves on the server via `createServerCoarsePreferencesResolver`, caches results by `(tenantId, subjectId, scopeHash)` for cross-tenant isolation, and is the only layer that ever appears in agent payloads.
- **Client-fine** (`verbosity`, `trigger`, `panelMode`, `expansion`, `perKindOptOut`) lives in a session-only store created via `createRichReferenceClientStore`. Mutations stay local until the consumer calls `persistPreferences()`, which invokes a persistence sink and emits a structured `rich-reference.preferences.persist` audit log event.

```ts
import {
  createServerCoarsePreferencesResolver,
  createRichReferenceClientStore,
  createUseRichReferencePreferences,
  resolveInherited,
  toAgentPayloadPreferences,
} from "@lssm-tech/lib.personalization/rich-reference";
```

`resolveInherited({ defaults, tenant, role, user, context })` applies explicit last-wins precedence per dimension. `toAgentPayloadPreferences(prefs)` strips fine-layer dimensions before serializing to an agent surface.


---

## @lssm-tech/lib.personalized-presentation

Description: Schema bridge and React provider/hook skeletons mapping lib.personalization preferences to cockpit-kit variant literals
Path: packages/libs/personalized-presentation
URL: /llms/lib.personalized-presentation

# @lssm-tech/lib.personalized-presentation

Schema bridge and React provider/hook skeletons mapping `lib.personalization`
preferences to `lib.cockpit-kit` variant literals.

## Status

**Phase 0 skeleton** — wired dimensions: `density`, `expansion`.
Runtime resolution logic is Phase 3 work.

## Installation

This package is an internal workspace package. Add it as a peer or direct
dependency from within the monorepo:

```json
"@lssm-tech/lib.personalized-presentation": "workspace:*"
```

## Peer dependencies

- `@lssm-tech/lib.cockpit-kit` — provides `Density` and `Expansion` variant types
- `@lssm-tech/lib.personalization` — provides `PreferenceDimensions`
- `react` — for the provider and hook

## Usage

### Provider

```tsx
import { PersonalizedSurfaceProvider } from "@lssm-tech/lib.personalized-presentation";

function App() {
  return (
    <PersonalizedSurfaceProvider role="manager" prefs={userPrefs}>
      <MyCockpitSurface />
    </PersonalizedSurfaceProvider>
  );
}
```

### Hook (Phase 0 — returns empty record)

```tsx
import { usePersonalizedVariants } from "@lssm-tech/lib.personalized-presentation";
import type { Density, Expansion } from "@lssm-tech/lib.cockpit-kit/variants";

function MyCockpitSurface() {
  const variants = usePersonalizedVariants<{
    density: Density;
    expansion: Expansion;
  }>("MyCockpitSurface");

  // Phase 0: variants is {}; Phase 3: will contain resolved literals
  return <div data-density={variants.density} />;
}
```

### Schema bridge (direct mapper access)

```ts
import { density, expansion } from "@lssm-tech/lib.personalized-presentation/schema-bridge";

const cockpitDensity = density("compact");   // → "compact"
const cockpitExpansion = expansion("detailed"); // → "expanded"
```

## Dependency direction

```
personalized-presentation → cockpit-kit
personalized-presentation → personalization
```

`cockpit-kit` and `personalization` must NOT depend on this package.

## Wired dimensions

| Dimension | Input type | Output type |
|-----------|-----------|-------------|
| density | `PreferenceDimensions["density"]` | `Density` |
| expansion | `PreferenceDimensions["dataDepth"]` | `Expansion` |

All other dimensions (`verbosity`, `trigger`, `panelMode`, `enrichedKinds`,
`perKindOptOut`) are stub-protected and will throw at runtime if called.


---

## @lssm-tech/lib.plugins

Description: Plugin API and registry for ContractSpec extensions
Path: packages/libs/plugins
URL: /llms/lib.plugins

# @lssm-tech/lib.plugins

Website: https://contractspec.io

**Plugin API and registry for ContractSpec extensions.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, CLI.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.plugins`

or

`bun add @lssm-tech/lib.plugins`

## Usage

Import the root entrypoint from `@lssm-tech/lib.plugins`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/config.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/registry.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./config` resolves through `./src/config.ts`.
- Export `./registry` resolves through `./src/registry.ts`.
- Export `./types` resolves through `./src/types.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Plugin interface is a public API contract — breaking changes affect all published plugins.
- Registry must stay backward-compatible; older plugin manifests must remain loadable.
- Config schema changes require a migration path for existing plugin configurations.


---

## @lssm-tech/lib.presentation-runtime-core

Description: Core presentation runtime for contract-driven UIs
Path: packages/libs/presentation-runtime-core
URL: /llms/lib.presentation-runtime-core

# @lssm-tech/lib.presentation-runtime-core

Website: https://contractspec.io

**Core presentation runtime for contract-driven UIs.**

## What It Provides

- **Layer**: lib.
- **Consumers**: presentation-runtime-react, presentation-runtime-react-native.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.presentation-runtime-core`

or

`bun add @lssm-tech/lib.presentation-runtime-core`

## Usage

Import the root entrypoint from `@lssm-tech/lib.presentation-runtime-core`, or choose a documented subpath when you only need one part of the package surface.

## Adaptive Experiences

The `./adaptive-experience` entrypoint maps ContractSpec adaptive experience primitives into presentation defaults that UI renderers can consume without importing product-specific code. It currently resolves DataView defaults such as collection view, density, data depth, and page size from `ResolvedAdaptiveExperience`.

Use this adapter at the boundary between product policy and rendering code. It should receive already-resolved preferences, behavior support, signals, constraints, and overrides; it should not store hidden user profiles or bypass permissions.

## Bundler Helpers

Import the bundler helpers from the root package:

```ts
import {
  withPresentationTurbopackAliases,
  withPresentationWebpackAliases,
  withPresentationMetroAliases,
} from '@lssm-tech/lib.presentation-runtime-core';
```

### Next.js Turbopack helper (default)

Use Turbopack as the default Next.js path:

```ts
import { withPresentationTurbopackAliases } from '@lssm-tech/lib.presentation-runtime-core';

const nextConfig = withPresentationTurbopackAliases({
  turbopack: {
    resolveAlias: {
      fs: { browser: 'browserify-fs' },
    },
  },
});

export default nextConfig;
```

### Next.js Webpack helper (fallback)

Use Webpack only when you opt in with `next dev --webpack` or `next build --webpack`:

```ts
import { withPresentationWebpackAliases } from '@lssm-tech/lib.presentation-runtime-core';

const nextConfig = {
  webpack: (config) => withPresentationWebpackAliases(config),
};

export default nextConfig;
```

### Expo / Metro helper

```js
const { getDefaultConfig } = require('expo/metro-config');
const {
  withPresentationMetroAliases,
} = require('@lssm-tech/lib.presentation-runtime-core');

const projectRoot = __dirname;
const config = getDefaultConfig(projectRoot);

module.exports = withPresentationMetroAliases(config);
```

The helpers also keep shared UI imports platform-correct:

- Metro rewrites `@lssm-tech/lib.ui-kit-web/ui/*` to `@lssm-tech/lib.ui-kit/ui/*`, `@lssm-tech/lib.presentation-runtime-react` to `@lssm-tech/lib.presentation-runtime-react-native`, and `lucide-react` to `lucide-react-native` for native platforms.
- Metro also enables package exports and merges platform export conditions so `ios`, `android`, `react-native`, and `browser` package conditions can resolve platform-specific build-tool outputs.
- Next.js Turbopack/Webpack rewrites the native package names back to the web packages, including `lucide-react-native` to `lucide-react`.

## Architecture

- `src/index.ts` is the root public barrel that builds the package entrypoint.
- `src/adaptive-experience.ts` is part of the package's public or composition surface.
- `src/metro.ts` is part of the package's public or composition surface.
- `src/next.ts` is part of the package's public or composition surface.
- `src/table.ts` is part of the package's public or composition surface.
- `src/visualization.echarts.ts` is part of the package's public or composition surface.
- `src/visualization.model.builders.ts` is part of the package's public or composition surface.
- `src/visualization.model.helpers.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` publishes through `./dist/index.js`; CommonJS `require` resolves to the generated Metro helper at `./dist/metro.cjs`.
- Export `./adaptive-experience` builds from `./src/adaptive-experience.ts`.
- Bundler helpers are part of the root entrypoint; no dedicated `./webpack` or `./turbopack` subpaths are published.
- Export `./metro` builds from `./src/metro.ts` and publishes a generated CommonJS `dist/metro.cjs` require target for Metro config files.
- Export `./next` builds from `./src/next.ts`.
- Export `./table` builds from `./src/table.ts`.
- Export `./visualization` builds from `./src/visualization.ts`.
- Export `./visualization.echarts` builds from `./src/visualization.echarts.ts`.
- Export `./visualization.model` builds from `./src/visualization.model.ts`.
- Export `./visualization.model.builders` builds from `./src/visualization.model.builders.ts`.
- Export `./visualization.model.helpers` builds from `./src/visualization.model.helpers.ts`.
- Export `./visualization.types` builds from `./src/visualization.types.ts`.
- Export `./visualization.utils` builds from `./src/visualization.utils.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit -p tsconfig.json
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add data visualization capabilities.
- Add table capabilities.
- Add table overflow metadata to controller render models so web and native
  renderers can apply consistent cell overflow behavior.
- Add adaptive experience adapters for DataView presentation defaults.

## Notes

- Core runtime interface is consumed by all presentation runtimes — changes here affect both web and mobile.
- Must remain platform-agnostic; no React or React Native imports allowed.
- API surface changes require coordinated updates in both downstream runtimes.


---

## @lssm-tech/lib.presentation-runtime-next

Description: Next.js lane for contract-driven marketing SEO/LLMO: metadata, JSON-LD, sitemap, robots, and llms.txt/agents.json route handlers
Path: packages/libs/presentation-runtime-next
URL: /llms/lib.presentation-runtime-next

# @lssm-tech/lib.presentation-runtime-next

Next.js lane for contract-driven marketing **SEO / LLMO**. It maps the
framework-neutral metadata produced by
`@lssm-tech/lib.presentation-runtime-core/marketing` into Next.js primitives and
serves AI-discovery artifacts.

This is the **only** presentation-runtime package allowed to import `next`.
`presentation-runtime-core` and `presentation-runtime-react` stay Next-free.

## Adapters

| Export | Purpose |
| ------ | ------- |
| `toNextMetadata(meta, opts?)` | `NormalizedMetadata` → Next `Metadata` (hreflang via `negotiateLocale`). |
| `JsonLd`, `StructuredData`, `serializeJsonLd` | JSON-LD `<script>` rendering from resolved schema.org shapes. |
| `buildSitemap(blueprint, opts?)` | `AppBlueprintSpec.routes` → `MetadataRoute.Sitemap`. |
| `buildRobots(aiDiscovery, opts?)` | `AiDiscoveryConfig.crawlerPolicy` → `MetadataRoute.Robots`. |
| `createLlmoRouteHandlers(emitter, opts?)` | `/llms.txt`, `/llms-full.md`, `/agents.json` route handlers with CDN cache headers. |

## Usage

### Page metadata + JSON-LD

```tsx
// app/pricing/page.tsx
import type { Metadata } from 'next';
import { transformAppConfigSeo } from '@lssm-tech/lib.presentation-runtime-core/marketing';
import { toNextMetadata, StructuredData } from '@lssm-tech/lib.presentation-runtime-next';
import { resolvedAppConfig } from '@/app-config';

const normalized = transformAppConfigSeo(resolvedAppConfig, { routePath: '/pricing' });

export const metadata: Metadata = toNextMetadata(normalized);

export default function PricingPage() {
  return (
    <>
      <StructuredData metadata={normalized} />
      {/* … */}
    </>
  );
}
```

### sitemap + robots

```ts
// app/sitemap.ts
import { buildSitemap } from '@lssm-tech/lib.presentation-runtime-next';
import { blueprint } from '@/app-config';
export default function sitemap() {
  return buildSitemap(blueprint, { supportedLocales: ['en', 'fr'], defaultLocale: 'en' });
}

// app/robots.ts
import { buildRobots } from '@lssm-tech/lib.presentation-runtime-next';
import { blueprint } from '@/app-config';
export default function robots() {
  return buildRobots(blueprint.aiDiscovery, {
    baseUrl: 'https://contractspec.dev',
    sitemapUrl: 'https://contractspec.dev/sitemap.xml',
  });
}
```

### LLMO route handlers (ISR + CDN cache)

```ts
// app/llms.txt/route.ts
import { createLlmoRouteHandlers } from '@lssm-tech/lib.presentation-runtime-next';
import { llmoEmitter } from '@/app-config'; // @lssm-tech/lib.content-gen LlmoEmitter

// Next.js segment config must be statically analyzable; keep this literal in the route file.
export const revalidate = 3600;
export const GET = createLlmoRouteHandlers(llmoEmitter).llmsTxt;
```

The `LlmoEmitter` contract is declared structurally in `./llmo-routes` so the
concrete `@lssm-tech/lib.content-gen` emitter is injected by the app.


---

## @lssm-tech/lib.presentation-runtime-react-native

Description: React Native presentation runtime for mobile apps
Path: packages/libs/presentation-runtime-react-native
URL: /llms/lib.presentation-runtime-react-native

# @lssm-tech/lib.presentation-runtime-react-native

Website: https://contractspec.io

**React Native presentation runtime for mobile apps.**

## What It Provides

- **Layer**: lib.
- **Consumers**: mobile apps.
- Related ContractSpec packages include `@lssm-tech/lib.presentation-runtime-core`, `@lssm-tech/lib.presentation-runtime-react`, `@lssm-tech/lib.ui-kit`, `@lssm-tech/tool.bun`.
- Related ContractSpec packages include `@lssm-tech/lib.presentation-runtime-core`, `@lssm-tech/lib.presentation-runtime-react`, `@lssm-tech/lib.ui-kit`, `@lssm-tech/tool.bun`.

## Installation

`npm install @lssm-tech/lib.presentation-runtime-react-native`

or

`bun add @lssm-tech/lib.presentation-runtime-react-native`

## Usage

Import the root entrypoint from `@lssm-tech/lib.presentation-runtime-react-native`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/nativewind-env.d.ts` is part of the package's public or composition surface.
- `src/useContractTable.ts` is part of the package's public or composition surface.
- `src/useDataViewTable.ts` is part of the package's public or composition surface.
- `src/useVisualizationModel.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./nativewind-env.d` resolves through `./src/nativewind-env.d.ts`.
- Export `./useContractTable` resolves through `./src/useContractTable.ts`.
- Export `./useDataViewTable` resolves through `./src/useDataViewTable.ts`.
- Export `./useVisualizationModel` resolves through `./src/useVisualizationModel.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit -p tsconfig.json
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add table capabilities.

## Notes

- Must stay compatible with presentation-runtime-core; do not diverge from the shared interface.
- NativeWind integration is platform-specific — changes must be tested on actual devices/simulators.
- Avoid web-only APIs; all code must run in React Native's JavaScript environment.


---

## @lssm-tech/lib.presentation-runtime-react

Description: React presentation runtime with workflow components
Path: packages/libs/presentation-runtime-react
URL: /llms/lib.presentation-runtime-react

# @lssm-tech/lib.presentation-runtime-react

Website: https://contractspec.io

**React presentation runtime with workflow components.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, apps.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.presentation-runtime-core`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/tool.bun`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.presentation-runtime-core`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/tool.bun`.

## Installation

`npm install @lssm-tech/lib.presentation-runtime-react`

or

`bun add @lssm-tech/lib.presentation-runtime-react`

## Usage

Import the root entrypoint from `@lssm-tech/lib.presentation-runtime-react`, or choose a documented subpath when you only need one part of the package surface.

## Adaptive Data Views

`useAdaptiveDataView` connects ContractSpec adaptive experience state to DataView renderers. It resolves safe defaults for view mode, density, data depth, and page size, then emits neutral interaction evidence when users manually change DataView settings.

The hook is intentionally vertical-agnostic: applications provide context, policy, constraints, and optional event emitters; the hook returns renderer props and explainable state. Explicit user choices remain stronger than inferred behavior, and emitted events describe observations rather than user labels.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/nativewind-env.d.ts` is part of the package's public or composition surface.
- `src/presentation-runtime-react.feature.ts` is part of the package's public or composition surface.
- `src/table.state.ts` is part of the package's public or composition surface.
- `src/table.types.ts` is part of the package's public or composition surface.
- `src/table.utils.test.ts` is part of the package's public or composition surface.
- `src/table.utils.ts` is part of the package's public or composition surface.
- `src/useContractTable.models.tsx` is part of the package's public or composition surface.
- `src/useContractTable.tsx` is part of the package's public or composition surface.
- `src/useAdaptiveDataView.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./nativewind-env.d` resolves through `./src/nativewind-env.d.ts`.
- Export `./presentation-runtime-react.feature` resolves through `./src/presentation-runtime-react.feature.ts`.
- Export `./table.state` resolves through `./src/table.state.ts`.
- Export `./table.types` resolves through `./src/table.types.ts`.
- Export `./table.utils` resolves through `./src/table.utils.ts`.
- Export `./useContractTable` resolves through `./src/useContractTable.tsx`.
- Export `./useContractTable.models` resolves through `./src/useContractTable.models.tsx`.
- Export `./useAdaptiveDataView` resolves through `./src/useAdaptiveDataView.ts`.
- Export `./useDataViewTable` resolves through `./src/useDataViewTable.tsx`.
- Export `./useVisualizationModel` resolves through `./src/useVisualizationModel.ts`.
- Export `./useWorkflow` resolves through `./src/useWorkflow.ts`.
- Export `./WorkflowStepper` resolves through `./src/WorkflowStepper.tsx`.
- Export `./WorkflowStepRenderer` resolves through `./src/WorkflowStepRenderer.tsx`.
- The package publishes 13 export subpaths plus the root entrypoint; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit -p tsconfig.json
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add data visualization capabilities.
- Add table capabilities.
- Propagate DataView table overflow metadata through `useDataViewTable` so
  renderers can truncate, wrap, expand, or initially hide columns consistently.
- Add `useAdaptiveDataView` for adaptive DataView defaults and neutral interaction events.

## Notes

- Workflow component API is consumed by bundles — breaking changes require coordinated updates.
- Must stay compatible with presentation-runtime-core interface.
- Hook signatures (`useWorkflow`) are public API; parameter changes are breaking.


---

## @lssm-tech/lib.product-intent-utils

Description: Prompt builders and validators for product-intent workflows.
Path: packages/libs/product-intent-utils
URL: /llms/lib.product-intent-utils

# @lssm-tech/lib.product-intent-utils

Website: https://contractspec.io

**Prompt builders and validators for product-intent workflows.**

## What It Provides

- **Layer**: lib.
- **Consumers**: module.product-intent-core, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.product-intent-utils`

or

`bun add @lssm-tech/lib.product-intent-utils`

## Usage

Import the root entrypoint from `@lssm-tech/lib.product-intent-utils`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/impact-engine.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/project-management-sync.ts` is part of the package's public or composition surface.
- `src/prompts.ts` is part of the package's public or composition surface.
- `src/ticket-pipeline-runner.ts` is part of the package's public or composition surface.
- `src/ticket-pipeline.ts` is part of the package's public or composition surface.
- `src/ticket-prompts.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Prompt templates directly affect AI output quality — test changes against representative inputs.
- Validation schemas must match contracts-spec definitions; drift causes silent mismatches.
- Changes here propagate to product-intent-core and all dependent bundles.


---

## @lssm-tech/lib.progressive-delivery

Description: (none)
Path: packages/libs/progressive-delivery
URL: /llms/lib.progressive-delivery

# @lssm-tech/lib.progressive-delivery

**Progressive delivery and canary release primitives. Provides strategy definitions and rollout logic for safe, incremental deployments.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- Related ContractSpec packages include `@lssm-tech/lib.observability`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.observability`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.progressive-delivery`

or

`bun add @lssm-tech/lib.progressive-delivery`

## Usage

Import the root entrypoint from `@lssm-tech/lib.progressive-delivery`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/canary-analyzer.ts` is part of the package's public or composition surface.
- `src/canary-controller.ts` is part of the package's public or composition surface.
- `src/deployment-coordinator.ts` is part of the package's public or composition surface.
- `src/events.ts` is package-level event definitions.
- `src/feature-flags.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/rollback-manager.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Delivery strategies must be deterministic — same input must produce same rollout decision.
- Peer dependency on observability; ensure OTel integration stays aligned.
- Strategy interface changes affect all deployment pipelines consuming this lib.


---

## @lssm-tech/lib.provider-ranking

Description: AI provider ranking: benchmark ingestion, scoring, and model comparison
Path: packages/libs/provider-ranking
URL: /llms/lib.provider-ranking

# @lssm-tech/lib.provider-ranking

Website: https://contractspec.io

**AI provider ranking: benchmark ingestion, scoring, and model comparison.**

## What It Provides

- **Layer**: lib.
- **Consumers**: module.provider-ranking.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.provider-ranking`

or

`bun add @lssm-tech/lib.provider-ranking`

## Usage

Import the root entrypoint from `@lssm-tech/lib.provider-ranking`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/eval` is part of the package's public or composition surface.
- `src/in-memory-store.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/ingesters` is part of the package's public or composition surface.
- `src/scoring` is part of the package's public or composition surface.
- `src/store.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./eval` resolves through `./src/eval/index.ts`.
- Export `./eval/runner` resolves through `./src/eval/runner.ts`.
- Export `./eval/types` resolves through `./src/eval/types.ts`.
- Export `./in-memory-store` resolves through `./src/in-memory-store.ts`.
- Export `./ingesters` resolves through `./src/ingesters/index.ts`.
- Export `./ingesters/artificial-analysis` resolves through `./src/ingesters/artificial-analysis.ts`.
- Export `./ingesters/chatbot-arena` resolves through `./src/ingesters/chatbot-arena.ts`.
- Export `./ingesters/fetch-utils` resolves through `./src/ingesters/fetch-utils.ts`.
- Export `./ingesters/open-llm-leaderboard` resolves through `./src/ingesters/open-llm-leaderboard.ts`.
- Export `./ingesters/registry` resolves through `./src/ingesters/registry.ts`.
- Export `./ingesters/swe-bench` resolves through `./src/ingesters/swe-bench.ts`.
- Export `./ingesters/types` resolves through `./src/ingesters/types.ts`.
- Export `./provider-ranking.feature` resolves through `./src/provider-ranking.feature.ts`.
- Export `./routing` resolves through `./src/routing/index.ts`.
- Export `./routing/classify-prompt` resolves through `./src/routing/classify-prompt.ts`.
- Export `./routing/config` resolves through `./src/routing/config.ts`.
- Export `./routing/escalation` resolves through `./src/routing/escalation.ts`.
- Export `./routing/model-capabilities` resolves through `./src/routing/model-capabilities.ts`.
- Export `./routing/profiles` resolves through `./src/routing/profiles.ts`.
- Export `./routing/resolve-difficulty` resolves through `./src/routing/resolve-difficulty.ts`.
- Export `./routing/role-matrix` resolves through `./src/routing/role-matrix.ts`.
- Export `./routing/scoring` resolves through `./src/routing/scoring.ts`.
- Export `./routing/select-model` resolves through `./src/routing/select-model.ts`.
- Export `./routing/telemetry` resolves through `./src/routing/telemetry.ts`.
- Export `./routing/types` resolves through `./src/routing/types.ts`.
- Export `./routing/weights` resolves through `./src/routing/weights.ts`.
- Export `./scoring` resolves through `./src/scoring/index.ts`.
- Export `./scoring/composite-scorer` resolves through `./src/scoring/composite-scorer.ts`.
- Export `./scoring/dimension-weights` resolves through `./src/scoring/dimension-weights.ts`.
- Export `./scoring/normalizer` resolves through `./src/scoring/normalizer.ts`.
- Export `./store` resolves through `./src/store.ts`.
- Export `./types` resolves through `./src/types.ts`.
- The package publishes 32 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- Store interface is the adapter boundary — do not leak implementation details.
- Scoring algorithms must stay deterministic (no randomness, no side effects).
- Benchmark dimension enum is shared across ingesters and scoring — keep in sync.

## Agent-aware routing

`@lssm-tech/lib.provider-ranking/routing` adds deterministic Builder model routing without executing providers. Use `selectModelForAgent(input)` to classify difficulty, apply manual thinking and risk floors, enforce required capabilities, select cheap/optimized/best/critical policy, and return an inspectable routing decision.

Critical risk (`payments`, `contract-liability`, `compliance`, destructive data loss, legal) cannot be downgraded by budget mode or manual thinking settings.


---

## @lssm-tech/lib.provider-runtime

Description: Builder provider-runtime helpers for routing, context prep, runtime targets, and receipt normalization.
Path: packages/libs/provider-runtime
URL: /llms/lib.provider-runtime

# @lssm-tech/lib.provider-runtime

Website: https://contractspec.io

Builder provider-runtime helpers for runtime-target normalization, provider registration, routing policy upserts, execution-context preparation, receipt normalization, and comparison records.

## What It Provides

- Runtime-target and external-provider record factories.
- Routing-policy and execution-context normalization helpers.
- Managed-first Builder routing-policy bootstrap helpers.
- Provider-output normalization into receipts, sources, patch proposals, activity records, and mobile review cards.
- Comparison-run record factories shared by Builder runtime and compatibility integrations.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./ai-improvement` exposes AI-improvement provider receipt normalization helpers.


## Runtime and credential mode taxonomy

Runtime target modes are limited to `managed`, `local`, and `hybrid`. Credential ownership modes are a separate resolver taxonomy (`managed`, `byok`, `local`, `ephemeral`, and `none`) and must not be accepted as runtime target modes. Provider-runtime helpers filter mixed mode arrays and preserve existing runtime defaults instead of coercing credential ownership tokens such as `byok` into managed runtime execution.

Use `redactCredentialResolverPayload` before logging resolver payloads that may include credential-looking fields. The helper preserves non-secret taxonomy fields such as `runtimeMode` while replacing token, secret, API key, authorization, password, credential, and private-key fields with `[redacted]`.

## Notes

- This package is a compatibility surface. Prefer additive evolution.
- It carries provider/runtime control-plane logic that should remain reusable outside the Builder runtime package.


---

## @lssm-tech/lib.provider-spec

Description: Provider routing and runtime-target contracts for ContractSpec Builder.
Path: packages/libs/provider-spec
URL: /llms/lib.provider-spec

# @lssm-tech/lib.provider-spec

Website: https://contractspec.io

Typed provider-routing, runtime-target, execution-receipt, comparison, and patch-proposal contracts for the Builder control plane.

## What It Provides

- Runtime-mode, provider-kind, task-type, risk, and comparison enums.
- Runtime target, handshake, trust-profile, and lease contracts.
- External execution provider, routing policy, context bundle, receipt, and patch proposal types.
- Validation helpers for routing policies, receipts, and runtime target records.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./types` resolves through `./src/types.ts`
- `./validation` resolves through `./src/validation.ts`

## Notes

- This package is a compatibility surface. Prefer additive evolution.
- Provider routing stays explicit policy, not hidden heuristics.


---

## @lssm-tech/lib.runtime-sandbox

Description: (none)
Path: packages/libs/runtime-sandbox
URL: /llms/lib.runtime-sandbox

# @lssm-tech/lib.runtime-sandbox

**Browser-compatible database abstraction built on PGLite for client-side SQL execution.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, apps.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.

## Installation

`npm install @lssm-tech/lib.runtime-sandbox`

or

`bun add @lssm-tech/lib.runtime-sandbox`

## Usage

Import the root entrypoint from `@lssm-tech/lib.runtime-sandbox`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/ports` is part of the package's public or composition surface.
- `src/types` is part of the package's public or composition surface.
- `src/web` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- DatabasePort interface is the adapter boundary — consumers depend on the port, not the implementation.
- PGLite adapter must stay browser-compatible (no Node-only APIs).
- Migration schema must remain stable — breaking changes require a migration path.


---

## @lssm-tech/lib.schema

Description: Schema utilities for Zod, JSON Schema, and GraphQL
Path: packages/libs/schema
URL: /llms/lib.schema

# @lssm-tech/lib.schema

Website: https://contractspec.io

**Schema utilities for Zod, JSON Schema, and GraphQL.**

## What It Provides

- **Layer**: lib.
- **Consumers**: nearly all libs, bundles, and apps.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.schema`

or

`bun add @lssm-tech/lib.schema`

## Usage

Import the root entrypoint from `@lssm-tech/lib.schema`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/entity` is part of the package's public or composition surface.
- `src/EnumType.test.ts` is part of the package's public or composition surface.
- `src/EnumType.ts` is part of the package's public or composition surface.
- `src/FieldType.test.ts` is part of the package's public or composition surface.
- `src/FieldType.ts` is part of the package's public or composition surface.
- `src/GraphQLSchemaType.test.ts` is part of the package's public or composition surface.
- `src/GraphQLSchemaType.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./entity` resolves through `./src/entity/index.ts`.
- Export `./entity/defineEntity` resolves through `./src/entity/defineEntity.ts`.
- Export `./entity/generator` resolves through `./src/entity/generator.ts`.
- Export `./entity/types` resolves through `./src/entity/types.ts`.
- Export `./EnumType` resolves through `./src/EnumType.ts`.
- Export `./FieldType` resolves through `./src/FieldType.ts`.
- Export `./GraphQLSchemaType` resolves through `./src/GraphQLSchemaType.ts`.
- Export `./JsonSchemaType` resolves through `./src/JsonSchemaType.ts`.
- Export `./ScalarFactoryCache` resolves through `./src/ScalarFactoryCache.ts`.
- The package publishes 14 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Preserve multi-surface consistency: Zod, GraphQL, and JSON Schema representations must stay aligned.
- Prefer additive changes; avoid silently weakening validation or changing scalar semantics.
- Do not edit `dist/`; source of truth is `src/`.

## Graph & Timeline Primitives

`@lssm-tech/lib.schema` ships `defineEntity` and `field` helpers for Layer-2 entity contract authoring alongside `defineContractEntity` from `@lssm-tech/lib.contracts-spec`:

```ts
import { defineEntity, field } from "@lssm-tech/lib.schema/entity/defineEntity";
```

Field helpers: `field.id()`, `field.string()`, `field.email()`, `field.createdAt()`, `field.updatedAt()`, `field.boolean()`, `field.int()`, `field.float()`.

Pair these with `defineContractEntity` when you need typed entity schemas for `entity-declarative` graph data views. They are entity-contract authoring utilities, not general-purpose schema tools.

See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for full details.


---

## @lssm-tech/lib.source-extractors

Description: Extract contract candidates from TypeScript source code across multiple frameworks (NestJS, Express, Fastify, Hono, Elysia, tRPC, Next.js)
Path: packages/libs/source-extractors
URL: /llms/lib.source-extractors

# @lssm-tech/lib.source-extractors

Website: https://contractspec.io

**Extract contract candidates from TypeScript source code across multiple frameworks (NestJS, Express, Fastify, Hono, Elysia, tRPC, Next.js).**

## What It Provides

- **Layer**: lib.
- **Consumers**: CLI, bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.source-extractors`

or

`bun add @lssm-tech/lib.source-extractors`

## Usage

Import the root entrypoint from `@lssm-tech/lib.source-extractors`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/__fixtures__` is part of the package's public or composition surface.
- `src/__snapshots__` is part of the package's public or composition surface.
- `src/codegen` is part of the package's public or composition surface.
- `src/codegen.test.ts` is part of the package's public or composition surface.
- `src/detect.test.ts` is part of the package's public or composition surface.
- `src/detect.ts` is part of the package's public or composition surface.
- `src/edge-cases.test.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./codegen` resolves through `./src/codegen/index.ts`.
- Export `./extractors` resolves through `./src/extractors/index.ts`.
- Export `./types` resolves through `./src/types.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Extractor interface must support multiple frameworks — keep it generic.
- Codegen output must stay deterministic (same input → same output, always).


---

## @lssm-tech/lib.support-bot

Description: AI support bot framework with RAG and ticket management
Path: packages/libs/support-bot
URL: /llms/lib.support-bot

# @lssm-tech/lib.support-bot

Website: https://contractspec.io

**AI support bot framework with RAG and ticket management.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.knowledge`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, ...

## Installation

`npm install @lssm-tech/lib.support-bot`

or

`bun add @lssm-tech/lib.support-bot`

## Usage

Import the root entrypoint from `@lssm-tech/lib.support-bot`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/bot` is part of the package's public or composition surface.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/rag` is part of the package's public or composition surface.
- `src/spec.ts` is part of the package's public or composition surface.
- `src/tickets` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./bot` resolves through `./src/bot/index.ts`.
- Export `./bot/auto-responder` resolves through `./src/bot/auto-responder.ts`.
- Export `./bot/feedback-loop` resolves through `./src/bot/feedback-loop.ts`.
- Export `./bot/tools` resolves through `./src/bot/tools.ts`.
- Export `./i18n` resolves through `./src/i18n/index.ts`.
- Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`.
- Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`.
- Export `./i18n/catalogs/es` resolves through `./src/i18n/catalogs/es.ts`.
- Export `./i18n/catalogs/fr` resolves through `./src/i18n/catalogs/fr.ts`.
- The package publishes 19 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint/test regressions after voice capability updates.
- Add full i18n support across all 10 packages (en/fr/es, 460 keys).

## Notes

- Bot spec interface follows ai-agent patterns — keep aligned with contracts-spec.
- Ticket schema is shared — changes affect consumers downstream.
- RAG pipeline must stay compatible with the knowledge lib.


---

## @lssm-tech/lib.surface-runtime

Description: AI-native surface specs and web runtime for adaptive ContractSpec surfaces
Path: packages/libs/surface-runtime
URL: /llms/lib.surface-runtime

# @lssm-tech/lib.surface-runtime

Website: https://contractspec.io

**Surface runtime for AI-native ContractSpec experiences, including bundle specs, planners, overlays, patching, and React rendering support.**

## What It Provides

- Provides the runtime layer behind AI-planned surfaces, widget registries, overrides, and bundle resolution.
- Supports React rendering, adapter boundaries, telemetry, evaluation harnesses, and planner tooling.
- Provides a UI-agnostic RoleMorph runtime for policy-aware, role/actor-specific operating surfaces.
- Recently expanded to better align with AI chat, i18n, workflow tools, and bundle export needs.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.

## Installation

`npm install @lssm-tech/lib.surface-runtime`

or

`bun add @lssm-tech/lib.surface-runtime`

## Usage

Import the root entrypoint from `@lssm-tech/lib.surface-runtime`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/spec/` defines module-bundle and surface-patch validation surfaces.
- `src/runtime/` contains planners, registries, patch application, policy evaluation, and bundle resolution.
- `src/rolemorph/` contains serializable RoleMorph contracts, the pure surface resolver, validation, AirDesk and non-AirDesk fixtures, and CompanyOS policy projection helpers.
- `src/react/` exports the React integration layer for bundle rendering and override handling.
- `src/adapters/`, `src.telemetry/`, `src.evals/`, and `src.examples/` support integration and verification flows.
- `src/index.ts` is the root public barrel and package entrypoint.

## RoleMorph runtime

RoleMorph resolves ContractSpec operating surfaces for different human and AI actors without generating arbitrary UI code. The exported `./rolemorph` subpath includes:

- `RoleMorphSurfaceSpec`, actor, component-registry, action-boundary, explanation, diagnostic, and resolution-result types;
- `resolveRoleMorphSurface()` for deterministic workflow/role/intent matching, policy and permission boundary evaluation, hidden-data explanations, and agent action-plan projection;
- `validateRoleMorphSurfaceContext()` for missing binding diagnostics and generated-UI escape-hatch rejection;
- AirDesk plus service-delivery and internal-approval fixtures for founder, ops manager, frontline staff, customer, AI agent, and auditor surfaces.
- CompanyOS policy projection helpers that compose policy/authority decisions into RoleMorph boundaries and fail closed when projections are missing or actor/workflow-mismatched.

RoleMorph may consume adaptive hints, but authorization, policy, permissions, and action boundaries remain explicit contract inputs.


## Ontology-linked RoleMorph authoring

RoleMorph decisions participate in the ontology graph through stable refs rather than local-only labels. Surface specs and resolution results should be able to explain which ontology actor, work, surface, resource, adaptation, and safety refs influenced visible components, hidden data, and enabled actions.

For the Autonomous Work Order slice, founder/operator/auditor/agent surfaces must all point at the same work-order graph: pages and DataViews are `surface` nodes, orders and workflow transitions are `work` nodes, humans and agents are `actor` nodes, source documents and evidence receipts are `resource` nodes, behavior/adaptive decisions are `adaptation` nodes, and policy/approval/audit/redaction records are `safety` nodes.

High-impact RoleMorph actions must fail closed when ontology safety refs are missing or mismatched. Display-only and low-risk render decisions may remain policy-optional, but explanations should still carry evidence refs when they are part of a governed work-order trace.

## Public Entry Points

- Exports runtime, spec, React integration, adapters, telemetry, eval, and example subpaths for AI-native surface composition.
- Export `.` resolves through `./src/index.ts`.
- Export `./adapters` resolves through `./src/adapters/index.ts`.
- Export `./adapters/ai-sdk-stub` resolves through `./src/adapters/ai-sdk-stub.ts`.
- Export `./adapters/blocknote-stub` resolves through `./src/adapters/blocknote-stub.tsx`.
- Export `./adapters/dnd-kit-adapter` resolves through `./src/adapters/dnd-kit-adapter.tsx`.
- Export `./adapters/dnd-kit-stub` resolves through `./src/adapters/dnd-kit-stub.ts`.
- Export `./adapters/floating-ui-stub` resolves through `./src/adapters/floating-ui-stub.tsx`.
- Export `./adapters/interfaces` resolves through `./src/adapters/interfaces.ts`.
- Export `./adapters/motion-stub` resolves through `./src/adapters/motion-stub.ts`.
- Export `./adapters/resizable-panels-stub` resolves through `./src/adapters/resizable-panels-stub.tsx`.
- Export `./rolemorph` resolves through `./src/rolemorph/index.ts`.
- Export `./rolemorph/types` resolves through `./src/rolemorph/types.ts`.
- Export `./rolemorph/companyos-policy` resolves through `./src/rolemorph/companyos-policy.ts`.
- Export `./rolemorph/companyos-policy-types` resolves through `./src/rolemorph/companyos-policy-types.ts`.
- Export `./rolemorph/companyos-policy-fail-closed` resolves through `./src/rolemorph/companyos-policy-fail-closed.ts`.
- Export `./rolemorph/resolver` resolves through `./src/rolemorph/resolver.ts`.
- Export `./rolemorph/validation` resolves through `./src/rolemorph/validation.ts`.
- Export `./rolemorph/fixtures` resolves through `./src/rolemorph/fixtures/index.ts`.
- Export `./rolemorph/fixtures/airdesk` resolves through `./src/rolemorph/fixtures/airdesk.ts`.
- Export `./rolemorph/fixtures/service-delivery` resolves through `./src/rolemorph/fixtures/service-delivery.ts`.
- Export `./rolemorph/fixtures/internal-approval` resolves through `./src/rolemorph/fixtures/internal-approval.ts`.
- The package publishes 65 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile && node scripts/fix-use-client-directive.mjs
- `bun run build:types` — contractspec-bun-build types
- `bun run lint:adapters` — node scripts/lint-adapters.mjs
- `bun run test:evals` — bun test src/evals/
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Export, sidebar, workflow tools, slotContent.
- Vercel AI SDK parity + surface-runtime i18n and bundle alignment.
- Bundle spec alignment, i18n support, PM workbench pilot.
- RoleMorph first canonical serialized runtime slice with AirDesk fixtures and Builder preview inputs.
- RoleMorph gap-closure hardening adds non-AirDesk fixtures and a fail-closed CompanyOS policy projection bridge without provider or storage side effects.

## Notes

- No direct third-party UI imports outside `src/adapters/` (when adapters are added).
- Every surface must have verification.dimensions for all 7 preference dimensions.
- Adapter rule: BlockNote, dnd-kit, etc. behind adapter boundaries only.

## RoleMorph rich content adapter

`@lssm-tech/lib.surface-runtime/rolemorph/rich-content-adapter` converts RoleMorph permission and policy decisions into rich-content redaction policies for code and diff payloads. Use it before rendering governed `CodeBlock` and `DiffBlock` surfaces so denied references or sensitivity classes are removed from client-safe models.


---

## @lssm-tech/lib.testing-helpers

Description: Shared test infrastructure helpers for Phase 1 / Phase 3 cockpit-kit extraction
Path: packages/libs/testing-helpers
URL: /llms/lib.testing-helpers

(No README.md)

---

## @lssm-tech/lib.testing

Description: Contract-aware testing utilities and runners
Path: packages/libs/testing
URL: /llms/lib.testing

# @lssm-tech/lib.testing

Website: https://contractspec.io

**Contract-aware testing utilities and runners.**

## What It Provides

- **Layer**: lib.
- **Consumers**: CLI, bundles.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.

## Installation

`npm install @lssm-tech/lib.testing`

or

`bun add @lssm-tech/lib.testing`

## Usage

Import the root entrypoint from `@lssm-tech/lib.testing`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- `src/generator` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/recorder` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- TrafficRecorder and GoldenTestGenerator interfaces are public API — do not break signatures.
- Test output format must stay compatible with Vitest and Jest runners.


---

## @lssm-tech/lib.translation-runtime

Description: Framework-independent ContractSpec translation runtime
Path: packages/libs/translation-runtime
URL: /llms/lib.translation-runtime

# @lssm-tech/lib.translation-runtime

Framework-independent runtime for ContractSpec translation contracts.

`@lssm-tech/lib.contracts-spec` remains the canonical source of truth for `TranslationSpec` contracts, metadata, ownership, versions, locale variants, validation, fallback declarations, and override policy. This package consumes those specs at runtime to resolve, format, cache, load, diagnose, and serialize translations across server code, React, React Native, CLIs, and tests.

## Boundaries

- **Spec layer:** `@lssm-tech/lib.contracts-spec/translations`
- **Runtime layer:** this package
- **Formatter engine:** `MessageFormatter`, with `createIntlMessageFormatter()` backed by FormatJS/`intl-messageformat`
- **Adapters:** React/design-system/i18next integrations consume this runtime and are optional downstream layers

## Example

```ts
import { createTranslationRuntime } from "@lssm-tech/lib.translation-runtime";
import { enMessages, frMessages } from "./catalogs";

const runtime = createTranslationRuntime({
  defaultLocale: "en-US",
  requestedLocales: ["fr-FR", "en-US"],
  specs: [enMessages, frMessages],
});

runtime.t("cart.itemCount", { count: 3 });
```

## SSR and hydration — factory stack (preferred)

Use the factory-stack snapshot surface from `@lssm-tech/lib.contracts-spec/translations` for new integrations. It produces a versioned, framework-neutral `I18nFactoryHydrationPayload` that never aliases live catalog references:

```ts
import {
  createI18nFactory,
  createI18nFactoryFromHydrationPayload,
} from "@lssm-tech/lib.contracts-spec/translations";
import { loadShardDelta, createStaticBundleLoader } from "@lssm-tech/lib.translation-runtime/loader";

// Server (RSC / route handler)
const factory = createI18nFactory({
  catalogs: [enMessages, frMessages, esMessages],
  supportedLocales: ["en", "fr", "es"],
  defaultLocale: "en",
});
const payload = factory.hydrationPayload(undefined, requestLocale);
// Transfer payload to the client (inline script, RSC stream, etc.)

// Client — rehydrate without refetching or renegotiating locale
const instance = createI18nFactoryFromHydrationPayload(payload);
instance.t("greeting", { name: "Alice" });

// Navigation: lazy-load only new shards
const loader = createStaticBundleLoader(allCatalogs);
await loadShardDelta({ loaded: sharedSpecKeys, required: pageSpecKeys, locales: [locale] }, loader);
```

`validateI18nFactorySnapshot(snapshot)` returns human-readable error strings for partial or unknown snapshots before hydration.

## SSR and hydration — deprecated runtime (compat only)

> **Deprecated.** `createTranslationRuntime` is dead-but-present. `createTranslationRuntimeFromPreferences` remains as a compat shim. Do not add new call sites to the active SSR render path. Engine deletion is a residual follow-up; see `.omc/plans/ralplan-translation-catalog-sharding-ssr.md`.

```ts
import { createTranslationRuntime } from "@lssm-tech/lib.translation-runtime";
// … (legacy pattern preserved for compat)
```

`createTranslationSnapshotStreamChunk(snapshot)` returns a cloned payload safe to enqueue before later async catalog loads mutate the request runtime. `validateTranslationHydrationPayload(payload)` returns `invalid_snapshot` diagnostics for unsupported payloads before hydration.

## Shard-scoped catalog loading

`src/loader.ts` accepts an optional `specKeys?` array on `TranslationBundleLoadRequest` to load a subset of catalogs per route. Use `loadShardDelta` to fetch only the incremental shards needed on navigation:

```ts
import { computeShardDelta, loadShardDelta } from "@lssm-tech/lib.translation-runtime/loader";

const delta = computeShardDelta(alreadyLoadedSpecKeys, requiredSpecKeys);
// delta = requiredSpecKeys not yet loaded

const newCatalogs = await loadShardDelta(
  { loaded: alreadyLoadedSpecKeys, required: requiredSpecKeys, locales: [locale] },
  bundleLoader,
);
```

Absent `specKeys` ⇒ all keys pass (existing `{specKey, locales}` semantics unchanged).

## Optimization surfaces (Model A — per-request inline payload)

> **Scope: per-request inline HTML reduction.** Catalogs remain bundled and cached in the JS bundle (shipped once per deploy). These optimizations reduce the per-request inline `<script>` hydration payload — NOT total transferred bytes. The ~90% total-bytes win requires Model B (catalog code-splitting + load-bearing inline payload). See `.omc/plans/ralplan-translation-catalog-sharding-ssr.md` § "Optimization Wave — ARCHITECTURE DECISION: Model A".

### O2/O3 — Slim inline payload + value-pool dedup

Enable slim mode on your scoped hydration builder to strip spec metadata from each shard before serialization. The value-pool dedup step folds message values appearing ≥2× into a `values[]` pool; expansion is automatic on rehydration.

**Realized:** `/` en 96.6 KB → 37.8 KB (−61%); `/companyos/founder` en 93.9 KB → 35.6 KB (−62%); fr routes ~−60%. No-flash (AC1) re-proven through slim+dedup path. CI budget gates: single-locale ≤ 64 KB, with-fallback ≤ 128 KB.

O3 adds only ~2% over O2 (five lanes have disjoint key namespaces; ~53 pooled value strings). The projected ~41 KB en-fallback win requires a shared-base architecture follow-up.

### O4 — Precompiled ICU AST fast-path (`./precompile` subpath)

At bundle build time, call `buildPrecompiledIcuCatalogFromSpecs(specs)` from `@lssm-tech/lib.translation-runtime/precompile` over your `TranslationSpec[]` set. This produces a `PrecompiledIcuCatalog` with FormatJS IR AST entries for every message. Pass `createPrecompiledIcuLookup(catalog)` as the `precompiled` option to `createIntlMessageFormatter` to activate the parse-skip fast-path:

```ts
// build step (runs once at bundle time, e.g. in your bundler plugin)
import {
  buildPrecompiledIcuCatalogFromSpecs,
  createPrecompiledIcuLookup,
  serializePrecompiledIcuCatalog,
} from "@lssm-tech/lib.translation-runtime/precompile";

const catalog = buildPrecompiledIcuCatalogFromSpecs([enMessages, frMessages]);
// optionally serialize and ship as a build asset
const serialized = serializePrecompiledIcuCatalog(catalog);

// runtime (wire the formatter with the precompiled lookup)
import { parsePrecompiledIcuCatalog, createPrecompiledIcuLookup } from "@lssm-tech/lib.translation-runtime/precompile";
import { createIntlMessageFormatter } from "@lssm-tech/lib.translation-runtime/formatters/intl-messageformat";

const precompiled = createPrecompiledIcuLookup(parsePrecompiledIcuCatalog(serialized));
const formatter = createIntlMessageFormatter({ precompiled });
// formatter skips ICU re-parsing for any message with a precompiled entry
```

Additive opt-in — messages without a precompiled entry fall back to the standard parser transparently. **Scope: formatter-path latency win only.** Factory proof routes use `{placeholder}` interpolation (no ICU); O4 benefits apply to ICU-heavy catalogs (plural/select/date/number).

### O5b (#17) — Scoped-hydration intersection (wired, currently no-op)

> **App-layer wiring — not a `translation-runtime` export.** `intersectScopedI18nHydration` and `isEffectiveReachabilityMap` are implemented in `web-application-monolith`'s scoped hydration path (`packages/apps/web-application-monolith/src/i18n/scoped-hydration.reachability.ts` and `reachability-map.loader.ts`). They compose with the loader's `loadShardDelta` but are not themselves library APIs. Do not import them from `@lssm-tech/lib.translation-runtime`.

Wired into `getRequestI18n` and fail-safe (pruned keys resolve via the bundled combined runtime — no flash). Currently no-op (77/129 `t()` call sites use dynamic dispatch; scanner emits retain-all map). Auto-activates if a precise reachability map ships. Zero regression.

### O5 (#14) — Dead-key audit tool (`@lssm-tech/tool.i18n-prune`)

`@lssm-tech/tool.i18n-prune` in `packages/tools/` walks `t('key')` call sites against a `RouteShardManifest` and reports dead keys per route. Use it in CI to surface dead-key drift. It does not drive the runtime inline payload under Model A.

## Optional i18next adapter

i18next is an optional downstream adapter, not the canonical ContractSpec model. Import it through the dedicated subpath so core runtime consumers do not load i18next:

```ts
import { createInstance } from "i18next";
import {
  createI18nextInitOptions,
  exportTranslationSnapshotToI18next,
} from "@lssm-tech/lib.translation-runtime/i18next";

const exported = exportTranslationSnapshotToI18next(runtime.snapshot(), {
  assumeIcuFormatter: true,
});
const { options, diagnostics } = createI18nextInitOptions(exported);
const i18next = createInstance();

await i18next.init(options);
```

The adapter exports resources as `{ [locale]: { [namespace]: { [messageKey]: string } } }`. `TranslationSpec.locale` becomes the i18next language, while the namespace defaults to the stable `TranslationSpec.meta.key`. Flat ContractSpec keys such as `"cart.items"` remain flat because generated init options set `keySeparator: false`.

ContractSpec ICU messages are exported intact. i18next does not use ICU as its default JSON format, so apps that call `i18next.t()` for ICU plural/select/selectordinal messages must install and configure an ICU-capable i18next format plugin such as `i18next-icu`. The adapter reports `i18next_icu_plugin_required` unless you explicitly acknowledge that formatting layer.

For SSR, export from the same runtime snapshot used by the server render and reuse those resources/options on the client. Do not let client-only language detection renegotiate the first hydrated render. For React Native, pass the host-selected locale explicitly; the adapter does not use DOM APIs or browser storage.

## React Native

The core runtime uses no DOM APIs. Locale detection is host-owned; pass device or user locales into `requestedLocales`. Ensure the host JS engine provides the required `Intl` APIs or install platform polyfills before using the default formatter.


---

## @lssm-tech/lib.ui-kit-core

Description: Core UI primitives and utilities
Path: packages/libs/ui-kit-core
URL: /llms/lib.ui-kit-core

# @lssm-tech/lib.ui-kit-core

`@lssm-tech/lib.ui-kit-core` is the shared foundation for the UI packages. It provides the low-level `cn()` utility plus the canonical shared interface layer used by `ui-kit` and `ui-kit-web`.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.ui-kit-core`

or

`npm install @lssm-tech/lib.ui-kit-core`

## What belongs here

This package is intentionally small:

- Very low-level, zero-surprise UI helpers shared across `ui-kit`, `ui-kit-web`, and `ui-link`.
- Small shared utilities that are useful across multiple UI packages and do not belong in a component package.
- Platform-neutral shared UI contracts under `./interfaces`.

## API map

- root export: `.`  
- shared interfaces subpath: `./interfaces`
- utility subpath: `./utils`
- command theme class contract: `./command-theme`
- core function: `cn(...inputs)`

## Operational semantics and gotchas

- This package is intentionally tiny.
- `./interfaces` is the shared compatibility layer for semantically matching `ui-kit` and `ui-kit-web` exports.
- `./command-theme` is a narrow shared class contract for command palette/search-trigger color states. It exists only to keep native, web, and design-system command surfaces aligned on semantic theme tokens; it is not a general design-token bucket.
- `cn()` composes `clsx` with `tailwind-merge`.
- Changes here ripple into all UI packages even though the file count is small.
- This package should stay boring and predictable.

## Compatibility guard

`ui-kit-core` also owns the registry used to compare the native and web UI kit lanes. Run the repo-level guard before adding or changing shared `./ui/*` surfaces:

```bash
bun run ui-kit:compat
```

The guard compares `packages/libs/ui-kit` and `packages/libs/ui-kit-web` exported `./ui/*` subpaths, exported symbols, and shared prop-shape contracts. Existing drift is recorded in `scripts/ui-kit-compatibility-baseline.json`; new drift should be fixed or deliberately accepted by refreshing that baseline in the same reviewed change. Shared component contracts should be declared here first under `./interfaces`, then consumed from both UI kit packages.

## When not to use this package

- Do not use it for components.
- Do not use it for design tokens.
- Do not use it for router or link abstractions.

## Related packages

- `@lssm-tech/lib.ui-kit`
- `@lssm-tech/lib.ui-kit-web`
- `@lssm-tech/lib.ui-link`

## Local commands

- `bun run lint:check`
- `bun run typecheck`

## Graph & Timeline Primitives

`@lssm-tech/lib.ui-kit-core` now exports platform-agnostic graph and timeline hooks and interfaces — pure TypeScript, no React or react-native imports.

**Hooks**: `useGraphFilter`, `useGraphLayout`, `useGraphSelection`, `useAdaptiveGraphRenderer`, `useTimelineRange`, `useTimelineZoom`

**Interfaces**: `GraphNode`, `GraphEdge`, `GraphSelection`, `GraphCanvasProps`, `TimelineEvent`, `TimelineRange`, `TimelineProps`, `TimelineGraphProps`, `GraphLayoutKind`

`useAdaptiveGraphRenderer` returns `"svg"` or `"reactflow"` based on a bounded node/edge threshold (default 300 nodes / 500 edges), enabling lazy-loading of `GraphCanvasAdvanced` in the web lane.

See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for full details.


---

## @lssm-tech/lib.ui-kit-web

Description: Web UI components with Radix primitives
Path: packages/libs/ui-kit-web
URL: /llms/lib.ui-kit-web

# @lssm-tech/lib.ui-kit-web

`@lssm-tech/lib.ui-kit-web` provides web UI components for React and Next surfaces, with accessible building blocks, Radix-based primitives, layout helpers, and web-specific UX utilities exposed through `./ui/*` subpaths.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.ui-kit-web`

or

`npm install @lssm-tech/lib.ui-kit-web`

## What belongs here

This package owns the web-first component layer:

- Radix-backed web UI components.
- Web-only accessibility helpers and route-announcement primitives.
- Map, marketing, list-page, and visualization building blocks.
- Web form, navigation, and layout primitives.

Use this package for browser and Next.js surfaces. Do not use it for native or Expo UI work.

## Core workflows

### Import a web component by subpath

```ts
import { Button } from "@lssm-tech/lib.ui-kit-web/ui/button";
import { Form } from "@lssm-tech/lib.ui-kit-web/ui/form";
```

### Wire accessibility helpers at the app root

```tsx
import {
  SRLiveRegionProvider,
  useSRLiveRegion,
} from "@lssm-tech/lib.ui-kit-web/ui/live-region";
import { SkipLink } from "@lssm-tech/lib.ui-kit-web/ui/skip-link";
import { RouteAnnouncer } from "@lssm-tech/lib.ui-kit-web/ui/route-announcer";
import { FocusOnRouteChange } from "@lssm-tech/lib.ui-kit-web/ui/focus-on-route-change";

function AppShell({ title, children }: { title: string; children: React.ReactNode }) {
  return (
    <SRLiveRegionProvider>
      <SkipLink targetId="main" />
      <RouteAnnouncer title={title} />
      <main id="main">
        <FocusOnRouteChange />
        {children}
      </main>
    </SRLiveRegionProvider>
  );
}
```

### Render the canonical account grid

The canonical data-table example lives in
[`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
Its raw browser lane renders `@lssm-tech/lib.ui-kit-web/ui/data-table`
directly:

```tsx
import { DataTable } from '@lssm-tech/lib.ui-kit-web/ui/data-table';
import { useContractTable } from '@lssm-tech/lib.presentation-runtime-react';

import { SHOWCASE_ROWS } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.data';
import { useShowcaseColumns } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.columns';
import {
  ExpandedRowContent,
  ShowcaseToolbar,
} from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.parts';

export function WebAccountGrid() {
  const columns = useShowcaseColumns();

  const controller = useContractTable({
    data: SHOWCASE_ROWS,
    columns,
    selectionMode: 'single',
    initialState: {
      sorting: [{ id: 'lastActivityAt', desc: true }],
      pagination: { pageIndex: 0, pageSize: 4 },
      columnVisibility: { notes: false },
      columnPinning: { left: ['account'], right: [] },
    },
    renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
    getCanExpand: () => true,
  });

  return (
    <DataTable
      controller={controller}
      toolbar={
        <ShowcaseToolbar
          controller={controller}
          label="Web primitive"
          primaryColumnId="account"
          toggleColumnId="notes"
          pinColumnId="owner"
          sortColumnIds={['arr', 'renewalDate']}
        />
      }
      loading={false}
      emptyState={<div>No rows available.</div>}
      footer={\`Rows \${controller.totalItems}\`}
    />
  );
}
```

Cells receive overflow behavior from the table controller. Web renderers use a
compact truncating wrapper for `truncate` and `expand`, multiline wrapping for
`wrap`, and preserve caller rendering for `none`.

Use the web primitive when you want direct control over the render surface.
For higher-level search, active chips, selection summary, and hidden-column
recovery, keep this primitive lean and layer
`@lssm-tech/lib.design-system` `DataTableToolbar` into the `toolbar` slot.

## API map

### Controls and forms

- `./ui/button`
- `./ui/button-group`
- `./ui/input`
- `./ui/input-password`
- `./ui/textarea`
- `./ui/select`
- `./ui/native-select`
- `./ui/field`
- `./ui/form`

`./ui/input-password` composes the shared input group, masked input, and
right-side visibility toggle while preserving `current-password` and
`new-password` autocomplete hints for password managers.
- `./ui/combobox`

`./ui/combobox` keeps the select-style button API compatible and also supports
editable autocomplete usage with query control, listbox ARIA wiring, loading,
empty, error, disabled-option, description, and multi-select chip states.
- `./ui/input-group`
- `./ui/input-otp`
- `./ui/spinner`
- `./ui/kbd`

### Overlays, menus, and navigation

- `./ui/dialog`
- `./ui/drawer`
- `./ui/dropdown-menu`
- `./ui/popover`
- `./ui/navigation-menu`
- `./ui/nav-layout`
- `./ui/link`

### Data display and layout

- `./ui/table`
- `./ui/data-table`
- `./ui/page-header`
- `./ui/section`
- `./ui/sidebar`
- `./ui/item`
- `./ui/chart`
- `./ui/direction`

### Accessibility helpers

- `./ui/skip-link`
- `./ui/live-region`
- `./ui/route-announcer`
- `./ui/focus-on-route-change`
- `./ui/visually-hidden`

### Hooks and grouped surfaces

- `./ui/use-media-query`
- `./ui/use-mobile`
- `./ui/use-reduced-motion`
- `./ui/use-toast`
- `./ui/utils`
- grouped subpaths under `./ui/map`, `./ui/marketing`, `./ui/usecases`, `./ui/organisms/ListPage`, and `./ui/visualization`
- shared semantic contracts are defined in `@lssm-tech/lib.ui-kit-core/interfaces`

## Public surface

The package publishes a root entry, but the meaningful consumer surface is `./ui/*`.

Consumers should import grouped subpaths directly. The public surface is best understood by category:

- controls and forms
- shadcn/Radix-style `Field` and `InputGroup` primitives for accessible labels, descriptions, errors, legends, addons, and grouped controls
- overlays and menus
- layout and navigation
- accessibility helpers
- data display
- grouped map, marketing, organisms, use-case, and visualization surfaces
- hooks and utilities

Use `package.json` as the exhaustive export map.

## Operational semantics and gotchas

- Components rely on Radix and browser or Next assumptions.
- `./ui/link` is based on `next/link`.
- `./ui/skip-link`, live-region helpers, and route announcers are first-class web-only APIs in this package.
- Storybook scripts exist here, unlike the other UI packages in this rewrite set.
- The package has optional map-related peer dependencies; map features should stay opt-in and not become implicit hard requirements.
- The root entry is not the meaningful consumer surface today.

## When not to use this package

- Do not use it for native or Expo surfaces.
- Do not use it for token orchestration or platform abstraction.
- Do not use it for framework-agnostic linking.

## Related packages

- `@lssm-tech/lib.ui-kit-core`: shared low-level utilities used across UI packages.
- `@lssm-tech/lib.ui-kit`: native-first component package for Expo and React Native surfaces.
- `@lssm-tech/lib.design-system`: higher-level design-system and composition layer built on top of the UI packages.

## Local commands

- `bun run lint:check`
- `bun run typecheck`
- `bun run test`

## Graph & Timeline Primitives

`@lssm-tech/lib.ui-kit-web` ships SVG graph and timeline primitives for web and Next.js surfaces.

**`@lssm-tech/lib.ui-kit-web/ui/graph`**:
- `GraphCanvas` — SVG-based graph renderer with layout + selection hooks
- `GraphCanvasAdvanced` — ReactFlow (`@xyflow/react`) adapter for large graphs

**`@lssm-tech/lib.ui-kit-web/ui/timeline`**:
- `Timeline` — SVG timeline with brush, axis, and event sub-modules
- `TimelineGraph` — combined timeline + graph view

All three respect `prefers-reduced-motion` via the `reducedMotion` prop.

> **Bundle-size note**: `GraphCanvasAdvanced` pulls in `@xyflow/react`. Always import it via `React.lazy(...)` — never statically. `GraphCanvas` (SVG-only) is safe for static import.

```ts
// GraphCanvas — static import OK
import { GraphCanvas } from "@lssm-tech/lib.ui-kit-web/ui/graph";

// GraphCanvasAdvanced — always lazy-load
const GraphCanvasAdvanced = React.lazy(
  () => import("@lssm-tech/lib.ui-kit-web/ui/graph").then(m => ({ default: m.GraphCanvasAdvanced }))
);
```

See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for layer placement and full import rules.


---

## @lssm-tech/lib.ui-kit

Description: Cross-platform UI components for React Native and web
Path: packages/libs/ui-kit
URL: /llms/lib.ui-kit

# @lssm-tech/lib.ui-kit

`@lssm-tech/lib.ui-kit` provides cross-platform UI components for native-first and Expo-based surfaces, with most real usage happening through `./ui/*` subpaths rather than the root barrel.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.ui-kit`

or

`npm install @lssm-tech/lib.ui-kit`

## What belongs here

This package owns the native-first component layer for ContractSpec UI work:

- React Native and Expo component wrappers.
- Shared UI building blocks such as forms, tables, overlays, navigation, loading states, marketing blocks, and visualization surfaces.
- Platform-aware helpers such as `useColorScheme` and list state helpers.

Use this package for Expo and React Native surfaces. Do not use it as the design-token layer or as the framework-agnostic link package.

## API map

### Forms and inputs

- `./ui/input`
- `./ui/input-password`
- `./ui/textarea`
- `./ui/select`
- `./ui/form`
- `./ui/field`

Native contract-driven forms consume the shared `Field` semantics through the
design-system renderer; web-only input-addon composition remains in
`@lssm-tech/lib.ui-kit-web/ui/input-group` and the design-system platform
facade.

`./ui/input-password` provides the native masked password primitive with
current/new password autocomplete hints and a right-side visibility toggle.

### Overlays and menus

- `./ui/dialog`
- `./ui/alert-dialog`
- `./ui/popover`
- `./ui/sheet`
- `./ui/dropdown-menu`
- `./ui/context-menu`
- `./ui/portal`
- `./ui/toast`
- `./ui/toolbar`

### Navigation and display

- `./ui/link`
- `./ui/sidebar`
- `./ui/navigation-menu`
- `./ui/page-header`
- `./ui/table`
- `./ui/data-table`
- `./ui/card`
- `./ui/empty-state`
- `./ui/slider`

## Data table example

The canonical data-table example lives in
[`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
Its native-first lane renders the same account-grid controller through
`@lssm-tech/lib.ui-kit/ui/data-table`:

```tsx
import { DataTable } from '@lssm-tech/lib.ui-kit/ui/data-table';
import { useContractTable } from '@lssm-tech/lib.presentation-runtime-react';

import { SHOWCASE_ROWS } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.data';
import { useShowcaseColumns } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.columns';
import {
  ExpandedRowContent,
  ShowcaseToolbar,
} from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.parts';

export function NativeAccountGrid() {
  const columns = useShowcaseColumns();

  const controller = useContractTable({
    data: SHOWCASE_ROWS,
    columns,
    selectionMode: 'single',
    initialState: {
      sorting: [{ id: 'arr', desc: true }],
      pagination: { pageIndex: 0, pageSize: 4 },
      columnVisibility: { notes: false },
      columnPinning: { left: ['account'], right: [] },
    },
    renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
    getCanExpand: () => true,
  });

  return (
    <DataTable
      controller={controller}
      toolbar={
        <ShowcaseToolbar
          controller={controller}
          label="Native primitive"
          primaryColumnId="account"
          toggleColumnId="notes"
          pinColumnId="owner"
          sortColumnIds={['arr', 'renewalDate']}
        />
      }
      loading={false}
      footer={\`Rows \${controller.rows.length}\`}
    />
  );
}
```

Cells receive overflow behavior from the table controller. Native renderers use
single-line ellipsis for `truncate` and `expand`, multiline text for `wrap`,
and preserve caller rendering for `none`.

This example explicitly demonstrates the same sorting, pagination, selection, column visibility, column resizing, left/right pinning, row expansion, loading, and empty-state contracts used by the browser lanes.

### Hooks, utilities, and grouped surfaces

- `./ui/useColorScheme`
- `./ui/useListState`
- `./ui/utils`
- grouped subpaths under `./ui/marketing`, `./ui/usecases`, and `./ui/visualization`
- icons under `./ui/icons/*`
- shared semantic contracts are defined in `@lssm-tech/lib.ui-kit-core/interfaces`

## Public surface

The current root entry exists, but it is not the meaningful consumer surface for this package.

Consumers should import `./ui/*` subpaths directly. The public surface is best understood in groups:

- atoms and controls
- forms
- overlays and menus
- navigation and layout
- data display
- loading and empty states
- marketing and use-case blocks
- organisms and visualization
- hooks, utilities, and icons

Use `package.json` as the exhaustive source of truth for all exported subpaths.

## Operational semantics and gotchas

- Consumers should import subpaths directly; the root package is not the useful primary API today.
- Many components wrap Expo, React Native, or RN-oriented primitives and dependencies.
- `./ui/link` is router-coupled through `expo-router`.
- `./ui/useColorScheme` is built on `nativewind`.
- `./ui/utils` exposes a local `cn()` helper, but the deeper compatibility dependency is `@lssm-tech/lib.ui-kit-core`.
- This package is native-first even when some components can render cross-platform through React Native Web.

## When not to use this package

- Do not use it for pure web-first Radix or Next.js surfaces.
- Do not use it for token or theming orchestration.
- Do not use it for framework-agnostic link behavior.

## Related packages

- `@lssm-tech/lib.ui-kit-core`: tiny shared utility layer used by the UI packages.
- `@lssm-tech/lib.ui-kit-web`: web-first component package for React and Next surfaces.
- `@lssm-tech/lib.design-system`: higher-level design-system and composition layer built on top of the UI packages.

## Local commands

- `bun run lint:check`
- `bun run typecheck`

## Graph & Timeline Primitives

`@lssm-tech/lib.ui-kit` ships native graph and timeline primitives backed by `react-native-svg` for Expo and React Native surfaces.

**`@lssm-tech/lib.ui-kit/ui/graph`**:
- `GraphCanvas` — native SVG graph renderer; same `GraphCanvasProps` interface as the web lane

**`@lssm-tech/lib.ui-kit/ui/timeline`**:
- `Timeline` — native SVG timeline renderer
- `TimelineGraph` — native combined timeline + graph view

All three respect `prefers-reduced-motion` via the `reducedMotion` prop (parity with web lane).

Metro aliases (`withPresentationMetroAliases`) automatically map `@lssm-tech/lib.ui-kit-web/ui/*` subpaths to `@lssm-tech/lib.ui-kit/ui/*` for native surfaces. Product code can import from `@lssm-tech/lib.design-system` and let the alias system route to the correct primitive.

See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for layer placement and full import rules.


---

## @lssm-tech/lib.ui-link

Description: Deep linking utilities for navigation
Path: packages/libs/ui-link
URL: /llms/lib.ui-link

# @lssm-tech/lib.ui-link

`@lssm-tech/lib.ui-link` provides a tiny link component for shared UI surfaces that should not be coupled to framework-specific routers.

Website: https://contractspec.io

## Installation

`bun add @lssm-tech/lib.ui-link`

or

`npm install @lssm-tech/lib.ui-link`

## What belongs here

This package is intentionally narrow:

- Generic anchor-style link behavior.
- Minimal styling composition via `@lssm-tech/lib.ui-kit-core`.

Use this package when you want shared link behavior without Expo-router or Next-specific coupling.

## API map

- root default export
- `./ui/link`
- `Link` component with anchor-style props and required `href`

## Operational semantics and gotchas

- The component renders a plain anchor.
- It depends on `@lssm-tech/lib.ui-kit-core` for `cn()`.
- Unlike `ui-kit` and `ui-kit-web`, this package should stay router-agnostic.
- The root export is just the default export from `./ui/link`.

## When not to use this package

- Do not use it for Expo-router navigation.
- Do not use it for Next.js `Link` behavior.
- Do not use it for complex navigation abstractions.

## Related packages

- `@lssm-tech/lib.ui-kit-core`
- `@lssm-tech/lib.ui-kit`
- `@lssm-tech/lib.ui-kit-web`

## Local commands

- `bun run lint:check`
- `bun run typecheck`


---

## @lssm-tech/lib.utils-typescript

Description: TypeScript utility types and helpers
Path: packages/libs/utils-typescript
URL: /llms/lib.utils-typescript

# @lssm-tech/lib.utils-typescript

Website: https://contractspec.io

**TypeScript utility types and helpers.**

## What It Provides

- **Layer**: lib.
- **Consumers**: many libs and bundles (wide blast radius).
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.utils-typescript`

or

`bun add @lssm-tech/lib.utils-typescript`

## Usage

Import the root entrypoint from `@lssm-tech/lib.utils-typescript`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/lib/` contains package-local helper utilities and adapters.
- `src/staticShouldNotHappen.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./lib/AwaitedResult` resolves through `./src/lib/AwaitedResult.ts`.
- Export `./lib/BrowserNativeObject` resolves through `./src/lib/BrowserNativeObject.ts`.
- Export `./lib/DeepInfiniteArray` resolves through `./src/lib/DeepInfiniteArray.ts`.
- Export `./lib/DeepKeepOnly` resolves through `./src/lib/DeepKeepOnly.ts`.
- Export `./lib/DeepKey` resolves through `./src/lib/DeepKey.ts`.
- Export `./lib/DeepMap` resolves through `./src/lib/DeepMap.ts`.
- Export `./lib/DeepNullable` resolves through `./src/lib/DeepNullable.ts`.
- Export `./lib/DeepOr` resolves through `./src/lib/DeepOr.ts`.
- Export `./lib/DeepPartial` resolves through `./src/lib/DeepPartial.ts`.
- The package publishes 31 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Utility types are used across the entire monorepo — changes can break many packages.
- Must stay zero-dependency (no runtime deps).
- Test any signature change against downstream consumers before merging.


---

## @lssm-tech/lib.video-gen

Description: (none)
Path: packages/libs/video-gen
URL: /llms/lib.video-gen

# @lssm-tech/lib.video-gen

**AI-powered video generation with Remotion: compositions, rendering, and design integration.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles, video-studio app.
- `src/docs/` contains docblocks and documentation-facing exports.
- Related ContractSpec packages include `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.content-gen`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.image-gen`, ...
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/lib.video-gen`

or

`bun add @lssm-tech/lib.video-gen`

## Usage

Import the root entrypoint from `@lssm-tech/lib.video-gen`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/compositions` is part of the package's public or composition surface.
- `src/design` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/generators` is part of the package's public or composition surface.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/player` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./compositions` resolves through `./src/compositions/index.ts`.
- Export `./compositions/api-overview` resolves through `./src/compositions/api-overview.tsx`.
- Export `./compositions/primitives` resolves through `./src/compositions/primitives/index.ts`.
- Export `./compositions/primitives/animated-text` resolves through `./src/compositions/primitives/animated-text.tsx`.
- Export `./compositions/primitives/brand-frame` resolves through `./src/compositions/primitives/brand-frame.tsx`.
- Export `./compositions/primitives/code-block` resolves through `./src/compositions/primitives/code-block.tsx`.
- Export `./compositions/primitives/progress-bar` resolves through `./src/compositions/primitives/progress-bar.tsx`.
- Export `./compositions/primitives/terminal` resolves through `./src/compositions/primitives/terminal.tsx`.
- Export `./compositions/primitives/transition` resolves through `./src/compositions/primitives/transition.tsx`.
- The package publishes 42 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add AI provider ranking system with ranking-driven model selection.
- Resolve lint/test regressions after voice capability updates.
- Add @lssm-tech/lib.voice package for TTS, STT, and conversational voice.

## Notes

- Remotion composition API is version-sensitive — pin and test upgrades carefully.
- Renderer interface is the adapter boundary — do not leak Remotion internals.
- Depends on voice, content-gen, image-gen, design-system — coordinate cross-lib changes.


---

## @lssm-tech/lib.voice

Description: Voice capabilities: TTS, STT, and conversational AI
Path: packages/libs/voice
URL: /llms/lib.voice

# @lssm-tech/lib.voice

Website: https://contractspec.io

**Voice capabilities: TTS, STT, and conversational AI.**

## What It Provides

- **Layer**: lib.
- **Consumers**: video-gen, bundles.
- `src/docs/` contains docblocks and documentation-facing exports.
- Related ContractSpec packages include `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.content-gen`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/lib.voice`

or

`bun add @lssm-tech/lib.voice`

## Usage

Import the root entrypoint from `@lssm-tech/lib.voice`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/audio` is part of the package's public or composition surface.
- `src/conversational` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/stt` is part of the package's public or composition surface.
- `src/sync` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./audio` resolves through `./src/audio/index.ts`.
- Export `./audio/audio-concatenator` resolves through `./src/audio/audio-concatenator.ts`.
- Export `./audio/duration-estimator` resolves through `./src/audio/duration-estimator.ts`.
- Export `./audio/format-converter` resolves through `./src/audio/format-converter.ts`.
- Export `./audio/silence-generator` resolves through `./src/audio/silence-generator.ts`.
- Export `./conversational` resolves through `./src/conversational/index.ts`.
- Export `./conversational/response-orchestrator` resolves through `./src/conversational/response-orchestrator.ts`.
- Export `./conversational/transcript-builder` resolves through `./src/conversational/transcript-builder.ts`.
- Export `./conversational/turn-detector` resolves through `./src/conversational/turn-detector.ts`.
- The package publishes 43 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and test failures across voice, workspace, library, and composio.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add AI provider ranking system with ranking-driven model selection.
- Add @lssm-tech/lib.voice package for TTS, STT, and conversational voice.

## Notes

- TTS/STT interfaces are adapter boundaries — keep them provider-agnostic.
- Audio processing must stay streaming-compatible (no full-buffer-only APIs).
- Depends on contracts-spec, contracts-integrations, content-gen.


---

## @lssm-tech/lib.workflow-composer

Description: Tenant-aware workflow composition helpers for ContractSpec.
Path: packages/libs/workflow-composer
URL: /llms/lib.workflow-composer

# @lssm-tech/lib.workflow-composer

Website: https://contractspec.io

**Tenant-aware workflow composition helpers for ContractSpec.**

## What It Provides

- **Layer**: lib.
- **Consumers**: bundles.
- Related ContractSpec packages include `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/lib.workflow-composer`

or

`bun add @lssm-tech/lib.workflow-composer`

## Usage

Import the root entrypoint from `@lssm-tech/lib.workflow-composer`, or choose a documented subpath when you only need one part of the package surface.

Workflow composition is deterministic by default:

- Extensions are applied in stable priority order.
- Duplicate injected step ids and invalid anchor combinations are rejected.
- Hidden-step overlays are validated so they cannot orphan the remaining graph.
- Extension `metadata` and `annotations` are merged into the composed workflow output.

## Architecture

- `src/composer.test.ts` is part of the package's public or composition surface.
- `src/composer.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/injector.ts` is part of the package's public or composition surface.
- `src/merger.ts` is part of the package's public or composition surface.
- `src/templates.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add AI provider ranking system with ranking-driven model selection.
- Upgrade dependencies.

## Notes

- Workflow composition must stay tenant-isolated — no cross-tenant data leakage.
- Depends on contracts-spec — keep aligned with contract definitions.


---

## @lssm-tech/module.agent-fleet

Description: Agent fleet management module — fleet, tree, detail, tool registry, and run console surfaces.
Path: packages/modules/agent-fleet
URL: /llms/module.agent-fleet

(No README.md)

---

## @lssm-tech/module.ai-chat

Description: AI chat interface module
Path: packages/modules/ai-chat
URL: /llms/module.ai-chat

# @lssm-tech/module.ai-chat

Website: https://contractspec.io

**AI chat module with context, core runtime, presentation components, hooks, providers, and agent-aware workflows.**

## What It Provides

- Provides the packaged chat feature layer used by examples and higher-level applications.
- Supports MCP tools, provider integration, presentation rendering, forms, and agent-mode workflows.
- Acts as the main composition layer between the low-level agent runtime and user-facing chat UIs.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/presentation/` contains presentation-layer components and renderers.

## Installation

`npm install @lssm-tech/module.ai-chat`

or

`bun add @lssm-tech/module.ai-chat`

## Usage

Import the root entrypoint from `@lssm-tech/module.ai-chat`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/context/` contains shared chat providers and contextual runtime state.
- `src/core/` contains chat orchestration, workflows, and non-UI runtime logic.
- `src/presentation/` exports UI components and React hooks for embedding the chat experience.
- `src/providers/` exposes provider bindings and provider-facing integration helpers.
- Top-level feature, capability, operation, schema, and event files define the module contract surface.
- `src/core/economic-evidence.ts` maps chat adapter usage into neutral agent-run economic evidence refs.
- `src/ai-chat.capability.ts` defines a capability surface.

## Public Entry Points

- Exports the root module plus context, core, core/workflow, presentation, presentation/components, presentation/hooks, and providers subpaths.
- Export `.` resolves through `./src/index.ts`.
- Export `./context` resolves through `./src/context/index.ts`.
- Export `./core` resolves through `./src/core/index.ts`.
- Export `./core/workflow` resolves through `./src/core/workflow.ts`.
- Export `./presentation` resolves through `./src/presentation/index.ts`.
- Export `./presentation/components` resolves through `./src/presentation/components/index.ts`.
- Export `./presentation/hooks` resolves through `./src/presentation/hooks/index.ts`.
- Export `./providers` resolves through `./src/providers/index.ts`.

## Economic Evidence

AI chat now emits safe economic evidence automatically when token usage exists. `ChatService` stores `createAiChatEconomicEvidenceMetadata()` output on assistant message metadata, `createChatRoute()` emits AI SDK `messageMetadata` on finish, and `createCompletionRoute()` calls `onEconomicEvidence` on finish. Missing usage returns `undefined` so callers do not fabricate spend. Route consumers should persist `economicEvidenceRefs`/usage metadata and keep prompts, messages, tool args, and provider receipts in their owning secure stores.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Agentic workflows — subagents, memory tools, and next steps.
- Vnext ai-native.
- Backend operations + frontend rendering support.
- Use browser-safe MCP client stub in client bundles.
- Add changesets and apply pending fixes.
- Add chat usage-to-economic-evidence mapping for AI-native billing, observability, and replay lanes.

## Notes

- Depends on `lib.ai-agent`, `lib.ai-providers`, `lib.contracts-spec`, `lib.schema`, `lib.metering`, `lib.cost-tracking`, `lib.surface-runtime`.
- React peer dependency (>=19.2.4); changes here affect all chat surfaces.
- Metering and cost-tracking are wired in -- never bypass them.


---

## @lssm-tech/module.alpic

Description: Alpic MCP and ChatGPT App hosting helpers
Path: packages/modules/alpic
URL: /llms/module.alpic

# @lssm-tech/module.alpic

Website: https://contractspec.io

**Alpic MCP and ChatGPT App hosting helpers.**

## What It Provides

- **Layer**: module.
- **Consumers**: apps (alpic-mcp, chatgpt-app).
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.

## Installation

`npm install @lssm-tech/module.alpic`

or

`bun add @lssm-tech/module.alpic`

## Usage

Import the root entrypoint from `@lssm-tech/module.alpic`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/assets` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Standardize tool naming to underscore notation.
- Add changesets and apply pending fixes.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Test runner.

## Notes

- Depends on `@modelcontextprotocol/sdk` and `elysia` -- version bumps may break MCP protocol compatibility.
- Exposes external-facing endpoints; treat all inputs as untrusted.
- Changes affect MCP tool registration and ChatGPT plugin manifests.


---

## @lssm-tech/module.app-submission-readiness

Description: ReviewReady module: runtime-driven app-submission readiness report, rejection assistant, and admin rule surfaces built from real audit output.
Path: packages/modules/app-submission-readiness
URL: /llms/module.app-submission-readiness

# @lssm-tech/module.app-submission-readiness

ReviewReady product module for mobile **app-submission readiness**. It renders
readiness reports, a resubmission assistant, and an admin rule surface for the
Apple App Store and Google Play submission flow.

## Runtime-driven, not hardcoded

Every view-model is derived from the **real audit output** of
`@lssm-tech/lib.app-submission-readiness-runtime` (`runReadinessAudit(...)`,
`draftRejectionResponse(...)`, `buildStoreChecklists(...)`) and the contract
provider-capability registry. There are no static demo numbers in this module.

This is intentionally distinct from `@lssm-tech/module.review-queue`'s
CompanyOS approval-lane surface, which models a different concept and must not be
reused for submission readiness.

## Design-system first

Presentation is built entirely from `@lssm-tech/lib.design-system` primitives
(`Box`/`HStack`/`VStack`, `H1`/`H2`/`H3`/`P`/`Text`, `Button`/`ButtonLink`,
`EmptyState`, `StatusChip`). No raw HTML, no native-only imports. Components
implement loading / empty / error states and accessible roles/labels.

## Public API

### Core view-model builders (`./core`)

- `buildReadinessReportViewModel(report, checklists?)` → `ReadinessReportViewModel`
- `buildRejectionAssistantViewModel(draft)` → `RejectionAssistantViewModel`
- `buildAdminRulesViewModel(rules, { now, staleAfterDays? })` → `AdminRulesViewModel`

### Presentation (`./presentation`)

- `ReadinessReportView`
- `RejectionAssistantView`
- `AdminRuleManager`
- `AppSubmissionReadinessScreen` (presentational composition of the flow)
- supporting: `DecisionBadge`, `FindingsSection`, `StoreChecklistSection`

### Fixtures (`./fixtures`)

Deterministic sample built from a real audit, reused by tests and the web
product proof: `fixtureSubmissionInput`, `fixtureAuditResult`,
`fixtureReportViewModel`, `fixtureRejectionViewModel`,
`fixtureAdminRulesViewModel`.

## Scope

Interactivity wiring (connect / manual entry / run audit) is owned by the host
web app. This module ships the reusable runtime-driven view-models and DS-based
presentation only.


---

## @lssm-tech/module.audit-trail

Description: Audit trail module for tracking and querying system events
Path: packages/modules/audit-trail
URL: /llms/module.audit-trail

# @lssm-tech/module.audit-trail

Website: https://contractspec.io

**Audit trail module for tracking and querying system events.**

## What It Provides

- **Layer**: module.
- **Consumers**: bundles (library, contractspec-studio), apps (web-landing).
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- Related ContractSpec packages include `@lssm-tech/lib.bus`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.

## Installation

`npm install @lssm-tech/module.audit-trail`

or

`bun add @lssm-tech/module.audit-trail`

## Usage

Import the root entrypoint from `@lssm-tech/module.audit-trail`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/audit-trail.capability.ts` defines a capability surface.
- `src/audit-trail.feature.ts` defines a feature entrypoint.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/entities/` contains domain entities and value objects.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/storage/` contains persistence adapters and storage implementations.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./audit-trail.capability` resolves through `./src/audit-trail.capability.ts`.
- Export `./audit-trail.feature` resolves through `./src/audit-trail.feature.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./storage` resolves through `./src/storage/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Depends on `lib.bus` for event dispatch -- never emit events outside the bus.
- Audit records are append-only; mutations or deletions break compliance invariants.
- Storage adapters must implement the store interface; do not bypass it.


---

## @lssm-tech/module.auth-os

Description: Reusable AuthOS module with fake adapters and UI flows for identity, authentication, organizations, and Connect with LSSM.
Path: packages/modules/auth-os
URL: /llms/module.auth-os

# `@lssm-tech/module.auth-os`

Reusable AuthOS UI module: a complete atomic-design component library for authentication and
identity flows, composable into any host app or bundle. The module ships atoms → molecules →
organisms → templates → screens in a single package, backed by the AuthOS contract surface
(`@lssm-tech/lib.authos-spec`) and the AuthObservability port. Production auth execution stays
host-owned; the module provides only the UI and composition layer.

---

## Atomic Taxonomy (after Waves 1–4)

| Layer | Count | Location |
| --- | --- | --- |
| Atoms | 16 | `src/ui/atoms/` |
| Molecules | 19 | `src/ui/molecules/` |
| Organisms | 16 | `src/ui/organisms/` |
| Templates | 5 (+1 deprecated alias) | `src/ui/templates/` |
| Screens | 12 | `src/ui/screens/` |
| Hooks | _in progress_ (Wave 5) | `src/ui/hooks/` |

All public exports flow through `src/ui/index.ts`.

---

## Adapter Contract Surface (`AuthOsAdapter`)

> _Defined in `src/ui/hooks/types.ts` — landing with Wave 5._

The `AuthOsAdapter` interface is the boundary between UI hooks and host-supplied auth backends.
Hooks accept an adapter instance and delegate all side-effectful auth operations to it. This
keeps the module free of any bespoke auth engine.

---

## i18n Surface

### Target locale set: `en / fr / es`

The readiness target for auth-os is **en/fr/es** (Option A, decided 2026-06-09).
`SUPPORTED_LOCALES = ['en', 'fr', 'es']` in `@lssm-tech/lib.contracts-spec/translations`.

### Atomic catalog structure

Catalogs are **split by UI area** so parallel workers can fill their own file without
conflicts. All area catalogs share the `auth-os.messages` spec key.

| Area | Files | Key namespace |
|------|-------|---------------|
| `atoms` | `catalogs/atoms.{en,fr,es}.ts` | `authOs.atoms.*` |
| `molecules` | `catalogs/molecules.{en,fr,es}.ts` | `authOs.molecules.*` |
| `organisms` | `catalogs/organisms.{en,fr,es}.ts` | `authOs.organisms.*` |
| `shell` | `catalogs/shell.{en,fr,es}.ts` | `authOs.shell.*` |
| `legacy` | `catalogs/legacy.{en,fr,es}.ts` | `auth.*` (back-compat) |

Merged catalogs (`enMessages` / `frMessages` / `esMessages`) collapse all areas
into one spec per locale for the runtime registry. The parity gate
(`__tests__/catalog-parity.test.ts`) enforces identical key sets and placeholder
signatures across en/fr/es for every area — 15 tests, zero failures.

### Factory (canonical)

```ts
import { createAuthOsI18n } from '@lssm-tech/module.auth-os/i18n';

const i18n = createAuthOsI18n('fr');
i18n.t('authOs.atoms.authCodeInput.defaultLabel'); // → 'Code d\'authentification'
```

### Legacy resolver (deprecated back-compat shim)

`resolveAuthMessage('auth.<surface>.<key>', params?)` — falls back to the key
verbatim when missing; fires `AUTH_I18N_MISSING_KEY` via the observability port.
New code should use `createAuthOsI18n`.

### German (`de`) — preserved ungated superset

`src/i18n/de.ts` is a 297-line **legacy monolith** retained from before the
atomic area structure. It is:

- **NOT** gated by `catalog-parity.test.ts` (which only gates en/fr/es).
- **NOT** using `defineTranslation` or the atomic area shape.
- **Retained** because `de.test.ts` gives regression coverage and the translation
  investment is preserved.
- **Not to be migrated** into `atoms.de` / `molecules.de` etc. unless German
  becomes a deliberate market commitment.

Usage (legacy resolver only):
```ts
import { de } from '@lssm-tech/module.auth-os/i18n';
import { resolveAuthMessage } from '@lssm-tech/module.auth-os/i18n';
const label = resolveAuthMessage('auth.signIn.submit', {}, { catalog: de });
// → 'Anmelden'
```

### Subpaths

`./i18n` · `./i18n/en` · `./i18n/resolveAuthMessage`

---

## Observability

Port interface and event taxonomy live in `src/observability/`.

| File | Purpose |
| --- | --- |
| `AuthEvent.ts` | `as const` UPPER_SNAKE_CASE enum — 28+ canonical events |
| `AuthObservability.ts` | Port interface (`emit` + `flush`), `NoopAuthObservability`, `ConsoleAuthObservability` |

**Key events** (partial list):

```
AUTH_SIGN_IN_VIEWED / SUBMITTED / SUCCEEDED / FAILED
AUTH_SIGN_UP_VIEWED / SUBMITTED / SUCCEEDED / FAILED
AUTH_MFA_PROMPTED / FACTOR_SELECTED / VERIFIED / FAILED
AUTH_PASSKEY_REGISTERED / FAILED
AUTH_SESSION_LISTED / REVOKED
AUTH_INVITATION_VIEWED / ACCEPTED / DECLINED
AUTH_AUDIT_VIEWED
AUTH_CONSENT_GRANTED / REVOKED
```

Props schema (`AuthEventProps`): enum + numeric + hashed-id only — **no PII, no raw tokens, no
i18n strings**. The module never imports a concrete analytics SDK (AC-19).

---

## .web / .native Discipline

Platform variants are colocated with their shared base:

```
atoms/AuthCodeInput/
├── AuthCodeInput.tsx          # shared base
├── AuthCodeInput.web.tsx      # browser-specific
└── index.ts
```

- `.web.tsx` — browser / Next.js surfaces.
- `.native.tsx` — React Native / Expo surfaces.
- The alias helpers (`withPresentationTurbopackAliases` / `withPresentationMetroAliases`) in
  `@lssm-tech/lib.presentation-runtime-core` route platform variants at build time.

---

## Bundle Integration

`AuthLandingTemplate`, `PasskeysTemplate`, and `AccountLockedTemplate` from
`@lssm-tech/bundle.managed-companyos/ui/templates` are locked by the adapter-contract test at
`src/__tests__/bundle-adapter-contract.test.tsx` via `satisfies ComponentProps<typeof T>`.

These three templates will be consolidated into the module's own template layer in a follow-up
wave; the contract test ensures prop-signature drift is caught at compile time until then.

---

## Status

| Wave | Scope | Status |
| --- | --- | --- |
| 0 | Foundation types + contract test | ✅ Landed |
| 1 | 9 atoms | ✅ Landed |
| 2 | 10 molecules | ✅ Landed |
| 3 | 10 organisms | ✅ Landed |
| 4 | 5 templates + `.web`/`.native` pairs | ✅ Landed |
| 5 | 15 hooks + `AuthOsAdapter` interface | 🔄 In progress |
| 6–7 | Screens refactor + pages + dual-app wiring | ⏳ Deferred |
| 8 | Docs + changeset (this wave) | ✅ Landed |


---

## @lssm-tech/module.billing-os

Description: CompanyOS composition module for governed BillingOS action plans, authority checks, autonomy classification, and operator inbox routing.
Path: packages/modules/billing-os
URL: /llms/module.billing-os

# `@lssm-tech/module.billing-os`

CompanyOS composition for BillingOS action plans. The module maps BillingOS action classifications into CompanyOS authority, autonomy, and operator inbox review artifacts without provider SDKs, credentials, network calls, France hard dependency, or authorized billing execution. It includes no production PA submission and no provider credentials.

The default surface is country-neutral. France readiness remains in `@lssm-tech/lib.billing-france` and can be composed by examples or optional adapters later.

## Reusable UI

The `./ui` export provides reusable, mobile-first BillingOS presentation surfaces for product shells and examples:

- quote creation and edition workspace with deterministic VAT totals and wrapping mobile-safe line-item controls
- invoice inbox and payment reconciliation workspaces with mobile-safe rows/actions
- compliance readiness and CompanyOS review workspaces with approval controls that wrap at narrow widths
- shared billing status badges, summary cards, cards, editor types, and currency helpers

Host packages should pass deterministic data into these components and keep provider execution, credentials, native/Expo rendering, and country-specific legal decisions outside the module. Expo/native hosts should render RN-safe adapters from deterministic view-model or proof data instead of importing `@lssm-tech/module.billing-os/ui`.

## Safety

The module includes no production PA submission, no provider credentials, and no authorized billing execution. It only creates review metadata and operator approval routing.

## Mobile and native proof boundary

The reusable UI is a web/React presentation surface that must remain usable on phone-width layouts, but it is not a React Native component library. The mobile monolith BillingOS proof renders the France SME summary/review path with RN primitives and deterministic proof constants, while keeping the same no-provider, no-network, no-production-submission safety boundary.

## Internationalization

All user-facing strings rendered by `./ui` are translated through the `./i18n` export, which ships `en`, `fr`, and `es` catalogs under the `billingOs.*` key namespace (spec key `billing-os.messages`).

- React components consume translations via `useI18n` from `@lssm-tech/lib.design-system/i18n`; the module never mounts a `LocaleProvider`. The host app/bundle owns the provider and supplies a runtime that binds these catalogs (e.g. wrapping `createBillingOsI18n(locale)`).
- Without a provider, `t(key)` returns the key as-is (fail-open, never throws). Catalog completeness is enforced statically by the parity test and the repo `i18n:check` gate.
- Non-React callers can build an instance directly with `createBillingOsI18n(locale)` from `@lssm-tech/module.billing-os/i18n`.
- French and Spanish translations are LLM-generated and pending human review; the `en` catalog is the reference locale.

### Locale-correct money formatting (readiness)

Readiness target locale set is **en/fr/es** (no `de`). Money/number formatting is locale-correct at every call site:

- `formatCurrency(amount, currency, locale)` (`./ui` → `src/ui/lib/format.ts`) takes a **required** `locale` (no `en-US` fallback), so French/Spanish amounts render with locale-correct grouping and symbol placement (e.g. `1 234,56 €`, not `€1,234.56`).
- The `PaymentCard` organism takes a **required** `locale` prop and threads it through `useI18n(locale)` for per-component locale-aware formatting.
- Resolve the active locale from `useI18n()` (or the host i18n context) and pass it at each call site.
- France-specific VAT/compliance lives in `@lssm-tech/lib.billing-france` and is **jurisdiction** logic, not locale formatting — it is preserved independently of the locale.


---

## @lssm-tech/module.builder-workbench

Description: Reusable Builder workbench UI module.
Path: packages/modules/builder-workbench
URL: /llms/module.builder-workbench

# @lssm-tech/module.builder-workbench

Reusable React surfaces for the Builder control plane: workspace home, guided chat/voice, source inbox, omnichannel inbox, blueprint editing, and readiness review.

## Model route inspection

The workbench exports route visibility components for Builder governance: `ModelRouteBadge`, `ModelRouteInspector`, `ModelRouteOverridePanel`, `RiskFlagList`, and `RoutingEvidenceTimeline`. These surfaces expose selected policy, difficulty, provider/model, risk flags, fallback routes, and rejected unsafe downgrades.

## RoleMorph Workbench panels

The workbench exports `RoleMorphWorkbenchPanels` for rendering RoleMorph packet views with existing design-system/ui-kit primitives. The panel set covers role selection, surface preview/registry summaries, inspector diagnostics, policy diff summaries, safe missing-binding repairs, authorization/evidence summaries, and audit/replay timestamps. It renders serializable packet contracts only; provider execution, durable stores, and production authorization enforcement remain outside the module.


---

## @lssm-tech/module.communication-os

Description: Spec-first communication backbone for turning conversations into structured, governed, agent-callable work
Path: packages/modules/communication-os
URL: /llms/module.communication-os

# @lssm-tech/module.communication-os

Website: https://contractspec.io

**CommunicationOS composes canonical communication contracts and backend-neutral runtime behavior into a module capability surface.**

## Package Boundary

CommunicationOS is now a thin module layer:

- Canonical contracts live in `@lssm-tech/lib.communication-spec`.
- Backend-neutral lifecycle, governance, state, ingestion, records, and replay helpers live in `@lssm-tech/lib.communication-runtime`.
- Examples, fixtures, and proof/replay data live in `@lssm-tech/example.communication-os`.
- Reusable low-level presentational communication blocks live behind `@lssm-tech/lib.design-system/components/communication-os`.
- Reusable CommunicationOS workflow UI and screen composition live in this module under `@lssm-tech/module.communication-os/ui`.
- Command-inbox helpers for message-originated commands are exposed through `@lssm-tech/module.communication-os/core/command-inbox` and delegate to the backend-neutral runtime.

CommunicationOS says: "Here is what changed, what matters, who owns it, what is blocked, what can be replied to, and what can safely happen next."

## What It Is

- A spec-first communication backbone.
- A normalized communication event model.
- A governed reply drafting and handoff contract surface.
- An agent-callable communication layer.
- A deterministic generic runtime for testable conversation-to-work flows.
- A reusable foundation for future vertical consumers and downstream applications.

## What It Is Not

- Not an end-user messaging product.
- Not a team chat replacement.
- Not a single-domain record inbox.
- Not a customer-support-only tool.
- Not a voicebot-only product.
- Not a free-form assistant widget.
- Not a channel bridge maintenance project.

The generic operational inbox is a consumer of CommunicationOS, not the core itself.

## Alignment With Existing ContractSpec Surfaces

- `@lssm-tech/module.ai-chat` owns conversational UI and model/provider workflows. CommunicationOS owns operational threads, normalized events, reply governance, and thread-to-action contracts.
- `@lssm-tech/module.notifications` owns notification delivery. CommunicationOS can emit events that a consumer routes into notifications, but it does not replace the notification module.
- `@lssm-tech/module.audit-trail` owns audit aggregation. CommunicationOS emits audit-ready event payloads, policy refs, and replay evidence rather than creating a second audit console.
- `@lssm-tech/module.lifecycle-core` owns reusable lifecycle primitives. CommunicationOS documents domain-specific transitions for messages, threads, suggestions, replies, and handoffs.
- `@lssm-tech/module.context-storage` owns durable context snapshots. CommunicationOS threads, summaries, and source message references can become agent-readable context sources.
- `@lssm-tech/module.product-intent-core` owns product intent routing. CommunicationOS message intents can become product intent signals for downstream applications.

## Core Concepts

- `CommunicationThread`: conversation container across channels.
- `CommunicationMessage`: normalized message with channel and participant context.
- `CommunicationParticipant`: person or system participating in conversations.
- `ChannelAccount`: participant identity on a specific channel.
- `ChannelPolicy` and `ConsentRecord`: channel-specific governance and permission state.
- `IdentityLink`: proposed or reviewed relation between participant identities.
- `ThreadLink`: generic bridge from a thread to a future vertical object.
- `MessageIntent`: classified intent with confidence and evidence.
- `ReplyDraft`: draft response with policy metadata and review state.
- `HandoffPacket`: structured transfer with summary, actions, questions, and evidence.
- `CommunicationAction`: extracted work candidate with source messages.
- `CommunicationSummary`: summary with source references, facts, actions, decisions, and risks.
- `AgentSuggestion`: non-canonical AI suggestion.
- `CommunicationAuditEvent`: audit-ready record of a communication action or policy decision.
- `CommunicationCommandInboxItem`: non-executing evidence packet for message-originated commands, including AIP controls and optional CompanyOS bridge status.

### Voice-originated proposals

Voice-originated work follows the same communication-to-governance split as message-originated work. CommunicationOS can normalize a voice transcript, preserve source evidence, classify intent, summarize redaction classes, and propose actions. It does not authorize the action. For the canonical Voice-to-Product-Gap proof, the internal product-gap proposal is handed to CompanyOS for policy and PM approval, while the customer-facing promise remains blocked by default.

## Product Invariants

- AI suggestions are not canonical truth.
- Identity links are proposed before trusted merge.
- Sensitive replies require policy checks.
- Channel constraints must be respected.
- Every sent reply must be auditable.
- Every generated handoff must link back to evidence.
- Future vertical links must not leak domain assumptions into the core.
- Command-inbox items are evidence, not execution authority; `canExecute` remains `false` and blocked signals fail closed.

## Agent Behavior

Agents may:

- read thread context;
- summarize with source references;
- classify message intent;
- propose thread links, identity links, and actions;
- draft replies;
- prepare handoff packets;
- request escalation;
- record human feedback.

Agents may not without explicit policy approval:

- send sensitive replies;
- merge identities;
- make commitments;
- mutate future vertical objects;
- bypass consent;
- ignore retention or channel policy;
- invent missing facts;
- treat a command-inbox item as permission to send, run shell commands, fetch credentials, or execute CompanyOS high-impact work.

## Examples And Fixtures

- `src/fixtures/` includes normalized event examples and evaluation fixtures for intent classification, identity rejection, policy blocking, reply review, handoff evidence, summary sources, and action extraction.
- `src/examples/operational-inbox.example.ts` shows a generic operational inbox consumer that groups threads and exposes review actions without becoming the core.
- `src/examples/domain-pack.example.ts` shows how a future domain pack links a thread to a neutral business object while keeping the core unchanged.
- `src/examples/channel-capability-matrix.ts` models email, SMS, voice transcript, and custom adapter capabilities without implementing full connectors.
- `src/proof/communication-os.replay.ts` replays the fixture surface into a compact proof object.

## Future Consumer Model

Future vertical consumers extend CommunicationOS through `ThreadLink`, domain-specific intent labels, reply policies, escalation rules, handoff templates, action extraction rules, and evaluation fixtures. CommunicationOS core owns communication primitives. Domain packs own vertical meaning. Deployment-specific apps and downstream applications own UI and workflow composition.

## Roadmap

- **Phase 0: inventory and alignment** — align with ai-chat, audit, notifications, lifecycle, context storage, product intent, docs, package exports, and examples conventions.
- **Phase 1: contracts and normalized events** — public contract map, normalized event examples, invariants, and fixtures.
- **Phase 2: AI triage and governed assistance** — classify, summarize, extract actions/decisions/risks, draft replies, create handoffs, propose links, escalate, block by policy, and record feedback.
- **Phase 3: generic operational inbox consumer** — minimal consumer example for grouping, review, handoff, escalation, and archive flows.
- **Phase 4: domain packs** — generic extension guide and neutral domain pack example.
- **Phase 5: advanced connectors and voice strategy** — capability matrix, voice transcript strategy, and deployment-specific workflow features as future layers.

## Architecture

- `src/communication-os.capability.ts` defines the module capability surface.
- `src/communication-os.feature.ts` defines the feature entrypoint with operations and events.
- `@lssm-tech/lib.communication-spec` owns canonical enums, models, operations, queries, events, capabilities, and validation helpers.
- `@lssm-tech/lib.communication-runtime` owns backend-neutral governance, lifecycle, state, ingestion, records, replay/scenario helpers, and deterministic runtime behavior.
- `src/core/` and `src/core/contracts/` are compatibility shims for existing module import paths; new code should import from the split lib packages.
- `src/docs/` contains module-specific public docblocks.
- `src/ui/` contains reusable workflow UI that accepts caller-provided CommunicationOS data and does not import example fixtures.
- `@lssm-tech/example.communication-os` owns examples, fixtures, and replay/proof evidence as a standalone adopter package and composes the module UI with local fixture adapters.

## Public Entry Points And Compatibility Classification

| Entry point | Classification | Canonical home / guidance |
| --- | --- | --- |
| `@lssm-tech/module.communication-os` | keep in module | Thin module composition entrypoint. |
| `@lssm-tech/module.communication-os/communication-os.capability` | keep in module | Module capability surface. |
| `@lssm-tech/module.communication-os/communication-os.feature` | keep in module | Module feature surface. |
| `@lssm-tech/module.communication-os/docs` | keep in module | Module documentation surface. |
| `@lssm-tech/module.communication-os/docs/communication-os.docblock` | keep in module | Module docblock surface. |
| `@lssm-tech/module.communication-os/ui` | keep in module | Reusable CommunicationOS workflow UI; callers provide data from runtime, fixtures, or apps. |
| `@lssm-tech/module.communication-os/ui/CommunicationOsPreview` | keep in module | Reusable preview shell for CommunicationOS workflows. |
| `@lssm-tech/module.communication-os/ui/communication-os-preview.data` | keep in module | Navigation and preview metadata for reusable UI. |
| `@lssm-tech/module.communication-os/ui/communication-os.types` | keep in module | UI data contracts for composition adapters. |
| `@lssm-tech/module.communication-os/core/command-inbox` | command-inbox runtime entry | Re-exports `@lssm-tech/lib.communication-runtime` command-inbox helpers for message-originated commands. |
| `@lssm-tech/module.communication-os/examples`, `./fixtures`, `./proof` | moved out of module | Use the standalone `@lssm-tech/example.communication-os` package; these are no longer module exports. |

Compatibility shims are intentionally additive for the current release. Do not remove module `./core*` exports until a release note classifies the break and downstream imports have a migration window.

## Local Commands

- `bun run build`
- `bun run typecheck`
- `bun run lint:check`
- `bun run test`

## Voice signal summary UI

`@lssm-tech/module.communication-os/ui` now exports `VoiceSignalSummaryCard` and optional `voiceSignal` data on `CommunicationOsPreviewData` / `MessagingWorkspaceData`. This keeps voice-originated evidence reusable at the module boundary without importing example fixtures or runtime providers.

## Quick-start

```bash
# In your consuming app or bundle
bun add @lssm-tech/module.communication-os
```

**Minimal wiring** (Next.js App Router route page):

```tsx
// app/comms/inbox/page.tsx  (server component)
import { InboxPage } from '@lssm-tech/module.communication-os/ui';
import { resolvePresentationData } from '@lssm-tech/lib.communication-runtime';
import { EMPTY_ROLEMORPH } from '@lssm-tech/module.communication-os/ui';

export default async function InboxRoute() {
  const data = await resolvePresentationData(); // your data layer
  return <InboxPage data={data} personalization={{}} rolemorph={EMPTY_ROLEMORPH} />;
}
```

**With persona-aware personalization and capability gating:**

```tsx
// app/comms/inbox/page.tsx  (server component)
import { InboxPage, EMPTY_ROLEMORPH } from '@lssm-tech/module.communication-os/ui';
import { resolveRoleMorph } from '@lssm-tech/lib.surface-runtime/rolemorph';
import {
  personalizationForActorKind,
  toRoleMorphProjection,
} from '../../../lib/companyos-rolemorph-projection';

export default async function InboxRoute() {
  const [data, roleMorphResult] = await Promise.all([
    resolvePresentationData(),
    resolveRoleMorph(),
  ]);
  return (
    <InboxPage
      data={data}
      personalization={personalizationForActorKind(roleMorphResult.actor.kind)}
      rolemorph={toRoleMorphProjection(roleMorphResult)}
    />
  );
}
```

Both `personalization` and `rolemorph` are optional — defaults are `{}` and `EMPTY_ROLEMORPH` (fail-closed).

## Template integration pattern

Bundle templates (`InboxTemplate`, `ThreadsTemplate`, `HandoffsTemplate`, `ThreadDetailTemplate` from `@lssm-tech/bundle.managed-companyos`) accept the same optional props and set providers once at the template boundary:

```tsx
// In a bundle template (already 'use client')
import {
  CommsCapabilityProvider,
  CommsPersonalizationProvider,
  EMPTY_ROLEMORPH,
  type ResolvedPreferenceProfile,
  type RoleMorphProjection,
} from '@lssm-tech/module.communication-os/ui';

export function InboxTemplate({
  viewModel,
  personalization = {},
  rolemorph = EMPTY_ROLEMORPH,
}: InboxTemplateProps) {
  return (
    <CommsCapabilityProvider capabilities={rolemorph.capabilities}>
      <CommsPersonalizationProvider profile={personalization}>
        {/* organisms read density/tone/capability from context — no prop drilling */}
      </CommsPersonalizationProvider>
    </CommsCapabilityProvider>
  );
}
```

**Rules:**
- Set providers **once** at the route or template boundary — never inside organisms or molecules.
- `CommsCapabilityProvider` without a parent fails closed: `useCommsCapability(key)` returns `false` for all keys.
- `personalization` defaults to `{}` — all hooks return their comfortable/default/normal fallback.

## Atomic layer guide

`@lssm-tech/module.communication-os/ui` follows atomic design with a strict 5-layer chain:

```
domain data → *presenter() → viewmodel → *Template → *Page
                                             ↑
                  organisms compose ─────────┘
                  molecules compose organisms
                  atoms compose molecules
```

### Variant token system (cva)

All atoms and top-level molecules use `class-variance-authority` with these canonical tokens:

| Token | Values | Default | Source |
|---|---|---|---|
| `density` | `compact` / `comfortable` / `spacious` | `comfortable` | `useCommsDensity()` |
| `tone` | `neutral` / `info` / `positive` / `warning` / `critical` / `auditor` | `neutral` | content-driven |
| `state` | `idle` / `hover` / `active` / `selected` / `disabled` | `idle` | interaction |
| `emphasis` | `subtle` / `default` / `strong` | `default` | caller |

`pace` (motion: `fast` / `normal` / `slow` / `instant`) is resolved by `useCommsPace()` internally — not a cva variant.

### Capability gating

```tsx
import { CapabilityGate } from '@lssm-tech/module.communication-os/ui';
import { COMMS_HANDOFF_KEYS } from '@lssm-tech/lib.communication-spec/capabilities';

// Omit affordance when capability absent (fail-closed)
<CapabilityGate capability={COMMS_HANDOFF_KEYS.APPROVE}>
  <HandoffApproveButton onClick={handleApprove} />
</CapabilityGate>

// Auditor fallback — surface stays meaningful
<CapabilityGate
  capability={COMMS_AI_CAPABILITY_KEYS.FULL}
  fallback={<EvidencePanel thread={thread} />}
>
  <Composer thread={thread} />
</CapabilityGate>
```

**Never use `isReadOnly` prop** — it is deprecated. Use `CapabilityGate` + `fallback` instead.

### Personalization hooks

```tsx
// Inside CommsPersonalizationProvider tree
import {
  useCommsDensity,
  useCommsGuidance,
  useCommsPace,
} from '@lssm-tech/module.communication-os/ui';

function MyAtom() {
  const density  = useCommsDensity();   // 'compact' | 'comfortable' | 'spacious'
  const guidance = useCommsGuidance();  // 'subtle' | 'default' | 'verbose'
  const pace     = useCommsPace();      // 'fast' | 'normal' | 'slow' | 'instant'
  // pass density as cva variant, use guidance for help-text expansion
}
```

## Storybook workflow

Stories live at `<AtomName>/<AtomName>.stories.tsx` co-located with each atom/molecule.

```bash
# Run Storybook (from monorepo root)
bun run storybook --filter=@lssm-tech/module.communication-os

# Snapshot all cva variant combos
bun run --cwd packages/modules/communication-os test --grep variants
```

Each atom ships stories covering all variant combinations. Storybook is the authoritative visual reference — run it before submitting UI changes to this module. Do not add ad-hoc `console.log` or demo-only logic to stories.


---

## @lssm-tech/module.companyos

Description: CompanyOS execution composition module with typed adapter ports over CompanyOS spec/runtime contracts.
Path: packages/modules/companyos
URL: /llms/module.companyos

# `@lssm-tech/module.companyos`

Thin CompanyOS execution composition over canonical `@lssm-tech/lib.companyos-spec` contracts and pure `@lssm-tech/lib.companyos-runtime` projections.

The module exposes typed adapter ports for agent, job, integration, human, dry-run, and manual-record dispatch lanes. It does not call providers, networks, queues, filesystems, apps, bundles, examples, integrations, or peer modules by default. Production execution must be supplied by caller-owned adapters. Host applications that persist CompanyOS state should consume the `./persistence` schema contribution and bind its `database.mutation.plan` / `database.mutation.execute` intents to provider-database adapters outside this module.

## Positioning

Long-term governance/runtime layer behind proofs like CompanyOS VoiceOps.

## Public entrypoints

- `@lssm-tech/module.companyos` — root barrel
- `@lssm-tech/module.companyos/executor` — executor composition and adapter port types
- `@lssm-tech/module.companyos/fake-adapters` — deterministic fake adapters for tests and examples
- `@lssm-tech/module.companyos/flagship-fixture` — replayable proof from communication-style source evidence to CompanyOS execution outcome
- `@lssm-tech/module.companyos/persistence` — provider-free CompanyOS schema contribution and governed database mutation intents for host-bound persistence
- `@lssm-tech/module.companyos/outcome-value-view` — deterministic view model for outcome value reports, review queues, readiness, and top prompt/skill influences
- `@lssm-tech/module.companyos/ui` — reusable, data-prop-driven CompanyOS preview screens and deterministic view-model data
- `@lssm-tech/module.companyos/ui/CompanyOsPreview` — canonical React preview shell for starter kits and examples

## Outcome value view

`./outcome-value-view` keeps module-level presentation data deterministic: it summarizes evidence-backed business value reports, review queue size, autonomy readiness, and top prompt/skill influence groups without providers, storage, network calls, or production action execution.

## Safety

The executor preserves CompanyOS policy-gate verdicts. Approval-required, denied, and reserved-human-only plans return operator-facing results instead of dispatching. Successful dispatches are represented by typed execution dispatch and receipt contracts. Non-dry-run lanes (`agent`, `job`, `integration`, `human`, and `manual_record`) also require `ExecutionDispatchAuthorization` before any adapter is called; missing, mismatched, denied, expired, or revoked authorization returns a typed operator-facing result and leaves adapters untouched. Dry-run dispatch remains available for deterministic proof and preview flows without production authorization.

## Flagship proof

`companyOsFlagshipExecutionProof` demonstrates a communication-style source thread becoming a CompanyOS work item, policy-gate request/decision, dry-run dispatch, execution receipt, and outcome receipt linked to objective, memory, and cadence projections.


## Reusable UI boundary

`./ui` is an isolated product-surface subpath for deterministic CompanyOS previews. It may use React, `@lssm-tech/lib.design-system`, and `lucide-react`; executor/core entrypoints remain side-effect-free and provider-free. The UI data is local fixture/view-model data only and does not perform network calls, filesystem writes, provider dispatch, outbound sends, or production action execution.

Focused examples should treat this module UI as canonical reusable presentation and keep package-level UI exports as thin compatibility/adopter adapters.

```tsx
import { CompanyOsPreview } from '@lssm-tech/module.companyos/ui';
import { CompanyOsScreen } from '@lssm-tech/module.companyos/ui/companyos.types';

export function Demo() {
  return <CompanyOsPreview initialScreen={CompanyOsScreen.WORK_GRAPH} />;
}
```

## Domain-command persistence

`./persistence` models the CompanyOS execution-receipt write path without importing provider-database, Drizzle, Postgres, or credentials. The exported `companyOsPersistenceSchemaContribution` declares `companyos.execution_receipts` and `companyos.domain_command_outbox`; `buildCompanyOsExecutionReceiptPersistenceIntent()` emits managed/BYOK-compatible mutation envelopes whose durable write authority is `companyos.command.execution-receipt.persist`.


---

## @lssm-tech/module.content-generation

Description: Thin provider-agnostic facade for unified content generation workflows with deterministic demo stubs.
Path: packages/modules/content-generation
URL: /llms/module.content-generation

# `@lssm-tech/module.content-generation`

Thin, provider-agnostic facade for unified content generation workflows across text/content, image, video, TTS, STT, and conversation.

## Boundary

This package intentionally ships deterministic demo stubs only. Real provider SDKs and integration packages must be injected by callers through the exported provider ports.

## Quick start

```ts
import { createContentGenerationFacade } from '@lssm-tech/module.content-generation';

const contentGeneration = createContentGenerationFacade();
const result = await contentGeneration.runDemoWorkflow();
```

The default facade does not read credentials or call external services.


---

## @lssm-tech/module.context-storage

Description: Context storage module with persistence adapters
Path: packages/modules/context-storage
URL: /llms/module.context-storage

# @lssm-tech/module.context-storage

Website: https://contractspec.io

**Context storage module with persistence adapters.**

## What It Provides

- **Layer**: module.
- **Consumers**: bundles (library), apps (registry-server).
- `src/pipeline/` contains pipeline stages and orchestration helpers.
- Related ContractSpec packages include `@lssm-tech/lib.context-storage`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.knowledge`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/pipeline/` contains pipeline stages and orchestration helpers.

## Installation

`npm install @lssm-tech/module.context-storage`

or

`bun add @lssm-tech/module.context-storage`

## Usage

Import the root entrypoint from `@lssm-tech/module.context-storage`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/entities/` contains domain entities and value objects.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/pipeline/` contains pipeline stages and orchestration helpers.
- `src/storage/` contains persistence adapters and storage implementations.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./pipeline/context-snapshot-pipeline` resolves through `./src/pipeline/context-snapshot-pipeline.ts`.
- Export `./storage` resolves through `./src/storage/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- Depends on `lib.context-storage`, `lib.knowledge`, `lib.contracts-integrations`.
- Pipeline stages must be idempotent; re-running a snapshot should not duplicate data.
- Storage adapters are swappable -- always code against the interface, not the implementation.


---

## @lssm-tech/module.editions

Description: Reusable deterministic edition platform surfaces for resources, UI, workflows, storage, agents, and evidence.
Path: packages/modules/editions
URL: /llms/module.editions

# @lssm-tech/module.editions

Reusable deterministic edition platform surfaces for ContractSpec.

This module owns composed behavior around canonical `@lssm-tech/lib.contracts-spec/editions` contracts: resource builders, UI view models, workflows, storage adapter wiring, deterministic agent plans, and evidence composition.

## Boundaries

- Imports libs only.
- No peer modules, bundles, apps, examples, provider SDKs, raw secrets, external database requirement, or production writes.
- Public tracks stay narrow and acyclic: `./resources`, `./ui`, `./workflow`, `./storage`, `./agents`, `./evidence`. `./proof` intentionally composes those tracks into an aggregate readiness proof.

## Public tracks and review boundaries

The module is a composition layer over `@lssm-tech/lib.contracts-spec/editions`;
it must not create a second edition ontology. Keep each track deterministic and
credential-free:

| Track | Responsibility | Review focus |
| --- | --- | --- |
| `./resources` | Resource template metadata for live proof/showcase callers. | No injected resolver side effects or provider calls. |
| `./ui` | View-model projection for edition screens. | Uses typed edition identity/evidence fields; no private source imports. |
| `./workflow` | Lifecycle transitions and audit events. | Published, rollback, archive, and migration transitions preserve evidence refs. |
| `./storage` | Adapter composition over file/database edition projections. | File and database counts derive from lib storage kinds, not product-specific ids. |
| `./agents` | Deterministic improvement plans. | No provider execution; plans cite edition refs and reversible steps. |
| `./evidence` | Harness/replay/knowledge evidence composition. | Reuses canonical evidence refs instead of inventing module-local proof systems. |
| `./proof` | Aggregate platform readiness proof. | Public exports, runtime wiring, and gate refs stay aligned with package exports. |

For published-edition API work, review code and docs against the subject-generic
identity contract in `packages/libs/contracts-spec/src/editions/README.md`: module
callers should depend on `subjectKey`, `subjectType`, `editionKind`, `editionId`, storage
projection refs, authority scopes, and evidence refs rather than parsing
CompanyOS-specific fixture ids.

## Commands

```bash
bun run test
bun run typecheck
bun run build
node ../../../scripts/biome.cjs check .
```


---

## @lssm-tech/module.examples

Description: Example contract specifications collection
Path: packages/modules/examples
URL: /llms/module.examples

# @lssm-tech/module.examples

Website: https://contractspec.io

**Catalog-first ContractSpec example metadata, with optional runtime helpers for rich example surfaces.**

## What It Provides

- **Layer**: module.
- **Consumers**: CLIs, editor bridges, apps, docs, and rich sandbox/template surfaces.
- Related ContractSpec packages include `@lssm-tech/example.agent-console`, `@lssm-tech/example.ai-chat-assistant`, `@lssm-tech/example.ai-support-bot`, `@lssm-tech/example.analytics-dashboard`, `@lssm-tech/example.calendar-google`, `@lssm-tech/example.content-generation`, ...
- `agent-console` is the default autonomous-agent showcase surfaced through `/sandbox`.
- `data-grid-showcase` is the canonical ContractSpec table showcase surfaced through `/sandbox?template=data-grid-showcase` and `/docs/examples/data-grid-showcase`.

## Installation

`npm install @lssm-tech/module.examples`

or

`bun add @lssm-tech/module.examples`

## Usage

Use the root entrypoint or `@lssm-tech/module.examples/catalog` for metadata-only discovery. Use `@lssm-tech/module.examples/runtime` only when rendering rich template previews or sandbox runtime surfaces. The catalog also exposes shared preview-surface helpers so apps can show every discoverable example while loading rich UI only for packages that export `./ui`.

```ts
import { getExample, listExamples } from '@lssm-tech/module.examples/catalog';
```

```ts
import { ExampleWebPreview, TemplateRuntimeProvider, listTemplates } from '@lssm-tech/module.examples/runtime';
```

The catalog contains source metadata for each example. CLI users can fetch a full example only when needed:

```sh
contractspec examples download minimal --out-dir ./examples/minimal
```

## Public preview/export workflow

Template, docs, and sandbox previews are generated from package-owned example metadata:

1. Example packages expose catalog metadata through `./example` and docs through `./docs` when they should appear in public template/docs surfaces.
2. Rich inline previews are opt-in public surfaces. A package that adds `./ui` must keep that export package-native, deterministic, fixture-backed, and mirrored in `publishConfig.exports`.
3. `scripts/generate-example-registry.ts` is the only writer for generated catalog and preview registry artifacts; run `bun run --cwd packages/modules/examples generate:registry` after changing example exports.
4. Preview consumers should use catalog helpers for discoverability and `supportsInlineExamplePreview()` / `getExamplePreviewSurface()` before loading runtime UI. Keep docs, sandbox, LLMS, and source fallback links available for examples without inline UI.
5. Do not introduce live backend calls, provider credentials, or production actions in preview fixtures. Provider-oriented examples must render local replay/fixture data only.

## Architecture

- `src/builtins.ts` is a generated literal catalog and must not statically import `@lssm-tech/example.*` packages.
- `src/catalog.ts` is the metadata-only public surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/registry.test.ts` is part of the package's public or composition surface.
- `src/registry.ts` is part of the package's public or composition surface.
- `src/runtime` is the optional rich runtime surface for consumers that intentionally install example packages.

## Public Entry Points

- Export `.` resolves through `./src/index.ts` and is catalog-only.
- Export `./catalog` resolves through `./src/catalog.ts`.
- Export `./runtime` resolves through `./src/runtime/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run generate:registry` — bun ../../../scripts/generate-example-registry.ts --write
- `bun run prebuild` — bun run generate:registry && contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add table capabilities.
- Stability.
- Vnext ai-native.

## Notes

- This module is a thin catalog/runtime bridge -- business logic belongs in individual example packages under `packages/examples/`.
- Adding a new example requires creating the example package and regenerating the catalog with `bun run generate:registry`; do not add it as a direct dependency here.
- Root/catalog imports must remain metadata-only. Rich runtime consumers should import `@lssm-tech/module.examples/runtime` and own any required `@lssm-tech/example.*` dependencies directly.
- The meetup-ready autonomous-agent path is the deterministic `agent-console` sandbox plus its replay proof lane.
- The shared ContractSpec table stack is demonstrated directly by `data-grid-showcase` and reused in `analytics-dashboard`, `crm-pipeline`, `integration-hub`, and `agent-console`.


---

## @lssm-tech/module.execution-console

Description: Operator-facing execution lane console module.
Path: packages/modules/execution-console
URL: /llms/module.execution-console

# @lssm-tech/module.execution-console

Website: https://contractspec.io

Operator-facing execution lane console components and helpers built on top of `@lssm-tech/lib.execution-lanes`.

## What It Provides

- Presentation components for lane status, timelines, team worker views, completion views, and evidence browsing.
- A read-only command reference component that surfaces the typed `/clarify`, `/plan`, `/plan --consensus`, `/complete`, and `/team` semantics from `@lssm-tech/lib.execution-lanes/interop`.
- Small core helpers that turn lane snapshots into UI-friendly timeline items.
- A light presentation-state hook for tabs and evidence selection.

## Public Entry Points

- `.` resolves through `./src/index.ts`
- `./core` resolves through `./src/core/index.ts`
- `./presentation` resolves through `./src/presentation/index.ts`
- `./presentation/components` resolves through `./src/presentation/components/index.ts`
- `./presentation/hooks` resolves through `./src/presentation/hooks/index.ts`


---

## @lssm-tech/module.governance-suite

Description: Governance and audit suite — policy editor, audit trail, and compliance surfaces for the Agent + Workflow pillar
Path: packages/modules/governance-suite
URL: /llms/module.governance-suite

# @lssm-tech/module.governance-suite

Website: https://contractspec.io

**Governance + Audit suite for the Agent + Workflow pillar — policy editor,
constraint management, audit-trail inspection, and evidence attachment.**

## What It Provides

- **Layer**: module.
- **Consumers**: `@lssm-tech/bundle.managed-companyos`, the
  `web-application-monolith` `/governance/**` + `/audit/**` routes, and
  future native shells via shared view-models.
- `src/core/` — policy simulators, constraint reducers, audit-event
  projectors, evidence-attachment workflows.
- `src/presentation/` — promoted screens (`GovernanceScreen`,
  `AuditTrailScreen`, `PolicyEditor`, `AuditEventDetail`).
- `src/data-views/` — data-view specs for tables and detail panels.

## Installation

`npm install @lssm-tech/module.governance-suite`

or

`bun add @lssm-tech/module.governance-suite`

## Usage

Import the root entrypoint from `@lssm-tech/module.governance-suite`, or
choose a documented subpath when you only need one slice of the surface.

## Architecture

- `src/governance-suite.capability.ts` — capability declaration.
- `src/governance-suite.feature.ts` — feature manifest listing the 10
  governance/audit operations the module owns.
- `src/core/` — domain logic.
- `src/presentation/` — UI (design-system-first).
- `src/data-views/` — data-view specs.
- `src/index.ts` — public barrel.

## Public Entry Points

- `.` → `./src/index.ts`
- `./governance-suite.capability` → `./src/governance-suite.capability.ts`
- `./governance-suite.feature` → `./src/governance-suite.feature.ts`
- `./core` → `./src/core/index.ts`
- `./presentation` → `./src/presentation/index.ts`
- `./data-views` → `./src/data-views/index.ts`

## Notes

- Audit records are append-only; mutations and deletions break compliance
  invariants. Corrections are compensating events.
- Auditor persona sees every action with `disabled + tooltip`, never silent
  capability strip.
- Design-system primitives first; fallbacks marked `// DS-FALLBACK:`.


---

## @lssm-tech/module.integration-hub

Description: Scoped integration-hub module — 3 genuinely reusable primitives (useIntegrationData, useCredentialSetup, renderIntegrationMarkdown) promoted from examples/integration-hub. RSC-directive boundaries are explicit.
Path: packages/modules/integration-hub
URL: /llms/module.integration-hub

# @lssm-tech/module.integration-hub

Scoped module hosting three reusable integration-hub primitives. Intentionally
narrow — any new export requires a planning loop.

## Installation

```bash
bun add @lssm-tech/module.integration-hub
```

## Exports

| Import path | Exports | RSC-safe? |
|---|---|---|
| `@lssm-tech/module.integration-hub/hooks` | `useIntegrationData`, `useCredentialSetup` | No — use in client components only |
| `@lssm-tech/module.integration-hub/model` | `buildCredentialSetupModel`, all credential-setup types | Yes |
| `@lssm-tech/module.integration-hub/renderers` | `renderIntegrationMarkdown` | Yes |
| `@lssm-tech/module.integration-hub` | All of the above | Use sub-paths to preserve RSC boundaries |

## Quick start

### Loading integration data (client component)

```typescript
'use client';
import { useIntegrationData, type IntegrationDataPort } from '@lssm-tech/module.integration-hub/hooks';

const port: IntegrationDataPort = {
  listIntegrations: (input) => fetch(`/api/integrations?projectId=${input.projectId}`).then(r => r.json()),
  listConnections:  () => fetch('/api/connections').then(r => r.json()),
  listSyncConfigs:  () => fetch('/api/syncs').then(r => r.json()),
};

export function IntegrationCatalog({ projectId }: { projectId: string }) {
  const { integrations, loading, error, stats } = useIntegrationData({ projectId, port });

  if (loading) return <p>Loading…</p>;
  if (error)   return <p>Error: {error.message}</p>;

  return (
    <ul>
      {integrations.map(i => <li key={i.id}>{i.name} — {i.status}</li>)}
    </ul>
  );
}
```

### Credential setup wizard (client component)

```typescript
'use client';
import { useCredentialSetup } from '@lssm-tech/module.integration-hub/hooks';
import { buildCredentialSetupModel, type CredentialManifest } from '@lssm-tech/module.integration-hub/model';

const manifest: CredentialManifest = {
  modes: {
    managed: { secretFields: [{ key: 'API_KEY', required: true }] },
    byok:    { configFields: [{ key: 'ENDPOINT', required: true }] },
  },
};

export function CredentialWizard() {
  const { state, advance, reset, setMode } = useCredentialSetup();

  const model = buildCredentialSetupModel({
    mode: state.mode,
    manifest,
    environment: { variables: {}, targets: {} },
    runtime: { configValues: {}, secretRefs: {}, targetIds: [] },
  });

  return (
    <div>
      <p>Step {state.step} / 3 — mode: {state.mode}</p>
      <p>Missing secrets: {model.missingSecrets.length}</p>
      <button onClick={advance}>Next</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}
```

### Rendering a markdown card (RSC-safe)

```typescript
// Works in React Server Components — no 'use client' needed
import { renderIntegrationMarkdown } from '@lssm-tech/module.integration-hub/renderers';

export async function IntegrationCard({ id }: { id: string }) {
  const integration = await fetchIntegration(id);
  const markdown = renderIntegrationMarkdown({
    id: integration.id,
    name: integration.name,
    description: integration.description,
    category: integration.category,
    status: integration.status,
    connectionCount: integration.connections.length,
  });
  return <MarkdownRenderer content={markdown} />;
}
```

## RSC directive boundaries

Hooks carry `'use client'` — import them only in client components. Model types
and the markdown renderer have no directive and are safe to import anywhere,
including React Server Components. See `AGENTS.md` for the full boundary table
and lint rules.

## What this package does NOT include

- CompanyOS-specific chrome or view-models (those live in `bundle.managed-companyos`)
- `RedactedCredentialChip` (stays in the bundle pending second consumer)
- Any example fixtures or mock data (see `packages/examples/integration-hub`)

## Development

```bash
bun test --cwd packages/modules/integration-hub
bun run --cwd packages/modules/integration-hub typecheck
```


---

## @lssm-tech/module.learning-journey

Description: Comprehensive learning journey engine - onboarding, LMS, flashcards, gamification, and AI personalization
Path: packages/modules/learning-journey
URL: /llms/module.learning-journey

# @lssm-tech/module.learning-journey

Website: https://contractspec.io

**Canonical adaptive journey runtime for onboarding, drills, coaching, LMS, flashcards, gamification, and AI personalization.**

## What It Provides

- **Layer**: module.
- **Consumers**: bundles (library, contractspec-studio), apps (web-landing).
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Installation

`npm install @lssm-tech/module.learning-journey`

or

`bun add @lssm-tech/module.learning-journey`

## Usage

Import the root entrypoint from `@lssm-tech/module.learning-journey`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/engines` is part of the package's public or composition surface.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./contracts/models` resolves through `./src/contracts/models.ts`.
- Export `./contracts/journey` resolves through `./src/contracts/journey.ts`.
- Export `./contracts/onboarding` resolves through `./src/contracts/onboarding.ts`.
- Export `./contracts/operations` resolves through `./src/contracts/operations.ts`.
- Export `./contracts/shared` resolves through `./src/contracts/shared.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-journey.docblock` resolves through `./src/docs/learning-journey.docblock.ts`.
- Export `./engines` resolves through `./src/engines/index.ts`.
- Export `./engines/srs` resolves through `./src/engines/srs.ts`.
- Export `./runtime` resolves through `./src/runtime/index.ts`.
- Export `./runtime/onboarding-runtime` resolves through `./src/runtime/onboarding-runtime.ts`.
- The package publishes 34 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add full i18n support across all 10 packages (en/fr/es, 460 keys).

## Notes

- SRS/streak/XP engines are pure functions -- keep them side-effect-free.
- i18n catalogs must stay in sync across all supported locales (en, es, fr).
- Entity schemas are shared with the UI; breaking changes propagate to all learning surfaces.


---

## @lssm-tech/module.lifecycle-advisor

Description: AI-powered lifecycle recommendations and guidance
Path: packages/modules/lifecycle-advisor
URL: /llms/module.lifecycle-advisor

# @lssm-tech/module.lifecycle-advisor

Website: https://contractspec.io

**AI-powered lifecycle recommendations and guidance.**

## What It Provides

- **Layer**: module.
- **Consumers**: bundles (library, contractspec-studio), apps (web-landing, cli).
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/module.lifecycle-advisor`

or

`bun add @lssm-tech/module.lifecycle-advisor`

## Usage

Import the root entrypoint from `@lssm-tech/module.lifecycle-advisor`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/ceremony` is part of the package's public or composition surface.
- `src/data/` contains static content, registries, and package-local datasets.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/recommendations` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Fix small issues.
- Add full i18n support across all 10 packages (en/fr/es, 460 keys).

## Notes

- Depends on `lib.lifecycle` for stage definitions -- never redefine stages here.
- Recommendation data lives in `src/data/`; keep data files declarative and serializable.
- Advisory outputs must be deterministic for the same input state.


---

## @lssm-tech/module.lifecycle-core

Description: Core lifecycle stage definitions and transitions
Path: packages/modules/lifecycle-core
URL: /llms/module.lifecycle-core

# @lssm-tech/module.lifecycle-core

Website: https://contractspec.io

**Core lifecycle stage definitions and transitions.**

## What It Provides

- **Layer**: module.
- **Consumers**: modules (lifecycle-advisor), bundles (library, contractspec-studio), apps (web-landing, cli).
- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.

## Installation

`npm install @lssm-tech/module.lifecycle-core`

or

`bun add @lssm-tech/module.lifecycle-core`

## Usage

Import the root entrypoint from `@lssm-tech/module.lifecycle-core`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- `src/collectors` is part of the package's public or composition surface.
- `src/data/` contains static content, registries, and package-local datasets.
- `src/i18n` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/orchestrator` is part of the package's public or composition surface.
- `src/planning` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint/test regressions after voice capability updates.
- Add full i18n support across all 10 packages (en/fr/es, 460 keys).

## Notes

- Depends on `lib.lifecycle` for foundational types -- this module adds orchestration on top.
- Stage transition rules are the source of truth; changes here cascade to lifecycle-advisor and all consuming bundles.
- Stage data in `src/data/` must remain backward-compatible to avoid breaking persisted project states.


---

## @lssm-tech/module.marketing-evolution

Description: Offline marketing evolution pipeline: signal collection, improvement proposals, human-gated PR output, and experiment-variant port.
Path: packages/modules/marketing-evolution
URL: /llms/module.marketing-evolution

(No README.md)

---

## @lssm-tech/module.mobile-review

Description: Reusable mobile-first Builder review surfaces.
Path: packages/modules/mobile-review
URL: /llms/module.mobile-review

# @lssm-tech/module.mobile-review

Reusable mobile-first Builder review surfaces that compose the existing Builder workbench components into a dedicated mobile review entrypoint.


---

## @lssm-tech/module.notifications

Description: Notification center module for ContractSpec applications
Path: packages/modules/notifications
URL: /llms/module.notifications

# `@lssm-tech/module.notifications`

Compatibility shim for the former notification module package.

Canonical notification contracts now live under `@lssm-tech/lib.contracts-spec/notifications`. Reusable notification entities, schema contributions, channels, templates, and i18n live in `@lssm-tech/lib.notification`.

## Migration

Prefer new imports for new code:

```ts
import { NotificationsFeature } from "@lssm-tech/lib.contracts-spec/notifications";
import { createChannelRegistry } from "@lssm-tech/lib.notification/channels";
import { notificationsSchemaContribution } from "@lssm-tech/lib.notification/entities";
```

Existing imports from `@lssm-tech/module.notifications` remain supported during the compatibility window. The module shim intentionally preserves:

- `notificationsSchemaContribution.moduleId === "@lssm-tech/module.notifications"`.
- `NotificationsFeature.meta.key === "modules.notifications"`.
- Existing export subpaths including `./channels`, `./contracts`, `./entities`, `./i18n`, `./i18n/catalogs/*`, `./notifications.capability`, `./notifications.feature`, and `./templates`.

## Local Commands

- `bun run test`
- `bun run typecheck`
- `bun run lint:check`
- `bun run build`


---

## @lssm-tech/module.operating-cockpit

Description: Operator cockpit shell — fleet board, navigation surface, and cross-domain operating screens for the Agent + Workflow pillar
Path: packages/modules/operating-cockpit
URL: /llms/module.operating-cockpit

# @lssm-tech/module.operating-cockpit

Website: https://contractspec.io

**Operator cockpit shell for the Agent + Workflow pillar — fleet board,
navigation surface, and cross-domain operating screens.**

## What It Provides

- **Layer**: module.
- **Consumers**: `@lssm-tech/bundle.managed-companyos`, the
  `web-application-monolith` `/operating/**` + `/fleet/**` routes and
  the navigation shell that wraps the entire Agent + Workflow pillar,
  and future native shells via shared view-models.
- `src/core/` — fleet read-model aggregators (composing agent + workflow
  + review snapshots), navigation surface resolvers, board-state
  projectors, ROI / health rollups.
- `src/presentation/` — promoted screens (`OperatorLandingScreen`,
  `OperatorOverviewScreen`, `FleetBoardScreen`, `NavigationShell`).
- `src/handlers/` — operation handlers for the 3 `fleet.*` contracts.
- `src/data-views/` — data-view specs for the fleet/board/landing
  tables.

## Installation

`npm install @lssm-tech/module.operating-cockpit`

or

`bun add @lssm-tech/module.operating-cockpit`

## Usage

Import the root entrypoint from `@lssm-tech/module.operating-cockpit`,
or choose a documented subpath when you only need one slice of the
surface.

## Architecture

- `src/operating-cockpit.capability.ts` — capability declaration.
- `src/operating-cockpit.feature.ts` — feature manifest listing the 3
  `fleet.*` operations the module owns.
- `src/core/` — domain logic (aggregation + navigation).
- `src/presentation/` — UI (design-system-first).
- `src/handlers/` — aggregating operation handlers.
- `src/data-views/` — data-view specs.
- `src/index.ts` — public barrel.

## Public Entry Points

- `.` → `./src/index.ts`
- `./operating-cockpit.capability` → `./src/operating-cockpit.capability.ts`
- `./operating-cockpit.feature` → `./src/operating-cockpit.feature.ts`
- `./core` → `./src/core/index.ts`
- `./presentation` → `./src/presentation/index.ts`
- `./handlers` → `./src/handlers/index.ts`
- `./data-views` → `./src/data-views/index.ts`

## Notes

- `fleet.*` handlers compose read-models from `agent.*`, `workflow.*`,
  and `review.*` handlers only — never direct store access. Seam
  contract lives in `lib.contracts-spec/src/operations/SEAMS.md`.
- The 28 NavSurface routes (Phase 0.6) are the single source of truth
  for the cockpit navigation shell.
- Capability gates resolve to `disabled + tooltip`, never silent strip.
- Design-system primitives first; fallbacks marked `// DS-FALLBACK:`.


---

## @lssm-tech/module.organization-planning

Description: Organization planning composition module with typed adapter ports for cross-module integration.
Path: packages/modules/organization-planning
URL: /llms/module.organization-planning

# `@lssm-tech/module.organization-planning`

Organization planning composition module with typed adapter ports for cross-module integration.

Composes planning packets into provider-neutral cross-module adapter-port obligations and readiness results. This module provides the bridge between organization-planning-spec contracts and actual cross-module execution through typed adapter ports.

## Public entrypoints

- `@lssm-tech/module.organization-planning` — root barrel
- `@lssm-tech/module.organization-planning/adapter-ports` — typed adapter port interfaces and receipts
- `@lssm-tech/module.organization-planning/composition` — composition function and core logic
- `@lssm-tech/module.organization-planning/fake-adapters` — deterministic fake adapters for tests
- `@lssm-tech/module.organization-planning/flagship-fixture` — three flagship cross-module proof fixtures
- `@lssm-tech/module.organization-planning/opa-runtime` — side-effect-free OPA manual loop runtime
- `@lssm-tech/module.organization-planning/domain-command-persistence` — immutable OPA domain-command persistence events

## Adapter Ports

The module defines typed adapter ports for:

- `companyos_work` / `companyos_commitment` — CompanyOS work and commitment operations
- `communication_send` — CommunicationOS confirmation, reminder, and follow-up operations
- `jobs_schedule` — Jobs scheduler operations
- `orchestration_workflow` — Orchestration workflow triggers
- `growth_qualification` — Growth qualification recording
- `finance_approval` — Finance approval requests
- `assurance_evidence` — Assurance evidence recording
- `integration_capability` — Integration capability checks
- `builder_delivery` — Builder delivery processing
- `rolemorph_surface` — RoleMorph surface rendering
- `calendar_execution` — real calendar event execution (`listEvents` /
  `createEvent` / `updateEvent` / `deleteEvent`). Bound to a real provider by
  `@lssm-tech/integration.opa-calendar-bridge`; invoked only on the authorized +
  approval-satisfied confirm path.

## Composition

```typescript
import { composeOrganizationPlanningCore } from '@lssm-tech/module.organization-planning/composition';
import { createAllFakeAdapters } from '@lssm-tech/module.organization-planning/fake-adapters';

const adapters = createAllFakeAdapters();
const result = await composeOrganizationPlanningCore(packet, adapters);
```

## OPA Manual Runtime

```typescript
import { runOpaManualLoop } from '@lssm-tech/module.organization-planning/opa-runtime';

const result = runOpaManualLoop({
	runId: 'mission-relay-ready',
	workspaceId: 'workspace_hackathon_paris_ai',
	generatedAt: '2026-05-16T08:00:00.000Z',
	tasks,
	primaryPolicy,
	agenda,
	booking,
	externalMarkdown: true,
});
```

The runtime composes the `@lssm-tech/lib.organization-planning-spec/opa`
availability/planner/agenda/booking/markdown primitives into the first manual
loop: plan proposal, agenda proposal, booking proposal, Notion-ready markdown,
audit payloads, required approvals, risk summary, and an immutable persisted
OPA domain-command event. It is intentionally side-effect free: external
calendar writes and client messages remain blocked until a host supplies
reviewed production adapters.


## OPA Domain Command Persistence

```typescript
import { persistOpaDomainCommand } from '@lssm-tech/module.organization-planning/domain-command-persistence';

const workflow = persistOpaDomainCommand({
	command: {
		id: 'cmd-opa-booking-1',
		actionKind: 'propose_booking_slots',
		actorKind: 'agent',
		targetType: 'booking_proposal',
		targetId: 'booking-1',
		mode: 'draft',
		workspaceId: 'workspace_hackathon_paris_ai',
	},
	log: { events: [], version: 0 },
	occurredAt: '2026-05-16T08:00:00.000Z',
});
```

OPA command persistence records the domain command, target, runtime action
contract, approval status, violations, and immutable event-log version. It does
not write to a database or provider: managed/BYOK storage remains a host concern,
and high-impact external-facing agenda, booking, markdown, and manual-loop
commands persist approval packets instead of executing.

## Flagship Fixtures

Three deterministic cross-module fixtures demonstrate end-to-end flows:

1. **Revenue Booking to Delivery Kickoff** — Sales booking through to CompanyOS work
2. **Capacity-Aware Project Reschedule** — Rescheduling with approval gates
3. **Builder Customer Delivery Agenda** — Builder delivery with customer communication

```typescript
import { organizationPlanningFlagshipFixtures } from '@lssm-tech/module.organization-planning/flagship-fixture';

const result = await organizationPlanningFlagshipFixtures.revenueBookingToDeliveryKickoff();
```

## Boundary

- Imports from `@lssm-tech/lib.organization-planning-spec` only
- No provider SDKs, credentials, network calls, filesystem access, or queue operations
- No side effects by default — production execution requires caller-provided adapters
- Preserves policy gates and approval requirements

> **Compatibility note (manual-loop result):** `externalEffectsBlocked` on the
> manual-loop result type widened from the literal `true` to `boolean`. It is now
> computed from `isOpaExecutionAllowed(...)`, so on the authorized +
> approval-satisfied path it can report `false` (effects executed) while every
> unauthorized/unapproved path still reports `true`. This is behaviour-compatible
> for runtime consumers but a type-narrowing break for any code that relied on the
> literal `true`.


---

## @lssm-tech/module.product-intent-core

Description: Core product intent orchestration and adapters
Path: packages/modules/product-intent-core
URL: /llms/module.product-intent-core

# @lssm-tech/module.product-intent-core

Website: https://contractspec.io

**Core product intent orchestration and adapters.**

## What It Provides

- **Layer**: module.
- **Consumers**: bundles (contractspec-studio), apps (web-landing).
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.product-intent-utils`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.product-intent-utils`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/module.product-intent-core`

or

`bun add @lssm-tech/module.product-intent-core`

## Usage

Import the root entrypoint from `@lssm-tech/module.product-intent-core`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/evidence/` contains evidence ingestion and normalization helpers.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/orchestrator` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Depends on `lib.product-intent-utils` for shared utilities -- keep orchestration logic here, primitives in the lib.
- Intent resolution must be idempotent; re-processing the same input should yield the same spec output.
- Adapter interfaces are the extension point; new integrations go through the adapter pattern.


---

## @lssm-tech/module.provider-ranking

Description: AI provider ranking module with persistence and pipeline orchestration
Path: packages/modules/provider-ranking
URL: /llms/module.provider-ranking

# @lssm-tech/module.provider-ranking

Website: https://contractspec.io

**Provider-ranking module that adds persistence adapters and pipeline orchestration on top of lower-level ranking logic.**

## What It Provides

- Coordinates ingest, storage, scoring, and ranking refresh flows over provider benchmark data.
- Exposes entities, pipelines, and storage interfaces for ranking-aware applications.
- Sits between ranking libraries and deployable MCP or application shells.
- `src/pipeline/` contains pipeline stages and orchestration helpers.

## Installation

`npm install @lssm-tech/module.provider-ranking`

or

`bun add @lssm-tech/module.provider-ranking`

## Usage

Import the root entrypoint from `@lssm-tech/module.provider-ranking`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/entities/` defines ranking-related domain shapes.
- `src/pipeline/` contains ingestion and ranking orchestration stages.
- `src/storage/` contains persistence-facing interfaces and implementations.
- `src/index.ts` exposes the composed module surface.

## Public Entry Points

- Exports entities, pipeline helpers, named pipeline entrypoints, and storage surfaces.
- Export `.` resolves through `./src/index.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./pipeline` resolves through `./src/pipeline/index.ts`.
- Export `./pipeline/ingestion-pipeline` resolves through `./src/pipeline/ingestion-pipeline.ts`.
- Export `./pipeline/ranking-pipeline` resolves through `./src/pipeline/ranking-pipeline.ts`.
- Export `./storage` resolves through `./src/storage/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Add Composio universal fallback, fix provider-ranking types, and expand package exports.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- Depends on `lib.provider-ranking` for scoring logic and ingesters -- this module adds persistence and orchestration.
- Pipeline stages must be idempotent; re-ingesting the same benchmark data should not create duplicates.
- Storage adapters are swappable -- always code against the interface, not the implementation.


---

## @lssm-tech/module.review-queue

Description: Review queue module: human-in-the-loop approval, escalation, audit-grade decision flows, and per-domain health probe.
Path: packages/modules/review-queue
URL: /llms/module.review-queue

(No README.md)

---

## @lssm-tech/module.workflow-orchestration

Description: Workflow orchestration module — board, DAG, dashboard, composer, state-machine, instance lifecycle, approvals.
Path: packages/modules/workflow-orchestration
URL: /llms/module.workflow-orchestration

# `@lssm-tech/module.workflow-orchestration`

Workflow orchestration exposes a module-local control-plane runtime for authored workflow runs. The runtime is intentionally small and spec-first: contracts define the public operation keys, while this module owns the in-memory reducer used by workbench, dashboard, approval, evidence, and audit projections.

## Runtime slice

The exported core helpers are:

- `createWorkflowRunState` — creates a deterministic draft run with pending steps.
- `applyWorkflowTransition` — applies the exposed lifecycle transitions and returns an immutable result.
- `validateWorkflowActionClassification` — enforces fail-closed action metadata before mutating run state.

Supported lifecycle transitions include activation, dispatch, pause, resume, retry, cancel, step advance/skip, and approval approve/reject. Approval-required steps block until an explicit approval transition is accepted.

## Safety and observability

Every mutating transition must provide a `WorkflowActionClassification` with operation kind, actor/work/surface/resource/adaptation/safety refs, authority scope, policy decision, audit receipt, evidence receipt, replay ref, risk tier, redaction status, and timestamp. Missing or denied classification fails closed and leaves the prior state unchanged.

Accepted transitions append:

- lifecycle telemetry for the transition and resulting status;
- audit entries linking actor, policy decision, operation, and receipt ref;
- evidence receipts with replay refs and redaction status.

This keeps composer validation, runtime dispatch, approval decisions, evidence export, and UI projections on the same observable run state.


---

## @lssm-tech/module.workspace

Description: Workspace discovery and management module
Path: packages/modules/workspace
URL: /llms/module.workspace

# @lssm-tech/module.workspace

Website: https://contractspec.io

**Workspace discovery, static analysis, and graph-building module.**

## What It Provides

- **Layer**: module.
- **Generative Core role**: owns pure static analyzers that turn scanned specs, package files, imports/exports, docs, tests, implementation links, and generated outputs into deterministic graph input.
- **Consumers**: bundles (contractspec-studio), apps (cli-contractspec, vscode-contractspec).
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/module.workspace`

or

`bun add @lssm-tech/module.workspace`

## Usage

Import the root entrypoint from `@lssm-tech/module.workspace`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/ai` is part of the package's public or composition surface.
- `src/analysis` is part of the package's public or composition surface.
- `src/formatter.ts` is part of the package's public or composition surface.
- `src/formatters` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/templates` is part of the package's public or composition surface.
- `src/types` is part of the package's public or composition surface.

## Generative Core Analyzer Scope

- Contract graph extraction covers authored operations, events, presentations, forms, workflows, knowledge, policies, integrations, jobs, translations, docs, tests, and generated-artifact refs.
- Codebase graph extraction covers packages, files, imports, exports, tests, docs, generated targets, implementation links, and confidence diagnostics.
- The module stays pure: persistence, Connect policy, CLI rendering, and apply/repair orchestration remain in bundle/app layers.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Add changesets and apply pending fixes.
- Add ai-native messaging channel runtime.

## Notes

- Uses `ts-morph` for AST analysis and `compare-versions` for semver checks -- version bumps may affect parsing behavior.
- Workspace detection is file-system-dependent; always use the provided abstractions, never raw `fs` calls.
- Changes here affect CLI, VSCode extension, and studio workspace initialization flows.


---

## @lssm-tech/bundle.alpic

Description: Alpic MCP server and ChatGPT App hosting bundle
Path: packages/bundles/alpic
URL: /llms/bundle.alpic

# @lssm-tech/bundle.alpic

Website: https://contractspec.io

**Re-exports the Alpic module to provide MCP server and ChatGPT App hosting helpers as a single bundle entry point.**

## What It Provides

- **Layer**: bundle
- **Consumers**: `apps/alpic-mcp`

## Installation

`npm install @lssm-tech/bundle.alpic`

or

`bun add @lssm-tech/bundle.alpic`

## Usage

Import the root entrypoint from `@lssm-tech/bundle.alpic`, or use one of the documented subpaths when you want a narrower surface area.

## Public Entry Points

- `.` — `./src/index.ts`

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Package exports
- Make workspace tests pass without local test files

## Notes

- No business logic lives here; all implementation is in `module.alpic`.
- Changes to exports must stay in sync with the module's public API.


---

## @lssm-tech/bundle.library

Description: (none)
Path: packages/bundles/library
URL: /llms/bundle.library

# @lssm-tech/bundle.library

**Shared library bundle that composes docs, templates, integrations, MCP implementations, and reusable presentation surfaces.**

## What It Provides

- Provides the reusable product-facing bundle consumed by API, web, and documentation surfaces.
- Aggregates docs pages, integration marketplace UI, templates, example showcase pages, and library-side MCP implementations.
- Includes reusable managed/BYOK credential setup UI for integration manifests and monorepo-aware env alias previews.
- Acts as the main composition layer between lower-level libraries and app-specific delivery shells.
- `src/presentation/` contains presentation-layer components and renderers.

## Installation

`npm install @lssm-tech/bundle.library`

or

`bun add @lssm-tech/bundle.library`

## Usage

Import the root entrypoint from `@lssm-tech/bundle.library`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/application/` contains application services including MCP implementations and cross-surface orchestration.
- `src/components/` contains reusable docs, integrations, legal, shell, and template presentation code.
- `src/components/docs/examples/` derives showcase links from the discoverable example catalog and leaves preview rendering to the shared `@lssm-tech/module.examples/runtime` host.
- `src/features/`, `src.config/`, `src.infrastructure/`, and `src.libs/` hold bundle-local composition helpers.
- `src/presentation/` contains feature-specific UI composition exported to consuming apps.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Large multi-subpath bundle exporting docs, integrations, templates, shell layout, email helpers, and MCP application surfaces.
- Export `.` resolves through `./src/index.ts`.
- Export `./application` resolves through `./src/application/index.ts`.
- Export `./application/context-storage` resolves through `./src/application/context-storage/index.ts`.
- Export `./application/mcp` resolves through `./src/application/mcp/index.ts`.
- Export `./application/mcp/cliMcp` resolves through `./src/application/mcp/cliMcp.ts`.
- Export `./application/mcp/common` resolves through `./src/application/mcp/common.ts`.
- Export `./application/mcp/contractsMcp` resolves through `./src/application/mcp/contractsMcp.ts`.
- Export `./application/mcp/contractsMcpResources` resolves through `./src/application/mcp/contractsMcpResources.ts`.
- Export `./application/mcp/contractsMcpTools` resolves through `./src/application/mcp/contractsMcpTools.ts`.
- Export `./application/mcp/contractsMcpTypes` resolves through `./src/application/mcp/contractsMcpTypes.ts`.
- The package publishes many generated export subpaths; treat `package.json` as the source of truth for the current subpath list and keep public-surface docs aligned when exports change.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Package exports.
- Vnext ai-native.
- Add latest models and align defaults.
- Standardize tool naming to underscore notation.
- Add changesets and apply pending fixes.

## Notes

- This bundle is consumed by multiple apps — breaking export changes cascade widely.
- MCP server implementations must stay transport-agnostic (the app layer wires the transport).
- Keep side effects behind explicit adapters; do not perform I/O at import time.


---

## @lssm-tech/bundle.lifecycle-managed

Description: Lifecycle management bundle with analytics and AI advisor
Path: packages/bundles/lifecycle-managed
URL: /llms/bundle.lifecycle-managed

# @lssm-tech/bundle.lifecycle-managed

Website: https://contractspec.io

**Lifecycle management bundle with analytics and AI advisor.**

## What It Provides

- **Layer**: bundle.
- **Consumers**: `examples/lifecycle-cli`.
- `src/services/` contains business logic services and workflows.
- Related ContractSpec packages include `@lssm-tech/lib.analytics`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/lib.observability`, `@lssm-tech/module.lifecycle-advisor`, `@lssm-tech/module.lifecycle-core`, ...
- `src/services/` contains business logic services and workflows.

## Installation

`npm install @lssm-tech/bundle.lifecycle-managed`

or

`bun add @lssm-tech/bundle.lifecycle-managed`

## Usage

Import the root entrypoint from `@lssm-tech/bundle.lifecycle-managed`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/services/` -- assessment service (lifecycle evaluation logic).
- `src/agents/` -- AI lifecycle advisor agent.
- `src/events/` -- lifecycle domain events.
- `src/api/` -- REST handler adapters.
- `src/__tests__/` -- unit tests.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.

## Notes

- Depends on six workspace packages (`lib.analytics`, `lib.contracts-spec`, `lib.lifecycle`, `lib.observability`, `module.lifecycle-advisor`, `module.lifecycle-core`); changes to those APIs propagate here.
- Events must remain serializable for cross-service consumption.
- Keep REST handlers thin; domain logic belongs in services.


---

## @lssm-tech/bundle.managed-companyos

Description: Provider-neutral composition helpers for the managed CompanyOS application ecosystem.
Path: packages/bundles/managed-companyos
URL: /llms/bundle.managed-companyos

# Managed CompanyOS Bundle

`@lssm-tech/bundle.managed-companyos` is the provider-neutral composition boundary for Managed CompanyOS, the invite-led AI operating system for companies built on the ContractSpec substrate.

It is intentionally safe for app packages to import while keeping lower layers pure:

- Apps may compose this bundle plus approved modules/libs.
- This bundle must not import app packages, example packages, provider SDKs, or raw provider credentials.
- Managed and BYOK integration ownership modes must expose equivalent admin affordances while using different support/accountability copy.
- Secret material is represented only as redacted references, never raw values.
- Public managed CompanyOS surfaces are inventoried with compatibility intent and verification evidence.
- Executable proof helpers must stay tied to runnable code and tests, not PRD-only narrative.

## UI surface (`./ui`)

All 427+ shared React components from the app shell have been migrated into this bundle under `src/ui/<domain>/` via PR series `chore/migration/slice-*` (Slices 1–13). The `./ui` subpath is the **canonical UI surface** for managed CompanyOS.

**Import patterns:**

```ts
// Barrel (all domains)
import { GovernancePolicyPanel } from '@lssm-tech/bundle.managed-companyos/ui';

// Per-domain (tree-shakeable, preferred)
import { GovernancePolicyPanel } from '@lssm-tech/bundle.managed-companyos/ui/governance';
```

**UI domains available:** `agents`, `analytics`, `audit`, `auth`, `autonomy`, `brain`, `cockpit`, `composition`, `finance`, `governance`, `graph`, `inbox`, `integrations`, `knowledge`, `landing`, `lifecycle`, `onboarding`, `policy`, `replay`, `shared`, `special-ops`, `status`, `team`, `threads`.

- SSR by default — all components are React Server Components unless they carry an explicit `"use client"` directive.
- App shells must not import from `src/ui/` by filesystem path; use the subpath exports only.


## Integration Hub reusable surfaces

The bundle is the canonical source for the reusable Integration Hub view-models
and templates consumed by examples and app shells.

**Provider-neutral view-models**:

- `buildIntegrationHubViewModel` from the root export or `./view-models/integration-hub` builds the searchable catalog summary, managed/BYOK counts, health counts, recommended tiles, screen-state matrix, and redacted credential references.
- `normalizeManagedCompanyOsIntegrationCatalog` and `normalizeManagedCompanyOsIntegrationConnections` convert workspace integrations into reusable catalog/connection records without app-local catalog rebuilding.
- `buildIntegrationHubViewModelFromCatalog` accepts normalized `IntegrationHubCatalogRecord[]` and `IntegrationHubConnectionRecord[]` input, so examples and app shells can pass provider-neutral records through the bundle instead of forking list/detail behavior.
- Public helper types (`IntegrationHubCatalogRecord`, `IntegrationHubConnectionRecord`, `IntegrationHubFilterState`, `IntegrationHubHealthSummary`, and `IntegrationHubActionDescriptor`) are exported with the catalog seam and remain pure data contracts.
- `buildIntegrationDetailViewModel`, `buildIntegrationConnectionsViewModel`, `buildIntegrationSyncsViewModel`, `buildIntegrationCredentialsViewModel`, `buildIntegrationSecretsViewModel`, `buildIntegrationConfigViewModel`, and `buildIntegrationAuditViewModel` live under their `./view-models/integration-*` subpaths and stay pure: no provider SDKs, network calls, persistence, filesystem reads, or secret access.
- The legacy `./integration-hub-view-model` shim is source-compatible for one release cycle; new consumers should import from `./view-models/integration-hub`.

**Reusable UI**:

- Catalog and detail templates are exported from `@lssm-tech/bundle.managed-companyos/ui/templates` (`IntegrationHubTemplate`, `IntegrationDetailTemplate`, `ConnectionsTemplate`, `SyncsTemplate`, `ConfigTabTemplate`, `IntegrationAuditTabTemplate`, `CredentialsTabTemplate`, and `SecretsTabTemplate`).
- `IntegrationHubTemplate` owns the health overview/details CTA, Info links, search/category/status/mode filters, recommended row, explicit managed/BYOK install wizard, and read-only configure affordance for denied personas.
- Capability atoms and integration-domain design primitives are exported from `@lssm-tech/bundle.managed-companyos/ui/integrations`.
- `CredentialsTabTemplate` and `SecretsTabTemplate` are security-class templates. App routes that render them must be `force-dynamic` and must re-resolve session/persona per request.

**Ownership and redaction contract**:

- Every catalog entry must expose managed/BYOK support metadata or an explicit exception rationale.
- Turn-on/configuration flows must require an explicit managed vs BYOK choice; do not silently default to managed.
- View-models, fixtures, rendered HTML, snapshots, logs, and evidence packets may show only redacted credential references such as `********` or `secretref://...`; raw credential-like values block promotion.

**Registry projection contract**:

- Managed CompanyOS consumes provider-neutral catalog view records only. Bundle
  source must not import Integration Hub examples, implementation packages,
  concrete provider SDKs, provider clients, network adapters, or raw credential
  fixtures to build catalog tiles.
- Preserve the registry two-state model in view-models: catalog availability is
  a policy/display overlay, while connection activation is derived from
  tenant/workspace connection records. Filtering one state must not mutate or
  erase the other.
- Displayed tile counts, recommended tiles, and health summaries should be based
  on the same filtered provider-neutral tile set unless a helper explicitly
  documents a global/unfiltered summary.
- `requiresModeChoice` remains `true` for install/configure affordances so the
  user/operator selects managed or BYOK before any connection flow starts.
- Promotion evidence for catalog changes should include:

```bash
bun test packages/bundles/managed-companyos/src/view-models/integration-hub/__tests__/integration-hub-normalized.test.ts
bun run --cwd packages/bundles/managed-companyos typecheck
bun run managed-companyos:provider-safety
```

## Public composition helpers

- `createManagedCompanyOsWorkspace` creates the deterministic reference workspace with tenant, policy, graph, workflow, replay, evidence, and health projections.
- `createManagedCompanyOsReadinessReport` proves required app surfaces, dual-mode integrations, fail-closed approvals, evidence receipts, and runtime health.
- `createManagedCompanyOsGovernanceReport` classifies managed public surfaces, S0 inventory row refs, and evidence refs before risky implementation changes.
- `createManagedCompanyOsExecutableProof` proves this bundle exposes runnable managed CompanyOS behavior and test-backed evidence.
- `buildManagedCompanyOsIntegrationOwnershipViewModel` keeps managed and BYOK integration UX at affordance parity with redacted credentials.
- `evaluateManagedCompanyOsProviderCandidate` fails closed for raw secrets and requires explicit approval before concrete provider SDK wiring.
- `createReferenceManagedCompanyOsIntegrationPort` provides a deterministic provider-neutral port for app layers.

Concrete provider defaults, managed-provider SDK wiring, credential-handling authority, persistence adapters, and production queue choices remain approval-gated follow-up work.

## Managed Builder navigation

The bundle registers `/companyos/builder` as a bundle-backed navigation surface
for the managed Builder Workbench. It links to integration setup and evidence
surfaces, but it does not replace or relabel the existing agent/workflow route
families. App shells should consume `managedCompanyOsNavRegistry` and
`managedCompanyOsNavGraph` rather than duplicating Builder route copy locally.

## I18n-ready product surface copy

The bundle owns Managed CompanyOS business display copy so app shells do not fork route labels, route descriptions, or degraded-state wording into app-local dictionaries. Product surface snapshots and route builders accept an optional locale input and resolve copy through the bundle translation runtime:

```ts
import { createManagedCompanyOsProductSurfaceSnapshot } from '@lssm-tech/bundle.managed-companyos/product-surfaces';

const snapshot = createManagedCompanyOsProductSurfaceSnapshot({
  locale: 'fr',
});
```

The `./product-surfaces` subpath is the preferred app/mobile import because it exposes only the RN-safe pure route/view-model snapshot seam and avoids pulling SSR/web UI barrels into Expo.

Current catalog coverage for the product-surface route group is `en`, `fr`, and `es`; unsupported or partial requests fall back through the deterministic bundle translation runtime to `en`. The localized fields are display-only: route ids, API paths, web paths, capability refs, evidence refs, health statuses, policy/evidence reason fields, tenant ids, and correlation ids remain stable machine values.

App adapters should pass a negotiated locale or preference context into the bundle helpers instead of duplicating Managed CompanyOS business copy locally. Web and mobile shells remain responsible for host-specific locale detection, document metadata, React/React Native boundaries, and hydration/snapshot handling.

## Capability graph

`src/capability-graph/` exposes the production-owned, pure shape contracts and view-model projections for the Special Ops capability graph. It is the SHAPE source-of-truth — repository (T4), API (T7), worker (T8), and web (T9) surfaces must match these types.

- Types: `CapabilityNodeKind`, `CapabilityStatus` (`enabled | blocked | degraded | disabled`), `CapabilityNode`, `CapabilityEdge`, `CapabilityGraph`.
- Pure builders: `createSpecialOpsCapabilityGraph()`, `createSpecialOpsWorkspaceProfile()`, `createSpecialOpsSeedRunReceipt()`, `attachSpecialOpsCapabilityGraph()` (clock is injectable; no `Date.now()`).
- Projection selectors: `selectCockpitProjection`, `selectOpsSprintProjection`, `selectWorkGraphProjection` — tenant/workspace-scoped, redaction-aware. Disabled or restricted nodes surface a `[redacted-capability]` label and a `disabled` effective status with no raw secret material.
- View-models that consume these projections live in `src/view-models/special-ops`, `src/view-models/ai-ops-sprint`, and `src/view-models/work-graph`. Each output carries a deterministic `locale` (default `en`) and an optional `displayCopy` map keyed by `ManagedCompanyOsI18nKey`, ready for T7/T9 to hydrate localized strings without forking builders.
- Major-version cleanup removed legacy `Managed*` capability aliases; use `CapabilityNodeKind`, `CapabilityStatus`, and `CapabilityGraph` directly.

## Special Ops production cutover

The Special Ops monolith production slice is documented in [`docs/runbooks/special-ops-monolith-production.md`](../../../docs/runbooks/special-ops-monolith-production.md). The bundle owns only pure, provider-neutral contracts for Special Ops, AI Ops Sprint, work graph, capability graph, replay, evidence, redaction view models, and deterministic database lifecycle artifacts. Live tenant/workspace persistence and provider dispatch remain app-layer approval-gated work; do not import example packages, provider SDKs, or raw fixture/customer data to satisfy the production cutover.

## Managed CompanyOS production-path boundary

The broader Managed CompanyOS production path is coordinated by
[`docs/runbooks/managed-companyos.md`](../../../docs/runbooks/managed-companyos.md).
For this bundle, the production-path review has one hard boundary: keep schema,
manifests, pure builders, view-models, redaction helpers, capability graph
contracts, replay, and evidence receipts deterministic and provider-neutral.

Production runtime concerns belong outside bundle module-load/helper execution:

- live DB repositories/connections (the bundle only prints deterministic migrate/seed SQL artifacts);
- session cookies, headers, and protected-route guards;
- concrete provider SDK dispatch, webhook calls, queues, or filesystem state;
- external production credentials or customer data.

The bundle exposes pure SQL/manifest/contract artifacts for app-owned tooling to execute through `bun run --cwd packages/bundles/managed-companyos database:cli <migrate|seed|verify|plan>`. The deterministic seed includes tenant/workspace, capability graph, Special Ops proof rows, replay/evidence rows, and AuthOS fixture-backed projections in `managed_companyos_authos_projections`; it must not open connections, mutate persistence, read secrets, or import app/example/provider packages during import or helper calls. Attach static import-guard, redaction-scan, `database:verify`, database CLI artifact, test, typecheck, lint, and build evidence before treating a boundary change as complete.

## Agent/Workflow Command Center readiness

The production-path Agent/Workflow Command Center slice is tracked by [`docs/agent-workflow-command-center-production-readiness.md`](../../../docs/agent-workflow-command-center-production-readiness.md). Treat that packet as the gate for agent lifecycle, tool registry/permissions, workflow builder/run execution, review/governance/audit/replay, and cross-surface UX parity. The bundle remains the reusable product surface; web/mobile hosts and examples must consume module/bundle APIs rather than owning command-center domain behavior.

The command-center view-model now exposes explicit Atomic CRUD coverage through `buildAgentWorkflowCommandCenterViewModel().atomic`:

- domains: `tool`, `agent`, and `workflow`;
- modes: `list`, `create`, `update`, and `detail` for every domain;
- states: loading, empty, error, denied, read-only, allowed, dirty-invalid, review-required, and blocked;
- per-surface `capabilities`, `policy`, `auditRefs`, `replayRefs`, redaction mode, app-relative `pillarRoute`, and optional host-prefixed `hostRoute`.

`AgentWorkflowCommandCenterTemplate` renders that matrix with CVA-backed state variants. Keep it client-safe: do not import database, provider SDK, app, or example code into the view-model or template.

## S6 release and operations readiness

The S6 handoff for this bundle is evidence-first and provider-neutral. A release
candidate is ready only when the acceptance matrix, operator runbook, release
copy guardrails, and final evidence packet all point to runnable checks.

### Acceptance matrix

| Gate | Required proof | Stop condition |
| --- | --- | --- |
| Managed/BYOK parity | Integration ownership and product-composition tests show equal admin affordances with redacted refs. | Any raw credential preview or asymmetric managed/BYOK affordance blocks release. |
| Tenant/redaction safety | Implementation proof and workspace tests show tenant-scoped graph, replay, and evidence receipts. | Cross-tenant graph nodes, unredacted customer-sensitive payloads, or raw secret-like strings block release. |
| Fail-closed approval | Readiness and product-composition tests show unknown or reserved actions are blocked or approval-required. | Financial, customer-facing, dispatch, legal, or reserved-human actions cannot run without accountable human evidence. |
| Provider-neutral smoke harness | Provider approval and product-composition tests use deterministic reference providers and expect no SDK instantiation. | Concrete provider SDK imports, defaults, credentials, or dispatch paths require a separate approval decision. |
| Provider catalog parity | App-layer provider catalog evidence shows managed/BYOK support metadata for each provider or a documented exception. | Bundle/libs/modules stay provider-neutral; live provider dispatch fails closed when deployment secret-manager values are missing. |
| CRDT disabled by default | `crdt-disabled-default.test.ts` scans managed bundle/app/runbook surfaces for Loro CRDT imports and CRDT enablement env defaults. | CRDT/Loro stays disabled until the root baseline plus focused CRDT typecheck, lint, and tests are green together. |
| Runtime health runbook | Product surface tests expose worker, WebSocket, replay, and evidence degraded states. | API-only green health cannot hide worker/WebSocket/replay degradation. |
| Support lifecycle | Operator runbook names intake, acknowledgement, severity classification, mitigation, customer status updates, post-incident evidence, closure, and ownership handoff. | Managed support availability, contracted response times, or uptime commitments remain blocked until support owner and coverage model approval exists. |
| Release copy guardrails | `createManagedCompanyOsReleaseReadinessPacket` and release-readiness tests scan release-facing copy. | Copy cannot claim formal-attestation guarantees, raw credential-handling authority, live provider execution without approval, or autonomous reserved-action execution. |
| Final evidence packet | Task handoff lists exact tests, typecheck, lint, build, secret scan, static import guard, and known gaps. | No release candidate is complete without command output and explicit known gaps. |

### Provider-neutral smoke harness

Use `createManagedCompanyOsOrchestrationFacade` and
`createManagedCompanyOsReleaseReadinessPacket` for bundle-level dry-run proof.
Smoke inputs must use deterministic reference providers, redacted credential
previews, and `expectedSdkInstantiation: false`. App-layer provider catalog
smoke may cover approved live/reference adapters only when each provider has
managed/BYOK support metadata or an explicit exception rationale. Live Resend,
Slack, PostHog, database, or webhook dispatch may be validated only from
deployment secret-manager values after provider approval; missing values must
fail closed. Raw values must not appear in git, snapshots, logs, release copy,
or evidence receipts.

### Environment validation and runbook

Support evidence is part of the same release gate: the operator packet must show how an incident or customer escalation moves from intake to acknowledgement, severity classification, mitigation, customer status updates, post-incident evidence capture, closure, and ownership handoff. P0/P1 communication expectations may be documented as reference-mode operating guidance, but the bundle must not claim managed support availability, contracted response times, or uptime commitments until a support owner and coverage model are separately approved.

Before promotion, operators validate these non-secret runtime variables:

- `MANAGED_COMPANYOS_STATE_FILE`
- `MANAGED_COMPANYOS_WORKER_HOST`
- `MANAGED_COMPANYOS_WORKER_PORT`
- `MANAGED_COMPANYOS_DEFAULT_TENANT_ID`

Provider env vars such as `MANAGED_COMPANYOS_RESEND_API_KEY`,
`MANAGED_COMPANYOS_SLACK_WEBHOOK_URL`, and
`MANAGED_COMPANYOS_BYOK_SLACK_WEBHOOK_URL` are optional until the approved
provider dispatch smoke is enabled, and must be configured only through the
deployment secret manager.

Before any approved provider smoke begins, validate the filled G006 decision
artifact. The command is intentionally fail-closed: exit `0` means all mandatory
provider categories are ready for adapter smoke, exit `1` means the artifact
parsed but remains blocked, and exit `2` means malformed JSON or an invalid
decision shape. Artifacts marked `not_real_approval` also fail closed unless the
operator passes `--allow-example`, which is reserved for synthetic command-path
evidence and must not be used as customer authorization.

```bash
bun run --cwd packages/bundles/managed-companyos provider-approval:validate \
  .omx/plans/evidence/g006-provider-approval-decision-template.json
```

Recommended S6 evidence commands:

```bash
bun run --cwd packages/bundles/managed-companyos test
bun run --cwd packages/bundles/managed-companyos typecheck
bun run --cwd packages/bundles/managed-companyos lint:check
bun run --cwd packages/bundles/managed-companyos build
bun scripts/check-managed-companyos-production-hardening.ts
```

The final release handoff should also include the executable `scanManagedCompanyOsReleaseSurface` secret/redaction scan, a provider-catalog parity guard, and a static import guard proving this bundle has no app, example, provider SDK, or CRDT/Loro enablement imports. Do not add a Managed CompanyOS CRDT flag, env var,
or adapter import until `docs/data-transmission-crdt-v0.md#crdt-promotion-criteria`
has green root baseline and focused CRDT evidence.

### UX states

The managed bundle keeps the canonical UI states visible instead of collapsing
them into a single healthy/failed binary:

- `healthy` surfaces the normal operator and product views.
- `degraded` keeps the degraded banner and degraded reason copy visible across
  the status and communication screens.
- `down` blocks promotion and keeps replay, worker, or WebSocket failures
  explicit instead of hiding them behind an API-only green check.
- `active` / `inactive` remain the auth-capability states for role and session
  affordances.
- Blocked or approval-required actions use explicit guard copy rather than
  provider, compliance, or credential claims.

These states are already exercised by the managed CompanyOS status,
communication-screen, and product-surface tests; the S6 docs should describe
them as UX contracts, not as new runtime modes.

### Operator docs and evidence packet

Operators should use this bundle README together with:

- `docs/companyos-ai-os-release-verification.md` for the central evidence
  packet and verifier checklist.
- `docs/release-workflow.md` for the broader release-capsule and `/llms*`
  guardrails.
- The bundle tests that prove health, redaction, provider-neutral smoke, and
  release-copy guardrails.

The final evidence packet must list the exact commands that were run, the
expected guardrail outcomes, and any known gaps that remain intentionally out of
scope.

## Integration with Custom Applications

This bundle is intended to be composed by the three official app monoliths (web, API, worker). If you need to integrate Managed CompanyOS into a custom application, use this bundle to build your own app composition:

```typescript
import {
  createManagedCompanyOsWorkspace,
  createManagedCompanyOsReadinessReport,
  buildManagedCompanyOsIntegrationOwnershipViewModel
} from '@lssm-tech/bundle.managed-companyos';

// Build deterministic workspace
const workspace = createManagedCompanyOsWorkspace({
  tenantId: 'custom_tenant_id'
});

// Verify readiness
const ready = createManagedCompanyOsReadinessReport(workspace);
if (!ready.allGatesPass) {
  console.error('Not release ready:', ready.failures);
}

// Get dual-mode integration models
const managed = buildManagedCompanyOsIntegrationOwnershipViewModel('managed');
const byok = buildManagedCompanyOsIntegrationOwnershipViewModel('byok');
```

**Important:** Do not import this bundle at runtime in `packages/examples/*`, `packages/libs/*`, or `packages/modules/*`. The three official apps are the only supported composition boundary.

## Provider Approval

This bundle is provider-neutral. All concrete provider integrations (Slack, Resend, PostHog, database/webhook adapters, AWS, etc.) are intentionally wired via approval-gated adapters in app/integration/provider packages, not in the bundle. Provider SDKs and credentials belong at the app composition layer, not here. Each catalog entry should expose managed and BYOK support by default; any managed-only or BYOK-only exception must name the operational reason and the approval/evidence path needed to close it.

The root export now includes `parseManagedCompanyOsProviderApprovalDecision`,
`evaluateManagedCompanyOsProviderApprovalDecision`,
`assertManagedCompanyOsProviderApprovalReady`, and
`createManagedCompanyOsLiveAdapterSmokePlan` so approval artifacts can be parsed,
evaluated, and converted into the per-category smoke checklist required before
live adapter work starts. These helpers do not select a provider, open
credentials, or authorize live dispatch; they only convert a filled decision
record into `approval_blocked` or `ready_for_smoke` readiness and required smoke
assertions.

## Agent/workflow command center view-model

`buildAgentWorkflowCommandCenterViewModel()` exposes the production walking skeleton for the Agent + Workflow pillar. The model is deterministic and client-safe: it uses simulator-only tool bindings by default, records review-required workflow state, includes correlated audit/replay evidence, and never requires provider credentials or external side effects.

```ts
import { buildAgentWorkflowCommandCenterViewModel } from '@lssm-tech/bundle.managed-companyos';

const commandCenter = buildAgentWorkflowCommandCenterViewModel();
```

Use `mode: 'blocked_tool'` to render the fail-closed authorization-required state for tool registry and audit/replay screens.


---

## @lssm-tech/bundle.marketing

Description: (none)
Path: packages/bundles/marketing
URL: /llms/bundle.marketing

# @lssm-tech/bundle.marketing

**Marketing composition bundle for the public ContractSpec site: category-defining substrate narrative, technical product/templates/examples pages, support pages, and email-facing marketing helpers.**

## What It Provides

- Marketing page bodies consumed by `@lssm-tech/app.web-landing`
- Platform-neutral landing story, navigation, page, and examples-entry data consumed by web and Expo shells
- Scenario/template browsing and preview surfaces used on `/templates`
- Support and program pages such as contact, contribute, cofounder, and design-partner
- Email/contact helpers and marketing-adjacent utilities

## Architecture

- `src/components/marketing/` owns the public marketing narratives, section composition, and page-level stories.
- `src/content/` owns React-free story data shared by web and mobile shells.
- `src/content/companyos-marketing-contracts.ts` owns the CompanyOS marketing `MarketingSiteContract` instances consumed by the web app. It imports the shared `@lssm-tech/lib.contracts-spec/marketing` validators, keeps CompanyOS copy in the bundle, and declares the route narrative, section sequence, density, deep-dive routes, CTAs, and evidence refs for `/`, `/product`, `/solutions`, `/solutions/ai-ops-automation-sprint`, `/platform/managed-contractspec`, `/autonomous-companies`, and `/pricing`.
- `src/components/templates/` owns template browsing, preview, and template-to-CLI/Studio flows. Preview content uses the shared example preview host from `@lssm-tech/module.examples/runtime` so UI-backed and fallback examples stay aligned with docs and sandbox.
- `src/libs/email/` owns contact/newsletter/waitlist actions and helpers used by marketing surfaces.
- `src/index.ts` is the root public entrypoint.

The important boundary:
- `@lssm-tech/lib.design-system` owns reusable marketing atoms, molecules, sections, and the typed landing-page section sequence.
- `bundle.marketing` owns story/content mapping, icon lookup, and product-specific page composition.
- Existing `./components/marketing/sections/*` subpaths remain compatibility shims over design-system components.
- CompanyOS contract pages use one render path: `MarketingPageContract` → design-system `MarketingPageSection[]` adapter → existing marketing landing primitives. The bundle supplies content and page contracts; the design system adapts generic presentation props; apps retain route metadata, structured data, canonical URLs, and Next.js shell concerns.
- App packages own routing, metadata, OG, shell, and public delivery.

## Template preview workflow

`bundle.marketing` stays a thin consumer of `@lssm-tech/module.examples` preview metadata:

- `/templates` actions should be derived from `supportsInlineExamplePreview()` and the shared preview surface, not bundle-local allowlists.
- Rich preview content belongs in the example package `./ui` export or an explicitly approved module/examples adapter; marketing should not duplicate domain preview implementations.
- Keep fallback CTAs to docs, sandbox, LLMS, and source links for examples that are discoverable but not inline-preview enabled.
- Preview data must remain deterministic and provider-free; no marketing preview should require live backends, provider credentials, or network execution.

## Public Entry Points

- Root export `.` through `src/index.ts`
- `./content` for platform-neutral landing story data and CTA helpers
- `./content/companyos-marketing-contracts` for CompanyOS marketing page/site contracts and validation helpers
- `./i18n` for a small marketing copy runtime used by app metadata and locale-provider composition
- `./components/marketing/*` for landing, product, pricing, contact, contribute, cofounder, and design-partner surfaces
- `./components/templates/*` for templates browsing and preview surfaces
- `./libs/email/*` for marketing contact/newsletter/waitlist helpers

## Marketing route contract system

`src/content/marketing-route-contracts.ts` exposes exact, generated, and runtime-family `MarketingPageContract` registries for the CompanyOS and ContractSpec public marketing route groups. Adapter-rendered pages keep using the full contract renderer; bespoke pages consume the same route contract system through an inert design-system boundary so existing page copy stays owned by the current components.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Notes

- Keep the bundle focused on page storytelling and marketing interaction flows. Do not move shell/routing concerns here.
- Public positioning in this package must stay aligned with root docs and `@lssm-tech/app.web-landing`.
- If the page story changes materially, update the package docs and the public LLM-facing docs so human-facing and agent-facing descriptions do not drift.

## Design-system marketing foundation split

Generic full-page marketing UI now lives in `@lssm-tech/lib.design-system`. The marketing bundle keeps product story/content ownership and exposes compatibility wrappers for existing section subpaths such as `CtaButtonRow`, `MarketingHero`, `MarketingCtaBand`, `ProseSection`, and `IconGridSection`.

Consumers can keep using the bundle section subpaths while new product pages should compose content into design-system `MarketingPageSection` objects when they need full landing-page foundations.


---

## @lssm-tech/bundle.product-intent

Description: Product intent bundle with AI runner and evidence retriever
Path: packages/bundles/product-intent
URL: /llms/bundle.product-intent

# @lssm-tech/bundle.product-intent

Website: https://contractspec.io

**Product intent bundle with AI runner and evidence retriever.**

## What It Provides

- **Layer**: bundle.
- **Consumers**: not yet wired into an app (standalone bundle).
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/module.product-intent-core`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/module.product-intent-core`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/bundle.product-intent`

or

`bun add @lssm-tech/bundle.product-intent`

## Usage

Import the root entrypoint from `@lssm-tech/bundle.product-intent`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/` -- AI runner and product-intent service.
- `src/__tests__/` -- unit tests.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Uses the Vercel AI SDK (`ai`) for LLM interactions; keep provider-agnostic patterns.
- Depends on `lib.contracts-spec` and `module.product-intent-core`; spec changes upstream affect this bundle.
- AI runner prompts and tool definitions should remain deterministic and testable.


---

## @lssm-tech/bundle.workspace

Description: Workspace utilities for monorepo development
Path: packages/bundles/workspace
URL: /llms/bundle.workspace

# @lssm-tech/bundle.workspace

Website: https://contractspec.io

**Core workspace bundle that powers ContractSpec CLI, validation, code generation, AI workflows, and repository setup.**

## What It Provides

- Provides the service layer behind the CLI, editor integrations, drift detection, diagnostics, and setup flows.
- Owns workspace-oriented AI agents, prompts, templates, fixers, and validation/reporting services.
- Acts as the main orchestration bundle for repository lifecycle, graph inspection, drift reporting, regeneration planning, and codegen workflows.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/services/` contains business logic services and workflows.
- Generative Core orchestration is exposed as `services.generativeCore` for graph artifact persistence, dry-run generation plans, drift reports, and Connect/path policy classification.

## Installation

`npm install @lssm-tech/bundle.workspace`

or

`bun add @lssm-tech/bundle.workspace`

## Usage

Import the root entrypoint from `@lssm-tech/bundle.workspace`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/services/` contains the core use-cases for build, validate, doctor, diff, setup, examples, and CI flows.
- `src/adapters/` and `src/ports/` isolate filesystem, git, AI, and workspace integration boundaries.
- `src/ai/` contains workspace-specific agent definitions, prompts, and model-aware helpers.
- `src/templates/`, `src/contracts/`, `src/formatters/`, `src.types/`, and `src.utils/` support generated outputs and reporting.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.

## Generative Core Responsibilities

- Compose discovery, graph-building, artifact persistence, drift classification, and regeneration-plan services behind ports/adapters.
- Keep graph and drift operations deterministic and JSON-schema-versioned so CLI, CI, Builder, and coding agents can replay evidence.
- Enforce preview-first generation: generated writes require provenance hashes and manual-edit guards; protected/apply paths require Connect verification before mutation.

## Public Entry Points

- Root bundle export with namespaced services, adapters, ports, formatters, templates, contracts, AI helpers, and utilities.
- `services.generativeCore` exposes guarded JSON-artifact helpers for `generated/contractspec/graphs/**`, `generated/contractspec/generation/**`, and `generated/contractspec/drift/**`; dry-run planning remains the default for mutation workflows.
- Export `.` resolves through `./src/index.ts`.
- Environment templates can generate root and app-target `.env.example` content from the shared logical environment contract while preserving per-framework aliases such as `NEXT_PUBLIC_*` and `EXPO_PUBLIC_*`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add table capabilities.
- Stability.
- Package exports.
- Add latest models and align defaults.
- Standardize tool naming to underscore notation.

## Notes

- Largest bundle in the monorepo (~280 source files); prefer editing existing services over adding new top-level directories.
- Adapters must implement port interfaces; no direct infrastructure calls from services.
- AI agent definitions must stay provider-agnostic via the `ai` SDK abstraction.
- Template changes affect generated code across all consumers; test thoroughly.


---

## @lssm-tech/app.web-landing

Description: (none)
Path: packages/apps/web-landing
URL: /llms/app.web-landing

# @lssm-tech/app.web-landing

**Next.js delivery shell for the public ContractSpec website: technical substrate marketing, docs, registry pages, `/llms*`, and selected operate/sandbox surfaces.**

## What It Does

- Owns the app shell, metadata, OG generation, route wrappers, and public site delivery.
- Publishes the marketing experience while delegating most page-body composition to `@lssm-tech/bundle.marketing`.
- Serves docs, registry, sandbox, and operate surfaces while keeping their shared shell consistent with the public brand system.
- Shares example preview rendering across docs, `/templates`, and `/sandbox`, with rich UI for UI-backed examples and fallback cards for the rest of the discoverable catalog.
- Publishes `/llms`, `/llms.txt`, `/llms-full`, `/llms-full.txt`, and package-specific `/llms/[slug]` endpoints for agent-friendly repo guidance.
- Documents design-system adoption guidance for shared interaction patterns such as `ObjectReferenceHandler` and `AdaptivePanel`, including human-readable docs and agent-facing `/llms*` prompts.
- Documents ContractSpec translation runtime guidance, including the optional i18next adapter, SSR/hydration rules, production checks, and an agent implementation prompt.
- Documents data-exchange flexible import-template guidance at `/docs/guides/data-exchange-import-templates`, including developer templates, user remapping flows, server dry-runs, format profiles, verification commands, and copy-ready prompts.

## Template preview and LLMS sync workflow

Public example preview changes must keep human and agent-facing surfaces aligned:

- `/templates`, `/docs/examples/<key>`, and `/sandbox?template=<key>` consume the same module examples preview surface so inline UI and fallback behavior stay consistent.
- `/llms`, `/llms.txt`, `/llms-full`, `/llms-full.txt`, and `/llms/[slug]` must be regenerated or verified after README changes that document example exports, preview support, route inventory, or release workflow expectations.
- Rich previews are deterministic local fixtures only. They must not call live backends, provider SDK clients, production endpoints, or require provider credentials.
- Public key or alias changes are compatibility-sensitive. Preserve existing `examples.*` and normalized lookup behavior unless a release capsule explicitly documents and tests the migration.

## Architecture

- `src/app/` contains route groups for marketing, docs, sandbox, operate, registry, and API endpoints.
- `src/components/` contains app-local shell concerns such as header, footer, SEO helpers, and local route UI.
- `public/llms*.txt` contains machine-readable monorepo guidance exposed directly from the site.
- `scripts/generate-llms-full.mjs` regenerates the public aggregated README corpus used by `/llms-full.txt`.

This package should stay thin:
- marketing page narratives belong in `@lssm-tech/bundle.marketing`
- docs and library composition belong in `@lssm-tech/bundle.library`
- shared reusable UI primitives belong in lower layers

## Public Entry Points and Topics

Static and generated public surfaces currently delivered by this app:

- **Marketing and conversion**: `/`, `/product`, `/pricing`, `/templates`, `/contact`, `/cofounder`, `/contribute`, `/design-partner`, plus legal pages at `/legal/privacy` and `/legal/terms`.
- **Release and registry**: `/changelog`, `/changelog/[version]`, `/registry/featured`, `/registry/packs`, `/registry/packs/[name]`, `/registry/packs/[name]/versions/[version]`, and `/registry/publish`.
- **Feature catalog**: `/features`, `/features/[key]`, and feature detail routes for operations, events, forms, presentations, and DataViews.
- **Docs shell**: `/docs` and topic groups for getting started, specs, guides, libraries, domains, safety, knowledge, integrations, architecture, advanced operation, comparisons, ecosystem, examples, Studio, intent pages, generated reference, manifesto, and ops.
- **Docs guide topics**: installation, private registry access, Hello World, compatibility, developer tools, DataViews, troubleshooting, Next.js endpoint adoption, imported codebases, contract intelligence, codebase graphs, validation/typing, ContractSpec theme, contract-driven forms, i18n, Drizzle database setup, data-exchange import templates, docs/client/schema generation, docs pipeline, module bundles, mobile navigation, Builder workbench/spec packs/intelligence, Connect, provider-backed knowledge, release capsules, and CI diff gating.
- **Docs library topics**: contracts, schema, runtime, translation runtime, UI kit, UI kit web, design system, application shell, cross-platform UI, data views, personalization, observability, resilience, multi-tenancy, workflow composer, workflows, AI agent, analytics, content generation, cost tracking, data backend, evolution, GraphQL, growth, overlay engine, SLO, support bot, and testing.
- **Docs integration topics**: setup/model docs plus OpenAI, Mistral, Qdrant, Gmail, Google Drive, Google Calendar, Stripe, Twilio, GitHub, Slack, Postmark, Powens, Resend, S3, ElevenLabs, WhatsApp Meta, WhatsApp Twilio, circuit breakers, and health routing.
- **Examples and sandbox**: `/docs/examples`, `/docs/examples/[exampleKey]`, `/docs/examples/data-grid-showcase`, `/templates`, `/sandbox`, and `/graph-showcase`.
- **Operate surfaces**: `/operate/builder/workspaces/[workspaceId]`, `/operate/builder/workspaces/[workspaceId]/mobile-review/[cardId]`, `/operate/pm/issues/[issueId]`, and API proxy routes under `/api/operate/builder/*`.
- **Agent-facing discovery**: `/llms`, `/llms.txt`, `/llms-full`, `/llms-full.txt`, `/llms/[slug]`, and `/docs/llms.txt` via static files and rewrites.
- **Public APIs**: `/api/changelog`, `/api/chat`, `/api/graphql/*`, `/api/mcp`, `/api/og`, and operate builder API routes.

Route changes here affect SEO, external links, sitemap output, and agent-discovery flows. Keep `src/app/sitemap.ts`, `next.config.mjs` rewrites, `public/llms*.txt`, this README, and route wrappers aligned.

## Marketing contract boundary

The `(landing-marketing)` route group is wrapped with the shared marketing contract boundary and backed by the ContractSpec route contract registry from `@lssm-tech/bundle.marketing/content`. Static routes, deterministic feature/changelog routes, and runtime-only registry pack families must stay covered by `src/marketing-contract-system.test.ts` when route files move or change.

## Local Commands

- `bun run dev` — bun --bun next dev
- `bun run start` — bun --bun next start
- `bun run build` — bun --bun next build
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run clean` — rimraf .next dist .turbo
- `bun run llms:generate` — bun scripts/generate-llms-full.mjs
- `bun run build:types` — tsgo --noEmit

## Notes

- Branding changes in this package must stay aligned with root docs, generated root AGENTS content, and `public/llms.txt`.
- When updating the public shell, verify that docs and `/llms*` remain readable; this package serves more than the marketing homepage.
- Keep `/docs/libraries/design-system` and `/llms/lib.design-system` aligned when documenting object references, adaptive panels, or other interaction primitives that downstream apps should adopt consistently.
- Keep `/docs/libraries/translation-runtime`, `/llms/[lib.translation-runtime]`, and `@lssm-tech/lib.translation-runtime` README guidance aligned when documenting i18n runtime or adapter behavior.
- Keep `/docs/guides/data-exchange-import-templates`, `/llms/lib.data-exchange-core`, `/llms/lib.data-exchange-client`, and `/llms/lib.data-exchange-server` aligned when documenting import templates, flexible column mapping, dry-runs, or mapping-review prompts.


---

## @lssm-tech/app.action-drift

Description: GitHub Action for ContractSpec drift detection
Path: packages/apps/action-drift
URL: /llms/app.action-drift

# @lssm-tech/action.drift

Website: https://contractspec.io

**GitHub Action that detects contract drift between specs and implementation. Runs in CI to flag when generated code diverges from its source contracts.**

## What It Does

- Uses `@lssm-tech/lib.contracts-spec` for contract definitions
- Uses `@lssm-tech/bundle.workspace` for workspace analysis
- Configured via `action.yml`; no `src/` — logic lives in workspace bundle

## Usage

```yaml
name: ContractSpec Drift
on: pull_request
jobs:
  contractspec:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
    steps:
      - uses: actions/checkout@v6
      - uses: lssm-tech/contractspec/packages/apps/action-drift@main
        with:
          github-packages-token: ${{ secrets.CONTRACTSPEC_PACKAGES_TOKEN }}
          generate-command: 'bun contractspec generate'
```

For private GitHub Packages access, `github-packages-token` must be a GitHub token that can read the ContractSpec packages granted to the consuming repository, bot, or GitHub App.

## Inputs

- `package-manager` (default: `bun`) — Package manager to use (bun|npm|pnpm|yarn)
- `working-directory` (default: `.`) — Working directory for running commands
- `generate-command` (default: `bun contractspec generate`) — Command to regenerate artifacts
- `on-drift` (default: `fail`) — Behavior when drift is detected (fail|issue|pr)
- `drift-paths-allowlist` — Comma-separated glob patterns to check for drift
- `token` (default: `${{ github.token }}`) — GitHub token for issues/PRs
- `github-packages-token` — Optional token used to configure private GitHub Packages auth before dependency installs

## Outputs

- `drift-detected` — Whether drift was detected

## Key Files

- `action.yml` — GitHub Action definition
- `fixtures/` — Test report data for drift scenarios

## Local Commands

- `bun run test` — bun test

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Stability
- Stability improvements

## Notes

- Do not change `action.yml` inputs/outputs without updating downstream workflow consumers
- Fixture JSON files are used for CI testing — keep them valid


---

## @lssm-tech/app.action-pr

Description: GitHub Action for ContractSpec PR checks
Path: packages/apps/action-pr
URL: /llms/app.action-pr

# @lssm-tech/action.pr

Website: https://contractspec.io

**GitHub Action that runs ContractSpec validation checks on pull requests. Posts drift reports, validation results, and product views as PR comments.**

## What It Does

- Uses `@lssm-tech/lib.contracts-spec` for contract definitions
- Uses `@lssm-tech/bundle.workspace` for workspace analysis
- Configured via `action.yml`; no `src/` — logic lives in workspace bundle

## Usage

```yaml
name: ContractSpec PR
on: pull_request
jobs:
  contractspec:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: lssm-tech/contractspec/packages/apps/action-pr@main
        with:
          github-packages-token: ${{ secrets.CONTRACTSPEC_PACKAGES_TOKEN }}
          generate-command: 'bun contractspec generate'
```

For private GitHub Packages access, `github-packages-token` must be a GitHub token that can read the ContractSpec packages granted to the consuming repository, bot, or GitHub App.

## Inputs

- `package-manager` (default: `bun`) — Package manager to use (bun|npm|pnpm|yarn)
- `working-directory` (default: `.`) — Working directory for running commands
- `report-mode` (default: `summary`) — Report output mode (summary|comment|both|off)
- `enable-drift` (default: `true`) — Run drift detection after generate
- `fail-on` (default: `any`) — Fail on breaking, drift, any, or never
- `generate-command` (default: `bun contractspec generate`) — Command to regenerate artifacts (required when enable-drift=true)
- `validate-command` — Override validation command
- `contracts-dir` — Directory containing contract specs
- `contracts-glob` — Glob pattern for contract specs
- `token` (default: `${{ github.token }}`) — GitHub token for PR comments
- `github-packages-token` — Optional token used to configure private GitHub Packages auth before dependency installs

## Outputs

- `drift-detected` — Whether drift was detected
- `breaking-change-detected` — Whether breaking changes were detected
- `validation-failed` — Whether validation failed

## Key Files

- `action.yml` — GitHub Action definition
- `fixtures/` — Test report data and validation fixtures
- `.contractspec-ci/contracts.json` — CI contract configuration

## Local Commands

- `bun run test` — bun test

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Stability
- Standardize tool naming to underscore notation

## Notes

- Do not change `action.yml` inputs/outputs without updating downstream workflow consumers
- Fixture files are used for CI testing — keep them valid


---

## @lssm-tech/action.validation

Description: GitHub Action for running ContractSpec CI checks
Path: packages/apps/action-validation
URL: /llms/action.validation

# @lssm-tech/action.validation

Website: https://contractspec.io

**ContractSpec GitHub Action for CI/CD integration. Wraps the `contractspec ci` CLI command as a composite action.**

## What It Does

- **Layer**: app (GitHub Action)
- **Consumers**: external CI/CD pipelines via `lssm/contractspec-action@v1`

## Usage

```yaml
name: ContractSpec CI
on: pull_request
jobs:
  contractspec:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
    steps:
      - uses: actions/checkout@v6
      - uses: lssm-tech/contractspec/packages/apps/action-validation@main
        with:
          github-packages-token: ${{ secrets.CONTRACTSPEC_PACKAGES_TOKEN }}
```

For private GitHub Packages access, `github-packages-token` must be a GitHub token that can read the ContractSpec packages granted to the consuming repository, bot, or GitHub App.

## Inputs

- `checks` (default: `all`) — Checks to run (comma-separated: structure,integrity,deps,doctor,handlers,tests) or "all"
- `skip` — Checks to skip (comma-separated)
- `pattern` — Glob pattern for spec discovery
- `fail-on-warnings` (default: `false`) — Fail the action on warnings (not just errors)
- `check-handlers` (default: `false`) — Include handler implementation checks
- `check-tests` (default: `false`) — Include test coverage checks
- `upload-sarif` (default: `true`) — Upload SARIF results to GitHub Code Scanning
- `working-directory` (default: `.`) — Working directory for running checks
- `bun-version` (default: `latest`) — Bun version to use
- `mode` (default: `validate`) — Action mode: "validate" (run checks) or "impact" (detect breaking changes)
- `baseline` — Git ref to compare against for impact detection (default: base branch from PR context)
- `pr-comment` (default: `true`) — Post impact results as PR comment
- `github-token` (default: `${{ github.token }}`) — GitHub token for PR comments and check runs
- `github-packages-token` — Optional token used to configure private GitHub Packages auth before dependency installs

## Outputs

- `success` — Whether all checks passed
- `errors` — Number of errors found
- `warnings` — Number of warnings found
- `sarif-file` — Path to SARIF output file (if uploaded)
- `json-file` — Path to JSON output file
- `impact-status` — Impact status: "no-impact" | "non-breaking" | "breaking"
- `breaking-count` — Number of breaking changes detected
- `non-breaking-count` — Number of non-breaking changes detected

## Key Files

- `action.yml` — GitHub Action definition (composite action)
- `README.md` — Usage documentation
- `package.json` — Package metadata (private, not published to npm)

## Local Commands

- `bun run test` — bun test

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Stability
- PublishConfig not supported by bun

## Notes

- All input/output changes must be reflected in both `action.yml` and `README.md`.
- The action is versioned with tags on the repository — breaking input changes require a major version bump.
- Test locally using `act` or by referencing the local action: `uses: ./packages/apps/action-validation`.


---

## @lssm-tech/action.version

Description: GitHub Action for ContractSpec version management
Path: packages/apps/action-version
URL: /llms/action.version

# @lssm-tech/action.version

Website: https://contractspec.io

**GitHub Action for automated ContractSpec version management in CI.**

## What It Does

- Standalone action with no workspace dependencies
- Configured entirely via `action.yml`; no TypeScript source

## Usage

```yaml
name: ContractSpec Version Manager
on: pull_request
jobs:
  contractspec:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: lssm-tech/contractspec/packages/apps/action-version@main
        with:
          github-packages-token: ${{ secrets.CONTRACTSPEC_PACKAGES_TOKEN }}
```

For private GitHub Packages access, `github-packages-token` must be a GitHub token that can read the ContractSpec packages granted to the consuming repository, bot, or GitHub App.

## Inputs

- `mode` (default: `analyze`) — Action mode: analyze (check only) or bump (apply changes)
- `auto-bump` (default: `false`) — Whether to automatically applying bumps based on impact analysis
- `commit-message` (default: `chore(release): bump spec versions [skip ci]`) — Commit message for version bumps
- `create-pr` (default: `false`) — Create a Pull Request instead of pushing directly
- `pr-title` (default: `chore(release): version packages`) — Title for the Pull Request
- `pr-branch` (default: `release/next-versions`) — Branch name for the Pull Request
- `github-token` (default: `${{ github.token }}`) — GitHub Token for creating PRs
- `github-packages-token` — Optional token used to configure private GitHub Packages auth before dependency installs

## Outputs

- `has-changes` — Whether changes were detected/applied
- `specs-bumped` — Number of specs bumped

## Key Files

- `action.yml` — GitHub Action definition (entry point)

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- PublishConfig not supported by bun
- Move automation into actions

## Notes

- Do not change `action.yml` inputs/outputs without updating downstream workflow consumers
- This is a standalone action — avoid adding workspace dependencies unless necessary


---

## @lssm-tech/app.alpic-mcp

Description: (none)
Path: packages/apps/alpic-mcp
URL: /llms/app.alpic-mcp

# @lssm-tech/app.alpic-mcp

Website: https://contractspec.io

**MCP (Model Context Protocol) server for Alpic. Exposes ContractSpec documentation and tooling to AI agents via the MCP standard.**

## What It Does

- Uses `@lssm-tech/bundle.alpic` for Alpic business logic.
- Uses `@lssm-tech/lib.logger` for structured logging.
- Built with tsdown; runs as a Node.js server.
- Related ContractSpec packages include `@lssm-tech/bundle.alpic`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.tsdown`, `@lssm-tech/tool.typescript`.

## Running Locally

From `packages/apps/alpic-mcp`:
- `bun run dev`
- `bun run start`
- `bun run build`

## Usage

```bash
bun run dev
```

## Architecture

- Uses `@lssm-tech/bundle.alpic` for Alpic business logic.
- Uses `@lssm-tech/lib.logger` for structured logging.
- Built with tsdown; runs as a Node.js server.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/server.ts` is the main server bootstrap entrypoint.

## Public Entry Points

- Export `.` resolves through `./dist/index.mjs`.
- Export `./server` resolves through `./dist/server.mjs`.
- Export `./*` resolves through `./*`.

## Local Commands

- `bun run dev` — tsdown --watch
- `bun run start` — node dist/server.js
- `bun run build` — tsdown && mkdir -p dist && cp -R assets dist/assets
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- MCP protocol compliance is critical — do not break tool/resource schemas.
- Keep server startup fast; defer heavy initialization.


---

## @lssm-tech/app.api-application-monolith

Description: (none)
Path: packages/apps/api-application-monolith
URL: /llms/app.api-application-monolith

# Managed CompanyOS API Application Monolith

Real API monolith for tenant-scoped Managed CompanyOS commands and queries.

> **api-monolith-elysia-convergence:** this app is now verified as a single **Elysia host** (`src/app.ts` + `api/index.js` `@vercel/node` entry). Former Next.js App Router handlers have been removed from `src/app/api`; route tests exercise `app.handle(Request)` directly. The `vercel.json` deploy flip and external webhook re-registration remain human-gated, but source ownership, tests, and local builds are Elysia-owned. Build the host with `bun run build:elysia`.

The handlers are deterministic and side-effect-free until production storage and queue adapters are explicitly approved. Provider strategy is implemented in the app production layer with secret-manager references only; bundle/libs/modules remain provider-neutral.

## Runtime surface

- `src/app.ts` — authoritative Elysia host composition for `/api/auth/*`, `/api/companyos/*`, `/api/companyos/builder/*`, webhooks, crons, schemas, control-plane, billing, and waitlist routes.
- `api/index.js` — Vercel Node adapter from `(req, res)` to Web `Request` to `app.handle(request)`.
- `src/handlers/auth-handler.ts` — better-auth catch-all with readiness gates, observability, and credentialed CORS.
- `src/handlers/companyos/companyos-status-handler.ts` — tenant-scoped Managed CompanyOS read routes (`health`, `database`, `evidence`, `providers`, `integrations`, `replay`, `workflow`, `workspace`, `surface`, `health/degraded`).
- `src/handlers/companyos/companyos-command-handler.ts` — verified-session command routes (`integrations/setup`, `workflow/approve`).
- `src/handlers/companyos-auth-*.ts` — invitation, lockout, passkey, sign-out, test-login, and sibling-session revoke routes.
- `src/handlers/companyos/*special-ops*.ts` — Special Ops and AI Ops Sprint scoped route families.
- `src/handlers/builder/builder-public-handler.ts` — public Builder REST surface at `/api/companyos/builder/*`, distinct from agent/workflow.
- `src/index.ts` — pure command/query functions shared by Elysia handlers and unit tests.

## Special Ops database-first cutover

Use [`docs/runbooks/special-ops-monolith-production.md`](../../../docs/runbooks/special-ops-monolith-production.md) for the NDconsulting/Special Ops seed, tenant/workspace isolation, capability graph, AI Ops Sprint, and all-in-one work-graph promotion gates. Until the approved DB repository lane lands, the API must describe `/api/companyos/database`, `/api/companyos/workspace`, and `/api/companyos/surface/special-ops` as deterministic proof paths rather than live customer-data seed execution.

## Production prerequisites

The following items must be resolved before this app is promoted to production with real-tenant data. They are deliberate deferrals during the deterministic-fixture phase.

| Prerequisite | Status | Detail |
|---|---|---|
| **JWT/session middleware for tenant identity** | ✅ **IMPLEMENTED** | All routes now derive `requestTenantId` from a verified HMAC-HS256 session token (`x-managed-companyos-session` header) via `src/middleware/session.ts`. Invalid or tampered tokens return 401. Set `MANAGED_COMPANYOS_SESSION_SECRET` to a strong secret before admitting real-tenant data. |
| **Persistent storage adapter** | ✅ **IMPLEMENTED FOR MANAGED COMPANYOS TABLES** | App-owned Drizzle/local lifecycle paths use canonical `managed_companyos_*` tables for tenant, session, invitation, passkey, lockout, audit, replay/evidence, capability, and mutation-ledger state. External production DB access remains URL-gated; live credentials are not committed. |
| **Production queue** | Approval-gated | Background job logic is in-process. A durable queue must be approved and wired before live workloads. |
| **Provider strategy** | ✅ **IMPLEMENTED APP-LAYER REFERENCE CATALOG** | `src/production/providers.ts` exposes an executable provider-neutral catalog and dispatch adapter for managed-reference and BYOK-reference modes. The wider provider family matrix remains a readiness/runbook contract until each family has app/provider-layer smoke evidence. Dispatch accepts env-backed redacted reference aliases only and fails closed before the harness when refs are missing, raw-looking, or not redacted. |

Do not promote to production until all prerequisites above have explicit approval artifacts and implementation sign-off. See the consolidated operator runbook at `docs/runbooks/managed-companyos.md` for the full prerequisite list.

## Local commands

```bash
bun run --cwd packages/apps/api-application-monolith dev
bun run --cwd packages/apps/api-application-monolith test
bun run --cwd packages/apps/api-application-monolith typecheck
bun run --cwd packages/apps/api-application-monolith lint:check
bun run --cwd packages/apps/api-application-monolith build
bun run --cwd packages/apps/api-application-monolith companyos:db:migrate:test
bun run --cwd packages/apps/api-application-monolith companyos:db:seed:test
bun run --cwd packages/apps/api-application-monolith companyos:db:verify:test
bun run --cwd packages/apps/api-application-monolith companyos:db:prove-rls:test
```

## Managed Builder public REST surface

The Elysia host exposes Builder operations at `/api/companyos/builder/*` as a
tenant-scoped Builder surface distinct from agent/workflow. The public handler
uses AuthOS/control-plane service-principal authorization, rejects raw-looking
provider or webhook credentials, and reuses the Builder runtime resources that
select DB-backed storage by default (or `BUILDER_RUNTIME_STORAGE=memory` for
tests). Key route families include sessions, sources, intents, spec packs, plan
compile/tasks, provider preflight, executions, webhooks, readiness, previews,
releases, replay, evidence, analytics, and improvements.

Provider/webhook activation stays fail-closed unless callers pass approved
typed refs such as `provider_ref:*` and `webhook_ref:*`; raw `sk-*`,
`whsec_*`, GitHub, Slack, or long secret-looking values return 422.

## Auth, DB lifecycle, and RLS closure

The API monolith owns the executable Managed CompanyOS auth/database/RLS slice:

- Session authority is request-derived from the `managed_companyos_session` cookie or the test-only `x-managed-companyos-session` header; invalid, missing, revoked, expired, or tenant-mismatched sessions fail closed.
- Auth lifecycle state is exposed through API-local invitation, passkey, lockout, sign-out, and governed session-revoke routes. Invitation and passkey routes return refs only; raw passwords, public keys, provider tokens, and secret-manager URIs are rejected or kept out of responses. The seeded `/api/companyos/auth/test-login` helper is disabled outside test mode unless `MANAGED_COMPANYOS_ENABLE_TEST_LOGIN=1` is set.
- The app Drizzle schema, migrations, local lifecycle, seed manifest, and mutation repository use canonical `managed_companyos_*` table names, including `managed_companyos_invitations`, `managed_companyos_passkeys`, `managed_companyos_passkey_challenges`, `managed_companyos_auth_lockouts`, and `managed_companyos_mutation_ledger`.
- Drizzle schema code is the canonical source for feasible owned tenant RLS metadata. `src/db/schema.ts` attaches `pgPolicy` tenant-isolation policies to tenant-scoped Drizzle tables, while `src/db/rls-policy-inventory.ts` records executable SQL parity expectations, schema-only classifications, runtime descriptor fallback, platform exceptions, and the current Drizzle 0.x version gate (`pgPolicy` only; no `pgTable.withRLS`).
- Checked-in SQL migrations remain the executable artifacts. Before changing policy names, roles, `USING`, `WITH CHECK`, `ENABLE`, or `FORCE` semantics, run the ContractSpec Connect gate and the static parity tests; treat any table/policy/role SQL drift as compatibility-impacting unless explicitly classified in the plan/evidence bundle.
- Local/test DB lifecycle commands require `MANAGED_COMPANYOS_TEST_DATABASE_URL` or `LSSM_STUDIO_TEST_DATABASE_URL` and refuse production-like targets. Auth lifecycle repository fallback to memory is test-only unless `MANAGED_COMPANYOS_ENABLE_MEMORY_AUTH_REPOSITORY=1` is explicitly set. When `AUTH_PROVIDER_MODE=better-auth`, the catch-all better-auth route also fails closed unless one of `MANAGED_COMPANYOS_AUTH_DATABASE_URL`, `MANAGED_COMPANYOS_TEST_DATABASE_URL`, `LSSM_STUDIO_TEST_DATABASE_URL`, or `LSSM_STUDIO_DATABASE_URL` is configured, preventing accidental in-memory auth fallback in production mode.
- `companyos:db:prove-rls:test` verifies forced RLS metadata and SQL tenant-denial behavior when a permitted local/test DB URL exists. The proof provisions `managed_companyos_rls_proof_app`, queries `pg_roles`, and fails unless that role is `rolsuper=false` and `rolbypassrls=false`; tenant-denial assertions never run on a superuser or BYPASSRLS role. If no permitted URL is present, report the live proof as not run rather than passed.

### AuthOS identity provider & identity-rbac authority

When `AUTH_PROVIDER_MODE=better-auth`, the API serves a real AuthOS identity provider through the `@lssm-tech/integration.authos-better-auth` bridge (`src/auth/better-auth-setup.ts`). The runtime-backed login surface is: email+password (credential), email-OTP, magic-link, generic OAuth (Google + Microsoft via OIDC discovery), `admin`, `organization`/`team`, two-factor (TOTP + recovery codes), and `bearer` (native-mobile token auth). Public self-signup is disabled (invite-only); email verification is required.

- **Single-session-authority.** Every credential path AND every enabled plugin funnels through one `finalizeAuthenticatedSession` seam (`src/auth/active-org-hook.ts`, wired as the better-auth `session.create` hook). It enforces exactly one authoritative session and stamps `activeOrganizationId` uniformly — redirect flows (magic-link/OAuth) have no client hook, so a per-method approach would miss them. No membership → left unset → the web layout fails closed to `/login`.
- **Fail-closed plugin config.** A capability marked `runtime-backed` in the spec without a real runtime-wired better-auth plugin throws at setup (`assertEnabledPluginRuntimeWiring` in `src/auth/plugin-config-guard.ts`) instead of silently no-opping.
- **identity-rbac is the live role/permission authority.** The frozen operator role (`ManagedCompanyOsRole`, single-sourced from `@lssm-tech/bundle.managed-companyos`) carried on each better-auth session maps to an exact, least-privilege identity-rbac permission set via the golden table in `src/middleware/companyos-role-permissions.ts`. `src/middleware/companyos-subject.ts` wraps `createSubjectProvider` (`@lssm-tech/lib.authos-runtime`) into the governance `Subject`, and `src/middleware/authorization.ts` attaches the resolved permission set to user actors. Control-plane/builder capability gating remains a SEPARATE axis (users still 403 on machine-only routes — parity preserved); identity-rbac permissions never over-grant control-plane access.
- **401 vs 503 (retryable RBAC distinction).** No session → **401**. A *valid* session whose identity-rbac resolution fails (store transiently unavailable / unmapped role) → **503** with an `auth.rbac.unavailable` signal (hashed tenant, no PII/tokens), NEVER the 401 reserved for "no session".

Deferred AuthOS capabilities (honest, contract-only with reasons — never marked runtime-backed):

- `passkey` (WebAuthn): better-auth 1.6.15 ships no passkey plugin; requires `@simplewebauthn` + cross-package dep wiring — deferred to its own wave. (The app-local `managed_companyos_passkeys` ref routes above are a separate deterministic proof-path, not the better-auth WebAuthn plugin.)
- `sso` / `saml` and `scim`: modeled as `external:*` bridge declarations (`runtimeWired: false`); ADR follow-ups pending real `@better-auth/sso` / `@better-auth/scim` wiring.
- `audit`: no better-auth audit plugin; audit-event listing is deferred to the admin/observability surface (adapter method stays unsupported with a written rationale).
- `connect-lssm-account-link`: the LSSM IdP (`oidc-provider`) is gated on `enableLssmIdp` + a security-review ref, neither configured in v1.

Live DB operation checklist:

1. Record the ContractSpec Connect gate/evidence for the migration/RLS decision.
2. Use an explicit target URL and redact it in logs.
3. Confirm the target is local/test, or attach a separately approved live-target, backup, rollback, and review artifact before any destructive/shared operation.
4. Run static parity first: `bun test --cwd packages/apps/api-application-monolith src/db/schema.test.ts src/db/rls-policy-inventory.test.ts src/db/rls-proof.test.ts`.
5. Run DB-gated migrate/seed/verify/prove commands only when the URL is permitted.
6. Report skipped or blocked DB proof as **not run**, never as passed.

## Integration Points

### REST API Integration

External systems integrate with Managed CompanyOS via REST routes:

```bash
# Workspace projection (workflow state, integrations, replay packets)
curl -H "x-managed-companyos-session: <HMAC-signed-token>" \
  https://api.host/api/companyos/workspace

# Evidence verification (audit proof)
curl -H "x-managed-companyos-session: <token>" \
  https://api.host/api/companyos/evidence?correlationId=corr_xyz

# Health check
curl https://api.host/api/companyos/health

# Degraded health (returns 503 if worker/WebSocket unhealthy)
curl https://api.host/api/companyos/health/degraded
```

All tenant-scoped queries derive `tenantId` from the verified session token. Cross-tenant access is rejected with 403.

### MCP (Model Context Protocol) Integration

For AI agents and CLI tools, use the planned `@lssm-tech/app.managed-companyos-mcp` server (see `.omx/audits/mcos-mcp-design-20260515.md` for design).

MCP tools expose the same operations as the REST API but with additional:
- Tool context factory for tenant/actor/policy decisions
- Resource URIs for replay packets, evidence receipts, and health snapshots
- Prompts for copilot-style operator guidance

### WebSocket Integration

For real-time UI updates, web browsers connect to the worker app's `/ws` endpoint:

```typescript
const ws = new WebSocket('ws://worker.host/ws?tenantId=tenant_id');
ws.onmessage = (event) => {
  const message = JSON.parse(event.data); // ManagedCompanyOsWebSocketMessage
  // message.type === 'managed-companyos.graph.snapshot'
  // message.correlationId links jobs + replay + evidence
};
```

See worker app README for full WebSocket message schema and event projection.

## Managed CompanyOS environment

Copy `deploy/env/api.env.example` into the deployment secret-manager backed environment group. Keep raw provider credentials out of committed files; production provider defaults remain approval-gated.

| Variable | Purpose |
| --- | --- |
| `MANAGED_COMPANYOS_STATE_FILE` | Optional durable state file for provider-neutral production-store previews. |
| `MANAGED_COMPANYOS_WORKER_BASE_URL` | Worker runtime base URL for degraded-health and operator runbook probes. |
| `MANAGED_COMPANYOS_WORKER_HOST` | Worker host used by deployment/runbook checks. |
| `MANAGED_COMPANYOS_WORKER_PORT` | Worker HTTP/WebSocket port. |
| `MANAGED_COMPANYOS_SESSION_SECRET` | **Required in production.** HMAC-HS256 signing secret for `x-managed-companyos-session` tokens. Must be a strong random value (≥32 bytes). Never commit to source control. |
| `MANAGED_COMPANYOS_DEFAULT_TENANT_ID` | Fixture-phase fallback tenant used when no session header is present and no `?tenantId=` param is supplied. |
| `MANAGED_COMPANYOS_REMOTE_CONFIG_URL` | **Required.** Signed tenant remote-config manifest URL for feature flags, runtime endpoints, and kill switches. Use `https://…` in deployment or `managed-companyos://fixture/<tenant>` in deterministic tests. |
| `MANAGED_COMPANYOS_REMOTE_CONFIG_SIGNING_KEY_REF` | **Required.** Redacted key reference for remote-config manifest verification. Never commit raw signing material. |
| `MANAGED_COMPANYOS_PROVIDER_APPROVAL_REQUIRED` | Must remain `true` until explicit provider approval exists. |
| `MANAGED_COMPANYOS_MANAGED_REFERENCE_CREDENTIAL_REF` | Platform-managed reference-provider credential alias for the executable provider-neutral catalog. The value must be a redacted reference label/alias, not a raw key, webhook URL, bearer token, or secret-manager URI. |
| `MANAGED_COMPANYOS_BYOK_REFERENCE_CREDENTIAL_REF` | Tenant-owned BYOK reference-provider credential alias for the executable provider-neutral catalog. The app stores and returns only redacted metadata. |
| `MANAGED_COMPANYOS_MANAGED_<PROVIDER>_CREDENTIAL_REF` / `MANAGED_COMPANYOS_BYOK_<PROVIDER>_CREDENTIAL_REF` | Future provider-family env names for approved app/provider-layer adapters. Keep values in the deployment secret manager and pass only redacted aliases/metadata through API responses, logs, tests, and evidence. |


### Provider strategy matrix

The executable app-layer provider catalog currently includes:

- `managed-reference` → `reference-managed-channel`, configured by `MANAGED_COMPANYOS_MANAGED_REFERENCE_CREDENTIAL_REF`.
- `byok-reference` → `reference-byok-channel`, configured by `MANAGED_COMPANYOS_BYOK_REFERENCE_CREDENTIAL_REF`.

Both entries expose redacted metadata only (`********`) and dispatch through an injected/provider-neutral harness. Missing env refs, raw-looking values (`sk-*`, `xox*`, bearer tokens, URLs/URIs, or oversized values), unknown provider ids, and unconfigured catalog entries fail closed before dispatch.

The broader provider family matrix is documented in `docs/runbooks/managed-companyos.md` and `specs/companyos-managed-readiness.md` as catalog/readiness intent, not blanket live-dispatch approval. Concrete SDK imports/defaults remain confined to app/integration/provider layers; lower bundles/libs/modules must stay provider-neutral.


---

## @lssm-tech/app.api-library

Description: (none)
Path: packages/apps/api-library
URL: /llms/app.api-library

# @lssm-tech/app.api-library

**Library API server for ContractSpec documentation and templates. Thin HTTP layer over `bundle.library`.**

> Hosted MCP endpoints were previously removed (zero hosted MCP compute; MCP ships locally via `contractspec mcp`). As of the api-monolith-elysia-convergence, the **builder, channel/control-plane, dispatch, schema, and in-process scheduler hosting has been converged into `@lssm-tech/app.api-application-monolith`** (the managed CompanyOS Elysia host). This server now serves ONLY:
>
> - `/mdx/*` markdown (the deliberate survivor, backed by `bundle.marketing`), and
> - the provider webhook ingress (Slack/Telegram/GitHub/WhatsApp), kept LIVE in parallel until the provider webhook URLs are repointed to the monolith host (human-gated). The webhook routes are stripped in a follow-up after repoint is confirmed.
>
> The Vercel project (`contractspec-library-api`) is retained for markdown + the gated webhook survivor.

## What It Does

- Markdown + webhook survivor — a thin HTTP layer; business logic lives in `bundle.library` / `bundle.marketing`.
- `src/handlers/` retains: `markdown-handler`, the 4 webhook handlers, and the channel/builder runtime resources the webhooks ingest through.
- Control-plane / channel dispatch / builder / schema endpoints are no longer served here — see `@lssm-tech/app.api-application-monolith`.
- Related ContractSpec packages include `@lssm-tech/bundle.library`, `@lssm-tech/bundle.marketing`, `@lssm-tech/bundle.workspace`, `@lssm-tech/integration.provider-messaging`, `@lssm-tech/integration.runtime`, `@lssm-tech/lib.contracts-spec`, ...
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/apps/api-library`:
- `bun run dev`
- `bun run start`
- `bun run build`

## Usage

```bash
bun run dev
```

## Architecture

- This app is a thin HTTP layer — all business logic lives in `bundle.library`.
- Elysia server exposing GraphQL, webhooks, control-plane, and channel handlers (no MCP endpoints).
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- This package is a deployable application rather than a library with published subpath exports.

## Local Commands

- `bun run dev` — bun run --watch src/index.ts
- `bun run start` — bun run ./dist/index.js
- `bun run build` — bun run build:types && bun run build:bundle
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run clean` — rm -rf dist api/dist
- `bun run build:bundle` — bun build --target node --packages bundle --outfile dist/index.js src/index.ts && mkdir -p api/dist && cp dist/index.js api/dist/index.js
- `bun run build:types` — tsc -p ./tsconfig.json --noEmit
- `bun run postinstall` — if [ "$VERCEL" = "1" ]; then bun run build:bundle; fi

## Recent Updates

- Removed the hosted MCP endpoints (docs/cli/internal/contracts); MCP now ships locally via `contractspec mcp`.
- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Expose contract management via CLI and MCP.
- Stabilize lint gate and runtime contract typing.
- Add ai-native messaging channel runtime.
- Inline server into index.ts and add Vercel configs.

## Notes

- Keep this app thin — no business logic here; delegate to `bundle.library`.
- MCP is no longer hosted here; agents/editors must use the local `contractspec mcp` stdio servers. The reusable MCP builders still live in `bundle.library` (`createDocsMcpHandler` remains used by `app.web-landing`).
- API route changes require coordinating with `app.web-landing` and any external clients.


---

## @lssm-tech/app.cli-contractspec

Description: CLI tool for creating, building, and validating contract specifications
Path: packages/apps/cli-contractspec
URL: /llms/app.cli-contractspec

# @lssm-tech/app.cli-contractspec

Website: https://contractspec.io

**CLI tool for authoring, materializing, and validating ContractSpec targets.**

## What It Does

- **Commands** (`src/commands/`) - Thin wrappers that call bundle services.
- **Prompts** (`src/commands/create/wizards/`) - Interactive UI using `@inquirer/prompts`.
- **CLI setup** (`src/index.ts`, `src/cli.ts`) - Commander.js configuration.
- **Types** (`src/types.ts`) - CLI-specific types.
- **Services** (`@lssm-tech/bundle.workspace/services/`) - Core use-cases.
- `create.ts` - Authored target creation logic.
- `build.ts` - Runtime/package materialization from authored targets.
- `openapi.ts` - OpenAPI export.

## Running Locally

From `packages/apps/cli-contractspec`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

```bash
bun run dev
```

## Recommended OSS Onboarding

```bash
contractspec onboard
contractspec onboard knowledge --example knowledge-canon
contractspec init --preset connect
contractspec validate
```

## Discover capabilities ("can it help?")

Ask whether ContractSpec already provides a capability — or whether your repo
already has one — before building it yourself. Fully offline, no model required.

```bash
contractspec can-help "render a data table from a contract"
contractspec ask "capture an invoice from a customer" --scope local
contractspec can-help "send a transactional email" --json --family integrations
```

Returns a `have-it` / `can-help` / `gap` verdict over a two-tier corpus (the
shipped ContractSpec + ecosystem adoption catalog plus a local overlay of your
own surfaces), with the canonical surface to adopt and a confidence score.
`--scope` accepts `all` (default), `local`, or `ecosystem`.

The same query is exposed to agents as the offline MCP tool `contractspec.can_help`
(served by `contractspec mcp`).

### Enforce reuse (Connect ladder)

```bash
# Graduated verdict: permit(0) / rewrite(10) / require_review(20) / deny(30)
contractspec connect leverage --intent "build a multi-agent AI chat surface"

# Opt-in hard-deny at high confidence; bypass with a recorded override
contractspec connect leverage --intent "..." --deny --override "need a bespoke variant" --actor you
```

`deny` is opt-in and high-confidence only; an `--override` justification is
persisted to `.contractspec/connect/leverage-overrides.json` as audit evidence.

### Leverage-gap report & catalog freshness (CI)

```bash
contractspec can-help report                 # where this repo reinvented existing capabilities
contractspec can-help catalog --snapshot capability-catalog.json
contractspec can-help catalog --check capability-catalog.json   # exit 1 if stale (CI gate)
```

## Core Authoring/Build Model

- `create` authors both runtime specs and package-oriented targets such as `module-bundle`, `builder-spec`, and `provider-spec`.
- `build` materializes one authored target into runtime artifacts or package scaffolds.
- `generate` runs workspace-wide generation for docs and derived artifacts.
- `validate` checks authored targets, package scaffolds, and optional runtime implementations.
- `onboard` generates repo-local AGENTS/USAGE guidance, recommends examples, and aligns users to the right ContractSpec track.


## Model Context Protocol (MCP) servers

The CLI ships two local, offline-first MCP servers over stdio. They replace the
previously hosted `api.contractspec.io` MCP endpoints (docs/cli/internal/contracts),
which have been **removed** — point your editor/agent at the local commands below.

```bash
# Knowledge + author tools (default). Offline, zero setup, no network.
contractspec mcp

# Runtime projection of THIS repo's own contracts (opt-in, fail-closed).
contractspec mcp --runtime

# Operate against a different working directory:
contractspec mcp --cwd /path/to/project
```

- **`contractspec mcp` (knowledge + author tools)** — fully offline. Exposes docs
  search/get/resolve-route/contract-reference/facets, CLI usage/suggest, the internal
  endpoint catalog, examples browsing, and author tools over the consumer's `cwd`:
  `contracts.list/get/validate/build/update/delete` plus the new **`contracts.create`**
  spec scaffold. The knowledge corpus is generated at build time from the docblock
  manifest + docs registry + example metadata (plus a small curated getting-started/patterns
  overlay) and bundled into the published package, so it works with **no network and no setup**.
- **`contractspec mcp --runtime` (runtime projection)** — opt-in. Discovers and loads the
  consumer's own `OperationSpecRegistry` and projects it as MCP tools. It is **fail-closed**:
  - Projects **only handler-backed operations** (spec-only ops are never surfaced).
  - **Read-only queries are allowed; every write/command is DENIED by default** (destructive
    and `admin` operations included). Permit specific writes by name via `.contractsrc.json`.
  - On no registry / zero bound ops / load failure it prints a clear error to stderr, exits
    non-zero, and registers nothing.

### Security notes

- **Author server has no policy gate (scope to trusted workspaces).** `contractspec mcp`
  (the default knowledge + author server) exposes write tools — `contracts.create`,
  `contracts.update`, `contracts.delete`, and `contracts.build` — that create, modify,
  delete, and generate spec files in the working directory. There is no per-tool policy
  check on this server, so only run it against a workspace you trust the connected agent
  to modify (and prefer `--cwd` to scope it explicitly).
- **`--runtime` handlers run as `actor: 'anonymous'`.** Every operation projected by the
  runtime server is executed with an anonymous actor context. Consumers MUST NOT treat
  `anonymous` as an elevated or privileged identity inside their handlers; gate any
  sensitive behavior on explicit policy, not on the absence of an actor.

### `.contractsrc.json` `mcp.runtime` keys (runtime server)

```jsonc
{
  "mcp": {
    "runtime": {
      // Path to a module exporting an OperationSpecRegistry (named `registry`/
      // `operations`/`ops`, or default). Overrides convention-based discovery.
      "registry": "dist/registry.js",
      // Operation keys allowed to be projected as writable tools (opt-in).
      "allowWrites": ["project.create"]
    }
  }
}
```

When `mcp.runtime.registry` is omitted, the server resolves candidate registry modules from
the contractsrc `operations` layout (and common defaults like `operations/`, `src/operations/`).
**v1 limitation:** the `mcp.runtime` block is read directly (not yet part of the typed
`contractsrc.schema.json`), so editor schema autocomplete is not available for these keys.

### Editor wiring (`mcp.json` / settings)

```json
"contractspec": { "command": "npx", "args": ["-y", "@lssm-tech/app.cli-contractspec", "mcp"], "env": {} },
"contractspec-runtime": { "command": "npx", "args": ["-y", "@lssm-tech/app.cli-contractspec", "mcp", "--runtime"], "env": {} }
```

> Migration from the removed hosted MCP: replace the old `api.contractspec.io` MCP entries in
> your `mcp.json` (or `.claude`/`.cursor`/`.zed` config) with the two stdio entries above. Zed
> entries also need `"type": "stdio"`. All MCP logging goes to **stderr**; stdout is the JSON-RPC channel.

## Help and command discovery

`contractspec --help` is the canonical public command index. It groups root commands by category and includes implemented public command families such as `intelligence`, `connect`, `release`, and `changelog`. Subcommand help uses the same grouped renderer, so `contractspec intelligence --help` and `contractspec connect --help` preserve clean descriptions and category headings instead of falling back to an unstructured command list.


## Release capsule guardrails

Prefer guided release authoring over raw YAML edits:

```bash
contractspec release prepare --baseline main
contractspec release edit <slug>
contractspec release fix <slug> --write
contractspec release check --strict --baseline main
```

`contractspec connect hook release-capsule after-file-edit --stdin` validates `.changeset/*.release.yaml` and paired `.changeset/*.md` edits without mutating files. When malformed YAML is recoverable, `contractspec release fix <slug> --write` rewrites the canonical `.release.yaml` and preserves unsupported fields in `.changeset/<slug>.release.quarantine.yaml`; the default dry-run previews issues and exits non-zero while invalid capsules remain.

## Generative Core Preview Commands

Generative Core commands are thin CLI wrappers over workspace/bundle services. They expose graph and regeneration evidence without bypassing Connect review gates:

- `contractspec graph inspect --json` reads authored contracts and workspace evidence and reports schema-versioned counts, diagnostics, and artifact paths.
- `contractspec graph export --json` writes only canonical graph artifacts under `generated/contractspec/graphs/**` after deterministic artifact metadata is available.
- `contractspec drift check --json` classifies contract, code, generated artifact, docs, tests, and downstream-consumer drift for advisory CI before strict gates.
- `contractspec generate plan --dry-run --json` produces planned writes and provenance hashes without mutating files.
- `contractspec generate apply --json` and future repair apply flows require `contractspec connect verify` to allow or review the protected/generated write.


## Shell Completion

Install the package so the `contractspec` executable is available on your `PATH`, then choose one of the supported shells:

```bash
contractspec completion script bash
contractspec completion script zsh
contractspec completion script fish
```

For managed installation, write the completion file and optionally patch the shell profile:

```bash
contractspec completion install bash
contractspec completion install zsh --write-profile
contractspec completion install fish
```

`completion install` always writes the generated completion script to a managed user config path. By default it does not edit startup files in non-interactive sessions. Use `--write-profile` to append an idempotent `source` block automatically.

## Initialization Presets

`contractspec init` is now preset-driven. The shared setup layer owns the flow, and the CLI just forwards the preset and renders the resulting next steps.

```bash
# Generic ContractSpec workspace setup
contractspec init --preset core

# Enable ContractSpec Connect defaults and local artifacts
contractspec init --preset connect

# Prepare Builder for a managed runtime
contractspec init --preset builder-managed

# Prepare Builder for a local runtime
contractspec init --preset builder-local

# Prepare Builder for a hybrid runtime
contractspec init --preset builder-hybrid
```

In non-interactive mode, setup remains config-first: it writes `.contractsrc.json`, editor wiring, and tailored follow-up commands, but it does not call live Builder bootstrap APIs for you.

`contractspec builder` remains control-plane-backed for managed, local, and hybrid runtime flows. The CLI resolves the Builder API base URL from `CONTRACTSPEC_API_BASE_URL`, then `.contractsrc.json` `builder.api.baseUrl`, then `https://api.contractspec.io`, and reads auth from the configured control-plane token environment variable.

Builder execution aliases are additive shorthands over canonical execution-lane artifacts:

```bash
contractspec builder ralphone "Finish this change" --json
contractspec builder ultrawork "Parallelize this rollout" --json
contractspec builder ulw "Parallelize this rollout" --json
contractspec builder background --dry-run --json
contractspec builder tools doctor --json
contractspec builder tools diagnostics --json
```

`ralphone` starts the `complete.persistent` lane, while `ultrawork` and `ulw` start the `team.coordinated` lane. Persisted lane artifacts keep those canonical lane keys; aliases are only command-entry metadata.


### Builder specs-pack dry-runs and Connect-gated apply

Use `contractspec builder pack` when product intent lives in an external zip or folder and must be inspected before any repository mutation. Import, analyze, and plan emit structured JSON; `implement` remains dry-run only, while `apply` requires an explicit Connect decision and returns a fail-closed task ledger until approved Connect, replay, verifier, and test evidence are present.

```bash
contractspec builder pack import specs/autonomous-company-specs --json
contractspec builder pack analyze specs/autonomous-company-specs --json
contractspec builder pack plan specs/autonomous-company-specs --dry-run --json
contractspec builder pack implement specs/autonomous-company-specs --dry-run --json
contractspec builder pack apply specs/autonomous-company-specs --connect-decision connect:decision:1 --json
```

The pack report keeps external product intent separate from repository implementation reality, preserves source refs for README/AGENTS/prompts/examples/fixtures, surfaces ambiguity/readiness blockers, and recommends whole-pack versus layer-by-layer follow-up planning. The apply ledger records Contract Steward tasks before handwritten work, reviewed write scopes, required artifact kinds, and verifier blockers. Use `$ralplan` for reviewable implementation planning, `$ralph` for one-owner completion, and `$team` only when the Builder plan marks layers or package scopes safe to parallelize.

### Translation diagnostics

Use `contractspec i18n check` to run the reusable ContractSpec static translation diagnostics from the CLI. The command scans `packages/**/src/i18n/catalogs` by default, compares `en/fr/es`, and reports missing catalogs, missing or extra keys, blank values, ICU syntax failures, and placeholder parity issues.

```bash
contractspec i18n check
contractspec i18n check --format json
contractspec i18n check packages/libs/ai-agent --base-locale en --locales en fr es
```

JSON output is the stable automation surface and contains `{ ok, summary, issues }`. Optional `.contractsrc.json` `i18n` settings provide workspace defaults; command flags override config values.

### Builder tmux Sessions

Use `contractspec builder tmux` for full interactive Builder terminal work: REPLs, debuggers, TUIs, long-running dev servers, and local agent sessions that need a durable terminal instead of a one-shot command.

```bash
contractspec builder tmux doctor
contractspec builder tmux start --session builder-debug -- node --inspect
contractspec builder tmux attach --session builder-debug
contractspec builder tmux send --session builder-debug -- npm test
contractspec builder tmux capture --session builder-debug --lines 120
contractspec builder tmux stop --session builder-debug
```

Sessions default to `contractspec-builder`, use argv-based tmux calls, fail on existing sessions unless `--reuse` is set, and support JSON output for automation.

### Builder agent lanes and diagnostics

Builder agent-lane commands keep persisted lane identity canonical even when operators use shorthand aliases:

| Operator surface | Persisted lane key | Metadata |
| --- | --- | --- |
| `contractspec builder ultrawork` / `contractspec builder ulw` | `team.coordinated` | `sourceAlias: "ultrawork"` or `sourceAlias: "ulw"` |
| `contractspec builder ralphone` | `complete.persistent` | `sourceAlias: "ralphone"` |
| `contractspec builder background` | `team.coordinated` | background-agent lease, scope, status, cancel, and attach evidence |
| `contractspec builder tools doctor` / `contractspec builder tools diagnostics` | diagnostics surface only | tool capability, adapter readiness, and degraded-state evidence |

Aliases are compatibility metadata, not new lane keys. Downstream state, release notes, workbench summaries, and replay artifacts should continue to branch on the canonical lane key and may display `sourceAlias` for human traceability.

## Architecture

- **Commands** (`src/commands/`) - Thin wrappers that call bundle services.
- **Prompts** (`src/commands/create/wizards/`) - Interactive UI using `@inquirer/prompts`.
- **CLI setup** (`src/index.ts`, `src/cli.ts`) - Commander.js configuration.
- **Types** (`src/types.ts`) - CLI-specific types.
- **Services** (`@lssm-tech/bundle.workspace/services/`) - Core use-cases.
- `create.ts` - Authored target creation logic.
- `build.ts` - Runtime/package materialization from authored targets.
- `openapi.ts` - OpenAPI export.
- `registry.ts` - Registry client.
- `examples.ts` - Examples management.

## Public Entry Points

- Export `./run` resolves through `bun`, `node`, `default`.

## Local Commands

- `bun run dev` — bun build ./src/cli.ts --outfile ./dist/cli.js --target node --watch
- `bun run build` — bun run prebuild && bun run build:types && bun run build:all
- `bun run test` — bun test
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist
- `bun run build:bun` — bun build --outdir ./dist/bun/ --target bun --minify --external playwright --external playwright-core --external electron --external chromium-bidi --external 'chromium-bidi/*' ./src/cli.ts
- `bun run build:node` — bun build --outdir ./dist/node/ --target node --minify --external playwright --external playwright-core --external electron --external chromium-bidi --external 'chromium-bidi/*' ./src/cli.ts
- `bun run build:all` — bun run build:bun && bun run build:node
- `bun run build:types` — tsgo --noEmit
- `bun run dev:bun` — bun build ./src/cli.ts --outfile ./dist/cli.bun.js --target bun --watch
- `bun run test:watch` — bun test --watch

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add table capabilities.
- Stability.
- Vnext ai-native.
- Add latest models and align defaults.
- Resolve lint and build errors in workspace bundle and integrations lib.

## Notes

- Works alongside `@lssm-tech/bundle.workspace`, `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, ...
- `contractspec apply` has been retired; use `contractspec generate` for write-generation flows.

## Contract Intelligence

The CLI includes a dry-run-first `contractspec intelligence` workflow for analyzing the current repository, exporting a portable bundle, importing it into another target, reconciling reality, and producing a selective import plan. `analyze` defaults to repo-derived evidence; pass `--fixture <name>` only for deterministic examples and regression fixtures. `adopt --apply` is intentionally blocked until ContractSpec Connect review and replay evidence exist. See `docs/contract-intelligence.md`.

`contractspec list --json`, `contractspec integrity --json`, and `contractspec integrity --format mermaid` are machine-output surfaces: stdout is reserved for the requested JSON or diagram, while human diagnostics belong in text mode or stderr. Discovery reports only authored contract/spec evidence and skips prompt/template implementation files that merely contain strings such as `key:`.

`contractspec portfolio index|centralize|propagate|radar` creates advisory portfolio envelopes over bundle refs without mutating shared cores or vertical projects. See `docs/portfolio-centralization.md`.

## i18n diagnostics

Run static translation catalog diagnostics from a workspace or catalog directory:

```bash
contractspec i18n check [path] --locales en fr es --format json
```

The command reports reusable ContractSpec diagnostics for missing catalogs/keys, extra keys, blank values, malformed message shapes, invalid ICU syntax, and placeholder parity. JSON output is stable for CI and exits `1` for diagnostic failures or `2` for fatal config/import errors.


---

## @lssm-tech/app.cli-database

Description: (none)
Path: packages/apps/cli-database
URL: /llms/app.cli-database

# @lssm-tech/app.cli-database

Website: https://contractspec.io

**CLI tool for contract-source-first Drizzle/PostgreSQL database management: generate, migrate, seed, and schema operations.**

## What It Does

- Uses `@lssm-tech/lib.schema` for schema definitions.
- Generates Drizzle/PostgreSQL artifacts from portable ContractSpec database entities.
- Commands dispatched via minimist argument parsing.
- Related ContractSpec packages include `@lssm-tech/lib.schema`, `@lssm-tech/tool.tsdown`, `@lssm-tech/tool.typescript`.

## Running Locally

From `packages/apps/cli-database`:
- `bun run dev`
- `bun run build`

## Usage

```bash
npx database --help
# or
bunx database --help
```

## Architecture

- Uses `@lssm-tech/lib.schema` for schema definitions.
- Generates Drizzle/PostgreSQL artifacts from portable ContractSpec database entities.
- Commands dispatched via minimist argument parsing.
- `src/cli.ts` is the CLI entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Binary `database` points to `dist/cli.js`.
- Export `.` resolves through `./dist/index.mjs`.
- Export `./cli` resolves through `./dist/cli.mjs`.
- Export `./commands/check` resolves through `./dist/commands/check.mjs`.
- Export `./commands/generate` resolves through `./dist/commands/generate.mjs`.
- Export `./commands/import` resolves through `./dist/commands/import.mjs`.
- Export `./commands/migrate` resolves through `./dist/commands/migrate.mjs`.
- Export `./commands/schema-compose` resolves through `./dist/commands/schema-compose.mjs`.
- Export `./commands/schema-generate` resolves through `./dist/commands/schema-generate.mjs`.
- Export `./commands/seed` resolves through `./dist/commands/seed.mjs`.
- Export `./lib/config` resolves through `./dist/lib/config.mjs`.
- The package publishes 12 total export subpaths; keep docs aligned with `package.json`.


## Database Workflow Boundary

Prisma support is retired for supported workflows. Broad root workflows such as `lint:fix`, `typecheck`, and release checks must not run Prisma implicitly; use the explicit Drizzle/PostgreSQL `packages/apps/cli-database` commands below when a database schema workflow is required.

## Local Commands

- `bun run dev` — bun run build --watch
- `bun run build` — tsdown
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist
- `bun run dbs:generate` — database generate --dry-run
- `bun run dbs:migrate` — database migrate:dev --dry-run
- `bun run dbs:deploy` — database migrate:deploy --dry-run
- `bun run dbs:status` — database migrate:status
- `bun run dbs:seed` — database seed

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Do not change CLI argument signatures without updating docs and CI scripts.
- Drizzle/PostgreSQL artifact generation is contract-source-first — test migrations carefully.


---

## @lssm-tech/app.cli-databases

Description: (none)
Path: packages/apps/cli-databases
URL: /llms/app.cli-databases

# @lssm-tech/app.cli-databases

Website: https://contractspec.io

**CLI orchestrator for multi-database workflows. Coordinates operations across multiple database profiles defined in a project.**

## What It Does

- Lightweight CLI with no workspace bundle dependencies.
- Uses minimist for argument parsing, execa for subprocess execution.
- Delegates per-database work to `cli-database`.
- Related ContractSpec packages include `@lssm-tech/tool.tsdown`, `@lssm-tech/tool.typescript`.

## Running Locally

From `packages/apps/cli-databases`:
- `bun run dev`
- `bun run build`

## Usage

```bash
npx databases --help
# or
bunx databases --help
```

## Architecture

- Lightweight CLI with no workspace bundle dependencies.
- Uses minimist for argument parsing, execa for subprocess execution.
- Delegates per-database work to `cli-database`.
- `src/cli.ts` is the CLI entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Binary `databases` points to `dist/cli.js`.
- Export `.` resolves through `./dist/index.mjs`.
- Export `./cli` resolves through `./dist/cli.mjs`.
- Export `./profile` resolves through `./dist/profile.mjs`.
- Export `./*` resolves through `./*`.

## Local Commands

- `bun run dev` — bun run build --watch
- `bun run build` — tsdown
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Keep this as a thin orchestrator — business logic belongs in `cli-database`.
- Do not change CLI argument signatures without updating docs and CI scripts.


---

## @lssm-tech/app.communicationos-mcp

Description: MCP server exposing CommunicationOS contracts as AI-callable tools via the Model Context Protocol.
Path: packages/apps/communicationos-mcp
URL: /llms/app.communicationos-mcp

(No README.md)

---

## @lssm-tech/jetbrains-contractspec-bridge

Description: Node.js bridge server for ContractSpec JetBrains Plugin
Path: packages/apps/jetbrains-contractspec/bridge
URL: /llms/jetbrains-contractspec-bridge

# @lssm-tech/jetbrains-contractspec-bridge

Website: https://contractspec.io/

**Node.js bridge server for ContractSpec JetBrains Plugin**

JSON-RPC/LSP server over stdio that connects the JetBrains IDE plugin to ContractSpec workspace services. Uses vscode-languageserver, TextDocuments, and BridgeServer handlers. Private package; not published to npm.

## Installation / Running

From the monorepo root:

```bash
bun install
bun run build --filter=@lssm-tech/jetbrains-contractspec-bridge
bun run start --filter=@lssm-tech/jetbrains-contractspec-bridge
```

Or from this directory:

```bash
bun run build
bun run start
```

The bridge is typically launched by the JetBrains plugin as a subprocess; it communicates via stdin/stdout.

## Entry Point

- `src/server.ts` — Creates LSP connection, TextDocuments manager, and BridgeServer. Handles `onInitialize`, `onInitialized`, and text document open/change/close events.

## Architecture

- **BridgeServer** (`src/handlers/BridgeServer.ts`) — Wraps `@lssm-tech/bundle.workspace` and `@lssm-tech/module.workspace` for spec validation, scaffolding, and analysis.
- **vscode-languageserver** — Provides stdio transport and LSP protocol.
- **TextDocuments** — Tracks open documents for the plugin.


---

## @lssm-tech/app.managed-companyos-mcp

Description: (none)
Path: packages/apps/managed-companyos-mcp
URL: /llms/app.managed-companyos-mcp

# @lssm-tech/app.managed-companyos-mcp

**MCP server that exposes Managed CompanyOS operations and resources for tenant onboarding, integration discovery, workflow status, replay, evidence, health probes, and fail-closed Managed Builder evidence tools.**

## What It Does

- Hosts a ContractSpec MCP server over Managed CompanyOS contracts (`companyos/*`).
- Exposes V1 read/onboarding tools, Builder readiness/replay/evidence/release tools, and one reference resource for the operator copilot.
- Resolves the actor from env vars (single-tenant per process) in V1; multi-tenant
  HTTP transport is deferred to V2.

## V1 Tools

| Tool | Contract |
| --- | --- |
| `tenant.onboard` | `companyos/commands/tenantOnboard.command.ts` |
| `tenant.get` | `companyos/queries/tenantGet.query.ts` |
| `integration.list-providers` | `companyos/queries/integrationListProviders.query.ts` |
| `workflow.get-status` | `companyos/queries/workflowGetStatus.query.ts` |
| `approval.list-pending` | `companyos/queries/approvalReasons.query.ts` (stub source until control-plane reuse lands) |
| `replay.get-packet` | `companyos/queries/replayGetPacket.query.ts` |
| `evidence.get-receipt` | `companyos/queries/evidenceGetReceipt.query.ts` |
| `health.worker` | `companyos/queries/healthWorker.query.ts` |
| `builder.readiness.evaluate` | `companyos/commands/builderReadinessEvaluate.command.ts` |
| `builder.evidence.receipt.get` | `companyos/queries/builderEvidenceReceiptGet.query.ts` |
| `builder.replay.packet.get` | `companyos/queries/builderReplayPacketGet.query.ts` |
| `builder.release.capsule.get` | `companyos/queries/builderReleaseCapsuleGet.query.ts` |

## Environment Variables

- `MANAGED_COMPANYOS_MCP_API_KEY` — platform API key (required in production).
- `MANAGED_COMPANYOS_MCP_TENANT_ID` — optional tenant pin for tenant-scoped keys.
- `MANAGED_COMPANYOS_MCP_NAME` — override server name (default `managed-companyos-mcp`).
- `MANAGED_COMPANYOS_MCP_VERSION` — override server version (default `0.1.0`).

## Running Locally

From `packages/apps/managed-companyos-mcp`:

- `bun run dev`
- `bun run start`
- `bun run build`
- `bun run typecheck`
- `bun run test`

## Architecture

- `src/server.ts` boots the MCP server and stdio transport.
- `src/blueprint.ts` defines the app blueprint.
- `src/tools.ts` installs operation specs through `installOp`.
- `src/resources.ts` exposes the reference workspace resource.
- `src/prompts.ts` registers the operator copilot prompt.
- `src/tenant-context.ts` resolves the actor and decision context.
- `src/smoke.test.ts` asserts the registry registers the expected number of tools.

## Status

Handlers are deterministic reference bindings for V1. Builder-specific handlers
are live fail-closed evidence tools: they reject raw-looking credentials, report
missing provider/webhook refs as blockers, and emit Builder-scoped
readiness/replay/receipt/release packets without replacing agent/workflow.


---

## @lssm-tech/app.mobile-monolith

Description: Expo ContractSpec native superapp foundation with contract-driven auth, workspace, remote-config, RoleMorph, and managed CompanyOS proof surfaces
Path: packages/apps/mobile-monolith
URL: /llms/app.mobile-monolith

# @lssm-tech/app.mobile-monolith

**Expo ContractSpec native superapp foundation with contract-driven auth, workspace, remote-config, RoleMorph, and managed CompanyOS proof surfaces.**

The root route now enters a narrow, native proof flow:

- Reframes the former mobile landing companion into a native superapp shell foundation.
- Keeps the first proof intentionally narrow: auth/session entry, remote tenant/workspace config, workspace selection, ContractSpec-driven surfaces, RoleMorph personalization, and managed CompanyOS view-model adapters.
- Uses Expo Router for native routes while keeping route files thin; shell decisions should come from app-local contracts, handlers, runtime ports, and registries rather than route-level fixtures.
- Reuses shared marketing/catalog content only as secondary documentation/discovery surfaces, not as the primary shell purpose.
- A preview-registry entry or shared example preview is discovery-only; it is not a standalone Special Ops app shell.
- Prefers `@lssm-tech/bundle.managed-companyos/view-models/*` exports plus React Native adapters over direct SSR/web UI imports.
- Keeps provider execution fail-closed: no raw secrets in fixtures, snapshots, event payloads, or view-models.

This package intentionally does **not** attempt full web-monolith parity. It reuses shared CompanyOS view-model/data exports and avoids SSR/web UI imports unless RN compatibility is separately proven.

## Special Ops managed app gate

Special Ops is a managed CompanyOS production candidate, not a standalone native shell. Mobile promotion must follow [`docs/runbooks/special-ops-monolith-production.md`](../../../docs/runbooks/special-ops-monolith-production.md) and prove the native route enters through AuthOS/session projection, remote workspace config, RoleMorph filtering, provider-safe degraded states, and the shared bundle view-model exports.

Required evidence before claiming mobile parity:

- `bun test --cwd packages/apps/mobile-monolith`
- `bun run --cwd packages/apps/mobile-monolith typecheck`
- import-boundary evidence showing no direct `@lssm-tech/bundle.managed-companyos/ui`, Next, DOM, or example-package runtime imports in the managed Special Ops path
- RoleMorph denial evidence for blocked/provider-impacting actions and no standalone Special Ops route outside the managed native shell

## BillingOS native proof

The example preview registry includes a dedicated `billingos-france-sme` native proof. It renders quote, invoice, paid payment, France readiness, and operator approval-packet summary data through React Native primitives backed by deterministic `src/examples/billingos-native-proof-data.ts` constants. This is a native-safe proof path only: it must not import `@lssm-tech/module.billing-os/ui`, provider SDKs, credentials, network submission paths, PA submission, payment processing, or autonomous production billing execution.

Targeted BillingOS proof evidence:

```bash
bun test packages/apps/mobile-monolith/src/examples/native-preview-registry.test.ts packages/apps/mobile-monolith/src/examples/billingos-native-proof.test.ts
bun run --cwd packages/apps/mobile-monolith lint:check
```

Package-wide `typecheck` remains a separate mobile-host gate and is currently blocked by pre-existing workspace config/type issues unrelated to the BillingOS proof (`bun:test` and Node test/global types). The managed CompanyOS `./product-surfaces` subpath is exported and covered by the mobile registry/import-boundary tests.


## App submission readiness

The native proof is configured for read-first App Store / Google Play review paths without committing provider credentials or production submission secrets.

- `app.config.ts` declares the stable iOS bundle id (`io.contractspec.expo-demo`), Android package (`io.contractspec.expo_demo`), 1024×1024 proof icon/splash assets, and legal review links (`https://contractspec.io/privacy`, `https://contractspec.io/terms`, `https://contractspec.io/support`) under `extra.appReview`.
- iOS encryption and privacy posture is explicit: `usesNonExemptEncryption: false`, `ITSAppUsesNonExemptEncryption: false`, and an Expo `ios.privacyManifests` block that materializes `PrivacyInfo.xcprivacy` during prebuild/EAS. The current proof declares no tracking domains, no collected data types, and the UserDefaults required-reason API (`CA92.1`) used by the native shell/SDK layer.
- Android proof builds deny optional sensitive permissions by default (`CAMERA`, `RECORD_AUDIO`, fine/coarse location, contacts) and keep the permission list empty until a reviewed feature needs one.
- `eas.json` keeps build profiles and production submit profile credential-free; App Store Connect / Google Play submission credentials must remain in EAS/CI secret stores rather than source.

Targeted readiness evidence:

```bash
bun test packages/apps/mobile-monolith/src/app-submission-readiness.test.ts
bun run --cwd packages/apps/mobile-monolith lint:check
bun run --cwd packages/apps/mobile-monolith typecheck
```

## Safety boundaries

- `bun run dev`
- `bun run start`
- `bun run test`
- `bun run typecheck`
- `bun run lint:check`

## Architecture

- `src/app/` contains Expo Router entry points and should remain thin.
- `src/contracts/` defines mobile ContractSpec shell/session/config/workspace/surface contracts as they are introduced.
- `src/handlers/` adapts deterministic local data and shared catalogs into operation results.
- `src/screens/` owns React Native screen composition for shell, workspace, managed CompanyOS proof, and degraded states.
- `src/examples/` and example preview components remain secondary discovery surfaces.

## Public Entry Points

- Deployable Expo app with no published library exports.
- Primary runtime surfaces are Expo routes, mobile contracts/registries, and deterministic local handlers/ports.

## Guardrails

- No full web-monolith parity in the mobile foundation pass.
- No unrelated API auth/database edits from this package lane.
- No direct `@lssm-tech/bundle.managed-companyos/ui`, `next`, `react-dom`, DOM global, or SSR-only component imports into the Expo shell unless compatibility is intentionally proven.
- Auth/session and remote config ports must be safe locally, redacted, deterministic in tests, and fail-closed when production credentials are unavailable.
- RoleMorph/persona differences must preserve denial evidence for blocked/provider-impacting actions.

## Notes

This package may still carry legacy landing/example routes while the superapp shell is being built, but docs, metadata, and guardrail tests now track the approved superapp foundation direction.


---

## @lssm-tech/app.notion-mcp

Description: (none)
Path: packages/apps/notion-mcp
URL: /llms/app.notion-mcp

# Notion MCP

Thin ContractSpec MCP package for Notion surfaces. This scaffold registers the canonical Notion MCP tool catalog and leaves execution as fail-loud pending handlers until the provider-backed integration is wired.


---

## @lssm-tech/app.organization-planning-host

Description: Thin OPA host: mounts the organization-planning operation registry on REST, GraphQL, and MCP surfaces via the shared contracts-runtime adapters.
Path: packages/apps/organization-planning-host
URL: /llms/app.organization-planning-host

# @lssm-tech/app.organization-planning-host

Website: https://contractspec.io

**Thin OPA host — mounts the organization-planning operation registry on REST,
GraphQL, and MCP.**

## What It Provides

- **Layer**: `app.` (thin deployable host; transport wiring only).
- Exposes `buildOpaOps()` (from `@lssm-tech/lib.organization-planning-runtime`)
  identically on three surfaces via existing contracts-runtime adapters:
  - **REST** — `createOpaRestHandler(ctxFactory)`, served by the Next App Router
    catch-all at `app/api/ops/[...route]/route.ts`.
  - **GraphQL** — `createOpaGraphqlBuilder()` returns a Pothos builder with the OPA
    query/mutation fields.
  - **MCP** — `mountOpaMcp(server, ctxFactories)` registers the OPA tools.
- Serves the **public booking page** at `app/book/[link]/page.tsx`, backed by the
  real public availability/confirm operations (`src/booking/*`) — anonymous
  visitors pick a slot and confirm against the live OPA registry.

## Auth

Fail-closed. The caller supplies a context projection (REST `ctxFactory`,
MCP `toolCtx`) that maps the authenticated Subject onto `HandlerCtx`. The route's
placeholder projection is a TODO for the identity-rbac / AuthOS wave (P2-B).

## Local Commands

- `bun run test` — smoke tests (3 surface mounts + REST round-trip)
- `bun run typecheck` — TypeScript check
- `bun run lint:check` — Biome check


---

## @lssm-tech/app.provider-ranking-mcp

Description: (none)
Path: packages/apps/provider-ranking-mcp
URL: /llms/app.provider-ranking-mcp

# @lssm-tech/app.provider-ranking-mcp

**MCP server that exposes provider-ranking operations and resources for benchmark ingestion, ranking refreshes, and leaderboard queries.**

## What It Does

- Hosts a ContractSpec MCP server over provider-ranking contracts and runtime registries.
- Exposes benchmark ingest, custom benchmark run, and ranking refresh operations.
- Publishes leaderboard and model-profile resources backed by the ranking store.
- Enriches incomplete ranking data with metadata from `@lssm-tech/lib.ai-providers`.

## Running Locally

From `packages/apps/provider-ranking-mcp`:
- `bun run dev`
- `bun run start`
- `bun run build`

## Usage

```bash
bun run dev
```

## Architecture

- `src/server.ts` boots the MCP server and transport wiring.
- `src/index.ts` exposes the package entrypoints for reuse or embedding.
- The server composes provider-ranking contracts, module orchestration, and MCP resource/tool exposure.

## Public Entry Points

- Exports `.` and `./server` for embedding or direct server startup.
- Primary MCP surfaces are benchmark-ingest tools, ranking refresh tools, leaderboard resources, and model-profile resources.
- Export `.` resolves through `./dist/index.mjs`.
- Export `./server` resolves through `./dist/server.mjs`.
- Export `./*` resolves through `./*`.

## Local Commands

- `bun run dev` — tsdown --watch
- `bun run start` — node dist/server.js
- `bun run build` — tsdown
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run clean` — rm -rf dist

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add latest models and align defaults.
- Resolve lint, build, and type errors across nine packages.
- Add AI provider ranking system with ranking-driven model selection.

## Notes

- The current implementation uses an in-memory store; restart the process to clear rankings and benchmark results.


---

## @lssm-tech/app.registry-packs

Description: (none)
Path: packages/apps/registry-packs
URL: /llms/app.registry-packs

# @lssm-tech/app.registry-packs

Website: https://agentpacks.dev

**Agentpacks registry server for pack publishing, discovery, reviews, dependency graphs, and MCP access.**

## What It Does

- Hosts the pack registry API, MCP layer, artifact storage, and publishing workflows.
- Supports versioning, reviews, organizations, quality scoring, GitHub integration, and webhooks.
- Supports both SQLite and PostgreSQL deployment paths with rate-limiting and auth middleware.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.
- `src/routes/` contains HTTP or API route definitions.
- `src/services/` contains business logic services and workflows.

## Running Locally

From `packages/apps/registry-packs`:
- `bun run dev`
- `bun run start`
- `bun run build`
- `bun run test`

## Usage

```bash
bun run dev
```

## Architecture

- `src/routes/` owns HTTP endpoints for packs, versions, publishing, organizations, dependencies, and GitHub flows.
- `src/services/` contains business workflows for registry operations, search, scoring, reviews, and webhooks.
- `src/mcp/` exposes registry tools, prompts, and resources over the MCP protocol.
- `src/db/`, `src/storage/`, `src/auth/`, and `src/middleware/` hold persistence and platform adapters.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/server.ts` is the main server bootstrap entrypoint.

## Public Entry Points

- Deployable API app with HTTP routes, MCP tools/prompts/resources, and registry publishing flows.
- Primary public surface is the HTTP route tree under `src/routes/`.
- This app exposes MCP-facing tools, prompts, resources, or transport handlers.

## Local Commands

- `bun run dev` — bun run --watch src/index.ts
- `bun run start` — bun run ./dist/index.js
- `bun run build` — bun build --minify-whitespace --minify-syntax --target bun --outfile dist/index.js src/index.ts
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run db:generate` — drizzle-kit generate
- `bun run db:migrate` — drizzle-kit migrate
- `bun run db:studio` — drizzle-kit studio
- `bun run clean` — rm -rf dist
- `bun run db:generate:pg` — drizzle-kit generate --config=drizzle-pg.config.ts
- `bun run db:migrate:pg` — drizzle-kit migrate --config=drizzle-pg.config.ts
- `bun run db:seed` — bun run src/db/seed.ts

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint and build errors in workspace bundle and integrations lib.
- Test runner.
- Resolve lint/test regressions after voice capability updates.
- Phase 4 production hardening — rate limiting, security, E2E tests, versioning polish.
- Add dependency graph, webhooks, GitHub App, and PostgreSQL support (Phase 3b).

## Notes

- REST API routes are consumed by external clients — do not change paths or response shapes without versioning.
- MCP tool schemas are a protocol contract — coordinate changes with MCP clients.
- Database migrations must be backwards-compatible.


---

## @lssm-tech/app.registry-server

Description: (none)
Path: packages/apps/registry-server
URL: /llms/app.registry-server

# @lssm-tech/app.registry-server

Website: https://contractspec.io

**ContractSpec registry server. Serves contract specs and metadata over HTTP for IDE plugins, CLI tools, and other consumers.**

## What It Does

- Built with Elysia (Bun HTTP framework).
- Uses `@lssm-tech/lib.contracts-spec` for contract definitions.
- Uses `@lssm-tech/lib.logger` for structured logging.
- Separate handlers for ContractSpec and LSSM routes.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/apps/registry-server`:
- `bun run dev`
- `bun run start`
- `bun run build`

## Usage

```bash
bun run dev
```

## Architecture

- Built with Elysia (Bun HTTP framework).
- Uses `@lssm-tech/lib.contracts-spec` for contract definitions.
- Uses `@lssm-tech/lib.logger` for structured logging.
- Separate handlers for ContractSpec and LSSM routes.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/server.ts` is the main server bootstrap entrypoint.

## Public Entry Points

- This package is a deployable application rather than a library with published subpath exports.

## Local Commands

- `bun run dev` — bun run --watch src/server.ts
- `bun run start` — ./server
- `bun run build` — bun build --compile --minify-whitespace --minify-syntax --target bun --outfile dist/server src/index.ts
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rm -rf dist server

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- API routes are consumed by IDE plugins and CI — do not change paths or response shapes without versioning.
- Filesystem access must use the `src/utils/` helpers for consistent path resolution.


---

## @lssm-tech/app.teams-mcp

Description: (none)
Path: packages/apps/teams-mcp
URL: /llms/app.teams-mcp

# Teams MCP

Thin ContractSpec MCP package for Microsoft Teams surfaces. This scaffold registers the canonical Teams MCP tool catalog and leaves execution as fail-loud pending handlers until the provider-backed integration is wired.


---

## @lssm-tech/app.video-studio

Description: (none)
Path: packages/apps/video-studio
URL: /llms/app.video-studio

# @lssm-tech/app.video-studio

**Thin Remotion Studio wrapper. Re-exports the Remotion entry point from `@lssm-tech/lib.video-gen`.**

## What It Does

- **Layer**: app (Remotion Studio)
- **Consumers**: internal — video preview and rendering

## Running Locally

From `packages/apps/video-studio`:
- `bun run dev`
- `bun run build`

## Usage

```bash
bun run dev
```

## Local Commands

- `bun run dev` — bunx remotionb studio src/index.ts
- `bun run build` — echo 'No build step needed for Remotion Studio'
- `bun run clean` — rimraf out .turbo
- `bun run render` — bunx remotionb render src/index.ts
- `bun run render:all` — bunx remotionb render src/index.ts ApiOverview out/api-overview.mp4 && bunx remotionb render src/index.ts SocialClip out/social-clip.mp4 && bunx remotionb render src/index.ts SocialClipSquare out/social-clip-square.mp4 && bunx remotionb render src/index.ts SocialClipPortrait out/social-clip-portrait.mp4 && bunx remotionb render src/index.ts TerminalDemo out/terminal-demo.mp4

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Improve agentpacks
- Switch Remotion CLI to bunx remotionb for Bun runtime support

## Notes

- Do NOT add compositions here. All compositions live in `@lssm-tech/lib.video-gen`.
- This package exists solely to provide a Remotion Studio entry point.
- Uses `remotionb` CLI for Bun runtime support. Known caveat: SSR scripts may not auto-quit (see [Remotion Bun docs](https://www.remotion.dev/docs/bun)).


---

## vscode-contractspec

Description: (none)
Path: packages/apps/vscode-contractspec
URL: /llms/vscode-contractspec

# vscode-contractspec

Website: https://contractspec.io

**ContractSpec: spec-first development for AI-written software. Validate, scaffold, and explore your contract specifications.**

## What It Does

- `@lssm-tech/module.workspace` for pure analysis + templates.
- `@lssm-tech/bundle.workspace` for workspace services + adapters.
- `src/ui/` contains packaged UI exports and embeddable views.
- Related ContractSpec packages include `@lssm-tech/bundle.workspace`, `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.contracts-transformers`, `@lssm-tech/module.ai-chat`, ...
- `src/ui/` contains packaged UI exports and embeddable views.

## Running Locally

From `packages/apps/vscode-contractspec`:
- `bun run dev`
- `bun run build`
- `bun run test`

## Usage

```bash
bun run dev
```

## Initialization Presets

The extension setup flow is preset-driven and backed by the shared workspace setup service.

- `ContractSpec: Setup ContractSpec` lets you choose between `core`, `connect`, `builder-managed`, `builder-local`, and `builder-hybrid`.
- `ContractSpec: Quick Setup (Defaults)` applies the `core` preset with no prompts.
- Builder managed and hybrid presets mirror the configured Builder API base URL into `contractspec.api.baseUrl` in `.vscode/settings.json`.

Representative follow-up commands after setup:

```bash
contractspec builder init --workspace-id ws-demo --preset managed-mvp
contractspec builder init --workspace-id ws-demo --preset local-daemon-mvp
contractspec builder local register --workspace-id ws-demo --runtime-id rt_local_daemon --granted-to local:operator
```

## Architecture

- `@lssm-tech/module.workspace` for pure analysis + templates.
- `@lssm-tech/bundle.workspace` for workspace services + adapters.

## Public Entry Points

- This package is a deployable application rather than a library with published subpath exports.

## Local Commands

- `bun run dev` — bun build src/extension.ts --outdir=dist --target=node --format=cjs --external=vscode --sourcemap=external --watch
- `bun run build` — bun run build:types && bun run build:bundle
- `bun run test` — vscode-test
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run vscode:prepublish` — bun run build
- `bun run build:bundle` — bun build src/extension.ts --outdir=dist --target=node --format=cjs --external=vscode --minify
- `bun run build:types` — tsgo --noEmit
- `bun run package` — vsce package --no-dependencies
- `bun run publish:off` — vsce publish --no-dependencies

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Standardize tool naming to underscore notation.

## Notes

- Works alongside `@lssm-tech/bundle.workspace`, `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.ai-providers`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.contracts-transformers`, ...


---

## @lssm-tech/app.web-application-monolith

Description: (none)
Path: packages/apps/web-application-monolith
URL: /llms/app.web-application-monolith

# Managed CompanyOS Web Application Monolith

Real Next.js App Router web entrypoint for Managed CompanyOS, the invite-led AI operating system for companies built on the ContractSpec substrate. It renders the public `/companyos` managed landing plus the managed cockpit for the reference tenant: onboarding, admin, AuthOS, integration hub, operating graph, composite workflow, replay, evidence, lifecycle, knowledge, team, analytics, finance, special ops, and degraded-state navigation.

The app stays thin by composing `@lssm-tech/bundle.managed-companyos` and design-system primitives. Provider decisions remain approval-gated. Credential values are never displayed — only redacted references (`'********'`) appear, enforced by `assertRedactedSecretDisplay` in the bundle.

## Special Ops production cutover

Use [`docs/runbooks/special-ops-monolith-production.md`](../../../docs/runbooks/special-ops-monolith-production.md) for the database-first Special Ops, AI Ops Sprint, and all-in-one work-graph promotion gates. The web app remains a thin shell: render production-owned bundle/API projections, preserve redaction and AI-dispatch blocks, and do not import `packages/examples/*` at runtime.

## Managed CompanyOS production path

Use [`docs/runbooks/managed-companyos.md`](../../../docs/runbooks/managed-companyos.md) as the cross-lane production-path evidence ledger for DB lifecycle, auth/session runtime, route conversion, UX richness, Special Ops, bundle boundary, and docs/contract gates. This README documents the current web surface; it is not a release gate for any DB-backed route.

Current route status:

- Most deterministic reference pages remain `force-static`; integration, onboarding, root, evidence, and other session/persona-sensitive route sections document `force-dynamic` where implemented.
- DB-backed route promotion requires local/test migrate + seed + verify output, not static workspace builders alone.
- Auth/session promotion requires unauthenticated denial, authenticated access, role-gate, session revoke, auditor read-only, and tenant-mismatch evidence.
- Special Ops promotion requires database-first capability graph/workspace/seed-run receipt evidence or an explicit known-gap note in the evidence packet.
- Replay and evidence routes remain read-only; adding mutation affordances there is a breaking contract change.

Do not hide mock/reference data behind production wording. If a page still reads deterministic bundle projections, call it deterministic/reference in release notes and attach the follow-up lane rather than claiming runtime persistence.


## CompanyOS marketing contract boundary

The `(marketing)` route group is wrapped with the shared marketing contract boundary and backed by the full CompanyOS route contract registry from `@lssm-tech/bundle.marketing/content`. The seven PRD CompanyOS pages remain adapter-rendered; bespoke marketing pages stay copy-owned by their existing components while being contract-addressable through the inert boundary. Public legal/trust pages (`/mentions-legales`, `/privacy`, `/terms`, `/cookies`, `/security`) are part of this unauthenticated marketing surface and must stay aligned with the blueprint, sitemap, robots/LLMO artifacts, footer links, and static `public/llms.txt` fallback.

## Route inventory

### Persona home pages (Phase 2 boil-lake)

| Route | File | Persona | Purpose |
|---|---|---|---|
| `/companyos/founder` | `src/app/companyos/founder/page.tsx` | `founder_approver` | Mission intelligence, pending approvals, evidence readiness, governance alerts |
| `/companyos/ops` | `src/app/companyos/ops/page.tsx` | `operations_manager` | Operational dashboards, workflow status, team assignments, performance metrics |
| `/companyos/frontline` | `src/app/companyos/frontline/page.tsx` | `frontline_staff` | Task queue, shift information, training resources, quick-access tools |
| `/companyos/auditor` | `src/app/companyos/auditor/page.tsx` | `auditor` | Audit findings, compliance status, risk assessments, evidence trails (read-only) |
| `/companyos/admin` | `src/app/companyos/admin/page.tsx` | `enterprise_admin` | System configuration, user management, integration hub, workspace settings |

### Core feature routes

| Route | File | Purpose |
|---|---|---|
| `/` | `src/app/page.tsx` | Cockpit landing; persona dispatcher; bundle proof + governance report |
| `/companyos` | `src/app/companyos/page.tsx` | Public managed landing; renders bundle-owned Managed CompanyOS view-model/template with deterministic reference posture |
| `/companyos/onboarding` | `src/app/companyos/onboarding/page.tsx` | Tenant onboarding; 4-step wizard (auth, billing, messaging, integrations); **≤60s reference-flow target** |
| `/companyos/integrations` | `src/app/companyos/integrations/page.tsx` | Force-dynamic Integration Hub catalog using bundle view-models/templates and per-request role morph resolution |
| `/companyos/integrations/connections` | `src/app/companyos/integrations/connections/page.tsx` | Force-dynamic global connections view with redacted credential references |
| `/companyos/integrations/syncs` | `src/app/companyos/integrations/syncs/page.tsx` | Force-dynamic sync health/config view with redacted credential references |
| `/companyos/integrations/[integrationId]` | `src/app/companyos/integrations/[integrationId]/page.tsx` | Force-dynamic integration detail overview with role-gated actions |
| `/companyos/integrations/[integrationId]/credentials` | `src/app/companyos/integrations/[integrationId]/credentials/page.tsx` | Force-dynamic security-class credentials tab; never statically render |
| `/companyos/integrations/[integrationId]/secrets` | `src/app/companyos/integrations/[integrationId]/secrets/page.tsx` | Force-dynamic security-class secrets tab; never statically render |
| `/companyos/integrations/[integrationId]/config` | `src/app/companyos/integrations/[integrationId]/config/page.tsx` | Force-dynamic integration configuration tab |
| `/companyos/integrations/[integrationId]/audit` | `src/app/companyos/integrations/[integrationId]/audit/page.tsx` | Force-dynamic integration audit tab |
| `/companyos/opa-os` | `src/app/companyos/opa-os/page.tsx` | Force-static OPA OS manual planning proof; consumes `buildManagedCompanyOsOpaOsProof` from the managed bundle, keeps provider effects approval-blocked, and emits only local `surface_viewed` / `role_morph_resolved` behavior signals |
| `/companyos/nav-map` | `src/app/companyos/nav-map/page.tsx` | Power-user navigation topology; renders all nav surfaces + edges as interactive DAG; capability-gated |
| `/companyos/workflow/[runId]` | `src/app/companyos/workflow/[runId]/page.tsx` | Composite workflow run; graph nodes + steps; approval/deny affordances role-gated; AI-dispatch blocked |
| `/companyos/replay/[runId]` | `src/app/companyos/replay/[runId]/page.tsx` | Deterministic replay viewer; events ordered by sequence; **read-only** — no approve/deny/request affordances |
| `/companyos/evidence/[runId]` | `src/app/companyos/evidence/[runId]/page.tsx` | Auditor-safe evidence receipt; metadata counts, verification hash, redaction summary |
| `/companyos/auth` | `src/app/companyos/auth/page.tsx` | AuthOS command center; passkeys, sessions, invitations, audit, lockout recovery |
| `/companyos/auth/sessions` | `src/app/companyos/auth/sessions/page.tsx` | Verified-session AuthOS active sessions; sibling-session revoke |
| `/companyos/auth/passkeys` | `src/app/companyos/auth/passkeys/page.tsx` | Passkey enrollment projection |
| `/companyos/auth/invitations` | `src/app/companyos/auth/invitations/page.tsx` | Invitation management projection |
| `/companyos/auth/audit` | `src/app/companyos/auth/audit/page.tsx` | Read-only AuthOS audit projection |
| `/companyos/auth/locked` | `src/app/companyos/auth/locked/page.tsx` | Account lockout recovery projection |
| `/companyos/lifecycle` | `src/app/companyos/lifecycle/page.tsx` | Lifecycle stages and milestone visibility with role redaction |
| `/companyos/knowledge` | `src/app/companyos/knowledge/page.tsx` | Governed knowledge base with editor/auditor projections |
| `/companyos/team` | `src/app/companyos/team/page.tsx` | Team directory and assignment visibility with contact redaction |
| `/companyos/analytics` | `src/app/companyos/analytics/page.tsx` | Operational analytics; blocked roles receive empty denied view models |
| `/companyos/finance` | `src/app/companyos/finance/page.tsx` | Finance queues with amount redaction and founder-only approval affordances |
| `/companyos/special-ops` | `src/app/companyos/special-ops/page.tsx` | Incident and escalation cockpit; blocked roles receive empty denied view models |
| `/error` | `src/app/error.tsx` | Global error boundary (Client Component); renders `stateCopy.error` with "Try again" |
| `/loading` | `src/app/loading.tsx` | Global loading state; renders `stateCopy.loading` with `role="status"` |
| `/not-found` | `src/app/not-found.tsx` | Global 404 page; renders `stateCopy.empty` with home link |

Deterministic reference pages use `export const dynamic = 'force-static'`. Session/persona-sensitive pages declare `force-dynamic`; the Integration Hub catalog, detail, connections, syncs, config, audit, credentials, and secrets routes are dynamic so role morphs and security-class tabs resolve per request. Dynamic replay/workflow routes may still pre-render `runId: 'corr_internal_approval_service_delivery_001'` via `generateStaticParams()` when their route file declares that behavior.

## Role-aware screens

### Onboarding (`/companyos/onboarding`)

`roleAffordances(role)` gates UI actions per role:

| Role | `canConfigure` | Action label |
|---|---|---|
| `enterprise_admin` | `true` | Configure |
| `operations_manager` | `false` | View status |
| `frontline_staff` (default) | `false` | Request access |

### Admin / integration setup (`/companyos/admin`)

`adminRoleAffordances(role)` gates management actions:

| Role | `canManage` | Secret action | Role label |
|---|---|---|---|
| `enterprise_admin` | `true` | Rotate secret ref | Enterprise admin |
| `operations_manager` | `false` | View audit trail | Operations manager |
| `frontline_staff` (default) | `false` | Request support | View only |

### Workflow (`/companyos/workflow/[runId]`)

`workflowStepAffordances(step, policyDecisions, viewerRole)` gates per-step actions:

| Role | `canApprove` | `canDeny` | Notes |
|---|---|---|---|
| `enterprise_admin` | depends on step boundary | depends on step boundary | Can approve `approval_required` steps |
| `operations_manager` | depends on step boundary | depends on step boundary | Default viewer role |
| `founder_approver` | depends on step boundary | depends on step boundary | `requiresFounderApproval: true` when step actor is `founder_approver` |
| `auditor` | **always `false`** | **always `false`** | Read-only — "Auditor read-only" label shown |
| Any role | **always `false`** | **always `false`** | When step boundary is `denied` + `actorRole` is `ai_operator`: `aiCannotDispatch: true` for **every role including enterprise_admin** |

### Replay (`/companyos/replay/[runId]`)

Read-only auditor surface. Zero approve / deny / request-approval affordances for any role.

### Evidence (`/companyos/evidence/[runId]`)

Shows metadata counts (replay events, policy decisions, graph nodes), `verificationHash` in monospace, `redactionSummary`, and a "Verify receipt" affordance. No mutation affordances.

## Dual-mode integration UX (`/companyos/admin`, `/companyos/integrations`)

Managed and BYOK integrations render with equal setup, audit, and support workflow. The standalone `/companyos/integrations/*` routes consume reusable bundle view-models/templates and require explicit managed vs BYOK choice before configuration:

- Ownership mode badge: cyan `managed` or violet `byok`
- Credential display: always `'********'` — raw values never rendered
- `custodySummary`: existing field name for the credential-handling owner summary (differs by mode)
- `supportContactLabel`: differs by mode (managed → platform support, BYOK → customer-managed)
- `capabilities`: same list per integration regardless of mode

- Security-class routes (`credentials`, `secrets`) are always `force-dynamic`; do not move them to static generation or cache rendered output.
- Rendered output, fixtures, snapshots, logs, and behavior signals may include only redacted credential references such as `********` or opaque `secretref://...` identifiers.
- The configure API route uses verified Better Auth context in production; `x-managed-companyos-session-id` is accepted only in local/test fixture mode. Anonymous and cross-site mutation attempts return deny responses.

## Degraded-state handling

Every page checks `shell.degradedBanner`:
- Present → renders an `aria-live="polite"` amber banner (`role="status"`) with the degraded reason
- Absent → no banner; normal render

`shell.stateCopy` provides all four state strings: `loading`, `empty`, `error`, `degraded`.

## Accessibility and responsiveness

- Page root: `aria-labelledby` tied to the `H1` `id`
- Navigation cards: `aria-label` on container and each article with health status
- Status badges: explicit `aria-label` (e.g. `"Ownership mode: managed"`, `"Health status: healthy"`)
- Degraded banner: `role="status"` + `aria-live="polite"`
- Responsive padding: `p-4 sm:p-8`; card widths: `w-full sm:w-64` or `w-full sm:w-80`
- No raw `<div>`, `<section>`, `<main>`, `<header>` — layout via design-system primitives only

## Design-system rule

Use design-system primitives exclusively:

```ts
// Layout
import { Box, HStack, VStack } from '@lssm-tech/lib.design-system/components/layout';
// Typography
import { H1, H2, P, Text } from '@lssm-tech/lib.design-system/components/typography';
```

No raw HTML markup in app shells. No imports from `@radix-ui/*` or native-only packages in web-only files.

## Environment variables

| Variable | Purpose |
|---|---|
| `NEXT_PUBLIC_WORKER_WS_URL` | Live WebSocket endpoint (`ws://worker.host/ws`); falls back to bundle default if absent |
| `NEXT_PUBLIC_DEFAULT_TENANT_ID` | Default tenant for static renders; falls back to reference tenant |

## Local commands

```bash
bun run --cwd packages/apps/web-application-monolith dev
bun run --cwd packages/apps/web-application-monolith test
bun run --cwd packages/apps/web-application-monolith typecheck
bun run --cwd packages/apps/web-application-monolith lint:check
bun run --cwd packages/apps/web-application-monolith build
```

For the full operator runbook (deploy, start/stop, degraded triage, replay regen, evidence verification), see [`docs/runbooks/managed-companyos.md`](../../../../docs/runbooks/managed-companyos.md).


## Theme & runtime wiring

### CSS

`src/app/globals.css` bootstraps the CSS pipeline: `tailwindcss` + `tw-animate-css`, `@source` globs covering all app and library code, and a cockpit slate/cyan/amber token block. The token block is a temporary home — it will migrate to `@lssm-tech/lib.design-system/styles/tokens.css` in S2.

### Theme provider

`src/app/providers.tsx` wraps children in `ThemeProvider` (`defaultTheme="dark"`, no `enableSystem` — dark-only until S2). The dark class is applied by `next-themes` at hydration; the `:root` tokens are cockpit-dark to minimise any flash.

### PostHog observability

`PostHogProvider` activates only when `NEXT_PUBLIC_POSTHOG_KEY` is set. When absent, no PostHog requests are made and the provider wrapper is omitted. SSR-safe: init runs inside `useEffect` with a `typeof window` guard. When enabled, add `connect-src https://eu.i.posthog.com` to your CSP (S2 concern).

### Global state routes

| Route | File | Type | Notes |
|---|---|---|---|
| `/error` | `src/app/error.tsx` | Client Component | Error boundary — renders `stateCopy.error` + "Try again"; logs `error.digest` only |
| `/loading` | `src/app/loading.tsx` | Server Component | Renders `stateCopy.loading` with `role="status"` |
| `/not-found` | `src/app/not-found.tsx` | Server Component | Renders `stateCopy.empty` + home link |

### Enforcement tests

Three mechanical tests added in S1:
- **`src/__tests__/import-boundaries.test.ts`** — fails CI if `next-themes` or `@posthog/react` appear outside `layout.tsx` / `providers.tsx`.
- **`src/__tests__/raw-color-baseline.test.ts`** — asserts raw Tailwind color class count ≤ 391 (2026-05-16 baseline). S3 target: 0.
- **`src/__tests__/providers.test.tsx`** — asserts `posthog.init` is not called when `NEXT_PUBLIC_POSTHOG_KEY` is unset.

Test infra: `src/__tests__/setup-next-mocks.ts` stubs `next/font/google` for bun's test runner, preloaded via `bunfig.toml`.

## How to add a new route

1. **Define the nav item in bundle**: Create `NavSurfaceItemSpec` in `@lssm-tech/bundle.managed-companyos/src/web-shell.ts`
   ```typescript
   defineNavSurfaceItem({
     id: 'my-feature',
     route: { web: '/companyos/my-feature' },
     capability: { surface: 'navigation', key: 'companyos:my_feature:view' },
     groupKey: 'operations',
     iconKey: 'briefcase',
     densityHint: 'compact',
   })
   ```

2. **Register the capability**: Ensure the capability is registered in `CapabilityRegistry` with `surface: 'navigation'`

3. **Create the page**: `src/app/companyos/my-feature/page.tsx`
   ```typescript
   export const dynamic = 'force-static';

   export default function MyFeaturePage() {
     return <MyFeatureComponent />;
   }

   export const myFeaturePageDocBlock = {
     id: 'my-feature-page',
     title: 'My Feature Page',
     body: '...',
     kind: 'goal',
     route: 'packages/apps/web-application-monolith/src/app/companyos/my-feature/page.tsx',
     visibility: 'public',
   } satisfies DocBlock;
   ```

4. **Emit signals**: In your component, emit behavior signals on mount
   ```typescript
   useEffect(() => {
     const id = crypto.randomUUID();
     void emitCompanyOsBehaviorSignal({
       surfaceId: 'my_feature',
       signal: 'surface_viewed',
       correlationId: id,
       tenantId: 'demo',
       actorKind: 'founder_approver',
     });
   }, []);
   ```

5. **Verify**: `bun run lint:check && bun run lint:signals && bun run typecheck`

## How to add a new persona

1. **Document in PERSONAS.md** (repo root): Define persona responsibilities, default preferences (density/guidance/pace)

2. **Create the home page**: `src/app/companyos/{persona}/page.tsx`
   - Either wrap a candidate template (e.g., `FounderHome` wraps `MissionLandingFunnel`)
   - Or compose custom shell with nav items and module grid

3. **Register nav subset**: In bundle `web-shell.ts`, set `personaVisibility` on nav items
   ```typescript
   defineNavSurfaceItem({
     // ...
     personaVisibility: {
       founder_approver: true,
       operations_manager: false,
       // ...
     }
   })
   ```

4. **Update persona dispatcher**: Modify `/companyos/page.tsx` to route to new persona home

5. **Add E2E test**: Create Playwright test for persona happy-path (signin → home → navigate → signout)

## Thin app shell

This app follows the [package-architecture layering rules](../../.claude/rules/package-architecture.md): apps stay thin by composing bundles, not owning shared UI.

Thin-shell rule is **active**. The `src/components/` directory is **intentionally absent** — all 427+ shared React components have been migrated to `packages/bundles/managed-companyos/src/ui/<domain>/` via PR series `chore/migration/slice-*` (Slices 1–13).

**Do not recreate `src/components/`.** All shared UI belongs in the bundle's `./ui` subpath, imported as `@lssm-tech/bundle.managed-companyos/ui` or `@lssm-tech/bundle.managed-companyos/ui/<domain>`. Boundary rules enforce this at error level in CI.

## Integration Points

### Embedding Managed CompanyOS Surfaces

The web app exposes individual screens as React Server Components that can be embedded in other Next.js applications:

```typescript
import { CompanyOsOnboarding } from '@lssm-tech/app.web-application-monolith/companyos/onboarding';

// Embed in another app's page
export default function AdminPanel() {
  return <CompanyOsOnboarding tenantId="tenant_xyz" />;
}
```

Each screen route (`/companyos/*`) is independently renderable and passes tenant context through layout context/props.

### API Dependency

All screens fetch data from the API app via fetch:

```typescript
// Inside a screen component
const response = await fetch('/api/companyos/workspace', {
  headers: { 'x-managed-companyos-session': sessionToken }
});
const workspace = await response.json();
```

The web app assumes the API is available at the same origin. For separate deployments, override `NEXT_PUBLIC_API_BASE` env var.

### WebSocket Updates

Screens subscribe to real-time graph updates via the worker app's WebSocket endpoint:

```typescript
const ws = new WebSocket('ws://worker.host/ws?tenantId=tenant_id');
ws.onmessage = (event) => {
  // Updates trigger UI refresh via server components or client-side state
};
```

Override with `NEXT_PUBLIC_WORKER_WS_URL` env var.

### MCP Integration

For AI agents and CLI tools that need to read Managed CompanyOS state without opening the web UI, use the planned `@lssm-tech/app.managed-companyos-mcp` server. It exposes tenant graph queries, approval lists, replay packets, and evidence receipts as MCP tools and resources.

## Environment

Copy `deploy/env/web.env.example` into the deployment secret-manager backed environment group. Public values may identify API/worker endpoints, but raw provider credentials never belong in web env files.


---

## @lssm-tech/app.worker-application-monolith

Description: (none)
Path: packages/apps/worker-application-monolith
URL: /llms/app.worker-application-monolith

# Managed CompanyOS Worker Application Monolith

VPS-suitable Bun worker and WebSocket runtime for Managed CompanyOS background jobs. It publishes deterministic operating-graph snapshots, tracks worker supervision health, and keeps all job projection side-effect-free until production queue, persistence, and provider adapters are approved.

No queue, provider, network, or credential side effects start at module load. The runtime starts only through `bun src/server.ts` / `bun run start`.

## Special Ops projection contract

The worker-side Special Ops production contract is documented in [`docs/runbooks/special-ops-monolith-production.md`](../../../docs/runbooks/special-ops-monolith-production.md). Worker projections must consume a repository-compatible tenant/workspace/capability snapshot, preserve correlation IDs across jobs, WebSocket events, replay, and evidence, and surface degraded/stale Special Ops state instead of hiding it behind a green worker response.

## Runtime surface

| File | Purpose |
|---|---|
| `src/server.ts` | Bun HTTP + WebSocket runtime; all route handlers and WebSocket server |
| `src/index.ts` | Deterministic job projection: worker runtime, job lifecycle, correlation ID proof, degraded-state evaluation, idempotency store |
| `src/live-client.ts` | WebSocket client with exponential-backoff reconnect for proof and monitoring |

## HTTP endpoints

| Method | Path | Query params | Response |
|---|---|---|---|
| `GET` | `/health` | `tenantId`, `degraded`, `lastSyncMs`, `nowMs`, `staleAfterMs` | `ManagedCompanyOsWebSocketMessage` (200) |
| `GET` | `/graph-snapshot` | `tenantId`, `idempotencyKey`, `degraded`, `lastSyncMs`, `nowMs`, `staleAfterMs` | `ManagedCompanyOsWebSocketMessage` (200) |
| `GET` | `/worker-supervision` | `tenantId`, `degraded`, `nowMs`, `lastSyncMs`, `staleAfterMs` | `ManagedWorkerSupervisionHealth` (200) |
| `WS` | `/ws` | `tenantId` | Upgrades to WebSocket; emits `ManagedCompanyOsWebSocketMessage` on open and each message |

Unknown paths return `{ error: "…" }` with status 404.

## Worker supervision health

`GET /worker-supervision` returns a `ManagedWorkerSupervisionHealth` object:

| Field | Type | Meaning |
|---|---|---|
| `alive` | `boolean` | `true` when proof is healthy and not stale |
| `last_heartbeat_at` | `string` (ISO 8601) | Timestamp of the latest worker run |
| `in_flight_jobs` | `number` | Count of jobs still in `queued` or `running` state |
| `stale_job_count` | `number` | Count of jobs marked `stale` |
| `replay_freshness` | `'fresh' \| 'stale' \| 'degraded'` | Replay output health |
| `websocket_connected` | `boolean` | `false` when proof is degraded or stale |

## WebSocket message schema

Every `/ws` push and `/graph-snapshot` response is a `ManagedCompanyOsWebSocketMessage`:

```ts
{
  type: 'managed-companyos.graph.snapshot';
  tenantId: string;
  correlationId: string;        // links jobs, replay events, and evidence receipt
  nodeCount: number;
  edgeCount: number;
  replayEventCount: number;
  replayEventIds: readonly string[];
  evidenceReceiptId: string;
  workerJobIds: readonly string[];
  workerStatus: 'queued' | 'running' | 'completed' | 'degraded' | 'stale';
  degraded: boolean;
  stale: boolean;
  idempotentReplay: boolean;    // true when the same idempotencyKey was replayed
  degradedReasons: readonly string[];
}
```

## WebSocket event stream

`projectWorkerWebSocketEvents(proof)` projects the worker proof into an ordered sequence of typed events. All events carry `correlationId` and `sequence`:

| Event type | Payload extras | When emitted |
|---|---|---|
| `job-started` | `jobId`, `kind`, `status: 'queued'` | Each job enters queued state |
| `job-progress` | `jobId`, `kind`, `status: 'running'` | Each job transitions to running |
| `job-completed` | `jobId`, `kind`, `status: 'completed'`, `degraded: false` | Job succeeds |
| `job-failed` | `jobId`, `kind`, `status: 'degraded'\|'stale'`, `degraded: true` | Job fails or goes stale |
| `replay-emitted` | `replayEventId` | Each replay event in the proof |
| `evidence-issued` | `evidenceReceiptId`, `verificationHash` | Evidence receipt issued |

Events are ordered by ascending `sequence` numbers. Degraded proofs emit `job-failed` instead of `job-completed`.

## Worker job inventory

| Job kind | Purpose |
|---|---|
| `integration_sync` | Integration provider sync (side-effect-free until provider approved) |
| `replay_generation` | Deterministic replay packet generation from workspace state |
| `evidence_generation` | Evidence receipt derivation from replay events; receipt carries `verificationHash` |
| `websocket_graph_update` | Publishes graph snapshot to connected WebSocket clients |

Job lifecycle: `queued` → `running` → `completed` (healthy) or `degraded` / `stale` (unhealthy).

## Correlation ID contract

A single `correlationId` links the entire proof chain:

```
proof.correlationId
  == each job.correlationId
  == each WS event.correlationId
  == each replay event.correlationId
  == evidenceReceipt.correlationId
```

Validate with `assertManagedWorkerCorrelation(proof)` — returns `{ valid: boolean, reasons: string[] }`.

## Degraded-state detection

The runtime surfaces degraded and stale conditions instead of hiding them behind healthy status:

| Condition | Trigger | Effect |
|---|---|---|
| Forced degraded | `?degraded=true` query param | All jobs report `degraded`; supervision `alive: false` |
| Stale sync | `nowMs - lastSyncMs > staleAfterMs` | All jobs report `stale`; supervision `stale_job_count = 4`, `replay_freshness: 'stale'` |
| Bundle health degraded | Propagated from `@lssm-tech/bundle.managed-companyos` | `degradedReasons` populated; supervision `alive: false` |

A green API response with a degraded worker is a contract regression — the `/health/degraded` API route returns HTTP 503 when worker or WebSocket health is impaired.

## Stale-job cleanup and idempotency

The deterministic in-memory store (`createDeterministicManagedWorkerStore`) enforces idempotency:

- A run with the same `idempotencyKey` returns the cached proof with `idempotentReplay: true`.
- Stale jobs are counted and surfaced — they are not silently discarded.
- Pass a fresh `idempotencyKey` to force a new run: `GET /graph-snapshot?idempotencyKey=fresh-key-001`

## WebSocket reconnect client

```ts
import { connectManagedCompanyOsLiveClientWithReconnect } from './src/live-client';

const proof = await connectManagedCompanyOsLiveClientWithReconnect({
  url: 'ws://worker.host/ws?tenantId=tenant_id',
  maxAttempts: 3,       // default: 3
  initialBackoffMs: 100, // default: 100ms; doubles each retry (100 → 200 → 400)
  timeoutMs: 1000,      // per-attempt timeout; default: 1000ms
});
// proof.connected, proof.attempts, proof.lastBackoffMs, proof.message
```

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `MANAGED_COMPANYOS_WORKER_HOST` | `0.0.0.0` | Bind address for the HTTP/WebSocket server |
| `MANAGED_COMPANYOS_WORKER_PORT` | `8787` | Bind port |
| `MANAGED_COMPANYOS_DEFAULT_TENANT_ID` | `tenant_managed_companyos_reference` | Fallback tenant when `tenantId` query param is absent |

Copy `deploy/env/worker.env.example` to `/etc/managed-companyos/worker.env` and fill values from the secret manager. Never write raw provider credentials to logs, fixtures, or API responses.

## Local commands

```bash
bun run --cwd packages/apps/worker-application-monolith dev
bun run --cwd packages/apps/worker-application-monolith test
bun run --cwd packages/apps/worker-application-monolith typecheck
bun run --cwd packages/apps/worker-application-monolith lint:check
bun run --cwd packages/apps/worker-application-monolith build
```

Build output: `dist/index.js` (Bun target). Production start: `bun dist/index.js`.

## Integration Points

### WebSocket Client Integration

External systems receive real-time graph updates by connecting a WebSocket client to `/ws`:

```typescript
import { connectManagedCompanyOsLiveClientWithReconnect } from '@lssm-tech/app.worker-application-monolith/src/live-client';

const proof = await connectManagedCompanyOsLiveClientWithReconnect({
  url: 'ws://worker.host/ws?tenantId=tenant_123',
  maxAttempts: 3,
  initialBackoffMs: 100, // doubles each retry
  timeoutMs: 1000
});

// proof.message is ManagedCompanyOsWebSocketMessage
// proof.connected indicates success
```

Each message carries a `correlationId` that links to API requests, replay packets, and evidence receipts.

### Health Polling

External monitoring can poll worker health via HTTP:

```bash
# Instant health snapshot (no stale-job cleanup)
curl http://worker.host/health?tenantId=tenant_id

# Worker supervision health (includes job/replay/WebSocket metrics)
curl http://worker.host/worker-supervision?tenantId=tenant_id

# Graph snapshot (deterministic projected state)
curl http://worker.host/graph-snapshot?tenantId=tenant_id&idempotencyKey=key_xyz
```

A degraded worker returns `{ degraded: true, degradedReasons: [...] }`. The API's `/health/degraded` route returns HTTP 503 when worker health is impaired, preventing callers from seeing green API status while worker is red.

### MCP Tool Integration

For AI agents, the planned `@lssm-tech/app.managed-companyos-mcp` server exposes worker health, job status, replay packet fetching, and evidence verification as MCP tools. Agents can query job state and fetch replay/evidence receipts without holding open a WebSocket connection.

## Correlation ID Guarantees

Every worker run produces a `correlationId` that persists across:
- Job execution (`job.correlationId`)
- WebSocket messages (`ManagedCompanyOsWebSocketMessage.correlationId`)
- Replay events (`replayEvent.correlationId`)
- Evidence receipts (`evidenceReceipt.correlationId`)

Validate the full chain with `assertManagedWorkerCorrelation(proof)` in production health checks.

Build output: `dist/index.js` (Bun target). Production start: `bun dist/index.js`.

For the full operator runbook (deploy, start/stop, degraded triage, replay regen, evidence verification), see [`docs/runbooks/managed-companyos.md`](../../../../docs/runbooks/managed-companyos.md).


---

## @lssm-tech/app.worker-data-transmission-realtime

Description: (none)
Path: packages/apps/worker-data-transmission-realtime
URL: /llms/app.worker-data-transmission-realtime

# `@lssm-tech/app.worker-data-transmission-realtime`

Bun WebSocket worker for the Data Transmission CRDT realtime proof.

This worker is intentionally ephemeral: no durable production database, no multi-region guarantees, no managed-service SLA, and no Vercel Functions WebSocket hosting. It exists to prove ContractSpec realtime contracts, runtime guardrails, and demo collaboration flow with bounded public-demo controls.


---

## @lssm-tech/example.shim-delete-ci

Description: CI test that verifies promoted symbols are importable from canonical locations (B2/B3). When this test passes it is safe to delete the example shims.
Path: packages/examples/__tests__
URL: /llms/example.shim-delete-ci

(No README.md)

---

## @lssm-tech/example.agent-console

Description: Agent Console example - AI agent orchestration with tools, runs, and logs
Path: packages/examples/agent-console
URL: /llms/example.agent-console

# @lssm-tech/example.agent-console

Website: https://contractspec.io

**Agent Console example - AI agent orchestration with tools, runs, and logs.**

## What This Demonstrates

- **Rich Landing Screen**: Product introduction explaining agent management concepts, demo path, and navigation.
- **Navigation Rail**: Clear sidebar navigation between Overview, Agent Fleet, Tool Registry, Run History, Metrics, and Proof.
- **Agent Entity**: Full lifecycle management with status tracking (draft, active, paused, retired).
- **Run Tracking**: Event-driven execution with status enums and state transitions.
- **Tool Registry**: Typed schemas and operation handlers for agent capabilities.
- **Contract-Backed Visualizations**: Charts and metrics derived from run activity.
- **Deterministic Replay**: Offline-safe demo runtime with proof evidence.
- **Presentation Layer**: React UI components, hooks, modals, overlays, and DataTable for run history.
- **Multi-Surface Output**: Markdown and React renderers for different contexts.
- **Seeded Local Data**: Mock agents, tools, and runs for immediate demo usage.

## Canonical Demo Path

- Default sandbox route: `/sandbox`
- Explicit sandbox route: `/sandbox?template=agent-console`
- Proof artifact: `packages/examples/agent-console/proofs/agent-console-meetup.replay.json`

The canonical walkthrough is deterministic and local-first:

1. **Landing Screen** - Start on the product introduction explaining agent management concepts.
2. **Navigation** - Use the sidebar rail to navigate between sections.
3. **Agent Fleet** - Inspect seeded agents (Customer Support Bot, Code Review Assistant, Data Analyst, Meeting Scheduler).
4. **Tool Registry** - Browse available tools and their schemas.
5. **Run History** - View execution history with status and metrics.
6. **Metrics** - See contract-backed visualizations of run activity.
7. **Proof** - Inspect deterministic replay evidence.

### New Features

- **LandingScreen**: Product-style introduction with value proposition and demo path.
- **AgentConsolePreviewV2**: Enhanced preview with sidebar navigation and dedicated screens.
- **AgentConsoleNav**: Navigation rail for moving between sections.
- **Navigation**: Clear paths from landing to specific agent, tool, and run views.

## Runtime Boundaries

- React hooks and the sandbox use `createAgentConsoleDemoHandlers(...)` for the meetup path.
- Markdown renderers prefer runtime-fetched data and fall back to the same deterministic demo handlers.
- The demo runtime is intentionally mocked and offline-safe by default.
- Database-backed `createAgentHandlers(db)` remains available for non-demo runtime wiring.

## Running Locally

From `packages/examples/agent-console`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run proof`
- `bun run typecheck`
- `bun run preflight`

From the repository root:
- `bun run meetup:agent-console:policy`
- `bun run meetup:agent-console:proof`
- `bun run meetup:agent-console:preflight`

## Usage

Use `@lssm-tech/example.agent-console` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/agent` is part of the package's public or composition surface.
- `src/agent.capability.ts` defines a capability surface.
- `src/agent.feature.ts` defines a feature entrypoint.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/proof/` contains the exported meetup proof scenario and suite.
- `src/ui/AgentConsolePreview.tsx` is the cross-platform preview component used by web and mobile example surfaces.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./agent` resolves through `./src/agent/index.ts`.
- Export `./agent.capability` resolves through `./src/agent.capability.ts`.
- Export `./agent.feature` resolves through `./src/agent.feature.ts`.
- Export `./agent/agent.entity` resolves through `./src/agent/agent.entity.ts`.
- Export `./agent/agent.enum` resolves through `./src/agent/agent.enum.ts`.
- Export `./agent/agent.event` resolves through `./src/agent/agent.event.ts`.
- Export `./agent/agent.handler` resolves through `./src/agent/agent.handler.ts`.
- Export `./agent/agent.operation` resolves through `./src/agent/agent.operation.ts`.
- Export `./agent/agent.presentation` resolves through `./src/agent/agent.presentation.ts`.
- Export `./proof` resolves through `./src/proof/index.ts`.
- Export `./proof/meetup-proof.scenario` resolves through `./src/proof/meetup-proof.scenario.ts`.
- Export `./proof/meetup-proof.suite` resolves through `./src/proof/meetup-proof.suite.ts`.
- The package publishes 72 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run proof` — bun ../../../scripts/generate-agent-console-meetup-proof.ts
- `bun run preflight` — bun run build && bun run typecheck && bun run test && bun ../../../scripts/check-agent-console-meetup-policy.ts && bun run proof
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Unified the meetup demo around a single seeded runtime.
- Added focused handler tests, a sandbox smoke test, and a harness replay proof.
- Added a slice-scoped meetup preflight instead of relying on the repo-wide policy backlog.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.runtime-sandbox`, `@lssm-tech/lib.schema`, ...


---

## @lssm-tech/example.agent-workflow-command-center

Description: Agent Workflow Command Center - All-in-one operator cockpit for supervised AI agents in business workflows
Path: packages/examples/agent-workflow-command-center
URL: /llms/example.agent-workflow-command-center

# @lssm-tech/example.agent-workflow-command-center

Website: https://contractspec.io

**Agent Workflow Command Center - All-in-one operator cockpit for supervised AI agents in business workflows.**

## What This Demonstrates

Agent Workflow Command Center is a ContractSpec example for operating supervised AI agents inside business workflows. It combines:

- **Agent Management:** Fleet overview, configuration, tool permissions, lifecycle controls
- **Workflow Orchestration:** State-machine workflows with agent assignments
- **Human Review:** Review queue with approve/reject/escalate actions
- **Governance:** Tool policies, risk thresholds, blocked actions
- **Audit Trail:** Complete event timeline with deterministic evidence
- **ROI & Handover:** Adoption metrics and handover readiness checklist

## Business Scenario

A PME industrielle (85 employees) undergoing finance transformation:

- Finance team under pressure with RAF departure
- Cash tension and reporting delays
- Fragmented Excel/BI tooling
- Weak or outdated finance procedures

NDconsulting installs supervised AI-assisted workflows and helps the client operate the system after handover.

## Core Demo Message

"ContractSpec delivers a controllable operating system where the client team can:
- Manage agents and assign them to workflows
- Review AI-generated outputs before operational use
- Enforce governance policies and block risky actions
- Inspect audit logs and track adoption/ROI
- Prove what happened through deterministic evidence"

## Included Agents

1. **Cash Aging Agent** - Prioritizes receivables follow-up using deterministic aging rules
2. **Reporting Narrative Agent** - Drafts reporting commentary with variance analysis
3. **Procedure Draft Agent** - Structures finance procedures with roles and controls
4. **Mission Intake Agent** - Triages transformation requests and classifies urgency
5. **AI Adoption Coach** - Tracks use cases and ROI without employee surveillance

## Workflows

1. **Cash Recovery Prioritization** - Intake → Agent Analysis → Human Review → Approved/Changes Requested
2. **Monthly Reporting Narrative** - Data Input → Narrative Draft → Variance Review → Finalization
3. **Finance Procedure Drafting** - Request → Procedure Structure → Control Review → Publication
4. **Mission Intake Triage** - Request → Classification → Priority Assignment → Follow-up
5. **AI Adoption / ROI Logging** - Usage Event → Impact Calculation → Trend Analysis

## Canonical Demo Path

1. Open `/sandbox?template=agent-workflow-command-center`
2. Start on the Landing screen - understand the value proposition
3. Enter the Command Center Overview - see active agents and workflows
4. Inspect the Cash Aging Agent - review allowed tools and governance
5. Open the Cash Recovery workflow - see state machine
6. Assign the Cash Aging Agent to the workflow
7. Trigger a deterministic agent run
8. Inspect run logs and emitted events
9. Open the review queue
10. Approve one recommendation, request changes on another
11. Show workflow state transition
12. Simulate a high-risk tool call - show it's blocked
13. Pause an agent, then resume after policy review
14. Open ROI & Handover - generate checklist
15. Export or display replay/audit proof

## Replay Proof

The `./proof` export now exposes a deterministic replay contract for the canonical Managed CompanyOS journey:

- `happyPath`: create/configure a synthetic agent, assign a deterministic tool, compose a review-gated workflow, dispatch a simulator run, submit human approval, and inspect audit replay evidence.
- `blockedPath`: request a high-risk external tool and attempt a run with that blocked tool; both events must stay authorization-required with no external side effect.
- `managedCompanyOsRouteRefs`: documents app-relative `pillarRoute` values and host-prefixed `hostRoute` values for agent, tool, and workflow managed surfaces without importing the managed bundle at runtime.
- `atomicCrudCoverage`: proves the example covers tool, agent, and workflow list/create/update/detail expectations plus loading, empty, error, denied, read-only, allowed, dirty-invalid, review-required, and blocked states.
- `assertCommandCenterReplayProof()` validates stable audit event IDs, evidence refs, correlation IDs, a human-review gate, a blocked path, and redacted/synthetic-only proof metadata.


## Tool Management Loop

The command-center preview includes a Tools surface that demonstrates the full controlled loop: create/edit/archive deterministic tools, inspect governance readiness, assign tools to demo agents or host-owned workflow projections, and simulate calls with audit/replay evidence. The demo uses `@lssm-tech/module.agent-fleet` reusable presentation contracts with local state only; it performs no provider, network, backend, ERP, email, payment, or secret-storage side effects.

## Safety Boundaries

- All agent outputs require human review before operational use
- No real emails, payment instructions, or accounting entries sent
- No connection to live finance systems
- Synthetic fixtures only - no real client or financial data
- Deterministic and offline-safe
- Drafts/recommendations only, not operational commands
- Tracks workflow ROI, not intrusive employee surveillance

## Core Entities

- **AgentProfile** - Agent configuration, status, autonomy level, allowed tools
- **WorkflowTemplate** - Workflow definitions with steps and transitions
- **WorkflowInstance** - Running workflow with current state and assignments
- **AgentAssignment** - Links agents to workflow steps
- **AgentRun** - Execution record with inputs, outputs, events
- **HumanReview** - Review queue with decisions and feedback
- **ToolPolicy** - Governance rules for tool usage
- **AuditEvent** - Immutable event log
- **AdoptionMetric** - ROI and usage tracking

## Public Entry Points

- Export `.` resolves through `./src/index.ts`
- Export `./agent` resolves through `./src/agent/index.ts`
- Export `./workflow` resolves through `./src/workflow/index.ts`
- Export `./review` resolves through `./src/review/index.ts`
- Export `./governance` resolves through `./src/governance/index.ts`
- Export `./fixtures` resolves through `./src/fixtures/index.ts`
- Export `./proof` resolves through `./src/proof/index.ts`
- Export `./ui` resolves through `./src/ui/index.ts`
- Export `./example` resolves through `./src/example.ts`
- Export `./docs` resolves through `./src/docs/index.ts`

## Code Quality Review

Review date: 2026-05-20.

- The example package exposes deterministic domain, fixture, proof, UI, example, and docs surfaces; the root export also re-exports `./docs` for consumers that import the aggregate package.
- Preview screens render from static PME finance fixtures and do not call live LLM, ERP, CRM, BI, email, payment, or accounting systems. Provider names in the fixture are labels only.
- Governance and human-review screens are part of the default demo path, so supervised operation is visible before ROI or handover claims.
- Replay proof stays under `src/proof/` and should be extended with any new workflow path before release.

## Production readiness evidence

Use [`docs/agent-workflow-command-center-production-readiness.md`](../../../docs/agent-workflow-command-center-production-readiness.md) as the release-facing checklist for the boil-lake command-center slice. It defines the promotion gates, verification command matrix, redaction/import-boundary proof, replay determinism evidence, and authority gates that must be attached before claiming production readiness.

## Validation Checklist

Before publishing changes to this template, run from `packages/examples/agent-workflow-command-center`:

1. `bun run lint:check` - package lint and formatting gate
2. `bun run typecheck` - public TypeScript entrypoint validation, including `./docs`
3. `bun run test` - preview shell and adaptive agent-fleet DataView tests
4. Open `/sandbox?template=agent-workflow-command-center` and follow the canonical demo path

## Local Commands

- `bun run dev` - Development build
- `bun run build` - Production build
- `bun run test` - Run tests
- `bun run typecheck` - TypeScript check
- `bun run lint` - Lint and fix
- `bun run preflight` - Full validation

## Architecture

- `src/agent/` - Agent profile domain
- `src/workflow/` - Workflow template and instance domain
- `src/review/` - Human review domain
- `src/governance/` - Tool policies and governance
- `src/fixtures/` - Synthetic demo data
- `src/proof/` - Replay evidence
- `src/ui/` - Preview components and screens

## Notes

Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.schema`.

### Tool Effects

The Tools screen demonstrates typed tool effects: `contract_effect` entries select a ContractSpec operation, and `integration_effect` entries select an already-integrated provider catalog item. The example validates and simulates effects deterministically by default. Real execution is represented as an explicit adapter boundary so the template stays secret-free and provider/network-free unless a host wires an adapter deliberately.

### Tool Effect Workbench

The Tools screen now demonstrates a decision-quality operation workbench for tool effects. Operators can inspect richer ContractSpec and integration-call fixtures, compare candidates, configure input mappings, validate readiness, and simulate deterministically before saving. Real execution remains an explicit host-adapter boundary so the example stays provider-free, backend-free, and secret-free by default.


---

## @lssm-tech/example.ai-chat-assistant

Description: Focused AI chat assistant template with MCP tools, reasoning, chain of thought, sources, and suggestions.
Path: packages/examples/ai-chat-assistant
URL: /llms/example.ai-chat-assistant

# @lssm-tech/example.ai-chat-assistant

Website: https://contractspec.io

**Focused AI chat assistant example with MCP tools, reasoning, sources, suggestions, and reusable dashboard UI.**

## What This Demonstrates

- Demonstrates how `@lssm-tech/module.ai-chat` can power a focused assistant experience.
- Publishes feature, contracts, handlers, docs, example, and dashboard UI entrypoints.
- Provides a search-backed, source-aware assistant template for example consumers and docs.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/ai-chat-assistant`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run smoke`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.ai-chat-assistant` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/ai-chat-assistant.feature.ts` defines the example feature surface.
- `src/contracts/` contains the assistant operation contract exports.
- `src/handlers/` contains the demo assistant handlers wired to the example feature.
- `src/ui/` contains the packaged dashboard UI for embedding or demonstration.
- `src/docs/` and `src/example.ts` provide docblock and runnable example entrypoints.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Exports the feature surface, contract barrels, handlers, docs entrypoints, runnable example, and dashboard UI.
- Export `.` resolves through `./src/index.ts`.
- Export `./ai-chat-assistant.feature` resolves through `./src/ai-chat-assistant.feature.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./contracts/assistant.operation` resolves through `./src/contracts/assistant.operation.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/ai-chat-assistant.docblock` resolves through `./src/docs/ai-chat-assistant.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./handlers/assistant.handlers` resolves through `./src/handlers/assistant.handlers.ts`.
- Export `./ui` resolves through `./src/ui/index.ts`.
- The package publishes 11 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run smoke` — bun test src/example.smoke.test.ts
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Vnext ai-native.

## Notes

- Works alongside `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/module.ai-chat`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.ai-support-bot

Description: AI support bot example: classify and resolve a support ticket using @lssm-tech/lib.support-bot.
Path: packages/examples/ai-support-bot
URL: /llms/example.ai-support-bot

# @lssm-tech/example.ai-support-bot

Website: https://contractspec.io

**AI support bot example: classify and resolve a support ticket using @lssm-tech/lib.support-bot.**

## What This Demonstrates

- Ticket classification pipeline with AI-driven resolution.
- Integration of support-bot lib with knowledge base.
- DocBlock documentation for in-app help.
- Setup and example entry points for quick cloning.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/ai-support-bot`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.ai-support-bot` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/ai-support-bot.feature.ts` defines a feature entrypoint.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/setup.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./ai-support-bot.feature` resolves through `./src/ai-support-bot.feature.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/ai-support-bot.docblock` resolves through `./src/docs/ai-support-bot.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./setup` resolves through `./src/setup.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.knowledge`, `@lssm-tech/lib.logger`, `@lssm-tech/lib.support-bot`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.analytics-dashboard

Description: Analytics Dashboard example with widgets and query engine for ContractSpec
Path: packages/examples/analytics-dashboard
URL: /llms/example.analytics-dashboard

# @lssm-tech/example.analytics-dashboard

Website: https://contractspec.io

**Analytics Dashboard example with widgets and query engine for ContractSpec.**

## What This Demonstrates

- Dashboard feature with presentation, schema, enum, and test-spec.
- Query engine with typed operations and handlers.
- PostHog datasource adapter.
- React UI with hooks, renderers, markdown output, and a shared ContractSpec `DataTable` for saved queries.
- Client-mode table capabilities including sorting, pagination, column visibility, column resizing, pinning, and expandable row details.
- Event definitions for analytics tracking.
- Seeders for demo data.

## Running Locally

From `packages/examples/analytics-dashboard`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.analytics-dashboard` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/dashboard` is part of the package's public or composition surface.
- `src/dashboard.feature.ts` defines a feature entrypoint.
- `src/datasource` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./dashboard` resolves through `./src/dashboard/index.ts`.
- Export `./dashboard.feature` resolves through `./src/dashboard.feature.ts`.
- Export `./dashboard/dashboard.enum` resolves through `./src/dashboard/dashboard.enum.ts`.
- Export `./dashboard/dashboard.operation` resolves through `./src/dashboard/dashboard.operation.ts`.
- Export `./dashboard/dashboard.presentation` resolves through `./src/dashboard/dashboard.presentation.ts`.
- Export `./dashboard/dashboard.schema` resolves through `./src/dashboard/dashboard.schema.ts`.
- Export `./dashboard/dashboard.test-spec` resolves through `./src/dashboard/dashboard.test-spec.ts`.
- Export `./datasource/posthog-datasource` resolves through `./src/datasource/posthog-datasource.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- The package publishes 37 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add data visualization capabilities.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.runtime-sandbox`, ...


---

## @lssm-tech/example.app-submission-readiness-mobile-proof

Description: Deterministic ReviewReady proof that audits the real brownfield Expo app packages/apps/mobile-monolith.
Path: packages/examples/app-submission-readiness-mobile-proof
URL: /llms/example.app-submission-readiness-mobile-proof

# @lssm-tech/example.app-submission-readiness-mobile-proof

Deterministic ReviewReady proof that audits the **real** Expo app at
`packages/apps/mobile-monolith` and emits a stable readiness report.

This proves ReviewReady works on a real brownfield mobile app, not a toy
fixture: the proof **reads and parses the actual mobile-monolith source files
from disk** at run time, maps them into the runtime's audit input, and runs
`@lssm-tech/lib.app-submission-readiness-runtime`. If the real app config
changes, the parsers pick it up and the inline expected values in the test will
catch the drift.

## Real files it reads

`parse-mobile-monolith.ts` reads these files via `node:fs` (no Expo execution,
no mutation):

| Source file | Parsed signal |
| --- | --- |
| `app.config.ts` | app name `ContractSpec`, version `0.1.1`, iOS bundle id `io.contractspec.expo-demo`, Android package `io.contractspec.expo_demo`, privacy/support/terms URLs, `usesNonExemptEncryption` |
| `eas.json` | credential-free `submit.production` posture |
| `ios/ContractSpec/PrivacyInfo.xcprivacy` | `NSPrivacyTracking=false`, collected-data-type count, accessed-API-type categories |
| `ios/ContractSpec/Info.plist` | `ITSAppUsesNonExemptEncryption`, ATS keys, usage-description keys |
| `assets/{icon,adaptive-icon,splash-icon}.png` | asset presence detection |

The plist files are parsed with a focused `<key>…</key>` extractor (no heavy
plist dependency for a proof).

## Honest gaps surface as findings

Declared-in-repo items are `pass`; genuinely absent submission materials become
real findings:

- `legal.account-deletion` — no account-deletion URL in the Expo config.
- `assets.screenshots.store` — `assets/` holds only icon/adaptive-icon/splash.
- `review.google.dataSafety` — no Google Play Data Safety answers in repo.

## Deterministic outcome

Fixed `checkedAt = 2026-06-07T00:00:00.000Z`, fixed ids, no `Date.now()` /
`Math.random()`. Current real audit outcome:

- decision: `blocked`
- score: `60`
- findings: `3`
- stores: `apple-app-store`, `google-play` (`store: "both"`)

## Usage

```ts
import {
	buildMobileMonolithReadinessReport,
	describeMobileMonolithProof,
} from "@lssm-tech/example.app-submission-readiness-mobile-proof";

console.log(describeMobileMonolithProof());
const { report } = buildMobileMonolithReadinessReport();
console.log(report.decision, report.score);
```

## Verify

```bash
cd packages/examples/app-submission-readiness-mobile-proof
tsgo --noEmit
bun test
```

The proof asserts: real parsed values, real findings for absent materials,
deterministic deep-equality across two runs, no secret-like strings in the
serialized report, and inline expected decision/score/finding ids.


---

## @lssm-tech/example.authos-command-center

Description: Rich AuthOS command center template for identity, MFA, organizations, Better Auth bridge planning, and Connect with LSSM.
Path: packages/examples/authos-command-center
URL: /llms/example.authos-command-center

# AuthOS Command Center

Rich ContractSpec example for AuthOS capabilities: identity, sign-in, MFA, OTP, phone/profile/security settings, organization/team/admin, Better Auth bridge planning, and Connect with LSSM account linking.

The example is deterministic and credential-free. It composes AuthOS contracts, runtime projections, the Better Auth bridge, and the reusable AuthOS module; it does not implement a bespoke authentication engine.

```bash
bun run preflight
```


---

## @lssm-tech/example.authos-user-relation-graph

Description: Entity-relation graph example built on Layer-2 defineContractEntity + defineContractEdge — RBAC structure (User ↔ Role ↔ Resource)
Path: packages/examples/authos-user-relation-graph
URL: /llms/example.authos-user-relation-graph

# @lssm-tech/example.authos-user-relation-graph

**Entity-relation graph example built on Layer-2 `defineContractEntity` + `defineContractEdge`. Models an RBAC structure: User ↔ Role ↔ Resource.**

## What This Demonstrates

- Defining a `DataViewGraphSpec` with an `entity-declarative` graph source.
- Using `defineContractEntity` and `defineContractEdge` to describe nodes and edge types.
- Modeling a simple RBAC graph: User → has Role → grants access to Resource.

## Running Locally

From `packages/examples/authos-user-relation-graph`:

```bash
bun run typecheck
```

## Architecture

- `src/index.ts` — root public barrel and package entrypoint.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`.
- Blocked on P1-RECON/B (Layer-2 `defineContractEntity`). Full `DataViewGraphSpec` export lands in task P5/W5.C.


---

## @lssm-tech/example.billingos-france-sme

Description: Smallest BillingOS French SME quote-to-cash replay proof without providers or production PA submission.
Path: packages/examples/billingos-france-sme
URL: /llms/example.billingos-france-sme

# BillingOS V0 package

Additive BillingOS V0 surface. Core contracts stay country-neutral; France-specific readiness lives only in `@lssm-tech/lib.billing-france`. Runtime helpers are deterministic, backend-neutral, provider-free, and do not execute high-impact billing actions.

France readiness metadata is not PA accreditation, production PA submission, legal advice, or tax advice.

## CompanyOS module proof

The example exports `./companyos` as a first-class CompanyOS V1 operating-loop composition for BillingOS France SME. It models finance-owner authority, draft/dry-run-only agent operations, operator inbox routing, work graph hooks, and weekly review evidence around the replayed quote -> invoice -> payment -> France readiness path. Production invoice submission and France e-invoicing submission stay approval-gated; the module contains no provider credentials, network calls, or autonomous high-impact execution.

## Preview / export workflow

BillingOS France SME previews must stay deterministic, backend-neutral, provider-free, and approval-gated. The current `./ui` export wraps local quote-to-invoice, payment/reconciliation, France readiness, and CompanyOS approval-packet screens in the shared `NestedCommandShell` from `@lssm-tech/lib.example-shared-ui`; keep that reusable nested-safe shell as the outer preview frame for compatible BillingOS UI work. Preview screens must not introduce production PA submission, provider credentials, payment processing, legal/tax advice, or autonomous high-impact billing execution.

Keep the France readiness pack as metadata and replay proof only. Preview docs, release notes, and `/llms*` guidance must repeat that the package is not PA accreditation and does not execute production e-invoicing.

## Data-fetching engine integration

`src/proof/data-fetching-integration.test.ts` proves BillingOS drives the canonical data-fetching engine (`@lssm-tech/lib.contracts-runtime-core` + `@lssm-tech/lib.contracts-runtime-server-rest`) end-to-end without weakening the safety model. All engine wiring lives in that `.test.ts` harness on purpose: the production example files must stay free of `fetch(`/`process.env`/credential literals (enforced by `safety.test.ts`), so the proof uses the real `createRestTransport` driven by an in-memory `fetch` double — deterministic, provider-free, no network.

The proof asserts: the `QueryResultEnvelope` read path (no `422`); one admitted draft mutation via `submitBillingMutation`; the admission gate parametrized over the **entire** `BillingActionKind` union (only `read`/`draft_quote`/`draft_invoice` reach `engine.mutate`; all 11 approval-gated kinds fail closed to a `pending approval` operator-review with no optimistic write); server-wins conflict rollback (never a silent overwrite); and offline queue-then-replay on reconnect.

Two decisions are load-bearing and documented in [`specs/billingos-consumer-guide/09-data-fetching-integration.md`](../../../specs/billingos-consumer-guide/09-data-fetching-integration.md): **draft writes carry no `versionToken` this pass** (the event-log `version` is never mapped to the engine etag), and **pending-approval is not an optimistic / read-your-writes state** (approval-gated actions perform no local write). Production hosts inject a real `Transport`; the example never executes providers or production PA submission.

## UI boundary

The preview UI is intentionally thin. It adapts the French SME fixture data into reusable workspaces from `@lssm-tech/module.billing-os/ui`, including quote creation/editing, invoice review, payment reconciliation, France readiness, and CompanyOS review screens. Example-local UI should stay limited to data mapping and preview shell wiring.


---

## @lssm-tech/example.calendar-google

Description: Google Calendar integration example: list and create events.
Path: packages/examples/calendar-google
URL: /llms/example.calendar-google

# @lssm-tech/example.calendar-google

Website: https://contractspec.io

**Google Calendar integration example: list and create events.**

## What This Demonstrates

- OAuth-based Google Calendar API wiring.
- Event listing and creation flows.
- Sync logic for calendar data.
- Integration provider pattern with ContractSpec contracts.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/calendar-google`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.calendar-google` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/calendar-google.feature.ts` defines a feature entrypoint.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/run.ts` is part of the package's public or composition surface.
- `src/sync.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./calendar-google.feature` resolves through `./src/calendar-google.feature.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/calendar-google.docblock` resolves through `./src/docs/calendar-google.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./run` resolves through `./src/run.ts`.
- Export `./sync` resolves through `./src/sync.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-calendar`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.communication-os

Description: Standalone CommunicationOS examples, fixtures, and replay proof for external adopter flows.
Path: packages/examples/communication-os
URL: /llms/example.communication-os

# @lssm-tech/example.communication-os

Standalone CommunicationOS examples, fixtures, replay proof, and composition adapters. This package consumes public CommunicationOS surfaces as an adopter would, keeps example data out of the module package, and imports reusable UI from `@lssm-tech/module.communication-os/ui`.

## Entry Points

- `.`
- `./docs`
- `./example`
- `./examples`
- `./fixtures`
- `./proof`
- `./contracts`
- `./handlers`
- `./ui`
- `./ui/CommunicationOsPreview`
- `./ui/communication-os-preview.data`
- `./ui/communication-os.types`
- `./communication-os.feature`

## Preview / export workflow

CommunicationOS preview work must keep this package as the source of truth for example fixtures and replay proof. Public preview discovery requires compatible `./example`, `./docs`, `./examples`, `./fixtures`, and `./proof` publish exports before an inline `./ui` surface can be generated.

`./ui` is a thin example adapter: it builds deterministic local communication fixture data and passes it into `@lssm-tech/module.communication-os/ui`. Adapter tests assert that actions/drafts remain review-gated and fixture-owned. Do not duplicate reusable screen components here and do not move example data back into the module package.

The replay proof also covers command-inbox fail-closed behavior: blocked send
commands become persisted inbox evidence with no outbound message, provider
call, credential access, shell execution, or external mutation.

## Commands

- `bun run test`
- `bun run typecheck`
- `bun run build`
- `bun run lint:check`

## VoiceOps fixture integration

This example now carries a `voiceSignal` summary through the reusable CommunicationOS module UI. The fixture models the Rivage Retail voice escalation from the hackathon proof as CommunicationOS evidence first: redacted source text, blocked customer-promise language, and a receipt reference. The example still imports only public module surfaces and remains provider-free.


---

## @lssm-tech/example.companyos-ai-os-proofs

Description: CompanyOS AI OS deterministic sandbox proofs for generic, EngineeringOS, support-to-product, and Incident Brain scenarios.
Path: packages/examples/companyos-ai-os-proofs
URL: /llms/example.companyos-ai-os-proofs

# CompanyOS AI OS Proofs

Deterministic sandbox proofs for the CompanyOS operating graph.

This package demonstrates one claim:

> CompanyOS turns messy company workflows into a permissioned operating graph where AI and humans can inspect, approve, replay, and prove work across multiple workflows.

The demo is local, deterministic, provider-free, credential-free, and side-effect-free. It does not call AI providers, send network requests, load credentials, or write to production systems.

## Canonical demo flow

The primary UI export is `CompanyOsAiOsProofsPreview` from `@lssm-tech/example.companyos-ai-os-proofs/ui`.

It follows exactly six top-level steps:

1. **Executive Story** — explains the proof in one sentence.
2. **Scenario Workbench** — selects the default `support-to-product` workflow and inspects the raw messy signal.
3. **Operating Graph** — shows explicit signals, actors, capabilities, policies, approvals, evidence, and graph edges.
4. **Permission + Redaction** — proves unsafe agent actions are blocked, sensitive data is redacted, and PM approval is required where needed.
5. **Replay** — replays the deterministic run with timeline events, state diffs, graph diffs, blocked actions, redactions, approvals, correction replay, and stale/conflict fail-closed checks.
6. **Evidence Receipt** — exports structured JSON proving what happened, including runbook selection/compilation and outcome attribution.

Do not add dashboards, settings, onboarding, or extra top-level proof steps to this flow.

## Default proof scenario

The fully wired scenario is **Support-to-Product**:

> A customer support signal becomes a product gap. The agent selects and compiles a dry-run runbook, CompanyOS queries a permissioned graph view, redacts sensitive data, fails closed on stale/conflicting write paths, requires PM approval, replays the corrected path, attributes the outcome, and exports a receipt.

Canonical metadata:

| Field | Value |
| --- | --- |
| Run ID | `run_support_to_product_001` |
| Receipt ID | `receipt_support_to_product_001` |
| Scenario | `support-to-product` |
| Graph schema | `companyos.graph.v0` |
| Proof version | `ai-os-proof.v0.1.0` |
| Sandbox mode | `true` |
| External calls | `false` |
| Production writes | `false` |

Other scenario previews may exist for comparison, but `support-to-product` is the canonical end-to-end proof path.

## What the receipt proves

The Evidence Receipt is derived from the same deterministic replay events used by Step 5. It includes:

- run and scenario metadata
- graph nodes and edges created
- actors involved
- permissions checked, including permissioned graph query results
- data redactions applied
- selected and compiled dry-run runbook
- stale/conflict fail-closed checks
- allowed and blocked actions
- approval gates still pending
- correction replay state changes
- outcome attribution from support signal through approval to product gap
- verification metadata, including event count and replay path

The receipt intentionally does **not** prove production integration, real customer usage, external provider execution, or legal compliance certification.

## Safety and trust boundaries

User-facing copy should consistently make these boundaries clear:

- Deterministic sandbox
- No provider calls
- No credentials
- No production writes
- Replayable run
- Evidence receipt
- Blocked by policy
- Redacted before agent access
- Requires PM approval
- Stale runbooks stay blocked

Avoid user-facing copy such as “fake adapters”, “AI agent magic”, “trust me”, or unqualified production claims.

## Package surfaces

Important source areas:

- `src/shared-core.ts` — shared deterministic proof-building primitives.
- `src/scenarios/*` — scenario-level proofs using the shared core.
- `src/ui/CompanyOsAiOsProofsPreview.tsx` — demo shell.
- `src/ui/proof-app.navigation.ts` — canonical six-step navigation.
- `src/ui/support-to-product-proof.data.ts` — shared canonical proof data.
- `src/ui/support-to-product-replay.data.ts` — deterministic replay events.
- `src/ui/proof-app.receipts.ts` — receipt derivation from replay events.

## Local commands

Run from `packages/examples/companyos-ai-os-proofs`:

```bash
bun run lint:check
bun run typecheck
bun run test
bun run build:bundle
```

Use `bun run build` when type artifact generation is needed for release validation.


---

## @lssm-tech/example.companyos-communicationos-operating-cockpit

Description: Deterministic combined CompanyOS and CommunicationOS operating cockpit example for governed conversation-to-work loops.
Path: packages/examples/companyos-communicationos-operating-cockpit
URL: /llms/example.companyos-communicationos-operating-cockpit

# CompanyOS + CommunicationOS Operating Cockpit

Deterministic combined example that turns CommunicationOS thread/action evidence into a CompanyOS work execution plan, runs it through policy-gated dry-run execution, and feeds the result back into a CommunicationOS audit/action state.

## Boundaries

- Provider-free by default: no network I/O, credentials, outbound messages, deployments, or production actions.
- Imports reusable modules/libs only; it does not import other examples.
- Package-local `src/contracts` describe proof fixtures for this example, not canonical reusable cross-OS contracts.
- CompanyOS execution uses deterministic module adapters from `@lssm-tech/module.companyos`.
- Message-originated commands enter the CommunicationOS command inbox as evidence only; production sends and CompanyOS high-impact bypass attempts are blocked before execution.


## Rich cockpit proof

- The UI exports an app-like `TemplateShell` cockpit from `@lssm-tech/lib.example-shared-ui/TemplateShell` with ten named screens: home, dashboard, CommunicationOS inbox, thread detail, evidence map, CompanyOS work graph, policy gate, dry-run console, audit feedback, and starter-kit guide.
- The start/home and dashboard screens introduce the cross-OS story, deterministic safety boundaries, metrics, production-readiness checks, command lanes, operator notes, and quick actions before the deeper workflow screens.
- Sidebar navigation, thread selection, evidence drill-down, workflow-stage inspection, policy approval, dry-run execution, audit viewing, operator notes, and reset are backed by a pure reducer so the preview is interactive without providers or side effects.
- Selecting a CommunicationOS thread advances deterministic state into CompanyOS work mapping; running the dry-run advances the proof into CommunicationOS audit feedback without outbound effects.
- Reusable starter-kit proof imports CompanyOS and CommunicationOS UI/runtime surfaces from `@lssm-tech/module.companyos` and `@lssm-tech/module.communication-os`; scenario copy and fixtures remain package-local.
- The proof summary includes `commandInboxStatus: blocked` and `companyOsBridgeStatus: blocked` so release evidence catches any accidental execution bypass.

## Public integration surfaces

Import the package-native cockpit UI from `@lssm-tech/example.companyos-communicationos-operating-cockpit/ui` when a host wants the combined proof without depending on another example package. The `./ui` subpath exports:

- `OperatingCockpitPreview` for the deterministic app-like cockpit.
- `OperatingCockpitScreen`, `OPERATING_COCKPIT_SCREEN_HREFS`, and `operatingCockpitNavigation` for host routing, docs anchors, and preview catalogs.
- `createInitialOperatingCockpitState`, `reduceOperatingCockpitState`, `serializeOperatingCockpitState`, `parseOperatingCockpitState`, and `createInMemoryOperatingCockpitPersistence` for host-owned state snapshots. The example never writes to browser storage, disk, or a backend by itself; hosts provide persistence adapters explicitly.
- `OriginChip`, `OriginChipProps`, and `COCKPIT_ORIGIN_KINDS` for rendering source-origin context from CompanyOS action-origin types while falling back safely for unknown kinds.

Public discovery is integrated through `@lssm-tech/module.examples`: registry entries point at this package's `./docs`, feature entrypoint, sandbox link, LLMS guide, and package-native `./ui` preview. Regenerate the example registry after changing these exports or discovery fields.

## Commands

```bash
bun run --cwd packages/examples/companyos-communicationos-operating-cockpit test
bun run --cwd packages/examples/companyos-communicationos-operating-cockpit typecheck
bun run --cwd packages/examples/companyos-communicationos-operating-cockpit build
bun run --cwd packages/examples/companyos-communicationos-operating-cockpit lint:check
bun run --cwd packages/modules/examples generate:registry
bun test packages/bundles/marketing/src/components/templates/template-catalog.test.ts packages/bundles/marketing/src/components/templates/template-preview.test.ts
```

## VoiceOps operating cockpit story

The cockpit fixture now starts from the Rivage Retail voice escalation: CommunicationOS holds the redacted voice evidence, CompanyOS drafts an internal security-documentation product gap, and customer-facing promises/security claims remain blocked. The dry-run remains deterministic and side-effect free while surfacing the same receipt/proof language as the VoiceOps workbench.

## Roadmap: UI/UX refresh

The example is still intentionally thin around `@lssm-tech/bundle.managed-companyos` cockpit templates. The next refresh should make the cockpit feel like a proper operator product surface while keeping the package deterministic and provider-free:

- Implement the reusable UI work in `packages/bundles/managed-companyos/src/ui/cockpit/templates/operating-cockpit`, then let this example provide fixtures and proof coverage.
- Upgrade the home/dashboard into an operator-grade command center with loop state, selected thread, policy, dry-run, audit, contact identity, and evidence context.
- Add richer CommunicationOS inbox/thread/contact affordances inspired by the messaging workspace: searchable conversations, contact-to-conversation navigation, detail drawers, edit/delete actions, and evidence-aware actions.
- Keep provider adapters host-owned; the example must remain no-network, no-credential, no-send, and no-production-action by default.


---

## @lssm-tech/example.companyos-knowledge-graph

Description: Runtime managed-graph example consuming CompanyOS ManagedGraphNode/Edge via DataViewGraphSpec
Path: packages/examples/companyos-knowledge-graph
URL: /llms/example.companyos-knowledge-graph

# @lssm-tech/example.companyos-knowledge-graph

**Runtime managed-graph example consuming `ManagedGraphNode`/`ManagedGraphEdge` via `DataViewGraphSpec` with the `two-op` source variant.**

## What This Demonstrates

- Defining a `DataViewGraphSpec` with a `two-op` graph source.
- Fetching nodes and edges via separate query operations at runtime.
- Modeling a CompanyOS knowledge graph structure.

## Running Locally

From `packages/examples/companyos-knowledge-graph`:

```bash
bun run typecheck
```

## Architecture

- `src/index.ts` — root public barrel and package entrypoint.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`.
- Full `DataViewGraphSpec` export lands in task P5/W5.B.


---

## @lssm-tech/example.companyos-product-engineering-loop

Description: Deterministic CompanyOS V1 operating review replay using public spec and pure runtime APIs.
Path: packages/examples/companyos-product-engineering-loop
URL: /llms/example.companyos-product-engineering-loop

# @lssm-tech/example.companyos-product-engineering-loop

Deterministic CompanyOS V1 product/engineering operating-loop example using public `@lssm-tech/lib.companyos-spec` and pure `@lssm-tech/lib.companyos-runtime` APIs.

## What this demonstrates

A provider-free replay of the CompanyOS V1 fixture:

```txt
onboarding-confusion signal
-> product feedback
-> customer commitment
-> quarterly objective drift
-> temporal memory snapshot
-> weekly operating review packet
-> company brain entry / gap
-> candidate decision
-> proposed engineering work
-> ContractSpec proposal
-> scoped agent organization
-> handoff/delegation policy
-> agent-native operation authority/autonomy classification
-> product-lead review surface selection
-> draft-only agent action
-> operator inbox approval
-> V1 operating review summary
```

The example validates the V1 fixture with CompanyOS public validation helpers before building the replay. It uses pure runtime projections for authority, autonomy, inbox routing, and operating-review summarization. It does not bind real providers, send customer messages, perform filesystem/network I/O, or execute production work. The optional `./ui` surface is a deterministic compatibility preview adapter over the package replay data while canonical reusable CompanyOS UI is promoted into `@lssm-tech/module.companyos/ui`.

## Preview / export workflow

This package stays provider-free and replay-led. It must not add live provider bindings, network I/O, filesystem I/O, outbound sends, or production mutation paths.

`./ui` is a thin deterministic compatibility adapter for the focused example: it derives preview metrics from `buildCompanyOsProductEngineeringReplay()` and preserves draft-only, dry-run, approval-gated semantics. New reusable/canonical CompanyOS UI should live in `@lssm-tech/module.companyos/ui`; this example should consume that module-owned surface once available rather than growing new canonical screens here.

## Running locally

From `packages/examples/companyos-product-engineering-loop`:

- `bun run build`
- `bun run typecheck`
- `bun run test`
- `bun run smoke`
- `bun run preflight`

## Usage

```ts
import { buildCompanyOsProductEngineeringReplay } from '@lssm-tech/example.companyos-product-engineering-loop/replay';

const replay = buildCompanyOsProductEngineeringReplay();
console.log(replay.reviewPacket.runtimeSummary);
console.log(replay.steps.map((step) => step.label));
```

## Public entry points

- `@lssm-tech/example.companyos-product-engineering-loop`
- `@lssm-tech/example.companyos-product-engineering-loop/example`
- `@lssm-tech/example.companyos-product-engineering-loop/companyos-product-engineering-loop.feature`
- `@lssm-tech/example.companyos-product-engineering-loop/replay`
- `@lssm-tech/example.companyos-product-engineering-loop/docs`
- `@lssm-tech/example.companyos-product-engineering-loop/ui`

## Safety boundaries

- The replay consumes public CompanyOS fixture, validation, and runtime APIs only.
- Agent-native operations remain draft-only, dry-run constrained, and approval-gated.
- Customer-facing action execution is represented as an operator inbox approval, not a provider write.
- No real providers, network I/O, filesystem I/O, outbound sends, or production mutation paths are included.
- `./ui` remains a deterministic preview adapter and must not become the canonical reusable CompanyOS UI surface.


---

## @lssm-tech/example.companyos-voiceops-workbench

Description: Deterministic CompanyOS VoiceOps workbench example adapted from the Hackathon Voice AI UI/UX ingest lane.
Path: packages/examples/companyos-voiceops-workbench
URL: /llms/example.companyos-voiceops-workbench

# CompanyOS VoiceOps Workbench

Deterministic example package for Hackathon Voice AI web-app parity inside the CompanyOS examples registry.

The package adapts the hackathon app's product shape into a safe, provider-free CompanyOS preview. `VoiceOpsWorkbenchPreview` now renders a package-local app shell with deterministic screen navigation for Workbench, Company, Work, Inbox, Integrations, Settings, Contracts, Receipt Viewer, and Receipt Verify. The Workbench screen keeps the core demo concepts together: source pills, redacted transcript replay, redaction proof, policy/action table, graph canvas, replay scrubber, receipt evidence, and an explicit live-mode-disabled safety banner.

This package intentionally does not ship live provider SDKs, API keys, production endpoints, generated media, raw quarantined source, browser audio capture, network behavior, or production writes. Live/provider ideas are represented only as fixture-backed disabled or reference-only view-model data.

## Source traceability

The UI model records source-path references from the Hackathon Voice AI ingest lane, including original workbench panels such as `TranscriptPanel.tsx`, `RedactionDiff.tsx`, `ReplayScrubber.tsx`, `ReceiptPanel.tsx`, `WorkTable.tsx`, and the sixty-second demo spec. Conceptual screen-map material is marked `reference-only`, while live/provider controls such as `LiveAudioRecorder.tsx` and `GradiumTtsButton.tsx` are marked `rejected-live` so hosts can audit parity without executing unsafe behavior.

## Public surface

- `VoiceOpsWorkbenchPreview` remains the public preview entrypoint.
- `initialScreenId` can render any deterministic app-shell screen for tests or host previews.
- `voiceOpsWorkbenchFixture` contains all screen, contract, approval, receipt, graph, replay, provider-readiness, and source-reference data.

## Safety boundary

All behavior is fixture/view-model only. Browser audio capture, speech recognition, live model/provider calls, router dependencies, environment reads, network requests, and production writes are represented as disabled explanatory cards rather than executable code.

Future fixture changes should keep each adapted concept source-traceable and should classify unsafe/live-only files as reference-only or rejected rather than executable package behavior. Examples of unsafe/live-only concepts include live audio recorders, provider test buttons, provider runtime wiring, environment/configuration files, production URLs, and credential-bearing readiness checks.

## Public exports

Preserve these package exports when evolving the example:

- `CompanyOsVoiceOpsWorkbenchExample`
- `voiceOpsWorkbenchFixture`
- `VoiceOpsWorkbenchPreview`
- `./fixtures`
- `./ui`
- `./ui/VoiceOpsWorkbenchPreview`

Additive fixture/type growth is preferred so downstream registry and sandbox consumers can keep importing the existing surface.

## Verification commands

Run package-local checks before claiming changes:

```bash
bun run typecheck
bun run test
bun run smoke
bun run lint:check
```

If example metadata or exported registry fields change, also regenerate/check the examples registry from the repository root.


---

## @lssm-tech/example.content-generation

Description: Content generation example using @lssm-tech/lib.content-gen.
Path: packages/examples/content-generation
URL: /llms/example.content-generation

# @lssm-tech/example.content-generation

Website: https://contractspec.io

**Content generation example using @lssm-tech/lib.content-gen.**

## What This Demonstrates

- Content generation pipeline with typed contracts.
- Integration with the content-gen library.
- Structured logging for generation steps.
- DocBlock documentation for the generation flow.
- Deterministic provider-free preview data for content, image, video, TTS, STT, and conversation workflow artifacts.
- `src/docs/` contains docblocks and documentation-facing exports.

## Preview / export workflow

Content Generation previews use deterministic local pipeline fixtures for brief/prompt editing, generation review, publishing/version snapshots, and audit status. The `./ui` export must not call LLM providers, production endpoints, or live storage.

The first-class preview packet covers these local artifact kinds:

- `content` — blog, email, landing, social, and SEO draft outputs from typed briefs.
- `image` — campaign hero image fixture references.
- `video` — launch teaser storyboard fixture references.
- `tts` — narration script fixture references.
- `stt` — transcript fixture references.
- `conversation` — human review assistant handoff fixture references.

Public key behavior is compatibility-sensitive because current catalog consumers may resolve both `examples.content-generation` and normalized keys. Document and test any alias migration before release. The Phase 0 compatibility gate lives in `.omx/plans/content-generation-compatibility-matrix.md`.

## Compatibility / Migration Notes

- Keep `content-generation` as the canonical feature key; any registry alias cleanup is major-version-only.
- Prefer future contract-source imports from `@lssm-tech/lib.contracts-spec/content-generation` once the contracts lane lands them; existing `@lssm-tech/lib.content-gen` generator imports remain valid for this example.
- Provider credentials are non-goals for this package. Real provider adapters belong in integration packages and are injected by apps/modules, while this example stays deterministic.
- Keep this README synchronized with `packages/apps/web-landing/public/llms-packages/example.content-generation.txt` until generated docs own the mirror.

## Running Locally

From `packages/examples/content-generation`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.content-generation` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/content-generation.feature.ts` defines a feature entrypoint.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/generate.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./content-generation.feature` resolves through `./src/content-generation.feature.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/content-generation.docblock` resolves through `./src/docs/content-generation.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./generate` resolves through `./src/generate.ts`.
- Export `./ui` resolves through `./src/ui/index.ts`.
- Export `./ui/content-generation-preview.data` resolves through `./src/ui/content-generation-preview.data.ts`.
- Export `./ui/ContentGenerationPreview` resolves through `./src/ui/ContentGenerationPreview.tsx`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.content-gen`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.contract-graph

Description: Static build-time graph example for ContractSpec: contracts → events → presentations, reusing graph-artifacts link kinds
Path: packages/examples/contract-graph
URL: /llms/example.contract-graph

# @lssm-tech/example.contract-graph

**Static build-time graph example: contracts → events → presentations using `DataViewGraphSpec`.**

## What This Demonstrates

- Defining a `DataViewGraphSpec` with an `inline-op` graph source.
- Connecting ContractSpec artifacts (contracts, events, presentations) as nodes and edges via `graph-artifacts` link kinds.
- Build-time graph — no managed-graph runtime or entity registry required.

## Running Locally

From `packages/examples/contract-graph`:

```bash
bun run typecheck
```

## Architecture

- `src/index.ts` — root public barrel and package entrypoint.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`.
- Implementation of the full `DataViewGraphSpec` export lands in task P5/W5.A.


---

## @lssm-tech/example.crm-pipeline

Description: CRM Pipeline - Contacts, Companies, Deals, Tasks
Path: packages/examples/crm-pipeline
URL: /llms/example.crm-pipeline

# @lssm-tech/example.crm-pipeline

Website: https://contractspec.io

**CRM Pipeline - Contacts, Companies, Deals, Tasks.**

## What This Demonstrates

- Multi-entity domain model (Contact, Company, Deal, Task).
- Deal pipeline with stage enums, operations, and test-specs.
- Event-driven architecture (contact, deal, task events).
- Presentation layer with dashboard and pipeline views.
- React UI with pipeline board, hooks, modals, overlays, renderers, and a server-mode shared `DataTable` for deals.
- Shared table capabilities including sorting, pagination, multi-row selection, column visibility, pinning, resizing, and expandable deal details.
- Feature definition and capability pattern.
- Seeders and mock data.

## Running Locally

From `packages/examples/crm-pipeline`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.crm-pipeline` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/crm-pipeline.feature.ts` defines a feature entrypoint.
- `src/deal` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events` is part of the package's public or composition surface.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./crm-pipeline.feature` resolves through `./src/crm-pipeline.feature.ts`.
- Export `./deal` resolves through `./src/deal/index.ts`.
- Export `./deal/deal.enum` resolves through `./src/deal/deal.enum.ts`.
- Export `./deal/deal.operation` resolves through `./src/deal/deal.operation.ts`.
- Export `./deal/deal.schema` resolves through `./src/deal/deal.schema.ts`.
- Export `./deal/deal.test-spec` resolves through `./src/deal/deal.test-spec.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/crm-pipeline.docblock` resolves through `./src/docs/crm-pipeline.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- The package publishes 44 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run validate` — contractspec validate "src/**/*"
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.identity-rbac`, `@lssm-tech/lib.runtime-sandbox`, ...


---

## @lssm-tech/example.data-fetching-ecosystem

Description: UX wiring proof: useContractQuery → QueryState → design-system components, all lifecycle states.
Path: packages/examples/data-fetching-ecosystem
URL: /llms/example.data-fetching-ecosystem

(No README.md)

---

## @lssm-tech/example.data-grid-showcase

Description: Focused data-grid example for ContractSpec table capabilities
Path: packages/examples/data-grid-showcase
URL: /llms/example.data-grid-showcase

# @lssm-tech/example.data-grid-showcase

Website: https://contractspec.io

**Canonical data-table example for the ContractSpec stack.**

## What This Demonstrates

- The same account-grid example across `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.ui-kit`, `@lssm-tech/lib.ui-kit-web`, and `@lssm-tech/lib.design-system`.
- Client-mode and server-mode table controllers with sorting, pagination, single and multiple selection, column visibility, resizing, left/right pinning, and row expansion.
- Loading states, empty states, design-system header actions, toolbar/footer slots, and a visible row-interaction log.
- A declarative `DataViewSpec` table contract that adapts onto the same headless table stack.
- Sandbox-friendly UI packaging for a focused canonical example instead of a full business template.

## Running Locally

From `packages/examples/data-grid-showcase`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.data-grid-showcase` as the canonical reference for ContractSpec table capabilities, or import its exported contracts and UI into docs, sandboxes, and internal examples.

## Live surfaces

- Sandbox: `/sandbox?template=data-grid-showcase`
- Docs example: `/docs/examples/data-grid-showcase`
- Generated reference: `/docs/reference/data-grid-showcase/data-grid-showcase`

## Architecture

- `src/contracts/` owns the sample query contract and declarative data view spec.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the example manifest surfaced by `@lssm-tech/module.examples`.
- `src/ui/` contains the table showcase component, the primitive/composed table lanes, and demo data/helpers.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./contracts/data-grid-showcase.data-view` resolves through `./src/contracts/data-grid-showcase.data-view.ts`.
- Export `./contracts/data-grid-showcase.operation` resolves through `./src/contracts/data-grid-showcase.operation.ts`.
- Export `./data-grid-showcase.feature` resolves through `./src/data-grid-showcase.feature.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./ui` resolves through `./src/ui/index.ts`.
- Export `./ui/DataGridShowcase` resolves through `./src/ui/DataGridShowcase.tsx`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit

## Data table contract example

The declarative contract lane uses the same account-grid example exposed in the interactive showcase:

```ts
import { defineDataView } from '@lssm-tech/lib.contracts-spec/data-views';
import { ListDataGridShowcaseRowsQuery } from './data-grid-showcase.operation';

export const DataGridShowcaseDataView = defineDataView({
  meta: {
    key: 'examples.data-grid-showcase.table',
    version: '1.0.0',
    entity: 'account',
    title: 'Data Grid Showcase Table',
    description:
      'Declarative DataViewSpec for the ContractSpec table showcase.',
    domain: 'examples',
    owners: ['@platform.core'],
    tags: ['examples', 'table', 'data-grid'],
    stability: 'experimental',
  },
  source: {
    primary: {
      key: ListDataGridShowcaseRowsQuery.meta.key,
      version: ListDataGridShowcaseRowsQuery.meta.version,
    },
  },
  view: {
    kind: 'table',
    executionMode: 'client',
    selection: 'multiple',
    columnVisibility: true,
    columnResizing: true,
    columnPinning: true,
    rowExpansion: {
      fields: ['notes', 'renewalDate', 'lastActivityAt'],
    },
    initialState: {
      pageSize: 4,
      hiddenColumns: ['notes'],
      pinnedColumns: {
        left: ['account'],
      },
      sorting: [{ field: 'arr', desc: true }],
    },
    fields: [
      { key: 'account', label: 'Account', dataPath: 'account', sortable: true },
      { key: 'owner', label: 'Owner', dataPath: 'owner', sortable: true },
      { key: 'status', label: 'Status', dataPath: 'status', sortable: true },
      { key: 'notes', label: 'Notes', dataPath: 'notes' },
    ],
  },
});
```

## Notes

- This package is intentionally narrow: it exists to showcase the full table stack, not to simulate a full vertical business template.
- The same table stack is reused by the larger examples in `analytics-dashboard`, `crm-pipeline`, `integration-hub`, and `agent-console`, but this package is the canonical source of truth.


---

## @lssm-tech/example.email-gmail

Description: Gmail integration example: inbound threads and outbound messages.
Path: packages/examples/email-gmail
URL: /llms/example.email-gmail

# @lssm-tech/example.email-gmail

Website: https://contractspec.io

**Gmail integration example: inbound threads and outbound messages.**

## What This Demonstrates

- OAuth authentication flow for Gmail API.
- Inbound email thread processing.
- Outbound message composition and sending.
- Integration provider pattern with ContractSpec contracts.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/email-gmail`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.email-gmail` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/auth.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/email-gmail.feature.ts` defines a feature entrypoint.
- `src/example.ts` is the runnable example entrypoint.
- `src/inbound.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/outbound.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./auth` resolves through `./src/auth.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/email-gmail.docblock` resolves through `./src/docs/email-gmail.docblock.ts`.
- Export `./email-gmail.feature` resolves through `./src/email-gmail.feature.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./inbound` resolves through `./src/inbound.ts`.
- Export `./outbound` resolves through `./src/outbound.ts`.
- Export `./run` resolves through `./src/run.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-email`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.finance-ops-ai-workflows

Description: Deterministic finance operations AI workflow example with human review, fixed rules, and synthetic data only.
Path: packages/examples/finance-ops-ai-workflows
URL: /llms/example.finance-ops-ai-workflows

# @lssm-tech/example.finance-ops-ai-workflows

Finance Ops AI Workflows is a public ContractSpec template for safe, deterministic, human-reviewed AI-assisted finance operations workflows.

It is designed as a credible business demo for NDconsulting / Desliance style work: DAF transition, cash management, reporting, procedures, finance process improvement, training, and AI adoption ROI.

## Product Positioning

This is not a chatbot, prompt collection, SaaS app, or live integration. It demonstrates how to turn finance-ops work into explicit workflows:

business input -> ContractSpec operation -> deterministic handler -> simulated AI-assisted workflow -> human review -> reviewable output -> ROI/adoption log.

The value is not "make an LLM talk". The value is to frame finance work, separate deterministic rules from assisted drafting, block autonomous decisions, and leave evidence that can be tested and industrialized.

## Included Workflows

- `financeOps.missionIntake.triage`: fictive DAF / finance transformation mission intake.
- `financeOps.cashAging.prioritize`: fixed-date aged receivables prioritization using deterministic rules.
- `financeOps.procedureDraft.create`: internal finance procedure draft with roles, steps, controls and KPIs.
- `financeOps.reportingNarrative.compose`: management reporting narrative with variance helpers and no invented causes.
- `financeOps.aiAdoption.logUsage`: AI adoption ROI log that tracks use cases, not intrusive employee surveillance.

## Demo Script

1. Open `/templates` and preview `Finance Ops AI Workflows`.
2. Switch between the PME recovery and reporting reset scenarios from the demo command bar.
3. Run a workflow draft, select the mission item, invoice, procedure step, reporting variance, or adoption log under discussion, and use the selected-detail panel to request changes or mark the draft ready.
4. Move through Mission intake, Cash aging, Procedure, Reporting, and Adoption ROI as an operator cockpit rather than a slide sequence.
5. Reset the replay when the presenter wants to restart the story from the same synthetic fixture.

## Interactive Preview

The inline template preview is intentionally demo-grade:

- Command bar with scenario switching, deterministic replay reset, draft-run controls and current workflow state.
- Workflow rail for Mission intake, Cash aging, Procedure, Reporting, and Adoption ROI.
- Compact lists and tables instead of oversized card grids.
- Selected-detail panel for every workflow click: mission evidence, invoice follow-up, procedure control, reporting variance, or adoption recommendation.
- Draft-only review actions to request changes or mark the selected workflow ready.

The preview recomputes from the handlers, so it demonstrates the same deterministic contract outputs that tests and replay proof cover. The interactivity is local UI state only: it simulates review and replay, not real operational execution.

## Scope Boundaries

The package uses synthetic fixtures and deterministic handlers only. It does not connect to live finance systems, does not send operational communications, and does not provide production financial, legal, tax, accounting, or investment advice. Workflow outputs keep `humanReviewRequired` set to `true`.

## Public Entry Points

- `@lssm-tech/example.finance-ops-ai-workflows`
- `@lssm-tech/example.finance-ops-ai-workflows/contracts`
- `@lssm-tech/example.finance-ops-ai-workflows/contracts/mission-intake-triage.operation`
- `@lssm-tech/example.finance-ops-ai-workflows/contracts/cash-aging-prioritization.operation`
- `@lssm-tech/example.finance-ops-ai-workflows/contracts/procedure-draft.operation`
- `@lssm-tech/example.finance-ops-ai-workflows/contracts/reporting-narrative.operation`
- `@lssm-tech/example.finance-ops-ai-workflows/contracts/adoption-roi-log.operation`
- `@lssm-tech/example.finance-ops-ai-workflows/fixtures`
- `@lssm-tech/example.finance-ops-ai-workflows/handlers`
- `@lssm-tech/example.finance-ops-ai-workflows/proof`
- `@lssm-tech/example.finance-ops-ai-workflows/ui`

## Implementation Notes

- Handlers are pure deterministic functions wrapped with `HandlerForOperationSpec`.
- Structured lists are returned as JSON strings where the contract surface asks for `*Json` fields.
- Fixtures are fictive and tuned for a commercial demo: PME industrielle, 85 employees, 14 M EUR revenue, RAF departure, missing reporting, cash tension and fragmented Excel/Power BI tools.
- The replay proof runs all five workflows and returns a compact evidence object.

## Commands

- `bun run build`
- `bun run typecheck`
- `bun run test`
- `bun run smoke`
- `bun run preflight`


---

## @lssm-tech/example.form-showcase

Description: Focused ContractSpec form example and template covering field kinds, conditional rules, and layout flows.
Path: packages/examples/form-showcase
URL: /llms/example.form-showcase

# @lssm-tech/example.form-showcase

Focused ContractSpec form example and template covering field kinds, conditional rules, and layout flows.

## What This Demonstrates

- Schema-backed `defineFormSpec` authoring with `fromZod`.
- Every current form field kind: text, email, textarea, select, checkbox, radio, switch, autocomplete, address, phone, date, time, datetime, group, and array.
- Layout variants including responsive columns, full-width spans, section flows, step flows, nested groups, horizontal/responsive orientation, and repeated group arrays.
- Form metadata for input groups, password fields, read-only/computed hints, conditional visibility/enabled/required rules, custom constraints, PII hints, and submit actions.
- A `FormRegistry` that downstream apps can import and filter, including entity projection form metadata.
- A `FormShowcasePreview` UI that demonstrates the specs with real form controls across field kinds, sections, arrays, groups, and step layouts.

## Running Locally

From `packages/examples/form-showcase`:

- `bun run build`
- `bun run typecheck`
- `bun run test`
- `bun run smoke`
- `bun run preflight`

## Usage

Import the registry or individual form specs:

```ts
import {
	FormShowcaseRegistry,
	FormShowcaseAllFieldsForm,
	FormShowcaseProgressiveStepsForm,
} from "@lssm-tech/example.form-showcase/forms";
```

Use this package as a form-only template when you want a compact reference for ContractSpec form authoring without a larger business app around it. Import `@lssm-tech/example.form-showcase/proof-config` when tooling needs the stable docs, sandbox, templates, forms, and UI entrypoint map without reaching into private preview helpers.

## Proof map and boundaries

The public proof map is intentionally stable and package-local:

- Docs routes: `/docs/examples/form-showcase`, `/docs/examples/form-showcase/usage`, and `/docs/examples/form-showcase/proof-config`.
- Sandbox route: `/sandbox?template=form-showcase`.
- Template route: `/templates?tag=forms`.
- Public entrypoints: the package barrel, `./example`, `./forms`, `./docs`, `./proof-config`, and `./ui`.

Private proof helpers under `src/ui/proof/*` and preview data/model files stay implementation details. Tooling should read `@lssm-tech/example.form-showcase/proof-config` instead of deep-importing those helpers.

When a form-configuration panel is needed, reuse the design-system `FormConfigShell`, `FormConfigMenuBar`, and `FormConfigPanel` exports from `@lssm-tech/lib.design-system/forms`. The showcase proof should not fork a local configuration shell.

No persistence, backend, auth, provider, credential custody, or production form-storage guarantee is implied by this example. Capture/readiness proof state is deterministic fixture state only.

## Public Entry Points

- `@lssm-tech/example.form-showcase`
- `@lssm-tech/example.form-showcase/example`
- `@lssm-tech/example.form-showcase/forms`
- `@lssm-tech/example.form-showcase/forms/all-fields.form`
- `@lssm-tech/example.form-showcase/forms/entity-projections.form`
- `@lssm-tech/example.form-showcase/forms/form-showcase.docs`
- `@lssm-tech/example.form-showcase/forms/progressive-steps.form`
- `@lssm-tech/example.form-showcase/proof-config`
- `@lssm-tech/example.form-showcase/docs`
- `@lssm-tech/example.form-showcase/ui`
- `@lssm-tech/example.form-showcase/ui/FormShowcasePreview`

Private proof/state helpers under `src/ui/proof/*`, any screen-model internals under `src/ui/screens/*`, and non-existent deep proof shortcuts such as `@lssm-tech/example.form-showcase/proof` are intentionally not package exports. Use `@lssm-tech/example.form-showcase/proof-config` for the stable proof map instead of deep imports.

## Notes

- This package intentionally does not ship a production custom renderer. Its preview uses real controls and the same sample data to demonstrate the contract capabilities, while host apps can map `FieldSpec` objects to their own design-system components for fully interactive forms.
- The example is available in the templates catalog through `surfaces.templates: true`.
- The proof/config preview is deterministic and in-memory only: it does not require persistence, backend routes, authentication, credentials, or network access.


---

## @lssm-tech/example.graph-showcase

Description: Interactive graph-richness showcase for ContractSpec P6 primitives: mini-map, focus-mode, custom renderers, edge labels, animations, and drilldown.
Path: packages/examples/graph-showcase
URL: /llms/example.graph-showcase

# `@lssm-tech/example.graph-showcase`

> **Showroom-grade interactive showcase** — 23 graph demos across 8 categories,
> 4-engine layout (ELK DAG / Ortho / Tree + d3-force), 3-preset theme system with
> full dark-mode, pointer/touch/keyboard interactions, and Playwright integration tests.

![Graph showcase — Workflow DAG, n8n-card light](./playwright/__screenshots__/responsive/desktop-after.png)

## What you'll see

| Category | Demo screens | Default preset |
|---|---|---|
| **Templates** | Workflow DAG, Agent Tree, Conversation Graph, Engineering Loop, Person Activity | `n8n-card` |
| **Filtering** | Facet Panel, Filter Chip Rack, Search Overlay, Path Highlight | `gh-slim` |
| **Time** | Time Scrub, Diff Animations, Saved View Restore | `gh-slim` |
| **Structure** | Clustering, Heatmap, Minimap, Focus Mode | `gh-slim` |
| **AI** | AI Input, AI Suggest+Confirm | `n8n-card` |
| **Annotations** | Annotations, Story Mode | `obsidian-dot` |
| **Collab** | Collab Cursors, Subscribe | `obsidian-dot` |
| **Export** | Export Pipeline | `obsidian-dot` |

## Interactions

| Action | Pointer | Touch | Keyboard |
|---|---|---|---|
| Navigate sidebar | Click item | Tap item | `↑` / `↓`, then `Enter` |
| Collapse sidebar | Click hamburger | Tap hamburger | `⌘B` / `Ctrl+B` |
| Pan canvas | Drag background | 1-finger swipe | `Space` + drag |
| Zoom in / out | Scroll wheel | 2-finger pinch | `+` / `-` via ZoomCluster |
| Fit graph to view | Click Auto-fit | — | Auto-fit button |
| Select node | Click | Tap | `Tab` to node, `Space` |
| Deselect / close | Click empty area | Tap empty | `Escape` |
| Open search | Click search bar | — | `/` |
| Open command palette | Click search bar | — | `⌘K` / `Ctrl+K` |
| Switch layout engine | Click pill in DemoHeader | — | Click only |
| Toggle dark mode | Click ☾ / ☀ in AppBar | — | Click only |

## Shell

The showcase uses a hash-based router (`useShowcaseRouter`) with 23 `SHOWCASE_ROUTES`
entries (`key / label / category / recommendedTheme`). Each demo is wrapped in
`<GraphThemeProvider themeId={recommendedTheme}>` — the shell auto-selects the best
visual preset per route.

Global keyboard handlers in `ShowcaseShell`: `⌘K` / `Ctrl+K` → `CommandPalette`;
`/` → `SearchBar`.

## Theme presets

Three presets ship with WCAG AA 4.5:1 verified tokens in both light and dark.

| Preset | Mode | Background | Node fill | Character |
|---|---|---|---|---|
| `n8n-card` | light | `#FAF4EC` warm cream | `#FFF8F0` | Rounded cards, warm workflow builder |
| `n8n-card` | dark | `#0E0D0B` near-black | `#1C1A17` warm | Immersive dark workflow |
| `gh-slim` | light | `#F8FAFC` cool white | `#F1F5F9` | Compact GitHub-style DAG |
| `gh-slim` | dark | `#020617` near-navy | `#1E293B` slate | Dark compact DAG |
| `obsidian-dot` | light | `#F5F3FF` violet tint | `#EDE9FE` | Knowledge-graph dot style |
| `obsidian-dot` | dark | `#0A0110` deep violet | `#1A0B2E` | Atmospheric dark dots |

Toggle dark mode via **☾** in the AppBar. This sets `DesignSystemThemeProvider mode="dark"`
and the Tailwind `dark` class on `<html>`, updating both chrome surfaces (Tailwind `dark:`
utilities) and graph tokens (`--graph-*` CSS vars via `CanvasVarsInjector`).

## Architecture

```mermaid
graph TD
    DSP["DesignSystemThemeProvider\nmode: light | dark"]
    Shell["ShowcaseShell\ncontext providers · dark toggle"]
    AppBar["AppBar  48px\nlogo · search · GitHub · CTA · ☾"]
    SidebarNav["SidebarNav  240px\n23 routes · 8 categories · ⌘B"]
    DemoHeader["DemoHeader  56px\nbreadcrumb · role · layout pills"]
    CanvasArea["CanvasArea\nadaptive dot-grid · border"]
    GTP["GraphThemeProvider\nthemeId context"]
    CVI["CanvasVarsInjector\n--graph-* CSS vars"]
    Demo["Demo Screen\nWorkflowDagDemo · AgentTreeDemo …"]
    GC["GraphCanvas\nSVG renderer · useGraphLayout"]
    Atoms["Node / Edge Atoms\nN8nCardNode · GhSlimNode\nObsidianDotNode + edges"]

    DSP -->|wraps| Shell
    Shell --> AppBar
    Shell --> SidebarNav
    Shell --> DemoHeader
    Shell --> CanvasArea
    CanvasArea --> GTP
    GTP --> CVI
    CVI --> Demo
    Demo --> GC
    GC --> Atoms
```

**Token flow:** `DesignSystemThemeProvider(mode)` → `useGraphTheme(themeId)` inside
`CanvasVarsInjector` → emits `--graph-node-fill`, `--graph-kind-{kind}-{fill|stroke|label|accent}`
CSS vars on a wrapper `<div>` → atom components read them as `var(--graph-node-fill, <light-fallback>)`.

## Fixture data

All demo screens share synthetic fixtures in `src/fixtures.ts`:

- **12 nodes** spanning 4 `kind` values (`contract`, `entity`, `event`, `feature`)
- **14 directed edges** — mix of labeled and unlabeled
- A **focus sub-graph** (6-node cluster) for minimap + focus-mode demos
- Seed `Viewport` and `selection` values

## Usage

```ts
import { SHOWCASE_ROUTES } from '@lssm-tech/example.graph-showcase';
// Enumerate all 23 route keys:
SHOWCASE_ROUTES.forEach(r => console.log(r.key, r.category, r.recommendedTheme));
```

## Commands

```bash
bun run typecheck      # tsgo --noEmit
bun test               # unit + smoke tests (bun test runner)
bun run test:e2e       # Playwright integration tests (showcase config, port 5999)
bun run lint:check     # Biome lint check
```

### Playwright integration tests

| Suite | File | Coverage |
|---|---|---|
| Accessibility | `playwright/a11y.spec.ts` | S8.1–S8.5: landmarks, keyboard, reduced-motion |
| Lighthouse | `playwright/lighthouse.spec.ts` | S9.2: performance + ARIA structure |
| Touch | `playwright/touch.spec.ts` | S9.3: iPad Mini tap-to-navigate, sidebar |
| Dark-mode | `playwright/template-darkmode.spec.ts` | S9.4: 10 PNG baselines (5 templates × light/dark) |
| Responsive | `playwright/responsive.spec.ts` | E3: phone / tablet / desktop viewports |

Regenerate dark-mode baselines:

```bash
bun exec playwright test --config playwright.showcase.config.ts \
  template-darkmode.spec.ts --update-snapshots
```


---

## @lssm-tech/example.harness-lab

Description: Focused harness example for ContractSpec scenarios, suites, orchestration, and runtime adapters.
Path: packages/examples/harness-lab
URL: /llms/example.harness-lab

# @lssm-tech/example.harness-lab

Website: https://contractspec.io

**Focused harness example for scenario contracts, suites, orchestration, and real runtime adapters.**

## What This Demonstrates

- Contract layer: canonical `harness-scenario` and `harness-suite` exports.
- Orchestration layer: `HarnessRunner`, `HarnessEvaluationRunner`, and replay bundle generation.
- Runtime layer: `SandboxedCodeExecutionAdapter`, `PlaywrightBrowserHarnessAdapter`, optional `AgentBrowserHarnessAdapter`, `DefaultHarnessTargetResolver`, and `InMemoryHarnessArtifactStore`.
- A deterministic local browser fixture that stays offline and exercises Playwright, auth profile refs, visual diff evidence, and optional agent-browser evidence.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/harness-lab`:
- `bunx playwright install chromium`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.harness-lab` as the focused harness reference package. It pairs with `@lssm-tech/example.agent-console`, which remains the business-oriented proof example for harness contracts.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/harness-lab.feature.ts` defines the feature entrypoint for docs/discovery.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/runtime/` contains the runnable sandbox and browser evaluation helpers plus the local browser fixture.
- `src/scenarios/` contains sandbox, Playwright browser, authenticated browser, visual baseline, and optional agent-browser scenario contracts.
- `src/suite/` contains the dual-mode harness suite contract.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/harness-lab.docblock` resolves through `./src/docs/harness-lab.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./harness-lab.feature` resolves through `./src/harness-lab.feature.ts`.
- Export `./runtime` resolves through `./src/runtime/index.ts`.
- Export `./runtime/runAgentBrowserEvaluation` resolves through `./src/runtime/runAgentBrowserEvaluation.ts`.
- Export `./runtime/runAuthenticatedBrowserEvaluation` resolves through `./src/runtime/runAuthenticatedBrowserEvaluation.ts`.
- Export `./runtime/runBrowserEvaluation` resolves through `./src/runtime/runBrowserEvaluation.ts`.
- Export `./runtime/runSandboxEvaluation` resolves through `./src/runtime/runSandboxEvaluation.ts`.
- Export `./runtime/runVisualEvaluation` resolves through `./src/runtime/runVisualEvaluation.ts`.
- Export `./scenarios` resolves through `./src/scenarios/index.ts`.
- Export `./scenarios/harnessLabAgentBrowser.scenario` resolves through `./src/scenarios/harnessLabAgentBrowser.scenario.ts`.
- Export `./scenarios/harnessLabAuthenticatedBrowser.scenario` resolves through `./src/scenarios/harnessLabAuthenticatedBrowser.scenario.ts`.
- Export `./scenarios/harnessLabBrowser.scenario` resolves through `./src/scenarios/harnessLabBrowser.scenario.ts`.
- Export `./scenarios/harnessLabSandbox.scenario` resolves through `./src/scenarios/harnessLabSandbox.scenario.ts`.
- Export `./scenarios/harnessLabVisual.scenario` resolves through `./src/scenarios/harnessLabVisual.scenario.ts`.
- Export `./suite` resolves through `./src/suite/index.ts`.
- The package publishes 21 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Notes

- Browser tests use a real local Playwright run against an in-package HTTP fixture. Install Chromium locally before running `bun run test`.
- Agent-browser tests are optional and skip automatically when the `agent-browser` CLI is unavailable.
- Authenticated scenarios use named auth profile refs; storage state is created by the test harness and credentials are not embedded in scenario specs.


---

## @lssm-tech/example.in-app-docs

Description: Example showing how to use DocBlock for in-app documentation for non-technical users
Path: packages/examples/in-app-docs
URL: /llms/example.in-app-docs

# @lssm-tech/example.in-app-docs

Website: https://contractspec.io

**Example showing how to use DocBlock for in-app documentation for non-technical users.**

## What This Demonstrates

- DocBlock-driven in-app documentation pattern.
- React viewer component for rendering DocBlocks.
- User-facing documentation without technical jargon.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/ui/` contains packaged UI exports and embeddable views.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/in-app-docs`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.in-app-docs` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/in-app-docs.feature.ts` defines a feature entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/ui/` contains packaged UI exports and embeddable views.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/in-app-docs.docblock` resolves through `./src/docs/in-app-docs.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./in-app-docs.feature` resolves through `./src/in-app-docs.feature.ts`.
- Export `./ui` resolves through `./src/ui/index.ts`.
- Export `./ui/InAppDocsViewer` resolves through `./src/ui/InAppDocsViewer.tsx`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.integration-hub

Description: Integration Hub example with sync engine and field mappings for ContractSpec
Path: packages/examples/integration-hub
URL: /llms/example.integration-hub

# @lssm-tech/example.integration-hub

Website: https://contractspec.io

**Integration Hub example with sync engine and field mappings for ContractSpec.**

## What This Demonstrates

- Connection management with typed schemas and enums.
- Integration lifecycle (create, configure, sync).
- Sync engine with field mapping and status tracking.
- MCP server example for tool integration.
- Capability and feature definition patterns.
- React UI with a cockpit-style Integration Hub command center, screen navigation, hooks, markdown renderers, and shared ContractSpec tables for connections and sync configs.
- Contract-backed visualizations for integration mix, connection health, and sync-state comparison.
- Client-mode table capabilities including sorting, pagination, column visibility, pinning, resizing, and expanded operational details.
- Event definitions and operation test-specs.
- Managed/BYOK credential setup metadata with monorepo-aware Next and Expo env aliases plus an interactive mode switch in the hub UI.
- Registry-derived provider seeding from `createDefaultIntegrationSpecRegistry()`
  so the preview covers the complete shipped integration catalog, including
  BYOK-only entries with explicit managed-mode exemption metadata.
- Redacted connection credential previews; handlers return secret placeholders
  instead of raw key material.
- Runtime resolver and governance screens that explain managed/BYOK fallback, policy evidence, and release-review posture.
- Managed/BYOK database mutation examples in `src/setup/database-mutation-examples.ts` route durable writes through the provider-database `./governed-mutation` helper only after an owning domain command emits `domainCommandRef`, `policyDecisionRef`, `idempotencyKey`, `transactionBoundary`, `expectedWriteSet`, `auditEventRefs`, `replayRef`, and `correlationRef` evidence; fixtures use redacted refs only and never embed raw database credentials.
- Phase 5 DS1/DS4: all UI cards in the catalog use `IntegrationCardSurface` (hover elevation + focus ring) and `IntegrationHealthDot` from `@lssm-tech/bundle.managed-companyos/ui/integrations`. Empty states use `EmptyStateIllustrated`. The credential setup flow is wrapped in `WizardStepper`. A dedicated **Rich Interactions** screen demonstrates every DS1 atom and molecule in one place.

## Reusable bundle integration

The example demonstrates the Integration Hub but does not own the reusable
Managed CompanyOS production surfaces. Hosts should compose the canonical bundle
surfaces directly:

- View-model builders from `@lssm-tech/bundle.managed-companyos/view-models/integration-*`.
- Templates from `@lssm-tech/bundle.managed-companyos/ui/templates`.
- Capability atoms and design primitives from `@lssm-tech/bundle.managed-companyos/ui/integrations`.

Example UI files should remain demo/adaptation layers over those imports. Do not
fork credential, secret, connection, sync, audit, or role-morph logic locally.
Managed/BYOK turn-on flows must require an explicit ownership-mode choice and
may render only redacted credential references.

## Design System Integration (Phase 5 DS1)

The example **imports** DS1 primitives from the bundle — it does not re-implement them.

| Primitive | Origin | Usage in example |
|---|---|---|
| `IntegrationCardSurface` | `atoms-design` bundle | Provider catalog cards |
| `IntegrationHealthDot` | `atoms-design` bundle | Status dot in catalog + rich-interactions |
| `EmptyStateIllustrated` | `molecules-design` bundle | Catalog empty state, rich-interactions |
| `LastRunPill` | `atoms-design` bundle | Rich interactions showcase |
| `RotationCountdown` | `atoms-design` bundle | Rich interactions showcase |
| `ScopeChip` | `atoms-design` bundle | Rich interactions showcase |
| `SecurityShieldBadge` | `atoms-design` bundle | Rich interactions showcase |
| `AffinityScoreBar` | `atoms-design` bundle | Recommended row demo |
| `WizardStepper` | `molecules-design` bundle | Credential setup preview |
| `DiffPreviewCard` | `molecules-design` bundle | Sync drift banner demo |

**Consumers** that want to adopt these primitives directly should import from
`@lssm-tech/bundle.managed-companyos/ui/integrations` — not from this example package.

## Running Locally

From `packages/examples/integration-hub`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.integration-hub` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/connection` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/integration` is part of the package's public or composition surface.
- `src/setup` exposes BYOK credential manifests, secret-reference fixtures, and monorepo env aliases.
- `src/ui/IntegrationDashboard.*` subpaths expose advanced UI composition pieces for hosts that want to reuse the command-center shell, navigation, screen model, or individual rich screens. The default `./ui/IntegrationDashboard` export wraps its command center in the shared `NestedCommandShell` from `@lssm-tech/lib.example-shared-ui`; keep local navigation inside that reusable nested-safe shell unless a preview-specific containment guardrail requires otherwise. Prefer `./ui/IntegrationDashboard` unless custom composition is required.
- Production apps should consume bundle Integration Hub view-models/templates directly; this package remains an example adapter and documentation surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./connection` resolves through `./src/connection/index.ts`.
- Export `./connection/connection.enum` resolves through `./src/connection/connection.enum.ts`.
- Export `./connection/connection.operation` resolves through `./src/connection/connection.operation.ts`.
- Export `./connection/connection.presentation` resolves through `./src/connection/connection.presentation.ts`.
- Export `./connection/connection.schema` resolves through `./src/connection/connection.schema.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/integration-hub.docblock` resolves through `./src/docs/integration-hub.docblock.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./setup` resolves through `./src/setup/index.ts`.
- Export `./setup/credential-setup` resolves through `./src/setup/credential-setup.ts`.
- The package publishes 52 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run validate` — contractspec validate "src/**/*"
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run run:mcp` — bun tsx src/run-mcp.ts
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Vnext ai-native.
- Missing contract layers.
- Resolve lint, build, and type errors across nine packages.
- Add Composio universal fallback, fix provider-ranking types, and expand package exports.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add Integration Hub BYOK credential setup metadata and Next/Expo alias previews.
- Seed Integration Hub from the shipped provider registry and expose typed
  ownership mode plus redacted credential previews through handler flows.
- Upgrade the Integration Hub dashboard into a rich command-center demo with provider catalog, managed/BYOK credential, connection, sync, runtime governance, and assistant screens.

## Notes

- Works alongside `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.runtime-sandbox`, ...


---

## @lssm-tech/example.integration-posthog

Description: PostHog analytics integration example: capture events, run HogQL, and manage feature flags.
Path: packages/examples/integration-posthog
URL: /llms/example.integration-posthog

# @lssm-tech/example.integration-posthog

Website: https://contractspec.io

**PostHog analytics integration example: capture events, run HogQL, and manage feature flags.**

## What This Demonstrates

- PostHog event capture and tracking setup.
- HogQL query execution pattern.
- Feature flag management via PostHog API.
- Integration provider pattern with ContractSpec contracts.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/integration-posthog`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.integration-posthog` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/integration-posthog.feature.ts` defines a feature entrypoint.
- `src/posthog.ts` is part of the package's public or composition surface.
- `src/run.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/integration-posthog.docblock` resolves through `./src/docs/integration-posthog.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./integration-posthog.feature` resolves through `./src/integration-posthog.feature.ts`.
- Export `./posthog` resolves through `./src/posthog.ts`.
- Export `./run` resolves through `./src/run.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add changesets and apply pending fixes.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-analytics`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.integration-stripe

Description: Integration example – Stripe Payments (blueprint + workflow + tenant config).
Path: packages/examples/integration-stripe
URL: /llms/example.integration-stripe

# @lssm-tech/example.integration-stripe

Website: https://contractspec.io

**Integration example – Stripe Payments (blueprint + workflow + tenant config).**

## What This Demonstrates

- Canonical `integration` export via `StripePaymentsIntegrationSpec`.
- Integration-oriented `app-config` example via `defineAppConfig(...)`.
- Canonical `workflow` export via `defineWorkflow(...)`.
- Multi-tenant configuration pattern.
- Connection sample for credential wiring.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/integration-stripe`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.integration-stripe` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/blueprint.ts` is part of the package's public or composition surface.
- `src/connection.sample.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/integration.ts` defines the exported integration spec.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/integration-stripe.feature.ts` defines a feature entrypoint.
- `src/tenant.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./blueprint` resolves through `./src/blueprint.ts`.
- Export `./connection.sample` resolves through `./src/connection.sample.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/integration-stripe.docblock` resolves through `./src/docs/integration-stripe.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./integration` resolves through `./src/integration.ts`.
- Export `./integration-stripe.feature` resolves through `./src/integration-stripe.feature.ts`.
- Export `./tenant` resolves through `./src/tenant.ts`.
- Export `./workflow` resolves through `./src/workflow.ts`.
- The package publishes 9 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.integration-supabase

Description: Integration example - Supabase vector store + Postgres database wiring.
Path: packages/examples/integration-supabase
URL: /llms/example.integration-supabase

# @lssm-tech/example.integration-supabase

Website: https://contractspec.io

**Integration example - Supabase vector store + Postgres database wiring.**

## What This Demonstrates

- Integration blueprint for Supabase vector store + Postgres.
- Multi-tenant configuration pattern.
- Connection sample for credential wiring.
- Runtime sample for execution context setup.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/integration-supabase`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.integration-supabase` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/blueprint.ts` is part of the package's public or composition surface.
- `src/connection.sample.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/integration-supabase.feature.ts` defines a feature entrypoint.
- `src/runtime.sample.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./blueprint` resolves through `./src/blueprint.ts`.
- Export `./connection.sample` resolves through `./src/connection.sample.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/integration-supabase.docblock` resolves through `./src/docs/integration-supabase.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./integration-supabase.feature` resolves through `./src/integration-supabase.feature.ts`.
- Export `./runtime.sample` resolves through `./src/runtime.sample.ts`.
- Export `./tenant` resolves through `./src/tenant.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.providers-impls`, `@lssm-tech/integration.runtime`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.kb-update-pipeline

Description: Example: KB update automation pipeline with HITL review and auditability.
Path: packages/examples/kb-update-pipeline
URL: /llms/example.kb-update-pipeline

# @lssm-tech/example.kb-update-pipeline

Website: https://contractspec.io

**Example: KB update automation pipeline with HITL review and auditability.**

## What This Demonstrates

- HITL (human-in-the-loop) review pipeline pattern.
- Entity models for KB articles and update proposals.
- Event-driven pipeline with typed operations.
- Feature definition with presentations and test-specs.
- In-memory handlers for demo scenarios.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/kb-update-pipeline`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.kb-update-pipeline` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/kb-update-pipeline.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/kb-update-pipeline.docblock` resolves through `./src/docs/kb-update-pipeline.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./entities/models` resolves through `./src/entities/models.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./handlers/memory.handlers` resolves through `./src/handlers/memory.handlers.ts`.
- Export `./kb-update-pipeline.feature` resolves through `./src/kb-update-pipeline.feature.ts`.
- The package publishes 14 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.knowledge-canon

Description: Knowledge example – Product Canon space (blueprint + tenant config + source sample + runtime helper).
Path: packages/examples/knowledge-canon
URL: /llms/example.knowledge-canon

# @lssm-tech/example.knowledge-canon

Website: https://contractspec.io

**Knowledge example – Product Canon space (blueprint + tenant config + source sample + real `lib.knowledge` retrieval helper).**

## What This Demonstrates

- Canonical `knowledge-space` export via `ProductCanonKnowledgeSpace`.
- Lightweight `app-config` example via `defineAppConfig(...)`.
- Multi-tenant configuration for knowledge bases.
- Source sample for content ingestion.
- Agent helper backed by `@lssm-tech/lib.knowledge` static retrieval.
- Minimal contract-only example pattern.
- `src/docs/` contains docblocks and documentation-facing exports.
- The same runtime primitives can ingest Gmail and Google Drive sources through `KnowledgeRuntime` when a workspace wires provider implementations.

## Running Locally

From `packages/examples/knowledge-canon`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.knowledge-canon` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

The public `answerWithKnowledge(...)` helper now performs a real retrieval step through `@lssm-tech/lib.knowledge`, so the example is suitable as a copy-pasteable lightweight knowledge-routing pattern.

For provider-backed workspaces, compose the same package with `createKnowledgeRuntime({ gmail, drive, ... })` and call `syncGmail(...)` or `syncDriveFiles(...)` before retrieval. Mutating external knowledge systems should use the governance helpers from `@lssm-tech/lib.knowledge/governance` so dry-runs, approval refs, idempotency keys, audit evidence, and outbound-send gates are captured consistently.

## Architecture

- `src/agent.ts` is part of the package's public or composition surface.
- `src/blueprint.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the package example manifest/metadata entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/knowledge-canon.feature.ts` defines a feature entrypoint.
- `src/product-canon.space.ts` defines the exported knowledge-space spec.
- `src/source.sample.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./agent` resolves through `./src/agent.ts`.
- Export `./blueprint` resolves through `./src/blueprint.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/knowledge-canon.docblock` resolves through `./src/docs/knowledge-canon.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./knowledge-canon.feature` resolves through `./src/knowledge-canon.feature.ts`.
- Export `./product-canon.space` resolves through `./src/product-canon.space.ts`.
- Export `./source.sample` resolves through `./src/source.sample.ts`.
- Export `./tenant` resolves through `./src/tenant.ts`.
- The package publishes 9 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.learning-journey-ambient-coach

Description: Ambient coach learning journey example with contextual tips and follow-up actions.
Path: packages/examples/learning-journey-ambient-coach
URL: /llms/example.learning-journey-ambient-coach

# @lssm-tech/example.learning-journey-ambient-coach

Website: https://contractspec.io

**Ambient coach learning journey example with contextual tips and follow-up actions.**

## What This Demonstrates

- Ambient coaching track definition using the learning-journey module.
- Contextual tip delivery based on user activity.
- Follow-up action triggers.
- Lightweight track + example pattern.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-ambient-coach`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-ambient-coach` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-ambient-coach.feature.ts` defines a feature entrypoint.
- `src/track.test.ts` is part of the package's public or composition surface.
- `src/track.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/ambient-coach.docblock` resolves through `./src/docs/ambient-coach.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-journey-ambient-coach.feature` resolves through `./src/learning-journey-ambient-coach.feature.ts`.
- Export `./track` resolves through `./src/track.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.learning-journey-crm-onboarding

Description: Learning journey track that onboards users to the CRM pipeline example.
Path: packages/examples/learning-journey-crm-onboarding
URL: /llms/example.learning-journey-crm-onboarding

# @lssm-tech/example.learning-journey-crm-onboarding

Website: https://contractspec.io

**Learning journey track that onboards users to the CRM pipeline example.**

## What This Demonstrates

- CRM-specific onboarding track with step-by-step guidance.
- Feature definition with operations, presentations, and test-specs.
- Demo handlers for simulated onboarding flow.
- Cross-example dependency (builds on crm-pipeline).
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/learning-journey-crm-onboarding`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-crm-onboarding` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-crm-onboarding.feature.ts` defines a feature entrypoint.
- `src/operations` is part of the package's public or composition surface.
- `src/presentations` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/crm-onboarding.docblock` resolves through `./src/docs/crm-onboarding.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`.
- Export `./learning-journey-crm-onboarding.feature` resolves through `./src/learning-journey-crm-onboarding.feature.ts`.
- Export `./operations` resolves through `./src/operations/index.ts`.
- Export `./presentations` resolves through `./src/presentations/index.ts`.
- Export `./tests/operations.test-spec` resolves through `./src/tests/operations.test-spec.ts`.
- Export `./track` resolves through `./src/track.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/example.crm-pipeline`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.learning-journey-duo-drills

Description: Drill-based learning journey example with SRS, XP, and streak hooks.
Path: packages/examples/learning-journey-duo-drills
URL: /llms/example.learning-journey-duo-drills

# @lssm-tech/example.learning-journey-duo-drills

Website: https://contractspec.io

**Drill-based learning journey example with SRS, XP, and streak hooks.**

## What This Demonstrates

- Drill-based learning track with SRS scheduling.
- XP and streak gamification hooks.
- Lightweight track + example pattern.
- Integration with the learning-journey module.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-duo-drills`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-duo-drills` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-duo-drills.feature.ts` defines a feature entrypoint.
- `src/track.test.ts` is part of the package's public or composition surface.
- `src/track.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/duo-drills.docblock` resolves through `./src/docs/duo-drills.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-journey-duo-drills.feature` resolves through `./src/learning-journey-duo-drills.feature.ts`.
- Export `./track` resolves through `./src/track.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.learning-journey-managed-onboarding

Description: Standalone managed onboarding reference proof for Learning Journey scenarios.
Path: packages/examples/learning-journey-managed-onboarding
URL: /llms/example.learning-journey-managed-onboarding

# Learning Journey Managed Onboarding

Standalone reference proof for the managed onboarding foundation in `@lssm-tech/module.learning-journey`.

The package turns the module-owned managed platform, SpecialOps, and AI Ops proof scenario adapters into deterministic reference UI view models. It demonstrates checklist, timeline, story, annotation, and presenter-cursor concepts without importing from other examples.

## Boundary

- Imports only from `@lssm-tech/module.learning-journey` and `@lssm-tech/lib.contracts-spec`.
- Does not import `@lssm-tech/example.*` packages.
- Uses fixture/proof references only; no external credentials, production endpoints, provider execution, outbound sends, or real customer data.
- AI Ops remains `proof-guidance-only` and exposes no sprint-product operation controls.

## Commands

```bash
bun test --pass-with-no-tests
bun run typecheck
bun run lint:check
```


---

## @lssm-tech/example.learning-journey-platform-tour

Description: Learning journey track covering ContractSpec platform primitives.
Path: packages/examples/learning-journey-platform-tour
URL: /llms/example.learning-journey-platform-tour

# @lssm-tech/example.learning-journey-platform-tour

Website: https://contractspec.io

**Learning journey track covering ContractSpec platform primitives.**

## What This Demonstrates

- Platform primitives tour with step-by-step guidance.
- Feature definition with operations, presentations, and test-specs.
- Demo handlers for simulated tour flow.
- Interactive exploration of ContractSpec concepts.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/learning-journey-platform-tour`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-platform-tour` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-platform-tour.feature.ts` defines a feature entrypoint.
- `src/operations` is part of the package's public or composition surface.
- `src/presentations` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/platform-tour.docblock` resolves through `./src/docs/platform-tour.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`.
- Export `./learning-journey-platform-tour.feature` resolves through `./src/learning-journey-platform-tour.feature.ts`.
- Export `./operations` resolves through `./src/operations/index.ts`.
- Export `./presentations` resolves through `./src/presentations/index.ts`.
- Export `./tests/operations.test-spec` resolves through `./src/tests/operations.test-spec.ts`.
- Export `./track` resolves through `./src/track.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.learning-journey-quest-challenges

Description: Time-bound quest/challenge learning journey example.
Path: packages/examples/learning-journey-quest-challenges
URL: /llms/example.learning-journey-quest-challenges

# @lssm-tech/example.learning-journey-quest-challenges

Website: https://contractspec.io

**Time-bound quest/challenge learning journey example.**

## What This Demonstrates

- Quest/challenge track with time-bound objectives.
- Completion tracking and deadline enforcement.
- Lightweight track + example pattern.
- Integration with the learning-journey module.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-quest-challenges`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-quest-challenges` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-quest-challenges.feature.ts` defines a feature entrypoint.
- `src/track.test.ts` is part of the package's public or composition surface.
- `src/track.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/quest-challenges.docblock` resolves through `./src/docs/quest-challenges.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-journey-quest-challenges.feature` resolves through `./src/learning-journey-quest-challenges.feature.ts`.
- Export `./track` resolves through `./src/track.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.learning-journey-registry

Description: Registry that aggregates learning journey example tracks.
Path: packages/examples/learning-journey-registry
URL: /llms/example.learning-journey-registry

# @lssm-tech/example.learning-journey-registry

Website: https://contractspec.io

**Registry that aggregates learning journey example tracks.**

## What This Demonstrates

- Track aggregation and discovery via a central registry.
- Feature definition pattern (`learning-journey-registry.feature`).
- Progress store for cross-track state.
- API and API-types separation for typed endpoints.
- Presentation layer with LearningMiniApp UI.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-registry`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-registry` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/api-types.ts` is part of the package's public or composition surface.
- `src/api.test.ts` is part of the package's public or composition surface.
- `src/api.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-registry.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./api` resolves through `./src/api.ts`.
- Export `./api-types` resolves through `./src/api-types.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-journey-registry.docblock` resolves through `./src/docs/learning-journey-registry.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-journey-registry.feature` resolves through `./src/learning-journey-registry.feature.ts`.
- Export `./presentations` resolves through `./src/presentations/index.ts`.
- Export `./progress-store` resolves through `./src/progress-store.ts`.
- Export `./tracks` resolves through `./src/tracks.ts`.
- The package publishes 12 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/example.learning-journey-ambient-coach`, `@lssm-tech/example.learning-journey-crm-onboarding`, `@lssm-tech/example.learning-journey-duo-drills`, `@lssm-tech/example.learning-journey-platform-tour`, `@lssm-tech/example.learning-journey-quest-challenges`, ...


---

## @lssm-tech/example.learning-journey-studio-onboarding

Description: Learning journey track for first 30 minutes in ContractSpec Studio.
Path: packages/examples/learning-journey-studio-onboarding
URL: /llms/example.learning-journey-studio-onboarding

# @lssm-tech/example.learning-journey-studio-onboarding

Website: https://contractspec.io

**Learning journey track for first 30 minutes in ContractSpec Studio.**

## What This Demonstrates

- Studio onboarding track with time-boxed steps.
- Feature definition with operations, presentations, and test-specs.
- Demo handlers for simulated onboarding flow.
- First-run experience pattern for new users.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/learning-journey-studio-onboarding`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-studio-onboarding` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-studio-onboarding.feature.ts` defines a feature entrypoint.
- `src/operations` is part of the package's public or composition surface.
- `src/presentations` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/studio-onboarding.docblock` resolves through `./src/docs/studio-onboarding.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`.
- Export `./learning-journey-studio-onboarding.feature` resolves through `./src/learning-journey-studio-onboarding.feature.ts`.
- Export `./operations` resolves through `./src/operations/index.ts`.
- Export `./presentations` resolves through `./src/presentations/index.ts`.
- Export `./tests/operations.test-spec` resolves through `./src/tests/operations.test-spec.ts`.
- Export `./track` resolves through `./src/track.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.learning-journey-ui-coaching

Description: Contextual coaching UI with tip cards and engagement tracking.
Path: packages/examples/learning-journey-ui-coaching
URL: /llms/example.learning-journey-ui-coaching

# @lssm-tech/example.learning-journey-ui-coaching

Website: https://contractspec.io

**Contextual coaching UI with tip cards and engagement tracking.**

## What This Demonstrates

- CoachingMiniApp as a self-contained React application.
- TipCard, TipFeed, and EngagementMeter components.
- Multi-view layout (Overview, Progress, Steps, Timeline).
- Integration with ambient-coach and crm-onboarding tracks.
- Design system and UI kit usage patterns.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-ui-coaching`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-ui-coaching` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/CoachingMiniApp.tsx` is part of the package's public or composition surface.
- `src/components/` contains reusable UI components and view composition.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-ui-coaching.feature.ts` defines a feature entrypoint.
- `src/views/` contains view-level composition.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./CoachingMiniApp` resolves through `./src/CoachingMiniApp.tsx`.
- Export `./components` resolves through `./src/components/index.ts`.
- Export `./components/EngagementMeter` resolves through `./src/components/EngagementMeter.tsx`.
- Export `./components/TipCard` resolves through `./src/components/TipCard.tsx`.
- Export `./components/TipFeed` resolves through `./src/components/TipFeed.tsx`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-journey-ui-coaching.docblock` resolves through `./src/docs/learning-journey-ui-coaching.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-journey-ui-coaching.feature` resolves through `./src/learning-journey-ui-coaching.feature.ts`.
- The package publishes 15 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/example.learning-journey-ambient-coach`, `@lssm-tech/example.learning-journey-crm-onboarding`, `@lssm-tech/example.learning-journey-ui-shared`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, ...


---

## @lssm-tech/example.learning-journey-ui-gamified

Description: Duolingo-style gamified learning UI for drills and quests.
Path: packages/examples/learning-journey-ui-gamified
URL: /llms/example.learning-journey-ui-gamified

# @lssm-tech/example.learning-journey-ui-gamified

Website: https://contractspec.io

**Duolingo-style gamified learning UI for drills and quests.**

## What This Demonstrates

- GamifiedMiniApp as a self-contained React application.
- FlashCard, DayCalendar, and MasteryRing components.
- Multi-view layout (Overview, Progress, Steps, Timeline).
- Integration with duo-drills and quest-challenges tracks.
- Design system and UI kit usage patterns.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-ui-gamified`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-ui-gamified` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/components/` contains reusable UI components and view composition.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/GamifiedMiniApp.tsx` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-ui-gamified.feature.ts` defines a feature entrypoint.
- `src/views/` contains view-level composition.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./components` resolves through `./src/components/index.ts`.
- Export `./components/DayCalendar` resolves through `./src/components/DayCalendar.tsx`.
- Export `./components/FlashCard` resolves through `./src/components/FlashCard.tsx`.
- Export `./components/MasteryRing` resolves through `./src/components/MasteryRing.tsx`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-journey-ui-gamified.docblock` resolves through `./src/docs/learning-journey-ui-gamified.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./GamifiedMiniApp` resolves through `./src/GamifiedMiniApp.tsx`.
- Export `./learning-journey-ui-gamified.feature` resolves through `./src/learning-journey-ui-gamified.feature.ts`.
- The package publishes 15 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/example.learning-journey-duo-drills`, `@lssm-tech/example.learning-journey-quest-challenges`, `@lssm-tech/example.learning-journey-ui-shared`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, ...


---

## @lssm-tech/example.learning-journey-ui-onboarding

Description: Developer onboarding UI with checklists and journey maps.
Path: packages/examples/learning-journey-ui-onboarding
URL: /llms/example.learning-journey-ui-onboarding

# @lssm-tech/example.learning-journey-ui-onboarding

Website: https://contractspec.io

**Developer onboarding UI with checklists and journey maps.**

## What This Demonstrates

- React-based onboarding mini-app with checklist and journey map components.
- Multi-view layout (Overview, Progress, Steps, Timeline).
- Shared UI component reuse across learning journey examples.
- DocBlock-driven documentation pattern.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-ui-onboarding`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-ui-onboarding` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/components/` contains reusable UI components and view composition.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-ui-onboarding.feature.ts` defines a feature entrypoint.
- `src/OnboardingMiniApp.tsx` is part of the package's public or composition surface.
- `src/views/` contains view-level composition.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./components` resolves through `./src/components/index.ts`.
- Export `./components/CodeSnippet` resolves through `./src/components/CodeSnippet.tsx`.
- Export `./components/JourneyMap` resolves through `./src/components/JourneyMap.tsx`.
- Export `./components/StepChecklist` resolves through `./src/components/StepChecklist.tsx`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-journey-ui-onboarding.docblock` resolves through `./src/docs/learning-journey-ui-onboarding.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-journey-ui-onboarding.feature` resolves through `./src/learning-journey-ui-onboarding.feature.ts`.
- Export `./OnboardingMiniApp` resolves through `./src/OnboardingMiniApp.tsx`.
- The package publishes 15 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/example.learning-journey-platform-tour`, `@lssm-tech/example.learning-journey-studio-onboarding`, `@lssm-tech/example.learning-journey-ui-shared`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, ...


---

## @lssm-tech/example.learning-journey-ui-shared

Description: Shared UI components and hooks for learning journey mini-apps.
Path: packages/examples/learning-journey-ui-shared
URL: /llms/example.learning-journey-ui-shared

# @lssm-tech/example.learning-journey-ui-shared

Website: https://contractspec.io

**Shared UI components and hooks for learning journey mini-apps.**

## What This Demonstrates

- Reusable gamification components (XpBar, StreakCounter, BadgeDisplay, ViewTabs).
- Custom hook pattern (`useLearningProgress`) for shared state.
- Shared types for cross-mini-app consistency.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-journey-ui-shared`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-journey-ui-shared` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/components/` contains reusable UI components and view composition.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/hooks/` contains custom hooks for host applications.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-journey-ui-shared.feature.ts` defines a feature entrypoint.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./components` resolves through `./src/components/index.ts`.
- Export `./components/BadgeDisplay` resolves through `./src/components/BadgeDisplay.tsx`.
- Export `./components/StreakCounter` resolves through `./src/components/StreakCounter.tsx`.
- Export `./components/ViewTabs` resolves through `./src/components/ViewTabs.tsx`.
- Export `./components/XpBar` resolves through `./src/components/XpBar.tsx`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-journey-ui-shared.docblock` resolves through `./src/docs/learning-journey-ui-shared.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./hooks` resolves through `./src/hooks/index.ts`.
- The package publishes 13 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.ui-kit-web`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.learning-patterns

Description: Example: drills + ambient coach + quests learning patterns, powered by Learning Journey (event-driven, deterministic).
Path: packages/examples/learning-patterns
URL: /llms/example.learning-patterns

# @lssm-tech/example.learning-patterns

Website: https://contractspec.io

**Example: drills + ambient coach + quests learning patterns, powered by Learning Journey (event-driven, deterministic).**

## What This Demonstrates

- Three distinct learning track patterns: drills, ambient-coach, quests.
- Event-driven track progression.
- Deterministic state transitions via the Learning Journey module.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/learning-patterns`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.learning-patterns` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/learning-patterns.feature.ts` defines a feature entrypoint.
- `src/learning-patterns.test.ts` is part of the package's public or composition surface.
- `src/tracks` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/learning-patterns.docblock` resolves through `./src/docs/learning-patterns.docblock.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./learning-patterns.feature` resolves through `./src/learning-patterns.feature.ts`.
- Export `./tracks` resolves through `./src/tracks/index.ts`.
- Export `./tracks/ambient-coach` resolves through `./src/tracks/ambient-coach.ts`.
- Export `./tracks/drills` resolves through `./src/tracks/drills.ts`.
- Export `./tracks/quests` resolves through `./src/tracks/quests.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/module.learning-journey`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.lifecycle-cli

Description: Lifecycle CLI demo (example): run lifecycle assessment without an HTTP server.
Path: packages/examples/lifecycle-cli
URL: /llms/example.lifecycle-cli

# @lssm-tech/example.lifecycle-cli

Website: https://contractspec.io

**Lifecycle CLI demo (example): run lifecycle assessment without an HTTP server.**

## What This Demonstrates

- Headless lifecycle assessment execution via CLI.
- Bundle consumption pattern (lifecycle-managed).
- Logger integration for CLI output.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/lifecycle-cli`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.lifecycle-cli` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/demo.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/lifecycle-cli.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./demo` resolves through `./src/demo.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/lifecycle-cli.docblock` resolves through `./src/docs/lifecycle-cli.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./lifecycle-cli.feature` resolves through `./src/lifecycle-cli.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/bundle.lifecycle-managed`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.lifecycle`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.lifecycle-dashboard

Description: Lifecycle dashboard example (snippet): how to call lifecycle-managed APIs and render a status card.
Path: packages/examples/lifecycle-dashboard
URL: /llms/example.lifecycle-dashboard

# @lssm-tech/example.lifecycle-dashboard

Website: https://contractspec.io

**Lifecycle dashboard example (snippet): how to call lifecycle-managed APIs and render a status card.**

## What This Demonstrates

- Lifecycle API consumption pattern.
- Status card rendering snippet.
- Minimal dependency footprint for quick integration.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/lifecycle-dashboard`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.lifecycle-dashboard` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/lifecycle-dashboard.feature.ts` defines a feature entrypoint.
- `src/snippets` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/lifecycle-dashboard.docblock` resolves through `./src/docs/lifecycle-dashboard.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./lifecycle-dashboard.feature` resolves through `./src/lifecycle-dashboard.feature.ts`.
- Export `./snippets/page` resolves through `./src/snippets/page.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.locale-jurisdiction-gate

Description: Example: enforce locale + jurisdiction + kbSnapshotId + allowed scope for assistant calls (fail-closed).
Path: packages/examples/locale-jurisdiction-gate
URL: /llms/example.locale-jurisdiction-gate

# @lssm-tech/example.locale-jurisdiction-gate

Website: https://contractspec.io

**Example: enforce locale + jurisdiction + kbSnapshotId + allowed scope for assistant calls (fail-closed).**

## What This Demonstrates

- Canonical `policy` export via `AssistantGatePolicy`.
- Canonical `form` export via `AssistantContextForm`.
- Canonical `translation` exports for `en-US`, `en-GB`, and `fr-FR`.
- Fail-closed policy guard pattern for AI assistant calls.
- Entity models for locale/jurisdiction gating.
- Event-driven policy enforcement.
- Handler and operation separation with typed operations.
- Feature definition pattern.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/locale-jurisdiction-gate`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.locale-jurisdiction-gate` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/forms/` contains the exported assistant context form spec.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/locale-jurisdiction-gate.feature.ts` defines a feature entrypoint.
- `src/translations/` contains the exported locale catalogs.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/locale-jurisdiction-gate.docblock` resolves through `./src/docs/locale-jurisdiction-gate.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./entities/models` resolves through `./src/entities/models.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./forms` resolves through `./src/forms/index.ts`.
- Export `./forms/assistant-context.form` resolves through `./src/forms/assistant-context.form.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`.
- Export `./locale-jurisdiction-gate.feature` resolves through `./src/locale-jurisdiction-gate.feature.ts`.
- Export `./policy/assistant-gate.policy` resolves through `./src/policy/assistant-gate.policy.ts`.
- Export `./translations` resolves through `./src/translations/index.ts`.
- Export `./translations/assistant-gate.en-GB.translation` resolves through `./src/translations/assistant-gate.en-GB.translation.ts`.
- Export `./translations/assistant-gate.en-US.translation` resolves through `./src/translations/assistant-gate.en-US.translation.ts`.
- Export `./translations/assistant-gate.fr-FR.translation` resolves through `./src/translations/assistant-gate.fr-FR.translation.ts`.
- The package publishes 21 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.managed-companyos-contract-editions

Description: Managed CompanyOS contract edition lifecycle proof across specs, storage, runtime wiring, integrations, and examples.
Path: packages/examples/managed-companyos-contract-editions
URL: /llms/example.managed-companyos-contract-editions

# Managed CompanyOS Contract Editions

Deterministic, credential-free proof that the ContractSpec edition platform is wired for an enterprise Managed CompanyOS vertical:

- typed operation specs for evaluation, improvement proposals, and release projection;
- file, database, and hybrid storage parity with rollback evidence;
- ContractSpec Connect, harness/replay, knowledge, intelligence coach, and enterprise guardrails;
- builder/runtime/integration wiring references; and
- full-loop readiness surfaced as a small importable example.

Run:

```bash
bun run test
bun run typecheck
```


---

## @lssm-tech/example.marketplace

Description: Marketplace example with orders, payouts, and reviews for ContractSpec
Path: packages/examples/marketplace
URL: /llms/example.marketplace

# @lssm-tech/example.marketplace

Website: https://contractspec.io

**Marketplace example with orders, payouts, and reviews for ContractSpec.**

## What This Demonstrates

- Multi-entity domain modeling (order, payout, product, review, store).
- Per-entity schema/enum/event/operations/presentation pattern.
- Capability and feature definition patterns.
- React UI with hooks, renderers, and dashboard component.
- Contract-backed visualizations for order status, category value comparison, and recent order activity.
- Seeder pattern for demo data.
- Test-spec for operations validation.

## Running Locally

From `packages/examples/marketplace`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.marketplace` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/marketplace.capability.ts` defines a capability surface.
- `src/marketplace.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/marketplace.docblock` resolves through `./src/docs/marketplace.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./entities/order` resolves through `./src/entities/order.ts`.
- Export `./entities/payout` resolves through `./src/entities/payout.ts`.
- Export `./entities/product` resolves through `./src/entities/product.ts`.
- Export `./entities/review` resolves through `./src/entities/review.ts`.
- Export `./entities/store` resolves through `./src/entities/store.ts`.
- Export `./example` resolves through `./src/example.ts`.
- The package publishes 52 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.runtime-sandbox`, `@lssm-tech/lib.schema`, ...


---

## @lssm-tech/example.meeting-recorder-providers

Description: Meeting recorder provider example: list meetings, transcripts, and webhooks.
Path: packages/examples/meeting-recorder-providers
URL: /llms/example.meeting-recorder-providers

# @lssm-tech/example.meeting-recorder-providers

Website: https://contractspec.io

**Meeting recorder provider example: list meetings, transcripts, and webhooks.**

## What This Demonstrates

- Provider integration pattern with connection samples.
- Handler-per-action pattern (create-provider, get-transcript, list-meetings, webhook-handler).
- Webhook handler for external event ingestion.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/meeting-recorder-providers`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.meeting-recorder-providers` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/connection.sample.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/meeting-recorder-providers.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./connection.sample` resolves through `./src/connection.sample.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/meeting-recorder-providers.docblock` resolves through `./src/docs/meeting-recorder-providers.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers/create-provider` resolves through `./src/handlers/create-provider.ts`.
- Export `./handlers/get-transcript` resolves through `./src/handlers/get-transcript.ts`.
- Export `./handlers/list-meetings` resolves through `./src/handlers/list-meetings.ts`.
- Export `./handlers/webhook-handler` resolves through `./src/handlers/webhook-handler.ts`.
- Export `./meeting-recorder-providers.feature` resolves through `./src/meeting-recorder-providers.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-meeting-recorder`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.messaging-agent-actions

Description: Safe messaging agent actions example with fixed intents, allowlisted actions, workflow dispatch, and deterministic replies.
Path: packages/examples/messaging-agent-actions
URL: /llms/example.messaging-agent-actions

# @lssm-tech/example.messaging-agent-actions

Safe messaging agent actions example with fixed intents, allowlisted action execution, workflow dispatch, and deterministic confirmation replies.

## What This Demonstrates

- Inbound message normalization for Slack, WhatsApp, Telegram, or any messaging bridge.
- Fixed intent parsing: `status`, `run action`, and `dispatch workflow`.
- Allowlisted action and workflow routing instead of arbitrary tool execution.
- Replayable meetup proof for the canonical status -> action -> workflow walkthrough.

## Running Locally

From `packages/examples/messaging-agent-actions`:
- `bun run build`
- `bun run test`
- `bun run typecheck`
- `bun run proof`
- `bun run preflight`

## Usage

Use this package when you need a conservative messaging demo that proves agent actions can stay safe, typed, and reviewable even when messages come from live provider webhooks.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts` resolves through `./src/contracts/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./messaging-agent-actions.feature` resolves through `./src/messaging-agent-actions.feature.ts`.
- Export `./proof/*` resolves through `./src/proof/*.ts`.

## Local Commands

- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run typecheck` — tsgo --noEmit
- `bun run proof` — bun ../../../scripts/generate-messaging-agent-actions-meetup-proof.ts
- `bun run preflight` — bun run build && bun run typecheck && bun run test && bun run proof


---

## @lssm-tech/example.messaging-app

Description: Thin messaging app example that composes reusable CommunicationOS messaging UI with deterministic fixture data.
Path: packages/examples/messaging-app
URL: /llms/example.messaging-app

# @lssm-tech/example.messaging-app

Thin messaging application example for CommunicationOS UI composition.

The reusable conversation list, thread, composer, and workspace live in `@lssm-tech/module.communication-os/ui`. This package only owns deterministic preview data and a small wrapper that demonstrates how an adopter wires the reusable UI.

## Entry Points

- `.`
- `./docs`
- `./example`
- `./ui`

## Commands

- `bun run typecheck`
- `bun run build`

## Voice-originated messaging demo

The messaging workspace now consumes the shared CommunicationOS `voiceSignal` summary. The first conversation reflects the Rivage security-answer escalation and renders the blocked customer-promise framing before the message composer policy ribbon.


---

## @lssm-tech/example.minimal

Description: (none)
Path: packages/examples/minimal
URL: /llms/example.minimal

# @lssm-tech/example.minimal

**Minimal ContractSpec example showing the simplest possible contract definition and build.**

## What This Demonstrates

- Bare-minimum contract definition (user contract).
- `contractspec build` and `contractspec validate` CLI usage.
- Maintained example package included in the ContractSpec example registry.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/minimal`:
- `bun run build`
- `bun run test`
- `bun run typecheck`
- `bun run smoke`
- `bun run preflight`

## Usage

Use `@lssm-tech/example.minimal` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/minimal.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/minimal.docblock` resolves through `./src/docs/minimal.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./minimal.feature` resolves through `./src/minimal.feature.ts`.
- Export `./contracts/user` resolves through `./src/contracts/user.ts`.

## Local Commands

- `bun run build` — bun ../../apps/cli-contractspec/src/cli.ts build src/contracts/user.ts
- `bun run validate` — bun ../../apps/cli-contractspec/src/cli.ts validate src/contracts/user.ts
- `bun run typecheck` — tsgo --noEmit
- `bun run test` — bun test
- `bun run smoke` — bun test src/example.smoke.test.ts
- `bun run preflight` — bun run build && bun run typecheck && bun run test && bun run validate && bun run smoke

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`.


---

## @lssm-tech/example.openbanking-powens

Description: OpenBanking Powens example: OAuth callback + webhook handler patterns (provider + workflows).
Path: packages/examples/openbanking-powens
URL: /llms/example.openbanking-powens

# @lssm-tech/example.openbanking-powens

Website: https://contractspec.io

**OpenBanking Powens example: OAuth callback + webhook handler patterns (provider + workflows).**

## What This Demonstrates

- OAuth callback handler pattern for open banking.
- Webhook handler for asynchronous bank event ingestion.
- Canonical `job` export via `PowensSyncDispatchJob`.
- Provider integration via contracts-integrations.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/openbanking-powens`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.openbanking-powens` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/jobs/` contains the exported Powens dispatch job spec.
- `src/openbanking-powens.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/openbanking-powens.docblock` resolves through `./src/docs/openbanking-powens.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers/oauth-callback` resolves through `./src/handlers/oauth-callback.ts`.
- Export `./handlers/webhook-handler` resolves through `./src/handlers/webhook-handler.ts`.
- Export `./jobs` resolves through `./src/jobs/index.ts`.
- Export `./jobs/powens-sync-dispatch.job` resolves through `./src/jobs/powens-sync-dispatch.job.ts`.
- Export `./openbanking-powens.feature` resolves through `./src/openbanking-powens.feature.ts`.
- The package publishes 8 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-openbanking`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.opencode-cli

Description: (none)
Path: packages/examples/opencode-cli
URL: /llms/example.opencode-cli

# @lssm-tech/example.opencode-cli

**OpenCode CLI example showing agent-mode contract building and validation.**

## What This Demonstrates

- Agent-mode (`--agent-mode opencode`) contract compilation.
- Implementation checking via `--check-implementation`.
- Maintained example package included in the ContractSpec example registry.
- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/opencode-cli`:
- `bun run build`
- `bun run test`
- `bun run typecheck`
- `bun run smoke`
- `bun run preflight`

## Usage

Use `@lssm-tech/example.opencode-cli` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/contracts/` contains contract specs, operations, entities, and registry exports.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/opencode-cli.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./contracts/opencode` resolves through `./src/contracts/opencode.contracts.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/opencode-cli.docblock` resolves through `./src/docs/opencode-cli.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./opencode-cli.feature` resolves through `./src/opencode-cli.feature.ts`.

## Local Commands

- `bun run build` — bun ../../apps/cli-contractspec/src/cli.ts build src/contracts/opencode.contracts.ts --agent-mode opencode
- `bun run validate` — bun ../../apps/cli-contractspec/src/cli.ts validate src/contracts/opencode.contracts.ts --check-implementation --agent-mode opencode
- `bun run typecheck` — tsgo --noEmit
- `bun run test` — bun test
- `bun run smoke` — bun test src/example.smoke.test.ts
- `bun run preflight` — bun run build && bun run typecheck && bun run test && bun run validate && bun run smoke

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`.


---

## @lssm-tech/example.organization-planning-agenda

Description: (none)
Path: packages/examples/organization-planning-agenda
URL: /llms/example.organization-planning-agenda

# @lssm-tech/example.organization-planning-agenda

Buildable OPA OS example for the local/manual Organization Planning Agenda loop.

## What this demonstrates

- Hackathon EOD Mission Relay-style day plan generation.
- NDconsulting-style agenda generation with private context redaction.
- Axoperf-style deployment planning constraints and blocker evidence.
- Customer-facing booking proposals blocked behind human approval.
- Rich calendar roadmap lanes for focus blocks, agendas, booking proposals,
  approval gates, and audit artifacts.
- Notion-ready markdown and audit payloads without calendar/provider writes.

## Flagship surface matrix proof

The exported `organizationPlanningAgendaSurfaceMatrixProof` fixture documents the
three flagship rows consumed by app smoke tests and docs:

| Vertical | Web monolith | Mobile demo | Examples/docs | Managed CompanyOS seam |
|---|---|---|---|---|
| Hackathon EOD | `/companyos/opa-os` consumes `buildManagedCompanyOsOpaOsProof` from `@lssm-tech/bundle.managed-companyos`. | `mobile.opa.hackathon_eod.native` consumes the managed OPA view model. | Smoke fixture renders the day plan, markdown, approvals, and evidence IDs. | `managed-companyos.view-model.organization-planning.hackathon-eod` |
| NDconsulting mission | `/companyos/opa-os` renders the client mission agenda from the managed bundle proof. | `mobile.opa.ndconsulting_mission.native` shows agenda and approval-denial state. | Smoke fixture proves agenda plus next meeting proposal. | `managed-companyos.view-model.organization-planning.ndconsulting-mission` |
| Axoperf deployment | `/companyos/opa-os` keeps deployment blocker proof in provider-blocked/degraded mode. | `mobile.opa.axoperf_deployment.native` shows blocker priority and approval-only booking slots. | Smoke fixture documents blocker outputs and evidence IDs. | `managed-companyos.view-model.organization-planning.axoperf-deployment` |

## Evidence links

- Rich calendar proof: `organizationPlanningRichCalendarRoadmapProof` exports
  provider-free lanes and approval-blocked calendar items for docs, sandbox, and
  managed-bundle consumers.
- Web proof: `packages/apps/web-application-monolith/src/opa-os-route.test.tsx` validates that `/companyos/opa-os` consumes the managed bundle proof, emits redacted behavior signals, and keeps external effects approval-blocked.
- Static safety: run `bun run opa-os:safety` from the repository root to verify the OPA no-provider, no-raw-secret, and no-live-send boundary before release handoff.

## Running locally

From `packages/examples/organization-planning-agenda`:

- `bun run build`
- `bun run typecheck`
- `bun run test`
- `bun run smoke`
- `bun run preflight`

## Boundary

This example is intentionally local and manual. It does not import provider SDKs,
write calendars, send client messages, or approve external effects.


---

## @lssm-tech/example.personalization

Description: Personalization examples: behavior tracking, overlay customization, workflow extension.
Path: packages/examples/personalization
URL: /llms/example.personalization

# @lssm-tech/example.personalization

Website: https://contractspec.io

**Personalization examples: behavior tracking, overlay customization, workflow extension.**

## What This Demonstrates

- Behavior tracking integration pattern.
- Canonical `experiment` export via `PersonalizationExperiment`.
- Overlay customization via overlay-engine.
- Canonical `theme` export via `PersonalizationTheme`.
- Workflow extension via workflow-composer.
- Multi-lib composition in a single example.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/personalization`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.personalization` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/behavior-tracking.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/overlay-customization.ts` is part of the package's public or composition surface.
- `src/personalization.experiment.ts` defines the exported experiment spec.
- `src/personalization.feature.ts` defines a feature entrypoint.
- `src/personalization.theme.ts` defines the exported theme spec.
- `src/workflow-extension.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./behavior-tracking` resolves through `./src/behavior-tracking.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/personalization.docblock` resolves through `./src/docs/personalization.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./overlay-customization` resolves through `./src/overlay-customization.ts`.
- Export `./personalization.experiment` resolves through `./src/personalization.experiment.ts`.
- Export `./personalization.feature` resolves through `./src/personalization.feature.ts`.
- Export `./personalization.theme` resolves through `./src/personalization.theme.ts`.
- Export `./workflow-extension` resolves through `./src/workflow-extension.ts`.
- The package publishes 9 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.logger`, `@lssm-tech/lib.overlay-engine`, `@lssm-tech/lib.personalization`, `@lssm-tech/lib.workflow-composer`, ...


---

## @lssm-tech/example.pocket-family-office

Description: Pocket Family Office example - personal finance automation with open banking
Path: packages/examples/pocket-family-office
URL: /llms/example.pocket-family-office

# @lssm-tech/example.pocket-family-office

Website: https://contractspec.io

**Pocket Family Office example - personal finance automation with open banking.**

## What This Demonstrates

- Workflow-driven open banking integration (sync accounts, transactions, balances).
- Financial summary and overview generation workflows.
- Document processing and email thread ingestion.
- Capability and feature definition patterns.
- Canonical `telemetry` export via `pocketFamilyOfficeTelemetry`.
- Sample tenant and connection configuration.
- An inline `PocketFamilyOfficePreview` UI for template and example browsers.

## Running Locally

From `packages/examples/pocket-family-office`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.pocket-family-office` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/blueprint.ts` is part of the package's public or composition surface.
- `src/connections` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/knowledge` is part of the package's public or composition surface.
- `src/operations` is part of the package's public or composition surface.
- `src/telemetry.ts` defines the exported telemetry spec.
- `src/ui/` contains the inline preview surface for catalog and template browsers.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./blueprint` resolves through `./src/blueprint.ts`.
- Export `./connections/samples` resolves through `./src/connections/samples.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/pocket-family-office.docblock` resolves through `./src/docs/pocket-family-office.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./knowledge/sources.sample` resolves through `./src/knowledge/sources.sample.ts`.
- Export `./operations` resolves through `./src/operations/index.ts`.
- Export `./pocket-family-office.capability` resolves through `./src/pocket-family-office.capability.ts`.
- Export `./pocket-family-office.feature` resolves through `./src/pocket-family-office.feature.ts`.
- Export `./telemetry` resolves through `./src/telemetry.ts`.
- Export `./tenant.sample` resolves through `./src/tenant.sample.ts`.
- Export `./ui` resolves through `./src/ui/index.ts`.
- Export `./ui/PocketFamilyOfficePreview` resolves through `./src/ui/PocketFamilyOfficePreview.tsx`.
- Export `./ui/pocket-family-office-preview.data` resolves through `./src/ui/pocket-family-office-preview.data.ts`.
- Export `./workflows` resolves through `./src/workflows/index.ts`.
- The package publishes 24 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — bun rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.
- Resolve lint/test regressions after voice capability updates.
- Major change to content generation.

## Notes

- Works alongside `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.knowledge`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.policy-safe-knowledge-assistant

Description: All-in-one template example: policy-safe knowledge assistant with locale/jurisdiction gating, versioned KB snapshots, HITL update pipeline, and learning hub.
Path: packages/examples/policy-safe-knowledge-assistant
URL: /llms/example.policy-safe-knowledge-assistant

# @lssm-tech/example.policy-safe-knowledge-assistant

Website: https://contractspec.io

**All-in-one template example: policy-safe knowledge assistant with locale/jurisdiction gating, versioned KB snapshots, HITL update pipeline, and learning hub.**

## What This Demonstrates

- Composition of multiple example packages into a full-stack assistant.
- Orchestrator pattern (`buildAnswer`) for policy-gated responses.
- React dashboard with hooks and UI components.
- Seed data and fixture patterns.
- Feature definition aggregating sub-features.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/policy-safe-knowledge-assistant`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.policy-safe-knowledge-assistant` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/integration.test.ts` is part of the package's public or composition surface.
- `src/orchestrator` is part of the package's public or composition surface.
- `src/policy-safe-knowledge-assistant.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/policy-safe-knowledge-assistant.docblock` resolves through `./src/docs/policy-safe-knowledge-assistant.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./handlers/policy-safe-knowledge-assistant.handlers` resolves through `./src/handlers/policy-safe-knowledge-assistant.handlers.ts`.
- Export `./orchestrator/buildAnswer` resolves through `./src/orchestrator/buildAnswer.ts`.
- Export `./policy-safe-knowledge-assistant.feature` resolves through `./src/policy-safe-knowledge-assistant.feature.ts`.
- Export `./seed` resolves through `./src/seed/index.ts`.
- Export `./seed/fixtures` resolves through `./src/seed/fixtures.ts`.
- The package publishes 14 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/example.kb-update-pipeline`, `@lssm-tech/example.learning-patterns`, `@lssm-tech/example.locale-jurisdiction-gate`, `@lssm-tech/example.versioned-knowledge-base`, `@lssm-tech/lib.contracts-spec`, ...


---

## @lssm-tech/example.product-intent

Description: Product intent example: evidence ingestion and prompt-ready outputs.
Path: packages/examples/product-intent
URL: /llms/example.product-intent

# @lssm-tech/example.product-intent

Website: https://contractspec.io

**Product intent example: evidence ingestion and prompt-ready outputs.**

## What This Demonstrates

- Canonical `product-intent` export via `ProductIntentDiscoverySpec`.
- Evidence loading and ingestion pipeline.
- PostHog signal extraction for product analytics.
- Action synchronization across tools.
- Script-based execution pattern.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/product-intent`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.product-intent` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/load-evidence.test.ts` is part of the package's public or composition surface.
- `src/load-evidence.ts` is part of the package's public or composition surface.
- `src/posthog-signals.ts` is part of the package's public or composition surface.
- `src/product-intent.discovery.ts` defines the exported product-intent spec.
- `src/product-intent.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/product-intent.docblock` resolves through `./src/docs/product-intent.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./load-evidence` resolves through `./src/load-evidence.ts`.
- Export `./posthog-signals` resolves through `./src/posthog-signals.ts`.
- Export `./product-intent.discovery` resolves through `./src/product-intent.discovery.ts`.
- Export `./product-intent.feature` resolves through `./src/product-intent.feature.ts`.
- Export `./script` resolves through `./src/script.ts`.
- Export `./sync-actions` resolves through `./src/sync-actions.ts`.
- The package publishes 9 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-analytics`, `@lssm-tech/integration.provider-project-management`, `@lssm-tech/lib.ai-agent`, `@lssm-tech/lib.analytics`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, ...


---

## @lssm-tech/example.project-management-sync

Description: Project management sync example: Linear, Jira, and Notion work item creation.
Path: packages/examples/project-management-sync
URL: /llms/example.project-management-sync

# @lssm-tech/example.project-management-sync

Website: https://contractspec.io

**Project management sync example: Linear, Jira, and Notion work item creation.**

## What This Demonstrates

- Multi-provider sync pattern (Linear, Jira, Notion).
- Work item creation from contract definitions.
- Run script for one-shot execution.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Preview / export workflow

Project Management Sync previews must never instantiate Linear, Jira, Notion, or other provider SDK clients. A future `./ui` export should render local sync overview, provider mapping, conflict review, and draft work-item approval fixtures only.

Keep provider writes represented as draft/approval states, not real network execution. Public key behavior is compatibility-sensitive because current catalog consumers may resolve both `examples.project-management-sync` and normalized keys.

## Running Locally

From `packages/examples/project-management-sync`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.project-management-sync` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/project-management-sync.feature.ts` defines a feature entrypoint.
- `src/run.ts` is part of the package's public or composition surface.
- `src/sync.ts` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/project-management-sync.docblock` resolves through `./src/docs/project-management-sync.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./project-management-sync.feature` resolves through `./src/project-management-sync.feature.ts`.
- Export `./run` resolves through `./src/run.ts`.
- Export `./sync` resolves through `./src/sync.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/integration.provider-project-management`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.saas-boilerplate

Description: SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings
Path: packages/examples/saas-boilerplate
URL: /llms/example.saas-boilerplate

# @lssm-tech/example.saas-boilerplate

Website: https://contractspec.io

**SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings.**

## What This Demonstrates

- Multi-domain SaaS architecture (billing, project, settings, dashboard).
- Per-domain entity/enum/event/handler/operations/presentation/schema pattern.
- React UI with hooks, modals, overlays, renderers, and dashboard.
- Contract-backed visualizations for portfolio status, tier mix, usage, and recent project activity.
- Feature definition, seeders, and test-spec patterns.
- RBAC, audit trail, and notification module integration.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/saas-boilerplate`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.saas-boilerplate` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/billing` is part of the package's public or composition surface.
- `src/dashboard` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/presentations` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./billing` resolves through `./src/billing/index.ts`.
- Export `./billing/billing.entity` resolves through `./src/billing/billing.entity.ts`.
- Export `./billing/billing.enum` resolves through `./src/billing/billing.enum.ts`.
- Export `./billing/billing.event` resolves through `./src/billing/billing.event.ts`.
- Export `./billing/billing.handler` resolves through `./src/billing/billing.handler.ts`.
- Export `./billing/billing.operations` resolves through `./src/billing/billing.operations.ts`.
- Export `./billing/billing.presentation` resolves through `./src/billing/billing.presentation.ts`.
- Export `./billing/billing.schema` resolves through `./src/billing/billing.schema.ts`.
- Export `./dashboard` resolves through `./src/dashboard/index.ts`.
- The package publishes 48 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.identity-rbac`, `@lssm-tech/lib.jobs`, ...


---

## @lssm-tech/example.service-business-os

Description: Service Business OS example (clients, quotes, jobs, invoices) for ContractSpec
Path: packages/examples/service-business-os
URL: /llms/example.service-business-os

# @lssm-tech/example.service-business-os

Website: https://contractspec.io

**Service Business OS example (clients, quotes, jobs, invoices) for ContractSpec.**

## What This Demonstrates

- Multi-entity domain modeling (client, quote, job, invoice, payment).
- Per-entity schema and operations pattern.
- Capability and feature definition patterns.
- Presentation layer and event-driven architecture.
- Handler aggregation.
- `src/docs/` contains docblocks and documentation-facing exports.

## Preview / export workflow

Service Business OS already publishes `./presentations` for deterministic service-business screens. The package-native `./ui` preview wraps service-business panels in the shared `NestedCommandShell` from `@lssm-tech/lib.example-shared-ui`; keep compatible inline preview work on that reusable nested-safe shell and use an explicitly approved module/examples presentation renderer only when the registry owns the replay adapter.

Keep preview data local and deterministic across client, quote, job, invoice, and payment states. Docs, sandbox, LLMS, and source fallback links should remain visible even when a host renders the richer inline preview.

## Running Locally

From `packages/examples/service-business-os`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.service-business-os` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/client` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./client` resolves through `./src/client/index.ts`.
- Export `./client/client.operations` resolves through `./src/client/client.operations.ts`.
- Export `./client/client.schema` resolves through `./src/client/client.schema.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/service-business-os.docblock` resolves through `./src/docs/service-business-os.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- The package publishes 26 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.special-ops-cockpit

Description: French fake-data Special Ops Cockpit template for mission dashboards, private daily journals, review workflows, playbooks, weekly reporting, AI governance, and roadmap planning.
Path: packages/examples/special-ops-cockpit
URL: /llms/example.special-ops-cockpit

# @lssm-tech/example.special-ops-cockpit

**Special Ops Cockpit** est une maquette ContractSpec headless, en français et avec données fictives, pour piloter une mission de retournement PME sans transformer l'IA en chatbot ni en outil de surveillance.

Elle matérialise une mission NDconsulting / Desliance comme un système pilotable : dashboard, journal privé, structuration des actions, cartes de revue, playbook 48h, synthèse hebdomadaire, gouvernance IA et feuille de route de modules futurs.

## Pourquoi cet exemple existe

Les missions de crise mélangent décisions rapides, preuves terrain, risques cash, reporting incomplet et transmission de méthode. Sans structure, les informations restent dans des notes, des mails, des tableurs ou des conversations dispersées.

Ce cockpit montre comment ContractSpec peut rendre ces workflows explicites :

- les opérations sont déclarées comme contrats ;
- les handlers restent déterministes et testables ;
- les données sont synthétiques, françaises et démonstratives ;
- les éléments soumis deviennent auditables ;
- les brouillons et suggestions restent privés tant qu'ils ne sont pas soumis ;
- la validation humaine reste obligatoire avant toute synthèse ou action de pilotage.

## Ce que la démo démontre

- **Mission Dashboard** — état de mission visible par Nathalie, limité aux artefacts soumis et revus.
- **Journal de mission** — brouillon privé pour Hugo, avec structuration assistée des actions, risques, prochaines étapes et preuves de valeur.
- **Trust Panel** — séparation explicite entre ce qui est visible, non visible, auditable et interdit.
- **Review Cards** — cartes soumises avec source attachée, décision humaine et options approuver / modifier / rejeter / inclure / créer action / escalader.
- **Playbook 48h** — jalons de retournement, preuves attendues, blocages et manques d'information.
- **Weekly Report** — synthèse hebdomadaire uniquement à partir de cartes approuvées, export Markdown stable, statut brouillon jusqu'à validation.
- **AI Stack Governance** — lecture des profils d'équipe, niveaux de maturité IA, risques de données et besoins de formation sans recommandation fournisseur définitive.
- **Future Modules** — roadmap Cash Scenario Simulator, Qualiopi, onboarding, PO/ARC matching, e-invoicing, knowledge base, mission playbook et offre Desliance.

## Modèle de confiance

Doc route: `/docs/examples/special-ops-cockpit/trust-model`.

Ce n'est pas un dispositif de contrôle salarié. Le cockpit est auditable au niveau mission, pas intrusif au niveau individu.

Le système **ne montre pas** à Nathalie :

- les brouillons privés non soumis ;
- les suggestions ignorées ;
- les captures d'écran ;
- l'historique navigateur ;
- les temps d'activité ;
- les scores de productivité ;
- les notes brutes avant soumission.

Le système **montre uniquement** :

- les artefacts explicitement soumis ;
- les cartes de revue créées depuis ces artefacts ;
- les décisions de validation ;
- les preuves attachées à une action mission ;
- les manques de preuve nécessaires pour piloter la mission.

## Mapping ContractSpec

| Concept ContractSpec | Rôle dans l'exemple |
| --- | --- |
| `defineExample` | Déclare le template public `special-ops-cockpit`. |
| `defineFeature` | Regroupe les neuf opérations cockpit. |
| Operation contracts | Formalisent dashboard, journal, revue, playbook, rapport, gouvernance et roadmap. |
| Fixtures | Fournissent la mission fictive `Fonderie Atlantique`, les dix personas et les notes terrain. |
| Handlers | Produisent des résultats déterministes, sans réseau, LLM, base de données ni fichiers. |
| Render models | Exposent les écrans headless que l'UI future pourra consommer. |
| Docblocks | Publient l'overview, le modèle de confiance et le script de démo. |

## Ce qui est simulé

- Client fictif : `Fonderie Atlantique`, PME industrielle de 85 salariés et 14M€ de CA.
- Mission : crise cash, départ RAF, reporting absent, litiges fournisseurs et risque approvisionnement.
- Données : notes terrain synthétiques, montants de démonstration `42k€`, `28k€`, `18k€`.
- Acteurs : Nathalie D., Hugo V., Marc P., Fritz L., Léa G. et autres personas fictifs.
- IA : assistance structurante simulée, jamais autonome, toujours sous revue humaine.

## Running Locally

Depuis `packages/examples/special-ops-cockpit` :

- `bun run build`
- `bun run typecheck`
- `bun run test`
- `bun run smoke`
- `bun run preflight`

Depuis la racine du monorepo, si le workspace est disponible :

- `bun ./node_modules/turbo/bin/turbo run typecheck --filter=@lssm-tech/example.special-ops-cockpit`
- `bun ./node_modules/turbo/bin/turbo run build --filter=@lssm-tech/example.special-ops-cockpit`
- `bun ./node_modules/turbo/bin/turbo run test --filter=@lssm-tech/example.special-ops-cockpit`

## Déroulé de démo 10 minutes

Doc route: `/docs/examples/special-ops-cockpit/demo-script`. Le script importable vit dans `@lssm-tech/example.special-ops-cockpit/docs/demo-script-ndconsulting`.

1. **Positionner la promesse** — présenter une maquette fonctionnelle de cockpit mission, pas un produit fini ni un chatbot.
2. **Ouvrir le Mission Dashboard** — montrer l'état de la mission, les risques cash et les artefacts visibles par Nathalie.
3. **Passer au Journal de mission** — montrer l’espace et la frontière de brouillon privé sans exposer son contenu, puis expliquer que rien ne remonte sans soumission.
4. **Structurer une note terrain** — transformer une note brute en action, risque, preuve et prochaine étape.
5. **Soumettre une entrée** — créer une trace auditée et des cartes de revue.
6. **Afficher le Trust Panel** — expliciter ce qui est visible, non visible et interdit.
7. **Revoir les cartes** — Nathalie approuve, modifie, rejette ou escalade des éléments soumis.
8. **Lire le Playbook 48h** — relier les entrées soumises aux jalons et preuves attendues.
9. **Composer la synthèse hebdo** — inclure uniquement les cartes approuvées et garder le rapport en brouillon.
10. **Terminer par la roadmap** — relier le pilote à l'offre Desliance : cash scenario, Qualiopi, onboarding, PO/ARC, e-invoicing et knowledge base.

## Script commercial court

> J'ai préparé une maquette fonctionnelle, pas comme un produit fini, mais pour matérialiser ce que pourrait être un cockpit Special Ops. L'idée n'est pas un chatbot ni un outil de surveillance. L'idée est de transformer une mission en système pilotable : playbook, journal de mission, validation, synthèse et capitalisation.

Le bon premier pilote serait une mission réelle ou anonymisée avec journal de mission, review Nathalie, playbook 48h et synthèse hebdo.

## Pilote NDconsulting / Desliance suggéré

- **Semaine 1** : choisir une mission réelle ou anonymisée, cadrer le journal de mission et les cartes de revue.
- **Semaine 2** : valider le playbook 48h, les preuves attendues et la synthèse hebdomadaire.
- **Semaine 3** : tester la gouvernance IA par persona et choisir les deux modules suivants.
- **Semaine 4** : transformer les apprentissages en offre Desliance AI Finance Ops Sprint.

## Public Entry Points

- `@lssm-tech/example.special-ops-cockpit`
- `@lssm-tech/example.special-ops-cockpit/contracts`
- `@lssm-tech/example.special-ops-cockpit/docs`
- `@lssm-tech/example.special-ops-cockpit/docs/special-ops-cockpit.docblock`
- `@lssm-tech/example.special-ops-cockpit/docs/demo-script-ndconsulting`
- `@lssm-tech/example.special-ops-cockpit/example`
- `@lssm-tech/example.special-ops-cockpit/fixtures`
- `@lssm-tech/example.special-ops-cockpit/handlers`
- `@lssm-tech/example.special-ops-cockpit/proof`
- `@lssm-tech/example.special-ops-cockpit/special-ops-cockpit.feature`
- `@lssm-tech/example.special-ops-cockpit/ui`
- `@lssm-tech/example.special-ops-cockpit/ui/SpecialOpsCockpitPreview`
- `@lssm-tech/example.special-ops-cockpit/ui/special-ops-cockpit-preview.data`

## Preview / export workflow

The public template preview for this example is package-native: the `./ui` export renders a contained interactive cockpit with nested navigation, a landing screen, and eight workflow-specific targets for mission dashboard, journal, trust panel, review cards, 48h playbook, weekly report, AI governance, and future modules from deterministic fixtures already owned by this package. The sidebar is scoped to the preview surface so hosts can embed it below their own headers without viewport overlap. The eight operational screen keys and order remain the compatibility contract; landing and navigation data are additive.

Reusable shell exception: unlike compatible examples such as Integration Hub, BillingOS France SME, and Service Business OS, this preview intentionally does not wrap the cockpit in `NestedCommandShell`. Its local shell owns a contained nested navigation rail so host pages can embed the cockpit below their own headers without fixed-position overlap, viewport takeover, or leakage of private-draft trust boundaries. Keep the local navigation exception documented here unless those containment guardrails move into the shared nested-safe shell contract.

Consumers should keep the docs, sandbox, LLMS, source, preview, and render-model fallback links visible. A registry refresh must be produced by the generator rather than by hand-editing generated files.

## Notes d'implémentation

- Les fixtures restent fictives et ne doivent pas contenir de données client réelles.
- Les handlers doivent rester purs, déterministes et sans accès réseau, LLM, DB, filesystem ou environnement.
- Les exports publics incluent `./ui` : les écrans restent alimentés par des fixtures déterministes et des render models de démo.
- Toute refresh de registry doit passer par le générateur, jamais par édition manuelle.
- Les changements de démo et de metadata doivent rester cohérents avec `AGENTS.md`, `CHANGELOG.md`, `package.json`, les docblocks et les exports publics.


---

## @lssm-tech/example.team-hub

Description: Team Hub example with spaces, tasks, rituals, and announcements
Path: packages/examples/team-hub
URL: /llms/example.team-hub

# @lssm-tech/example.team-hub

Website: https://contractspec.io

**Team Hub example with spaces, tasks, rituals, and announcements.**

## What This Demonstrates

- Multi-entity team collaboration domain (space, task, ritual, announcement).
- Per-entity schema and operations pattern.
- Capability and feature definition patterns.
- Presentation layer with team-hub presentation.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/team-hub`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.team-hub` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/announcement` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./announcement` resolves through `./src/announcement/index.ts`.
- Export `./announcement/announcement.operations` resolves through `./src/announcement/announcement.operations.ts`.
- Export `./announcement/announcement.schema` resolves through `./src/announcement/announcement.schema.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/team-hub.docblock` resolves through `./src/docs/team-hub.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- The package publishes 23 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.versioned-knowledge-base

Description: Example: curated, versioned knowledge base with immutable sources, rule versions, and published snapshots.
Path: packages/examples/versioned-knowledge-base
URL: /llms/example.versioned-knowledge-base

# @lssm-tech/example.versioned-knowledge-base

Website: https://contractspec.io

**Example: curated, versioned knowledge base with immutable sources, rule versions, and published snapshots.**

## What This Demonstrates

- Immutable source and versioned rule management.
- Snapshot publishing pattern.
- Canonical `migration` export via `KnowledgeSnapshotPublicationMigration`.
- Entity models for KB domain.
- Memory-based handler implementation.
- Feature definition and event-driven architecture.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/versioned-knowledge-base`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.versioned-knowledge-base` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/knowledge-snapshot-publication.migration.ts` defines the exported migration spec.
- `src/operations` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/versioned-knowledge-base.docblock` resolves through `./src/docs/versioned-knowledge-base.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./entities/models` resolves through `./src/entities/models.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./handlers/memory.handlers` resolves through `./src/handlers/memory.handlers.ts`.
- Export `./knowledge-snapshot-publication.migration` resolves through `./src/knowledge-snapshot-publication.migration.ts`.
- Export `./operations` resolves through `./src/operations/index.ts`.
- Export `./operations/kb` resolves through `./src/operations/kb.ts`.
- Export `./versioned-knowledge-base.feature` resolves through `./src/versioned-knowledge-base.feature.ts`.
- The package publishes 12 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.video-api-showcase

Description: Generate API documentation videos from contract spec definitions using the ApiOverview composition.
Path: packages/examples/video-api-showcase
URL: /llms/example.video-api-showcase

# @lssm-tech/example.video-api-showcase

Website: https://contractspec.io

**Generate API documentation videos from contract spec definitions using the ApiOverview composition.**

## What This Demonstrates

- Video generation pipeline from contract specs.
- ApiOverview composition pattern.
- Sample spec definitions for video input.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/video-api-showcase`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.video-api-showcase` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/build-api-video.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/sample-specs.ts` is part of the package's public or composition surface.
- `src/video-api-showcase.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./build-api-video` resolves through `./src/build-api-video.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/video-api-showcase.docblock` resolves through `./src/docs/video-api-showcase.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./sample-specs` resolves through `./src/sample-specs.ts`.
- Export `./video-api-showcase.feature` resolves through `./src/video-api-showcase.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.video-gen`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.video-docs-terminal

Description: Generate terminal demo videos from CLI walkthroughs using the TerminalDemo composition and ScriptGenerator.
Path: packages/examples/video-docs-terminal
URL: /llms/example.video-docs-terminal

# @lssm-tech/example.video-docs-terminal

Website: https://contractspec.io

**Generate terminal demo videos from CLI walkthroughs using the TerminalDemo composition and ScriptGenerator.**

## What This Demonstrates

- Terminal demo video generation pipeline.
- Narration generation from CLI walkthroughs.
- Sample tutorial definitions for video input.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/video-docs-terminal`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.video-docs-terminal` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/build-tutorial.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/generate-narration.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/sample-tutorials.ts` is part of the package's public or composition surface.
- `src/video-docs-terminal.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./build-tutorial` resolves through `./src/build-tutorial.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/video-docs-terminal.docblock` resolves through `./src/docs/video-docs-terminal.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./generate-narration` resolves through `./src/generate-narration.ts`.
- Export `./sample-tutorials` resolves through `./src/sample-tutorials.ts`.
- Export `./video-docs-terminal.feature` resolves through `./src/video-docs-terminal.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.content-gen`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.video-gen`, `@lssm-tech/tool.bun`, ...


---

## @lssm-tech/example.video-marketing-clip

Description: Generate short-form marketing videos from content briefs using the video-gen pipeline.
Path: packages/examples/video-marketing-clip
URL: /llms/example.video-marketing-clip

# @lssm-tech/example.video-marketing-clip

Website: https://contractspec.io

**Generate short-form marketing videos from content briefs using the video-gen pipeline.**

## What This Demonstrates

- Marketing clip generation from content briefs.
- Brief definition pattern for video input.
- Video-gen pipeline consumption.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/video-marketing-clip`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.video-marketing-clip` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/briefs.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/generate-clip.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/video-marketing-clip.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./briefs` resolves through `./src/briefs.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/video-marketing-clip.docblock` resolves through `./src/docs/video-marketing-clip.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./generate-clip` resolves through `./src/generate-clip.ts`.
- Export `./video-marketing-clip.feature` resolves through `./src/video-marketing-clip.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.content-gen`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.video-gen`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.visualization-showcase

Description: Focused visualization showcase for ContractSpec primitives and design-system wrappers
Path: packages/examples/visualization-showcase
URL: /llms/example.visualization-showcase

# Visualization Showcase

`@lssm-tech/example.visualization-showcase` is the focused reference package for ContractSpec's visualization layer.

It demonstrates:

- Contract-owned `VisualizationSpec` primitives
- Shared visualization registries and refs
- Design-system wrappers like `VisualizationCard`, `VisualizationGrid`, `ComparisonView`, and `TimelineView`
- Markdown summaries for non-React surfaces

Use this package when you want a lightweight, deterministic reference for the visualization contract model without the heavier domain logic of `analytics-dashboard`.


---

## @lssm-tech/example.voice-providers

Description: Voice provider example: Gradium and Fal text-to-speech integration patterns.
Path: packages/examples/voice-providers
URL: /llms/example.voice-providers

# @lssm-tech/example.voice-providers

Website: https://contractspec.io

**Voice provider example: Gradium and Fal text-to-speech integration patterns.**

## What This Demonstrates

- TTS provider integration pattern with connection samples.
- Handler-per-action pattern (create-provider, list-voices, synthesize).
- Run script for one-shot execution.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/docs/` contains docblocks and documentation-facing exports.

## Running Locally

From `packages/examples/voice-providers`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.voice-providers` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/connection.sample.ts` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/run.ts` is part of the package's public or composition surface.
- `src/voice-providers.feature.ts` defines a feature entrypoint.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./connection.sample` resolves through `./src/connection.sample.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/voice-providers.docblock` resolves through `./src/docs/voice-providers.docblock.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers/create-provider` resolves through `./src/handlers/create-provider.ts`.
- Export `./handlers/list-voices` resolves through `./src/handlers/list-voices.ts`.
- Export `./handlers/synthesize` resolves through `./src/handlers/synthesize.ts`.
- Export `./run` resolves through `./src/run.ts`.
- Export `./voice-providers.feature` resolves through `./src/voice-providers.feature.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.
- Major change to content generation.

## Notes

- Works alongside `@lssm-tech/integration.provider-voice`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.


---

## @lssm-tech/example.voiceops-operating-graph

Description: VoiceOps operating graph example: conversation → governed operating graph (DataViewGraphSpec canary replacing hackathon GraphCanvas)
Path: packages/examples/voiceops-operating-graph
URL: /llms/example.voiceops-operating-graph

# @lssm-tech/example.voiceops-operating-graph

**VoiceOps operating graph — `DataViewGraphSpec` canary replacing the hackathon `GraphCanvas`.**

## What This Demonstrates

- `voiceOpsOperatingGraphView: DataViewGraphSpec` with `inline-op` source and `author` layout.
- The 10 VoiceOps node kinds: `voiceSignal`, `transcript`, `customerPain`, `productGap`, `sensitiveData`, `internalTask`, `customerCommitment`, `policyGate`, `approvalGate`, `evidenceReceipt`.
- How a conversation becomes a governed operating graph: captured → extracted → classified → gated → approved → evidenced.

## Feature Parity (pending Phase 3 renderer)

| Feature | Status |
|---------|--------|
| Search by id/label/kind | Spec declared — renderer P3/W3.2 |
| Kind filter dropdown | Spec declared — renderer P3/W3.2 |
| Node selection → inspector | `inspector: 'panel'` declared |
| Edge selection → inspector | Spec declared |
| Pulse on customerCommitment + policyGate | `experiments` metadata — renderer P3/W3.2 |
| ARIA `role="application"` + keyboard | Renderer responsibility (P3/W3.2) |
| Author-supplied layout | `layout: 'author'` declared |

## Running Locally

From `packages/examples/voiceops-operating-graph`:

```bash
bun run typecheck
bun run test
```

## Architecture

- `src/voiceOpsOperatingGraphView.ts` — spec, node kind constants, DocBlock
- `src/index.ts` — public barrel

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`.
- Full RTL parity test suite lands in #43 (P6/W6.3).
- Replaces `companyos-ai-os-proofs/src/ui/operating-graph-canvas.tsx` import dependency.


---

## @lssm-tech/example.wealth-snapshot

Description: Wealth Snapshot mini-app for accounts, assets, liabilities, and goals
Path: packages/examples/wealth-snapshot
URL: /llms/example.wealth-snapshot

# @lssm-tech/example.wealth-snapshot

Website: https://contractspec.io

**Wealth Snapshot mini-app for accounts, assets, liabilities, and goals.**

## What This Demonstrates

- Financial entity modeling (accounts, assets, liabilities, goals).
- Capability and feature definition patterns.
- Presentation layer and event-driven architecture.
- RBAC, audit trail, and notification module integration.
- An inline `WealthSnapshotPreview` UI for template and example browsers.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.

## Running Locally

From `packages/examples/wealth-snapshot`:
- `bun run dev`
- `bun run build`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.wealth-snapshot` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/events.ts` is package-level event definitions.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/operations` is part of the package's public or composition surface.
- `src/ui/` contains the inline preview surface for catalog and template browsers.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/wealth-snapshot.docblock` resolves through `./src/docs/wealth-snapshot.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- Export `./events` resolves through `./src/events.ts`.
- Export `./example` resolves through `./src/example.ts`.
- Export `./handlers` resolves through `./src/handlers/index.ts`.
- Export `./operations` resolves through `./src/operations/index.ts`.
- Export `./presentations` resolves through `./src/presentations.ts`.
- Export `./ui` resolves through `./src/ui/index.ts`.
- Export `./ui/WealthSnapshotPreview` resolves through `./src/ui/WealthSnapshotPreview.tsx`.
- Export `./ui/wealth-snapshot-preview.data` resolves through `./src/ui/wealth-snapshot-preview.data.ts`.
- Export `./wealth-snapshot.capability` resolves through `./src/wealth-snapshot.capability.ts`.
- Export `./wealth-snapshot.feature` resolves through `./src/wealth-snapshot.feature.ts`.
- The package publishes 14 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Missing contract layers.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.identity-rbac`, `@lssm-tech/lib.notification`, `@lssm-tech/lib.schema`, `@lssm-tech/module.audit-trail`, ...


---

## @lssm-tech/example.workflow-system

Description: Workflow and approval system example for ContractSpec - State machine with role-based transitions
Path: packages/examples/workflow-system
URL: /llms/example.workflow-system

# @lssm-tech/example.workflow-system

Website: https://contractspec.io

**Workflow and approval system example for ContractSpec - State machine with role-based transitions.**

## What This Demonstrates

- **Rich Landing Screen**: Product introduction explaining workflow orchestration concepts, demo path, and navigation.
- **Navigation Rail**: Clear sidebar navigation between Overview, Templates, Instances, Approvals, and Analytics.
- **State Machine Pattern**: Workflow transitions with defined states and allowed transitions.
- **Approval Flow**: Role-based access control for approval decisions.
- **Multi-Entity Domain**: Workflow definitions, instances, steps, and approvals.
- **React UI**: WorkflowDashboard with templates, instances, and visualizations.
- **Contract-Backed Visualizations**: Status, throughput, and workload analysis.
- **Demo Scenarios**: Expense Approval, Vendor Onboarding, and Policy Exception workflows with sample data.

## Canonical Demo Path

1. **Landing Screen** - Start on the product introduction explaining workflow orchestration.
2. **Navigation** - Use the sidebar rail to explore Templates, Instances, and Approvals.
3. **Templates** - View workflow definitions (Expense Approval, Vendor Onboarding, Policy Exception).
4. **Instances** - See running workflows with their current states.
5. **Approvals** - Review pending approvals and role-based access.
6. **Analytics** - View throughput metrics and workload analysis.

### New Features

- **LandingScreen**: Product-style introduction with value proposition and demo path.
- **WorkflowSystemPreviewV2**: Enhanced preview with sidebar navigation.
- **WorkflowNav**: Navigation rail for moving between workflow sections.
- **Demo Scenarios**: Three complete workflow examples with sample instances.

## Running Locally

From `packages/examples/workflow-system`:
- `bun run dev`
- `bun run build`
- `bun run test`
- `bun run typecheck`

## Usage

Use `@lssm-tech/example.workflow-system` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

## Architecture

- `src/approval` is part of the package's public or composition surface.
- `src/docs/` contains docblocks and documentation-facing exports.
- `src/entities/` contains domain entities and value objects.
- `src/example.ts` is the runnable example entrypoint.
- `src/handlers/` contains handlers or demo adapters wired to contract surfaces.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/instance` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./approval` resolves through `./src/approval/index.ts`.
- Export `./approval/approval.enum` resolves through `./src/approval/approval.enum.ts`.
- Export `./approval/approval.event` resolves through `./src/approval/approval.event.ts`.
- Export `./approval/approval.handler` resolves through `./src/approval/approval.handler.ts`.
- Export `./approval/approval.operations` resolves through `./src/approval/approval.operations.ts`.
- Export `./approval/approval.schema` resolves through `./src/approval/approval.schema.ts`.
- Export `./docs` resolves through `./src/docs/index.ts`.
- Export `./docs/workflow-system.docblock` resolves through `./src/docs/workflow-system.docblock.ts`.
- Export `./entities` resolves through `./src/entities/index.ts`.
- The package publishes 44 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild
- `bun run test` — bun test

## Recent Updates

- **UI Improvements**: Added LandingScreen, WorkflowNav, and WorkflowSystemPreviewV2 with enhanced navigation.
- **Demo Scenarios**: Complete workflow examples with Expense Approval, Vendor Onboarding, and Policy Exception.
- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.design-system`, `@lssm-tech/lib.example-shared-ui`, `@lssm-tech/lib.runtime-sandbox`, `@lssm-tech/lib.schema`, ...


---

## @lssm-tech/agentpacks

Description: Composable AI agent configuration manager. Pack-based rules, commands, skills, hooks, and MCP sync across OpenCode, Cursor, Claude Code, Codex, Gemini, Copilot, and more.
Path: packages/tools/agentpacks
URL: /llms/agentpacks

# agentpacks

Website: https://github.com/lssm-tech/contractspec/tree/main/packages/tools/agentpacks

**Composable AI agent configuration manager that merges packs into target-specific tool configuration, rules, hooks, skills, and AGENTS output.**

## What It Provides

- Loads, merges, and resolves agent packs into Cursor, Claude Code, Codex, Copilot, Gemini, OpenCode, registry, and AGENTS targets.
- Publishes a CLI plus a broad programmatic API for pack loading, sources, targets, importers, and exporters.
- Recently expanded around AI-native flows, model guidance, Cursor plugin output, and compatibility hardening.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install agentpacks`

or

`bun add agentpacks`

## Usage

```bash
npx agentpacks --help
# or
bunx agentpacks --help
```

### Generate and RTK refresh

After a successful non-dry-run `agentpacks generate` writes files, the CLI runs
`rtk init` and then `rtk init --codex` to refresh Claude Code and Codex RTK
guidance. Dry runs, diff-only runs, no-op generations, and partial generations
with target errors skip the RTK refresh. RTK command failures are reported as
warnings after generation output is written.

## Platform compatibility and canonical packs

Agentpacks is migrating from file-only pack prose toward typed all-content feature units that can render or transform platform-native artifacts without semantic drift or silent loss. The public contract is:

- canonical production guidance lives in three pack families: ContractSpec-specific, software best practices, and monorepo-specific ContractSpec mission/goals/constraints;
- each canonical pack includes `feature-units.json` as the typed all-content migration baseline;
- every meaningful prose feature unit must keep a shared invariant and explicit Claude plus Codex/GPT variants;
- OpenCode selects the Codex/GPT operational variant by default;
- Codex CLI generation treats root `AGENTS.md` as the primary operational guidance surface and may also emit `.codex/*` artifacts;
- structural feature units such as hooks, MCP, model profiles, plugins, ignore files, assets, manifests, and exported docs require target capability status, transform/loss policy, diagnostics, and trace evidence;
- generated files must preserve traceability back to feature-unit ids and Connect parity evidence;
- `agentpacks:all` is the selected core-target smoke run, while `agentpacks:compat:all-targets` is the exhaustive registered-target compatibility run.

See `docs/agentpacks-platform-compatibility.md` and `packs/README.md` in the ContractSpec repository for the canonical taxonomy, legacy-pack disposition, and release gates.

## Architecture

- `src/cli/` contains command implementations for init, generate, install, publish, search, and pack subcommands.
- `src/core/` handles config loading, dependency resolution, pack loading, typed feature-unit coverage validation, lockfiles, and feature merging.
- `src/features/`, `src.sources/`, `src.targets/`, `src.importers/`, and `src.exporters/` implement the pack pipeline.
- `src.utils/` contains credentials, diffing, markdown, registry, and model-helper utilities.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Exports the CLI binary plus API, core, features, targets, sources, importers, exporters, and utility subpaths.
- Binary `agentpacks` points to `./dist/index.js`.
- Export `.` resolves through `./src/index.ts`.
- Export `./api` resolves through `./src/api.ts`.
- Export `./cli/export-cmd` resolves through `./src/cli/export-cmd.ts`.
- Export `./cli/generate` resolves through `./src/cli/generate.ts`.
- Export `./cli/import-cmd` resolves through `./src/cli/import-cmd.ts`.
- Export `./cli/info` resolves through `./src/cli/info.ts`.
- Export `./cli/init` resolves through `./src/cli/init.ts`.
- Export `./cli/install` resolves through `./src/cli/install.ts`.
- Export `./cli/login` resolves through `./src/cli/login.ts`.
- Export `./cli/models-explain` resolves through `./src/cli/models-explain.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Use the Biome-only lint and formatting workflow in pack guidance and generated targets.
- Vnext ai-native.
- Add latest models and align defaults.
- Harden AgentSkills compatibility in agentpacks.
- Add first-class mistral provider support.
- Align cursor plugin export and hooks output.

## Notes

- Do not modify target output formats without updating the corresponding target writer, capability matrix, trace/loss diagnostics, and release evidence.
- Pack schema changes must stay backward-compatible (see `schema.json`) unless the release capsule explicitly declares the public compatibility-surface migration and migration evidence.
- Never hard-code model names; use `utils/model-allowlist` and `utils/model-guidance`.


---

## @lssm-tech/biome-config

Description: Biome presets, Grit plugins, and policy manifest for ContractSpec repositories.
Path: packages/tools/biome-config
URL: /llms/biome-config

# @lssm-tech/biome-config

Website: https://contractspec.io

**Typed ContractSpec lint-policy package that generates Biome presets, Grit plugins, and AI-facing rule summaries.**

## What It Provides

- Acts as the source of truth for repository and consumer Biome policy artifacts.
- Publishes generated presets, Grit plugins, and AI summaries alongside the typed manifest and generation helpers.
- Requires artifact synchronization whenever the typed policy manifest changes so committed outputs stay aligned.
- Enforces React and React Native compatible JSX in shared presentation packages by preferring layout primitives (`HStack`, `VStack`, `Box`) over raw `<div>` and requiring visible text to sit inside `Text` or approved typography components. Repository app packages are excluded by default and can be opted in with the policy allowlist.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/biome-config`

or

`bun add @lssm-tech/biome-config`

## Usage

Import the root entrypoint from `@lssm-tech/biome-config`, or choose a documented subpath when you only need one part of the package surface.

### JSX Primitive Fixer

The Biome Grit plugins emit diagnostics only. To apply conservative native HTML replacement fixes, run:

`bun run jsx:fix-primitives`

or from this package:

`bun run fix:jsx-primitives`

By default the fixer scans `packages/bundles`, `packages/examples`, and `packages/modules`. It skips `packages/apps` unless an app is explicitly allowlisted:

`bun run jsx:fix-primitives -- --allow-app web-landing`

Use `--check` for a dry run. The fixer preserves original attributes and className by default, infers safe list props from simple class strings, and wraps raw text with context awareness: block-safe containers keep `<Text>...</Text>`, while mixed-content contexts use inline-safe `<Text asChild><span>...</span></Text>`. Ambiguous form/action primitives remain diagnostic-only, and generic inline `<span>` elements are still skipped.

## Architecture

- `src/policies.ts` defines the typed policy manifest.
- `src/generate.ts` and `src/sync.ts` generate and synchronize derived artifacts.
- `src/fix-jsx-primitives.ts` provides the conservative companion codemod for deterministic JSX primitive replacements.
- `src/types.ts` and `src/index.ts` expose the public API for generation and policy consumption.
- `presets/`, `plugins/`, and `ai/` contain committed generated artifacts consumed by downstream tools.

## Public Entry Points

- Exports the root library API and ships generated presets, Grit plugins, and AI-facing summaries as committed package artifacts.
- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run fix:jsx-primitives` — apply conservative JSX primitive replacements.
- `bun run typecheck` — tsgo --noEmit
- `bun run sync:artifacts` — bun src/sync.ts
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — bun run sync:artifacts && contractspec-bun-build prebuild

## Recent Updates

- Add cross-platform JSX layout and text guardrails for React and React Native compatibility.
- Add a conservative JSX primitive fixer command for deterministic native HTML replacements.
- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- The committed `presets/`, `plugins/`, and `ai/` artifacts are intended for downstream scaffolding without code execution.


---

## @lssm-tech/tool.bun

Description: Shared Bun build presets and CLI for ContractSpec packages
Path: packages/tools/bun
URL: /llms/tool.bun

# @lssm-tech/tool.bun

Website: https://contractspec.io

**Shared Bun build presets and CLI for ContractSpec packages. Provides the `contractspec-bun-build` binary used by nearly every package's `build`, `dev`, and `prebuild` scripts.**

## What It Provides

- **Layer**: tool
- **Consumers**: all monorepo packages (via `contractspec-bun-build` in their scripts)

## Installation

`npm install @lssm-tech/tool.bun`

or

`bun add @lssm-tech/tool.bun`

## Usage

```bash
npx contractspec-bun-build --help
# or
bunx contractspec-bun-build --help
```

## Typed Config

The root package export includes TypeScript declarations for config presets:

```ts
import {
	defineConfig,
	moduleLibrary,
	type BuildConfig,
} from "@lssm-tech/tool.bun";

const config: BuildConfig = {
	...moduleLibrary,
	styleMode: "copy",
};

export default defineConfig(() => config);
```

## Private Build Entries

Packages can emit implementation-only files without adding them to generated package exports. Use `exports.exclude` for files that public entries import relatively but consumers must not import as package subpaths:

```js
export default {
	entry: ['src/**/*.ts', 'src/**/*.tsx'],
	exports: {
		rewrite: true,
		exclude: ['src/**/internal/**'],
	},
};
```

The files still build into `dist`, but `prebuild` omits matching paths from `exports` and `publishConfig.exports`.

## Style Exports

`contractspec-bun-build` scans public CSS style entries separately from TypeScript entries so style files do not affect JavaScript output roots.

Default style entries:

- `styles/**/*.css`
- `src/*.css`
- `!**/*.module.css`

Packages can override or disable style entries from their build config:

```js
export default {
	styleEntry: ['styles/**/*.css'],
	// or: styles: { entry: ['styles/**/*.css'] },
	// or: styleEntry: false,
};
```

By default, style entries are processed with `bun build`. Packages that need to preserve CSS directives for another processor, such as Tailwind `@source`, `@custom-variant`, `@theme`, or `@tailwind`, can copy style files unchanged:

```js
export default {
	styleEntry: ['src/styles/**/*.css'],
	styleMode: 'copy',
	// or: styles: { entry: ['src/styles/**/*.css'], mode: 'copy' },
};
```

Style entries are exported under the `style` and `default` conditions, for example `./styles/globals.css`.

## Type Declaration Emit

`contractspec-bun-build types` emits package declarations with the TypeScript 7
native preview (`tsgo`) by generating a temporary declaration-only tsconfig and
writing `.d.ts` files to `dist`. Apps do not use this package declaration path.

## Platform Variants

`contractspec-bun-build` recognizes platform suffixes in public TypeScript entries and emits conditional exports plus matching build outputs:

| Source suffix | Export condition | Build output |
| --- | --- | --- |
| `.web` | `browser` | `dist/browser/*` plus the Bun default when no base entry exists |
| `.native` | `react-native` | `dist/native/*` |
| `.ios` | `ios` | `dist/native/*` |
| `.android` | `android` | `dist/native/*` |

Exact subpaths such as `./foo.web`, `./foo.native`, `./foo.ios`, and `./foo.android` are exported alongside canonical subpaths such as `./foo`.

## Public Entry Points

- `contractspec-bun-build` -> `./bin/contractspec-bun-build.mjs`
- `.` — `./index.js`

## Local Commands

- `bun run test` — bun test
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary

## Recent Updates

- Add copy mode for public CSS style files that must preserve framework directives
- Add direct CSS style subpath exports for public style files
- Replace eslint+prettier by biomejs to optimize speed
- Add multi platform support to bun build
- Use-client within lib surface-runtime

## Notes

- Changes here affect every package's build pipeline -- test broadly before merging
- Do not remove or rename CLI sub-commands (`transpile`, `types`, `dev`, `prebuild`) without updating all consumers
- Keep the package dependency-light; only `glob` as a dev dependency


---

## @lssm-tech/tool.contracts-mcp-gen

Description: Generator that walks ContractSpec defineCommand/defineQuery specs and produces MCP-compatible tool schemas.
Path: packages/tools/contracts-mcp-gen
URL: /llms/tool.contracts-mcp-gen

(No README.md)

---

## @lssm-tech/tools.contractspec-codemods

Description: Codemods + import-graph scanner that mechanically migrate consumers of the rich-reference legacy surfaces (CodeBlock, DiffBlock, ObjectReferenceHandler, RichContentReference, rich-code-preferences) to the post-S-8 surface (RichBlock, RichRef, RichReference, rich-reference/preferences).
Path: packages/tools/contractspec-codemods
URL: /llms/tools.contractspec-codemods

# `@lssm-tech/tools.contractspec-codemods`

Codemods + import-graph scan that mechanically migrate consumers of the
pre-S-8 rich-reference legacy surface (`CodeBlock`, `DiffBlock`,
`ObjectReferenceHandler/Panel`, `RichContentReference`,
`rich-code-preferences`) to the post-S-8 surface (`RichBlock`, `RichRef`,
`PreviewPanel`, `RichReference`, `rich-reference/preferences`).

See [`MIGRATION.md`](./MIGRATION.md) for the full migration guide,
before/after examples, and human-follow-up cases.

## Quick start

```bash
# Discover legacy call sites (writes discovery-list.json)
bun run scripts/discover.ts --roots packages/ --out discovery-list.json

# Dry-run the codemods
bun run scripts/apply.ts --roots packages/ --dry

# Apply the codemods in place
bun run scripts/apply.ts --roots packages/
```

## Codemods

- `codemod-code-block` — `CodeBlock` → `<RichBlock kind="code">`.
- `codemod-diff-block` — `DiffBlock` → `<RichBlock kind="diff">` (incl.
  `DiffBlock.web` / `DiffBlock.native` platform splits).
- `codemod-object-reference` — `ObjectReferenceHandler` → `<RichRef>` and
  `ObjectReferencePanel` → `<PreviewPanel>`.
- `codemod-rich-content-references` — `RichContentReference` /
  `RichCodeBlockModel` / `RichDiffBlockModel` / `redactRichCodeBlock` /
  `redactRichDiffBlock` → new rich-reference + ui-kit-core equivalents.
- `codemod-personalization-imports` — `rich-code-preferences` subpath →
  `rich-reference/preferences`.

Each codemod is pure (string → string) and idempotent. Run them in the
canonical `STANDARD_CODEMODS` pipeline, or call them individually.

## Safety

The codemods are regex/string-based with a brace-balanced JSX attribute
parser. They use a context scanner that:

- skips strings, template literals, and comments (so docs-page example
  template strings stay intact);
- newline-terminates string scanning (defends against JSX-text
  apostrophes such as "What you'll build" — JS strings cannot contain raw
  newlines per spec, so this is correct in addition to defensive);
- inserts new imports after the last REAL top-level import, never inside
  a template literal.

## CI gate (AC-17)

- Per-PR: `bun run discover` is informational; growth should be flagged.
- Per-release: the migration regression test
  (`__tests__/migration-regression.test.ts`) asserts that every entry in
  `discovery-list.json` was migrated. Zero hits required to ship.

## Files

```
src/
  legacy-symbols.ts        # canonical migration map
  parse-helpers.ts         # safe-span scanner + JSX tag parser
  codemod-runner.ts        # CodemodResult + pipeline helper
  codemod-code-block.ts
  codemod-diff-block.ts
  codemod-object-reference.ts
  codemod-rich-content-references.ts
  codemod-personalization-imports.ts
  import-graph-scan.ts     # AST-ish + string-literal scanner
  index.ts                 # public surface
scripts/
  discover.ts              # writes discovery-list.json
  apply.ts                 # writes codemod output in place
__tests__/                 # fixture tests + migration regression
```


---

## @lssm-tech/tool.contractspec-drizzle-gen

Description: Generator that compiles ContractSpec defineDatabaseTable specs into Drizzle pgTable definitions, relations, and an RLS adapter manifest.
Path: packages/tools/contractspec-drizzle-gen
URL: /llms/tool.contractspec-drizzle-gen

(No README.md)

---

## @lssm-tech/tool.create-contractspec-plugin

Description: CLI tool for creating ContractSpec plugins from templates
Path: packages/tools/create-contractspec-plugin
URL: /llms/tool.create-contractspec-plugin

# @lssm-tech/tool.create-contractspec-plugin

Website: https://contractspec.io

**CLI tool for creating ContractSpec plugins from templates.**

## What It Provides

- **Layer**: tool.
- **Consumers**: plugin authors (via `create-contractspec-plugin` CLI).
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/tool.create-contractspec-plugin`

or

`bun add @lssm-tech/tool.create-contractspec-plugin`

## Usage

```bash
npx create-contractspec-plugin --help
# or
bunx create-contractspec-plugin --help
```

## Architecture

- `src/index.ts` is the root public barrel and package entrypoint.
- `src/templates` is part of the package's public or composition surface.
- `src/utils.ts` is part of the package's public or composition surface.

## Public Entry Points

- Binary `create-contractspec-plugin` points to `./dist/index.js`.
- Export `.` resolves through `./src/index.ts`.
- Export `./templates/example-generator` resolves through `./src/templates/example-generator.ts`.
- Export `./utils` resolves through `./src/utils.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Template files live in `templates/` -- keep them in sync with the current plugin contract.
- Do not change interactive prompts without updating the corresponding template variables.
- Depends on `@lssm-tech/lib.contracts-spec` and `@lssm-tech/lib.schema` -- respect their APIs.


---

## @lssm-tech/tool.docs-generator

Description: CLI tool for generating docs artifacts from ContractSpec specs and DocBlocks
Path: packages/tools/docs-generator
URL: /llms/tool.docs-generator

# @lssm-tech/tool.docs-generator

Website: https://contractspec.io

**CLI tool for generating docs artifacts from ContractSpec specs and DocBlocks.**

## What It Provides

- **Layer**: tool.
- **Consumers**: docs pipeline (`bun run docs:generate`), CI.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/tool.docs-generator`

or

`bun add @lssm-tech/tool.docs-generator`

## Usage

```bash
npx contractspec-docs --help
# or
bunx contractspec-docs --help
```

## Architecture

- `src/fs.ts` is part of the package's public or composition surface.
- `src/generate.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/markdown.test.ts` is part of the package's public or composition surface.
- `src/markdown.ts` is part of the package's public or composition surface.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Binary `contractspec-docs` points to `./dist/index.js`.
- Export `.` resolves through `./src/index.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run docs:generate` — bun src/index.ts generate --source "../../../generated/docs" --out "../../../packages/bundles/library/src/components/docs/generated" --content-root "../../../generated/docs"
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Output paths are configured via CLI flags -- do not hard-code destination directories.
- Depends on `@lssm-tech/lib.contracts-spec` for spec parsing -- changes there may require updates here.
- The `docs:generate` script references relative paths to `generated/docs` and the library bundle; verify paths if the monorepo structure changes.


---

## @lssm-tech/tools.eslint-plugin-i18n

Description: ESLint rules enforcing i18n hygiene: no module-scope translation calls and no raw Accept-Language reads.
Path: packages/tools/eslint-plugin-i18n
URL: /llms/tools.eslint-plugin-i18n

(No README.md)

---

## @lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields

Description: ESLint rule enforcing that every defineReferenceKind() call declares an explicit sensitiveFields array (closes F-4).
Path: packages/tools/eslint-plugin-no-implicit-sensitivefields
URL: /llms/tools.eslint-plugin-no-implicit-sensitivefields

# @lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields

ESLint plugin that enforces explicit `sensitiveFields` declarations on every `defineReferenceKind()` call from `@lssm-tech/lib.contracts-spec/rich-reference`.

Closes plan slice S-1b (architect NR-2 / F-4 mitigation): the contracts-spec runtime already throws when `sensitiveFields` is missing or non-array, but the runtime cannot enforce the additional repository policy that an empty array (`sensitiveFields: []`) must be accompanied by an inline confirmation comment. This rule catches both issues at lint time.

## Install

```bash
bun add -d @lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields
```

`eslint` (>=8, <11) is a peer dependency.

## Flat config (ESLint 9+)

```js
import noImplicitSensitiveFields from '@lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields';

export default [
  {
    plugins: { 'no-implicit-sensitivefields': noImplicitSensitiveFields },
    rules: { 'no-implicit-sensitivefields/no-implicit-sensitivefields': 'error' },
  },
];
```

Or apply the bundled `recommended` flat config in one line:

```js
import { configs } from '@lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields';

export default [configs.recommended];
```

## What the rule does

For every call expression whose callee is `defineReferenceKind` (or `<obj>.defineReferenceKind`):

1. If the object literal argument lacks a `sensitiveFields` property → reports `missing`.
2. If `sensitiveFields: []` appears without a nearby comment containing `confirmed: no sensitive fields` → reports `emptyWithoutComment`.

A "nearby" comment is one whose line number is within ±1 line of the `sensitiveFields` property — covering the common authoring shapes: a leading comment, a same-line trailing comment, or an in-block comment immediately after.

### Valid

```ts
defineReferenceKind({
  id: 'ticket',
  schema,
  sensitiveFields: ['title'],
  defaultPreview: 'inline-card',
  defaultPanel: 'drawer',
  icon: 'ticket',
});

defineReferenceKind({
  id: 'public-doc',
  schema,
  // confirmed: no sensitive fields
  sensitiveFields: [],
  defaultPreview: 'inline-card',
  defaultPanel: 'drawer',
  icon: 'doc',
});

defineReferenceKind({
  id: 'public-doc-2',
  schema,
  sensitiveFields: [], // confirmed: no sensitive fields
  defaultPreview: 'inline-card',
  defaultPanel: 'drawer',
  icon: 'doc',
});
```

### Invalid

```ts
// Missing sensitiveFields entirely
defineReferenceKind({
  id: 'bad-1',
  schema,
  defaultPreview: 'inline-card',
  defaultPanel: 'drawer',
  icon: 'bad',
}); // error: missing

// Empty list without the confirmation marker
defineReferenceKind({
  id: 'bad-2',
  schema,
  sensitiveFields: [],
  defaultPreview: 'inline-card',
  defaultPanel: 'drawer',
  icon: 'bad',
}); // error: emptyWithoutComment
```

## Test

```bash
bun test
```


---

## @lssm-tech/tool.i18n-dead-key-pruner

Description: Build-time tool that prunes unreferenced translation catalog keys using RouteShardManifest reachability and t('key') source scanning
Path: packages/tools/i18n-dead-key-pruner
URL: /llms/tool.i18n-dead-key-pruner

(No README.md)

---

## @lssm-tech/tool.icon-gen

Description: Cross-platform CLI to generate PWA / web icon sets from a source logo (favicon.ico, PNG variants, apple-touch-icon, maskable). Uses sharp + a pure-JS ICO writer — no macOS-only sips dependency.
Path: packages/tools/icon-gen
URL: /llms/tool.icon-gen

(No README.md)

---

## @lssm-tech/tool.test-redaction-rules

Description: Credential-pattern regex corpus for CI telemetry redaction sweeps (T.3).
Path: packages/tools/test-redaction-rules
URL: /llms/tool.test-redaction-rules

(No README.md)

---

## @lssm-tech/tool.tsdown

Description: Shared tsdown config presets for LSSM monorepo
Path: packages/tools/tsdown
URL: /llms/tool.tsdown

# @lssm-tech/tool.tsdown

Website: https://contractspec.io

**Shared tsdown configuration presets for the ContractSpec monorepo. Packages that use tsdown for bundling import this preset to keep build config consistent.**

## What It Provides

- **Layer**: tool
- **Consumers**: packages using tsdown (typically libs with `tsdown.config.js`)

## Installation

`npm install @lssm-tech/tool.tsdown`

or

`bun add @lssm-tech/tool.tsdown`

## Usage

Import the root entrypoint from `@lssm-tech/tool.tsdown`, or use one of the documented subpaths when you want a narrower surface area.

## Public Entry Points

- `.` — `./index.js`

## Local Commands

- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- PublishConfig not supported by bun
- Add examples of integration

## Notes

- Changes affect every tsdown consumer's build output -- test downstream packages before merging
- Peer-depends on `tsdown ^0.21` -- keep in sync with the workspace catalog version
- Keep the preset minimal; package-specific overrides belong in each consumer's `tsdown.config.js`


---

## @lssm-tech/tool.typescript

Description: (none)
Path: packages/tools/typescript
URL: /llms/tool.typescript

# @lssm-tech/tool.typescript

Website: https://contractspec.io

**Shared TypeScript configuration presets (base, nextjs, react-library) extended by every package's `tsconfig.json` in the monorepo.**

## What It Provides

- **Layer**: tool
- **Consumers**: all monorepo packages (via `"extends": "@lssm-tech/tool.typescript/..."`)

## Installation

`npm install @lssm-tech/tool.typescript`

or

`bun add @lssm-tech/tool.typescript`

## Local Commands

- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- PublishConfig not supported by bun
- Migrate non-app builds to shared Bun toolchain

## TypeScript 7 Native Preview

The monorepo keeps the default `typescript` catalog on TypeScript 6 for apps and
framework tooling. Non-app packages can be checked with the side-by-side
TypeScript 7 native preview (`tsgo`) from the repository root:

```sh
bun run typecheck:tsgo:not-apps
```

This command scans `packages/libs`, `packages/modules`, and `packages/bundles`,
uses each package's existing typecheck project (`tsconfig.build.json` when the
package script selects it), and intentionally skips `packages/apps`. Use
`bun run typecheck:tsgo:not-apps:sample` for a fast representative smoke check.

`contractspec-bun-build types` now emits non-app package declarations with
`tsgo`; apps remain on the TypeScript 6 compiler path and do not use this
package declaration pipeline.

Rollback is intentionally narrow: revert `contractspec-bun-build types` to
`tsc`, remove the root `typecheck:tsgo:not-apps` scripts, and remove
`@typescript/native-preview` where it is only needed for tsgo verification.
Package tsconfig presets and app package configs do not need to change.

## Notes

- Compiler option changes propagate to every package -- verify with `bun run typecheck` across the repo
- Do not weaken strict-mode settings (`strict`, `noUncheckedIndexedAccess`, etc.)
- Adding a new preset file requires documenting which packages should use it


---

## @lssm-tech/integration.app-store-connect

Description: Read-first App Store Connect API integration for ReviewReady app submission readiness, with deterministic mocks and secret-ref-only credentials.
Path: packages/integrations/app-store-connect
URL: /llms/integration.app-store-connect

# @lssm-tech/integration.app-store-connect

Read-first App Store Connect integration for ReviewReady app submission
readiness. It maps supported metadata reads to the ContractSpec provider
capability registry and returns typed capability results for everything the
official API does not safely expose.

## Safety policy

- **Read-first / write-disabled.** The port exposes no write/update operations.
  Provider writes are out of scope for this package.
- **Mock-by-default.** Tests and CI use `createMockAppStoreConnectClient`, which
  performs no network access and is fully deterministic (injected clock + ids).
- **Live calls are opt-in.** `createAppStoreConnectClient` only attempts live
  access when `enableLiveCalls` is true, secret-ref auth is present, and a secret
  resolver is supplied. Otherwise reads return typed `degraded` results.
- **No faked data.** Fields the API cannot supply (e.g. App Privacy answers)
  return a typed `manual-required` / `unsupported` / `degraded` capability
  result, never a silent success.

## Secret handling

Auth config carries **secret references only** (`privateKeySecretRefId`). Raw
`.p8` private keys, JWTs, and headers are never accepted as config fields, and
never appear in snapshots, logs, or fixtures. Log entries record only
`provider`, `operation`, `status`, `correlationId`, and `capabilityId`.

## Usage

```ts
import { createMockAppStoreConnectClient } from "@lssm-tech/integration.app-store-connect";

const client = createMockAppStoreConnectClient({
	now: "2026-06-07T12:00:00.000Z",
	correlationId: "corr-001",
});

const metadata = await client.getAppMetadata({ appId: "1234567890" });
const privacy = await client.getAppPrivacyAnswers({ appId: "1234567890" });
// privacy.status === "manual-required"
```

Source: https://developer.apple.com/documentation/appstoreconnectapi/


---

## @lssm-tech/integration.authos-better-auth

Description: Better Auth bridge that maps AuthOS contracts to provider configuration, plugins, and redacted events.
Path: packages/integrations/authos-better-auth
URL: /llms/integration.authos-better-auth

# `@lssm-tech/integration.authos-better-auth`

Better Auth bridge for AuthOS Broad V0.

This package turns AuthOS contracts into Better Auth configuration and maps Better Auth-like user/session/events back to AuthOS contracts. Canonical models stay in `@lssm-tech/lib.authos-spec`; pure projections and security gates stay in `@lssm-tech/lib.authos-runtime`.

## Maturity

- Core email/password, organization/team, admin, OAuth/OIDC client, MFA, magic link, email OTP, phone, and one-tap are runtime-backed through Better Auth `1.6.10` surfaces.
- SSO, SCIM, and passkey are represented as declared external plugin capabilities until their production package wiring is separately reviewed.
- LSSM-as-IdP is contract-only unless `securityReviewRef` is present and production enablement is explicitly gated.

## Verification

```bash
bun run lint:check
bun run typecheck
bun run test
bun run build
```


---

## @lssm-tech/integration.builder-telegram

Description: Telegram Builder control-channel integration.
Path: packages/integrations/builder-telegram
URL: /llms/integration.builder-telegram

# @lssm-tech/integration.builder-telegram

Telegram webhook normalization and Builder control-channel envelope mapping.


---

## @lssm-tech/integration.builder-voice

Description: Voice Builder input integration.
Path: packages/integrations/builder-voice
URL: /llms/integration.builder-voice

# @lssm-tech/integration.builder-voice

Browser and uploaded voice helpers for Builder transcription flows.


---

## @lssm-tech/integration.builder-whatsapp

Description: WhatsApp Builder control-channel integration.
Path: packages/integrations/builder-whatsapp
URL: /llms/integration.builder-whatsapp

# @lssm-tech/integration.builder-whatsapp

Meta and Twilio WhatsApp normalization for Builder control-channel workflows.


---

## @lssm-tech/integration.communication-channel-core

Description: Shared ChannelAdapter port + registry types for CommunicationOS channel integrations (INTERNAL/UNSTABLE until P2-S4 freezes it).
Path: packages/integrations/communication-channel-core
URL: /llms/integration.communication-channel-core

(No README.md)

---

## @lssm-tech/integration.communication-channel-email

Description: CommunicationOS email channel adapter: inbound normalization (provider-email Gmail parse), outbound send (Postmark/Resend), and documented-retention erasure.
Path: packages/integrations/communication-channel-email
URL: /llms/integration.communication-channel-email

(No README.md)

---

## @lssm-tech/integration.communication-channel-slack

Description: CommunicationOS Slack channel adapter: inbound normalization (Events API + signing-secret verify), outbound send (chat.postMessage), and best-effort erasure (chat.delete).
Path: packages/integrations/communication-channel-slack
URL: /llms/integration.communication-channel-slack

(No README.md)

---

## @lssm-tech/integration.communication-channel-sms

Description: CommunicationOS SMS channel adapter: inbound normalization (Twilio webhook parse), outbound send (provider-sms/Twilio), and documented-retention erasure.
Path: packages/integrations/communication-channel-sms
URL: /llms/integration.communication-channel-sms

(No README.md)

---

## @lssm-tech/integration.communication-channel-telegram

Description: CommunicationOS Telegram channel adapter: inbound normalization (builder-telegram), outbound + erasure via the Telegram Bot API.
Path: packages/integrations/communication-channel-telegram
URL: /llms/integration.communication-channel-telegram

(No README.md)

---

## @lssm-tech/integration.communication-os-agent

Description: Governed agent binding that drafts CommunicationOS replies via the ai-agent runtime, using the fail-closed command-inbox as the approval seam and a SovereigntyProfile-driven sovereign LLM (Mistral EU default, Claude alternative) — with no outbound send authority.
Path: packages/integrations/communication-os-agent
URL: /llms/integration.communication-os-agent

# @lssm-tech/integration.communication-os-agent

Governed agent binding for CommunicationOS (plan P1-S2 + P1-S3, AC1.2, AC1.4).

It wires the `@lssm-tech/lib.ai-agent` runtime so it drafts replies and
extracts decisions/risks/actions/summaries/intent for CommunicationOS — using
the fail-closed governed command-inbox as the approval seam and a
`SovereigntyProfile`-driven sovereign LLM (Mistral EU by default, Claude as a
config-only alternative) — **without ever giving the agent outbound send
authority**.

## Why this is an integration package

This package binds three reusable libs (`ai-agent`, `ai-providers`,
`communication-runtime`) plus the `communication-spec` contracts to a concrete
runtime target (the governed agent). It introduces no new domain contracts and
depends only downward (libs + spec), matching `package-architecture.md` for the
`integrations/` layer. It is the glue between the generic agent runtime and the
CommunicationOS governance surface; it does not belong in a lib (it composes
several libs) nor in a bundle/app (it is reusable across verticals).

## Safety invariants (non-negotiable)

1. **Allowlist, not denylist (pre-mortem #3, R3).**
   `createCommunicationAgentOperationRegistry()` builds the agent's
   `operationRegistry` from an explicit allowlist:
   `reply.draft`, `summary.generate`, `intent.classify`, `action.extract`,
   `decision.extract`, `risk.extract`. The outbound `communication.reply.send`
   operation is structurally absent — it is never registered, so the agent can
   never resolve it into a tool. A future send-like operation cannot leak in by
   omission.
2. **Inbox-backed approval seam (architect MUST-FIX 1).**
   `CommunicationInboxApprovalStore implements ApprovalStore`. Every approval
   request is projected through `createCommunicationCommandInboxItem`, producing
   a fail-closed inbox item (`canExecute: false`). The agent can only *create*
   pending records; it cannot transition them to approved and holds no send
   tool. The store is wrapped as `new ApprovalWorkflow(store)` and passed as
   `approvalWorkflow` — the inbox object is never passed directly.
3. **Send is a separate port the agent cannot call.** Outbound delivery is
   reachable only by an inbox approval transition driven by a human or an
   explicitly authorized policy — never by the agent.

## Sovereign model binding (P1-S3, AC1.4)

`resolveSovereignDefaultModel` / `createSovereignModelSelector` resolve the
`LanguageModel` from the tenant `SovereigntyProfile.llmProviderId`:
Mistral (sovereign EU) by default, Claude (`anthropic`) as the alternative,
switchable by config only. On-prem/self-host hosting routes through a
`provider-local-model` OpenAI-compatible `baseUrl`.

## Usage

```ts
import { createCommunicationOsAgent } from '@lssm-tech/integration.communication-os-agent';

const { factory, approvalStore, approvalWorkflow } = createCommunicationOsAgent({
  models: {
    sovereignty: { llmProviderId: 'mistral', hostingMode: 'saas' },
    providers: {
      mistral: { apiKey: process.env.MISTRAL_API_KEY },
      anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
    },
  },
  inbox: { log: { events: [], version: 0 } },
});
```


---

## @lssm-tech/integration.communication-os-persistence

Description: Server-only persistence binding that executes CommunicationOS governed-mutation descriptors against a database, with self-host (PgLite) and managed Postgres support.
Path: packages/integrations/communication-os-persistence
URL: /llms/integration.communication-os-persistence

# @lssm-tech/integration.communication-os-persistence

Server-only persistence binding for CommunicationOS. It executes the
`createCommunicationOsMutationDescriptor(...)` governed-mutation descriptors from
`@lssm-tech/lib.communication-spec` against a database via
`executeGovernedMutation`, enforcing the spec `deploymentMode` (managed / BYOK)
itself — the executor never validates it.

## Surfaces

- **Root (`.`)** — browser-safe. Pure types + helpers only:
  - `persistCommunicationOsMutation(descriptor, runtime, options?)`
  - `adaptCommunicationOsDescriptor`, `enforceDeploymentMode`
  - `buildSchemaContributionDdl`
  - `CommunicationOsDeploymentModeError`, `COMMUNICATION_OS_PERSISTENCE_MODES`
- **`./database`** — SERVER-ONLY (node-only). Reached only via this subpath, never
  re-exported from the root (pre-mortem #1: no node-only DB in browser bundles):
  - `createPgLitePersistenceProvider` (self-host, in-process Postgres/WASM)
  - `migrateCommunicationOsSchema` (applies `communicationOsSchemaContribution`)
  - `createManagedCommunicationOsPersistence` (wraps the managed
    `createDatabaseRuntime` from `@lssm-tech/integration.runtime-managed/database`)

## Self-host (PgLite)

```ts
import {
	createPgLitePersistenceProvider,
	migrateCommunicationOsSchema,
} from '@lssm-tech/integration.communication-os-persistence/database';
import { persistCommunicationOsMutation } from '@lssm-tech/integration.communication-os-persistence';

const provider = createPgLitePersistenceProvider({ dataDir: './data/comms' });
await migrateCommunicationOsSchema(provider);
await persistCommunicationOsMutation(descriptor, { provider });
```

## Managed Postgres

```ts
import { createManagedCommunicationOsPersistence } from '@lssm-tech/integration.communication-os-persistence/database';

const { persistenceRuntime } = createManagedCommunicationOsPersistence({
	connection: { connectionString: process.env.DATABASE_URL },
});
await persistCommunicationOsMutation(descriptor, persistenceRuntime('tenant:acme'));
```


---

## @lssm-tech/integration.communication-os-runtime

Description: Governed approve→send→event+audit orchestrator that closes the CommunicationOS hexagon: an approved approval (never the agent) is the only path that resolves a ChannelAdapter, dispatches the outbound send exactly once, emits ReplySentPayload, and persists the governed audit record.
Path: packages/integrations/communication-os-runtime
URL: /llms/integration.communication-os-runtime

# @lssm-tech/integration.communication-os-runtime

The **single composition point** that closes the CommunicationOS hexagon. One
`createCommunicationOsRuntime({...})` call wires all five CommunicationOS ports —
persistence, channels, model/agent, auth, observability — plus the
`ChannelAdapterRegistry` into one cohesive runtime handle (plan P2-S1, AC2.1).

This package also owns the governed **approve → send → event + audit**
orchestrator (`executeApprovedSend`, P1-S4): only a human-approved approval
(never the agent) can resolve a `ChannelAdapter` and dispatch an outbound send,
exactly once, with a replayable governed audit record.

## Why a factory + registry

- **Adopt in <1 file.** A vertical wires CommunicationOS through a single
  `createCommunicationOsRuntime` call (≤40 LOC) with **no edits** to any
  channel / persistence / agent package — it composes their published public
  APIs only.
- **The registry lives HERE.** Per the architecture (Option C), per-channel
  packages stay provider-specific; the `ChannelAdapterRegistry` composition
  point is owned by this factory, not by any single channel package.

## The five composed ports

| Port | Source package | Wired as |
| --- | --- | --- |
| Persistence | `@lssm-tech/integration.communication-os-persistence` | injected `persistence` + `reads` (node-only engine built behind the server-only `.../database` subpath by the caller) |
| Channels | `@lssm-tech/integration.communication-channel-core` | `createChannelAdapterRegistry(channels)` |
| Model / agent | `@lssm-tech/integration.communication-os-agent` | `createCommunicationOsAgent` (Mistral/Claude via SovereigntyProfile + narrowed registry — no send tool) |
| Auth | identity-rbac actor seam | `auth.resolveActorContext()` threaded per-call into the read `HandlerCtx` |
| Observability | `@lssm-tech/integration.communication-os-persistence` | optional `CommunicationOsObservability` binding |

## Runtime handle

`createCommunicationOsRuntime(config)` returns a `CommunicationOsRuntime`:

- `ingest({ channelType, rawPayload })` — normalize a raw inbound payload.
- `draftViaAgent({ sessionId, agentId, toolCallId, threadId, reason })` —
  produce a fail-closed pending approval; returns the approval id (the agent
  holds no send authority and cannot self-approve).
- `searchInbox(input)` / `getThread(input)` / `listMessages(input)` — actor-scoped reads.
- `approveAndSend({ approvalRequestId, context })` — fail-closed, idempotent
  approve → send → emit `ReplySentPayload` → persist governed audit.
- `eraseSubject({ channelType, ... })` — best-effort GDPR erasure (three-state outcome).
- `channelRegistry` / `agent` / `approvalWorkflow` — composed surfaces.

## Wiring example (≤40 LOC, AC2.1)

The canonical wiring lives in `src/runtime.fixture.ts` between the
`WIRING-START` / `WIRING-END` markers and is measured by `src/runtime.test.ts`:

```ts
return createCommunicationOsRuntime({
  persistence: deps.persistence,
  reads: deps.reads,
  channels: [
    createTelegramChannelAdapter({ botToken: deps.telegramBotToken, fetchImpl: deps.fetchImpl }),
    createEmailChannelAdapter({ outbound: deps.emailOutbound, fromAddress: { email: deps.fromEmail } }),
  ],
  model: {
    sovereignty: { llmProviderId: 'mistral' },
    providers: { mistral: { apiKey: deps.mistralApiKey } },
    createModel: deps.createModel,
  },
  inbox: { log: deps.eventLog },
  auth: { resolveActorContext: deps.resolveActor },
  observability: deps.observability,
  events: deps.events,
});
```

## Self-host / on-prem bring-up (P2-S3, AC2.2)

`@lssm-tech/integration.communication-os-runtime/install` is the **server-only**
one-command bring-up for a self-hosted CommunicationOS. `bringUpCommunicationOs`
runs DB migrations, reads env + sovereignty config, composes the runtime via the
factory, and (optionally) builds the governed MCP gateway.

### One command

```ts
// server-only — pulls the node-only persistence ./database subpath
import { bringUpCommunicationOs } from '@lssm-tech/integration.communication-os-runtime/install';
import { buildCommunicationOsMcpServer } from '@lssm-tech/app.communicationos-mcp/server';

const { runtime, mcpServer, close } = await bringUpCommunicationOs({
  buildMcpServer: buildCommunicationOsMcpServer, // governed allowlist owner
});
```

With no `DATABASE_URL` this stands up an in-process **PgLite** engine (zero
external services). Set `DATABASE_URL` to bind managed Postgres instead. The
governed `communication_os` schema + actor-aware RLS are applied idempotently on
every boot, so the call is safe to repeat.

### Environment contract

No secrets are baked into code — every value is read from the env. All keys are
optional; a bare environment resolves to a runnable EU self-host on PgLite.

| Env var                          | Default             | Purpose                                              |
| -------------------------------- | ------------------- | ---------------------------------------------------- |
| `DATABASE_URL`                   | _(absent → PgLite)_ | Managed Postgres connection string                   |
| `COMMOS_PGLITE_DATA_DIR`         | _(ephemeral)_       | PgLite on-disk data dir (self-host data survives)    |
| `COMMOS_APPLY_RLS`               | `true`              | Apply the actor-aware tenant RLS DDL                 |
| `COMMOS_RESIDENCY_REGION`        | `eu`                | Data residency region (`eu`, `eu_fr`, `self_managed`)|
| `COMMOS_HOSTING_MODE`            | `self_host`         | Hosting posture (`self_host`, `on_prem`, `saas`)     |
| `COMMOS_LLM_PROVIDER`            | `mistral`           | Sovereign / local LLM provider id                    |
| `COMMOS_LLM_BASE_URL`            | _(provider default)_| OpenAI-compatible base URL for a local LLM           |
| `COMMOS_DATA_RESIDENCY_ENFORCED` | `true`              | Assert residency enforcement                         |
| `COMMOS_RETENTION_DAYS`          | `365`               | Documented retention window for governed data        |
| `COMMOS_MCP_NAME` / `_VERSION`   | `communicationos-mcp` / `1.0.0` | MCP gateway identity                     |
| `MISTRAL_API_KEY`                | _(none)_            | BYOK key for the Mistral binding                     |

### SovereigntyProfile knobs

The defaults target a **sovereign EU self-host**: EU residency, a sovereign LLM
(`mistral`, or a `local` endpoint via `COMMOS_LLM_BASE_URL`), RLS on, and a
documented 365-day retention window — mirroring the `SovereigntyProfileModel`
contract (`communication-spec/contracts/sovereignty.ts`). Switch to a local
sovereign model with `COMMOS_LLM_PROVIDER=local` + `COMMOS_LLM_BASE_URL`; the
slice runs unchanged (no code edit — only config).

## Server-only boundary

The factory itself is **pure composition** — it imports NO node-only code. The
node-only persistence engine (`createDatabaseRuntime` / Postgres) is built by the
caller behind the server-only `@lssm-tech/integration.communication-os-persistence/database`
subpath and **injected** as `config.persistence`. The package root barrel
therefore stays browser-safe (pre-mortem #1). Never re-export the node-only
engine through this package.

## Exports

- `.` — `createCommunicationOsRuntime`, the runtime/config types, the
  orchestrator, and the governed audit-descriptor builder (browser-safe).
- `./runtime` / `./runtime-types` / `./types` / `./approval-send-orchestrator` /
  `./audit-descriptor` — focused subpaths.
- `./install` — **server-only** self-host bring-up (`bringUpCommunicationOs`,
  `resolveSelfHostConfig`, `createSelfHostReadPort`). Pulls the node-only
  persistence engine; never re-exported from the root barrel.

## Tests

```bash
bun test            # full suite (orchestrator + factory + self-host bring-up)
bun run typecheck   # tsgo --noEmit
```

`src/install/bring-up.smoke.test.ts` is the AC2.2 smoke test: it brings up
against PgLite (no external services), asserts the governed tables exist, the
runtime is constructed, and the governed MCP tool allowlist registers (the send
tool is never exposed). The real-Postgres path runs only when `DATABASE_URL` is
set and is skipped gracefully otherwise.


---

## @lssm-tech/integration.crdt-loro

Description: Isolated Loro-compatible CRDT adapter proof for data transmission collaboration envelopes.
Path: packages/integrations/crdt-loro
URL: /llms/integration.crdt-loro

# @lssm-tech/integration.crdt-loro

Isolated Loro adapter proof for ContractSpec collaboration envelopes.

## Boundary

This is the only V0 package that imports `loro-crdt`. Core data-transmission spec/runtime packages expose ContractSpec envelopes and never expose raw Loro types.

## Convergence proof

The package exports `runLoroConvergenceProof`, which applies independent left/right document updates, exchanges snapshots/updates through adapter-scoped envelopes, and verifies converged snapshots, versions, update counts, and byte counts without leaking Loro document objects to core contracts.

## V0 constraints

The proof covers in-memory update/snapshot/export/import/merge semantics. Production persistence, auth, managed WebSocket hosting, multi-region guarantees, and hosted collaboration backends are future work.


---

## @lssm-tech/integration.example-generator

Description: Example plugin: Markdown documentation generator for ContractSpec specs
Path: packages/integrations/example-generator
URL: /llms/integration.example-generator

# @lssm-tech/integration.example-generator

Website: https://contractspec.io

**Example plugin: Markdown documentation generator for ContractSpec specs.**

## What It Provides

- **Layer**: integration.
- **Consumers**: plugin authors, documentation pipelines.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/integration.example-generator`

or

`bun add @lssm-tech/integration.example-generator`

## Usage

Import the root entrypoint from `@lssm-tech/integration.example-generator`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/config.ts` is part of the package's public or composition surface.
- `src/generator.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/types.ts` is shared public type definitions.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./config` resolves through `./src/config.ts`.
- Export `./generator` resolves through `./src/generator.ts`.
- Export `./types` resolves through `./src/types.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run test:watch` — bun test --watch
- `bun run test:coverage` — bun test --coverage
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.

## Notes

- Do not add business logic; this is a reference plugin.
- Keep the export surface minimal -- new exports need a clear use-case.
- Peer-depends on `contracts-spec` and `schema`; do not bundle them.


---

## @lssm-tech/integration.fake-outbox-adapter

Description: Fake/sandbox outbox adapter for builder delivery loop testing.
Path: packages/integrations/fake-outbox-adapter
URL: /llms/integration.fake-outbox-adapter

# @lssm-tech/integration.fake-outbox-adapter

Website: https://contractspec.io

**Fake/sandbox outbox adapter for builder delivery loop testing.**

## What It Provides

- Simulated outbox adapter for testing builder delivery loop transitions without real provider SDKs or credentials.
- Supports `fake` and `sandbox` modes only; rejects production mode.
- Implements preflight checks, draft preparation, submission, receipt generation, and rollback.
- Idempotency key tracking and duplicate detection.
- Configurable latency simulation and failure rates for testing.

## When to Use

- Testing builder-delivery-loop transitions in development/staging.
- CI/CD integration tests that don't require real provider sends.
- Local development where real credentials aren't available.
- **Never use in production** - this adapter is explicitly designed to reject production mode.

## Usage

```typescript
import { createFakeOutboxAdapter } from '@lssm-tech/integration.fake-outbox-adapter';

const adapter = createFakeOutboxAdapter({
  mode: 'sandbox',
  simulateLatencyMs: 100,
  failureRate: 0.1, // 10% simulated failure rate
});

// Preflight check
const preflight = await adapter.preflight({
  loopId: 'loop-123',
  idempotencyKey: 'unique-key-123',
  billingOSRefs: ['billing-ref-1'],
  companyOSRefs: ['company-ref-1'],
  operatorApprovalRef: 'approval-123',
});

if (preflight.canProceed) {
  // Prepare draft
  const draft = await adapter.prepareDraft(input, preflight);
  
  // Submit
  const submission = await adapter.submit(draft, {
    draftId: draft.draftId,
    loopId: 'loop-123',
    idempotencyKey: 'unique-key-123',
    approvalStillValid: true,
    revisionAtSubmission: 1,
  });
  
  // Get receipt
  const receipt = await adapter.getReceipt({
    submissionId: submission.submissionId,
    idempotencyKey: 'unique-key-123',
  });
}
```

## Architecture

- Pure TypeScript implementation with no external provider dependencies.
- In-memory storage for drafts, submissions, and receipts.
- Fails closed on production mode detection.
- Supports idempotency for safe retry semantics.

## Safety

- **Always rejects production mode** - set `rejectProductionMode: true` (default).
- Requires idempotency keys for all operations.
- Requires operator approval references.
- Duplicate idempotency keys return existing receipts (idempotent).

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint:check` — biome check .


---

## @lssm-tech/integration.google-play-developer

Description: Read-first Google Play Android Publisher API integration for ReviewReady app submission readiness, with deterministic mocks and secret-ref-only credentials.
Path: packages/integrations/google-play-developer
URL: /llms/integration.google-play-developer

# @lssm-tech/integration.google-play-developer

Read-first Google Play Android Publisher API integration for ReviewReady app
submission readiness.

## Safety posture

- **Secret-ref only.** Auth config carries `clientEmail` and
  `serviceAccountSecretRefId` — never raw service-account JSON or private keys.
  Secrets are resolved at call time by a host-provided
  `GooglePlayDeveloperSecretResolver`.
- **Read-first.** No write/commit/track-promotion operations are exposed.
- **Honest capabilities.** Fields the public API cannot supply (Data Safety
  console answers) return a typed `CapabilityResult` (`manual-required` /
  `unsupported` / `degraded`), never fake data. Results map to
  `appSubmissionProviderCapabilities` in `@lssm-tech/lib.contracts-spec`.
- **Mock-by-default.** `createMockGooglePlayDeveloperClient` returns
  deterministic snapshots for tests/CI. `createGooglePlayDeveloperClient` is
  live-capable but live calls are opt-in; enabling them without resolved
  credentials throws.
- **Redacted logging.** Log entries hold only provider, operation, status,
  correlationId, capabilityId.

## Sources

- Android Publisher Edits: <https://developers.google.com/android-publisher/edits>
- Google Play Data Safety: <https://support.google.com/googleplay/android-developer/answer/10787469>


---

## @lssm-tech/integration.harness-runtime

Description: Runtime adapters for the ContractSpec harness system.
Path: packages/integrations/harness-runtime
URL: /llms/integration.harness-runtime

# @lssm-tech/integration.harness-runtime

Website: https://contractspec.io

**Runtime adapters that bridge the ContractSpec harness core into browser, sandbox, artifact, and MCP-backed execution targets.**

## What It Provides

- Provides concrete adapters for deterministic Playwright browser automation, optional `agent-browser` visual computer-use runs, sandboxed execution, and artifact storage.
- Exposes MCP helpers and default target resolution on top of the mode-agnostic harness core.
- Keeps higher-cost runtime integrations optional so consumers can opt into heavier execution targets deliberately.
- `src/adapters/` contains runtime, provider, or environment-specific adapters.
- `src/mcp/` contains MCP handlers, tools, prompts, and resources.

## Installation

`npm install @lssm-tech/integration.harness-runtime`

or

`bun add @lssm-tech/integration.harness-runtime`

## Usage

Import the root entrypoint from `@lssm-tech/integration.harness-runtime`, or choose a documented subpath when you only need one part of the package surface.

## Architecture

- `src/adapters/` contains Playwright, agent-browser, sandbox, and visual harness adapters.
- `src/artifacts/` contains filesystem and in-memory artifact-store implementations.
- `src/mcp/` exposes harness execution surfaces to MCP-aware runtimes.
- `src/targets/` contains target resolution helpers and target-selection logic.
- `src/types.ts` exposes shared runtime-facing harness types.
- `src/index.ts` is the root public barrel and package entrypoint.

## Public Entry Points

- Exports runtime adapters, artifact stores, MCP exposure helpers, target resolution, and shared types.
- Export `.` resolves through `./src/index.ts`.
- Export `./adapters/agentBrowserHarnessAdapter` resolves through `./src/adapters/agentBrowserHarnessAdapter.ts`.
- Export `./adapters/playwrightBrowserHarnessAdapter` resolves through `./src/adapters/playwrightBrowserHarnessAdapter.ts`.
- Export `./adapters/sandboxedCodeExecutionAdapter` resolves through `./src/adapters/sandboxedCodeExecutionAdapter.ts`.
- Export `./adapters/visualHarnessAdapter` resolves through `./src/adapters/visualHarnessAdapter.ts`.
- Export `./artifacts/filesystemArtifactStore` resolves through `./src/artifacts/filesystemArtifactStore.ts`.
- Export `./artifacts/inMemoryArtifactStore` resolves through `./src/artifacts/inMemoryArtifactStore.ts`.
- Export `./mcp/exposure` resolves through `./src/mcp/exposure.ts`.
- Export `./targets/defaultTargetResolver` resolves through `./src/targets/defaultTargetResolver.ts`.
- Export `./types` resolves through `./src/types.ts`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun run lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Add a first-class harness system for controlled inspection, testing, evaluation, and proof generation.
- Add OSS full-app verification adapters for Playwright and `agent-browser`, including auth profile refs, visual diff evidence, and replay-friendly browser artifacts.

## Notes

- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.harness`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Authenticated browser runs should use named storage-state, browser-profile, session-name, or headers-env refs. Do not embed raw credentials, cookies, or bearer tokens in scenario specs or replay bundles.


---

## @lssm-tech/integration.opa-calendar-bridge

Description: Bridge adapting the real CalendarProvider (e.g. GoogleCalendarProvider from integration.provider-calendar) to the organization-planning module's CalendarExecutionAdapterPort. Port → provider; no new Google SDK code.
Path: packages/integrations/opa-calendar-bridge
URL: /llms/integration.opa-calendar-bridge

# @lssm-tech/integration.opa-calendar-bridge

Bridge that binds the **organization-planning** module's
`CalendarExecutionAdapterPort` (`kind: 'calendar_execution'`) to a real
`CalendarProvider` — without reimplementing any provider SDK. This is the
port→provider seam: the module declares the typed port; this package adapts it to
a concrete provider (e.g. the `GoogleCalendarProvider` owned by
`@lssm-tech/integration.provider-calendar`).

## Why it exists

OPA proposes bookings and agendas as fail-closed drafts. To actually *execute* a
confirmed booking (write a calendar event), the runtime needs a bound
`calendar_execution` adapter. This bridge provides one over an existing provider,
keeping Google SDK code out of the runtime and the module.

## Usage

```ts
import { createOpaCalendarExecutionBridge } from '@lssm-tech/integration.opa-calendar-bridge';
import { GoogleCalendarProvider } from '@lssm-tech/integration.provider-calendar/impls/google-calendar';

// Any CalendarProvider works (Google, a fake, a future provider).
const calendar = createOpaCalendarExecutionBridge(
  new GoogleCalendarProvider({ auth })
);

// Or the convenience factory (./google):
import { createGoogleOpaCalendarExecutionBridge } from '@lssm-tech/integration.opa-calendar-bridge/google';
const calendar = createGoogleOpaCalendarExecutionBridge({ auth });

// Bind into the OPA runtime so booking.confirm can write on the authorized path:
buildOpaOps({ rbac, calendar });
```

## Fail-closed posture

The bridge only forwards a method call when invoked. The OPA runtime invokes
`createEvent` **exclusively** on the authorized + approval-satisfied confirm path
(`isOpaExecutionAllowed`); every other path performs no external write.

## Exports

| Subpath     | Export                                                    |
| ----------- | --------------------------------------------------------- |
| `.`         | `createOpaCalendarExecutionBridge`, `OpaCalendarExecutionAdapter`, `createGoogleOpaCalendarExecutionBridge` |
| `./bridge`  | provider-agnostic bridge (no Google SDK)                  |
| `./google`  | Google convenience factory                                |


---

## @lssm-tech/integration.opa-notification-bridge

Description: Bridge implementing the organization-planning CommunicationSendAdapterPort + JobsScheduleAdapterPort over injected email (EmailOutboundProvider), SMS (SmsProvider), and durable job-queue (JobQueue) transports. Feature-flag gated, fail-closed, no secrets in code.
Path: packages/integrations/opa-notification-bridge
URL: /llms/integration.opa-notification-bridge

# @lssm-tech/integration.opa-notification-bridge

Binds the **organization-planning** communication + jobs adapter ports to
injected notification transports — without reimplementing any provider SDK:

- `CommunicationSendAdapterPort` (`sendConfirmation` / `sendReminder` /
  `sendFollowUp`) → an injected `EmailOutboundProvider` (gmail/postmark/resend)
  for email, or an injected `SmsProvider` (Twilio, …) for SMS.
- `JobsScheduleAdapterPort` (`scheduleReminder`) → an injected durable `JobQueue`
  (Scaleway SQS / GCP Cloud Tasks / Pub-Sub) — reminders are enqueued so delivery
  survives restarts; confirmations/follow-ups send immediately.

## Posture: feature-flag gated + fail-closed

- Email and SMS sends are gated behind `OPA_NOTIFY_EMAIL` / `OPA_NOTIFY_SMS`
  (`OPA_NOTIFY_FLAGS`), both defaulting **safe (off)**.
- An unconfigured channel — flag off, transport absent, missing recipient, or no
  resolved target — yields a **no-op receipt** (`success: true`,
  `outputRefs: ['opa-notify-noop:<reason>']`). It **never throws**.
- **No secrets in code.** Every transport is injected via the constructor.

## Usage

```ts
import { createOpaNotificationBridge, OPA_NOTIFY_FLAGS } from '@lssm-tech/integration.opa-notification-bridge';

const { communication, jobs } = createOpaNotificationBridge({
  email,            // e.g. GmailOutboundProvider / PostmarkEmailProvider
  sms,              // e.g. TwilioSmsProvider
  jobs: jobQueue,   // e.g. ScalewaySqsQueue / GcpCloudTasksQueue / MemoryJobQueue
  defaultFromEmail: 'noreply@yourdomain.example',
  flags: { [OPA_NOTIFY_FLAGS.EMAIL]: true, [OPA_NOTIFY_FLAGS.SMS]: false },
  resolveNotification: (handoff, kind) => ({
    channel: 'email',
    email: lookupRecipientEmail(handoff),
    body: renderBody(handoff, kind),
  }),
});

// worker-1 threads `communication` + `jobs` into buildOpaOps.
```

The host owns `resolveNotification` (recipient/PII derivation) — the bridge never
reads recipient data from the handoff itself.


---

## @lssm-tech/integration.opa-personalization-bridge

Description: Bridge mapping the canonical @lssm-tech/lib.personalization surfaces (preference-dimensions, preference-evolution, behavior-signals, adaptive-surface) onto OPA optimizer objective weights, the behavior→preference learning loop, and role-aware booking/UI adaptation. No ad-hoc preference state.
Path: packages/integrations/opa-personalization-bridge
URL: /llms/integration.opa-personalization-bridge

# @lssm-tech/integration.opa-personalization-bridge

Bridge between the canonical `@lssm-tech/lib.personalization` surfaces and
Organization Planning & Agenda (OPA). It exists so OPA never grows ad-hoc
preference state — all behaviour/preference logic flows through the
canonical personalization lib.

## Surfaces

- **`./objective`** — `mapPreferencesToObjective(dimensions)`: pure,
  deterministic mapping of the 7-dimension `PreferenceDimensions` model onto
  the OPA optimizer's `OptimizerObjectiveWeights` (focus defense, priority,
  deadline urgency, fragmentation, context switch). Deep-work preferences
  raise `focusDefenseWeight`; deadline-driven preferences raise
  `deadlineUrgencyWeight`.
- **`./learning`** — the behaviour → preference learning loop. OPA
  scheduling interactions (focus respected/broken, slot rescheduled,
  evidence expanded, guidance dismissed…) become canonical
  `PreferenceEvolutionObservation`s and canonical `BehaviorSignalModel`s,
  fed through `suggestPreferenceEvolution` so the objective weights adapt
  over time. Behaviour signals carry only interaction kinds, dimension ids,
  and opaque surface ids — **no PII**.
- **`./surface`** — `resolveOpaAdaptiveSurface(...)`: a typed accessor the
  host/UI consumes to adapt booking/planning per user preference AND role.
  RoleMorph/ACL boundaries are authoritative and fail closed (a read-only
  auditor never gets advanced controls).
- **`./opa-policy`** — `deriveObjectiveFromOpaPolicy(policy)`: maps the OPA
  spec's local policy enums onto canonical preferences, so the spec's
  `applyOpaPersonalizationPolicy` can delegate to the canonical mapping
  instead of maintaining a parallel scoring system.

## Privacy

Behaviour data is personal data and is minimised. Signals never include
actor identity, names, emails, titles, or free text — only stable ids and
dimension keys. `createBehaviorSignalModel` additionally fails closed on
unsafe behavioural labelling.

## Layering

This is an integration: it depends only downward on `lib.personalization`
and `lib.organization-planning-spec`. It owns no scheduling, persistence, or
optimizer logic (those live in spec/runtime).


---

## @lssm-tech/integration.provider-analytics

Description: Analytics provider implementations for ContractSpec.
Path: packages/integrations/provider-analytics
URL: /llms/integration.provider-analytics

# @lssm-tech/integration.provider-analytics

Website: https://contractspec.io

Analytics provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the analytics implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-calendar

Description: Calendar provider implementations for ContractSpec.
Path: packages/integrations/provider-calendar
URL: /llms/integration.provider-calendar

# @lssm-tech/integration.provider-calendar

Website: https://contractspec.io

Calendar provider implementations for ContractSpec. Each implementation conforms
to the shared `CalendarProvider` interface (`listEvents` / `createEvent` /
`updateEvent` / `deleteEvent`) from `@lssm-tech/lib.contracts-integrations`, so
they are interchangeable behind the same port (e.g. the OPA
`calendar_execution` adapter).

## Implementations

| Subpath | Export | Notes |
| --- | --- | --- |
| `./impls/google-calendar` | `GoogleCalendarProvider` | Google Calendar via `googleapis`. |
| `./impls/microsoft-graph` | `MicrosoftGraphCalendarProvider` | Microsoft 365 / Outlook via Microsoft Graph. |
| `./impls/caldav` | `CalDavCalendarProvider` | Generic CalDAV servers (Fastmail, Nextcloud, iCloud, …). |
| `./impls/ics-feed` | `IcsFeedCalendarProvider`, `CalendarOperationNotSupportedError` | Read-only ICS subscription feeds; write methods fail closed. |
| `./impls/ics-codec` | ICS encode/decode helpers | Shared iCalendar serialization used by the feed/CalDAV adapters. |

## Usage

Import the root entrypoint for the domain surface, or import a concrete
implementation from the `./impls/*` subpaths:

```ts
import { MicrosoftGraphCalendarProvider } from '@lssm-tech/integration.provider-calendar/impls/microsoft-graph';

const calendar = new MicrosoftGraphCalendarProvider({ auth });
```

## Boundaries

- Provider SDK code lives **here**, not in OPA runtime/module or the OPA bridges.
- Read-only sources (`IcsFeedCalendarProvider`) fail closed on write operations
  rather than silently no-op'ing.

## Compatibility

This package owns the calendar implementation slice split out of
`@lssm-tech/integration.providers-impls`. The legacy package continues to
re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-claude-code

Description: Claude Code provider compatibility wrapper for Builder.
Path: packages/integrations/provider-claude-code
URL: /llms/integration.provider-claude-code

(No README.md)

---

## @lssm-tech/integration.provider-codex

Description: Codex provider compatibility wrapper for Builder.
Path: packages/integrations/provider-codex
URL: /llms/integration.provider-codex

(No README.md)

---

## @lssm-tech/integration.provider-copilot

Description: Copilot provider compatibility wrapper for Builder.
Path: packages/integrations/provider-copilot
URL: /llms/integration.provider-copilot

(No README.md)

---

## @lssm-tech/integration.provider-database

Description: Database provider implementations for ContractSpec.
Path: packages/integrations/provider-database
URL: /llms/integration.provider-database

# @lssm-tech/integration.provider-database

Website: https://contractspec.io

Database provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
Use `./governed-read` when a contracts-spec `DataViewQueryGenerator` emits a `database.query.readonly` descriptor and you need to execute that governed read through a `DatabaseProvider`. The helper builds parameterized SQL from field mappings and keeps SQL construction inside this adapter package.
Governed reads support offset descriptors and cursor descriptors from
`DataViewDatabaseBinding.pagination`. Cursor descriptors add a parameterized
`cursorField > cursor` predicate only when the cursor field is present in the
contract-owned select mapping; unknown cursor fields fail before provider
execution, and `maxPageSize` is enforced before the query reaches the provider.
`executeQuery` exposes the governed read as a `Transport`-shaped resolver for the data-fetching engine: it executes a canonical `QueryEnvelope` and returns a `ContractResult<QueryResultEnvelope>` carrying a real `versionToken` (sourced from the persistence column on the entity-workspace proof entities via the drizzle/supabase impls) for the engine's etag / optimistic-concurrency path.

Use `./governed-mutation` for first-class database writes after the owning domain command has planned a portable `database.mutation.execute@2.0.0` envelope. The helper validates actor, tenant, domain-command authority, policy decision, idempotency key, transaction boundary, expected write set, audit refs, replay ref, and correlation ref before running the provider transaction. Drizzle/PostgreSQL rendering remains in this integration package, not in contracts-spec core.

Managed and BYOK Postgres/Supabase deployments are the production posture. Local/PgLite remains a provider-binding compatibility mode for deterministic tests and demos, not a separate ownership mode.

## Public subpaths

- `.` re-exports the provider surface plus governed read/mutation helpers.
- `./database` re-exports the shared `DatabaseProvider` contracts.
- `./governed-read` executes portable DataView read descriptors through a provider.
- `./governed-mutation` executes governed mutation descriptors with transaction, idempotency, and audit hooks.
- `./impls` and `./impls/supabase-psql` expose concrete PostgreSQL/Supabase implementations.

## Compatibility

This package owns the database implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-einvoicing

Description: French Factur-X (EN16931 CII) generation, EN16931/CIUS-FR conformance (Mustangproject), and PDP submission adapters for ContractSpec BillingOS.
Path: packages/integrations/provider-einvoicing
URL: /llms/integration.provider-einvoicing

# @lssm-tech/integration.provider-einvoicing

French Factur-X generation and PDP submission for ContractSpec BillingOS.

- `./cii` — pure EN16931 Cross-Industry Invoice (CII) XML builder.
- `./facturx` — `FacturXGeneratorPort` + a Mustangproject-backed PDF/A-3 hybrid generator.
- `./conformance` — EN16931 / Factur-X CIUS-FR validation via Mustangproject (JVM).
- `./pdp` — `PdpSubmissionPort`, a deterministic mock, a fail-closed production stub, and an idempotent submission guard.

## Conformance toolchain

Validator: **Mustangproject CLI 2.17.0** (vendored at `vendor/Mustang-CLI-2.17.0.jar`,
from Maven Central `org.mustangproject:Mustang-CLI:2.17.0`). It runs XSD schema
validation and EN16931 / Factur-X Schematron business rules over the JVM
(OpenJDK 17). Set `EINVOICING_JAVA_BIN` to override the `java` binary.

Conformance and embedding are never faked: if the jar or JVM is absent, the
generator returns the machine CII XML with `embedded:false`, and the validator
returns `available:false` with a skip reason.

Depends on `@lssm-tech/lib.billing-france` (TVA rounding, flow classification)
and `@lssm-tech/lib.billing-spec` (invoice types). This package owns Factur-X
generation + PDP submission; the lib stays pure.


---

## @lssm-tech/integration.provider-email

Description: Email provider implementations for ContractSpec.
Path: packages/integrations/provider-email
URL: /llms/integration.provider-email

# @lssm-tech/integration.provider-email

Website: https://contractspec.io

Email provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Included Providers

- `GmailInboundProvider` for thread and message sync
- `GmailOutboundProvider` for Gmail-based outbound delivery
- `PostmarkEmailProvider` for transactional email delivery

## Compatibility

This package owns the email implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-embedding

Description: Embedding provider implementations for ContractSpec.
Path: packages/integrations/provider-embedding
URL: /llms/integration.provider-embedding

# @lssm-tech/integration.provider-embedding

Website: https://contractspec.io

Embedding provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the embedding implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-gemini

Description: Gemini provider compatibility wrapper for Builder.
Path: packages/integrations/provider-gemini
URL: /llms/integration.provider-gemini

(No README.md)

---

## @lssm-tech/integration.provider-github

Description: GitHub provider implementation for ContractSpec with repository, issue, and pull request management.
Path: packages/integrations/provider-github
URL: /llms/integration.provider-github

(No README.md)

---

## @lssm-tech/integration.provider-health

Description: Health data provider implementations for ContractSpec.
Path: packages/integrations/provider-health
URL: /llms/integration.provider-health

# @lssm-tech/integration.provider-health

Website: https://contractspec.io

Health data provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the health implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-llm

Description: LLM provider implementations for ContractSpec.
Path: packages/integrations/provider-llm
URL: /llms/integration.provider-llm

# @lssm-tech/integration.provider-llm

Website: https://contractspec.io

LLM provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the llm implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-local-model

Description: Local model provider compatibility wrapper for Builder.
Path: packages/integrations/provider-local-model
URL: /llms/integration.provider-local-model

(No README.md)

---

## @lssm-tech/integration.provider-meeting-recorder

Description: Meeting recorder provider implementations for ContractSpec.
Path: packages/integrations/provider-meeting-recorder
URL: /llms/integration.provider-meeting-recorder

# @lssm-tech/integration.provider-meeting-recorder

Website: https://contractspec.io

Meeting recorder provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the meeting-recorder implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-messaging

Description: Messaging provider implementations for ContractSpec.
Path: packages/integrations/provider-messaging
URL: /llms/integration.provider-messaging

# @lssm-tech/integration.provider-messaging

Website: https://contractspec.io

Messaging provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Included Providers

- `SlackMessagingProvider`
- `GithubMessagingProvider`
- `MatrixMessagingProvider`
- `TelegramMessagingProvider`
- `MetaWhatsappMessagingProvider`
- `TwilioWhatsappMessagingProvider`

## Compatibility

This package owns the messaging implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.

## Slack

`SlackMessagingProvider` implements Slack message send/update/delete plus conversations, users, reactions, files, and search operations over the Slack Web API. It requires a bot token for standard Web API calls and can optionally use a user token for search endpoints that require user-scoped Slack permissions.

Import it from:

```ts
import { SlackMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-slack";
```

```ts
const slack = new SlackMessagingProvider({
	botToken: process.env.SLACK_BOT_TOKEN!,
	userToken: process.env.SLACK_USER_TOKEN,
	defaultChannelId: "C0123456789",
});

await slack.sendMessage({ text: "ContractSpec check passed" });
const search = await slack.searchMessages("ContractSpec", 10);
```

For inbound Slack Event API requests, verify signatures and normalize events through `@lssm-tech/integration.runtime/channel/slack` or the higher-level Slack webhook receiver in `@lssm-tech/integration.runtime/webhooks/slack`. Keep `botToken`, `userToken`, app tokens, and signing secrets in a `SecretProvider` or environment secret store; never commit real Slack credentials, raw webhook URLs, or signed payload logs.

## GitHub

`GithubMessagingProvider` implements the messaging bridge for GitHub issue and pull request comments. Use `recipientId` in the `owner/repo#number` form, or configure `defaultOwner` and `defaultRepo` and pass the issue/PR number as `threadId`.

Import it from:

```ts
import { GithubMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-github";
```

```ts
const github = new GithubMessagingProvider({
	token: process.env.GITHUB_TOKEN!,
	defaultOwner: "lssm-tech",
	defaultRepo: "contractspec",
});

await github.sendMessage({
	threadId: "42",
	text: "ContractSpec automation result",
});
```

For repository, issue, pull request, merge, and code-search operations, use `@lssm-tech/integration.provider-github`. For inbound GitHub webhook requests, verify signatures and normalize channel events through `@lssm-tech/integration.runtime/channel/github` or the webhook receiver in `@lssm-tech/integration.runtime/webhooks/github`. Keep personal access tokens, GitHub App installation tokens, private keys, and webhook secrets in managed secrets; test fixtures should use redacted placeholders and mocked `fetch` responses only.

## Matrix

`MatrixMessagingProvider` is a minimal `matrix-js-sdk` adapter for Matrix room sends and mocked room-event normalization. It expects an existing homeserver URL and access token; it does not provision homeservers, automate hosted signup, install bridges, guarantee production bridge operation, or replace direct Slack/Telegram/WhatsApp providers.

Import it from:

```ts
import { MatrixMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-matrix";
```


---

## @lssm-tech/integration.provider-openbanking

Description: Open banking provider implementations for ContractSpec.
Path: packages/integrations/provider-openbanking
URL: /llms/integration.provider-openbanking

# @lssm-tech/integration.provider-openbanking

Website: https://contractspec.io

Open banking provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the openbanking implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-opencode-go

Description: OpenCode Go provider compatibility wrapper for Builder.
Path: packages/integrations/provider-opencode-go
URL: /llms/integration.provider-opencode-go

(No README.md)

---

## @lssm-tech/integration.provider-payments

Description: Payments provider implementations for ContractSpec.
Path: packages/integrations/provider-payments
URL: /llms/integration.provider-payments

# @lssm-tech/integration.provider-payments

Website: https://contractspec.io

Payments provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the payments implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-pioneer-ai

Description: Pioneer AI provider adapter for ContractSpec AI improvement workflows.
Path: packages/integrations/provider-pioneer-ai
URL: /llms/integration.provider-pioneer-ai

# @lssm-tech/integration.provider-pioneer-ai

Targeted Pioneer AI adapter for the vendor-neutral AI improvement contracts.

The adapter is feature-gated and mock-first. It never exports Pioneer-specific domain types into core packages; callers interact through ContractSpec AI-improvement envelopes, provider capability maps, and provider receipts.

## Safety defaults

- `AI_IMPROVEMENT_VENDOR_EXPORT=off` denies raw dataset export.
- `AI_IMPROVEMENT_AUTO_APPLY=off` prevents automatic promotion.
- `AI_IMPROVEMENT_LEARNING=off` prevents memory writes.
- `PIONEER_AI_ADAPTER=off` disables this adapter at the Pioneer integration boundary; the neutral core uses `adapterDisabled`.


---

## @lssm-tech/integration.provider-project-management

Description: Project management provider implementations for ContractSpec.
Path: packages/integrations/provider-project-management
URL: /llms/integration.provider-project-management

# @lssm-tech/integration.provider-project-management

Website: https://contractspec.io

Project management provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the project-management implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-sms

Description: SMS provider implementations for ContractSpec.
Path: packages/integrations/provider-sms
URL: /llms/integration.provider-sms

# @lssm-tech/integration.provider-sms

Website: https://contractspec.io

SMS provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the sms implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-storage

Description: Object storage provider implementations for ContractSpec.
Path: packages/integrations/provider-storage
URL: /llms/integration.provider-storage

# @lssm-tech/integration.provider-storage

Website: https://contractspec.io

Object storage provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the storage implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-stt

Description: Speech-to-text provider compatibility wrapper for Builder.
Path: packages/integrations/provider-stt
URL: /llms/integration.provider-stt

(No README.md)

---

## @lssm-tech/integration.provider-vector-store

Description: Vector store provider implementations for ContractSpec.
Path: packages/integrations/provider-vector-store
URL: /llms/integration.provider-vector-store

# @lssm-tech/integration.provider-vector-store

Website: https://contractspec.io

Vector store provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the vector-store implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


---

## @lssm-tech/integration.provider-voice

Description: Voice, speech, and conversational provider implementations for ContractSpec.
Path: packages/integrations/provider-voice
URL: /llms/integration.provider-voice

# @lssm-tech/integration.provider-voice

Website: https://contractspec.io

Voice, speech, and conversational provider implementations for ContractSpec.

## Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.

## Compatibility

This package owns the voice implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.


## Implementations

- `GradiumVoiceProvider`: Gradium SDK-backed TTS implementation for the configured workspace, with contract metadata covering public REST/WebSocket TTS and STT surfaces.
- `FalVoiceProvider`: official `@fal-ai/client`-backed Chatterbox TTS implementation with contract metadata covering broader fal media SDK/API/MCP surfaces.
- `SlngVoiceProvider`: API-key `fetch` implementation for SLNG TTS and STT routes. Route templates are configurable so tenants can target the SLNG provider/model path available to their account.

Secrets are passed explicitly through provider options or secret providers; implementations do not read environment variables directly or serialize secret values.


---

## @lssm-tech/integration.providers-impls

Description: Integration provider implementations for email, payments, storage, and more
Path: packages/integrations/providers-impls
URL: /llms/integration.providers-impls

# @lssm-tech/integration.providers-impls

Website: https://contractspec.io

**Compatibility facade and all-provider factory for ContractSpec provider implementations.**

## What It Provides

- **Layer**: integration.
- **Consumers**: bundles, apps, and modules that still need the broad compatibility surface or the all-provider factory.
- Targeted provider implementation packages now own the concrete domains, such as `@lssm-tech/integration.provider-email`, `@lssm-tech/integration.provider-payments`, `@lssm-tech/integration.provider-voice`, and `@lssm-tech/integration.provider-project-management`.
- Related ContractSpec packages include `@lssm-tech/integration.runtime`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, and `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/integration.providers-impls`

or

`bun add @lssm-tech/integration.providers-impls`

## Usage

Prefer a targeted package when you only need one provider domain:

```ts
import { GmailInboundProvider } from '@lssm-tech/integration.provider-email/impls/gmail-inbound';
import { StripePaymentsProvider } from '@lssm-tech/integration.provider-payments/impls/stripe-payments';
```

Existing imports from `@lssm-tech/integration.providers-impls` and its `./impls/*` subpaths remain supported as compatibility re-exports. Keep using this package for `IntegrationProviderFactory` or when you intentionally need the broad composition surface.

### Communication Coverage

`IntegrationProviderFactory` now covers the main OSS communication paths directly:

- `createEmailInboundProvider(...)` for Gmail thread/message sync
- `createEmailOutboundProvider(...)` for Gmail and Postmark delivery
- `createSmsProvider(...)` for Twilio SMS
- `createMessagingProvider(...)` for Telegram, WhatsApp Meta, and WhatsApp Twilio

## Architecture

- `src/analytics.ts`, `src/calendar.ts`, `src/database.ts`, `src/email.ts`, `src/embedding.ts`, and the other domain files are compatibility re-exports to targeted packages.
- `src/impls/provider-factory.ts` owns the all-provider factory and imports targeted packages.
- `src/impls/composio-*` owns the cross-domain Composio fallback/proxy surface.
- `src/impls/*` provider implementation files are compatibility re-exports to targeted packages.
- `src/index.ts` is the root public barrel and package entrypoint.

## Targeted Packages

- `@lssm-tech/integration.provider-analytics`
- `@lssm-tech/integration.provider-calendar`
- `@lssm-tech/integration.provider-database`
- `@lssm-tech/integration.provider-email`
- `@lssm-tech/integration.provider-embedding`
- `@lssm-tech/integration.provider-health`
- `@lssm-tech/integration.provider-llm`
- `@lssm-tech/integration.provider-meeting-recorder`
- `@lssm-tech/integration.provider-messaging`
- `@lssm-tech/integration.provider-openbanking`
- `@lssm-tech/integration.provider-payments`
- `@lssm-tech/integration.provider-project-management`
- `@lssm-tech/integration.provider-sms`
- `@lssm-tech/integration.provider-storage`
- `@lssm-tech/integration.provider-vector-store`
- `@lssm-tech/integration.provider-voice`

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./analytics` resolves through `./src/analytics.ts`.
- Export `./calendar` resolves through `./src/calendar.ts`.
- Export `./database` resolves through `./src/database.ts`.
- Export `./email` resolves through `./src/email.ts`.
- Export `./embedding` resolves through `./src/embedding.ts`.
- Export `./health` resolves through `./src/health.ts`.
- Export `./impls` resolves through `./src/impls/index.ts`.
- Export `./impls/pioneer-ai` resolves through `./src/impls/pioneer-ai.ts`.
- Export `./impls/slng-voice` resolves through `./src/impls/slng-voice.ts`.
- Export `./impls/async-event-queue` resolves through `./src/impls/async-event-queue.ts`.
- Export `./impls/composio-fallback-resolver` resolves through `./src/impls/composio-fallback-resolver.ts`.
- The package publishes 81 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Missing dependencies (thanks to knip).
- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Resolve lint, build, and test failures across voice, workspace, library, and composio.
- Composio.
- Normalize formatting across contracts-integrations, composio, and observability.

## Notes

- Every implementation must satisfy a contract from `contracts-integrations`.
- Never import from apps or bundles.
- Secrets must flow through `@lssm-tech/integration.runtime`; never hard-code credentials.
- Composio fallback is opt-in; existing code paths are unchanged when config is absent.
- Composio proxy adapters must not leak Composio-specific types into domain interfaces.

- `@lssm-tech/integration.provider-pioneer-ai` for mock-first Pioneer AI self-improvement job/evaluation integration.


---

## @lssm-tech/integration.runtime-hybrid

Description: Hybrid runtime compatibility wrapper for Builder.
Path: packages/integrations/runtime-hybrid
URL: /llms/integration.runtime-hybrid

(No README.md)

---

## @lssm-tech/integration.runtime-local

Description: Local runtime compatibility wrapper for Builder.
Path: packages/integrations/runtime-local
URL: /llms/integration.runtime-local

(No README.md)

---

## @lssm-tech/integration.runtime-managed

Description: Managed runtime compatibility wrapper for Builder.
Path: packages/integrations/runtime-managed
URL: /llms/integration.runtime-managed

# @lssm-tech/integration.runtime-managed

Managed runtime compatibility wrapper for Builder, plus the managed **database
runtime** preset (`./database`).

## `createDatabaseRuntime()`

`createDatabaseRuntime(options)` composes the governed Postgres provider, the O2
observability binding, tenant-scoped RLS access, and the pre-bound governed
read / relational-read / mutation resolvers into one preset. It returns:

| member            | description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `provider`        | Tenant-scoped `DatabaseProvider` (ambient tenant; fail-closed when none) |
| `governedQuery`   | Pre-bound resolver factory (data-view **and** relational descriptors)    |
| `governedMutation`| Pre-bound `executeGovernedMutation`                                       |
| `withTenant(id)`  | Returns a slice bound to a fixed tenant id                               |
| `close()`         | Closes the underlying pool once                                          |

```ts
import { createDatabaseRuntime } from '@lssm-tech/integration.runtime-managed/database';

const db = createDatabaseRuntime({
  connection: { connectionString: process.env.DATABASE_URL },
  pooler: 'transaction-pooler',
  instrumentation, // lib.observability Instrumentation facade (optional)
});

const tenant = db.withTenant('tenant-42');
const list = tenant.governedQuery({ descriptor }); // (envelope, ctx) => ContractResult
await tenant.governedMutation(mutationDescriptor);
```

### Tenant scoping (RLS, Critic N6)

The raw provider is never exposed. Every read/write runs inside a transaction
that first issues `set_config('app.tenant_id', <id>, true)`, so Postgres RLS
policies see the active tenant. The top-level `provider` resolves the tenant
from `resolveTenantId` (or the auth seam) per call and **fails closed** when no
tenant context is present; use `withTenant(id)` in server contexts that already
know the tenant. `TransportContext.principal` is carried onto resolver ctx and
never stripped (AC14); `policyDecisionRef` / `policy.auth` enforcement stays in
the handlers.

### Pooler modes (AC3)

`pooler` selects connection sizing and SSL. Prepared statements are **always
disabled** — `SupabasePostgresProvider` hard-sets `prepare: false`, which the
Supabase transaction pooler (pgBouncer transaction mode) requires.

| mode                 | maxConnections | sslMode   | notes                                            |
| -------------------- | -------------- | --------- | ------------------------------------------------ |
| `transaction-pooler` | 1              | `require` | Default. pgBouncer txn mode; no prepared stmts.  |
| `session-pooler`     | 10             | `require` | Backend held per connection for the session.     |
| `direct`             | 10             | `prefer`  | Direct Postgres connection (no pooler).          |

Override sizing/SSL via `connection.maxConnections` / `connection.sslMode`.

### Observability (O2)

Pass an `instrumentation` (the `lib.observability` Instrumentation facade) and
each governed read/write emits one span plus a `database.query` /
`database.mutation` duration metric. The tenant `set_config` statement is
classified as a session statement and excluded from the data-latency histograms.


---

## @lssm-tech/integration.runtime

Description: Runtime integration with secret management
Path: packages/integrations/runtime
URL: /llms/integration.runtime

# @lssm-tech/integration.runtime

Website: https://contractspec.io

**Runtime integration with secret management.**

## What It Provides

- **Layer**: integration.
- **Consumers**: `providers-impls`, bundles, apps that need secrets or channel routing.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.

## Installation

`npm install @lssm-tech/integration.runtime`

or

`bun add @lssm-tech/integration.runtime`

## Usage

Import the root entrypoint from `@lssm-tech/integration.runtime`, or choose a documented subpath when you only need one part of the package surface.

The channel runtime keeps policy evaluation deterministic and auditable:

- Signature-invalid events are rejected before processing.
- `MessagingPolicyEngine` can be replaced by a contract-backed policy evaluator through `ChannelRuntimeService`.
- `ChannelApprovalService` exposes a generic approval queue for CLI, API, web, or custom operator surfaces via the shared channel store.
- `ControlPlaneSkillRegistryService` verifies, installs, lists, and disables signed skill artifacts against an allowlisted trust policy.
- Compiled plans now carry deterministic plan and step IDs, DAG dependency metadata, typed step I/O schema refs, actor audit context, and approval timeout fallback state.
- Capability grants are intended to be bound by the hosting application, for example through `CHANNEL_RUNTIME_DEFAULT_CAPABILITY_GRANTS`, rather than trusted from inbound event payload metadata.
- Hosting applications should also bind a server-side actor via `actorResolver` so runtime approvals and execution are attributed to the authenticated service, operator, or agent principal rather than raw inbound channel claims.
- Telemetry now carries `traceId`, `sessionId`, and `workflowId` when callers provide them in inbound metadata.
- Trace services now persist stage-level trace events so operators can inspect the full intent -> plan -> policy -> action -> outcome chain.

## Architecture

- `src/channel` is part of the package's public or composition surface.
- `src/health.ts` is part of the package's public or composition surface.
- `src/index.ts` is the root public barrel and package entrypoint.
- `src/runtime.health.test.ts` is part of the package's public or composition surface.
- `src/runtime.ts` is part of the package's public or composition surface.
- `src/secrets` is part of the package's public or composition surface.
- `src/transport` is part of the package's public or composition surface.

## Public Entry Points

- Export `.` resolves through `./src/index.ts`.
- Export `./channel` resolves through `./src/channel/index.ts`.
- Export `./channel/approval` resolves through `./src/channel/approval.ts`.
- Export `./channel/authorization` resolves through `./src/channel/authorization.ts`.
- Export `./channel/base-types` resolves through `./src/channel/base-types.ts`.
- Export `./channel/dispatcher` resolves through `./src/channel/dispatcher.ts`.
- Export `./channel/github` resolves through `./src/channel/github.ts`.
- Export `./channel/memory-store` resolves through `./src/channel/memory-store.ts`.
- Export `./channel/plan-types` resolves through `./src/channel/plan-types.ts`.
- Export `./channel/plan-utils` resolves through `./src/channel/plan-utils.ts`.
- Export `./channel/planner` resolves through `./src/channel/planner.ts`.
- Export `./channel/planner-types` resolves through `./src/channel/planner-types.ts`.
- Export `./channel/policy` resolves through `./src/channel/policy.ts`.
- Export `./channel/postgres-queries` resolves through `./src/channel/postgres-queries.ts`.
- Export `./channel/postgres-schema` resolves through `./src/channel/postgres-schema.ts`.
- Export `./channel/postgres-store` resolves through `./src/channel/postgres-store.ts`.
- Export `./channel/replay-fixtures` resolves through `./src/channel/replay-fixtures.ts`.
- Export `./channel/service` resolves through `./src/channel/service.ts`.
- Export `./channel/slack` resolves through `./src/channel/slack.ts`.
- Export `./channel/store` resolves through `./src/channel/store.ts`.
- Export `./channel/telegram` resolves through `./src/channel/telegram.ts`.
- Export `./channel/telemetry` resolves through `./src/channel/telemetry.ts`.
- Export `./channel/trace` resolves through `./src/channel/trace.ts`.
- Export `./channel/types` resolves through `./src/channel/types.ts`.
- Export `./channel/whatsapp-meta` resolves through `./src/channel/whatsapp-meta.ts`.
- Export `./channel/whatsapp-twilio` resolves through `./src/channel/whatsapp-twilio.ts`.
- Export `./health` resolves through `./src/health.ts`.
- Export `./runtime` resolves through `./src/runtime.ts`.
- Export `./secrets` resolves through `./src/secrets/index.ts`.
- Export `./secrets/env-secret-provider` resolves through `./src/secrets/env-secret-provider.ts`.
- Export `./secrets/gcp-secret-manager` resolves through `./src/secrets/gcp-secret-manager.ts`.
- Export `./secrets/manager` resolves through `./src/secrets/manager.ts`.
- Export `./secrets/provider` resolves through `./src/secrets/provider.ts`.
- Export `./transport` resolves through `./src/transport/index.ts`.
- Export `./transport/auth-resolver` resolves through `./src/transport/auth-resolver.ts`.
- Export `./transport/transport-factory` resolves through `./src/transport/transport-factory.ts`.
- Export `./transport/version-negotiator` resolves through `./src/transport/version-negotiator.ts`.
- The package publishes 41 total export subpaths; keep docs aligned with `package.json`.

## Local Commands

- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
- `bun run test` — bun test --pass-with-no-tests
- `bun run lint` — bun lint:fix
- `bun run lint:check` — biome check .
- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
- `bun run typecheck` — tsgo --noEmit
- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
- `bun run clean` — rimraf dist .turbo
- `bun run build:bundle` — contractspec-bun-build transpile
- `bun run build:types` — contractspec-bun-build types
- `bun run prebuild` — contractspec-bun-build prebuild

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed.
- Resolve lint, build, and type errors across nine packages.
- Add Composio universal fallback, fix provider-ranking types, and expand package exports.
- Add first-class transport, auth, versioning, and BYOK support across all integrations.
- Add monorepo-aware environment resolution helpers that materialize framework aliases and redact secret values in reports.
- Upgrade dependencies.
- Stabilize lint gate and runtime contract typing.

## Notes

- Secret providers must implement the `provider` interface; never read secrets directly.
- Environment resolution reports must stay redacted; secret and sensitive values are never serialized into examples, reports, telemetry, or errors.
- Channel stores (memory, postgres) are swappable; do not couple to a specific backend.
- Never import from apps or bundles.


---

## @lssm-tech/integration.voice-input-native

Description: @react-native-voice/voice + expo-av/Deepgram STT integration for M3 voice input
Path: packages/integrations/voice-input-native
URL: /llms/integration.voice-input-native

(No README.md)

---

## @lssm-tech/integration.voice-input-web

Description: Web Speech API + Deepgram Nova-3 STT integration for M3 voice input
Path: packages/integrations/voice-input-web
URL: /llms/integration.voice-input-web

(No README.md)

---

## @lssm-tech/integration.workflow-devkit

Description: Workflow DevKit compiler and runtime bridges for ContractSpec workflows
Path: packages/integrations/workflow-devkit
URL: /llms/integration.workflow-devkit

# @lssm-tech/integration.workflow-devkit

Workflow DevKit compiler and runtime bridges for ContractSpec `WorkflowSpec`.

## What it provides

- Compile a `WorkflowSpec` into a deterministic Workflow DevKit manifest.
- Generate Workflow, Next.js, and generic-host scaffolding.
- Run a `WorkflowSpec` through injected Workflow DevKit primitives such as `sleep`, hooks, and webhooks.
- Create a Workflow-backed `AgentRuntimeAdapterBundle` for `@lssm-tech/lib.ai-agent`.
- Expose chat route helpers and re-export `WorkflowChatTransport` for reconnectable chat UIs.

## Entry points

- `@lssm-tech/integration.workflow-devkit`
- `@lssm-tech/integration.workflow-devkit/compiler`
- `@lssm-tech/integration.workflow-devkit/runtime`
- `@lssm-tech/integration.workflow-devkit/chat-routes`
- `@lssm-tech/integration.workflow-devkit/agent-adapter`
- `@lssm-tech/integration.workflow-devkit/next`

## Workflow vs step boundary

Workflow DevKit code runs across two different execution contexts:

- Workflow functions (`"use workflow"`) orchestrate control flow and must stay deterministic.
- Step functions (`"use step"`) perform the actual Node.js work.

This matches the Workflow docs: workflow functions do not have full Node.js access, while step functions do. Keep Node.js core modules, SDK clients, database access, and other side effects inside `use step` helpers. The workflow function itself should only compose Workflow primitives and call step helpers.

For `WorkflowSpec` authoring in Workflow-hosted apps, import the safe authoring API from `@lssm-tech/lib.contracts-spec/workflow/spec`, not the broad `@lssm-tech/lib.contracts-spec/workflow` barrel.

## Next.js example

```ts
import { withContractSpecWorkflow } from "@lssm-tech/integration.workflow-devkit/next";
import { createWorkflowChatRoutes } from "@lssm-tech/module.ai-chat/core/workflow";

export default withContractSpecWorkflow({
  experimental: {},
});

const routes = createWorkflowChatRoutes({
  workflow: async (payload) => payload,
  getFollowUpToken({ runId }) {
    return `chat:${runId}`;
  },
});

export const POST = routes.start;
```

## Generic host example

```ts
import { createHook, createWebhook, sleep } from "workflow";
import {
  runWorkflowSpecWithWorkflowDevkit,
  type WorkflowDevkitRuntimeBridge,
} from "@lssm-tech/integration.workflow-devkit";
import { onboardingWorkflow } from "./onboarding.workflow";

export async function runOnboarding(input: Record<string, unknown>, bridge: WorkflowDevkitRuntimeBridge) {
  "use workflow";

  // Keep this function deterministic. Node.js work belongs in `use step`
  // helpers that your bridge dispatches to.
  return runWorkflowSpecWithWorkflowDevkit({
    spec: onboardingWorkflow,
    initialData: input,
    bridge,
    primitives: {
      sleep,
      createHook,
      createWebhook,
    },
  });
}
```


---

## contractspec

Description: CLI tool for creating, building, and validating contract specifications
Path: packages/apps-registry/contractspec
URL: /llms/contractspec

# contractspec

Website: https://contractspec.io

**npm-published CLI entry point for ContractSpec. Thin wrapper that delegates to `@lssm-tech/app.cli-contractspec` via `bin/contractspec.mjs`.**

## What It Does

- **Layer**: apps-registry
- **Consumers**: end-users installing `npx contractspec` or `bun x contractspec`

## Installation

`npm install contractspec`

or

`bun add contractspec`

## Usage

```bash
npx contractspec --help
# or
bunx contractspec --help
```

## Public Entry Points

- `contractspec` -> `./bin/contractspec.mjs`

## Local Commands

- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Stability
- Refactor contracts libs to split them reducing bundle size and load

## Notes

- This package is a shim; all logic lives in `@lssm-tech/app.cli-contractspec`
- Do not add dependencies beyond the CLI app workspace reference
- Changes to `bin/contractspec.mjs` affect every user -- test locally before publishing


---

## @lssm-tech/app.cursor-marketplace

Description: Cursor marketplace catalog for ContractSpec product and core libraries
Path: packages/apps-registry/cursor-marketplace
URL: /llms/app.cursor-marketplace

# @lssm-tech/app.cursor-marketplace

Website: https://contractspec.io

**Cursor marketplace catalog containing publishable plugin artifacts for ContractSpec's IDE integrations.**

## What It Does

- **Layer**: apps-registry
- **Consumers**: Cursor IDE users, marketplace publishing pipeline
- Hosts derived plugin artifacts generated from reusable `packs/*` sources of truth

## Running Locally

From `packages/apps-registry/cursor-marketplace`:

## Local Commands

- `bun run validate` — node ../../../scripts/validate-contractspec-plugin.mjs

## Catalog Structure

- Root catalog manifest: `.cursor-plugin/marketplace.json`
- Publishable plugin artifacts: `plugins/*`
- Reusable source packs live outside this package under `packs/*` and are exported here

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- Expose contract management via CLI and MCP
- Add Cursor marketplace catalog for core ContractSpec libraries

## Notes

- Each plugin must have a valid `.cursor-plugin/plugin.json`
- Do not add runtime code; this package contains only declarative metadata
- Customer-facing runtime behavior is produced through `agentpacks` generation and hook/MCP configs, not custom code in this package
- Validate changes with `bun run validate` before publishing
- Logo assets in `assets/` must remain stable (referenced by marketplace)


---

## spec-driven-development

Description: CLI tool for creating, building, and validating contract specifications
Path: packages/apps-registry/spec-driven-development
URL: /llms/spec-driven-development

# spec-driven-development

Website: https://contractspec.io

**npm-published CLI alias for ContractSpec under the `sdd` / `spec-driven-development` binary names. Thin wrapper that delegates to `@lssm-tech/app.cli-contractspec`.**

## What It Does

- **Layer**: apps-registry
- **Consumers**: end-users installing `npx sdd` or `npx spec-driven-development`

## Installation

`npm install spec-driven-development`

or

`bun add spec-driven-development`

## Usage

```bash
npx sdd --help
# or
bunx sdd --help
```

## Public Entry Points

- `sdd` -> `./bin/contractspec.mjs`
- `spec-driven-development` -> `./bin/contractspec.mjs`

## Local Commands

- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
- `bun run publish:pkg:canary` — bun publish:pkg --tag canary

## Recent Updates

- Replace eslint+prettier by biomejs to optimize speed
- PublishConfig not supported by bun

## Notes

- This package is a shim; all logic lives in `@lssm-tech/app.cli-contractspec`
- Do not add dependencies beyond the CLI app workspace reference
- Changes to `bin/contractspec.mjs` affect every user -- test locally before publishing


---