[Docs] README and AGENTS updates: Split docs by audience (plugin authors vs framework contributors)

AGENTS.md

@@ -0,0 +1,35 @@
+# DatoCMS Plugin SDK monorepo
+
+Lerna monorepo with **fixed/lockstep versioning** (both packages always share one version number) containing two npm packages:
+
+- `packages/sdk` → `datocms-plugin-sdk` — core TypeScript SDK for building DatoCMS plugins
+- `packages/react-ui` → `datocms-react-ui` — React components mimicking the DatoCMS UI; depends on `datocms-plugin-sdk`
+
+## Setup and commands (run from repo root)
+
+```bash
+npm install && npx lerna bootstrap   # required on fresh checkout; package-local commands fail without it
+npx lerna run build                  # builds in dependency order (sdk before react-ui)
+npm test                             # Jest unit tests
+npm run format                       # biome check + format
+```
+
+## Testing changes inside a real plugin
+
+Each package has an `install-in-place` script that rebuilds **that package only** and copies its artifacts over the installed copy in a plugin project:
+
+```bash
+cd packages/<pkg> && INSTALL_PATH=/path/to/plugin npm run install-in-place
+```
+
+Use it instead of `npm link` (a symlinked React library breaks with duplicate-React "Invalid hook call" errors). If a change spans both packages, run the sdk's script before react-ui's — react-ui compiles against the sdk's build output.
+
+## Gotchas
+
+- CI (`.github/workflows/node.js.yml`) triggers on `main`, but the default branch is `master`, so PRs get no automated checks — run `npm test` and a full `npx lerna run build` locally before opening one.
+- Releasing (maintainers only): `npm run publish` from the root → `lerna publish` bumps both packages, commits, tags `vX.Y.Z`, and publishes to npm.
+
+## More detail
+
+- `packages/react-ui/AGENTS.md` — react-ui architecture (CSS Modules JSON pipeline, dual CJS/ESM output, theming via `ctx`)
+- Each package README has a human-facing "Developing" section; keep them in sync with these files.

README.md

@@ -10,15 +10,25 @@
 
 # DatoCMS Plugin SDK
 
-Monorepo with Typescript libraries to help you build DatoCMS plugins. See [documentation](https://www.datocms.com/docs/plugin-sdk/introduction) and [examples](https://www.datocms.com/docs/plugin-sdk/real-world-examples) for usage information.
+Monorepo with the TypeScript libraries used to build DatoCMS plugins.
+
+## Building a plugin?
+
+You should not need to install these packages manually. Follow our [Build your first plugin](https://www.datocms.com/docs/plugin-sdk/build-your-first-plugin#set-up-your-project) guide to easily scaffold a plugin with both packages already set up. 
+
+From there, the [Plugin SDK documentation](https://www.datocms.com/docs/plugin-sdk/introduction) and [real-world examples](https://www.datocms.com/docs/plugin-sdk/real-world-examples) cover everything else.
 
 ## Packages
 
 - [`datocms-plugin-sdk`](https://github.com/datocms/plugins-sdk/tree/master/packages/sdk)
-  - Typescript SDK to build DatoCMS plugins.
+  - TypeScript SDK to build DatoCMS plugins.
 - [`datocms-react-ui`](https://github.com/datocms/plugins-sdk/tree/master/packages/react-ui)
   - React component library to mimic the DatoCMS interface inside plugins.
 
+## Developing
+
+To work on the packages themselves (e.g. to prepare a PR or debug an issue in the framework itself), see the "Developing" section of each package's README: [`datocms-plugin-sdk`](https://github.com/datocms/plugins-sdk/blob/master/packages/sdk/README.md#developing), [`datocms-react-ui`](https://github.com/datocms/plugins-sdk/blob/master/packages/react-ui/README.md#developing). Both are developed in this Lerna monorepo and released in lockstep.
+
 ## License
 
 This repository is published under the [MIT](LICENSE.md) license.

packages/react-ui/CLAUDE.md → packages/react-ui/AGENTS.md

@@ -167,6 +167,15 @@ Allows rapid iteration when developing the UI library alongside a plugin project
 
 ## Development Workflow
 
+### First-time setup
+
+On a fresh checkout, package-local commands fail (missing binaries, missing SDK types) until the monorepo is set up from the repo root:
+
+```bash
+npm install && npx lerna bootstrap   # root tooling + per-package dependencies
+npx lerna run build                  # builds datocms-plugin-sdk first, then this package
+```
+
 ### Building
 
 ```bash

packages/react-ui/README.md

@@ -1,17 +1,47 @@
-# `datocms-plugin-sdk`
+# `datocms-react-ui`
 
-React component library to mimic the DatoCMS interface inside plugins. You can read all about this package in [our documentation](https://www.datocms.com/docs/plugin-sdk).
+React component library to mimic the DatoCMS interface inside plugins.
 
-## Installation
+## Using these components
 
-Using [npm](http://npmjs.org/):
+To build a plugin with these components, see the official [DatoCMS Plugin SDK documentation](https://www.datocms.com/docs/plugin-sdk) for guides and component reference. Plugins scaffolded from the official plugin template already include this package (alongside `datocms-plugin-sdk`). You should not need to manually add this.
+
+## Developing
+
+This package is developed in the [`datocms/plugins-sdk`](https://github.com/datocms/plugins-sdk) repository, a [Lerna](https://lerna.js.org/) monorepo (a single Git repo hosting multiple npm packages, with Lerna managing their shared version number and publishing). The monorepo contains two packages, released in lockstep:
+
+- [`datocms-plugin-sdk`](https://github.com/datocms/plugins-sdk/tree/master/packages/sdk) — the core plugin SDK;
+- `datocms-react-ui` — this component library, which depends on it.
+
+To work on the library itself (e.g. to prepare a PR), clone the whole monorepo — this package isn't buildable standalone:
+
+```sh
+git clone https://github.com/datocms/plugins-sdk && cd plugins-sdk
+npm install && npx lerna bootstrap   # root tooling + per-package dependencies
+npx lerna run build                  # build all packages in dependency order
+```
+
+To verify the checkout, `npm test` runs the monorepo's small Jest suite (unit tests for SDK and UI helpers); it takes a couple of seconds and every test should pass.
+
+A fresh checkout won't compile until that first build: components import generated `styles.module.css.json` class maps, and this package needs `datocms-plugin-sdk`'s build output — so a `Cannot find module './styles.module.css.json'` error just means "run the build".
+
+### Testing your changes inside a real plugin
+
+Don't use `npm link` — symlinking a React library commonly breaks with duplicate-React "Invalid hook call" errors. Instead, use our provided npm `install-in-place` script, which rebuilds **this package only** and copies its artifacts (`dist/`, `styles.css`, `types.json`) over the copy installed in a plugin project:
 
 ```sh
-npm install datocms-plugin-sdk
+cd packages/react-ui
+INSTALL_PATH=/path/to/your-plugin npm run install-in-place
 ```
 
-Using [yarn](https://yarnpkg.com/):
+Re-run it after every change; if the plugin uses Vite, restart the dev server with `--force` so its dependency cache doesn't serve stale bits. If your change also touches `datocms-plugin-sdk`, run that package's own `install-in-place` too, **before** this one — this package compiles against the SDK's build output. To restore the registry version afterwards, in the plugin run:
 
 ```sh
-yarn add datocms-plugin-sdk
+rm -rf node_modules/datocms-react-ui node_modules/.vite && npm install
 ```
+
+### Releasing (maintainers)
+
+From the repo root, `npm run publish` runs the tests, builds everything, and hands off to `lerna publish`, which bumps **both** packages to the same version (fixed mode), commits, tags `vX.Y.Z`, and publishes to npm. Use `npm run publish-next` for a prerelease under the `next` dist-tag.
+
+For deeper architectural notes (CSS Modules pipeline, dual CJS/ESM output, theming via `ctx`), see [`AGENTS.md`](https://github.com/datocms/plugins-sdk/blob/master/packages/react-ui/AGENTS.md) in this directory.

packages/sdk/README.md

@@ -1,17 +1,45 @@
 # `datocms-plugin-sdk`
 
-Typescript SDK to build DatoCMS plugins. You can read all about the SDK in [our documentation](https://www.datocms.com/docs/plugin-sdk/introduction).
+TypeScript SDK to build DatoCMS plugins.
 
-## Installation
+## Using this SDK
 
-Using [npm](http://npmjs.org/):
+To build a plugin with this SDK, see the official [DatoCMS Plugin SDK documentation](https://www.datocms.com/docs/plugin-sdk) for guides and API reference.
+
+Plugins scaffolded from the official plugin template already include the SDK (alongside [`datocms-react-ui`](https://github.com/datocms/plugins-sdk/tree/master/packages/react-ui)). You should not need to manually add this.
+
+## Developing
+
+This package is developed in the [`datocms/plugins-sdk`](https://github.com/datocms/plugins-sdk) repository, a [Lerna](https://lerna.js.org/) monorepo (a single Git repo hosting multiple npm packages, with Lerna managing their shared version number and publishing). The monorepo contains two packages, released in lockstep:
+
+- `datocms-plugin-sdk` — this core plugin SDK;
+- [`datocms-react-ui`](https://github.com/datocms/plugins-sdk/tree/master/packages/react-ui) — a React component library that depends on it.
+
+To work on the SDK (e.g. to prepare a PR), clone the whole monorepo — this package isn't buildable standalone:
 
 ```sh
-npm install datocms-plugin-sdk
+git clone https://github.com/datocms/plugins-sdk && cd plugins-sdk
+npm install && npx lerna bootstrap   # root tooling + per-package dependencies
+npx lerna run build                  # build all packages in dependency order
 ```
 
-Using [yarn](https://yarnpkg.com/):
+To verify the checkout, `npm test` runs the monorepo's small Jest suite (unit tests for SDK and UI helpers); it takes a couple of seconds and every test should pass.
+
+### Testing your changes inside a real plugin
+
+Use the provided npm `install-in-place` script, which rebuilds **this package only** and copies its artifacts (`dist/`, `manifest.json`) over the copy installed in a plugin project:
 
 ```sh
-yarn add datocms-plugin-sdk
+cd packages/sdk
+INSTALL_PATH=/path/to/your-plugin npm run install-in-place
 ```
+
+Re-run it after every change; if the plugin uses Vite, restart the dev server with `--force` so its dependency cache doesn't serve stale bits. This is enough even if the plugin also uses `datocms-react-ui`: at runtime the UI library resolves `datocms-plugin-sdk` from the plugin's `node_modules`, so it picks up your copied build automatically. To restore the registry version afterwards, in the plugin run:
+
+```sh
+rm -rf node_modules/datocms-plugin-sdk node_modules/.vite && npm install
+```
+
+### Releasing (maintainers)
+
+From the repo root, `npm run publish` runs the tests, builds everything, and hands off to `lerna publish`, which bumps **both** packages to the same version (fixed mode), commits, tags `vX.Y.Z`, and publishes to npm. Use `npm run publish-next` for a prerelease under the `next` dist-tag.