@contractspec/lib.contracts 1.44.0

package/dist/data-views/types.d.ts

@@ -0,0 +1,157 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { EventRef, OpRef, PresentationRef } from "../features/types.js";
+import "../features/index.js";
+
+//#region src/data-views/types.d.ts
+/**
+ * Supported data view kinds.
+ */
+type DataViewKind = 'list' | 'detail' | 'table' | 'grid';
+/**
+ * Metadata for a data view spec.
+ */
+interface DataViewMeta extends OwnerShipMeta {
+  /** Canonical entity slug (e.g., "space", "resident"). */
+  entity: string;
+}
+/**
+ * Source configuration for fetching data in a data view.
+ */
+interface DataViewSource {
+  /** Primary query used to fetch items for this view. */
+  primary: OpRef;
+  /** Optional operation used to fetch a single item (detail views). */
+  item?: OpRef;
+  /** Optional record mutation operations (used for inline editing or actions). */
+  mutations?: {
+    create?: OpRef;
+    update?: OpRef;
+    delete?: OpRef;
+  };
+  /** Events that should trigger refresh when emitted. */
+  refreshEvents?: EventRef[];
+}
+/**
+ * Display formatting hints for data view fields.
+ */
+type DataViewFieldFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'dateTime' | 'boolean' | 'badge';
+/**
+ * Field definition within a data view.
+ */
+interface DataViewField {
+  /** Unique identifier for the field within the view. */
+  key: string;
+  /** Human-friendly label for headers/tooltips. */
+  label: string;
+  /** Dot-path into the data item (e.g., "address.city"). */
+  dataPath: string;
+  /** Optional description surfaced in tooltips or docs. */
+  description?: string;
+  /** Optional formatting hint for renderers. */
+  format?: DataViewFieldFormat;
+  /** When true, the field can be used for sorting. */
+  sortable?: boolean;
+  /** When true, the field can be used for filtering. */
+  filterable?: boolean;
+  /** Optional width hint for table layouts. */
+  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+  /** Optional presentation override (e.g., card component). */
+  presentation?: PresentationRef;
+}
+/**
+ * Filter definition for a data view.
+ */
+interface DataViewFilter {
+  key: string;
+  label: string;
+  field: string;
+  type: 'search' | 'enum' | 'number' | 'date' | 'boolean';
+  options?: {
+    value: string;
+    label: string;
+  }[];
+}
+/**
+ * Action that can be triggered from a data view.
+ */
+interface DataViewAction {
+  key: string;
+  label: string;
+  kind: 'navigation' | 'operation';
+  /** Operation invoked when kind === 'operation'. */
+  operation?: OpRef;
+  /** Optional feature flag gating the action. */
+  requiresFlag?: string;
+}
+/**
+ * Section configuration for detail views.
+ */
+interface DataViewSections {
+  title?: string;
+  description?: string;
+  fields: string[];
+}
+/**
+ * Base configuration shared by all data view kinds.
+ */
+interface DataViewBaseConfig {
+  kind: DataViewKind;
+  fields: DataViewField[];
+  primaryField?: string;
+  secondaryFields?: string[];
+  filters?: DataViewFilter[];
+  actions?: DataViewAction[];
+}
+/**
+ * List view configuration.
+ */
+interface DataViewListConfig extends DataViewBaseConfig {
+  kind: 'list';
+  layout?: 'card' | 'compact';
+}
+/**
+ * Detail view configuration.
+ */
+interface DataViewDetailConfig extends DataViewBaseConfig {
+  kind: 'detail';
+  sections?: DataViewSections[];
+}
+/**
+ * Table column configuration.
+ */
+interface DataViewTableColumn {
+  field: string;
+  label?: string;
+  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+  align?: 'left' | 'center' | 'right';
+}
+/**
+ * Table view configuration.
+ */
+interface DataViewTableConfig extends DataViewBaseConfig {
+  kind: 'table';
+  columns?: DataViewTableColumn[];
+  rowSelectable?: boolean;
+  density?: 'comfortable' | 'compact';
+}
+/**
+ * Grid view configuration.
+ */
+interface DataViewGridConfig extends DataViewBaseConfig {
+  kind: 'grid';
+  columns?: number;
+}
+/**
+ * Union of all data view configurations.
+ */
+type DataViewConfig = DataViewListConfig | DataViewDetailConfig | DataViewTableConfig | DataViewGridConfig;
+/**
+ * Presentation references for different view states.
+ */
+interface DataViewStates {
+  empty?: PresentationRef;
+  error?: PresentationRef;
+  loading?: PresentationRef;
+}
+//#endregion
+export { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewSections, DataViewSource, DataViewStates, DataViewTableColumn, DataViewTableConfig };

package/dist/docs/accessibility_wcag_compliance_specs.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/accessibility_wcag_compliance_specs.docblock.d.ts
+declare const accessibility_wcag_compliance_specs_DocBlocks: DocBlock[];
+//#endregion
+export { accessibility_wcag_compliance_specs_DocBlocks };

package/dist/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -0,0 +1,17 @@
+import { registerDocBlocks } from "./registry.js";
+
+//#region src/docs/accessibility_wcag_compliance_specs.docblock.ts
+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 `@contractspec/lib.accessibility` at app root. It auto-imports its `styles.css` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:\n\n```tsx\n// app/layout.tsx\nimport '@contractspec/lib.accessibility'; // includes tokens and provider exports\n// or if needed: import '@contractspec/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
+export { accessibility_wcag_compliance_specs_DocBlocks };

package/dist/docs/index.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock, DocBlockLink, DocKind, DocVisibility } from "./types.js";
+import { DocPresentationOptions, DocPresentationRoute, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes } from "./presentations.js";
+import { DocId, DocRegistry, defaultDocRegistry, docId, listRegisteredDocBlocks, registerDocBlocks } from "./registry.js";
+import { techContractsDocs } from "./tech-contracts.docs.js";
+import { metaDocs } from "./meta.docs.js";
+export { DocBlock, DocBlockLink, DocId, DocKind, DocPresentationOptions, DocPresentationRoute, DocRegistry, DocVisibility, defaultDocRegistry, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };

package/dist/docs/index.js

@@ -0,0 +1,29 @@
+import { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes } from "./presentations.js";
+import { DocRegistry, defaultDocRegistry, docId, listRegisteredDocBlocks, registerDocBlocks } from "./registry.js";
+import { techContractsDocs } from "./tech-contracts.docs.js";
+import { metaDocs } from "./meta.docs.js";
+import "./accessibility_wcag_compliance_specs.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 "../workflow/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/contracts/openapi-import.docblock.js";
+import "../workspace-config/workspace-config.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";
+
+export { DocRegistry, defaultDocRegistry, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };

package/dist/docs/meta.docs.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "./types.js";
+
+//#region src/docs/meta.docs.d.ts
+declare const metaDocs: DocBlock[];
+//#endregion
+export { metaDocs };

package/dist/docs/meta.docs.js

@@ -0,0 +1,29 @@
+import { registerDocBlocks } from "./registry.js";
+
+//#region src/docs/meta.docs.ts
+const metaDocs = [{
+	id: "docs.meta.docblocks-process",
+	title: "DocBlocks process",
+	summary: "How to author goal/how/usage DocBlocks close to code.",
+	kind: "reference",
+	visibility: "mixed",
+	route: "/docs/meta/docblocks-process",
+	tags: ["docs", "process"],
+	body: `## DocBlocks authoring rules
+
+- Colocate docs beside implementation; avoid barrel /docs folders.
+- Split intent:
+  - **goal**: why this exists (before implementation).
+  - **how**: operational/runbook steps.
+  - **usage**: quick checklist for consumers.
+- Use \`visibility\`: public | internal | mixed.
+- Prefer routes like \`/docs/<domain>/<topic>/<kind>\`; ids mirror that.
+- Keep body Markdown LLM-friendly; avoid HTML.
+- Add owners/tags/domain/stability when known.
+- For presentations/markdown outputs, rely on TransformEngine via DocRegistry.
+- No sourcePath; DocBlocks are canonical.`
+}];
+registerDocBlocks(metaDocs);
+
+//#endregion
+export { metaDocs };

package/dist/docs/presentations.d.ts

@@ -0,0 +1,33 @@
+import { DocBlock } from "./types.js";
+import { PresentationSpec, PresentationTarget } from "../presentations/presentations.js";
+import { Stability } from "../ownership.js";
+
+//#region src/docs/presentations.d.ts
+interface DocPresentationOptions {
+  /**
+   * Namespace for presentation meta.key (e.g., web-landing.docs.ops).
+   * Defaults to the DocBlock id.
+   */
+  namespace?: string;
+  /** Route prefix when no explicit route is provided on the block. Defaults to /docs. */
+  routePrefix?: string;
+  /** Default presentation targets. */
+  defaultTargets?: PresentationTarget[];
+  /** Default version when block.version is not set. */
+  defaultVersion?: number;
+  /** Default stability if not provided on the DocBlock. */
+  defaultStability?: Stability;
+}
+interface DocPresentationRoute {
+  route: string;
+  descriptor: PresentationSpec;
+  block: DocBlock;
+}
+declare function docBlockToPresentationSpec(block: DocBlock, options?: DocPresentationOptions): PresentationSpec;
+/** @deprecated Use docBlockToPresentationSpec instead */
+declare const docBlockToPresentationV2: typeof docBlockToPresentationSpec;
+declare function docBlocksToPresentationRoutes(blocks: DocBlock[], options?: DocPresentationOptions): DocPresentationRoute[];
+declare function docBlocksToPresentationSpecs(blocks: DocBlock[], options?: DocPresentationOptions): PresentationSpec[];
+declare function mapDocRoutes(routes: DocPresentationRoute[]): [string, PresentationSpec][];
+//#endregion
+export { DocPresentationOptions, DocPresentationRoute, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes };

package/dist/docs/presentations.js

@@ -0,0 +1,64 @@
+//#region src/docs/presentations.ts
+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 docBlockToPresentationSpec(block, options) {
+	const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+	const version = block.version ?? options?.defaultVersion ?? 1;
+	const stability = block.stability ?? options?.defaultStability ?? "stable";
+	return {
+		meta: {
+			key: buildName(block, options?.namespace),
+			title: block.title,
+			version,
+			description: block.summary ?? block.title,
+			tags: block.tags || [],
+			owners: block.owners || [],
+			domain: block.domain || "",
+			stability,
+			goal: `Documentation of: ${block.summary}`,
+			context: `Auto-generated`
+		},
+		policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : void 0,
+		source: {
+			type: "blocknotejs",
+			docJson: block.body
+		},
+		targets
+	};
+}
+/** @deprecated Use docBlockToPresentationSpec instead */
+const docBlockToPresentationV2 = docBlockToPresentationSpec;
+function docBlocksToPresentationRoutes(blocks, options) {
+	return blocks.map((block) => ({
+		block,
+		route: deriveRoute(block, options?.routePrefix),
+		descriptor: docBlockToPresentationSpec(block, options)
+	}));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+	return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+	return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+//#endregion
+export { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes };

package/dist/docs/registry.d.ts

@@ -0,0 +1,23 @@
+import { DocBlock } from "./types.js";
+import { PresentationSpec } from "../presentations/presentations.js";
+import { DocPresentationOptions, DocPresentationRoute } from "./presentations.js";
+
+//#region src/docs/registry.d.ts
+type DocId = string & {
+  __docId: true;
+};
+declare class DocRegistry {
+  private readonly routes;
+  constructor(blocks?: DocBlock[], options?: DocPresentationOptions);
+  register(block: DocBlock, options?: DocPresentationOptions): this;
+  list(): DocPresentationRoute[];
+  get(id: string): DocPresentationRoute | undefined;
+  toRouteTuples(): [string, PresentationSpec][];
+  toPresentationSpecs(options?: DocPresentationOptions): PresentationSpec[];
+}
+declare const defaultDocRegistry: DocRegistry;
+declare function registerDocBlocks(blocks: DocBlock[]): void;
+declare function listRegisteredDocBlocks(): DocBlock[];
+declare function docId(id: string): DocId;
+//#endregion
+export { DocId, DocRegistry, defaultDocRegistry, docId, listRegisteredDocBlocks, registerDocBlocks };

package/dist/docs/registry.js

@@ -0,0 +1,51 @@
+import { docBlockToPresentationSpec, docBlocksToPresentationRoutes } from "./presentations.js";
+
+//#region src/docs/registry.ts
+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);
+	}
+}
+function listRegisteredDocBlocks() {
+	return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+	if (!defaultDocRegistry.get(id)) throw new Error(`DocBlock not registered: ${id}`);
+	return id;
+}
+
+//#endregion
+export { DocRegistry, defaultDocRegistry, docId, listRegisteredDocBlocks, registerDocBlocks };

package/dist/docs/tech/auth/better-auth-nextjs.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/auth/better-auth-nextjs.docblock.d.ts
+declare const tech_auth_better_auth_nextjs_DocBlocks: DocBlock[];
+//#endregion
+export { tech_auth_better_auth_nextjs_DocBlocks };

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

@@ -0,0 +1,81 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/auth/better-auth-nextjs.docblock.ts
+const tech_auth_better_auth_nextjs_DocBlocks = [{
+	id: "docs.tech.auth.better-auth-nextjs",
+	title: "Better Auth + Next.js integration (ContractSpec)",
+	summary: "How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/auth/better-auth-nextjs",
+	tags: [
+		"auth",
+		"better-auth",
+		"nextjs",
+		"cookies",
+		"proxy",
+		"hmr"
+	],
+	body: `# Better Auth + Next.js integration (ContractSpec)
+
+This repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).
+
+## Server config (Better Auth)
+
+- Source: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Important: \`nextCookies()\` must be the **last** plugin in the Better Auth plugin list so \`Set-Cookie\` is applied correctly in Next.js environments.
+
+## Better Auth Admin plugin
+
+ContractSpec Studio enables the Better Auth **Admin plugin** to support platform-admin user operations (list users, impersonation, etc.).
+
+- Server: \`admin()\` plugin in \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Client: \`adminClient()\` in \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+
+### PLATFORM_ADMIN ⇒ Better Auth admin role
+
+Better Auth Admin endpoints authorize via \`user.role\`. ContractSpec enforces an org-driven rule:
+
+- If the **active organization** has \`type = PLATFORM_ADMIN\`, the signed-in user is ensured to have \`User.role\` containing \`admin\`.
+- This is applied in the session creation hook and re-checked in \`assertsPlatformAdmin()\`.
+
+This keeps admin enablement deterministic and avoids manual role backfills.
+
+## Client config (React web + Expo)
+
+To avoid duplicate background refresh/polling loops in dev (Fast Refresh/HMR), the Better Auth client is implemented as a singleton cached on \`globalThis\`.
+
+- Web client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+- Native client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.native.ts\`
+
+Import guidance:
+
+- If you only need the context/hook, prefer importing from \`@contractspec/bundle.studio/presentation/providers/auth\`.
+- If you explicitly need the Better Auth client instance (e.g. admin impersonation, direct API calls), import from \`@contractspec/bundle.studio/presentation/providers/auth/client\`.
+
+## Public routes (login / signup)
+
+Public auth pages should avoid eager \`authClient\` initialization.
+
+Pattern used:
+
+- In the submit handler, dynamically import \`@contractspec/bundle.studio/presentation/providers/auth/index.web\` and call \`authClient.signIn.*\` / \`authClient.signUp.*\`.
+
+This prevents session refresh behavior from starting just because a public page rendered.
+
+## Next.js proxy auth (web-landing)
+
+The Next.js proxy/middleware is used for **redirect decisions only**. It must not perform DB-backed session reads on every request.
+
+- Source: \`packages/apps/web-landing/src/proxy.ts\`
+- Approach: cookie-only checks via Better Auth cookies helpers:
+  - \`getSessionCookie(request)\`
+  - \`getCookieCache(request)\`
+
+These checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.
+`
+}];
+registerDocBlocks(tech_auth_better_auth_nextjs_DocBlocks);
+
+//#endregion
+export { tech_auth_better_auth_nextjs_DocBlocks };

package/dist/docs/tech/contracts/README.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/README.docblock.d.ts
+declare const tech_contracts_README_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_README_DocBlocks };

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

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

package/dist/docs/tech/contracts/create-subscription.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/create-subscription.docblock.d.ts
+declare const tech_contracts_create_subscription_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_create_subscription_DocBlocks };

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

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