@nexalink/carecompass-sdk 0.3.0-beta.15 → 0.5.0

package/README.md

@@ -1,141 +1,358 @@
-# CareCompass Healthcare AI Infrastructure SDK
+# CareCompass SDK
 
-CareCompass helps healthcare teams launch branded healthcare navigation assistants, member support assistants, and patient-facing AI experiences inside their own portals or applications. The SDK combines an embeddable chat experience with Nexalink-hosted healthcare AI infrastructure, reducing the implementation effort required to move from idea to deployable healthcare navigation workflow.
+CareCompass is embeddable healthcare AI infrastructure for teams building AI-powered healthcare products.
 
-The SDK is publicly installable for developer convenience, but live regulated use requires Nexalink onboarding, issued credentials, and BAA coverage where PHI may be involved. CareCompass is designed for healthcare navigation and support workflows. It is not a general-purpose LLM SDK, not a medical diagnosis tool, not autonomous treatment recommendation software, and not a replacement for clinicians or clinical judgment.
+It gives healthcare companies a secure SDK and hosted runtime for adding LLM-powered experiences to their own applications without building the regulated AI stack from scratch: model routing, tenant-aware runtime APIs, browser-safe authentication, prompt controls, guardrails, origin validation, deployment checks, and healthcare-specific onboarding.
 
-## Who It's For
+CareCompass is for teams that want to ship their own AI product experience while relying on Nexalink to operate the healthcare AI infrastructure layer underneath.
 
-- Healthcare startups building AI-powered patient experiences
-- Payer innovation and member engagement teams
-- Employer-benefits platforms
-- Provider organizations adding patient-facing support workflows
-- Digital health engineering teams
-- Healthcare product teams that need AI infrastructure quickly
+The SDK gives teams two integration paths:
 
-## Why Teams Use CareCompass
+- **Headless core** for product teams that want full control over their own UI, workflow, state management, and rendering.
+- **Optional UI kit** for teams that want a fast, branded AI chat experience they can drop into a web app and customize over time.
 
-- **Faster deployment**: add a healthcare-focused AI assistant to an existing healthcare product without months of infrastructure work.
-- **Reduced engineering effort**: avoid building and operating the supporting healthcare AI infrastructure around the assistant.
-- **Hosted healthcare AI runtime**: chat requests route through Nexalink-hosted APIs and the CareCompass AI runtime.
-- **Embedded branded experience**: use the React component, JavaScript mount helper, generated embed page, or iframe with your display name, labels, theme, logo, and support links.
-- **Prompt and configuration controls**: define approved prompt context, welcome copy, placement, allowed origins, and deployment environment.
-- **Deployment controls**: use key management, origin allowlists, hosted validation, and staging/production credential separation.
-- **Enterprise onboarding**: support BAA-gated onboarding where PHI may be involved.
+CareCompass is not a diagnosis tool, autonomous treatment product, replacement for clinicians, or general-purpose LLM SDK. It is healthcare AI infrastructure for building compliance-oriented, embedded AI workflows.
 
-## Why Not Build It Yourself?
+## Why Teams Choose CareCompass
 
-Most healthcare teams can access foundation models through OpenAI, Anthropic, Bedrock, Azure OpenAI, or similar providers. The harder work is not obtaining an LLM. The harder work is building and operating the healthcare AI infrastructure around it:
+Healthcare teams can already access foundation models. The hard part is turning those models into production-ready healthcare software.
 
-- Healthcare-focused prompts and guardrails
-- Hosted inference infrastructure
-- Tenant isolation
-- Key management
-- Deployment validation
-- Browser embedding
-- Usage tracking
-- Compliance-oriented onboarding
+CareCompass packages the healthcare-specific infrastructure layer that most teams would otherwise need to build themselves:
 
-CareCompass provides a managed healthcare AI infrastructure layer for these workflows, while keeping the embedded experience configurable for your application and brand.
+- secure hosted runtime APIs
+- tenant and environment routing
+- browser-safe embed authentication
+- origin allowlist validation
+- prompt and configuration controls
+- guardrails for regulated workflows
+- deployment readiness checks
+- white-label UI support
+- operational onboarding for healthcare use cases
+
+Instead of spending months building LLM infrastructure, product teams can use CareCompass to embed AI into their own application and focus on the workflow, customer experience, and clinical or operational use case they are trying to ship.
+
+## What You Can Build
+
+CareCompass can power healthcare AI features inside products such as:
+
+- clinical workflow copilots
+- patient engagement assistants
+- care navigation and resource guidance flows
+- benefits or plan guidance experiences
+- RCM and prior authorization support tools
+- onboarding and support flows for digital health products
+- internal operations copilots for healthcare teams
+- white-labeled AI assistants inside existing healthcare applications
+
+CareCompass is intentionally workflow-agnostic at the infrastructure layer. The customer owns the product experience; CareCompass provides the SDK, runtime, guardrails, and deployment model needed to make healthcare AI usable in production.
 
 ## What You Avoid Building
 
-- Model gateway
-- Chat embed
-- Prompt validation layer
-- Tenant and key management
-- Usage tracking
-- Hosted inference path
-- Staging and production credential separation
-- Deployment validation tooling
+CareCompass handles infrastructure that healthcare AI teams usually need before they can safely ship:
+
+- Hosted inference gateway
+- Tenant-aware runtime APIs
+- Browser-safe embed authentication model
+- Tenant and environment routing
+- Origin allowlist validation
+- Prompt and configuration validation
+- Guardrail enforcement
+- Streaming and retry lifecycle state
+- Default chat UI and iframe setup assets
+- Deployment readiness tooling
+- Anonymous deployment-health telemetry
 - Compliance-oriented onboarding workflow
 
-## What You Can Build
+## SDK Architecture
 
-- Member support assistants
-- Benefits navigation assistants
-- Provider discovery support flows
-- Employer healthcare navigation portals
-- Payer member engagement tools
-- Digital health support chat experiences
+```text
+Your product UI
+  |
+  | uses either
+  |-- CareCompass headless core
+  |-- CareCompass UI kit
+  |
+CareCompass SDK
+  |
+Nexalink-hosted CareCompass APIs
+  |
+CareCompass AI runtime
+```
 
-## Example Questions CareCompass Can Help With
+The browser receives only public embed configuration: tenant identifier, environment, public embed key, allowed origins, endpoint, model preferences, feature flags, branding, labels, theme, placement, compliance, and approved prompt settings.
 
-CareCompass is intended for healthcare navigation and support, not diagnosis or treatment recommendations. Example navigation questions include:
+Secret API keys stay in CLI, server-side, or trusted setup workflows. The browser never receives model credentials or Nexalink API keys.
 
-- "How do I find an in-network cardiologist?"
-- "What does my deductible mean?"
-- "How do I schedule a specialist appointment?"
-- "Where can I find behavioral health resources?"
-- "What support resources are available through my plan?"
+## Integration Options
 
-## What CareCompass Is Not
+### 1. Headless Core
 
-- Not a general-purpose LLM SDK
-- Not a diagnosis tool
-- Not a replacement for clinical judgment
-- Not autonomous treatment recommendation software
+Use the headless core when your team already has a product surface and wants CareCompass to own the AI runtime lifecycle, not the UI.
 
-## Quick Start
+The core manages:
 
-Account creation and credentials are required because CareCompass is healthcare AI infrastructure for regulated deployment workflows, not an unauthenticated demo widget. The CLI requires Node.js 18 or newer.
+- message submission
+- poll-backed streaming lifecycle events
+- conversation snapshots
+- loading, error, timeout, and retry state
+- context injection
+- subscriptions for custom renderers
+- PHI preflight, safety callbacks, and metadata-only audit trails
+- endpoint calls and telemetry integration
 
-```bash
-npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
-npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
-npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
+```ts
+import { createCareCompassCore } from "@nexalink/carecompass-sdk/core";
+import config from "./carecompass/carecompass.config.json";
+
+const careCompass = createCareCompassCore(config, {
+  initialContext: {
+    userId: "user_123",
+    organizationId: "acme-health",
+  },
+});
+
+const unsubscribe = careCompass.subscribe((snapshot) => {
+  renderMessages(snapshot.messages);
+  renderLoading(snapshot.loading);
+  renderError(snapshot.error);
+});
+
+for await (const event of careCompass.streamMessage(
+  "Help me understand the next step in this workflow.",
+  { context: { workflow: "patient-onboarding" } },
+)) {
+  console.log(event.type);
+}
+
+unsubscribe();
+careCompass.dispose();
 ```
 
-`init` validates your Nexalink API key, stores it locally, and generates:
+The streaming API is lifecycle streaming over the existing CareCompass endpoint flow. It exposes submitted, status, completion, and error events so your UI can respond immediately while the hosted runtime works. It is not token-by-token model streaming.
 
-- `carecompass/carecompass.config.json`
-- `carecompass/system-prompt.md`
-- `carecompass/carecompass-embed.html`
-- `carecompass/carecompass-iframe.html`
-- `carecompass/README.md`
+### 2. Optional React UI Kit
 
-`npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package.
+Use the UI kit when you want a fast branded AI interface with minimal setup.
 
-## How It Works
+```tsx
+import { CareCompassChat } from "@nexalink/carecompass-sdk/ui";
+import config from "./carecompass/carecompass.config.json";
 
-```text
-Your Application
-  ↓
-CareCompass SDK
-  ↓
-Nexalink Hosted APIs
-  ↓
-CareCompass AI Runtime
+export function HealthcareAssistant() {
+  return (
+    <CareCompassChat
+      config={config}
+      initialContext={{ userId: "user_123" }}
+      renderMessage={(message) => (
+        <p data-role={message.role}>{message.text}</p>
+      )}
+      retryLabel="Try again"
+      onEvent={(event) => console.log(event.type)}
+    />
+  );
+}
+```
+
+The UI kit includes:
+
+- branded header, labels, disclaimer, and theme support
+- loading, error, and retry states
+- default assistant markdown rendering for headings, bold text, lists, rules, and tables
+- safe text rendering without raw HTML injection
+- `renderMessage` escape hatch for teams that want complete message-render control
+- compatibility with existing `CareCompassEmbed` and `mountCareCompass` integrations
+
+Custom message rendering:
+
+```tsx
+<CareCompassChat
+  config={config}
+  renderMessage={(message) => (
+    <MessageBubble role={message.role}>{message.text}</MessageBubble>
+  )}
+/>
+```
+
+### RCM coding-assistance pilot workflow
+
+The RCM kit is a narrow, structured coding-review workflow built on the same
+headless core, compliance preflight, and metadata-only audit events. It returns
+candidate codes for qualified human review; it never makes a final coding,
+billing, claim-submission, diagnosis, or treatment decision.
+
+The SDK sends `workflow: "rcm-coding-assistance"` as an explicit top-level ask
+field. The hosted runtime authorizes the workflow from the issued embed key and
+server-side tenant entitlement. Values in user context do not authorize a
+workflow.
+
+For the hosted RCM path, configure the tenant's RCM policy corpus in the
+CareCompass tenant portal before embedding: an authorized administrator must
+have an executed BAA, enable the RCM entitlement, set up the corpus, upload a
+customer-owned policy version, explicitly approve it, and wait for ingestion to
+become active. The browser sends structured encounter context only; it never
+sends a corpus ID, policy text, or policy references.
+
+```tsx
+import {
+  CARECOMPASS_RCM_SYNTHETIC_DEMO,
+  RcmCodingAssistant,
+} from "@nexalink/carecompass-sdk/rcm";
+
+<RcmCodingAssistant
+  config={config}
+  initialInput={CARECOMPASS_RCM_SYNTHETIC_DEMO}
+  workflowOptions={{
+    customerRules: { requirePolicySupport: true },
+    retrieval: "hosted",
+  }}
+  onAuditEvent={(event) => hostAudit(event)}
+  onSafetyEvent={(event) => hostSafetyMonitor(event)}
+/>;
+```
+
+The included demo input is synthetic and contains no patient data. Use it only
+with synthetic, approved policy material during development. The package
+includes [`DEMO-ENC-1042-rcm-policy.md`](qa-fixtures/DEMO-ENC-1042-rcm-policy.md)
+for the matching demo. Upload that file through **RCM policy corpus**, give it
+the `2026.1-demo` version, explicitly approve it, and wait for ingestion before
+submitting `CARECOMPASS_RCM_SYNTHETIC_DEMO`. It is deliberately not a real payer
+policy or coding manual.
+
+A production tenant must have an executed BAA, an RCM entitlement, and a
+healthy active corpus; otherwise the hosted workflow fails closed with a
+structured human-review escalation.
+
+In hosted mode, the result's `policyReferences` are the sanitized citations
+resolved by the runtime. Render those citations alongside a coder-review
+suggestion. A `review_required` result requires policy support; empty retrieval,
+invalid citations, guardrail intervention, or invalid JSON becomes an
+`abstain`/`escalate` result with no recommendations. Hosts receive the normal
+metadata-only audit and safety events, including authorization, retrieval,
+validation, and escalation outcomes.
+
+For a customer-managed trusted retrieval boundary, pass an `RcmPolicyRetriever`
+instead of `"hosted"`. Its `approvedCorpusIds` allowlist is enforced by the SDK;
+unapproved or missing references produce a human-review escalation.
+
+To evaluate the pilot, compare **manual research minutes per case** before and
+after assisted, human-reviewed use. The target is to measure a 25% or greater
+reduction, not to make or submit a coding decision.
+
+### 3. React Hook
+
+Use `useCareCompass` when your React app needs its own visual design but does
+not want to manage subscriptions, retries, or teardown by hand.
+
+```tsx
+import { useCareCompass } from "@nexalink/carecompass-sdk/react";
+import config from "./carecompass/carecompass.config.json";
+
+export function CareCompassPanel() {
+  const { snapshot, sendMessage, retryLast } = useCareCompass(config, {
+    initialContext: { workflow: "member-portal" },
+    onSafetyEvent: (event) => monitorSafety(event),
+  });
+
+  return (
+    <section>
+      {snapshot.messages.map((message) => (
+        <p key={message.id}>{message.text}</p>
+      ))}
+      <button
+        disabled={snapshot.loading}
+        onClick={() => void sendMessage("Find an in-network doctor")}
+      >
+        Find care
+      </button>
+      {snapshot.canRetry && (
+        <button onClick={() => void retryLast()}>Retry</button>
+      )}
+    </section>
+  );
+}
+```
+
+The hook returns the underlying `core` for audit export, safety/audit
+subscriptions, tool/widget events, and the lifecycle `streamMessage` API.
+
+### 4. Web Component (Vue-compatible)
+
+The Web Component is rendered directly from the headless core and exposes a
+standard custom-element property, making it a good fit for Vue, Angular, CMS
+shells, and mixed-framework pages without requiring a React runtime. Register
+it only in the browser.
+
+```ts
+import { defineCareCompassElement } from "@nexalink/carecompass-sdk/web-component";
+
+defineCareCompassElement();
 ```
 
-Your application renders the CareCompass UI through the SDK. The browser receives only public embed configuration: payer ID, environment, public embed key, branding, labels, theme, support links, approved prompt settings, placement, and telemetry defaults. The browser does not receive the secret API key, private model endpoint details, SageMaker credentials, AppSync signing roles, or Nexalink server-side allowlists.
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from "vue";
+import { defineCareCompassElement } from "@nexalink/carecompass-sdk/web-component";
+import config from "./carecompass/carecompass.config.json";
+
+const chat = ref<HTMLElement & { config?: typeof config }>();
+onMounted(() => {
+  defineCareCompassElement();
+  if (chat.value) chat.value.config = config;
+});
+</script>
+
+<template><carecompass-chat ref="chat" /></template>
+```
+
+For static hosts, the element also accepts a JSON `config` attribute. Prefer the
+property assignment above in application code: it avoids HTML escaping and keeps
+the configuration in your typed build pipeline.
+
+### 5. Script-tag Quickstart
+
+The existing `mountCareCompass` path remains supported for quick static pages
+and CMS integrations. Generate a script snippet from the same config:
+
+```ts
+import { generateCareCompassSnippet } from "@nexalink/carecompass-sdk";
+
+const html = generateCareCompassSnippet(config, { mode: "cdn" });
+```
+
+The generated module calls `mountCareCompass` and does not require a React app.
 
-Chat requests go to Nexalink-hosted CareCompass API routes. Those hosted routes are responsible for authorization, origin validation, tenant isolation, prompt guardrails, rate limiting, request attribution, usage tracking, and routing to the CareCompass AI runtime.
+### 6. Iframe Fallback
 
-## Account, Credentials, and BAA Requirements
+Use an iframe when the host page needs strong CSS/JavaScript isolation or cannot
+run a module script. The CLI `init` flow generates an iframe page, or you can
+create the host markup with `generateCareCompassIframeSnippet(config)`.
 
-A Nexalink account with SDK access is required beyond package installation so Nexalink can validate payer identity, deployment environment, allowed origins, approved prompt configuration, credentials, and API usage.
+```ts
+import { generateCareCompassIframeSnippet } from "@nexalink/carecompass-sdk";
 
-CareCompass uses two different keys:
+const html = generateCareCompassIframeSnippet(config, {
+  src: "/carecompass/carecompass-embed.html",
+});
+```
 
-- **API key**: a secret credential for trusted setup and server-side or CLI workflows, including `init` sign-in and validation. Never include it in browser code, generated embed HTML, frontend config, or source control.
-- **Embed key**: a public browser-facing identifier for the CareCompass embed. It is safe to include in `carecompass.config.json` and generated snippets. It identifies the payer, environment, and embed client for runtime requests, but it is not a secret or proof of identity on its own.
+An iframe isolates page styles and scripts, but it adds a separate document for
+focus management, analytics, responsive sizing, and host-to-widget context.
+Choose the React hook or Web Component when the assistant needs rich in-page
+coordination; choose the iframe for constrained or high-isolation environments.
 
-API keys are issued in the Nexalink portal. When PHI may be involved, a tenant owner or admin may need to execute the canonical BAA before generating the first key. The secret API key is shown once, stored locally by the developer, and should be handled as a server-side or CLI credential.
+### 7. Existing Embed Compatibility
 
-## React Usage
+Existing embed integrations can keep using the root package exports.
 
 ```tsx
 import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
 import config from "./carecompass/carecompass.config.json";
 
-export function MemberSupport() {
+export function HealthcareAssistant() {
   return <CareCompassEmbed config={config} />;
 }
 ```
 
-## JavaScript Usage
-
 ```ts
 import { mountCareCompass } from "@nexalink/carecompass-sdk";
 import config from "./carecompass/carecompass.config.json";
@@ -143,9 +360,65 @@ import config from "./carecompass/carecompass.config.json";
 mountCareCompass(document.getElementById("carecompass-root"), config);
 ```
 
-## Configuration Reference
+### Production runtime tokens
+
+Production embeds require a fresh runtime token from an integrator-controlled
+backend-for-frontend (BFF). Do not place a Nexalink API key, runtime-token
+secret, or a reusable token in `carecompass.config.json` or browser code.
+
+Provide `runtimeTokenProvider`; the SDK calls it before validation, every
+inference request, and every status poll. The provider should call your BFF,
+which holds the Nexalink API key and obtains a short-lived token for the
+current browser origin and workflow.
+
+```tsx
+const runtimeTokenProvider = async ({ workflow }: { workflow?: string }) => {
+  const response = await fetch("/api/carecompass/runtime-token", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ workflow }),
+  });
+  if (!response.ok) throw new Error("Could not authorize CareCompass.");
+  return ((await response.json()) as { token: string }).token;
+};
+
+<CareCompassEmbed
+  config={config}
+  runtimeTokenProvider={runtimeTokenProvider}
+/>;
+```
+
+For static hosts, pass the provider as the third argument to
+`mountCareCompass`. For Web Components, assign it to the
+`runtimeTokenProvider` property before setting `config`. Production requests
+fail closed when the provider is absent, fails, or returns an empty token.
+
+## Quick Start
+
+Live regulated use requires Nexalink onboarding, issued credentials, and BAA coverage where PHI may be involved. The package is publicly installable for developer convenience, but runtime access is credentialed.
+
+```bash
+npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://app.acme-health.com
+npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
+npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
+```
+
+`payerId` is the current tenant identifier used by the SDK. Despite the name, it can represent any healthcare customer workspace, including providers, digital health companies, RCM vendors, care platforms, AI healthcare products, and other healthcare organizations.
 
-`carecompass/carecompass.config.json` is safe to commit when it contains only public embed configuration. Store the secret API key only in local CLI credentials or an approved server-side secret store.
+`init` creates a starter setup kit:
+
+- `carecompass/carecompass.config.json`
+- `carecompass/system-prompt.md`
+- `carecompass/carecompass-embed.html`
+- `carecompass/carecompass-iframe.html`
+- `carecompass/README.md`
+
+`npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package in your project.
+
+## Public Configuration
+
+`carecompass.config.json` is safe to commit when it contains only public embed configuration. Do not put the secret API key in browser code, generated HTML, frontend config, or source control.
 
 ```json
 {
@@ -153,11 +426,11 @@ mountCareCompass(document.getElementById("carecompass-root"), config);
   "environment": "staging",
   "apiBaseUrl": "https://www.nexalink.care",
   "embedKey": "embed_public_key_from_nexalink",
-  "allowedOrigins": ["https://members.acme-health.com"],
+  "allowedOrigins": ["https://app.acme-health.com"],
   "branding": {
     "displayName": "Acme Health",
-    "logoUrl": "https://members.acme-health.com/logo.svg",
-    "supportUrl": "https://members.acme-health.com/support"
+    "logoUrl": "https://app.acme-health.com/logo.svg",
+    "supportUrl": "https://app.acme-health.com/support"
   },
   "theme": {
     "primaryColor": "#2563eb",
@@ -167,17 +440,28 @@ mountCareCompass(document.getElementById("carecompass-root"), config);
     "fontFamily": "system-ui, sans-serif"
   },
   "labels": {
-    "title": "Acme Care Guide",
-    "placeholder": "Ask about benefits, care options, or next steps...",
+    "title": "Acme AI Assistant",
+    "placeholder": "Ask about this workflow...",
     "sendButton": "Send",
-    "disclaimer": "CareCompass provides navigation support, not medical advice.",
+    "disclaimer": "This assistant provides support, not medical advice.",
     "errorMessage": "CareCompass is unavailable right now."
   },
   "prompt": {
     "systemInstructionFile": "./system-prompt.md",
-    "welcomeMessage": "How can I help you navigate your care today?",
+    "welcomeMessage": "How can I help?",
     "allowUserContext": false
   },
+  "compliance": {
+    "preset": "healthcare"
+  },
+  "model": {
+    "id": "care-navigation-v2",
+    "version": "2026-07"
+  },
+  "featureFlags": {
+    "care-plan-summary": true,
+    "provider-search": true
+  },
   "placement": {
     "mode": "inline"
   },
@@ -185,39 +469,100 @@ mountCareCompass(document.getElementById("carecompass-root"), config);
 }
 ```
 
-`carecompass/system-prompt.md` defines approved context before a member message reaches the AI runtime: plan terminology, support boundaries, escalation rules, and navigation context. The CLI resolves the prompt file into `carecompass/carecompass-embed.html`; the browser receives prompt text, not a local file path. Nexalink guardrails still validate prompt content.
+## Compliance Controls And Audit Trails
+
+Compliance controls are local SDK preflight checks, not a substitute for Nexalink runtime guardrails, a BAA, or the host application's own HIPAA program. They detect common direct identifiers (email addresses, US phone numbers, SSNs, DOBs, member/policy IDs, and MRNs) in messages, responses, and string-valued context before the SDK stores or sends them.
+
+Choose a preset in public SDK configuration, then override only the behavior you need:
 
-`carecompass/carecompass-iframe.html` contains the iframe to place on the integrating page:
+| Preset       | PHI behavior                                                                      | Audit retention | Tradeoff                                                                                                      |
+| ------------ | --------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
+| `standard`   | Detects and emits a `policy_sensitive` safety callback; does not modify requests. | Off             | Preserves existing SDK behavior; the host must opt into audit retention.                                      |
+| `healthcare` | Replaces detected values with `[REDACTED]` before requests and UI state.          | On              | Recommended default for PHI-oriented browser integrations; local detection cannot identify every form of PHI. |
+| `strict`     | Blocks a request or response with detectable PHI.                                 | On              | Stronger browser-side control, but legitimate identifier-bearing workflows need a host-approved alternative.  |
 
-```html
-<iframe
-  title="Acme Health CareCompass"
-  src="/carecompass/carecompass-embed.html"
-  style="width: 100%; min-height: 640px; border: 0; border-radius: 8px;"
-  loading="lazy"
-></iframe>
+```ts
+import { createCareCompassCore } from "@nexalink/carecompass-sdk/core";
+
+const core = createCareCompassCore({
+  ...config,
+  compliance: {
+    preset: "healthcare",
+    phi: { replacement: "[PHI REMOVED]" },
+  },
+});
+
+const unsubscribeAudit = core.subscribeAudit((event) => {
+  // Persist to your audit system. Events contain type, outcome, timestamp,
+  // source, PHI category/count, and a generated ID—never message text,
+  // context values, identifiers, or raw errors.
+  persistAuditEvent(event);
+});
+
+const unsubscribeSafety = core.subscribeSafety((event) => {
+  // `blocked`, `redacted`, `escalated`, or `policy_sensitive` with only
+  // source plus PHI category/count for safe monitoring.
+  monitorSafetyEvent(event);
+});
+
+// Export a copy of the in-memory, metadata-only audit trail on demand.
+const auditTrail = core.exportAuditTrail();
+
+unsubscribeAudit();
+unsubscribeSafety();
 ```
 
-Serve `carecompass/carecompass-embed.html` at the iframe `src`, often by copying the generated `carecompass` folder into public/static assets.
+For host-owned tools and UI actions that happen outside the core request lifecycle, add their metadata-only events explicitly:
+
+```ts
+core.recordToolCall("completed");
+core.recordWidgetAction();
+core.recordSafetyDecision("escalated");
+```
+
+If your organization has an approved detector or redaction format, pass it through `createCareCompassCore` options. These hooks receive the raw value only inside your host application; the SDK still emits only PHI categories and counts in audit and safety events.
+
+```ts
+const core = createCareCompassCore(config, {
+  compliance: {
+    phi: {
+      detect: (value) => approvedPhiDetector(value),
+      redact: (value, matches) => approvedRedactor(value, matches),
+    },
+  },
+});
+```
+
+The React UI kit accepts `onAuditEvent` and `onSafetyEvent` with the same safe payloads. Its submit and retry actions are automatically represented as widget audit events when auditing is enabled.
+
+## Credential Model
+
+CareCompass uses two key types:
+
+- **API key**: secret credential for trusted setup, CLI validation, and server-side workflows. Never expose it in browser code.
+- **Embed key**: public browser-facing identifier used by the runtime embed. It identifies the tenant, environment, and embed client, but it is not a secret by itself.
+
+Nexalink-hosted routes remain responsible for authorization, origin validation, tenant isolation, prompt guardrails, rate limiting, request attribution, usage tracking, and routing to the CareCompass runtime.
 
 ## CLI Reference
 
 ### `init`
 
-Runs first-time setup: routes users to signup, validates the API key, stores it locally, and generates the config, prompt starter, embed page, iframe, and setup guide with only public embed configuration.
+Creates the local setup kit, validates credentials, stores the API key locally, and generates starter config and embed assets.
 
-Credentials are stored at `~/.nexalink/carecompass/credentials.json` by default. You can also set `CARECOMPASS_API_KEY`. For scripted setup, pass `--account-type developer`. Configure signup with `--developer-signup-url` or `CARECOMPASS_DEVELOPER_SIGNUP_URL`; default: `https://www.nexalink.care/developer/signup`.
+```bash
+npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://app.acme-health.com
+```
 
-Generated HTML defaults to bundler-friendly imports from `@nexalink/carecompass-sdk`. For a raw browser HTML demo that is not processed by a bundler, add `--snippet-mode cdn`.
+For raw browser HTML that is not processed by a bundler:
 
 ```bash
-npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
-npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com
+npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://app.acme-health.com
 ```
 
 ### `validate`
 
-Checks local config shape and credentials, then hosted validation for `apiBaseUrl`, `embedKey`, `payerId`, `environment`, and `allowedOrigins` unless `--local-only` is passed. Browser-side validation uses public embed headers and does not send the secret API key.
+Checks local config shape and hosted runtime configuration.
 
 ```bash
 npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
@@ -226,7 +571,7 @@ npx @nexalink/carecompass-sdk validate --local-only --config carecompass/carecom
 
 ### `snippet`
 
-Regenerates the HTML embed snippet after config, branding, origin, or prompt changes. `init` already runs this once.
+Regenerates embed HTML after config, branding, origin, or prompt changes.
 
 ```bash
 npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json
@@ -235,36 +580,42 @@ npx @nexalink/carecompass-sdk snippet --snippet-mode cdn --config carecompass/ca
 
 ### `doctor`
 
-Prints a deployment readiness summary for the selected config.
+Prints a deployment readiness summary.
 
 ```bash
 npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
 ```
 
-## Security and Compliance Model
+## Security And Compliance Positioning
 
-CareCompass is BAA-gated where PHI may be involved and HIPAA-oriented for regulated healthcare deployment workflows, but this README does not claim blanket HIPAA compliance for every implementation or deployment.
+CareCompass is BAA-gated where PHI may be involved and built for regulated healthcare workflows, but this README does not claim blanket HIPAA compliance for every implementation or deployment.
 
-The SDK keeps secret keys out of the browser. Browser code receives public embed configuration only. Staging and production `apiBaseUrl` values must be Nexalink-hosted HTTPS URLs; `localhost` is accepted only for `development`.
+The SDK is designed to keep sensitive operational details out of the browser:
 
-Nexalink-hosted API routes are responsible for authorization, origin allowlists, tenant isolation, prompt guardrails, rate limiting, request attribution, and usage tracking. Generated snippets escape serialized config, and React renders chat messages and labels as text.
+- no secret API keys in frontend config
+- no model endpoint credentials in browser code
+- no customer-managed telemetry switches in runtime config
+- no prompt, response, chat history, user context, PHI/PII, payer, tenant, deployment, session, or user identifiers, credentials, raw errors, stack traces, CLI arguments, terminal input, or file paths in SDK telemetry
+- generated snippets escape serialized config
+- default React rendering escapes raw HTML
 
-Telemetry is enabled automatically with Nexalink-managed defaults. The SDK sends only allowlisted anonymous deployment-health events to PostHog's public ingestion API. It does not bundle `posthog-js`, enable session replay or autocapture, identify users, set cookies, or persist analytics state. Prompts, responses, chat history, user context, PHI/PII, credentials, raw errors, stack traces, CLI arguments, terminal input, and file paths are excluded from telemetry.
+Telemetry is enabled with Nexalink-managed defaults and sends only allowlisted anonymous deployment-health events.
 
 ## Runtime Notes
 
-Some development and MVP environments may use scale-to-zero infrastructure, which can add cold-start latency to the first request after an idle period. The request still routes through Nexalink-hosted APIs; the browser embed does not receive infrastructure credentials or call the model endpoint directly.
+Some development and MVP environments may use scale-to-zero infrastructure, which can add cold-start latency to the first request after an idle period.
+
+Requests still route through Nexalink-hosted APIs. The browser embed does not receive infrastructure credentials or call model endpoints directly.
 
 ## Troubleshooting
 
 - `Missing Nexalink API key`: run `init`, choose Developer, and sign in. For scripts, pass `--account-type developer` with `--api-key <key>`, or set `CARECOMPASS_API_KEY` with `CARECOMPASS_ACCOUNT_TYPE=developer`.
 - `zsh: command not found: carecompass`: `npx` does not install a permanent command. Run `npx @nexalink/carecompass-sdk <command>` or install the package.
-- `@parcel/core: Failed to resolve 'https://esm.sh/...'`: regenerate with bundler mode: `npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json`. CDN mode is for raw browser HTML.
-- `CareCompass could not reach http://localhost:3000`: hosted sandboxes cannot reach your machine's `localhost`. Test locally or use a deployed Nexalink `apiBaseUrl`. Run `validate` before typing into the embed.
-- `Origin is not authorized`: add the exact website origin to the Nexalink portal SDK configuration.
+- `@parcel/core: Failed to resolve 'https://esm.sh/...'`: regenerate with bundler mode. CDN mode is for raw browser HTML.
+- `CareCompass could not reach http://localhost:3000`: hosted sandboxes cannot reach your machine's `localhost`. Test locally or use a deployed Nexalink `apiBaseUrl`.
+- `Origin is not authorized`: add the exact website origin to the Nexalink SDK configuration.
 - `Prompt configuration violates CareCompass guardrails`: remove unsafe or unsupported instructions and re-run validation.
-- `CareCompass embed client is not authorized`: confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued in the Nexalink portal.
-- `CareCompass AppSync inference service is not configured`: Nexalink server operators should confirm `NEXT_PUBLIC_API_URL` or `CARECOMPASS_APPSYNC_URL`. The embed does not require a payer-provided LLM URL.
+- `CareCompass embed client is not authorized`: confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued for the deployment.
 
 ## License