diff --git a/AGENTS.md b/AGENTS.md
index 0f8457217..d2e3f624a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,7 +82,7 @@ mkdir -p .bob && ln -s ../.agents/skills .bob/skills
 
 ## 5. Coding Standards
 - **Types required** on all core functions
-- **Docstrings are prompts** — be specific, the LLM reads them
+- **Docstrings are published in the public API reference** — be specific and accurate.
 - **Google-style docstrings** — `Args:` on the **class docstring only**; `__init__` gets a single summary sentence. Add `Attributes:` only when a stored value differs in type/behaviour from its constructor input (type transforms, computed values, class constants). See CONTRIBUTING.md for a full example. **No RST directives inside docstrings** — never use `Example::`, `.. deprecated::`, `:param:`, `:type:`, or other RST markup inside a docstring; Google-style sections (`Example:`, `Raises:`, etc.) use plain Markdown. **Code examples use triple-backtick fences** (` ```python `) — not `>>>` doctest prompts (output is not verified). **Inline code uses single backticks** (`` `name` ``) — never double backticks (`` ``name`` ``); Mellea uses Markdown-style docstrings where double backticks are RST syntax and render incorrectly. See CONTRIBUTING.md for the full rationale and examples.
 - **Ruff** for linting/formatting
 - Use `...` in `@generative` function bodies
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a32f7f194..3306fbd28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -129,7 +129,7 @@ def process_text(text: str, max_length: int = 100) -> str:
 
 ### Docstrings
 
-**Docstrings are prompts** - the LLM reads them, so be specific.
+**Docstrings are published in the public API reference** — be specific.
 
 Use **[Google-style docstrings](https://google.github.io/styleguide/pyguide.html#381-docstrings)**: