docs(docs): add AI harness readiness guidance [NT-4002]

.github/workflows/publish-docs.yml

@@ -46,8 +46,8 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
-          # Upload docs
-          path: './docs'
+          # Upload the generated TypeDoc site
+          path: './site'
       - name: Find previous successful Pages deployment
         continue-on-error: true
         id: previous_deployment

.gitignore

@@ -18,12 +18,12 @@ blob-report
 build
 coverage
 dist
-docs
 node_modules
 pkgs
 pids
 playwright-report
 playwright.cache
+site
 temp
 test-results
 tmp

AGENTS.md

@@ -307,7 +307,7 @@ explicitly requests it.
 ## Docs and README
 
 - Follow [`STYLE_GUIDE.md`](./STYLE_GUIDE.md) for human-authored prose. Authored docs live in
-  `documentation/`; generated TypeDoc output lives in `docs/`.
+  `documentation/`; generated TypeDoc output lives in `site/`.
 - Preserve existing README families: repo/package/reference implementation headers, navigation, and
   release-status warnings where applicable; documentation indexes; short status READMEs for placeholders or
   internal-only surfaces.

ARCHITECTURE.md

@@ -0,0 +1,24 @@
+# Architecture
+
+## Purpose
+
+Public pnpm monorepo for Contentful Personalization and Analytics SDKs across web, Node.js, React Native, iOS, and Android.
+
+## Main areas
+
+- packages/ contains published SDKs and shared libraries.
+- implementations/ contains reference applications and end-to-end fixtures.
+- lib/ contains shared development, mock, and test tooling.
+- documentation/ contains guides and concepts; scripts/ contains release and validation tooling.
+
+## Change flow
+
+Repository manifests and checked-in configuration define how source becomes a build, package, report, example, or documentation artifact. Keep changes inside the owning area and follow explicit dependencies rather than copying behavior between components.
+
+## Boundaries
+
+External services, credentials, and deployment environments are not represented by source code alone. Local validation should use documented fixtures or configuration and must not embed secrets.
+
+## Failure and verification
+
+Start with the narrowest affected command, inspect its direct inputs, and expand to repository-level validation. If a required external system is unavailable, record that verification gap instead of claiming success.

CONTRIBUTING.md

@@ -66,7 +66,7 @@ package, implementation, or `lib/` workspace.
   `.nvmrc`.
 - Use the pnpm version pinned in the root [`package.json`](./package.json).
 - Change source-of-truth files, not generated output. Authored docs live in `documentation/`;
-  generated TypeDoc output lives in `docs/`.
+  generated TypeDoc output lives in `site/`.
 - Treat reference implementations as maintained product artifacts, not disposable examples.
 - Do not hand-edit `dist/`, `coverage/`, `docs/`, `pkgs/`, `.rslib/`, `.rsdoctor/`, `node_modules/`,
   or local `.env` files unless the task explicitly targets them.
@@ -104,7 +104,8 @@ pnpm version:pnpm
 | `packages/ios/`      | Swift package                                                                       |
 | `implementations/`   | Reference apps used for integration testing, validation evidence, and E2E coverage  |
 | `documentation/`     | Authored guides and concepts published with TypeDoc                                 |
-| `docs/`              | Generated TypeDoc output                                                            |
+| `docs/`              | Architecture decision records                                                       |
+| `site/`              | Generated TypeDoc and GitHub Pages output                                           |
 | `pkgs/`              | Generated tarballs created by `pnpm build:pkgs`; implementations install from these |
 | `dist/`, `coverage/` | Generated build and test artifacts inside individual workspaces                     |
 | `.github/workflows/` | CI, release, publish, and title-check workflows                                     |
@@ -377,7 +378,7 @@ Follow [`STYLE_GUIDE.md`](./STYLE_GUIDE.md) for human-authored prose.
 Code reference documentation is generated with TypeDoc:
 
 - Authored supporting docs belong in `documentation/`.
-- Generated TypeDoc output belongs in `docs/`; do not hand-edit it.
+- Generated TypeDoc output belongs in `site/`; do not hand-edit it.
 - `pnpm docs:generate` generates documentation from TSDoc comments, package README files, and
   Markdown files under `documentation/`.
 - `pnpm docs:watch` watches for file updates and rebuilds generated docs while writing.

README.md

@@ -141,7 +141,8 @@ patterns with intentionally minimal application code.
 - `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
+- `docs/`: architecture decision records
+- `site/`: generated TypeDoc and GitHub Pages output; not source of truth
 
 ## Get involved
 

docs/ADRs/0001-keep-environment-and-framework-sdks-layered-over-shared-foundations.md

@@ -0,0 +1,17 @@
+# Keep environment and framework SDKs layered over shared foundations
+
+- Status: Accepted
+- Scope: Optimization SDK Suite
+
+## Context
+
+The repository publishes multiple runtime and framework packages while sharing schemas, API clients, and optimization behavior.
+
+## Decision
+
+Keep shared behavior in universal foundation packages and expose environment or framework-specific packages as the primary application entry points.
+
+## Consequences
+
+Changes to shared packages can affect several SDKs, so package builds, unit tests, and relevant reference implementations must be checked together.
+

eslint.config.ts

@@ -29,7 +29,7 @@ export default defineConfig(
       '**/coverage',
       '**/contentful-generated.d.ts',
       '**/dist',
-      'docs/media/**',
+      'site/media/**',
       '**/ios/**',
       // Engine-targeted JS bridge glue compiled into the native SDKs; consolidated
       // from the ios/android bridge packages, which were ignored under the rules above.

typedoc.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://typedoc.org/schema.json",
   "name": "Contentful Personalization & Analytics",
+  "out": "site",
   "includeVersion": false,
   "headings": {
     "document": false,