[doc] add agent context for Ray documentation

.gitignore

@@ -253,3 +253,4 @@ CLAUDE.local.md
 
 # Worktrees
 .worktrees/
+.claude/worktrees/

doc/.claude/CLAUDE.md

@@ -0,0 +1,54 @@
+<!-- Loaded on-demand when Claude works on Ray documentation files. -->
+<!-- Keep under 50 lines. Multi-step procedures → skills. Code style → rules/. -->
+
+# Ray Documentation
+
+Sphinx documentation built by Read the Docs and served at `docs.ray.io`. Build pipeline: `.buildkite/doc.rayci.yml`.
+
+## File format for new pages
+
+Author new files under `doc/source/` as MyST Markdown (`.md`). A lint check rejects newly added `.rst` files. Edits to existing `.rst` files are not flagged. `git mv` is not flagged for any rename, which covers file renames and directory reorganization. This is deliberate, to keep reorganization and agent-driven moves unblocked.
+
+## How CI is configured
+
+`.buildkite/test.rules.txt` maps file-change patterns to tag sets, and tags drive which CI suites run. The `doc` tag covers content under `doc/`, `doc/requirements-doc.txt`, `.vale.ini`/`.vale/`, and `.buildkite/doc.rayci.yml`. Docs-only deplock changes (`python/deplocks/docs/*.lock`, `ci/raydepsets/configs/docs.depsets.yaml`) tag to `doc python_dependencies` to skip the full python-deps test set.
+
+## Scope discipline for PRs
+
+For docs-only fixes, take the lightest path:
+
+- Touch only files mapped to the `doc` tag.
+- Don't bundle in a non-doc change "while you're at it" — that change pulls its own (often expensive) test set into the PR.
+- If a docs change requires a non-doc change to land cleanly (e.g., autodoc references a renamed symbol), land them in the larger non-doc PR, not a docs-led PR.
+
+For generated API docs that depend on Python source under `python/ray/...`, expect broader test runs. That's correct, not a misconfiguration.
+
+## DCO sign-off
+
+Every commit on a `ray-project/ray` PR needs a `Signed-off-by:` trailer (Developer Certificate of Origin). Pass `--signoff` to `git commit`, or `git commit --amend --signoff` to fix an unsigned commit. The DCO GitHub check fails the PR otherwise.
+
+## When to revise the test rules
+
+If a docs-only PR hits unnecessarily broad tests, file a `.buildkite/test.rules.txt` PR (precedent: #63132) instead of working around it. Quick check: does the file change affect any non-`doc` build artifact, runtime behavior, or API surface? If no, tag it `doc`.
+
+## Cross-references between .md and .rst sources
+
+When linking from .md to a doc whose source is .rst, use the {doc} role, not a bare `[text](path.md)` link: `` {doc}`Ray documentation home page </index>` ``. MyST-Parser 2.0 has a cross-extension resolution bug — a bare `[text](path.md)` link to an .rst source emits `myst.xref_missing`, which `fail_on_warning: true` in `.readthedocs.yaml` turns into a build failure.
+
+## Comparing PR previews against `/en/master` vs `/en/latest`
+
+For regression checks, compare a PR preview against `/en/master` — it's the docs build of the same master state your PR branches from, so byte-level content diffs against master are attributable to the stack. `/en/latest` is the last tagged release and lags master by every unreleased commit, so diffs there mix in upstream feature work and don't isolate regressions. Use `/en/latest` only to inventory net-new content since the last release.
+
+## Editing the docs lockfile
+
+`doc/requirements-doc.txt` is source of truth; `python/deplocks/docs/docbuild_depset_py3.10.lock` is regenerated by raydepsets, and CI's `raydepsets --check` enforces consistency.
+
+- Additive packages or version bumps with unchanged dep trees: hand-edit the package's entry block plus its via comments. Precedent: #63130.
+- Version bumps that change a package's direct deps (gaining or losing requirements): regenerate via `bazelisk run //ci/raydepsets:raydepsets -- build ci/raydepsets/configs/docs.depsets.yaml`. Hand-edits miss transitive churn — precedent: #63344 caught a stale `# via pydata-sphinx-theme` line under `packaging` after the theme dropped that dep.
+
+## Skills
+
+- `/lint` — run linters on modified files.
+- `/fetch-buildkite-logs` — pull build logs for CI failures.
+
+See top-level `.claude/CLAUDE.md` for the full skill index.

doc/README.md

@@ -2,6 +2,12 @@
 
 Repository for documentation of the Ray project, hosted at [docs.ray.io](https://docs.ray.io).
 
+## Contributing new documentation pages
+
+Author new documentation files under `doc/source/` as MyST Markdown (`.md`), not reStructuredText (`.rst`). A lint check rejects newly added `.rst` files. Edits to existing `.rst` files continue to work. `git mv` is not flagged for any rename, which covers file renames and directory reorganization.
+
+MyST is a Markdown superset that supports the Sphinx directives used throughout the docs. See the [MyST Parser documentation](https://myst-parser.readthedocs.io/) for syntax reference.
+
 ## Installation
 
 To build the documentation, make sure you have `ray` installed first.