prepare release v1.19.0

.github/file-filters.yml

@@ -36,7 +36,8 @@ markdown_all: &markdown_all
 
 infrahub_reference_generated: &infrahub_reference_generated
   - "docs/docs/infrahubctl/*.mdx"
-  - "docs/docs/python-sdk/reference/config.mdx"
+  - "docs/docs/python-sdk/reference/*.mdx"
+  - "docs/docs/python-sdk/sdk_ref/**/*.mdx"
 
 documentation_all:
   - *development_files

.github/workflows/ci.yml

@@ -108,7 +108,7 @@ jobs:
       - name: "Linting: markdownlint"
         uses: DavidAnson/markdownlint-cli2-action@v22
         with:
-          config: .markdownlint.yaml
+          config: docs/.markdownlint.yaml
           globs: |
             **/*.{md,mdx}
             !changelog/*.md
@@ -176,7 +176,7 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: 20
-          cache: 'npm'
+          cache: "npm"
           cache-dependency-path: docs/package-lock.json
       - name: "Install dependencies"
         run: npm install
@@ -207,6 +207,15 @@ jobs:
         uses: "actions/checkout@v6"
         with:
           submodules: true
+      - name: Install NodeJS
+        uses: actions/setup-node@v5
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+      - name: "Install npm dependencies"
+        run: npm install
+        working-directory: ./docs
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -217,9 +226,11 @@ jobs:
           version: "${{ needs.prepare-environment.outputs.UV_VERSION }}"
       - name: Install dependencies
         run: uv sync --all-groups --all-extras
+      - name: Docs unit tests
+        run: npx --no-install vitest run
+        working-directory: ./docs
       - name: Validate generated documentation
         run: uv run invoke docs-validate
-
   validate-documentation-style:
     if: |
       always() && !cancelled() &&
@@ -236,6 +247,7 @@ jobs:
 
       # The official GitHub Action for Vale doesn't work, installing manually instead:
       # https://github.com/errata-ai/vale-action/issues/103
+      # cf -> https://github.com/nf-core/website/pull/3509
       - name: Download Vale
         run: |
           curl -sL "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" -o vale.tar.gz

.github/workflows/sync-docs.yml

@@ -8,8 +8,9 @@ on:
       - stable
     paths:
       - 'docs/docs/**'
-      - 'docs/sidebars-infrahubctl.ts'
-      - 'docs/sidebars-python-sdk.ts'
+      - 'docs/sidebars/sidebars-infrahubctl.ts'
+      - 'docs/sidebars/sidebars-python-sdk.ts'
+      - 'docs/sidebars/sidebar-utils.ts'
 
 jobs:
   sync:
@@ -33,8 +34,9 @@ jobs:
           rm -f target-repo/docs/sidebars-python-sdk.ts
           rm -f target-repo/docs/sidebars-infrahubctl.ts
           cp -r source-repo/docs/docs/* target-repo/docs/docs-python-sdk/
-          cp source-repo/docs/sidebars-infrahubctl.ts target-repo/docs/
-          cp source-repo/docs/sidebars-python-sdk.ts target-repo/docs/
+          cp source-repo/docs/sidebars/sidebars-infrahubctl.ts target-repo/docs/
+          cp source-repo/docs/sidebars/sidebars-python-sdk.ts target-repo/docs/
+          cp source-repo/docs/sidebars/sidebar-utils.ts target-repo/docs/
           cd target-repo
           git config user.name github-actions
           git config user.email github-actions@github.com

.vale.ini

@@ -23,3 +23,10 @@ BasedOnStyles =
 
 [*]
 BasedOnStyles = Infrahub
+
+# Generated API reference docs: use GeneratedRef spelling (allows snake_case)
+# instead of global Infrahub spelling. Must be last to override [*].
+[docs/docs/python-sdk/sdk_ref/**/*.mdx]
+BasedOnStyles = Infrahub, GeneratedRef
+Infrahub.spelling = NO
+BlockIgnores = (?s) *((import.*?\n)|(```.*?```\n))

.vale/styles/GeneratedRef/spelling.yml

@@ -0,0 +1,10 @@
+---
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+filters:
+  - '[pP]y.*\b'
+  - '\bimport_.*\b' # Ignore variables starting with 'import_'
+  - '\w+__value' # Skip Infrahub filters in documentation (name__value)
+  - '\b\w+_\w+\b' # Ignore snake_case identifiers in generated API reference docs
+ignore: spelling-exceptions.txt

.vale/styles/Infrahub/sentence-case.yml

@@ -52,6 +52,7 @@ exceptions:
   - Jinja
   - Jinja2
   - JWT
+  - MDX
   - Namespace
   - NATS
   - Node

.vale/styles/Infrahub/spelling.yml

@@ -4,6 +4,6 @@ message: "Did you really mean '%s'?"
 level: error
 filters:
   - '[pP]y.*\b'
-  - '\bimport_.*\b' # New filter to ignore variables starting with 'import_'
-  - '\w+__value' # New filter to skip Infrahub filters in documentation (name__value)
+  - '\bimport_.*\b' # Ignore variables starting with 'import_'
+  - '\w+__value' # Skip Infrahub filters in documentation (name__value)
 ignore: spelling-exceptions.txt

.vale/styles/spelling-exceptions.txt

@@ -3,6 +3,7 @@ Alibaba
 Ansible
 append_git_suffix
 APIs
+Args
 artifact_definitions
 artifact_name
 async
@@ -78,6 +79,7 @@ kbps
 Keycloak
 Loopbacks
 markdownlint
+MDX
 max_count
 memgraph
 menu_placement

AGENTS.md

@@ -7,8 +7,10 @@ Infrahub Python SDK - async/sync client for Infrahub infrastructure management.
 ```bash
 uv sync --all-groups --all-extras   # Install all deps
 uv run invoke format                # Format code
-uv run invoke lint                  # All linters (code + yamllint + documentation)
+uv run invoke lint                  # Full pipeline: ruff, yamllint, ty, mypy, markdownlint, vale
 uv run invoke lint-code             # All linters for Python code
+uv run invoke docs-generate         # Generate all docs (CLI + SDK)
+uv run invoke docs-validate         # Check generated docs match committed version
 uv run pytest tests/unit/           # Unit tests
 uv run pytest tests/integration/    # Integration tests
 ```
@@ -54,7 +56,7 @@ Key rules:
 ✅ **Always**
 
 - Run `uv run invoke format lint-code` before committing Python code
-- Run `uv run invoke generate-sdk generate-infrahubctl` after changing CLI commands or SDK config
+- Run `uv run invoke docs-generate` after creating, modifying or deleting CLI commands, SDK config, or Python docstrings
 - Run markdownlint before committing markdown changes
 - Follow async/sync dual pattern for new features
 - Use type hints on all function signatures

CHANGELOG.md

@@ -10,6 +10,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/opsmill/infrahub/tree/develop/infrahub/python_sdk/changelog/>.
 
 <!-- towncrier release notes start -->
+
+## [1.19.0](https://github.com/opsmill/infrahub-sdk-python/tree/v1.19.0) - 2026-03-16
+
+### Added
+
+- Added support for FileObject nodes with file upload and download capabilities. New methods `upload_from_path(path)` and `upload_from_bytes(content, name)` allow setting file content before saving, while `download_file(dest)` enables downloading files to memory or streaming to disk for large files. ([#ihs193](https://github.com/opsmill/infrahub-sdk-python/issues/ihs193))
+- Python SDK API documentation is now generated directly from the docstrings of the classes, functions, and methods contained in the code. ([#201](https://github.com/opsmill/infrahub-sdk-python/issues/201))
+- Added a 'py.typed' file to the project. This is to enable type checking when the Infrahub SDK is imported from other projects. The addition of this file could cause new typing issues in external projects until all typing issues have been resolved. Adding it to the project now to better highlight remaining issues.
+
+### Changed
+
+- Updated branch report command to use node metadata for proposed change creator information instead of the deprecated relationship-based approach. Requires Infrahub 1.7 or above.
+
+### Fixed
+
+- Allow SDK tracking feature to continue after encountering delete errors due to impacted nodes having already been deleted by cascade delete. ([#265](https://github.com/opsmill/infrahub-sdk-python/issues/265))
+- Fixed Python SDK query generation regarding from_pool generated attribute value ([#497](https://github.com/opsmill/infrahub-sdk-python/issues/497))
+
 ## [1.18.1](https://github.com/opsmill/infrahub-sdk-python/tree/v1.18.1) - 2026-01-08
 
 ### Fixed

dev/commands/feedback.md

@@ -0,0 +1,92 @@
+# Session Feedback
+
+Analyze this conversation and identify what documentation or context was missing, incomplete, or incorrect. The goal is to continuously improve the project's knowledge base so future conversations are more efficient.
+
+## Step 1: Session Analysis
+
+Reflect on the work done in this conversation. For each area, identify friction points:
+
+1. **Exploration overhead**: What parts of the codebase did you have to discover by searching that should have been documented? (e.g., patterns, conventions, module responsibilities)
+2. **Wrong assumptions**: Did you make incorrect assumptions due to missing or misleading documentation?
+3. **Repeated patterns**: Did you discover recurring patterns or conventions that aren't documented anywhere?
+4. **Missing context**: What background knowledge would have helped you start faster? (e.g., architecture decisions, data flow, naming conventions)
+5. **Tooling gaps**: Were there commands, scripts, or workflows that you had to figure out?
+
+## Step 2: Documentation Audit
+
+For each friction point identified, determine the appropriate fix. Check the existing documentation to avoid duplicating what's already there:
+
+- `AGENTS.md` — Top-level project instructions and component map
+- `CLAUDE.md` — Entry point referencing AGENTS.md
+- `docs/AGENTS.md` — Documentation site guide
+- `infrahub_sdk/ctl/AGENTS.md` — CLI development guide
+- `infrahub_sdk/pytest_plugin/AGENTS.md` — Pytest plugin guide
+- `tests/AGENTS.md` — Testing guide
+
+Read the relevant existing files to understand what's already documented before proposing changes.
+
+## Step 3: Generate Report
+
+Present the feedback as a structured report with the following sections. Only include sections that have content — skip empty sections.
+
+### Format
+
+```markdown
+## Session Feedback Report
+
+### What I Was Working On
+<!-- Brief summary of the task(s) performed in this conversation -->
+
+### Documentation Gaps
+<!-- Things that should be documented but aren't -->
+
+For each gap:
+
+- **Topic**: What's missing
+- **Where**: Which file should contain this (existing file to update, or new file to create)
+- **Why**: How this would have helped during this conversation
+- **Suggested content**: A draft of what should be added (be specific and actionable)
+
+### Documentation Corrections
+<!-- Things that are documented but wrong or misleading -->
+
+For each correction:
+
+- **File**: Path to the file
+- **Issue**: What's wrong or misleading
+- **Fix**: What it should say instead
+
+### Discovered Patterns
+<!-- Conventions or patterns found in the code that aren't documented -->
+
+For each pattern:
+
+- **Pattern**: Description of the convention
+- **Evidence**: Where in the code this pattern is used (file paths)
+- **Where to document**: Which AGENTS.md or guide file should capture this
+
+### Memory Updates
+<!-- Propose additions/changes to MEMORY.md for cross-session persistence -->
+
+For each update:
+
+- **Action**: Add / Update / Remove
+- **Content**: What to write
+- **Reason**: Why this is worth remembering across sessions
+```
+
+## Step 4: Apply Changes
+
+After presenting the report, ask the user which changes they want to apply. Present the options:
+
+1. **Apply all** — Create/update all proposed documentation files and memory
+2. **Cherry-pick** — Let the user select which changes to apply
+3. **None** — Just keep the report as reference, don't modify any files
+
+
+For approved changes:
+
+- Edit existing files when updating documentation
+- Create new files only when no appropriate existing file exists
+- Update `MEMORY.md` with approved memory changes
+- Keep all changes minimal and focused — don't over-document

dev/commands/pre-ci.md

@@ -0,0 +1,36 @@
+Run a subset of fast CI checks locally. These are lightweight validations that catch common issues before pushing. Run all steps and report a summary at the end.
+
+## Steps
+
+1. **Format** Python code:
+   ```bash
+   uv run invoke format
+   ```
+
+2. **Lint** (YAML, Ruff, ty, mypy, markdownlint, vale):
+   ```bash
+   uv run invoke lint
+   ```
+
+3. **Python unit tests**:
+   ```bash
+   uv run pytest tests/unit/
+   ```
+
+4. **Docs unit tests** (vitest):
+   ```bash
+   (cd docs && npx --no-install vitest run)
+   ```
+
+5. **Validate generated documentation** (regenerate and check for drift):
+   ```bash
+   uv run invoke docs-validate
+   ```
+
+## Instructions
+
+- Run each step in order using the Bash tool.
+- If a step fails, continue with the remaining steps.
+- At the end, print a summary table of all steps with pass/fail status.
+- Do NOT commit or push anything.
+

docs/AGENTS.md

@@ -1,4 +1,4 @@
-# docs/AGENTS.md
+# Documentation agents
 
 Docusaurus documentation following Diataxis framework.
 
@@ -8,8 +8,10 @@ Docusaurus documentation following Diataxis framework.
 cd docs && npm install              # Install deps
 cd docs && npm start                # Dev server at localhost:3000
 cd docs && npm run build            # Build static site
-uv run invoke docs                  # Generate auto-docs
-uv run invoke docs-validate         # Validate docs are current
+cd docs && npm test                 # Run sidebar utility tests
+uv run invoke docs                  # Build documentation website
+uv run invoke docs-generate         # Regenerate all docs (infrahubctl CLI + Python SDK)
+uv run invoke docs-validate         # Check that generated docs match committed files
 ```
 
 ## Structure
@@ -23,13 +25,21 @@ docs/docs/
 └── infrahubctl/     # CLI docs (auto-generated)
 ```
 
-## Adding Documentation
+## Sidebars
+
+Sidebar navigation is dynamic: `sidebars-*.ts` files read the filesystem at build time via utility functions in `sidebar-utils.ts`.
+
+- **infrahubctl**: all `.mdx` files are discovered automatically and sorted alphabetically.
+- **python-sdk**: guides, topics, and reference sections preserve a defined display order; new files are appended alphabetically at the end.
+
+No manual sidebar update is needed when adding a new `.mdx` file. However, to control the display order of a new page, add its doc ID to the ordered list in the corresponding `sidebars-*.ts` file.
+
+## Adding documentation
 
 1. Create MDX file in appropriate directory
 2. Add frontmatter with `title`
-3. Update `sidebars-*.ts` for navigation
 
-## MDX Pattern
+## MDX pattern
 
 Use Tabs for async/sync examples, callouts for notes:
 
@@ -52,9 +62,11 @@ Use callouts for important notes.
 ✅ **Always**
 
 - Include both async/sync examples using Tabs
-- Run `uv run invoke docs-validate` after code changes
+- Run `uv run invoke docs-validate` after code changes to verify generated docs are up to date
 
 🚫 **Never**
 
-- Edit `docs/infrahubctl/*.mdx` directly (regenerate with `uv run invoke generate-infrahubctl`)
-- Edit `docs/python-sdk/reference/config.mdx` directly (regenerate with `uv run invoke generate-sdk`)
+- Edit `docs/infrahubctl/*.mdx` directly (regenerate with `uv run invoke docs-generate`)
+- Edit `docs/python-sdk/reference/config.mdx` directly (regenerate with `uv run invoke docs-generate`)
+- Edit `docs/python-sdk/reference/templating.mdx` directly (regenerate with `uv run invoke docs-generate`)
+- Edit `docs/python-sdk/sdk_ref/**/*.mdx` directly (regenerate with `uv run invoke docs-generate`)

docs/_templates/sdk_config.j2

@@ -31,8 +31,6 @@ The following settings can be defined in the `Config` class
 {% for property in properties %}
 <!-- vale off -->
 ## {{ property.name }}
-
-**Property**: {{ property.name }}<br />
 <!-- vale on -->
 **Description**: {% if '\n' in property.description %} {% endif %}{{ property.description }}<br />
 **Type**: `{{ property.type }}`<br />

docs/docs/python-sdk/guides/client.mdx

@@ -251,7 +251,7 @@ Your client is now configured to use the specified default branch instead of `ma
 
 ## Hello world example
 
-Let's create a simple "Hello World" example to verify your client configuration works correctly. This example will connect to your Infrahub instance and query the available accounts.
+Let's create a "Hello World" example to verify your client configuration works correctly. This example will connect to your Infrahub instance and query the available accounts.
 
 1. Create a new file called `hello_world.py`: