📘 docs(plumbing): Updating docs plumbing to fix dead links and prep for Guides

.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

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.

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
 

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,78 +37,85 @@ 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)
 
 <!-- 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
 

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

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`

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>
 

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>
 

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>
 

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>