diff --git a/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md b/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md
index d4c32a875..0bf962a4c 100644
--- a/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md
+++ b/docs/src/content/docs/producer/author-primitives/instructions-and-agents.md
@@ -58,6 +58,17 @@ unconditional and gets folded into compiled context files
 (`AGENTS.md`, `GEMINI.md`) instead of a per-file rule directory. With
 it, each harness wraps the body in its own scoping syntax.
 
+Multiple globs are supported via comma-separation:
+
+```yaml
+applyTo: "**/src/**,**/api/**,**/services/**"
+```
+
+Targets that use YAML lists (claude, cursor, windsurf) expand the
+comma-separated value into a proper list automatically. Brace
+alternations like `**/*.{css,scss}` are treated as a single glob and
+are not split.
+
 ### Body conventions
 
 - Lead with bullets, not prose. Instructions are read by an agent
@@ -72,10 +83,10 @@ it, each harness wraps the body in its own scoping syntax.
 
 | Target | Output path | Transform |
 |---|---|---|
-| copilot | `.github/instructions/<name>.instructions.md` | verbatim; `applyTo` preserved |
-| claude | `.claude/rules/<name>.md` | `applyTo` -> `paths:` list |
-| cursor | `.cursor/rules/<name>.mdc` | `applyTo` -> `globs:`; description auto-derived if missing |
-| windsurf | `.windsurf/rules/<name>.md` | `applyTo` -> `trigger: glob` + `globs:`; missing `applyTo` -> `trigger: always_on` |
+| copilot | `.github/instructions/<name>.instructions.md` | verbatim; `applyTo` preserved as-is |
+| claude | `.claude/rules/<name>.md` | `applyTo` -> `paths:` list; comma-separated value expanded to YAML list |
+| cursor | `.cursor/rules/<name>.mdc` | `applyTo` -> `globs:`; comma-separated value expanded to YAML list; description auto-derived if missing |
+| windsurf | `.windsurf/rules/<name>.md` | `applyTo` -> `trigger: glob` + `globs:`; comma-separated value expanded to YAML list; missing `applyTo` -> `trigger: always_on` |
 | codex | folded into `AGENTS.md` | compile-only, no per-file deploy |
 | gemini | folded into `GEMINI.md` | compile-only, no per-file deploy |
 | opencode | folded into `AGENTS.md` | compile-only, no per-file deploy |