Merge stable into develop

.claude/commands

@@ -1 +1 @@
-../dev/commands
+../.agents/commands

.claude/skills

@@ -1 +1 @@
-../dev/skills
+../.agents/skills

.github/workflows/ci.yml

@@ -112,6 +112,8 @@ jobs:
           globs: |
             **/*.{md,mdx}
             !changelog/*.md
+            !.agents/commands/**
+            !.agents/skills/**
             !.claude/commands/**
             !.claude/skills/**
             !dev/commands/**

AGENTS.md

@@ -4,7 +4,7 @@ Infrahub Python SDK - async/sync client for Infrahub infrastructure management.
 
 ## Product context
 
-The SDK is the foundational library for programmatically interacting with Infrahub. It abstracts away the underlying API so developers can work with infrastructure data using native Python objects.
+Foundational library for programmatically interacting with Infrahub. Abstracts the underlying API so developers work with infrastructure data as native Python objects (built-in auth, batching, caching, tracking).
 
 **Primary audience:** Network automation engineers and software developers.
 
@@ -14,8 +14,6 @@ The SDK is the foundational library for programmatically interacting with Infrah
 - **Integrate with external systems** — Query and sync data between Infrahub and existing tools. `infrahubctl` and the Infrahub Ansible collection both use this SDK internally.
 - **Build custom applications** — Use Infrahub as a data backend for Python projects entirely outside of Infrahub's own pipeline.
 
-**Why the SDK over direct API calls:** eliminates the need to learn Infrahub's API structure, provides Python-native interfaces with built-in auth, adds advanced capabilities (batching, caching, tracking), and reduces boilerplate.
-
 ## Commands
 
 ```bash
@@ -57,9 +55,7 @@ infrahub_sdk/
 
 ## Markdown style
 
-When editing `.md` or `.mdx` files, run `uv run invoke lint-docs` before committing.
-
-Key rules:
+When editing `.md` or `.mdx` files (`uv run invoke lint-docs` enforces these):
 
 - Use `text` language for directory structure code blocks
 - Add blank lines before and after lists
@@ -71,7 +67,7 @@ Key rules:
 
 - Run `uv run invoke format lint-code` before committing Python code
 - Run `uv run invoke docs-generate` after creating, modifying or deleting CLI commands, SDK config, or Python docstrings
-- Run markdownlint before committing markdown changes
+- Run `uv run invoke lint-docs` before committing markdown changes
 - Follow async/sync dual pattern for new features
 - Use type hints on all function signatures
 
@@ -87,14 +83,6 @@ Key rules:
 - Modify generated code (protocols.py)
 - Bypass type checking without justification
 
-## Knowledge base
-
-Deep-dive docs on architecture and workflows live in `dev/knowledge/`. Read these before making changes to the areas they cover.
-
-- [dev/knowledge/cli-architecture.md](dev/knowledge/cli-architecture.md) - CLI command hierarchy and design rules
-- [dev/knowledge/cli-design-principles.md](dev/knowledge/cli-design-principles.md) - Principles for writing CLI commands (no pre-validation, phrasing, etc.)
-- [dev/knowledge/doc-generation.md](dev/knowledge/doc-generation.md) - How docs are auto-generated from code
-
 ## Subdirectory guides
 
 - [docs/AGENTS.md](docs/AGENTS.md) - Documentation (Docusaurus)

dev/adr/README.md

@@ -0,0 +1,4 @@
+# Decision Records (ADRs)
+
+MADR-format decision records. Name each file `nnnn-title.md`: a zero-padded 4-digit
+sequence and a lowercase kebab-case title, no `adr-` prefix (e.g. `0001-use-uv.md`).

dev/guidelines/README.md

@@ -0,0 +1,3 @@
+# Guidelines
+
+Conventions and standards.

dev/guides/README.md

@@ -0,0 +1,3 @@
+# Guides
+
+How-to documentation.

dev/knowledge/README.md

@@ -0,0 +1,3 @@
+# Knowledge
+
+Domain knowledge and glossary, loaded on demand. Houses `CONTEXT.md`.