Merge 'infrahub-develop' into 'stable'

.specify/scripts/bash/common.sh

@@ -28,7 +28,7 @@ get_current_branch() {
 
     # For non-git repos, try to find the latest feature directory
     local repo_root=$(get_repo_root)
-    local specs_dir="$repo_root/specs"
+    local specs_dir="$repo_root/dev/specs"
 
     if [[ -d "$specs_dir" ]]; then
         local latest_feature=""
@@ -81,14 +81,14 @@ check_feature_branch() {
     return 0
 }
 
-get_feature_dir() { echo "$1/specs/$2"; }
+get_feature_dir() { echo "$1/dev/specs/$2"; }
 
 # Find feature directory by numeric prefix instead of exact branch match
 # This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
 find_feature_dir_by_prefix() {
     local repo_root="$1"
     local branch_name="$2"
-    local specs_dir="$repo_root/specs"
+    local specs_dir="$repo_root/dev/specs"
 
     # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
     if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
@@ -99,7 +99,7 @@ find_feature_dir_by_prefix() {
 
     local prefix="${BASH_REMATCH[1]}"
 
-    # Search for directories in specs/ that start with this prefix
+    # Search for directories in dev/specs/ that start with this prefix
     local matches=()
     if [[ -d "$specs_dir" ]]; then
         for dir in "$specs_dir"/"$prefix"-*; do

.specify/templates/plan-template.md

@@ -1,7 +1,7 @@
 # Implementation Plan: [FEATURE]
 
 **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
-**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+**Input**: Feature specification from `/dev/specs/[###-feature-name]/spec.md`
 
 **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
 
@@ -38,7 +38,7 @@
 ### Documentation (this feature)
 
 ```text
-specs/[###-feature]/
+dev/specs/[###-feature]/
 ├── plan.md              # This file (/speckit.plan command output)
 ├── research.md          # Phase 0 output (/speckit.plan command)
 ├── data-model.md        # Phase 1 output (/speckit.plan command)

.specify/templates/tasks-template.md

@@ -5,7 +5,7 @@ description: "Task list template for feature implementation"
 
 # Tasks: [FEATURE NAME]
 
-**Input**: Design documents from `/specs/[###-feature-name]/`
+**Input**: Design documents from `/dev/specs/[###-feature-name]/`
 **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
 
 **Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.

.vale/styles/spelling-exceptions.txt

@@ -133,6 +133,7 @@ validators
 Version Control
 Vitest
 VLANs
+yaml
 Yaml
 yamllint
 YouTube

AGENTS.md

@@ -87,6 +87,14 @@ 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)

changelog/+artifact-composition.added.md

@@ -0,0 +1 @@
+Add `artifact_content`, `file_object_content`, `from_json`, and `from_yaml` Jinja2 filters for artifact content composition in templates.

changelog/+artifact-composition.changed.md

@@ -0,0 +1 @@
+Replace `FilterDefinition.trusted: bool` with flag-based `ExecutionContext` model (`CORE`, `WORKER`, `LOCAL`) for context-aware template validation. `validate()` now accepts an optional `context` parameter. Backward compatible.

changelog/+infp380.removed.md

@@ -0,0 +1 @@
+Removed the deprecated `raise_for_error` argument from `execute_graphql`, `query_gql_query`, `get_diff_summary`, `allocate_next_ip_address`, and `allocate_next_ip_prefix` client methods. HTTP errors are now always raised via `resp.raise_for_status()`.

changelog/654.fixed.md

@@ -0,0 +1 @@
+Allow direct assignment of authentication method to the configuration to override settings from environment variables.

changelog/958.fixed.md

@@ -0,0 +1 @@
+Fixed `ObjectStore.get()` and `ObjectStore.upload()` silently swallowing non-2xx HTTP errors instead of raising them.

dev/commands/speckit.specify.md

@@ -47,7 +47,7 @@ Given that feature description, do this:
    b. Find the highest feature number across all sources for the short-name:
       - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
       - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
-      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+      - Specs directories: Check for directories matching `dev/specs/[0-9]+-<short-name>`
 
    c. Determine the next available number:
       - Extract all numbers from all three sources

dev/knowledge/cli-architecture.md

@@ -0,0 +1,51 @@
+# CLI Architecture
+
+The `infrahubctl` CLI is built with [Typer](https://typer.tiangolo.com/) via a custom `AsyncTyper` subclass that supports async command functions.
+
+## Entry point
+
+The main Typer app lives in `infrahub_sdk/ctl/cli_commands.py`. It is re-exported through `infrahub_sdk/ctl/cli.py` which adds the `infrahubctl` entry point name.
+
+## Command hierarchy
+
+Commands are organized in two tiers:
+
+- **Root commands** are registered directly on the main app with `app.command()`. These are standalone operations that don't belong to a logical group (e.g. `dump`, `load`, `check`, `render`, `run`, `transform`, `protocols`, `version`, `info`).
+- **Subcommand groups** are separate `AsyncTyper()` instances registered with `app.add_typer(sub_app, name="group")`. Each group lives in its own module under `infrahub_sdk/ctl/`. Current groups: `branch`, `schema`, `validate`, `repository`, `menu`, `object`, `graphql`, `task`.
+
+## Adding a new command
+
+For a **root command**, define the function in the appropriate module and register it in `cli_commands.py`:
+
+```python
+app.command(name="mycommand")(my_function)
+```
+
+For a **subcommand**, add it to the relevant group's package or module. For example, object subcommands live in `infrahub_sdk/ctl/object/` and are registered on the object app in `__init__.py`.
+
+## Group packages
+
+When a subcommand group has multiple commands, it lives as a package (directory with `__init__.py`) rather than a single module file. The `object` group is the reference example:
+
+```text
+infrahub_sdk/ctl/object/
+├── __init__.py    # App, callback, load/validate commands, registers CRUD
+├── create.py      # create subcommand
+├── delete.py      # delete subcommand
+├── get.py         # get subcommand
+├── update.py      # update subcommand
+└── utils.py       # Shared utilities (resolve_node, etc.)
+```
+
+Each command file contains a single command function. Shared logic goes in `utils.py`. The `__init__.py` wires everything together by importing and registering commands on the group's `AsyncTyper` app. Other groups that grow beyond a single file should follow this same pattern.
+
+## Decorators
+
+- `@catch_exception(console=console)` wraps commands for consistent error handling via Rich.
+- Async commands work natively thanks to `AsyncTyper`.
+
+## Design rules
+
+**Always check if a new command belongs in an existing group before adding it at the root.** A command that operates on a specific resource type (objects, branches, schemas, etc.) should go under the matching subgroup, not at the top level. Root-level commands are reserved for cross-cutting or standalone operations (e.g. `run`, `version`, `info`).
+
+When in doubt, look at what the command acts on and find the group that matches. For example, anything that creates, reads, updates, or deletes Infrahub objects belongs under `object`, not at the root.

dev/knowledge/cli-design-principles.md

@@ -0,0 +1,45 @@
+# CLI Design Principles
+
+Guidelines for writing `infrahubctl` commands. These complement the structural rules in `cli-architecture.md`.
+
+## Don't pre-validate what the server validates
+
+The CLI's job is to translate user intent into API calls, not to reimplement server-side logic. When in doubt, just fire the request and let the server respond.
+
+**Avoid**:
+
+- Extra round-trips to check whether an object already exists before creating it
+- Re-implementing uniqueness, permission, or referential-integrity checks client-side
+- Heuristics that guess at server behavior (e.g., deriving identifiers from partial data to simulate a lookup)
+
+**Why this matters**:
+
+- Pre-validation is stale by the time the real call is made (TOCTOU).
+- The server returns better errors than the CLI can construct.
+- Every client-side check is a duplication that will drift from the server implementation.
+- Extra calls slow the CLI down and make it feel laggy on high-latency links.
+
+**Exception**: local-only validation that doesn't need the server is fine — malformed `--set` arguments, mutually exclusive flags, missing required options, etc. The test is: "could the server figure this out from the request alone?" If yes, let the server do it.
+
+## Prefer HFID over `default_filter`
+
+When resolving identifiers, HFID (human-friendly ID) is the long-term path. `default_filter` is deprecated and will be removed. New code should not depend on it, and existing code should be written so its removal is a straightforward change.
+
+## Output phrasing should match semantics
+
+Messages like `Created`, `Updated`, `Deleted` are promises about what actually happened. When using upsert semantics (`allow_upsert=True`), the CLI genuinely doesn't know whether the object was created or updated — so use neutral phrasing like `Saved` or `Applied`. Don't lie to the user for the sake of a cleaner message.
+
+## Deduplicate redundant output
+
+When printing an object's label and ID, check that they're actually different before printing both. Many objects have `display_label == id`, in which case repeating the value adds noise:
+
+```python
+if node.display_label and node.display_label != node.id:
+    console.print(f"Saved {kind} '{node.display_label}' (ID: {node.id})")
+else:
+    console.print(f"Saved {kind} (ID: {node.id})")
+```
+
+## Raise errors directly, don't invoke dead calls
+
+If the CLI has determined a call will fail (e.g., no lookup strategy matched), raise the appropriate exception directly rather than making a request you know will error out just to piggyback on the server's error message. The request is wasted network traffic and the roundabout path is harder to read.

dev/knowledge/doc-generation.md

@@ -0,0 +1,40 @@
+# Documentation Generation
+
+CLI and SDK documentation is auto-generated from code. Always regenerate after changing commands, config, or public docstrings.
+
+## How to run
+
+```bash
+uv run invoke docs-generate    # Generate all docs (CLI + SDK)
+uv run invoke docs-validate    # Verify generated docs match committed versions
+```
+
+## CLI documentation
+
+Defined in `tasks.py` (`_generate_infrahubctl_documentation`). The process:
+
+1. Deletes all existing `infrahubctl-*.mdx` files in `docs/docs/infrahubctl/`.
+2. Iterates `app.registered_commands` and creates a `TyperSingleCommand` for each.
+3. Iterates `app.registered_groups` and creates a `TyperGroupCommand` for each.
+4. Each command object generates an mdx file via `typer ... utils docs`.
+
+### How it maps to files
+
+- A **root command** named `foo` produces `infrahubctl-foo.mdx` using:
+  `uv run typer --func foo infrahub_sdk.ctl.cli_commands utils docs --name "infrahubctl foo"`
+- A **subcommand group** named `bar` produces `infrahubctl-bar.mdx` using:
+  `uv run typer infrahub_sdk.ctl.bar utils docs --name "infrahubctl bar"`
+
+The group variant documents all subcommands within that group automatically.
+
+### Key implication
+
+Moving a command from root to a group (or vice versa) changes which mdx files get generated. The old files are cleaned up automatically by the glob delete, but the new ones only appear after running `docs-generate`. Always regenerate and commit the result.
+
+## SDK documentation
+
+Other doc generators cover SDK config, compatibility matrix, templates, and API reference. These are independent of CLI structure and are also triggered by `docs-generate`.
+
+## Validation in CI
+
+`docs-validate` diffs the generated output against the committed files. If they don't match, CI fails. This ensures docs stay in sync with code.

dev/specs/001-end-user-cli/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: End-User CLI (`infrahubctl` command)
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-28
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass validation. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
+- Assumptions section documents reasonable defaults for unspecified details.
+- CLI command examples in acceptance scenarios use generic syntax (not framework-specific).

dev/specs/001-end-user-cli/contracts/cli-commands.md

@@ -0,0 +1,64 @@
+# CLI Command Contracts
+
+## Global Options
+
+All commands accept:
+
+- `--branch TEXT` — Target Infrahub branch (default: from config)
+- `--config-file PATH` — Configuration file path (default: infrahubctl.toml)
+- `--output [table|json|csv|yaml]` — Output format (default: table if TTY, json if piped)
+
+## `infrahubctl get <kind> [identifier]`
+
+**List mode** (no identifier):
+
+- Input: kind (positional), --filter (repeatable), --limit INT, --offset INT
+- Output: Table with columns for each attribute + relationship (display names)
+- Exit 0: results found | Exit 80: no results (empty list) | Exit 1: invalid kind
+
+**Detail mode** (with identifier):
+
+- Input: kind (positional), identifier (positional — UUID or display name)
+- Output: Key-value display of all attributes, relationships, metadata
+- Exit 0: found | Exit 1: not found
+
+**Filters**: `--filter name__value="spine01"` (repeatable)
+
+## `infrahubctl create <kind>`
+
+- Input: kind (positional), --set key=value (repeatable), --file PATH
+- --set and --file are mutually exclusive
+- Output: Confirmation with created object ID and display label
+- Exit 0: created | Exit 1: validation error | Exit 1: server error
+
+**File input**: JSON or YAML in Infrahub Object format
+(`apiVersion: infrahub.app/v1`)
+
+## `infrahubctl update <kind> <identifier>`
+
+- Input: kind (positional), identifier (positional), --set key=value
+  (repeatable), --file PATH
+- --set and --file are mutually exclusive
+- Output: Confirmation with old → new values for changed fields
+- Exit 0: updated | Exit 1: not found | Exit 1: validation error
+
+## `infrahubctl delete <kind> <identifier>`
+
+- Input: kind (positional), identifier (positional), --yes (skip confirmation)
+- Output: Confirmation prompt (unless --yes), then success message
+- Exit 0: deleted | Exit 1: not found | Exit 1: dependency conflict
+
+## `infrahubctl schema list`
+
+- Input: --filter TEXT (substring match on kind name)
+- Output: Table with columns: Namespace, Name, Kind, Description
+- Exit 0: always (empty table if no matches)
+
+## `infrahubctl schema show <kind>`
+
+- Input: kind (positional)
+- Output: Formatted display of:
+  - Kind metadata (namespace, label, description, display_labels, HFID)
+  - Attributes table (name, type, required, default, description)
+  - Relationships table (name, peer kind, cardinality, optional)
+- Exit 0: found | Exit 1: invalid kind