From 7289ac93d412318edefd3e04e9c1ba6eb9c27be9 Mon Sep 17 00:00:00 2001
From: Charles Hudson <charles.hudson@contentful.com>
Date: Tue, 31 Mar 2026 14:45:08 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=98=20docs(plumbing):=20Updating=20doc?=
 =?UTF-8?q?s=20plumbing=20to=20fix=20dead=20links=20and=20prep=20for=20Gui?=
 =?UTF-8?q?des?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

[[NT-2556](https://contentful.atlassian.net/browse/NT-2556)]
---
 .github/workflows/publish-npm.yaml            |   9 +
 AGENTS.md                                     |   7 +
 CONTRIBUTING.md                               |   8 +-
 README.md                                     | 124 ++++----
 documentation/README.md                       |  15 +
 documentation/choosing-the-right-sdk.md       |  70 +++++
 implementations/node-sdk+web-sdk/README.md    |   6 +-
 implementations/node-sdk/README.md            |   4 +-
 implementations/react-native-sdk/README.md    |   4 +-
 implementations/web-sdk/README.md             |   6 +-
 implementations/web-sdk_react/README.md       |  21 +-
 lib/build-tools/src/cli.ts                    |  94 ++++--
 lib/build-tools/src/index.ts                  |   5 +
 lib/build-tools/src/publishReadme.test.ts     |  90 ++++++
 lib/build-tools/src/publishReadme.ts          | 279 ++++++++++++++++++
 packages/node/node-sdk/README.md              |   4 +-
 packages/node/node-sdk/package.json           |   5 +
 packages/react-native-sdk/README.md           |   4 +-
 packages/react-native-sdk/package.json        |   5 +
 .../OptimizationNavigationContainer.tsx       |   4 +-
 .../src/components/OptimizationProvider.tsx   |   2 +-
 .../context/InteractionTrackingContext.tsx    |   4 +-
 .../src/context/LiveUpdatesContext.tsx        |   4 +-
 .../src/context/OptimizationScrollContext.tsx |   2 +-
 .../src/hooks/useTapTracking.ts               |   2 +-
 packages/react-native-sdk/src/index.ts        |  18 +-
 .../src/preview/components/PreviewPanel.tsx   |   2 +-
 .../components/PreviewPanelOverlay.tsx        |   4 +-
 .../context/PreviewOverrideContext.tsx        |   6 +-
 .../react-native-sdk/src/preview/types.ts     |   2 +-
 packages/universal/api-client/README.md       |   6 +-
 packages/universal/api-client/package.json    |   5 +
 .../universal/api-client/src/ApiClient.ts     |   4 +-
 .../universal/api-client/src/ApiClientBase.ts |   2 +-
 .../src/experience/ExperienceApiClient.ts     |  64 ++--
 .../api-client/src/experience/index.ts        |   5 +-
 .../src/fetch/createProtectedFetchMethod.ts   |   2 +-
 .../src/fetch/createRetryFetchMethod.ts       |   2 +-
 .../src/fetch/createTimeoutFetchMethod.ts     |   2 +-
 packages/universal/api-client/src/index.ts    |   1 +
 .../src/insights/InsightsApiClient.ts         |  12 +-
 .../api-client/src/insights/index.ts          |   5 +-
 packages/universal/api-schemas/README.md      |   6 +-
 packages/universal/api-schemas/package.json   |   5 +
 .../api-schemas/src/contentful/CtflEntry.ts   |   2 +-
 .../src/experience/change/Change.ts           |   6 +-
 .../api-schemas/src/experience/index.ts       |   1 +
 .../optimization/SelectedOptimization.ts      |   2 +-
 .../profile/properties/SessionStatistics.ts   |   4 +-
 packages/universal/core-sdk/README.md         |   6 +-
 packages/universal/core-sdk/package.json      |   5 +
 packages/universal/core-sdk/src/CoreBase.ts   |   2 +-
 .../universal/core-sdk/src/CoreStateless.ts   |   2 +-
 .../core-sdk/src/events/EventBuilder.ts       |  24 +-
 packages/universal/core-sdk/src/index.ts      |  10 +
 .../core-sdk/src/lib/decorators/guardedBy.ts  |   6 +-
 .../core-sdk/src/lib/decorators/index.ts      |   1 +
 .../src/lib/interceptor/InterceptorManager.ts |   2 +-
 .../web/frameworks/react-web-sdk/README.md    |  21 +-
 .../web/frameworks/react-web-sdk/package.json |   5 +
 packages/web/preview-panel/README.md          |   4 +-
 packages/web/preview-panel/package.json       |   5 +
 .../src/attachOptimizationPreviewPanel.ts     |   2 +-
 packages/web/preview-panel/src/index.ts       |   2 +
 packages/web/web-sdk/README.md                |   4 +-
 packages/web/web-sdk/package.json             |   5 +
 .../web/web-sdk/src/ContentfulOptimization.ts |   6 +-
 ...resolveAutoTrackEntryInteractionOptions.ts |   4 +-
 packages/web/web-sdk/src/index.ts             |  19 +-
 typedoc.json                                  |  16 +-
 70 files changed, 873 insertions(+), 224 deletions(-)
 create mode 100644 documentation/README.md
 create mode 100644 documentation/choosing-the-right-sdk.md
 create mode 100644 lib/build-tools/src/publishReadme.test.ts
 create mode 100644 lib/build-tools/src/publishReadme.ts

diff --git a/.github/workflows/publish-npm.yaml b/.github/workflows/publish-npm.yaml
index 98209be6..86076f7f 100644
--- a/.github/workflows/publish-npm.yaml
+++ b/.github/workflows/publish-npm.yaml
@@ -69,6 +69,11 @@ jobs:
         env:
           RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
 
+      - name: Prepare package READMEs for publish
+        run: pnpm -r --filter "@contentful/optimization-*" exec build-tools rewrite-readme prepare
+        env:
+          RELEASE_TAG: ${{ env.RELEASE_TAG }}
+
       - name: Create packages for troubleshooting
         run: pnpm pack --filter "@contentful/optimization-*" --pack-destination pkgs
 
@@ -92,3 +97,7 @@ jobs:
         run: pnpm -r --filter "@contentful/optimization-*" publish --access public --no-git-checks
         env:
           NODE_AUTH_TOKEN: ${{ steps.vault.outputs.GITHUB_PACKAGES_WRITE_TOKEN }}
+
+      - name: Restore package READMEs after publish
+        if: always()
+        run: pnpm -r --filter "@contentful/optimization-*" exec build-tools rewrite-readme restore
diff --git a/AGENTS.md b/AGENTS.md
index 87d66c1b..4a248e8d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,6 +44,7 @@ Prefer editing source files and configuration:
 - `e2e/**`
 - `__tests__/**`
 - `scripts/**`
+- `documentation/**`
 - `README.md`
 - `package.json`
 - `tsconfig*.json`
@@ -96,6 +97,9 @@ Do not hand-edit generated or local-only artifacts unless the task is explicitly
 ## Validation Policy
 
 - Run the smallest meaningful validation that matches the change.
+- When linting or formatting is likely needed, prefer the smallest fix-enabled command that matches
+  the edited area first, then confirm with a check-only command if needed. Avoid the pattern of
+  running a pure check, then rerunning the same tool again only to apply obvious auto-fixes.
 - For TypeScript or TSX edits, run the relevant lint command early enough to influence the shape of
   the implementation, not only at the end.
 - For `lib/` or `packages/` edits, prefer `pnpm lint` after the first meaningful patch and again
@@ -137,6 +141,8 @@ High-signal repo-wide commands:
   - unknown
 - Prefer a small probe before a full rerun. Check the nearest `AGENTS.md`, the target
   `package.json`, and any relevant `README.md` or `CONTRIBUTING.md` section before guessing.
+- If a lint or format command fails with findings that the tool can auto-fix, prefer a targeted
+  fix-enabled rerun over repeated check-only runs, then revalidate once.
 - If the shell reports a command as missing:
   - first prefer `pnpm <script>` or `pnpm exec <tool>` over assuming a global binary
   - check whether the command is defined in the relevant `package.json`
@@ -184,6 +190,7 @@ Common repo-specific failure modes:
 
 - When public SDK behavior changes, update the relevant TSDoc or JSDoc and the affected package
   `README.md` in the same change.
+- Authored supporting docs live in `documentation/`; generated TypeDoc output lives in `docs/`.
 - If a package includes a package-local dev harness or other meaningful local dev surface, keep that
   surface relevant to the current SDK behavior and update it in the same change when the package's
   developer-facing flows, configuration, or core capabilities change.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6521a21d..766ca19c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -306,8 +306,9 @@ Practical implications:
 Code is documented using TSDoc, and reference documentation is generated using TypeDoc and published
 automatically with each new version.
 
-- `pnpm docs:generate` generates documentation from TSDoc code comments, as well as README and other
-  linked markdown files
+- authored supporting docs belong in `documentation/`, while `docs/` remains generated output
+- `pnpm docs:generate` generates documentation from TSDoc code comments, package README files, and
+  markdown files under `documentation/`
 - `pnpm docs:watch` watches for file updates and rebuilds documentation output; useful while writing
   and updating documentation
 
@@ -321,7 +322,8 @@ keep these artifacts aligned:
 - any replacement design, architecture, or specification artifacts that the repository adds for the
   changed area
 
-`docs/` is generated output. Do not hand-edit generated TypeDoc output.
+`documentation/` contains source markdown that TypeDoc publishes. `docs/` is generated output. Do
+not hand-edit generated TypeDoc output.
 
 ## Local Troubleshooting
 
diff --git a/README.md b/README.md
index adce8085..7873830d 100644
--- a/README.md
+++ b/README.md
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](./CONTRIBUTING.md)
+[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](./CONTRIBUTING.md)
 
 </div>
 
@@ -21,8 +21,9 @@
 
 ## Introduction
 
-A [pnpm](https://pnpm.io/) monorepo hosting a Suite of SDKs that implement functionality for
-Contentful's [Personalization](https://www.contentful.com/developers/docs/personalization/) and
+A [pnpm](https://pnpm.io/) monorepo hosting a suite of SDKs, supporting libraries, and reference
+implementations for Contentful
+[Personalization](https://www.contentful.com/developers/docs/personalization/) and
 [Analytics](https://www.contentful.com/developers/docs/analytics/overview/) products.
 
 **What is Contentful?**
@@ -36,10 +37,11 @@ enables developers and content creators to ship their products faster.
   <summary>Table of Contents</summary>
 <!-- mtoc-start -->
 
-- [Optimization SDKs](#optimization-sdks)
+- [Choosing a Package](#choosing-a-package)
+- [Published Packages](#published-packages)
+- [Planned SDKs](#planned-sdks)
 - [Reference Implementations](#reference-implementations)
-- [Universal Libraries](#universal-libraries)
-- [Shared Internal Libraries](#shared-internal-libraries)
+- [Repository Layout](#repository-layout)
 - [Get Involved](#get-involved)
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
@@ -47,67 +49,73 @@ enables developers and content creators to ship their products faster.
 <!-- mtoc-end -->
 </details>
 
-## Optimization SDKs
-
-Optimization SDKs are organized in a hierarchy based on platform, environment, and optionally,
-framework. Each SDK builds on top of the common SDK for its platform, environment, and so on, to
-ensure functionality is reasonably shared and consistent.
-
-- [Optimization Core SDK](./packages/universal/core-sdk/README.md)
-  - iOS
-    - iOS Swift SDK (planned)
-  - Android
-    - Android Kotlin SDK (planned)
-    - Android Java SDK (planned)
-  - _JavaScript_
-    - [Node SDK](./packages/node/node-sdk/README.md)
-      - Nest.js SDK (planned)
-    - [React Native SDK](./packages/react-native-sdk/README.md)
-    - [Web SDK](./packages/web/web-sdk/README.md) and
-      [Web Preview Panel](./packages/web/preview-panel/README.md)
-      - Angular SDK (planned)
-      - [React Web SDK](./packages/web/frameworks/react-web-sdk/README.md)
-      - Svelte SDK (planned)
-      - Vue SDK (planned)
-
-> [!NOTE]
->
-> The JavaScript platform includes React Native, which could be considered a JavaScript development
-> environment for native platforms.
+## Choosing a Package
 
-## Reference Implementations
+If you are deciding which SDK or library belongs in your application, start with
+[Choosing the Right SDK](./documentation/choosing-the-right-sdk.md).
 
-The SDK Suite's reference implementations are intended to serve the following purposes:
+For additional narrative documentation, see the [Guides](./documentation/README.md) section.
 
-- E2E testing of critical SDK functionality
-- Clear and simple documentation of common SDK use cases with absolutely no extraneous content or
-  functionality
+Package README files listed below are package-level overviews. Generated
+[reference documentation](https://contentful.github.io/optimization) remains the source of truth for
+exported API signatures.
 
-> [!WARNING]
->
-> Reference implementations may share some similarities with projects commonly labeled examples,
-> demos, or playgrounds, but are more sparse and strictly maintained
+## Published Packages
 
-## Universal Libraries
+The published package surface is intentionally layered. The table below is a package inventory and
+high-level role summary.
 
-These libraries may be used independently of other libraries and SDKs in the Optimization SDK Suite.
-They are relied upon by all SDKs, with their exported values and functionality exposed throughout
-the SDK hierarchy.
+| Package                                      | Kind                  | Runtime          | Role                                                               | Package README                                                     |
+| -------------------------------------------- | --------------------- | ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `@contentful/optimization-web`               | Environment SDK       | Browser          | Stateful browser SDK for optimization, tracking, and consent       | [Web SDK](./packages/web/web-sdk/README.md)                        |
+| `@contentful/optimization-react-web`         | Framework SDK         | React on the web | React integration layer on top of the Web SDK                      | [React Web SDK](./packages/web/frameworks/react-web-sdk/README.md) |
+| `@contentful/optimization-node`              | Environment SDK       | Node.js          | Stateless Node SDK for server-side and SSR integrations            | [Node SDK](./packages/node/node-sdk/README.md)                     |
+| `@contentful/optimization-react-native`      | Environment SDK       | React Native     | React Native SDK for mobile applications                           | [React Native SDK](./packages/react-native-sdk/README.md)          |
+| `@contentful/optimization-web-preview-panel` | Tooling package       | Browser          | Preview tooling package for existing Web SDK instances             | [Web Preview Panel](./packages/web/preview-panel/README.md)        |
+| `@contentful/optimization-core`              | Shared SDK foundation | Runtime-agnostic | Shared optimization foundation for runtime adapters and SDK layers | [Core SDK](./packages/universal/core-sdk/README.md)                |
+| `@contentful/optimization-api-client`        | Universal library     | Runtime-agnostic | Direct Experience API and Insights API client library              | [API Client](./packages/universal/api-client/README.md)            |
+| `@contentful/optimization-api-schemas`       | Universal library     | Runtime-agnostic | Validation schemas and inferred API/content types library          | [API Schemas](./packages/universal/api-schemas/README.md)          |
 
-- [API Client Library](./packages/universal/api-client/README.md) for the Experience API and
-  Insights API
-- [API Schemas Library](./packages/universal/api-schemas/README.md) maintains Zod validation schemas
-  and TypeScript types for working with Experience API request/response payloads and Insights API
-  event payloads
+General selection rules:
 
-## Shared Internal Libraries
+- Most application code should start with an environment SDK or framework SDK.
+- `@contentful/optimization-core` is the shared foundation for runtime adapters and SDK layering.
+- `@contentful/optimization-api-client` and `@contentful/optimization-api-schemas` are lower-level
+  building blocks.
 
-Libraries that are shared internally among Optimization SDKs, and are not currently published.
+## Planned SDKs
+
+These packages or layers are planned, but are not currently published from this repository:
+
+- iOS Swift SDK
+- Android Kotlin SDK
+- Android Java SDK
+- Nest.js SDK
+- Angular SDK
+- Svelte SDK
+- Vue SDK
+
+## Reference Implementations
 
-- Logger functionality is provided through `@contentful/optimization-api-client/logger` and passed
-  through by each SDK at its own `./logger` entry point
-- [Mocks](./lib/mocks/README.md) supplies testing fixtures and data, as well as mock server
-  implementations used in both unit and end to end tests throughout the SDK suite
+Reference implementations exist to exercise critical flows end to end and to document common usage
+patterns with intentionally minimal application code.
+
+- [Web Vanilla](./implementations/web-sdk/README.md): static browser integration for the Web SDK
+- [React Web](./implementations/web-sdk_react/README.md): React-based browser integration
+- [Node SSR Only](./implementations/node-sdk/README.md): server-rendered integration using the Node
+  SDK
+- [Node SSR + Web Vanilla](./implementations/node-sdk+web-sdk/README.md): split server/browser flow
+  using Node and Web SDKs together
+- [React Native](./implementations/react-native-sdk/README.md): mobile application integration for
+  Android and iOS targets
+
+## Repository Layout
+
+- `packages/`: published SDKs and supporting libraries
+- `implementations/`: reference applications used for examples and E2E coverage
+- `lib/`: shared internal workspace packages such as mocks and build tooling
+- `documentation/`: authored supporting documentation published alongside TypeDoc
+- `docs/`: generated TypeDoc output; not source of truth
 
 ## Get Involved
 
diff --git a/documentation/README.md b/documentation/README.md
new file mode 100644
index 00000000..48f4945d
--- /dev/null
+++ b/documentation/README.md
@@ -0,0 +1,15 @@
+---
+title: Guides
+children:
+  - ./choosing-the-right-sdk.md
+---
+
+# Guides
+
+Start here when you need higher-level guidance about package selection, layering, or how the SDKs
+are intended to be used.
+
+## Available Guides
+
+- [Choosing the Right SDK](./choosing-the-right-sdk.md): pick the narrowest published package layer
+  for a browser, React, Node, or React Native application
diff --git a/documentation/choosing-the-right-sdk.md b/documentation/choosing-the-right-sdk.md
new file mode 100644
index 00000000..73043ec6
--- /dev/null
+++ b/documentation/choosing-the-right-sdk.md
@@ -0,0 +1,70 @@
+# Choosing the Right SDK
+
+Use this guide to choose the narrowest package layer that matches the runtime you are building for.
+
+## Runtime-First Selection
+
+### Browser Applications
+
+Choose `@contentful/optimization-web` when the application runs in the browser and needs stateful,
+client-side optimization behavior such as consent handling, event delivery, and automatic entry
+interaction tracking.
+
+Add `@contentful/optimization-web-preview-panel` when the same browser runtime also needs local
+preview tooling for optimization overrides.
+
+### React Applications on the Web
+
+Choose `@contentful/optimization-react-web` when the application is already built with React and
+benefits from provider composition, hooks, `OptimizedEntry`, and router-specific automatic page
+tracking.
+
+This package sits on top of `@contentful/optimization-web`, so React applications generally use the
+React layer as their application-facing entry point and rely on the Web SDK transitively.
+
+### Node Servers and Server-Side Rendering
+
+Choose `@contentful/optimization-node` when optimization decisions are resolved in a stateless Node
+environment such as a server, an SSR layer, or a server-side function.
+
+The Node SDK intentionally avoids runtime-managed state. Consent, identity persistence, and other
+long-lived user concerns should remain in the host application or an upstream platform layer.
+
+### React Native Applications
+
+Choose `@contentful/optimization-react-native` for React Native applications that need stateful
+optimization behavior on mobile, including offline-aware event handling and React Native-specific
+tracking utilities.
+
+## Lower-Level Building Blocks
+
+Choose one of the lower layers only when the environment SDKs are too opinionated for the use case
+or when you are building a new SDK layer inside this repository.
+
+### `@contentful/optimization-core`
+
+Use Core when building another SDK layer or when you need the shared optimization domain logic
+without committing to a specific runtime integration surface.
+
+- `CoreStateful` is the basis for browser and mobile-style runtimes.
+- `CoreStateless` is the basis for server-side runtimes.
+
+### `@contentful/optimization-api-client`
+
+Use the API client when the goal is direct Experience API and Insights API access without the higher
+level state, tracking, or entry-resolution behavior exposed by the SDK layers.
+
+### `@contentful/optimization-api-schemas`
+
+Use the schema package when you only need runtime validation and inferred TypeScript types for the
+Optimization APIs and Contentful entry-shape helpers.
+
+## Common Package Combinations
+
+- Browser application with author preview: `@contentful/optimization-web` and
+  `@contentful/optimization-web-preview-panel`
+- React browser application: `@contentful/optimization-react-web`
+- Server-rendered application with browser follow-up tracking: `@contentful/optimization-node` on
+  the server and `@contentful/optimization-web` in the browser
+- Custom internal SDK layer: `@contentful/optimization-core`, optionally with
+  `@contentful/optimization-api-client` and `@contentful/optimization-api-schemas`
diff --git a/implementations/node-sdk+web-sdk/README.md b/implementations/node-sdk+web-sdk/README.md
index d8086710..9baba79c 100644
--- a/implementations/node-sdk+web-sdk/README.md
+++ b/implementations/node-sdk+web-sdk/README.md
@@ -6,12 +6,12 @@
 
 <h1 align="center">Contentful Personalization & Analytics</h1>
 
-<h3 align="center">Node SSR + Web Vanilla Reference Implementation</h3>
+<h3 align="center">Node SDK SSR + Web SDK Vanilla JS Reference Implementation</h3>
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/implementations/node-sdk/README.md b/implementations/node-sdk/README.md
index 75c73840..ccb64fc0 100644
--- a/implementations/node-sdk/README.md
+++ b/implementations/node-sdk/README.md
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/implementations/react-native-sdk/README.md b/implementations/react-native-sdk/README.md
index 93d2c16a..0650b40b 100644
--- a/implementations/react-native-sdk/README.md
+++ b/implementations/react-native-sdk/README.md
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/implementations/web-sdk/README.md b/implementations/web-sdk/README.md
index cd28d50f..6da09867 100644
--- a/implementations/web-sdk/README.md
+++ b/implementations/web-sdk/README.md
@@ -6,12 +6,12 @@
 
 <h1 align="center">Contentful Personalization & Analytics</h1>
 
-<h3 align="center">Web Vanilla JS Reference Implementation</h3>
+<h3 align="center">Web SDK Vanilla JS Reference Implementation</h3>
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/implementations/web-sdk_react/README.md b/implementations/web-sdk_react/README.md
index de4e97f7..93688855 100644
--- a/implementations/web-sdk_react/README.md
+++ b/implementations/web-sdk_react/README.md
@@ -1,4 +1,23 @@
-# Web React Reference Implementation
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/personalization/">
+    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align="center">Contentful Personalization & Analytics</h1>
+
+<h3 align="center">Web SDK React Reference Implementation</h3>
+
+<div align="center">
+
+[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
+
+</div>
+
+> [!WARNING]
+>
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes may be published at any time.
 
 Reference implementation demonstrating `@contentful/optimization-web` usage in a React web
 application.
diff --git a/lib/build-tools/src/cli.ts b/lib/build-tools/src/cli.ts
index ce619cc6..f08afed8 100644
--- a/lib/build-tools/src/cli.ts
+++ b/lib/build-tools/src/cli.ts
@@ -1,15 +1,20 @@
 import { checkBundleSize } from './bundleSize'
 import { emitDualDts } from './emitDualDts'
+import { preparePublishReadme, restorePublishReadme } from './publishReadme'
 
 function printUsage(): void {
   process.stderr.write(
     'Usage:\n' +
       '  build-tools emit-dual-dts [distDir]\n' +
       '  build-tools bundle-size [packageDir] [--report-only]\n' +
+      '  build-tools rewrite-readme prepare [packageDir]\n' +
+      '  build-tools rewrite-readme restore [packageDir]\n' +
       '\n' +
       'Examples:\n' +
       '  build-tools emit-dual-dts ./dist\n' +
       '  build-tools bundle-size\n' +
+      '  build-tools rewrite-readme prepare\n' +
+      '  build-tools rewrite-readme restore ./packages/universal/core-sdk\n' +
       '  build-tools bundle-size ./packages/web/web-sdk --report-only\n',
   )
 }
@@ -34,6 +39,58 @@ function parseBundleSizeArgs(
   return { packageDir, reportOnly }
 }
 
+function failUsage(): void {
+  printUsage()
+  process.exitCode = 1
+}
+
+function runBundleSizeCommand(args: string[]): void {
+  const parsed = parseBundleSizeArgs(args)
+
+  if (parsed === undefined) {
+    failUsage()
+    return
+  }
+
+  const { failures, results } = checkBundleSize(parsed)
+
+  for (const result of results) {
+    const { budgetBytes, file, gzipBytes, rawBytes } = result
+    // eslint-disable-next-line no-console -- this CLI reports bundle stats to CI logs.
+    console.log(`${file}: raw=${rawBytes} gzip=${gzipBytes} budget=${budgetBytes}`)
+  }
+
+  if (failures.length > 0) {
+    // eslint-disable-next-line no-console -- this CLI reports failures to CI logs.
+    console.error('Bundle size budget exceeded:')
+
+    for (const failure of failures) {
+      // eslint-disable-next-line no-console -- this CLI reports failures to CI logs.
+      console.error(
+        `- ${failure.file}: gzip=${failure.gzipBytes} budget=${failure.budgetBytes} (+${failure.overBytes})`,
+      )
+    }
+
+    process.exitCode = 1
+  }
+}
+
+function runRewriteReadmeCommand(args: string[]): void {
+  const [action, packageDir = '.'] = args
+
+  if (action === 'prepare') {
+    preparePublishReadme(packageDir)
+    return
+  }
+
+  if (action === 'restore') {
+    restorePublishReadme(packageDir)
+    return
+  }
+
+  failUsage()
+}
+
 /**
  * CLI entry point that parses arguments and dispatches to the appropriate command.
  *
@@ -57,39 +114,14 @@ export function main(argv: string[]): void {
   }
 
   if (command === 'bundle-size') {
-    const parsed = parseBundleSizeArgs(rest)
-
-    if (parsed === undefined) {
-      printUsage()
-      process.exitCode = 1
-      return
-    }
-
-    const { failures, results } = checkBundleSize(parsed)
-
-    for (const result of results) {
-      const { budgetBytes, file, gzipBytes, rawBytes } = result
-      // eslint-disable-next-line no-console -- this CLI reports bundle stats to CI logs.
-      console.log(`${file}: raw=${rawBytes} gzip=${gzipBytes} budget=${budgetBytes}`)
-    }
-
-    if (failures.length > 0) {
-      // eslint-disable-next-line no-console -- this CLI reports failures to CI logs.
-      console.error('Bundle size budget exceeded:')
-
-      for (const failure of failures) {
-        // eslint-disable-next-line no-console -- this CLI reports failures to CI logs.
-        console.error(
-          `- ${failure.file}: gzip=${failure.gzipBytes} budget=${failure.budgetBytes} (+${failure.overBytes})`,
-        )
-      }
-
-      process.exitCode = 1
-    }
+    runBundleSizeCommand(rest)
+    return
+  }
 
+  if (command === 'rewrite-readme') {
+    runRewriteReadmeCommand(rest)
     return
   }
 
-  printUsage()
-  process.exitCode = 1
+  failUsage()
 }
diff --git a/lib/build-tools/src/index.ts b/lib/build-tools/src/index.ts
index c080d6b5..bb17561c 100644
--- a/lib/build-tools/src/index.ts
+++ b/lib/build-tools/src/index.ts
@@ -7,4 +7,9 @@ export { checkBundleSize } from './bundleSize'
 export type { BundleSizeFailure, BundleSizeResult, CheckBundleSizeOptions } from './bundleSize'
 export { emitDualDts } from './emitDualDts'
 export { getPackageName, hasPackageName } from './package'
+export {
+  preparePublishReadme,
+  restorePublishReadme,
+  rewriteReadmeForPublish,
+} from './publishReadme'
 export { ensureUmdDefaultExport, maybeEnableRsDoctor } from './rslib'
diff --git a/lib/build-tools/src/publishReadme.test.ts b/lib/build-tools/src/publishReadme.test.ts
new file mode 100644
index 00000000..a15a8ff4
--- /dev/null
+++ b/lib/build-tools/src/publishReadme.test.ts
@@ -0,0 +1,90 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  preparePublishReadme,
+  restorePublishReadme,
+  rewriteReadmeForPublish,
+} from './publishReadme'
+
+describe('rewriteReadmeForPublish', () => {
+  it('rewrites relative README links and assets using package repository metadata', () => {
+    const rewrittenReadme = rewriteReadmeForPublish(
+      [
+        '<img alt="Contentful Logo" src="../../../contentful-icon.png" width="150">',
+        '',
+        '[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)',
+        '[Optimization Core Library](../../universal/core-sdk/README.md)',
+        '![Logo](../../../contentful-icon.png)',
+        '',
+        '```md',
+        '[Contributing](../../../CONTRIBUTING.md)',
+        '```',
+      ].join('\n'),
+      {
+        blobBaseUrl: 'https://github.com/contentful/optimization/blob/v1.2.3',
+        rawBaseUrl: 'https://raw.githubusercontent.com/contentful/optimization/v1.2.3',
+        readmeUrl: new URL('/packages/node/node-sdk/README.md', 'https://publish-readme.invalid'),
+      },
+    )
+
+    expect(rewrittenReadme).toContain(
+      '<img alt="Contentful Logo" src="https://raw.githubusercontent.com/contentful/optimization/v1.2.3/contentful-icon.png" width="150">',
+    )
+    expect(rewrittenReadme).toContain(
+      '[Contributing](https://github.com/contentful/optimization/blob/v1.2.3/CONTRIBUTING.md)',
+    )
+    expect(rewrittenReadme).toContain(
+      '[Optimization Core Library](https://github.com/contentful/optimization/blob/v1.2.3/packages/universal/core-sdk/README.md)',
+    )
+    expect(rewrittenReadme).toContain(
+      '![Logo](https://raw.githubusercontent.com/contentful/optimization/v1.2.3/contentful-icon.png)',
+    )
+    expect(rewrittenReadme).toContain('```md\n[Contributing](../../../CONTRIBUTING.md)\n```')
+  })
+})
+
+describe('preparePublishReadme', () => {
+  it('rewrites README.md in place and restores it afterwards', () => {
+    const packageDir = mkdtempSync(join(tmpdir(), 'build-tools-publish-readme-'))
+    const readmePath = join(packageDir, 'README.md')
+
+    try {
+      writeFileSync(
+        join(packageDir, 'package.json'),
+        JSON.stringify({
+          name: '@contentful/example',
+          repository: {
+            type: 'git',
+            url: 'git+https://github.com/contentful/optimization.git',
+            directory: 'packages/example',
+          },
+        }),
+      )
+      writeFileSync(
+        readmePath,
+        '[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)\n![Logo](../../contentful-icon.png)\n',
+      )
+
+      preparePublishReadme(packageDir, { publishRef: 'v1.2.3' })
+
+      expect(readFileSync(readmePath, 'utf8')).toBe(
+        '[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/v1.2.3/CONTRIBUTING.md)\n![Logo](https://raw.githubusercontent.com/contentful/optimization/v1.2.3/contentful-icon.png)\n',
+      )
+      expect(existsSync(join(packageDir, '.tmp', 'build-tools-publish-readme-backup.md'))).toBe(
+        true,
+      )
+
+      restorePublishReadme(packageDir)
+
+      expect(readFileSync(readmePath, 'utf8')).toBe(
+        '[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)\n![Logo](../../contentful-icon.png)\n',
+      )
+      expect(existsSync(join(packageDir, '.tmp', 'build-tools-publish-readme-backup.md'))).toBe(
+        false,
+      )
+    } finally {
+      rmSync(packageDir, { force: true, recursive: true })
+    }
+  })
+})
diff --git a/lib/build-tools/src/publishReadme.ts b/lib/build-tools/src/publishReadme.ts
new file mode 100644
index 00000000..144ec860
--- /dev/null
+++ b/lib/build-tools/src/publishReadme.ts
@@ -0,0 +1,279 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+const README_FILE_NAME = 'README.md'
+const README_BACKUP_DIR_NAME = '.tmp'
+const README_BACKUP_FILE_NAME = 'build-tools-publish-readme-backup.md'
+const README_BASE_URL = 'https://publish-readme.invalid'
+const ABSOLUTE_TARGET_PATTERN = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i
+const RELATIVE_IMAGE_EXTENSIONS = new Set([
+  '.avif',
+  '.gif',
+  '.jpeg',
+  '.jpg',
+  '.png',
+  '.svg',
+  '.webp',
+])
+
+interface PublishReadmeOverrides {
+  publishRef?: string
+}
+
+interface PublishReadmeConfig {
+  blobBaseUrl: string
+  rawBaseUrl: string
+  readmeUrl: URL
+}
+
+interface RepositoryConfig {
+  directory: string
+  url: string
+}
+
+interface PackageJsonLike {
+  repository?: unknown
+}
+
+function getReadmePath(packageDir: string): string {
+  return path.resolve(packageDir, README_FILE_NAME)
+}
+
+function getReadmeBackupPath(packageDir: string): string {
+  return path.resolve(packageDir, README_BACKUP_DIR_NAME, README_BACKUP_FILE_NAME)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return isRecord(error) && error.code === code
+}
+
+function getPackageJson(packageDir: string): PackageJsonLike {
+  const packageJson: unknown = JSON.parse(
+    readFileSync(path.resolve(packageDir, 'package.json'), 'utf8'),
+  )
+
+  if (!isRecord(packageJson)) {
+    throw new Error(`Invalid package.json in ${path.resolve(packageDir, 'package.json')}.`)
+  }
+
+  return packageJson
+}
+
+function getRepositoryConfig(packageJson: PackageJsonLike, packageDir: string): RepositoryConfig {
+  const { repository } = packageJson
+
+  if (!isRecord(repository)) {
+    throw new Error(
+      `Missing repository.url or repository.directory in ${path.resolve(packageDir, 'package.json')}.`,
+    )
+  }
+
+  const { directory: rawDirectory, url } = repository
+
+  if (typeof rawDirectory !== 'string' || typeof url !== 'string') {
+    throw new Error(
+      `Missing repository.url or repository.directory in ${path.resolve(packageDir, 'package.json')}.`,
+    )
+  }
+
+  const directory = rawDirectory.replaceAll(path.sep, path.posix.sep).replace(/^\/+|\/+$/g, '')
+
+  if (directory === '') {
+    throw new Error(
+      `repository.directory must not be empty in ${path.resolve(packageDir, 'package.json')}.`,
+    )
+  }
+
+  return {
+    directory,
+    url,
+  }
+}
+
+function getGitHubSlug(repositoryUrl: string, packageDir: string): string {
+  const normalizedUrl = repositoryUrl
+    .replace(/^git\+/, '')
+    .replace(/\.git$/, '')
+    .replace(/\/$/, '')
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:)(.+)$/.exec(normalizedUrl)
+
+  if (match?.[1] === undefined) {
+    throw new Error(
+      `Unsupported repository.url in ${path.resolve(packageDir, 'package.json')}: ${repositoryUrl}.`,
+    )
+  }
+
+  return match[1]
+}
+
+function getPublishRef(overrides: PublishReadmeOverrides): string {
+  const publishRef = overrides.publishRef ?? process.env.RELEASE_TAG
+
+  if (!publishRef) {
+    throw new Error('Missing publish ref. Set RELEASE_TAG before rewriting package READMEs.')
+  }
+
+  return publishRef
+}
+
+function getPublishReadmeConfig(
+  packageDir: string,
+  overrides: PublishReadmeOverrides = {},
+): PublishReadmeConfig {
+  const packageJson = getPackageJson(packageDir)
+  const repository = getRepositoryConfig(packageJson, packageDir)
+  const slug = getGitHubSlug(repository.url, packageDir)
+  const publishRef = getPublishRef(overrides)
+
+  return {
+    blobBaseUrl: `https://github.com/${slug}/blob/${publishRef}`,
+    rawBaseUrl: `https://raw.githubusercontent.com/${slug}/${publishRef}`,
+    readmeUrl: new URL(`/${repository.directory}/${README_FILE_NAME}`, README_BASE_URL),
+  }
+}
+
+function isRelativeTarget(target: string): boolean {
+  return !ABSOLUTE_TARGET_PATTERN.test(target)
+}
+
+function isImagePath(repoPath: string): boolean {
+  return RELATIVE_IMAGE_EXTENSIONS.has(path.posix.extname(repoPath).toLowerCase())
+}
+
+function rewriteTarget(target: string, config: PublishReadmeConfig, isImage: boolean): string {
+  if (!isRelativeTarget(target)) {
+    return target
+  }
+
+  const resolvedTarget = new URL(target.replace(/^<|>$/g, ''), config.readmeUrl)
+  const repoPath = resolvedTarget.pathname.slice(1)
+  const baseUrl = isImage || isImagePath(repoPath) ? config.rawBaseUrl : config.blobBaseUrl
+
+  return `${baseUrl}/${repoPath}${resolvedTarget.search}${resolvedTarget.hash}`
+}
+
+function rewriteHtmlTargets(line: string, config: PublishReadmeConfig): string {
+  return line.replaceAll(
+    /\b(href|src)=(["'])([^"']+)\2/g,
+    (_match, attribute, quote, rawTarget) =>
+      `${attribute}=${quote}${rewriteTarget(String(rawTarget), config, attribute === 'src')}${quote}`,
+  )
+}
+
+function readFileIfExists(filePath: string): string | undefined {
+  try {
+    return readFileSync(filePath, 'utf8')
+  } catch (error) {
+    if (isNodeErrorWithCode(error, 'ENOENT')) {
+      return undefined
+    }
+
+    throw error
+  }
+}
+
+function rewriteMarkdownLinkMatches(
+  line: string,
+  config: PublishReadmeConfig,
+  pattern: RegExp,
+): string {
+  return line.replaceAll(pattern, (_match, label: string, rawTarget: string, ...rest) => {
+    const title = typeof rest[0] === 'string' ? rest[0] : ''
+
+    return `${label}(${rewriteTarget(rawTarget, config, label.startsWith('!'))}${title})`
+  })
+}
+
+function rewriteMarkdownLinks(line: string, config: PublishReadmeConfig): string {
+  return [
+    /(!?\[[^\]\r\n]+])\((<[^>\r\n]+>)(\s+"[^"\r\n]*")\)/g,
+    /(!?\[[^\]\r\n]+])\((<[^>\r\n]+>)(\s+'[^'\r\n]*')\)/g,
+    /(!?\[[^\]\r\n]+])\((<[^>\r\n]+>)\)/g,
+    /(!?\[[^\]\r\n]+])\(([^()\s]+)(\s+"[^"\r\n]*")\)/g,
+    /(!?\[[^\]\r\n]+])\(([^()\s]+)(\s+'[^'\r\n]*')\)/g,
+    /(!?\[[^\]\r\n]+])\(([^()\s]+)\)/g,
+  ].reduce(
+    (rewrittenLine, pattern) => rewriteMarkdownLinkMatches(rewrittenLine, config, pattern),
+    line,
+  )
+}
+
+export function rewriteReadmeForPublish(
+  readmeContent: string,
+  config: PublishReadmeConfig,
+): string {
+  const lines = readmeContent.split('\n')
+  let activeFence: '```' | '~~~' | undefined = undefined
+
+  return lines
+    .map((line) => {
+      const trimmedLine = line.trimStart()
+      const fenceMarker = trimmedLine.startsWith('```')
+        ? '```'
+        : trimmedLine.startsWith('~~~')
+          ? '~~~'
+          : undefined
+
+      if (fenceMarker !== undefined) {
+        activeFence = activeFence === fenceMarker ? undefined : fenceMarker
+        return line
+      }
+
+      if (activeFence !== undefined) {
+        return line
+      }
+
+      return rewriteHtmlTargets(rewriteMarkdownLinks(line, config), config)
+    })
+    .join('\n')
+}
+
+export function preparePublishReadme(
+  packageDir = '.',
+  overrides: PublishReadmeOverrides = {},
+): void {
+  const resolvedPackageDir = path.resolve(packageDir)
+  const readmePath = getReadmePath(resolvedPackageDir)
+  const backupPath = getReadmeBackupPath(resolvedPackageDir)
+  const backupReadme = readFileIfExists(backupPath)
+
+  if (backupReadme !== undefined) {
+    writeFileSync(readmePath, backupReadme)
+    rmSync(backupPath, { force: true })
+  }
+
+  const originalReadme = readFileIfExists(readmePath)
+
+  if (originalReadme === undefined) {
+    return
+  }
+  const rewrittenReadme = rewriteReadmeForPublish(
+    originalReadme,
+    getPublishReadmeConfig(resolvedPackageDir, overrides),
+  )
+
+  if (rewrittenReadme === originalReadme) {
+    return
+  }
+
+  mkdirSync(path.dirname(backupPath), { recursive: true })
+  writeFileSync(backupPath, originalReadme)
+  writeFileSync(readmePath, rewrittenReadme)
+}
+
+export function restorePublishReadme(packageDir = '.'): void {
+  const resolvedPackageDir = path.resolve(packageDir)
+  const backupPath = getReadmeBackupPath(resolvedPackageDir)
+  const originalReadme = readFileIfExists(backupPath)
+
+  if (originalReadme === undefined) {
+    return
+  }
+
+  writeFileSync(getReadmePath(resolvedPackageDir), originalReadme)
+  rmSync(backupPath, { force: true })
+}
diff --git a/packages/node/node-sdk/README.md b/packages/node/node-sdk/README.md
index 1504ad7c..8338b15b 100644
--- a/packages/node/node-sdk/README.md
+++ b/packages/node/node-sdk/README.md
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/node/node-sdk/package.json b/packages/node/node-sdk/package.json
index 6b8b95e8..e019f4f3 100644
--- a/packages/node/node-sdk/package.json
+++ b/packages/node/node-sdk/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-node",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/node/node-sdk"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/react-native-sdk/README.md b/packages/react-native-sdk/README.md
index 9284a781..5a5e59a2 100644
--- a/packages/react-native-sdk/README.md
+++ b/packages/react-native-sdk/README.md
@@ -8,8 +8,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/react-native-sdk/package.json b/packages/react-native-sdk/package.json
index 33f47bfc..a6a3b50a 100644
--- a/packages/react-native-sdk/package.json
+++ b/packages/react-native-sdk/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-react-native",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/react-native-sdk"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx b/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx
index 31768779..c583295c 100644
--- a/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx
+++ b/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx
@@ -14,7 +14,7 @@ function paramsToJson(params: Record<string, unknown>): z.core.util.JSONType {
 /**
  * @internal
  */
-interface NavigationState {
+export interface NavigationState {
   index: number
   routes: Array<{
     name: string
@@ -26,7 +26,7 @@ interface NavigationState {
 /**
  * @internal
  */
-interface NavigationContainerRef {
+export interface NavigationContainerRef {
   getCurrentRoute: () => { name: string; params?: Record<string, unknown> } | undefined
 }
 
diff --git a/packages/react-native-sdk/src/components/OptimizationProvider.tsx b/packages/react-native-sdk/src/components/OptimizationProvider.tsx
index 66b038a8..6664a7db 100644
--- a/packages/react-native-sdk/src/components/OptimizationProvider.tsx
+++ b/packages/react-native-sdk/src/components/OptimizationProvider.tsx
@@ -9,7 +9,7 @@ const logger = createScopedLogger('RN:Provider')
 /**
  * Props for the {@link OptimizationProvider} component.
  *
- * Accepts all {@link OptimizationConfig} properties directly. Only `clientId` is required.
+ * Accepts all `OptimizationConfig` properties directly. Only `clientId` is required.
  *
  * @public
  */
diff --git a/packages/react-native-sdk/src/context/InteractionTrackingContext.tsx b/packages/react-native-sdk/src/context/InteractionTrackingContext.tsx
index 557f0d9b..682889d9 100644
--- a/packages/react-native-sdk/src/context/InteractionTrackingContext.tsx
+++ b/packages/react-native-sdk/src/context/InteractionTrackingContext.tsx
@@ -28,7 +28,7 @@ export type TrackEntryInteractionOptions = Partial<Record<EntryInteraction, bool
  *
  * @internal
  */
-interface InteractionTrackingContextValue {
+export interface InteractionTrackingContextValue {
   /** Whether view tracking is enabled globally. */
   views: boolean
   /** Whether tap tracking is enabled globally. */
@@ -45,7 +45,7 @@ const InteractionTrackingContext = createContext<InteractionTrackingContextValue
 
 /**
  * Returns the resolved interaction tracking configuration from the nearest
- * {@link InteractionTrackingProvider}.
+ * `InteractionTrackingProvider`.
  *
  * @returns The resolved interaction tracking state with `views` and `taps` booleans.
  *
diff --git a/packages/react-native-sdk/src/context/LiveUpdatesContext.tsx b/packages/react-native-sdk/src/context/LiveUpdatesContext.tsx
index 9dfb9b23..4d638fd1 100644
--- a/packages/react-native-sdk/src/context/LiveUpdatesContext.tsx
+++ b/packages/react-native-sdk/src/context/LiveUpdatesContext.tsx
@@ -3,7 +3,7 @@ import React, { createContext, useContext, useState, type ReactNode } from 'reac
 /**
  * @internal
  */
-interface LiveUpdatesContextValue {
+export interface LiveUpdatesContextValue {
   globalLiveUpdates: boolean
   previewPanelVisible: boolean
   setPreviewPanelVisible: (visible: boolean) => void
@@ -34,7 +34,7 @@ export function useLiveUpdates(): LiveUpdatesContextValue | null {
 /**
  * @internal
  */
-interface LiveUpdatesProviderProps {
+export interface LiveUpdatesProviderProps {
   globalLiveUpdates?: boolean
   children: ReactNode
 }
diff --git a/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx b/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx
index 9404418b..ae3422b8 100644
--- a/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx
+++ b/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx
@@ -13,7 +13,7 @@ const logger = createScopedLogger('RN:Scroll')
 /**
  * @internal
  */
-interface ScrollContextValue {
+export interface ScrollContextValue {
   scrollY: number
   viewportHeight: number
 }
diff --git a/packages/react-native-sdk/src/hooks/useTapTracking.ts b/packages/react-native-sdk/src/hooks/useTapTracking.ts
index 9fc2e2ed..97882211 100644
--- a/packages/react-native-sdk/src/hooks/useTapTracking.ts
+++ b/packages/react-native-sdk/src/hooks/useTapTracking.ts
@@ -72,7 +72,7 @@ export interface UseTapTrackingReturn {
  * Uses `onTouchStart`/`onTouchEnd` rather than wrapping children in a
  * `Pressable`, so taps are captured even when a child `Pressable` handles
  * the gesture. A touch is classified as a tap only when the finger moves
- * less than {@link TAP_DISTANCE_THRESHOLD} points between start and end.
+ * less than `TAP_DISTANCE_THRESHOLD` points between start and end.
  *
  * @example
  * ```tsx
diff --git a/packages/react-native-sdk/src/index.ts b/packages/react-native-sdk/src/index.ts
index 1624ea06..76c2ac50 100644
--- a/packages/react-native-sdk/src/index.ts
+++ b/packages/react-native-sdk/src/index.ts
@@ -33,14 +33,22 @@ export { OptimizedEntry } from './components/OptimizedEntry'
 export type { OptimizedEntryProps } from './components/OptimizedEntry'
 
 export { OptimizationScrollProvider, useScrollContext } from './context/OptimizationScrollContext'
-export type { OptimizationScrollProviderProps } from './context/OptimizationScrollContext'
+export type {
+  OptimizationScrollProviderProps,
+  ScrollContextValue,
+} from './context/OptimizationScrollContext'
 
 export { LiveUpdatesProvider, useLiveUpdates } from './context/LiveUpdatesContext'
+export type {
+  LiveUpdatesContextValue,
+  LiveUpdatesProviderProps,
+} from './context/LiveUpdatesContext'
 export { useOptimization } from './context/OptimizationContext'
 
 export { useInteractionTracking } from './context/InteractionTrackingContext'
 export type {
   EntryInteraction,
+  InteractionTrackingContextValue,
   TrackEntryInteractionOptions,
 } from './context/InteractionTrackingContext'
 
@@ -58,12 +66,18 @@ export { useScreenTracking, useScreenTrackingCallback } from './hooks/useScreenT
 export type { UseScreenTrackingOptions, UseScreenTrackingReturn } from './hooks/useScreenTracking'
 
 export { OptimizationNavigationContainer } from './components/OptimizationNavigationContainer'
-export type { OptimizationNavigationContainerProps } from './components/OptimizationNavigationContainer'
+export type {
+  NavigationContainerRef,
+  NavigationState,
+  OptimizationNavigationContainerProps,
+} from './components/OptimizationNavigationContainer'
 
 export { PreviewPanel as OptimizationPreviewPanel } from './preview/components/PreviewPanel'
 export { PreviewPanelOverlay } from './preview/components/PreviewPanelOverlay'
 export type {
   ContentfulClient,
+  ContentfulEntry,
+  ContentfulEntryCollection,
   PreviewPanelConfig,
   PreviewPanelOverlayProps,
   PreviewPanelProps,
diff --git a/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx b/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx
index 9f195a83..84dc45a3 100644
--- a/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx
+++ b/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx
@@ -48,7 +48,7 @@ function PreviewPanelHeader({ consent }: { consent: boolean | undefined }): Reac
  * @returns The rendered preview panel
  *
  * @remarks
- * Must be used within a {@link PreviewOverrideProvider} (typically provided by
+ * Must be used within a `PreviewOverrideProvider` (typically provided by
  * {@link PreviewPanelOverlay} or {@link OptimizationRoot}).
  *
  * @example
diff --git a/packages/react-native-sdk/src/preview/components/PreviewPanelOverlay.tsx b/packages/react-native-sdk/src/preview/components/PreviewPanelOverlay.tsx
index fd4b2621..b7f7bdc9 100644
--- a/packages/react-native-sdk/src/preview/components/PreviewPanelOverlay.tsx
+++ b/packages/react-native-sdk/src/preview/components/PreviewPanelOverlay.tsx
@@ -25,8 +25,8 @@ const ANIMATION_DURATION_MS = 200
 const DRAG_HANDLE_HEIGHT = 4
 
 /**
- * Renders app content with a floating action button that opens the {@link PreviewPanel}
- * in a bottom-sheet modal. Wraps children in a {@link PreviewOverrideProvider} to
+ * Renders app content with a floating action button that opens the `PreviewPanel`
+ * in a bottom-sheet modal. Wraps children in a `PreviewOverrideProvider` to
  * persist override state across modal open/close cycles.
  *
  * @param props - Component props
diff --git a/packages/react-native-sdk/src/preview/context/PreviewOverrideContext.tsx b/packages/react-native-sdk/src/preview/context/PreviewOverrideContext.tsx
index 3863b50c..470009e5 100644
--- a/packages/react-native-sdk/src/preview/context/PreviewOverrideContext.tsx
+++ b/packages/react-native-sdk/src/preview/context/PreviewOverrideContext.tsx
@@ -10,11 +10,11 @@ interface PreviewOverrideContextValue {
 const PreviewOverrideContext = createContext<PreviewOverrideContextValue | null>(null)
 
 /**
- * Returns the preview override state and actions from the nearest {@link PreviewOverrideProvider}.
+ * Returns the preview override state and actions from the nearest `PreviewOverrideProvider`.
  *
  * @returns The current override state and action handlers
  *
- * @throws Error if called outside of a {@link PreviewOverrideProvider}
+ * @throws Error if called outside of a `PreviewOverrideProvider`
  *
  * @internal
  */
@@ -37,7 +37,7 @@ interface PreviewOverrideProviderProps {
 
 /**
  * Hosts preview override state and SDK registration logic, allowing the
- * {@link PreviewPanel} to be unmounted/remounted without losing state.
+ * `PreviewPanel` to be unmounted/remounted without losing state.
  *
  * @param props - Provider props
  * @returns A context provider wrapping the children
diff --git a/packages/react-native-sdk/src/preview/types.ts b/packages/react-native-sdk/src/preview/types.ts
index ce906075..f1eda4c4 100644
--- a/packages/react-native-sdk/src/preview/types.ts
+++ b/packages/react-native-sdk/src/preview/types.ts
@@ -219,7 +219,7 @@ export interface PreviewActions {
 }
 
 /**
- * Props for the {@link PreviewPanel} component.
+ * Props for the `PreviewPanel` component.
  *
  * @public
  */
diff --git a/packages/universal/api-client/README.md b/packages/universal/api-client/README.md
index 63fcbdad..a5abe286 100644
--- a/packages/universal/api-client/README.md
+++ b/packages/universal/api-client/README.md
@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.contentful.com/developers/docs/personalization/">
-    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="../../../contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/universal/api-client/package.json b/packages/universal/api-client/package.json
index 8d13e3c9..d9e95d40 100644
--- a/packages/universal/api-client/package.json
+++ b/packages/universal/api-client/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-api-client",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/universal/api-client"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/universal/api-client/src/ApiClient.ts b/packages/universal/api-client/src/ApiClient.ts
index a58c2faf..2be4ecb9 100644
--- a/packages/universal/api-client/src/ApiClient.ts
+++ b/packages/universal/api-client/src/ApiClient.ts
@@ -1,6 +1,6 @@
 import type { ApiConfig, GlobalApiConfigProperties } from './ApiClientBase'
-import ExperienceApiClient, { type ExperienceApiClientConfig } from './experience'
-import InsightsApiClient, { type InsightsApiClientConfig } from './insights'
+import { ExperienceApiClient, type ExperienceApiClientConfig } from './experience'
+import { InsightsApiClient, type InsightsApiClientConfig } from './insights'
 
 /**
  * Configuration for the high-level {@link ApiClient}.
diff --git a/packages/universal/api-client/src/ApiClientBase.ts b/packages/universal/api-client/src/ApiClientBase.ts
index 139fe7d7..2db0d5eb 100644
--- a/packages/universal/api-client/src/ApiClientBase.ts
+++ b/packages/universal/api-client/src/ApiClientBase.ts
@@ -11,7 +11,7 @@ const logger = createScopedLogger('ApiClient')
 const DEFAULT_ENVIRONMENT = 'main'
 
 /**
- * Configuration options for API clients extending {@link ApiClientBase}.
+ * Configuration options for API clients extending `ApiClientBase`.
  *
  * @public
  */
diff --git a/packages/universal/api-client/src/experience/ExperienceApiClient.ts b/packages/universal/api-client/src/experience/ExperienceApiClient.ts
index 95f5ea28..67cffd82 100644
--- a/packages/universal/api-client/src/experience/ExperienceApiClient.ts
+++ b/packages/universal/api-client/src/experience/ExperienceApiClient.ts
@@ -7,7 +7,7 @@ import {
   parseWithFriendlyError,
   type BatchExperienceEventArray,
   type BatchExperienceResponseData,
-  type ExperienceRequestOptions,
+  type ExperienceRequestOptions as ExperienceRequestBodyOptions,
   type OptimizationData,
 } from '@contentful/optimization-api-schemas'
 import ApiClientBase, { type ApiConfig } from '../ApiClientBase'
@@ -27,14 +27,14 @@ export const EXPERIENCE_BASE_URL = 'https://experience.ninetailed.co/'
  *
  * @internal
  */
-type Feature = 'ip-enrichment' | 'location'
+export type Feature = 'ip-enrichment' | 'location'
 
 /**
  * Options that control how requests to the Experience API are handled.
  *
- * @internal
+ * @public
  */
-interface RequestOptions {
+export interface ExperienceApiClientRequestOptions {
   /**
    * Enabled features (for example, `"ip-enrichment"`) which the API should use for this request.
    *
@@ -87,15 +87,15 @@ interface RequestOptions {
 interface ProfileMutationRequestOptions {
   url: string
   body: unknown
-  options: RequestOptions
+  options: ExperienceApiClientRequestOptions
 }
 
 /**
  * Parameters used when creating a profile.
  *
- * @internal
+ * @public
  */
-interface CreateProfileParams {
+export interface CreateProfileParams {
   /**
    * Events used to aggregate the profile state.
    */
@@ -105,9 +105,9 @@ interface CreateProfileParams {
 /**
  * Parameters used when updating an existing profile.
  *
- * @internal
+ * @public
  */
-interface UpdateProfileParams extends CreateProfileParams {
+export interface UpdateProfileParams extends CreateProfileParams {
   /**
    * ID of the profile to update.
    */
@@ -117,9 +117,9 @@ interface UpdateProfileParams extends CreateProfileParams {
 /**
  * Parameters used when creating or updating a profile.
  *
- * @internal
+ * @public
  */
-interface UpsertProfileParams extends CreateProfileParams {
+export interface UpsertProfileParams extends CreateProfileParams {
   /**
    * Optional ID of the profile; when omitted, a new profile is created.
    */
@@ -129,9 +129,9 @@ interface UpsertProfileParams extends CreateProfileParams {
 /**
  * Parameters used when performing a batch profile update.
  *
- * @internal
+ * @public
  */
-interface BatchUpdateProfileParams {
+export interface BatchUpdateProfileParams {
   /**
    * Batch of events to process.
    */
@@ -143,7 +143,7 @@ interface BatchUpdateProfileParams {
  *
  * @public
  */
-export interface ExperienceApiClientConfig extends ApiConfig, RequestOptions {}
+export interface ExperienceApiClientConfig extends ApiConfig, ExperienceApiClientRequestOptions {}
 
 /**
  * Client for interacting with the Experience API.
@@ -162,7 +162,7 @@ export interface ExperienceApiClientConfig extends ApiConfig, RequestOptions {}
  * const profile = await client.getProfile('profile-id')
  * ```
  *
- * @see {@link ApiClientBase}
+ * Extends `ApiClientBase`.
  *
  * @public
  */
@@ -172,11 +172,11 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   protected readonly baseUrl: string
 
-  private readonly enabledFeatures?: RequestOptions['enabledFeatures']
-  private readonly ip?: RequestOptions['ip']
-  private readonly locale?: RequestOptions['locale']
-  private readonly plainText?: RequestOptions['plainText']
-  private readonly preflight?: RequestOptions['preflight']
+  private readonly enabledFeatures?: ExperienceApiClientRequestOptions['enabledFeatures']
+  private readonly ip?: ExperienceApiClientRequestOptions['ip']
+  private readonly locale?: ExperienceApiClientRequestOptions['locale']
+  private readonly plainText?: ExperienceApiClientRequestOptions['plainText']
+  private readonly preflight?: ExperienceApiClientRequestOptions['preflight']
 
   /**
    * Creates a new {@link ExperienceApiClient} instance.
@@ -204,7 +204,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    * @param options - Optional request options. `preflight` and `plainText` are not allowed here.
    * @returns The current optimization data for the profile.
    *
-   * @throws {@link Error}
+   * @throws Error
    * Thrown if `id` is missing or the underlying request fails.
    *
    * @example
@@ -216,7 +216,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   public async getProfile(
     id: string,
-    options: Omit<RequestOptions, 'preflight' | 'plainText'> = {},
+    options: Omit<ExperienceApiClientRequestOptions, 'preflight' | 'plainText'> = {},
   ): Promise<OptimizationData> {
     if (!id) throw new Error('Valid profile ID required.')
 
@@ -291,7 +291,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   public async createProfile(
     { events }: CreateProfileParams,
-    options: RequestOptions = {},
+    options: ExperienceApiClientRequestOptions = {},
   ): Promise<OptimizationData> {
     const requestName = 'Create Profile'
 
@@ -331,7 +331,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    * @param options - Optional request options.
    * @returns The updated optimization data for the profile.
    *
-   * @throws {@link Error}
+   * @throws Error
    * Thrown if `profileId` is missing or the underlying request fails.
    *
    * @example
@@ -344,7 +344,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   public async updateProfile(
     { profileId, events }: UpdateProfileParams,
-    options: RequestOptions = {},
+    options: ExperienceApiClientRequestOptions = {},
   ): Promise<OptimizationData> {
     if (!profileId) throw new Error('Valid profile ID required.')
 
@@ -397,7 +397,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   public async upsertProfile(
     { profileId, events }: UpsertProfileParams,
-    options?: RequestOptions,
+    options?: ExperienceApiClientRequestOptions,
   ): Promise<OptimizationData> {
     if (!profileId) {
       return await this.createProfile({ events }, options)
@@ -432,7 +432,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   public async upsertManyProfiles(
     { events }: BatchUpdateProfileParams,
-    options: RequestOptions = {},
+    options: ExperienceApiClientRequestOptions = {},
   ): Promise<BatchExperienceResponseData['profiles']> {
     const requestName = 'Upsert Many Profiles'
 
@@ -475,7 +475,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    *
    * @internal
    */
-  private constructUrl(path: string, options: RequestOptions): string {
+  private constructUrl(path: string, options: ExperienceApiClientRequestOptions): string {
     const url = new URL(path, this.baseUrl)
     const locale = options.locale ?? this.locale
     const preflight = options.preflight ?? this.preflight
@@ -502,7 +502,7 @@ export default class ExperienceApiClient extends ApiClientBase {
   private constructHeaders({
     ip = this.ip,
     plainText = this.plainText,
-  }: RequestOptions): Record<string, string> {
+  }: ExperienceApiClientRequestOptions): Record<string, string> {
     const headers = new Map<string, string>()
 
     if (ip) {
@@ -528,8 +528,8 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   private readonly constructBodyOptions = ({
     enabledFeatures = this.enabledFeatures,
-  }: RequestOptions): ExperienceRequestOptions => {
-    const bodyOptions: ExperienceRequestOptions = {}
+  }: ExperienceApiClientRequestOptions): ExperienceRequestBodyOptions => {
+    const bodyOptions: ExperienceRequestBodyOptions = {}
 
     if (enabledFeatures && Array.isArray(enabledFeatures) && enabledFeatures.length > 0) {
       bodyOptions.features = enabledFeatures
@@ -551,7 +551,7 @@ export default class ExperienceApiClient extends ApiClientBase {
    */
   private constructExperienceRequestBody(
     events: ExperienceEventArray,
-    options: RequestOptions,
+    options: ExperienceApiClientRequestOptions,
   ): ExperienceRequestData {
     return ExperienceRequestData.parse({
       events: parseWithFriendlyError(ExperienceEventArray, events),
diff --git a/packages/universal/api-client/src/experience/index.ts b/packages/universal/api-client/src/experience/index.ts
index 08c2f991..871f9730 100644
--- a/packages/universal/api-client/src/experience/index.ts
+++ b/packages/universal/api-client/src/experience/index.ts
@@ -1,5 +1,2 @@
-import ExperienceApiClient from './ExperienceApiClient'
-
 export * from './ExperienceApiClient'
-
-export default ExperienceApiClient
+export { default as ExperienceApiClient, default } from './ExperienceApiClient'
diff --git a/packages/universal/api-client/src/fetch/createProtectedFetchMethod.ts b/packages/universal/api-client/src/fetch/createProtectedFetchMethod.ts
index 9d7d99b0..07c16255 100644
--- a/packages/universal/api-client/src/fetch/createProtectedFetchMethod.ts
+++ b/packages/universal/api-client/src/fetch/createProtectedFetchMethod.ts
@@ -25,7 +25,7 @@ export interface ProtectedFetchMethodOptions
  * @param options - Configuration options for both timeout and retry behavior.
  * @returns A {@link FetchMethod} that applies timeout and retry logic to requests.
  *
- * @throws {@link Error}
+ * @throws Error
  * Rethrows the original error after logging, including abort errors.
  *
  * @remarks
diff --git a/packages/universal/api-client/src/fetch/createRetryFetchMethod.ts b/packages/universal/api-client/src/fetch/createRetryFetchMethod.ts
index 983f2511..d22b5f06 100644
--- a/packages/universal/api-client/src/fetch/createRetryFetchMethod.ts
+++ b/packages/universal/api-client/src/fetch/createRetryFetchMethod.ts
@@ -195,7 +195,7 @@ async function delayRetry(intervalTimeout: number): Promise<void> {
  * @param options - Configuration options that control retry behavior.
  * @returns A {@link FetchMethod} that automatically retries qualifying failures.
  *
- * @throws {@link Error}
+ * @throws Error
  * Thrown when the request cannot be retried and no successful response is obtained.
  *
  * @remarks
diff --git a/packages/universal/api-client/src/fetch/createTimeoutFetchMethod.ts b/packages/universal/api-client/src/fetch/createTimeoutFetchMethod.ts
index dc82a441..b1e9e8a5 100644
--- a/packages/universal/api-client/src/fetch/createTimeoutFetchMethod.ts
+++ b/packages/universal/api-client/src/fetch/createTimeoutFetchMethod.ts
@@ -44,7 +44,7 @@ export interface TimeoutFetchMethodOptions extends BaseFetchMethodOptions {
  *
  * @remarks
  * When a timeout occurs, the request is aborted using an {@link AbortController}.
- * If `onRequestTimeout` is not provided, an error is logged by the {@link logger}.
+ * If `onRequestTimeout` is not provided, an error is logged by the package logger.
  *
  * @example
  * ```ts
diff --git a/packages/universal/api-client/src/index.ts b/packages/universal/api-client/src/index.ts
index c7ae07ae..3d559958 100644
--- a/packages/universal/api-client/src/index.ts
+++ b/packages/universal/api-client/src/index.ts
@@ -11,4 +11,5 @@ export { default as ApiClient } from './ApiClient'
 export * from './ApiClient'
 export * from './ApiClientBase'
 export * from './experience'
+export * from './fetch'
 export * from './insights'
diff --git a/packages/universal/api-client/src/insights/InsightsApiClient.ts b/packages/universal/api-client/src/insights/InsightsApiClient.ts
index ec4e90aa..c980bb13 100644
--- a/packages/universal/api-client/src/insights/InsightsApiClient.ts
+++ b/packages/universal/api-client/src/insights/InsightsApiClient.ts
@@ -17,9 +17,9 @@ export const INSIGHTS_BASE_URL = 'https://ingest.insights.ninetailed.co/'
 /**
  * Options that control how Insights events are sent.
  *
- * @internal
+ * @public
  */
-interface RequestOptions {
+export interface InsightsApiClientRequestOptions {
   /**
    * Handler used to enqueue events via the Beacon API or a similar mechanism.
    *
@@ -40,7 +40,7 @@ interface RequestOptions {
  *
  * @public
  */
-export interface InsightsApiClientConfig extends ApiConfig, RequestOptions {}
+export interface InsightsApiClientConfig extends ApiConfig, InsightsApiClientRequestOptions {}
 
 /**
  * Client for sending analytics and insights events to the Ninetailed Insights API.
@@ -70,7 +70,7 @@ export interface InsightsApiClientConfig extends ApiConfig, RequestOptions {}
  * ])
  * ```
  *
- * @see {@link ApiClientBase}
+ * Extends `ApiClientBase`.
  *
  * @public
  */
@@ -83,7 +83,7 @@ export default class InsightsApiClient extends ApiClientBase {
   /**
    * Optional handler used to enqueue events via the Beacon API or a similar mechanism.
    */
-  private readonly beaconHandler: RequestOptions['beaconHandler']
+  private readonly beaconHandler: InsightsApiClientRequestOptions['beaconHandler']
 
   /**
    * Creates a new {@link InsightsApiClient} instance.
@@ -145,7 +145,7 @@ export default class InsightsApiClient extends ApiClientBase {
    */
   public async sendBatchEvents(
     batches: BatchInsightsEventArray,
-    options: RequestOptions = {},
+    options: InsightsApiClientRequestOptions = {},
   ): Promise<boolean> {
     const { beaconHandler = this.beaconHandler } = options
 
diff --git a/packages/universal/api-client/src/insights/index.ts b/packages/universal/api-client/src/insights/index.ts
index 938f04d6..2da5e106 100644
--- a/packages/universal/api-client/src/insights/index.ts
+++ b/packages/universal/api-client/src/insights/index.ts
@@ -1,5 +1,2 @@
-import InsightsApiClient from './InsightsApiClient'
-
 export * from './InsightsApiClient'
-
-export default InsightsApiClient
+export { default as InsightsApiClient, default } from './InsightsApiClient'
diff --git a/packages/universal/api-schemas/README.md b/packages/universal/api-schemas/README.md
index e798d0eb..acf61888 100644
--- a/packages/universal/api-schemas/README.md
+++ b/packages/universal/api-schemas/README.md
@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.contentful.com/developers/docs/personalization/">
-    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="../../../contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/universal/api-schemas/package.json b/packages/universal/api-schemas/package.json
index 49c3ff72..cbfd00b9 100644
--- a/packages/universal/api-schemas/package.json
+++ b/packages/universal/api-schemas/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-api-schemas",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/universal/api-schemas"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/universal/api-schemas/src/contentful/CtflEntry.ts b/packages/universal/api-schemas/src/contentful/CtflEntry.ts
index df92a707..876c8c7d 100644
--- a/packages/universal/api-schemas/src/contentful/CtflEntry.ts
+++ b/packages/universal/api-schemas/src/contentful/CtflEntry.ts
@@ -107,7 +107,7 @@ export type SpaceLink = z.infer<typeof SpaceLink>
  *
  * @internal
  */
-const TaxonomyConceptLink = z.object({
+export const TaxonomyConceptLink = z.object({
   sys: z.object({
     type: z.literal('Link'),
     linkType: z.literal('TaxonomyConcept'),
diff --git a/packages/universal/api-schemas/src/experience/change/Change.ts b/packages/universal/api-schemas/src/experience/change/Change.ts
index cd4fb187..e2354348 100644
--- a/packages/universal/api-schemas/src/experience/change/Change.ts
+++ b/packages/universal/api-schemas/src/experience/change/Change.ts
@@ -5,7 +5,7 @@ import * as z from 'zod/mini'
  *
  * @remarks
  * Currently only the `'Variable'` change type is supported, but the union
- * in {@link ChangeBase} allows for additional types to be introduced.
+ * in `ChangeBase` allows for additional types to be introduced.
  *
  * @public
  */
@@ -19,7 +19,7 @@ export const ChangeType = ['Variable'] as const
  *
  * @internal
  */
-const ChangeBase = z.object({
+export const ChangeBase = z.object({
   /**
    * Key identifying the subject of the change.
    */
@@ -111,7 +111,7 @@ export const VariableChange = z.extend(ChangeBase, {
   type: z.literal('Variable'),
 
   /**
-   * New value for the variable identified by {@link ChangeBase.key}.
+   * New value for the variable identified by `ChangeBase.key`.
    */
   value: VariableChangeValue,
 })
diff --git a/packages/universal/api-schemas/src/experience/index.ts b/packages/universal/api-schemas/src/experience/index.ts
index 9130d495..0b885a5a 100644
--- a/packages/universal/api-schemas/src/experience/index.ts
+++ b/packages/universal/api-schemas/src/experience/index.ts
@@ -6,3 +6,4 @@ export * from './ExperienceRequest'
 export * from './ExperienceResponse'
 export * from './optimization'
 export * from './profile'
+export * from './ResponseEnvelope'
diff --git a/packages/universal/api-schemas/src/experience/optimization/SelectedOptimization.ts b/packages/universal/api-schemas/src/experience/optimization/SelectedOptimization.ts
index 68217e19..0a62bef3 100644
--- a/packages/universal/api-schemas/src/experience/optimization/SelectedOptimization.ts
+++ b/packages/universal/api-schemas/src/experience/optimization/SelectedOptimization.ts
@@ -20,7 +20,7 @@ export const SelectedOptimization = z.object({
    * Index of the selected variant within the experience configuration.
    *
    * @remarks
-   * Typically corresponds to the index of the selected {@link OptimizationConfig } entry.
+   * Typically corresponds to the index of the selected `OptimizationConfig` entry.
    */
   variantIndex: z.number(),
 
diff --git a/packages/universal/api-schemas/src/experience/profile/properties/SessionStatistics.ts b/packages/universal/api-schemas/src/experience/profile/properties/SessionStatistics.ts
index 01fb3ac6..846a74a6 100644
--- a/packages/universal/api-schemas/src/experience/profile/properties/SessionStatistics.ts
+++ b/packages/universal/api-schemas/src/experience/profile/properties/SessionStatistics.ts
@@ -38,7 +38,7 @@ export const SessionStatistics = z.object({
    * Number of sessions associated with this profile or identifier.
    *
    * @remarks
-   * Often used in combination with {@link SessionStatistics.averageSessionLength}.
+   * Often used in combination with `SessionStatistics.averageSessionLength`.
    */
   count: z.number(),
 
@@ -51,7 +51,7 @@ export const SessionStatistics = z.object({
    * Average session duration across all sessions represented by this record.
    *
    * @remarks
-   * The unit should match {@link SessionStatistics.activeSessionLength}.
+   * The unit should match `SessionStatistics.activeSessionLength`.
    */
   averageSessionLength: z.number(),
 })
diff --git a/packages/universal/core-sdk/README.md b/packages/universal/core-sdk/README.md
index f0c3defb..802fe0a9 100644
--- a/packages/universal/core-sdk/README.md
+++ b/packages/universal/core-sdk/README.md
@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.contentful.com/developers/docs/personalization/">
-    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="../../../contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/universal/core-sdk/package.json b/packages/universal/core-sdk/package.json
index 13afd111..d34a97e7 100644
--- a/packages/universal/core-sdk/package.json
+++ b/packages/universal/core-sdk/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-core",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/universal/core-sdk"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/universal/core-sdk/src/CoreBase.ts b/packages/universal/core-sdk/src/CoreBase.ts
index 32c9de1f..6f708199 100644
--- a/packages/universal/core-sdk/src/CoreBase.ts
+++ b/packages/universal/core-sdk/src/CoreBase.ts
@@ -82,7 +82,7 @@ export interface LifecycleInterceptors {
 }
 
 /**
- * Options for configuring the {@link CoreBase} runtime and underlying clients.
+ * Options for configuring the `CoreBase` runtime and underlying clients.
  *
  * @public
  */
diff --git a/packages/universal/core-sdk/src/CoreStateless.ts b/packages/universal/core-sdk/src/CoreStateless.ts
index 12c53685..00c1535b 100644
--- a/packages/universal/core-sdk/src/CoreStateless.ts
+++ b/packages/universal/core-sdk/src/CoreStateless.ts
@@ -37,7 +37,7 @@ export interface CoreStatelessConfig extends Omit<CoreConfig, 'api'> {
  * Core runtime for stateless environments.
  *
  * @public
- * @see {@link CoreBase}
+ * Built on top of `CoreBase`.
  */
 class CoreStateless extends CoreBase {
   constructor(config: CoreStatelessConfig) {
diff --git a/packages/universal/core-sdk/src/events/EventBuilder.ts b/packages/universal/core-sdk/src/events/EventBuilder.ts
index 82eb8125..5dd9207a 100644
--- a/packages/universal/core-sdk/src/events/EventBuilder.ts
+++ b/packages/universal/core-sdk/src/events/EventBuilder.ts
@@ -107,7 +107,7 @@ export interface EventBuilderConfig {
   getUserAgent?: () => string | undefined
 }
 
-const UniversalEventBuilderArgs = z.object({
+export const UniversalEventBuilderArgs = z.object({
   campaign: z.optional(Campaign),
   locale: z.optional(z.string()),
   location: z.optional(GeoLocation),
@@ -123,7 +123,7 @@ const UniversalEventBuilderArgs = z.object({
  */
 export type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs>
 
-const EntryInteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {
+export const EntryInteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {
   componentId: z.string(),
   experienceId: z.optional(z.string()),
   variantIndex: z.optional(z.number()),
@@ -136,7 +136,7 @@ const EntryInteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {
  */
 export type EntryInteractionBuilderArgsBase = z.infer<typeof EntryInteractionBuilderArgsBase>
 
-const ViewBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
+export const ViewBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
   sticky: z.optional(z.boolean()),
   viewId: z.string(),
   viewDurationMs: z.number(),
@@ -149,7 +149,7 @@ const ViewBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
  */
 export type ViewBuilderArgs = z.infer<typeof ViewBuilderArgs>
 
-const FlagViewBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
+export const FlagViewBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
   viewId: z.optional(z.string()),
   viewDurationMs: z.optional(z.number()),
 })
@@ -161,7 +161,7 @@ const FlagViewBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
  */
 export type FlagViewBuilderArgs = z.infer<typeof FlagViewBuilderArgs>
 
-const ClickBuilderArgs = EntryInteractionBuilderArgsBase
+export const ClickBuilderArgs = EntryInteractionBuilderArgsBase
 
 /**
  * Arguments for constructing entry click events.
@@ -170,7 +170,7 @@ const ClickBuilderArgs = EntryInteractionBuilderArgsBase
  */
 export type ClickBuilderArgs = z.infer<typeof ClickBuilderArgs>
 
-const HoverBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
+export const HoverBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
   hoverId: z.string(),
   hoverDurationMs: z.number(),
 })
@@ -182,7 +182,7 @@ const HoverBuilderArgs = z.extend(EntryInteractionBuilderArgsBase, {
  */
 export type HoverBuilderArgs = z.infer<typeof HoverBuilderArgs>
 
-const IdentifyBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+export const IdentifyBuilderArgs = z.extend(UniversalEventBuilderArgs, {
   traits: z.optional(Traits),
   userId: z.string(),
 })
@@ -197,7 +197,7 @@ const IdentifyBuilderArgs = z.extend(UniversalEventBuilderArgs, {
  */
 export type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs>
 
-const PageViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+export const PageViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
   properties: z.optional(z.partial(Page)),
 })
 
@@ -212,7 +212,7 @@ const PageViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
  */
 export type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs>
 
-const ScreenViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+export const ScreenViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
   name: z.string(),
   properties: Properties,
 })
@@ -221,14 +221,14 @@ const ScreenViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
  * Arguments for constructing screen view events.
  *
  * @remarks
- * Any properties passed here are merged with the base screen properties from
- * {@link EventBuilderConfig.getScreenProperties}.
+ * Any properties passed here are merged with the base screen properties supplied
+ * by the runtime.
  *
  * @public
  */
 export type ScreenViewBuilderArgs = z.infer<typeof ScreenViewBuilderArgs>
 
-const TrackBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+export const TrackBuilderArgs = z.extend(UniversalEventBuilderArgs, {
   event: z.string(),
   properties: z.optional(z.prefault(Properties, {})),
 })
diff --git a/packages/universal/core-sdk/src/index.ts b/packages/universal/core-sdk/src/index.ts
index 4db96011..b6f56759 100644
--- a/packages/universal/core-sdk/src/index.ts
+++ b/packages/universal/core-sdk/src/index.ts
@@ -9,12 +9,17 @@ export {
   effect,
   signalFns,
   signals,
+  toDistinctObservable,
+  toObservable,
+  type Observable,
   type Signal,
   type SignalFns,
   type Signals,
+  type Subscription,
 } from './signals'
 
 export type * from './BlockedEvent'
+export type { ConsentController, ConsentGuard } from './Consent'
 export * from './constants'
 export * from './CoreBase'
 export * from './CoreStateful'
@@ -22,6 +27,11 @@ export * from './CoreStateless'
 export * from './events'
 export * from './lib/decorators'
 export * from './lib/interceptor'
+export type {
+  QueueFlushFailureContext,
+  QueueFlushPolicy,
+  QueueFlushRecoveredContext,
+} from './lib/queue'
 export * from './resolvers'
 export * from './symbols'
 
diff --git a/packages/universal/core-sdk/src/lib/decorators/guardedBy.ts b/packages/universal/core-sdk/src/lib/decorators/guardedBy.ts
index 01ca30c3..3ab90e82 100644
--- a/packages/universal/core-sdk/src/lib/decorators/guardedBy.ts
+++ b/packages/universal/core-sdk/src/lib/decorators/guardedBy.ts
@@ -7,7 +7,7 @@
  *
  * @public
  */
-type BlockHandler = (methodName: string, args: readonly unknown[]) => void
+export type BlockHandler = (methodName: string, args: readonly unknown[]) => void
 
 /**
  * The original method implementation.
@@ -23,7 +23,7 @@ type BlockHandler = (methodName: string, args: readonly unknown[]) => void
  *
  * @internal
  */
-type GuardedByFunction<T extends object> = <A extends readonly unknown[], R>(
+export type GuardedByFunction<T extends object> = <A extends readonly unknown[], R>(
   value: (...args: A) => R,
   context: ClassMethodDecoratorContext<T, (...args: A) => R>,
 ) => void
@@ -126,7 +126,7 @@ const isAsyncFunction = (fn: (...args: readonly unknown[]) => unknown): boolean
  *
  * @param predicateName - The name (string or symbol) of a **synchronous** instance method on `this`
  * that acts as the predicate. It is called as `this[predicateName](methodName, argsArray)`.
- * @param opts - Optional {@link GuardedByOptions | options} to configure inversion and `onBlocked`.
+ * @param opts - Optional `GuardedByOptions` to configure inversion and `onBlocked`.
  *
  * @returns A methods-only class decorator compatible with Stage-3 decorators that wraps the method.
  *
diff --git a/packages/universal/core-sdk/src/lib/decorators/index.ts b/packages/universal/core-sdk/src/lib/decorators/index.ts
index 9a4a380b..714de6c7 100644
--- a/packages/universal/core-sdk/src/lib/decorators/index.ts
+++ b/packages/universal/core-sdk/src/lib/decorators/index.ts
@@ -1 +1,2 @@
 export { guardedBy } from './guardedBy'
+export type { BlockHandler, GuardedByFunction, GuardedByOptions } from './guardedBy'
diff --git a/packages/universal/core-sdk/src/lib/interceptor/InterceptorManager.ts b/packages/universal/core-sdk/src/lib/interceptor/InterceptorManager.ts
index f26fb24d..8a7d2fb3 100644
--- a/packages/universal/core-sdk/src/lib/interceptor/InterceptorManager.ts
+++ b/packages/universal/core-sdk/src/lib/interceptor/InterceptorManager.ts
@@ -7,7 +7,7 @@ import { cloneDeep } from 'es-toolkit'
  * @typeParam T - The resolved value type.
  * @public
  */
-type MaybePromise<T> = T | Promise<T>
+export type MaybePromise<T> = T | Promise<T>
 
 /**
  * A function that receives a value of type `T` and returns a (possibly async)
diff --git a/packages/web/frameworks/react-web-sdk/README.md b/packages/web/frameworks/react-web-sdk/README.md
index 79d429a8..ba366e20 100644
--- a/packages/web/frameworks/react-web-sdk/README.md
+++ b/packages/web/frameworks/react-web-sdk/README.md
@@ -1,4 +1,23 @@
-# React Web SDK
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/personalization/">
+    <img alt="Contentful Logo" title="Contentful" src="../../../../contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align="center">Contentful Personalization & Analytics</h1>
+
+<h3 align="center">Optimization React Web SDK</h3>
+
+<div align="center">
+
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../../CONTRIBUTING.md)
+
+</div>
+
+> [!WARNING]
+>
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes may be published at any time.
 
 React Web SDK package for `@contentful/optimization-react-web`.
 
diff --git a/packages/web/frameworks/react-web-sdk/package.json b/packages/web/frameworks/react-web-sdk/package.json
index efb9e07e..142ad1e3 100644
--- a/packages/web/frameworks/react-web-sdk/package.json
+++ b/packages/web/frameworks/react-web-sdk/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-react-web",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/web/frameworks/react-web-sdk"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/web/preview-panel/README.md b/packages/web/preview-panel/README.md
index ee94bdac..dd82a7eb 100644
--- a/packages/web/preview-panel/README.md
+++ b/packages/web/preview-panel/README.md
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/web/preview-panel/package.json b/packages/web/preview-panel/package.json
index 2d8ad295..e7f2cf50 100644
--- a/packages/web/preview-panel/package.json
+++ b/packages/web/preview-panel/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-web-preview-panel",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/web/preview-panel"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/web/preview-panel/src/attachOptimizationPreviewPanel.ts b/packages/web/preview-panel/src/attachOptimizationPreviewPanel.ts
index bfad8367..f2c4b28a 100644
--- a/packages/web/preview-panel/src/attachOptimizationPreviewPanel.ts
+++ b/packages/web/preview-panel/src/attachOptimizationPreviewPanel.ts
@@ -184,7 +184,7 @@ function canDefineComponents(): void {
  *
  * @internal
  */
-interface AttachOptimizationPreviewPanelArgs {
+export interface AttachOptimizationPreviewPanelArgs {
   /** Contentful client used to fetch audience and optimization entries. */
   contentful: ContentfulClientApi<ChainModifiers>
   /** ContentfulOptimization Web SDK instance to register the preview panel with. */
diff --git a/packages/web/preview-panel/src/index.ts b/packages/web/preview-panel/src/index.ts
index c7a8cc5b..92ad6b03 100644
--- a/packages/web/preview-panel/src/index.ts
+++ b/packages/web/preview-panel/src/index.ts
@@ -5,4 +5,6 @@
  */
 import attachOptimizationPreviewPanel from './attachOptimizationPreviewPanel'
 
+export type { AttachOptimizationPreviewPanelArgs } from './attachOptimizationPreviewPanel'
+
 export default attachOptimizationPreviewPanel
diff --git a/packages/web/web-sdk/README.md b/packages/web/web-sdk/README.md
index f36e084d..30575f4c 100644
--- a/packages/web/web-sdk/README.md
+++ b/packages/web/web-sdk/README.md
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
 
diff --git a/packages/web/web-sdk/package.json b/packages/web/web-sdk/package.json
index 3dd4189a..f8de468f 100644
--- a/packages/web/web-sdk/package.json
+++ b/packages/web/web-sdk/package.json
@@ -2,6 +2,11 @@
   "name": "@contentful/optimization-web",
   "version": "0.0.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/optimization.git",
+    "directory": "packages/web/web-sdk"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
diff --git a/packages/web/web-sdk/src/ContentfulOptimization.ts b/packages/web/web-sdk/src/ContentfulOptimization.ts
index 637044c1..3ea7c618 100644
--- a/packages/web/web-sdk/src/ContentfulOptimization.ts
+++ b/packages/web/web-sdk/src/ContentfulOptimization.ts
@@ -48,9 +48,9 @@ declare global {
  *
  * @public
  * @remarks
- * These options are passed to {@link Cookies.set} when persisting the anonymous ID.
+ * These options are used when persisting the anonymous ID cookie.
  */
-interface CookieAttributes {
+export interface CookieAttributes {
   /**
    * Cookie domain attribute.
    *
@@ -346,7 +346,7 @@ class ContentfulOptimization extends CoreStateful {
   }
 
   /**
-   * Persist (or clear) the anonymous ID in both cookies and {@link LocalStore}.
+   * Persist (or clear) the anonymous ID in both cookies and `LocalStore`.
    *
    * @param value - Anonymous identifier to persist. If omitted, clears persisted state.
    * @returns Nothing.
diff --git a/packages/web/web-sdk/src/entry-tracking/resolveAutoTrackEntryInteractionOptions.ts b/packages/web/web-sdk/src/entry-tracking/resolveAutoTrackEntryInteractionOptions.ts
index 8770f950..a36a58f0 100644
--- a/packages/web/web-sdk/src/entry-tracking/resolveAutoTrackEntryInteractionOptions.ts
+++ b/packages/web/web-sdk/src/entry-tracking/resolveAutoTrackEntryInteractionOptions.ts
@@ -62,13 +62,13 @@ export interface EntryHoverInteractionElementOptions {
   readonly data?: unknown
 }
 
-interface EntryInteractionStartOptionsMap {
+export interface EntryInteractionStartOptionsMap {
   clicks: undefined
   views: EntryViewInteractionStartOptions | undefined
   hovers: EntryHoverInteractionStartOptions | undefined
 }
 
-interface EntryInteractionElementOptionsMap {
+export interface EntryInteractionElementOptionsMap {
   clicks: EntryClickInteractionElementOptions
   views: EntryViewInteractionElementOptions
   hovers: EntryHoverInteractionElementOptions
diff --git a/packages/web/web-sdk/src/index.ts b/packages/web/web-sdk/src/index.ts
index 884250a9..9ef9c4f9 100644
--- a/packages/web/web-sdk/src/index.ts
+++ b/packages/web/web-sdk/src/index.ts
@@ -3,7 +3,7 @@
  *
  * @remarks
  * Exposes Web-specific utilities such as {@link ContentfulOptimization}, {@link beaconHandler},
- * and {@link LocalStore}. Core and transitive API exports are available from
+ * and `LocalStore`. Core and transitive API exports are available from
  * dedicated entrypoints:
  * `@contentful/optimization-web/core-sdk`,
  * `@contentful/optimization-web/api-client`,
@@ -23,6 +23,23 @@ export {
   OPTIMIZATION_WEB_SDK_VERSION,
 } from './constants'
 export * from './ContentfulOptimization'
+export type {
+  AutoTrackEntryInteractionOptions,
+  EntryClickInteractionElementOptions,
+  EntryElementInteraction,
+  EntryHoverInteractionElementOptions,
+  EntryHoverInteractionStartOptions,
+  EntryInteraction,
+  EntryInteractionApi,
+  EntryInteractionElementOptions,
+  EntryInteractionElementOptionsMap,
+  EntryInteractionStartOptions,
+  EntryInteractionStartOptionsMap,
+  EntryInteractionTracker,
+  EntryInteractionTrackers,
+  EntryViewInteractionElementOptions,
+  EntryViewInteractionStartOptions,
+} from './entry-tracking'
 export * from './handlers/beaconHandler'
 export * from './storage/LocalStore'
 
diff --git a/typedoc.json b/typedoc.json
index c7e3c740..5e56e96b 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -13,7 +13,21 @@
     "packages/react-native-sdk",
     "packages/universal/*"
   ],
-  "projectDocuments": ["CONTRIBUTING.md"],
+  "projectDocuments": ["documentation/README.md", "CONTRIBUTING.md"],
+  "externalSymbolLinkMappings": {
+    "@types/node": {
+      "__global.AbortController": "#",
+      "__global.Response": "#"
+    },
+    "contentful": {
+      "ChainModifiers": "#",
+      "Entry": "#",
+      "LocaleCode": "#"
+    },
+    "zod": {
+      "json": "#"
+    }
+  },
   "packageOptions": {
     "includeVersion": true,
     "entryPoints": ["src/index.ts"]