@capxul/sdk 1.2.1 → 1.2.3

package/README.md

@@ -19,32 +19,30 @@ const client = created.value;
 Every public operation resolves a `Promise<CapxulResult<T>>`. Domain failures
 are values, not thrown exceptions.
 
-## Engineering telemetry
+## Observability
 
-Production hosts can opt into sanitized Effect logs and traces through the
-public client input:
+Hosts can attach the PostHog client they already initialized through one
+product-and-failure module:
 
 ```ts
+import { postHogObservability } from "@capxul/sdk";
+
 const created = await createCapxulClient({
   publishableKey: "cap_pk_…",
-  engineeringTelemetry: {
-    host: "https://us.i.posthog.com",
-    headers: { Authorization: "Bearer phc_…" },
+  observability: postHogObservability(posthog, {
     capxulEnv: "production",
-    serviceName: "capxul-sdk",
-  },
+    context: () => ({ correlationId, journeyId, organizationId }),
+  }),
 });
 ```
 
-Use the browser-safe PostHog project token (`phc_...`), never a personal API
-key (`phx_...`) or another secret. The host URL must be a credential-free HTTPS
-origin; credentials belong only in the explicit header. The SDK supplies its
-runtime producer and version, permits only closed identity classifications and
-safe correlation identifiers, and excludes email, OTP, auth/session tokens,
-wallet data, request/response bodies, provider messages, raw causes, and
-stacks. Export is best-effort and cannot change the operation result. An OTLP
-HTTP 200 is not delivery proof: verify a live run by querying both PostHog
-`logs` and `posthog.trace_spans` for the same fresh trace.
+The SDK initializes no analytics client and preserves host consent. Product
+events and sanitized failures share one enable/context/delivery policy.
+Engineering logs and traces are separate internally, but applications do not
+configure them: the versioned bootstrap response optionally supplies the
+governed PostHog ingest origin, public project token, and environment. The SDK
+derives endpoints, service, producer, and version. Missing or invalid policy
+disables engineering export without failing client creation.
 
 Onboarding uses explicit domain objects. Personal completion accepts
 `{ profile }`; Organization completion accepts independently validated
@@ -60,7 +58,7 @@ Public Profile reads include the durable `onboarded` flag and optional
 The packed npm package exposes only:
 
 - `@capxul/sdk` — the client factory, public method and value types, signers,
-  and observation helpers.
+  and the host observability helper.
 - `@capxul/sdk/node` — Node-only signer and runtime helpers.
 - `@capxul/sdk/testing` — the real identity runtime assembled over
   deterministic in-memory ports, with OTP, advance-only clock, transition,
@@ -96,8 +94,8 @@ The testing entry is identity-scoped and hermetic. Fine-grained
   evidence, and update triggers.
 - [Architecture](./docs/architecture.md) — client assembly, flows, ports,
   adapters, and proof map.
-- [Observation](./docs/observation.md) — host-owned failure observation and
-  bounded backend linkage.
+- [Observation](./docs/observation.md) — unified host observability,
+  bootstrap-owned engineering policy, and bounded backend linkage.
 - [Public SDK documentation](../../apps/docs/content/docs/sdk/index.mdx) —
   tutorials, guides, reference, and explanation for npm consumers.