keep the agent symlinks (#13968)

* Commit root AGENTS.md/CLAUDE.md symlinks so agents auto-load conventions

Track the root AGENTS.md/CLAUDE.md symlinks (-> .ai/AGENTS.md) instead of
generating them via `make claude`/`make codex`, so a fresh clone auto-loads
the agent guide with no setup step (matching transformers). The make targets
now only wire up skills; .ai/AGENTS.md, the contribution doc, and the PR
template are updated to match.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Add documentation-impact check to PR review rules

During review, scan related usage docs and agent docs and flag (advisory)
any that should be updated based on the PR — outdated/missing usage docs, or
a rule/pattern/gotcha worth recording in the agent guides.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.ai/AGENTS.md

@@ -1,5 +1,10 @@
 # Diffusers — Agent Guide
 
+## Setup
+
+- Local Claude Code agents: run `make claude` after cloning to wire the [skills](#skills) under `.claude/`.
+- Local OpenAI Codex agents: run `make codex` after cloning to wire the [skills](#skills) under `.agents/`.
+
 ## Coding style
 
 Strive to write code as simple and explicit as possible.

.ai/review-rules.md

@@ -15,6 +15,13 @@ Common mistakes are covered in the common-mistakes / gotcha sections in [AGENTS.
 
 - **Ephemeral context.** Comments, docstrings, and files that only made sense to the current PR's author or reviewer don't help a future reader/user/developer. Examples: `# per reviewer comment on PR #NNNN`, `# as discussed in review`, `# TODO from offline chat`, debug printouts. Same for files: parity harnesses, comparison scripts, anything in `scripts/` with hardcoded developer paths or imports from the reference repo. State the *reason* so the comment stands alone, or drop it.
 
+## Documentation impact
+
+A PR can leave existing docs stale or surface a pattern worth recording. Scan the docs related to what the PR touches and flag updates as a **suggestions / additional info** section (not blocking):
+
+- **Usage docs.** New or changed public behavior — a new pipeline/model, a new argument, changed defaults, a renamed API — should have matching updates in `docs/`, docstrings, and examples. Flag any that now describe outdated behavior or that are missing for the new surface.
+- **Agent docs.** If the review turns up a rule, pattern, or common gotcha that isn't written down yet — especially one the author got wrong or that you had to reason out — propose adding it to the relevant agent guide ([AGENTS.md](AGENTS.md), [models.md](models.md), [pipelines.md](pipelines.md), [modular.md](modular.md), a skill, or this file) so the next contributor/agent gets it for free instead of repeating the mistake.
+
 ## Dead code analysis (new models)
 
 When reviewing a PR that adds a new model, trace how the model is actually called from the pipeline to identify likely dead code. Include the results as a **suggestions / additional info** section in your review (not as blocking comments — the findings are advisory).

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,7 +17,7 @@ Fixes # (issue)
 
 ## Before submitting
 - [ ] Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so:
-  - [ ] Did you point it at the project conventions in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai) (e.g. via `make claude` / `make codex`)? See [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents).
+  - [ ] Did you read the [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents) guide?
   - [ ] Did you self-review the diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)?
 - [ ] Did you read the [contributor guideline](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution)?
 - [ ] Did you read our [philosophy doc](https://huggingface.co/docs/diffusers/main/en/conceptual/philosophy)? (important for complex PRs)

.gitignore

@@ -184,7 +184,5 @@ tags
 wandb
 
 # AI agent generated symlinks
-/AGENTS.md
-/CLAUDE.md
 /.agents/skills
 /.claude/skills

AGENTS.md

@@ -0,0 +1 @@
+.ai/AGENTS.md

CLAUDE.md

@@ -0,0 +1 @@
+.ai/AGENTS.md

Makefile

@@ -107,17 +107,14 @@ post-patch:
 # AI agent symlinks
 
 codex:
-	ln -snf .ai/AGENTS.md AGENTS.md
 	mkdir -p .agents
 	rm -rf .agents/skills
 	ln -snf ../.ai/skills .agents/skills
 
 claude:
-	ln -snf .ai/AGENTS.md CLAUDE.md
 	mkdir -p .claude
 	rm -rf .claude/skills
 	ln -snf ../.ai/skills .claude/skills
 
 clean-ai:
-	rm -f AGENTS.md CLAUDE.md
 	rm -rf .agents/skills .claude/skills

docs/source/en/conceptual/contribution.md

@@ -570,9 +570,9 @@ For documentation strings, 🧨 Diffusers follows the [Google style](https://goo
 
 ## Coding with AI agents
 
-The repository keeps AI-agent configuration in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai) and exposes local agent files via symlinks. If you use a coding agent (Claude Code, OpenAI Codex, etc.) to help with a contribution, point it at this directory — it contains the project conventions and on-demand task knowledge maintainers expect contributors to follow.
+The repository keeps AI-agent configuration in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai). Run `make claude` / `make codex` to additionally wire up the on-demand task skills for your tool.
 
-- **Read-only for contributors** — `.ai/` is maintained by the core maintainers. Please do not edit files under `.ai/` (or the generated root-level `AGENTS.md`, `CLAUDE.md`, `.agents/skills`, `.claude/skills`, which are symlinks) in your PR. If you find something missing or wrong, open an issue or flag it on the PR and a maintainer will update it.
+- **Read-only for contributors** — `.ai/` is maintained by the core maintainers. Please do not edit files under `.ai/` (or the root-level `AGENTS.md` / `CLAUDE.md` symlinks, or the generated `.agents/skills` / `.claude/skills`) in your PR. If you find something missing or wrong, open an issue or flag it on the PR and a maintainer will update it.
 - **Guidelines** (loaded into every agent session):
   - [`.ai/AGENTS.md`](https://github.com/huggingface/diffusers/blob/main/.ai/AGENTS.md) — top-level coding guidelines
   - [`.ai/models.md`](https://github.com/huggingface/diffusers/blob/main/.ai/models.md) — attention pattern, model implementation rules, common conventions
@@ -583,9 +583,9 @@ The repository keeps AI-agent configuration in [`.ai/`](https://github.com/huggi
   - `model-integration` — adding a new model or pipeline to diffusers end-to-end (file structure, integration checklist, testing layout, weight conversion)
   - `self-review` — review your changes against the project rules before opening a PR
 - **Setup commands**:
-  - `make codex` — symlink guidelines + skills for OpenAI Codex
-  - `make claude` — symlink guidelines + skills for Claude Code
-  - `make clean-ai` — remove all generated symlinks
+  - `make codex` — wire up skills for OpenAI Codex (under `.agents/`)
+  - `make claude` — wire up skills for Claude Code (under `.claude/`)
+  - `make clean-ai` — remove the generated skills symlinks
 
 ### AI-assisted and agentic contributions