📝 Add AI development guidance and coding agent notices

docs/ai-development.md

@@ -0,0 +1,29 @@
+# Develop with AI
+
+SQLModel includes an official **agent skill**, bundled with the Python package, with guidance for the version installed in your project.
+
+## Install the skill
+
+After [installing SQLModel](install.md), run [Library Skills](https://library-skills.io/use/) from your project directory:
+
+```bash
+uvx library-skills
+```
+
+Select the SQLModel skill and `.agents/skills` for Codex and most agents, or `.claude/skills` for Claude Code. You can select both.
+
+Your agent can then use the skill automatically when working on SQLModel code.
+
+### Install without prompts
+
+For agents and scripts, select the SQLModel skill without interactive prompts:
+
+```bash
+uvx library-skills install --skill sqlmodel --yes
+```
+
+For Claude Code, add `--claude` to also install it in `.claude/skills`:
+
+```bash
+uvx library-skills install --skill sqlmodel --yes --claude
+```

docs/index.md

@@ -41,6 +41,8 @@ SQLModel is a library for interacting with <abbr title='Also called "Relational
 
 **SQLModel** is based on Python type annotations, and powered by [Pydantic](https://pydantic-docs.helpmanual.io/) and [SQLAlchemy](https://sqlalchemy.org/).
 
+<!-- agent-banner -->
+
 The key features are:
 
 * **Intuitive to write**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.

includes/agent-banner.md

@@ -0,0 +1,11 @@
+/// details | AI coding agents
+
+Use the official SQLModel skill for your installed version. Install it from your project directory:
+
+```bash
+uvx library-skills
+```
+
+See [Develop with AI](ai-development.md).
+
+///

mkdocs.yml

@@ -66,6 +66,7 @@ nav:
     - install.md
     - "":
       - tutorial/index.md
+      - ai-development.md
       - tutorial/create-db-and-table-with-db-browser.md
       - tutorial/create-db-and-table.md
       - tutorial/insert.md
@@ -129,7 +130,12 @@ nav:
     - management.md
   - release-notes.md
 
+watch:
+  - scripts/agent_banner.py
+  - includes/agent-banner.md
+
 markdown_extensions:
+  scripts.agent_banner:
   # Material for MkDocs
   material.extensions.preview:
     targets:

scripts/agent_banner.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+from posixpath import relpath
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+from mkdocstrings import MkdocstringsInnerExtension
+from zensical.extensions.context import ContextPreprocessor
+
+
+class AgentBannerPreprocessor(Preprocessor):
+    def run(self, lines: list[str]) -> list[str]:
+        # Docstrings render their own Markdown inside an API reference page.
+        if any(
+            isinstance(extension, MkdocstringsInnerExtension)
+            for extension in self.md.registeredExtensions
+        ):
+            return lines
+
+        context = ContextPreprocessor.from_markdown(self.md)
+        if context is None or context.page.path == "ai-development.md":
+            return lines
+
+        banner_path = (
+            Path(__file__).resolve().parent.parent / "includes/agent-banner.md"
+        )
+        banner = banner_path.read_text(encoding="utf-8").strip()
+        guide_path = relpath(
+            "ai-development.md", Path(context.page.path).parent.as_posix()
+        )
+        banner = banner.replace("(ai-development.md)", f"({guide_path})")
+        content = "\n".join(lines)
+        marker = "<!-- agent-banner -->"
+        if marker in content:
+            return content.replace(marker, banner).splitlines()
+
+        header, _, body = content.lstrip().partition("\n")
+        if header == "#" or header.startswith("# "):
+            return f"{header}\n\n{banner}\n\n{body.lstrip()}".splitlines()
+        return f"{banner}\n\n{content}".splitlines()
+
+
+class AgentBannerExtension(Extension):
+    def extendMarkdown(self, md: Markdown) -> None:
+        # Insert the notice before macros and fenced code blocks are processed.
+        md.preprocessors.register(AgentBannerPreprocessor(md), "agent_banner", 36)
+
+
+def makeExtension() -> AgentBannerExtension:
+    return AgentBannerExtension()

scripts/docs.py

@@ -65,6 +65,7 @@ def generate_readme_content() -> str:
         new_content,
         flags=re.DOTALL,
     )
+    new_content = new_content.replace("<!-- agent-banner -->\n\n", "")
     return new_content