[dangertoaster]

🤖 GENERATED BY A TOASTER -- kimi-k3

Agents will often attempt make -C docs, which misses the redefinition of DOCS_VENVDIR in common.mk and creates a secondary venv that confuses much of our tooling.

[Copilot]

🟢 Approval recommended

No blocking issues were identified; remaining feedback is limited to minor command-naming clarification.

3 open findings

• Incorrectly documents docs-* as a Make target pattern · New
• Incorrectly documents docs-* as a Make target pattern · New
• Incorrectly documents docs-* as a Make target pattern · New

What changed in this PR

Updates agent guidance to avoid make -C docs, preventing creation of a conflicting documentation virtual environment.

Changes:

• Warns against direct documentation subdirectory builds.
• Directs agents to top-level documentation targets.
• Applies guidance across all agent instruction files.

File	Summary
AGENTS.md	Updated documentation build guidance
AGENTS.lib.md	Updated library agent guidance
AGENTS.app.md	Updated application agent guidance

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[LoweRAM]

Review notes on the new agent instruction:

2. The phrase "Never run make -C docs directly" can still be read as banning only the exact command. make -C docs html, make -C ./docs, or cd docs && make bypass it. Suggest wording such as: do not pass -C docs to Make and do not run Make from inside docs/.

3. The examples stop at make docs. An agent needing targets such as linkcheck, spelling, or woke may not know the corresponding top-level wrappers and fall back to direct make -C docs. Adding examples like make docs-linkcheck, make docs-spelling, and make docs-woke would make the intended pattern clearer.

4. docs/_dev/.pre-commit-config.yaml still invokes make -C docs spelling, make -C docs linkcheck, and make -C docs woke. It is unclear whether that file is an intentional exception. Either document that the rule applies to agent commands only, or migrate those hooks to the top-level make docs-* wrappers.

[dangertoaster]

🤖 [GENERATED BY A TOASTER -- kimi-k3]

Thanks for the review — all three points addressed in dbf19af:

2. Reworded to forbid invoking Make inside docs/ in any form: no -C docs, no running make from within the docs/ directory.
3. Added make docs-linkcheck, make docs-spelling, and make docs-woke to the examples so agents can discover the passthrough wrappers.
4. The new guidance now opens with "When running documentation builds or checks yourself", making it explicit that the rule applies to agent-run commands. docs/_dev/.pre-commit-config.yaml is invoked by pre-commit, not by the agent directly, and the dev-only hooks there intentionally exercise the docs sub-Makefile — migrating them to the top-level wrappers is a separate concern from this PR.

[dangertoaster]

🤖 [GENERATED BY A TOASTER -- kimi-k3]

Replaced the explicit target list with a pointer to make help in 242177e — it enumerates the documented top-level documentation targets (docs, docs-auto, docs-clean, docs-help, docs-install, docs-lint, setup-docs), and make docs-help lists the full docs subproject commands. This avoids the maintenance burden of keeping a hardcoded list in sync with the Makefile.

[LoweRAM]

Potential agent misinterpretations:

1. Rule scope: Agent might only ban the exact command make -C docs.
2. Target discovery: make help omits specific pattern-rule passthroughs (e.g., make docs-linkcheck).
3. Scope confusion: Agent might apply the rule to developer-initiated commands (like those in .pre-commit-config.yaml) instead of only agent-run tasks.

[mr-cal]

Nice, thanks!

As an aside, I hold almost no value in agent opnions on the contents of an agents file.