[doc] add agent context for Ray documentation (#63227)

## Why

Ray's per-library `.claude/CLAUDE.md` convention is in place for `data`,
`serve`, `train`, `tune`, `rllib`, and `src/ray`. `doc/` is missing this
file. Agents working on docs (Claude Code sessions, OSS contributors
using AI assistants) have no in-repo signal about how Ray's CI is
configured for documentation changes or how to scope PRs to land
cleanly.

## What

Adds `doc/.claude/CLAUDE.md` with concise pointers to:

- How `.buildkite/test.rules.txt` maps file patterns to tag sets, and
which patterns the `doc` tag covers (post-#63132 shape).
- Scope discipline for docs-only PRs: take the lightest path; don't
bundle in non-doc changes.
- When to revise test rules vs. work around them (precedent: #63132).
- Existing skills (`/lint`, `/fetch-buildkite-logs`, `/rebuild`).

Under 50 lines per the existing per-library convention. Wording can
iterate.

## Verification

- `find ray/doc -path '*/.claude/CLAUDE.md'` returns the new file.
- File loads when a Claude Code session is rooted at `doc/` (a session
under `doc/source/` will pick this up alongside the top-level
`.claude/CLAUDE.md`).

## Context

Tracked under `DOC-879` in anyscale/docs Jira (private). Captures the
test-rule discipline that emerged during the docs-infra mapping work in
#63132.

---------

Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dstrodtman

.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.