docs: add agent guidance for major subtrees (#332)

Author: ibgreen

AGENTS.md

@@ -0,0 +1,16 @@
+# Repository-wide instructions for agents
+
+This file applies to the entire `deck.gl-community` repository. Directories may add more specific guidance in their own `AGENTS.md` files.
+
+## Tooling
+- Use the Yarn 4 workspace that ships with the repo. Install dependencies with `yarn` and run scripts via `yarn <script>` from the repo root. See `package.json` for the canonical script list.
+- Prefer TypeScript and ES module syntax when authoring source files. Most packages ship dual ESM/CJS bundles via build tooling defined per workspace package.
+- if any dependencies are changed, the yarn.lock file must be rebuilt by running `yarn` in the root before committing.
+
+## Quality gates
+- Run `yarn lint` or `yarn lint-fix` before committing JavaScript/TypeScript changes.
+- Run the relevant Vitest project: `yarn test` (Node), `yarn test-browser`, or `yarn test-headless` as appropriate for your change.
+
+## Documentation and release process
+- Follow the contribution flow in `docs/CONTRIBUTING.md` before landing breaking changes.
+- When adding or removing packages or examples, update any related documentation, sidebars, or release notes under `docs/`.

docs/AGENTS.md

@@ -0,0 +1,15 @@
+# Documentation subtree instructions
+
+See `/AGENTS.md` for shared repo policies. This file covers Markdown under `docs/` that feeds the Docusaurus site in `website/`.
+
+## Authoring conventions
+- Prefer Markdown (`.md`/`.mdx`) with Docusaurus front matter when adding new pages. Reuse existing heading structures where possible for consistent slug generation.
+- Update the relevant `sidebar.json` file alongside new pages so navigation stays in sync with content.
+
+## Local preview
+- Run `yarn --cwd website start` to preview documentation changes with live reload.
+- Use `yarn --cwd website build` to catch broken links, missing front matter, or sidebar issues before publishing.
+
+## Pitfalls and references
+- Doc IDs become route segments—renaming files requires matching updates in `website/src/docs-sidebar.js`. Missing updates will break the docs navigation during deploy.
+- Follow the contribution expectations in `docs/CONTRIBUTING.md` when introducing new guides or major content revisions.

examples/AGENTS.md

@@ -0,0 +1,15 @@
+# Examples subtree instructions
+
+This file supplements `/AGENTS.md` for everything under `examples/`.
+
+## Running examples
+- Each subfolder is a Yarn workspace (see the root `package.json`). Start an example with `yarn workspace <example-name> start`.
+- Use the optional `start-local` script (when defined) to alias workspace modules through `examples/vite.config.local.mjs` for rapid iteration against local package changes.
+
+## Authoring conventions
+- Keep example entry points in `src/example.tsx` (or `index.tsx` for legacy folders) and export an `App` component so the website embedding utilities can import it.
+- Mirror new examples in `website/src/examples-sidebar.js` to make them visible on the docs site.
+
+## Pitfalls and references
+- The local Vite config warns that `editable-layers/editor` cannot be run with `start-local` because it loads two React copies. See the note in `examples/vite.config.local.mjs` and fall back to the regular `start` script for that case.
+- Publishing guides for editable-layer scenarios live in `docs/modules/editable-layers/developer-guide/get-started.md`; follow them to keep example props consistent with the documented API.

website/AGENTS.md

@@ -0,0 +1,16 @@
+# Website subtree instructions
+
+This file layers on top of `/AGENTS.md` for the Docusaurus app under `website/`.
+
+## Commands
+- Start the dev server with `yarn --cwd website start`.
+- Build static assets via `yarn --cwd website build`; CI uses `scripts/build.sh` to include gallery assets and worker transpilation.
+- Run `yarn --cwd website write-heading-ids` after adding new Markdown headings so generated anchors stay stable.
+
+## Authoring notes
+- Docs and example sidebars are defined in `src/docs-sidebar.js` and `src/examples-sidebar.js`. Keep entries sorted and ensure new routes map to actual Markdown or example exports.
+- Embed interactive examples by importing from `examples/*`—ensure those examples expose an `App` export per the guidance in `examples/AGENTS.md`.
+
+## Pitfalls and references
+- The staging/prod build script (`scripts/build.sh`) validates tokens and rebuilds gallery bundles; keep it in sync if you change build steps so deploys do not miss assets.
+- Navigation relies on IDs emitted from `docs/sidebar.json` files in the `docs/` tree. When you rename or move docs, update the mappings here and in the docs sidebars to avoid broken links during deployment.