chore(agentic): align AGENTS.md navigation + minimal .claude settings

.claude/hooks/session-start.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure the project virtualenv exists and is exported into the session.
+# Kept minimal: dev/integration dependency groups have incompatible transitive
+# pins, so we do not run `uv sync` here — just guarantee a venv is present.
+
+REPO_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+VENV_PATH="$REPO_ROOT/.venv"
+
+if [ ! -d "$VENV_PATH" ]; then
+  if command -v uv >/dev/null 2>&1; then
+    uv venv "$VENV_PATH" >&2
+  else
+    echo "session-start hook: 'uv' not found on PATH; skipping venv creation" >&2
+    exit 0
+  fi
+fi
+
+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
+  printf 'export VIRTUAL_ENV=%q\n' "$VENV_PATH" >> "$CLAUDE_ENV_FILE"
+  printf 'export PATH=%q:$PATH\n' "$VENV_PATH/bin" >> "$CLAUDE_ENV_FILE"
+fi

.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "enabledPlugins": {
+    "pyright-lsp@claude-plugins-official": true
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

.gitignore

@@ -13,5 +13,10 @@ docs/_build/*
 **/.pytest_cache
 .pytest_collections/
 
+# Runtime Claude Code artifacts (never tracked; settings.json and commands are tracked)
+.claude/quality-gates/
+.claude/scheduled_tasks.lock
+.claude/settings.local.json
+
 # https://github.com/ansible/ansible/issues/68499
 # ansible_collections/

AGENTS.md

@@ -2,6 +2,8 @@
 
 Ansible collection — modules, plugins, and inventory sources for [Infrahub](https://github.com/opsmill/infrahub), an infrastructure data platform.
 
+This file is the portable router: repo-wide facts every agent needs up front. Deeper how-tos, architecture notes, and decision records live under [dev/](dev/) — see Navigation below.
+
 - **Namespace / Collection:** `opsmill.infrahub` · **License:** GPLv3
 - **Repo:** <https://github.com/opsmill/infrahub-ansible> · **Docs:** <https://docs.infrahub.app/ansible/>
 - **Constitution (binding principles):** [.specify/memory/constitution.md](.specify/memory/constitution.md)