@lssm/module.learning-journey 0.0.0-canary-20251217083314 → 1.41.0

package/dist/index.d.ts

@@ -1,19 +0,0 @@
-import { LEARNING_JOURNEY_OWNERS } from "./contracts/shared.js";
-import { AchievementModel, CardModel, CompleteLessonInput, CourseModel, DeckModel, EnrollInCourseInput, EnrollmentModel, GetDueCardsInput, GetDueCardsOutput, GetLearnerDashboardInput, LearnerDashboardModel, LearnerModel, ProgressModel, SubmitCardReviewInput, SuccessOutput } from "./contracts/models.js";
-import { CompleteLessonContract, EnrollInCourseContract, GetDueCardsContract, GetLearnerDashboardContract, SubmitCardReviewContract } from "./contracts/operations.js";
-import { GetOnboardingProgressContract, ListOnboardingTracksContract, OnboardingProgressModel, OnboardingStepModel, OnboardingStepProgressModel, OnboardingTrackModel, RecordOnboardingEventContract } from "./contracts/onboarding.js";
-import { CardRating, DEFAULT_SRS_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, srsEngine } from "./engines/srs.js";
-import { DEFAULT_XP_CONFIG, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, xpEngine } from "./engines/xp.js";
-import { DEFAULT_STREAK_CONFIG, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, streakEngine } from "./engines/streak.js";
-import { LearnerProfileEntity, LearningGapEntity, LearningPathEntity, LearningStyleEnum, RecommendationEntity, RecommendationTypeEnum, SkillMapEntity, aiEntities, aiEnums } from "./entities/ai.js";
-import { ContentTypeEnum, CourseDifficultyEnum, CourseEntity, CourseModuleEntity, CourseStatusEnum, LessonContentEntity, LessonEntity, LessonTypeEnum, courseEntities, courseEnums } from "./entities/course.js";
-import { CardEntity, CardRatingEnum, CardReviewEntity, CardScheduleEntity, DeckEntity, flashcardEntities, flashcardEnums } from "./entities/flashcard.js";
-import { AchievementEntity, AchievementTypeEnum, DailyGoalEntity, HeartEntity, LeaderboardEntryEntity, LeaderboardPeriodEnum, LearnerAchievementEntity, StreakEntity, XPTransactionEntity, gamificationEntities, gamificationEnums } from "./entities/gamification.js";
-import { CertificateEntity, EnrollmentEntity, EnrollmentStatusEnum, LearnerEntity, LessonProgressEntity, ModuleCompletionEntity, ProgressStatusEnum, learnerEntities, learnerEnums } from "./entities/learner.js";
-import { OnboardingProgressEntity, OnboardingStepCompletionEntity, OnboardingStepEntity, OnboardingStepStatusEnum, OnboardingTrackEntity, onboardingEntities, onboardingEnums } from "./entities/onboarding.js";
-import { AttemptStatusEnum, QuestionEntity, QuestionOptionEntity, QuestionTypeEnum, QuizAttemptEntity, QuizEntity, QuizStatusEnum, SkillAssessmentEntity, quizEntities, quizEnums } from "./entities/quiz.js";
-import { learningJourneyEntities, learningJourneyEnums, learningJourneySchemaContribution } from "./entities/index.js";
-import { AchievementUnlockedEvent, CardReviewedEvent, CertificateIssuedEvent, CourseCompletedEvent, CoursePublishedEvent, DailyGoalCompletedEvent, EnrollmentCreatedEvent, LearningJourneyEvents, LessonCompletedEvent, LevelUpEvent, OnboardingCompletedEvent, OnboardingStartedEvent, OnboardingStepCompletedEvent, QuizCompletedEvent, QuizStartedEvent, StreakUpdatedEvent, XpEarnedEvent } from "./events.js";
-import { BaseEventConditionSpec, CompletionRewardsSpec, CountCompletionConditionSpec, EventCompletionConditionSpec, LearningJourneyStepSpec, LearningJourneyTrackSpec, SrsMasteryCompletionConditionSpec, StepAvailabilitySpec, StepCompletionConditionSpec, StreakRuleSpec, TimeWindowCompletionConditionSpec } from "./track-spec.js";
-import { LearningJourneyFeature } from "./learning-journey.feature.js";
-export { AchievementEntity, AchievementModel, AchievementTypeEnum, AchievementUnlockedEvent, AttemptStatusEnum, BaseEventConditionSpec, CardEntity, CardModel, CardRating, CardRatingEnum, CardReviewEntity, CardReviewedEvent, CardScheduleEntity, CertificateEntity, CertificateIssuedEvent, CompleteLessonContract, CompleteLessonInput, CompletionRewardsSpec, ContentTypeEnum, CountCompletionConditionSpec, CourseCompletedEvent, CourseDifficultyEnum, CourseEntity, CourseModel, CourseModuleEntity, CoursePublishedEvent, CourseStatusEnum, DEFAULT_SRS_CONFIG, DEFAULT_STREAK_CONFIG, DEFAULT_XP_CONFIG, DailyGoalCompletedEvent, DailyGoalEntity, DeckEntity, DeckModel, EnrollInCourseContract, EnrollInCourseInput, EnrollmentCreatedEvent, EnrollmentEntity, EnrollmentModel, EnrollmentStatusEnum, EventCompletionConditionSpec, GetDueCardsContract, GetDueCardsInput, GetDueCardsOutput, GetLearnerDashboardContract, GetLearnerDashboardInput, GetOnboardingProgressContract, HeartEntity, LEARNING_JOURNEY_OWNERS, LeaderboardEntryEntity, LeaderboardPeriodEnum, LearnerAchievementEntity, LearnerDashboardModel, LearnerEntity, LearnerModel, LearnerProfileEntity, LearningGapEntity, LearningJourneyEvents, LearningJourneyFeature, LearningJourneyStepSpec, LearningJourneyTrackSpec, LearningPathEntity, LearningStyleEnum, LessonCompletedEvent, LessonContentEntity, LessonEntity, LessonProgressEntity, LessonTypeEnum, LevelUpEvent, ListOnboardingTracksContract, ModuleCompletionEntity, OnboardingCompletedEvent, OnboardingProgressEntity, OnboardingProgressModel, OnboardingStartedEvent, OnboardingStepCompletedEvent, OnboardingStepCompletionEntity, OnboardingStepEntity, OnboardingStepModel, OnboardingStepProgressModel, OnboardingStepStatusEnum, OnboardingTrackEntity, OnboardingTrackModel, ProgressModel, ProgressStatusEnum, QuestionEntity, QuestionOptionEntity, QuestionTypeEnum, QuizAttemptEntity, QuizCompletedEvent, QuizEntity, QuizStartedEvent, QuizStatusEnum, RecommendationEntity, RecommendationTypeEnum, RecordOnboardingEventContract, ReviewResult, SRSConfig, SRSEngine, SRSState, SkillAssessmentEntity, SkillMapEntity, SrsMasteryCompletionConditionSpec, StepAvailabilitySpec, StepCompletionConditionSpec, StreakConfig, StreakEngine, StreakEntity, StreakRuleSpec, StreakState, StreakUpdateResult, StreakUpdatedEvent, SubmitCardReviewContract, SubmitCardReviewInput, SuccessOutput, TimeWindowCompletionConditionSpec, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, XPTransactionEntity, XpEarnedEvent, aiEntities, aiEnums, courseEntities, courseEnums, flashcardEntities, flashcardEnums, gamificationEntities, gamificationEnums, learnerEntities, learnerEnums, learningJourneyEntities, learningJourneyEnums, learningJourneySchemaContribution, onboardingEntities, onboardingEnums, quizEntities, quizEnums, srsEngine, streakEngine, xpEngine };

package/dist/learning-journey.feature.d.ts

@@ -1,11 +0,0 @@
-import { FeatureModuleSpec } from "@lssm/lib.contracts";
-
-//#region src/learning-journey.feature.d.ts
-
-/**
- * Learning Journey feature module that bundles course enrollment,
- * onboarding tracks, flashcard review, and gamification capabilities.
- */
-declare const LearningJourneyFeature: FeatureModuleSpec;
-//#endregion
-export { LearningJourneyFeature };

package/dist/libs/contracts/dist/capabilities/openbanking.js

@@ -1,88 +0,0 @@
-import { StabilityEnum } from "../ownership.js";
-
-//#region ../../libs/contracts/dist/capabilities/openbanking.js
-const OWNERS = ["platform.finance"];
-const TAGS = ["open-banking", "finance"];
-const openBankingAccountsReadCapability = {
-	meta: {
-		key: "openbanking.accounts.read",
-		version: 1,
-		kind: "integration",
-		title: "Open Banking Accounts (Read)",
-		description: "Provides read-only access to linked bank accounts, including account summaries and metadata.",
-		domain: "finance",
-		owners: [...OWNERS],
-		tags: [...TAGS],
-		stability: StabilityEnum.Experimental
-	},
-	provides: [
-		{
-			surface: "operation",
-			name: "openbanking.accounts.list",
-			version: 1,
-			description: "List bank accounts linked to a Powens open banking connection."
-		},
-		{
-			surface: "operation",
-			name: "openbanking.accounts.get",
-			version: 1,
-			description: "Retrieve the canonical bank account record for a specific account."
-		},
-		{
-			surface: "operation",
-			name: "openbanking.accounts.sync",
-			version: 1,
-			description: "Trigger a refresh of bank account metadata from the open banking provider."
-		}
-	]
-};
-const openBankingTransactionsReadCapability = {
-	meta: {
-		key: "openbanking.transactions.read",
-		version: 1,
-		kind: "integration",
-		title: "Open Banking Transactions (Read)",
-		description: "Enables retrieval of transaction history for linked bank accounts via open banking providers.",
-		domain: "finance",
-		owners: [...OWNERS],
-		tags: [...TAGS, "transactions"],
-		stability: StabilityEnum.Experimental
-	},
-	provides: [{
-		surface: "operation",
-		name: "openbanking.transactions.list",
-		version: 1,
-		description: "List transactions for a given bank account with optional date filtering."
-	}, {
-		surface: "operation",
-		name: "openbanking.transactions.sync",
-		version: 1,
-		description: "Synchronise transactions from the open banking provider into the canonical ledger."
-	}]
-};
-const openBankingBalancesReadCapability = {
-	meta: {
-		key: "openbanking.balances.read",
-		version: 1,
-		kind: "integration",
-		title: "Open Banking Balances (Read)",
-		description: "Allows querying of current and available balances for linked bank accounts via open banking providers.",
-		domain: "finance",
-		owners: [...OWNERS],
-		tags: [...TAGS, "balances"],
-		stability: StabilityEnum.Experimental
-	},
-	provides: [{
-		surface: "operation",
-		name: "openbanking.balances.get",
-		version: 1,
-		description: "Retrieve the latest known balances for a specified bank account."
-	}, {
-		surface: "operation",
-		name: "openbanking.balances.refresh",
-		version: 1,
-		description: "Force a balance refresh from the open banking provider."
-	}]
-};
-
-//#endregion

package/dist/libs/contracts/dist/client/index.js

@@ -1,5 +0,0 @@
-'use client';
-
-import "./react/feature-render.js";
-import "./react/form-render.js";
-import "./react/index.js";

package/dist/libs/contracts/dist/client/react/feature-render.js

@@ -1,2 +0,0 @@
-import "../../presentations.v2.js";
-import "react";

package/dist/libs/contracts/dist/client/react/form-render.js

@@ -1,4 +0,0 @@
-import "react";
-import "react-hook-form";
-import "@hookform/resolvers/zod";
-import "react/jsx-runtime";

package/dist/libs/contracts/dist/client/react/index.js

@@ -1,4 +0,0 @@
-'use client';
-
-import "./feature-render.js";
-import "./form-render.js";

package/dist/libs/contracts/dist/contract-registry/index.js

@@ -1 +0,0 @@
-import { ContractRegistryFileSchema, ContractRegistryItemSchema, ContractRegistryItemTypeSchema } from "./schemas.js";

package/dist/libs/contracts/dist/contract-registry/schemas.js

@@ -1,60 +0,0 @@
-import { StabilityEnum } from "../ownership.js";
-import z from "zod";
-
-//#region ../../libs/contracts/dist/contract-registry/schemas.js
-const ContractRegistryItemTypeSchema = z.enum([
-	"contractspec:operation",
-	"contractspec:event",
-	"contractspec:presentation",
-	"contractspec:form",
-	"contractspec:feature",
-	"contractspec:workflow",
-	"contractspec:template",
-	"contractspec:integration",
-	"contractspec:data-view",
-	"contractspec:migration",
-	"contractspec:telemetry",
-	"contractspec:experiment",
-	"contractspec:app-config",
-	"contractspec:knowledge"
-]);
-const ContractRegistryFileSchema = z.object({
-	path: z.string().min(1),
-	type: z.string().min(1),
-	content: z.string().optional()
-});
-const ContractRegistryItemSchema = z.object({
-	name: z.string().min(1),
-	type: ContractRegistryItemTypeSchema,
-	version: z.number().int().nonnegative(),
-	title: z.string().min(1),
-	description: z.string().min(1),
-	meta: z.object({
-		stability: z.enum([
-			StabilityEnum.Idea,
-			StabilityEnum.InCreation,
-			StabilityEnum.Experimental,
-			StabilityEnum.Beta,
-			StabilityEnum.Stable,
-			StabilityEnum.Deprecated
-		]),
-		owners: z.array(z.string().min(1)).default([]),
-		tags: z.array(z.string().min(1)).default([])
-	}),
-	dependencies: z.array(z.string().min(1)).optional(),
-	registryDependencies: z.array(z.string().min(1)).optional(),
-	files: z.array(ContractRegistryFileSchema).min(1),
-	schema: z.object({
-		input: z.unknown().optional(),
-		output: z.unknown().optional()
-	}).optional()
-});
-const ContractRegistryManifestSchema = z.object({
-	$schema: z.string().min(1).optional(),
-	name: z.string().min(1),
-	homepage: z.string().min(1).optional(),
-	items: z.array(ContractRegistryItemSchema)
-});
-
-//#endregion
-export { ContractRegistryFileSchema, ContractRegistryItemSchema, ContractRegistryItemTypeSchema };

package/dist/libs/contracts/dist/docs/PUBLISHING.docblock.js

@@ -1,16 +0,0 @@
-import { registerDocBlocks } from "./registry.js";
-
-//#region ../../libs/contracts/dist/docs/PUBLISHING.docblock.js
-const PUBLISHING_DocBlocks = [{
-	id: "docs.PUBLISHING",
-	title: "Publishing ContractSpec Libraries",
-	summary: "This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/PUBLISHING",
-	tags: ["PUBLISHING"],
-	body: "# Publishing ContractSpec Libraries\n\nThis guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).\n\n## Release Tracks\n\n| Track | Branch | npm Tag | Frequency | Versioning | Use Case |\n|-------|--------|---------|-----------|------------|----------|\n| **Stable** | `release` | `latest` | Manual | SemVer (e.g., `1.7.4`) | Production, external users |\n| **Canary** | `main` | `canary` | Every Push | Snapshot (e.g., `1.7.4-canary...`) | Dev, internal testing |\n\n## Prerequisites\n\n- ✅ `NPM_TOKEN` secret is configured in GitHub (owner or automation token with _publish_ scope).\n- ✅ `GITHUB_TOKEN` (built-in) has permissions to create PRs (enabled by default in new repos).\n- ✅ For stable releases: `release` branch exists and is protected.\n\n## Canary Workflow (Automatic)\n\nEvery commit pushed to `main` triggers the `.github/workflows/publish-canary.yml` workflow.\n\n1. **Trigger**: Push to `main`.\n2. **Versioning**: Runs `changeset version --snapshot canary` to generate a temporary snapshot version.\n3. **Publish**: Packages are published to npm with the `canary` tag using `changeset publish --tag canary`.\n\n### Consuming Canary Builds\n\nTo install the latest bleeding-edge version:\n\n```bash\nnpm install @lssm/lib.contracts@canary\n# or\nbun add @lssm/lib.contracts@canary\n```\n\n## Stable Release Workflow (Manual)\n\nStable releases are managed via the `release` branch using the standard [Changesets Action](https://github.com/changesets/action).\n\n1. **Develop on `main`**: Create features and fixes.\n2. **Add Changesets**: Run `bun changeset` to document changes and impact (major/minor/patch).\n3. **Merge to `release`**: When ready to ship, open a PR from `main` to `release` or merge manually.\n4. **\"Version Packages\" PR**:\n   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **\"Version Packages\"**.\n   - This PR contains the version bumps and updated `CHANGELOG.md` files.\n5. **Merge & Publish**:\n   - Review and merge the \"Version Packages\" PR.\n   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the `latest` tag.\n\n### Publishing Steps\n\n1. Ensure all changesets are present on `main`.\n2. Merge `main` into `release`:\n   ```bash\n   git checkout release\n   git pull origin release\n   git merge main\n   git push origin release\n   ```\n3. Go to GitHub Pull Requests. You will see a **\"Version Packages\"** PR created by the bot.\n4. Merge that PR.\n5. The release is now live on npm!\n\n## Manual Verification (Optional)\n\nBefore publishing a new version you can run:\n\n```bash\nbun run build:not-apps\nnpx npm-packlist --json packages/libs/contracts\n```\n\n## Rollback\n\nIf a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use `npm deprecate <package>@<version>` if we need to warn consumers about a broken release.\n"
-}];
-registerDocBlocks(PUBLISHING_DocBlocks);
-
-//#endregion

package/dist/libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -1,16 +0,0 @@
-import { registerDocBlocks } from "./registry.js";
-
-//#region ../../libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js
-const accessibility_wcag_compliance_specs_DocBlocks = [{
-	id: "docs.accessibility_wcag_compliance_specs",
-	title: "Accessibility & WCAG Compliance — **specs.md**",
-	summary: "> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/accessibility_wcag_compliance_specs",
-	tags: ["accessibility_wcag_compliance_specs"],
-	body: "# Accessibility & WCAG Compliance — **specs.md**\n\n> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.\n\n---\n\n## 0) Scope & Principles\n\n- **Standards:** WCAG\xA02.2\xA0AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN\xA0301\xA0549 compliance by conformance to WCAG.\n- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).\n- **Rule of ARIA:** “No ARIA is better than bad ARIA.” Prefer native elements.\n- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.\n- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in `packages/lssm/libs/ui-kit-web`. Prefer those components over per‑app duplicates (`packages/*/apps/*/src/components/ui`). When missing, add to `ui-kit-web` first, then adopt app‑side.\n\n---\n\n## 1) Design Requirements (Design System & Tokens)\n\n**1.1 Color & Contrast**\n\n- Body text, icons essential to meaning: **≥\xA04.5:1**; large text (≥\xA018.66px regular / 14px bold): **≥\xA03:1**.\n- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥\xA03:1** against adjacent colors; text within components follows text ratios.\n- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.\n\n**1.2 Focus Indicators (WCAG\xA02.4.11/12)**\n\n- Every interactive element has a **visible focus** with clear offset; indicator contrast **≥\xA03:1** vs adjacent colors and indicator **area ≥\xA02\xA0CSS\xA0px** thick.\n- Focus **must not be obscured** by sticky headers/footers or scroll containers.\n\n**1.3 Motion & Preferences**\n\n- Respect `prefers-reduced-motion`: suppress large parallax, auto‑animations; provide instant alternatives.\n- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.\n\n**1.4 Target Size (2.5.8)**\n\n- Hit areas **≥\xA024×24\xA0CSS\xA0px** (web) and **≥\xA044×44\xA0dp** (mobile) unless exempt.\n\n**1.5 Typography & Layout**\n\n- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320\xA0CSS\xA0px** width.\n- Maintain clear heading hierarchy (h1…h6), one **h1** per view.\n\n- Repository baseline (Web): default body text uses Tailwind `text-lg` (≈18px). As of 2025‑09‑20, the repository bumped all Tailwind typography scale usages by +1 step (e.g., `text-sm`→`text-base`, `text-base`→`text-lg`, …, `text-8xl`→`text-9xl`). For long‑form content, default to `prose-lg`.\n- Do not use `text-xs` for body copy. Reserve `text-sm` only for non‑essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.\n- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or `leading-relaxed`/`leading-7` for body text where dense blocks appear.\n\n**1.6 Iconography & Imagery**\n\n- Decorative images: `alt=\"\"` or `aria-hidden=\"true\"`.\n- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.\n\n---\n\n## 2) Content Requirements (UX Writing)\n\n- Links say **what happens** (avoid “click here”).\n- Buttons start with verbs; avoid ambiguous labels.\n- Form labels are **visible**; placeholders are **not labels**.\n- Error messages: human + programmatic association; avoid color‑only.\n- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).\n- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).\n\n---\n\n## 3) Engineering Requirements (Web — Next.js/React)\n\n> Use and extend `packages/lssm/libs/ui-kit-web` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to `ui-kit-web` first.\n\n**3.1 Semantics & Landmarks**\n\n- Use native elements: `<button>`, `<a href>`, `<label for>`, `<fieldset>`, `<legend>`, `<table>`, etc.\n- Landmarks per page: `header`, `nav`, `main`, `aside`, `footer`. Provide a **Skip to main content** link.\n- Provide a **Route Announcer** (`aria-live=\"polite\"`) and move focus to page **h1** after navigation.\n\n**3.2 Keyboard**\n\n- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.\n- Common bindings:\n  - Space/Enter → activate button; Enter on link;\n  - Esc closes dialogs/menus;\n  - Arrow keys for lists/menus/tablists with **roving tabindex**.\n\n**3.3 Focus Management**\n\n- On route change (Next.js), move focus to the page `<h1>` or container and announce via a live region.\n- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.\n- Don’t steal focus except after explicit user action.\n\n**3.4 Forms**\n\n- Each input has a `<label>` or `aria-label`. Group related inputs with `<fieldset><legend>`.\n- Associate errors via `aria-describedby` or inline IDs; announce with `role=\"alert\"` (assertive only for critical).\n- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.\n\n**3.5 ARIA Usage**\n\n- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.\n- Ensure **name/role/value** are programmatically determinable.\n\n**3.6 Media**\n\n- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.\n- No auto‑playing audio. Auto‑playing video must be muted and pausable; provide controls.\n\n**3.7 Tables & Data**\n\n- Use `<th scope>` for headers; captions via `<caption>`; announce sorting via `aria-sort`.\n- Provide CSV/JSON export where charts are primary.\n\n**3.8 Performance & Robustness**\n\n- Avoid content shifts that move focus; reserve space or use skeletons.\n- Maintain accessible names through hydration/SSR; avoid `dangerouslySetInnerHTML` where possible.\n\n**3.9 Next.js specifics**\n\n- Use `next/link` for navigation; ensure links are **links**, not buttons.\n- `next/image` must include **alt** (empty if decorative).\n- Announce route changes with a **global live region** and shift focus to the new view.\n\n**3.10 Accessibility library integration**\n\n- Import `@lssm/lib.accessibility` at app root. It auto-imports its `styles.css` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:\n\n```tsx\n// app/layout.tsx\nimport '@lssm/lib.accessibility'; // includes tokens and provider exports\n// or if needed: import '@lssm/lib.accessibility/src/styles.css';\n```\n\n- Wrap the app with `AccessibilityProvider` and include an element with `id=\"main\"` for the skip link target.\n\n---\n\n## 3b) lssm/ui-kit-web — Component Patterns & Defaults\n\n> Source: `packages/lssm/libs/ui-kit-web/ui/*`\n\n- **Button/Input/Textarea**: Built‑in `focus-visible` rings; ensure visible labels via `FormLabel` or `aria-label`.\n- **Form** (`form.tsx`): `FormControl` wires `aria-invalid` and `aria-describedby` to `FormMessage` and `FormDescription`. Prefer `FormMessage` for inline errors. Add `role=\"alert\"` only for critical.\n- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus‑trap and return‑focus. Provide `DialogTitle` + `DialogDescription` for name/description.\n- **Select/Combobox**: Prefer `SelectTrigger` with visible label; for icon‑only triggers, supply `aria-label`. Document examples in each app.\n- **Tabs**: Use `TabsList`, `TabsTrigger`, `TabsContent`; names are programmatically determinable.\n- **Toast/Toaster**: Prefer non‑blocking announcements; map critical to assertive region; include action buttons with clear labels.\n- **Table**: Use `TableCaption`; ensure `TableHead` cells use proper `scope`. Provide `aria-sort` on sortable headers.\n- **Utilities to add (repo action)**:\n  - `SkipLink` component and pattern in layouts.\n  - `RouteAnnouncer` (`aria-live=\"polite\"`) and **FocusOnRouteChange** helper.\n  - `VisuallyHidden` wrapper (Radix visually-hidden or minimal utility).\n  - `useReducedMotion` helper; honor in animated components.\n  - Touch‑size variants (≥44×44) for interactive atoms.\n\n---\n\n## 4) Engineering Requirements (Mobile — Expo/React\xA0Native)\n\n- Set `accessibilityLabel`, `accessibilityHint`, and `accessibilityRole` on touchables.\n- Ensure **hit slop** / min size **≥\xA044×44\xA0dp**.\n- Support Dynamic Type / font scaling; no clipped text at **200%**.\n- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.\n- Group related items with `accessibilityElements` ordering; hide decoration with `accessible={false}` or `importantForAccessibility=\"no-hide-descendants\"` when appropriate.\n- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.\n\n---\n\n## 5) Component Patterns (Acceptance Rules)\n\n**Buttons & Links**\n\n- Use `<button>` for actions, `<a href>` for navigation. Provide disabled states that are perceivable beyond color.\n\n**Navigation**\n\n- Provide **Skip link**. One primary nav landmark. Indicate current page (`aria-current=\"page\"`).\n\n**Menus/Combobox/Autocomplete**\n\n- Follow ARIA patterns: focus moves into list; `aria-expanded`, `aria-controls`, `aria-activedescendant` when applicable; Esc closes; typing filters.\n\n**Modals/Dialogs**\n\n- `role=\"dialog\"` or `alertdialog` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.\n\n**Tabs**\n\n- `role=\"tablist\"`; tabs are in the tab order; arrow keys switch focus; content is `role=\"tabpanel\"` with `aria-labelledby`.\n\n**Toasts/Notifications**\n\n- Non-critical: `aria-live=\"polite\"`; critical: `role=\"alert\"` sparingly.\n\n**Infinite Scroll / “Load More”**\n\n- Provide **Load more** control; announce new content to SR; preserve keyboard position.\n\n**Drag & Drop (2.5.7)**\n\n- Provide **non‑drag** alternative (e.g., move up/down buttons).\n\n**Charts & Maps**\n\n- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.\n\n---\n\n## 6) Testing & CI (Blocking Gates)\n\n**Static & Unit**\n\n- `eslint-plugin-jsx-a11y` — error on violations.\n- `jest-axe` — unit tests for components.\n\n**Automated Integration**\n\n- `axe-core` via Playwright or Cypress on critical flows.\n- `pa11y-ci` on key routes; threshold: **0 Critical / 0 Serious** to merge.\n- Lighthouse CI a11y score **≥\xA095** on target pages.\n\n**Manual QA (per release)**\n\n- **Keyboard patrol:** navigate primary flows without mouse.\n- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.\n- **Zoom & Reflow:** 200–400% & 320\xA0px width.\n- **Color/Contrast check:** tokens in both themes.\n\n**Reporting**\n\n- A11y issues labeled: `a11y-blocker`, `a11y-bug`, `a11y-enhancement` with WCAG ref.\n\n---\n\n## 7) Repository‑Specific Adoption Plan\n\n- Centralize UI usage on `packages/lssm/libs/ui-kit-web` and de‑duplicate per‑app `components/ui` where feasible.\n- Introduce `SkipLink`, `RouteAnnouncer`, `FocusOnRouteChange`, and `VisuallyHidden` in `ui-kit-web`. Adopt in app layouts (`app/layout.tsx`) first.\n- Add `useReducedMotion` and wire into animated components (e.g., `drawer`, `tooltip`, `carousel`).\n- Add touch‑size variants to `Button`, `IconButton`, `TabsTrigger`, toggles.\n- Document Select label patterns and error association in Forms.\n\n---\n\n## 8) Code Snippets\n\n**Skip Link**\n\n```html\n<a\n  class=\"sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2\"\n  href=\"#main\"\n  >Skip to main content</a\n>\n<main id=\"main\">…</main>\n```\n\n**Dialog (Radix + shadcn/ui) — essentials**\n\n```tsx\n// Ensure label, description, focus trap, and return focus on close remain intact\n<Dialog>\n  <DialogTrigger asChild>\n    <button aria-haspopup=\"dialog\">Open settings</button>\n  </DialogTrigger>\n  <DialogContent aria-describedby=\"settings-desc\">\n    <DialogTitle>Settings</DialogTitle>\n    <p id=\"settings-desc\">Update your preferences.</p>\n    <DialogClose asChild>\n      <button>Close</button>\n    </DialogClose>\n  </DialogContent>\n</Dialog>\n```\n\n**Form error association**\n\n```tsx\n<label htmlFor=\"email\">Email</label>\n<input id=\"email\" name=\"email\" type=\"email\" aria-describedby=\"email-err\" />\n<p id=\"email-err\" role=\"alert\">Enter a valid email.</p>\n```\n\n**Route change announcement (Next.js)**\n\n```tsx\n// Add once at app root\n<div\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n  id=\"route-announcer\"\n  className=\"sr-only\"\n/>\n```\n\n---\n\n## 9) Exceptions & Waivers\n\n- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**\n\n---\n\n## 10) Ownership\n\n- **Design:** maintains token contrast, component specs.\n- **Engineering:** enforces CI gates, implements patterns.\n- **QA:** runs manual checks per release.\n- **PM:** blocks release if AA not met on user‑visible flows.\n\n---\n\n## 11) References (internalize; no external dependency at runtime)\n\n- WCAG\xA02.2 (AA), EN\xA0301\xA0549. ARIA Authoring Practices. Platform HIG (Apple, Material).\n- `packages/lssm/libs/ui-kit-web` as the canonical UI source for web.\n\n> **Bottom line:** Shipping means **accessible by default**. We don’t trade a11y for speed; we bake it into speed.\n\n---\n\n## 12) Adoption Status (2025-09-23)\n\n- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.\n- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.\n- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to `Section`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role=\"alert\" where critical.\n\n> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.\n\n---\n\n## 13) CI Hardening & Visual QA\n\n- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.\n- Unit: Run jest-axe for ui-kit-web and app-level components.\n- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).\n- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).\n- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.\n- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.\n\n### Recent additions (2025-09-26)\n\n- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with `aria-controls`, `aria-activedescendant`, `Escape`/`Tab` handling, and labelled listbox.\n- Cypress a11y tests added for furniture and incidents modules on `/modules` and operators flows; checks run axe with critical/serious impacts.\n\n## 14) Accessibility Telemetry (PostHog)\n\n- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.\n- Properties: app, route, previous_value, new_value, timestamp.\n- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.\n- Privacy: No PII; aggregate only.\n"
-}];
-registerDocBlocks(accessibility_wcag_compliance_specs_DocBlocks);
-
-//#endregion

package/dist/libs/contracts/dist/docs/index.js

@@ -1,29 +0,0 @@
-import { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes } from "./presentations.js";
-import { DocRegistry, defaultDocRegistry, registerDocBlocks } from "./registry.js";
-import "./PUBLISHING.docblock.js";
-import "./accessibility_wcag_compliance_specs.docblock.js";
-import "./tech/PHASE_1_QUICKSTART.docblock.js";
-import "./tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js";
-import "./tech/PHASE_3_AUTO_EVOLUTION.docblock.js";
-import "./tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.js";
-import "./tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.js";
-import "./tech/lifecycle-stage-system.docblock.js";
-import "./tech/presentation-runtime.docblock.js";
-import "./tech/auth/better-auth-nextjs.docblock.js";
-import "./tech/schema/README.docblock.js";
-import "./tech/templates/runtime.docblock.js";
-import "./tech/workflows/overview.docblock.js";
-import "./tech/mcp-endpoints.docblock.js";
-import "./tech/vscode-extension.docblock.js";
-import "./tech/telemetry-ingest.docblock.js";
-import "./tech/contracts/openapi-export.docblock.js";
-import "./tech/studio/workspaces.docblock.js";
-import "./tech/studio/sandbox-unlogged.docblock.js";
-import "./tech/studio/workspace-ops.docblock.js";
-import "./tech/studio/project-routing.docblock.js";
-import "./tech/studio/platform-admin-panel.docblock.js";
-import "./tech/studio/learning-events.docblock.js";
-import "./tech/studio/learning-journeys.docblock.js";
-import "./tech/studio/project-access-teams.docblock.js";
-import "./tech/studio/team-invitations.docblock.js";
-import "./tech/llm/llm-integration.docblock.js";

package/dist/libs/contracts/dist/docs/presentations.js

@@ -1,71 +0,0 @@
-//#region ../../libs/contracts/dist/docs/presentations.js
-const DEFAULT_TARGETS = [
-	"markdown",
-	"application/json",
-	"application/xml",
-	"react"
-];
-function normalizeRoute(route) {
-	if (!route.length) return "/";
-	const withLeading = route.startsWith("/") ? route : `/${route}`;
-	return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-	if (block.route) return normalizeRoute(block.route);
-	const prefix = routePrefix ?? "/docs";
-	const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-	return normalizeRoute(slug.startsWith("/") ? slug : `${prefix}/${slug}`);
-}
-function buildName(block, namespace) {
-	return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationV2(block, options) {
-	const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-	const version = block.version ?? options?.defaultVersion ?? 1;
-	const stability = block.stability ?? options?.defaultStability ?? "stable";
-	return {
-		meta: {
-			name: buildName(block, options?.namespace),
-			version,
-			description: block.summary ?? block.title,
-			tags: block.tags,
-			owners: block.owners,
-			domain: block.domain,
-			stability
-		},
-		policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : void 0,
-		source: {
-			type: "blocknotejs",
-			docJson: block.body
-		},
-		targets
-	};
-}
-function docBlockToPresentationSpec(block, options) {
-	const version = block.version ?? options?.defaultVersion ?? 1;
-	const stability = block.stability ?? options?.defaultStability ?? "stable";
-	return {
-		meta: {
-			name: buildName(block, options?.namespace),
-			version,
-			stability,
-			tags: block.tags,
-			owners: block.owners,
-			description: block.summary ?? block.title
-		},
-		content: {
-			kind: "markdown",
-			content: block.body
-		}
-	};
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-	return blocks.map((block) => ({
-		block,
-		route: deriveRoute(block, options?.routePrefix),
-		descriptor: docBlockToPresentationV2(block, options)
-	}));
-}
-
-//#endregion
-export { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes };

package/dist/libs/contracts/dist/docs/registry.js

@@ -1,44 +0,0 @@
-import { docBlockToPresentationSpec, docBlocksToPresentationRoutes } from "./presentations.js";
-
-//#region ../../libs/contracts/dist/docs/registry.js
-var DocRegistry = class {
-	routes = /* @__PURE__ */ new Map();
-	constructor(blocks = [], options) {
-		blocks.forEach((block) => this.register(block, options));
-	}
-	register(block, options) {
-		const [route] = docBlocksToPresentationRoutes([block], options);
-		if (route) this.routes.set(block.id, route);
-		return this;
-	}
-	list() {
-		return [...this.routes.values()];
-	}
-	get(id) {
-		return this.routes.get(id);
-	}
-	toRouteTuples() {
-		return this.list().map(({ route, descriptor }) => [route, descriptor]);
-	}
-	toPresentationSpecs(options) {
-		return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-	}
-};
-const requiredFields = [
-	"id",
-	"title",
-	"body",
-	"kind",
-	"visibility",
-	"route"
-];
-const defaultDocRegistry = new DocRegistry();
-function registerDocBlocks(blocks) {
-	for (const block of blocks) {
-		for (const field of requiredFields) if (!block[field]) throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-		defaultDocRegistry.register(block);
-	}
-}
-
-//#endregion
-export { DocRegistry, defaultDocRegistry, registerDocBlocks };

package/dist/libs/contracts/dist/docs/tech/PHASE_1_QUICKSTART.docblock.js

@@ -1,16 +0,0 @@
-import { registerDocBlocks } from "../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/PHASE_1_QUICKSTART.docblock.js
-const tech_PHASE_1_QUICKSTART_DocBlocks = [{
-	id: "docs.tech.PHASE_1_QUICKSTART",
-	title: "Phase 1: API Reference Index",
-	summary: "Quick reference for all new Phase 1 APIs.",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/tech/PHASE_1_QUICKSTART",
-	tags: ["tech", "PHASE_1_QUICKSTART"],
-	body: "# Phase 1: API Reference Index\n\nQuick reference for all new Phase 1 APIs.\n\n---\n\n## @lssm/lib.multi-tenancy\n\n### RLS\n```typescript\nimport { createRlsMiddleware, type TenantIdProvider } from '@lssm/lib.multi-tenancy/rls';\n```\n\n### Provisioning\n```typescript\nimport { \n  TenantProvisioningService,\n  type CreateTenantInput,\n  type TenantProvisioningConfig \n} from '@lssm/lib.multi-tenancy/provisioning';\n```\n\n### Isolation\n```typescript\nimport { IsolationValidator } from '@lssm/lib.multi-tenancy/isolation';\n```\n\n---\n\n## @lssm/lib.observability\n\n### Tracing\n```typescript\nimport { \n  getTracer,\n  traceAsync,\n  traceSync,\n  createTracingMiddleware \n} from '@lssm/lib.observability/tracing';\n```\n\n### Metrics\n```typescript\nimport {\n  getMeter,\n  createCounter,\n  createUpDownCounter,\n  createHistogram,\n  standardMetrics\n} from '@lssm/lib.observability/metrics';\n```\n\n### Logging\n```typescript\nimport {\n  Logger,\n  logger,\n  type LogLevel,\n  type LogEntry\n} from '@lssm/lib.observability/logging';\n```\n\n---\n\n## @lssm/lib.resilience\n\n### Circuit Breaker\n```typescript\nimport {\n  CircuitBreaker,\n  type CircuitState,\n  type CircuitBreakerConfig\n} from '@lssm/lib.resilience/circuit-breaker';\n```\n\n### Retry\n```typescript\nimport { retry } from '@lssm/lib.resilience/retry';\n```\n\n### Timeout\n```typescript\nimport { timeout } from '@lssm/lib.resilience/timeout';\n```\n\n### Fallback\n```typescript\nimport { fallback } from '@lssm/lib.resilience/fallback';\n```\n\n---\n\n## Enhanced: @lssm/lib.contracts\n\n### DataViews\n```typescript\nimport { DataViewQueryGenerator } from '@lssm/lib.contracts/data-views/query-generator';\nimport { DataViewRuntime } from '@lssm/lib.contracts/data-views/runtime';\n```\n\n### Workflows\n```typescript\nimport { SLAMonitor, type SLABreachEvent } from '@lssm/lib.contracts/workflow/sla-monitor';\nimport { PrismaStateStore } from '@lssm/lib.contracts/workflow/adapters/db-adapter';\n```\n\n---\n\n## Enhanced: @lssm/lib.design-system\n\n### DataView Components\n```typescript\nimport { DataViewRenderer } from '@lssm/lib.design-system/components/data-view/DataViewRenderer';\n// Also available: DataViewList, DataViewTable, DataViewDetail\n```\n\n---\n\n## Usage Examples\n\n### Complete Workflow with All Features\n\n```typescript\nimport { WorkflowRunner } from '@lssm/lib.contracts/workflow/runner';\nimport { PrismaStateStore } from '@lssm/lib.contracts/workflow/adapters/db-adapter';\nimport { SLAMonitor } from '@lssm/lib.contracts/workflow/sla-monitor';\nimport { CircuitBreaker } from '@lssm/lib.resilience/circuit-breaker';\nimport { traceAsync } from '@lssm/lib.observability/tracing';\n\nconst runner = new WorkflowRunner({\n  registry,\n  stateStore: new PrismaStateStore(db),\n  opExecutor: async (op, input, ctx) => {\n    return traceAsync(`op.${op.name}`, async (span) => {\n      span.setAttribute('operation', op.name);\n      const breaker = getCircuitBreaker(op.name);\n      return breaker.execute(() => executeOperation(op, input, ctx));\n    });\n  },\n  eventEmitter: (event, payload) => {\n    if (event.startsWith('workflow.')) {\n      logger.info(event, payload);\n    }\n  },\n});\n\nconst monitor = new SLAMonitor((event, payload) => {\n  logger.warn('SLA_BREACH', payload);\n  alertOps(payload);\n});\n\n// Start workflow\nconst workflowId = await runner.start('payment.flow', 1);\n\n// Monitor SLA\nconst state = await runner.getState(workflowId);\nconst spec = registry.get('payment.flow', 1);\nmonitor.check(state, spec!);\n```\n\n### Complete DataView with Observability\n\n```typescript\nimport { DataViewRenderer } from '@lssm/lib.design-system';\nimport { DataViewQueryGenerator } from '@lssm/lib.contracts/data-views/query-generator';\nimport { traceAsync } from '@lssm/lib.observability/tracing';\nimport { MyDataView } from './specs/users.data-view';\n\nexport function UserListPage() {\n  const [page, setPage] = useState(1);\n  const [users, setUsers] = useState([]);\n\n  const loadUsers = async () => {\n    return traceAsync('load_users', async (span) => {\n      const generator = new DataViewQueryGenerator(MyDataView);\n      const query = generator.generate({ pagination: { page, pageSize: 20 } });\n      \n      span.setAttribute('page', page);\n      const result = await api.execute(query);\n      setUsers(result.data);\n    });\n  };\n\n  return (\n    <DataViewRenderer\n      spec={MyDataView}\n      items={users}\n      pagination={{ page, pageSize: 20, total: users.length }}\n      onPageChange={setPage}\n    />\n  );\n}\n```\n\n### Complete Multi-Tenant Setup\n\n```typescript\n// 1. RLS Middleware\nimport { createRlsMiddleware } from '@lssm/lib.multi-tenancy/rls';\ndb.$use(createRlsMiddleware(() => req.tenantId));\n\n// 2. Tenant Provisioning\nimport { TenantProvisioningService } from '@lssm/lib.multi-tenancy/provisioning';\nconst service = new TenantProvisioningService({ db });\n\n// 3. Create new tenant\nawait service.provision({\n  id: 'acme',\n  name: 'Acme Corp',\n  slug: 'acme',\n  ownerEmail: 'admin@acme.com',\n});\n\n// 4. Validate isolation in tests\nimport { IsolationValidator } from '@lssm/lib.multi-tenancy/isolation';\n\ntest('queries are isolated', () => {\n  const isValid = IsolationValidator.validateQuery(\n    'User',\n    'findMany',\n    { where: { tenantId: 'acme' } },\n    'acme'\n  );\n  expect(isValid).toBe(true);\n});\n```\n\n---\n\n## Testing\n\n### Test Circuit Breakers\n\n```typescript\nimport { CircuitBreaker } from '@lssm/lib.resilience/circuit-breaker';\n\ntest('circuit opens after threshold', async () => {\n  const breaker = new CircuitBreaker({\n    failureThreshold: 3,\n    resetTimeoutMs: 5000,\n  });\n\n  // Trigger failures\n  for (let i = 0; i < 3; i++) {\n    await expect(\n      breaker.execute(() => Promise.reject('error'))\n    ).rejects.toThrow();\n  }\n\n  // Circuit should be open\n  await expect(\n    breaker.execute(() => Promise.resolve('ok'))\n  ).rejects.toThrow('CircuitBreaker is OPEN');\n});\n```\n\n### Test Workflow Retry\n\n```typescript\ntest('workflow retries on failure', async () => {\n  let attempts = 0;\n  const opExecutor = async () => {\n    attempts++;\n    if (attempts < 3) throw new Error('fail');\n    return 'success';\n  };\n\n  const runner = new WorkflowRunner({ /* ... */ opExecutor });\n  await runner.executeStep(workflowId);\n  \n  expect(attempts).toBe(3);\n});\n```\n\n---\n\n## Common Patterns\n\n### Pattern: Resilient External Call\n\n```typescript\nimport { CircuitBreaker } from '@lssm/lib.resilience/circuit-breaker';\nimport { retry } from '@lssm/lib.resilience/retry';\nimport { timeout } from '@lssm/lib.resilience/timeout';\nimport { traceAsync } from '@lssm/lib.observability/tracing';\n\nconst breaker = new CircuitBreaker({ failureThreshold: 5, resetTimeoutMs: 30000 });\n\nexport async function callExternalAPI(input: any) {\n  return traceAsync('external_api_call', async (span) => {\n    span.setAttribute('service', 'stripe');\n    \n    return breaker.execute(() =>\n      retry(\n        () => timeout(() => stripe.api.call(input), 5000),\n        3,\n        1000,\n        true\n      )\n    );\n  });\n}\n```\n\n**Benefits**: Circuit breaker + retry + timeout + tracing in one place.\n\n---\n\n### Pattern: Tenant-Aware Operation\n\n```typescript\nimport { traceAsync } from '@lssm/lib.observability/tracing';\n\nexport async function listUsers(tenantId: string) {\n  return traceAsync('list_users', async (span) => {\n    span.setAttribute('tenant_id', tenantId);\n    \n    // RLS middleware will inject WHERE tenantId = ?\n    return db.user.findMany();\n  });\n}\n```\n\n---\n\n### Pattern: Monitored Workflow\n\n```typescript\nimport { WorkflowRunner } from '@lssm/lib.contracts/workflow/runner';\nimport { SLAMonitor } from '@lssm/lib.contracts/workflow/sla-monitor';\nimport { logger } from '@lssm/lib.observability/logging';\n\nconst monitor = new SLAMonitor((event, payload) => {\n  logger.warn('workflow.sla_breach', payload);\n});\n\n// In workflow poller\nconst state = await runner.getState(workflowId);\nconst spec = registry.get(state.workflowName, state.workflowVersion);\nif (spec) {\n  monitor.check(state, spec);\n}\n```\n\n---\n\n## Next Steps\n\n1. **Implement one quick win** (30 minutes)\n2. **Add tests for new functionality** (1 hour)\n3. **Deploy to staging and verify observability** (1 hour)\n4. **Roll out to production** (monitor closely)\n5. **Read full documentation** at https://contractspec.lssm.tech/docs\n\n---\n\n**Questions?** See `/docs/guides/phase-1-migration` or reach out via https://contractspec.lssm.tech/contact\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"
-}];
-registerDocBlocks(tech_PHASE_1_QUICKSTART_DocBlocks);
-
-//#endregion

package/dist/libs/contracts/dist/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js

@@ -1,16 +0,0 @@
-import { registerDocBlocks } from "../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js
-const tech_PHASE_2_AI_NATIVE_OPERATIONS_DocBlocks = [{
-	id: "docs.tech.PHASE_2_AI_NATIVE_OPERATIONS",
-	title: "Phase 2: AI-Native Operations",
-	summary: "_Last updated: 2025-11-20_",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS",
-	tags: ["tech", "PHASE_2_AI_NATIVE_OPERATIONS"],
-	body: "# Phase 2: AI-Native Operations\n\n_Last updated: 2025-11-20_\n\nPhase 2 turns ContractSpec into an AI-first operations stack. The new libraries below are the building blocks used by support bots, growth agents, and human-in-the-loop flows.\n\n## Libraries\n\n### @lssm/lib.ai-agent\n\n- **Spec + Registry**: `defineAgent`, `AgentRegistry` keep agent definitions type-safe.\n- **Runner**: `AgentRunner` drives LLM conversations, tool calls, retries, escalation, and telemetry hooks.\n- **Tools**: `ToolExecutor` standardizes schema validation + timeouts.\n- **Memory**: `InMemoryAgentMemory` + interfaces for plugging persistent stores.\n- **Approvals**: new `ApprovalWorkflow` + `InMemoryApprovalStore` capture low-confidence decisions and surface them to reviewers.\n\n### @lssm/lib.support-bot\n\nComposable support automation primitives:\n\n- `TicketClassifier` → heuristics + optional LLM validation for category, priority, sentiment.\n- `TicketResolver` → RAG pipeline backed by knowledge spaces.\n- `AutoResponder` → tone-aware drafts with citations.\n- `SupportFeedbackLoop` → tracks resolution rates.\n- `createSupportTools` → ready-made tool definitions for AgentRunner.\n\n### @lssm/lib.content-gen\n\nContent generators that consume a `ContentBrief` and output production-ready assets:\n\n- `BlogGenerator`, `LandingPageGenerator`, `EmailCampaignGenerator`, `SocialPostGenerator`.\n- `SeoOptimizer` builds metadata + schema markup.\n\n### @lssm/lib.analytics\n\nQueryless analytics helpers:\n\n- `FunnelAnalyzer` – conversion/drop-off per step.\n- `CohortTracker` – retention + LTV per cohort.\n- `ChurnPredictor` – recency/frequency/error scoring.\n- `GrowthHypothesisGenerator` – surfaces experiment ideas from metric trends.\n\n### @lssm/lib.growth\n\nA/B testing toolkit:\n\n- `ExperimentRegistry` + `ExperimentRunner` – deterministic bucketing.\n- `ExperimentTracker` – persist exposures + metrics.\n- `StatsEngine` – Welch’s t-test + improvement calculations.\n\n### Human-in-the-loop UI\n\n`@lssm/lib.design-system` now exposes:\n\n- `ApprovalQueue` – list + act on pending approvals.\n- `AgentMonitor` – live view of agent sessions with confidence + status.\n\n## Examples\n\n- `examples/ai-support-bot/setup.ts` shows ticket classification → resolution → response draft.\n- `examples/content-generation/generate.ts` produces blog, landing, email, social, SEO output from one brief.\n\n## Next Steps\n\n1. Wire these libraries into vertical apps (H-Circle, ArtisanOS, etc.).\n2. Add background workers that consume the new analytics/growth trackers.\n3. Expand web-landing to highlight these Phase 2 capabilities (see separate TODO).\n"
-}];
-registerDocBlocks(tech_PHASE_2_AI_NATIVE_OPERATIONS_DocBlocks);
-
-//#endregion

package/dist/libs/contracts/dist/docs/tech/PHASE_3_AUTO_EVOLUTION.docblock.js

@@ -1,16 +0,0 @@
-import { registerDocBlocks } from "../registry.js";
-
-//#region ../../libs/contracts/dist/docs/tech/PHASE_3_AUTO_EVOLUTION.docblock.js
-const tech_PHASE_3_AUTO_EVOLUTION_DocBlocks = [{
-	id: "docs.tech.PHASE_3_AUTO_EVOLUTION",
-	title: "Phase 3: Auto-Evolution Technical Notes",
-	summary: "**Status**: In progress",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/tech/PHASE_3_AUTO_EVOLUTION",
-	tags: ["tech", "PHASE_3_AUTO_EVOLUTION"],
-	body: "# Phase 3: Auto-Evolution Technical Notes\n\n**Status**: In progress  \n**Last updated**: 2025-11-21  \n\nPhase 3 introduces self-learning capabilities that analyze production telemetry, suggest new specs, safely roll out variants, and generate golden tests from real traffic. This document captures the main building blocks delivered in this iteration.\n\n---\n\n## 1. Libraries\n\n### @lssm/lib.evolution\n\n- `SpecAnalyzer` converts raw telemetry samples into usage stats + anomalies.\n- `SpecGenerator` produces `SpecSuggestion` objects and validates confidence thresholds.\n- `SpecSuggestionOrchestrator` routes proposals through the AI approval workflow and writes approved specs to `packages/libs/contracts/src/generated`.\n- Storage adapters:\n  - `InMemorySpecSuggestionRepository` for tests.\n  - `PrismaSpecSuggestionRepository` persists to the new Prisma model (see §4).\n  - `FileSystemSuggestionWriter` emits JSON envelopes for git review.\n\n### @lssm/lib.observability\n\n- Added intent detection modules:\n  - `IntentAggregator` batches telemetry into rolling windows.\n  - `IntentDetector` surfaces latency/error/throughput regressions and sequential intents.\n- `EvolutionPipeline` orchestrates aggregation → detection → intent events and exposes hooks for downstream orchestrators.\n- `createTracingMiddleware` now accepts `resolveOperation`/`onSample` hooks to feed telemetry samples into the pipeline.\n\n### @lssm/lib.growth\n\n- New `spec-experiments` module:\n  - `SpecExperimentRegistry`, `SpecExperimentRunner`, `SpecExperimentAdapter`.\n  - `SpecExperimentAnalyzer` + `SpecExperimentController` handle guardrails and staged rollouts.\n  - Helper `createSpecVariantResolver` plugs directly into `HandlerCtx.specVariantResolver`.\n- `SpecVariantResolver` is now a first-class concept in `@lssm/lib.contracts`. The runtime will attempt to execute variant specs before falling back to the registered handler.\n\n### @lssm/lib.testing\n\n- `TrafficRecorder` + `TrafficStore` capture production requests with sampling and sanitization hooks.\n- `GoldenTestGenerator` converts `TrafficSnapshot`s into Vitest/Jest suites.\n- `generateVitestSuite` / `generateJestSuite` output self-contained test files, and `runGoldenTests` offers a programmatic harness for CI pipelines.\n\n---\n\n## 2. Telemetry → Intent → Spec Pipeline\n\n1. `createTracingMiddleware({ onSample })` emits `TelemetrySample`s for every HTTP request.\n2. `IntentAggregator` groups samples into statistical windows (default 15 minutes).\n3. `IntentDetector` raises signals for:\n   - Error spikes\n   - Latency regressions\n   - Throughput drops\n   - Sequential workflows that hint at missing specs\n4. `EvolutionPipeline` emits `intent.detected` events and hands them to `SpecGenerator`.\n5. `SpecSuggestionOrchestrator` persists suggestions, triggers approval workflows, and—upon approval—writes JSON envelopes to `packages/.../contracts/src/generated`.\n\n---\n\n## 3. Spec Experiments & Rollouts\n\n1. Register spec experiments in `SpecExperimentRegistry` with control + variant bindings.\n2. Expose bucketed specs by attaching `createSpecVariantResolver` to `HandlerCtx.specVariantResolver` inside adapters.\n3. Record outcomes via `SpecExperimentAdapter.trackOutcome()` (latency + error metrics).\n4. `SpecExperimentController` uses guardrails from config and `SpecExperimentAnalyzer` to:\n   - Auto-rollback on error/latency breaches.\n   - Advance rollout stages (1% → 10% → 50% → 100%) when metrics stay green.\n\n---\n\n## 4. Data Models (Prisma)\n\nFile: `packages/libs/database/prisma/schema.prisma`\n\n- `SpecSuggestion` – stores serialized suggestion payloads + statuses.\n- `IntentSnapshot` – captured detector output for auditing/training.\n- `TrafficSnapshot` – persisted production traffic (input/output/error blobs).\n- `SpecExperiment` / `SpecExperimentMetric` – rollout state + metrics for each variant.\n\n> Run `bun database generate` after pulling to refresh the Prisma client.\n\n---\n\n## 5. Golden Test Workflow\n\n1. Capture traffic via middleware or direct `TrafficRecorder.record`.\n2. Use the new CLI command to materialize suites:\n\n```bash\ncontractspec test generate \\\n  --operation billing.createInvoice \\\n  --output tests/billing.createInvoice.golden.test.ts \\\n  --runner-import ./tests/run-operation \\\n  --runner-fn runBillingCommand \\\n  --from-production \\\n  --days 7 \\\n  --sample-rate 0.05\n```\n\n3. Generated files import your runner and assert against recorded outputs (or expected errors for negative paths).\n\n---\n\n## 6. Operational Notes\n\n- **Approvals**: By default, every suggestion still requires human approval. `EvolutionConfig.autoApproveThreshold` can be tuned per environment but should remain conservative (<0.3) until OverlaySpec tooling lands.\n- **Sampling**: Keep `TrafficRecorder.sampleRate` ≤ 0.05 in production to avoid sensitive payload storage; scrub PII through the `sanitize` callback before persistence.\n- **Rollouts**: Guardrails default to 5% error-rate and 750ms P99 latency. Override per experiment to match SLOs.\n\n---\n\n## 7. Next Steps\n\n1. Wire `SpecExperimentAdapter.trackOutcome` into adapters (REST, GraphQL, Workers) so every execution logs metrics automatically.\n2. Add a UI for reviewing `SpecSuggestion` objects alongside approval status.\n3. Expand `TrafficRecorder` to ship directly to the Prisma-backed store (currently in-memory by default).\n4. Integrate `EvolutionPipeline` events with the Regenerator to close the loop (auto-open proposals + attach evidence).\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"
-}];
-registerDocBlocks(tech_PHASE_3_AUTO_EVOLUTION_DocBlocks);
-
-//#endregion

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

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

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

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