docs(vibe): bootstrap vibe/ knowledge tree + ecosystem AGENTS.md

Add a root AGENTS.md (ecosystem map of factory/tools/cms + agent operating
rules + the persona cohort & workflow) and a new vibe/ knowledge base for LLM
agents, modeled on tree-docs conventions and the factory house style.

vibe/ folders (each with a README hub + contribution rules):
- ADR/      optimized MADR-lite; canonical home going forward (doc/adr stays historical)
- PRD/      one subfolder per PRD, mandatory STATUS.md, QA strategy for big ones
- investigations/  single INV-NNN-slug.md, or stub + folder w/ notebooks
- guidebooks/      tree-docs maps; lab-ecosystem guidebook of factory+tools+cms
- runbooks/        [AGENT]/[HUMAN] step procedures (EN; doc/runbooks stays FR)
- shareouts/       dated FR handouts (decks/mp4)

Seed content (first ADR + PRD): a safe, production-like environment to rehearse
risky changes and recovery without touching real prod — local-only sandbox
(k3d + arm64 VMs) with a hard prod/sandbox isolation boundary. Includes
INV-001 (prod blast-radius couplings), the ecosystem guidebook, and a FR shareout.

Conventions enforced: no-tombstone rule, breadcrumb spine, bidirectional
cross-links, theme:base mermaid (MCP-validated) + ordered-list-after-diagram.
Built with a Workflow + persona cohort; 24 files, zero dead links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

vibe/guidebooks/lab-ecosystem/02-tools.md

@@ -0,0 +1,76 @@
+[vibe](../../README.md) > [Guidebooks](../README.md) > [Lab ecosystem](README.md) > **02 · tools**
+
+# 02 · tools
+
+> **Status:** ✅ Active
+> **Last Updated:** 2026-06-23
+> **Upstream:** [01 · factory](01-factory.md)
+> **Related:** [secrets-and-vault.md](secrets-and-vault.md) · [storage-and-recovery.md](storage-and-recovery.md)
+
+The [`tools` repo](https://gitea.arcodange.lab/arcodange-org/tools) is deployed by factory's ArgoCD into the **`tools` namespace**. It is the platform layer that every app namespace depends on: secrets (Vault + VSO), observability (Prometheus + Grafana), edge security (CrowdSec), database pooling (pgbouncer / pgcat), caching (Redis/KeyDB), and analytics (Plausible + ClickHouse). Each component ships its own Helm chart or Kustomize overlay, and most carry an `iac/` directory of OpenTofu that declares the Vault config (roles, policies, dynamic-secret backends) that wires the component to secrets — see [secrets-and-vault.md](secrets-and-vault.md).
+
+## Components in the `tools` namespace
+
+| Component | What it does | How declared | How it gets secrets |
+|---|---|---|---|
+| **Vault** | Secrets engine: KV v1 + v2, transit, PostgreSQL **dynamic creds**; auth backends `kubernetes` + Gitea **OIDC/JWT** | Helm chart + `iac/` (Vault config of itself + apps) | Is the source of truth; unsealed at boot (1 key, threshold 1) |
+| **VSO** (Vault Secrets Operator) | Injects Vault secrets into pods via `VaultAuth` + `VaultDynamicSecret` CRDs | Helm chart | Authenticates to Vault via **Kubernetes auth** (per-`<app>` role) |
+| **Prometheus** | Metrics scraping + storage | Helm (community subchart) | — (scrape configs) |
+| **Grafana** | Dashboards at `grafana.arcodange.lab`; datasources Prometheus + ClickHouse | Helm | Admin/datasource creds via VSO from Vault |
+| **CrowdSec** | Behavioural detection + **Traefik bouncer** for the public edge | Helm + `iac/` | **Dynamic secrets** from Vault (VSO) |
+| **pgbouncer** | Connection pooler to the **external** PostgreSQL on `pi2` | Helm | Auth via the per-app `user_lookup()` function (see [01 · factory](01-factory.md)); creds via VSO |
+| **pgcat** | Alternative pooler (optional, **not the default**) | Helm | VSO-injected creds when enabled |
+| **Redis / KeyDB** | In-memory cache; **KeyDB** master/replica (Redis-compatible) | Helm | VSO-injected auth when set |
+| **Plausible** | Privacy-friendly web analytics | **Kustomize** | VSO-injected creds; backed by ClickHouse |
+| **ClickHouse** | OLAP column store backing Plausible | **Kustomize** | VSO-injected creds |
+| **`tool`** | A Helm **library chart** — shared templates/helpers reused by the other charts (not itself deployable) | Helm library chart | n/a |
+
+## How tools fit together
+
+```mermaid
+%%{init: {'theme': 'base'}}%%
+flowchart TB
+    classDef store fill:#7c3aed,stroke:#6d28d9,color:#fff
+    classDef proc fill:#059669,stroke:#047857,color:#fff
+    classDef edge fill:#d97706,stroke:#b45309,color:#fff
+
+    VAULT[("Vault<br>single source of truth")]:::store
+    VSO["VSO<br>VaultAuth / VaultDynamicSecret"]:::proc
+    PG[("External PostgreSQL<br>pi2 · 192.168.1.202")]:::store
+    PGB["pgbouncer<br>pooler"]:::proc
+    APPS["app pods<br>(webapp, erp, …)"]:::proc
+    PROM["Prometheus"]:::proc
+    GRAF["Grafana<br>grafana.arcodange.lab"]:::proc
+    CH[("ClickHouse")]:::store
+    PLA["Plausible"]:::proc
+    CS["CrowdSec + Traefik bouncer"]:::edge
+
+    VAULT --> VSO
+    VSO -- "inject secrets" --> APPS
+    VSO -- "inject secrets" --> PGB
+    VSO -- "dynamic secret" --> CS
+    APPS --> PGB --> PG
+    PROM --> GRAF
+    CH --> GRAF
+    PLA --> CH
+```
+
+1. **Vault** holds every secret; **VSO** is the operator that delivers them into pods.
+2. VSO **injects** static and dynamic secrets into the app pods, into **pgbouncer**, and supplies **CrowdSec** its dynamic secret.
+3. App pods connect through **pgbouncer**, which pools connections to the **external PostgreSQL** on `pi2` (using the per-app `user_lookup()` function defined in factory's `postgres/iac/`).
+4. **Prometheus** scrapes metrics and **ClickHouse** stores analytics; both are wired as **Grafana** datasources.
+5. **Plausible** writes its analytics into **ClickHouse**.
+6. **CrowdSec** runs as a Traefik bouncer on the public edge, fed dynamic secrets from Vault — the same edge that fronts the CMS in [03 · cms](03-cms.md).
+
+## Where to look
+
+- Repo: [arcodange-org/tools](https://gitea.arcodange.lab/arcodange-org/tools) — each component is a top-level chart/overlay with its own `iac/`.
+- Vault config patterns: [hashicorp-vault/iac/modules](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/hashicorp-vault/iac) (e.g. `app_roles`, `app_policy`) — referenced by the [naming convention](../../../doc/runbooks/new-web-app/conventions.md).
+
+## Cross-references
+
+- [Lab ecosystem hub](README.md) — the whole-lab map.
+- [01 · factory](01-factory.md) — the ArgoCD that deploys this namespace, and the `postgres/iac/` roles + `user_lookup()` that pgbouncer consumes.
+- [03 · cms](03-cms.md) — the public edge protected by **CrowdSec** (Turnstile → CrowdSec wiring).
+- [secrets-and-vault.md](secrets-and-vault.md) — full Vault detail: KV/transit/dynamic engines, Gitea OIDC JWT, VSO injection.
+- [storage-and-recovery.md](storage-and-recovery.md) — Longhorn PVCs these stateful tools mount, and the Vault-unseal step in recovery.