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

Add a router-framing sentence + Navigation (and File Structure) section
to AGENTS.md indexing dev/ docs and .agents/commands; add a minimal
.claude/settings.json (+ uv session-start hook) adapted from peer repos
(Node/TS bits stripped); gitignore runtime .claude/ artifacts. CLAUDE.md
unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Benoit Kohler

.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"
+          }
+        ]
+      }
+    ]
+  }
+}

.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,11 +2,34 @@
 
 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)
 - **Dev docs index:** [dev/README.md](dev/README.md) · **Decision records:** [dev/adr/](dev/adr/)
 
+## Navigation
+
+Internal developer docs are indexed in [dev/README.md](dev/README.md): architecture in [dev/knowledge/](dev/knowledge/) ([architecture](dev/knowledge/architecture.md), [plugin-patterns](dev/knowledge/plugin-patterns.md), [infrahub-sdk-usage](dev/knowledge/infrahub-sdk-usage.md)), how-to guides in [dev/guides/](dev/guides/) ([creating-a-module](dev/guides/creating-a-module.md), [running-tests](dev/guides/running-tests.md)), coding rules in [dev/guidelines/](dev/guidelines/) ([python](dev/guidelines/python.md), [testing](dev/guidelines/testing.md), [documentation](dev/guidelines/documentation.md), [git-workflow](dev/guidelines/git-workflow.md)), decisions in [dev/adr/](dev/adr/), binding principles in [.specify/memory/constitution.md](.specify/memory/constitution.md), and agent commands in [.agents/commands/](.agents/commands/).
+
+## File Structure
+
+```text
+plugins/modules/        Module stubs (DOCUMENTATION + AnsibleModule)
+plugins/action/         Action plugins (controller-side logic)
+plugins/module_utils/   Core shared code (infrahub_utils, node, branch, exception)
+plugins/inventory/      Dynamic inventory plugin
+plugins/lookup/         GraphQL lookup plugin
+plugins/doc_fragments/  Reusable DOCUMENTATION fragments
+tests/                  Unit + integration + sanity tests
+docs/                   Docusaurus site + generated plugin reference
+dev/                    Internal developer docs (knowledge, guides, guidelines, adr)
+.agents/                Portable agent sources (commands, skills)
+.specify/               Spec-kit (constitution, templates, workflows)
+.claude/                Claude Code adapter (settings, symlinked commands)
+```
+
 ## Tech Stack
 
 | Component | Version/Tool |