diff --git a/CLAUDE.md b/CLAUDE.md
index f974c3a..4c28566 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,35 +1,82 @@
-# Claude Code Instructions — Schema Refinement
+# Claude Code Instructions — fabric-orchestrator
 
 ## Project Context
-This is a fabric-orchestrator project managing Arista EVPN-VXLAN fabrics.
-Branch: `feature/41-infrahub-schema`
-Schema files are in `schemas/` directory (Infrahub YAML format).
 
-## Reference Topology (from overlaid.net)
-- 2 spines (AS 65000), 8 leafs in 4 MLAG pairs (AS 65001-65004)
-- Loopback0: BGP router-id, Loopback1: shared VTEP IP per MLAG pair
-- VLANs 4090/4091: MLAG peering with trunk groups
-- EVPN overlay via eBGP multihop on loopbacks
-- L2VXLAN (Type-2) and L3VXLAN (Type-5) with VRFs
+Fabric-orchestrator manages Arista EVPN-VXLAN fabrics using Infrahub as the source of truth.
+Gitea: https://gitea.arnodo.fr/Damien/fabric-orchestrator
+Branch: `feature/41-infrahub-schema`
+
+## Reference Topology (overlaid.net)
+
+- 2 spines (AS 65000), 8 leafs in 4 MLAG pairs (AS 65001–65004)
+- Loopback0: BGP router-id per device, Loopback1: shared VTEP IP per MLAG pair
+- VLANs 4090 (MLAG peer) / 4091 (MLAG iBGP) with trunk groups
+- Underlay: eBGP point-to-point (spine↔leaf) + iBGP (leaf↔leaf peer)
+- Overlay: EVPN eBGP multihop on loopbacks, spines as route-reflectors with next-hop-unchanged
+- L2VXLAN (EVPN Type-2): VLAN→VNI mapping, redistribute learned
+- L3VXLAN (EVPN Type-5): VRF→VNI mapping, redistribute connected
+- Border peering: BGP sessions inside VRF (leaf7/8 → AS 64999 in VRF gold)
+
+## Schema Files (Infrahub YAML format, in `schemas/`)
+
+| File             | Content                                                                       |
+| ---------------- | ----------------------------------------------------------------------------- |
+| `base.yml`       | Device, Interfaces (Ethernet, Loopback, Vlan, Lag, Vxlan), IPAddress          |
+| `bgp.yml`        | AutonomousSystem, BGPRouterConfig, BGPPeerGroup, BGPSession, BGPAddressFamily |
+| `vlan_vxlan.yml` | VLAN, VNI, VTEP, VlanVniMapping, EVPNInstance                                 |
+| `vrf.yml`        | VRFConfig, RouteTarget, VRFDeviceAssignment                                   |
+| `mlag.yml`       | MlagDomain, MlagPeerConfig, MlagInterface                                     |
+| `extensions.yml` | UnderlayLink, HostConnection, FabricSettings                                  |
 
 ## Infrahub Schema Rules
-1. `human_friendly_id` attributes MUST have `unique: true`
-2. If human_friendly_id needs to be scoped per-device, traverse Parent
-   relationships: `parent_rel__parent_attr__value`
-3. Parent relationships need `optional: false` explicitly
+
+1. `human_friendly_id` fields MUST have `unique: true` — globally unique across all instances
+2. To scope human_friendly_id per-device, traverse Parent relationships:
+   `parent_rel__parent_attr__value` (e.g. `device__name__value`)
+3. Parent relationships (`kind: Parent`) need `optional: false` explicitly
 4. Self-referencing relationships need `direction: outbound`
-5. Multiple relationships to same peer type need unique `identifier`
-6. Validate with: `infrahubctl schema check schemas/`
+5. Multiple relationships to the same peer type need distinct `identifier` values
+6. Don't model the same concept twice (e.g. VTEP source_address vs InterfaceVxlan source_interface)
+7. `kind: Attribute` for association, `kind: Component` for ownership (lifecycle-coupled)
+8. `kind: Parent` implies the child cannot exist without the parent
+
+## Validation
+
+```bash
+infrahubctl schema check schemas/
+```
+
+Always run before committing. Fix any errors before pushing.
 
 ## Commit Convention
-- Reference issue: `fix(schema): description — refs #41`
-- One logical change per commit
-- Run schema validation before committing
 
-## Files
-- `schemas/base.yml` — Device, Interfaces, IPAddress
-- `schemas/bgp.yml` — AS, BGPRouterConfig, PeerGroup, Session, AF
-- `schemas/vlan_vxlan.yml` — VLAN, VNI, VTEP, VlanVniMapping, EVPN
-- `schemas/vrf.yml` — VRF, RouteTarget, VRFDeviceAssignment
-- `schemas/mlag.yml` — MlagDomain, MlagPeerConfig, MlagInterface
-- `schemas/extensions.yml` — UnderlayLink, HostConnection, FabricSettings
+```
+fix(schema): short description — refs #<issue>
+feat(schema): short description — refs #<issue>
+```
+
+- One logical change per commit
+- Reference the Gitea issue number
+- Comment on the issue after implementation with changes summary
+
+## Open Issues (prioritized)
+
+Check https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues for current backlog.
+Critical issues (blocking data load) take priority over functional improvements.
+Dependency chain: resolve critical → significant → minor sequentially.
+
+## Workflow
+
+1. Read the issue description fully before starting
+2. Read relevant schema files to understand current state
+3. Make minimal, targeted changes
+4. Validate with `infrahubctl schema check schemas/`
+5. Commit with proper message referencing the issue
+6. Comment on the Gitea issue with what was changed
+
+## Don'ts
+
+- Don't add fields not needed by the reference topology
+- Don't change `human_friendly_id` without checking uniqueness implications
+- Don't remove existing relationships without checking reverse dependencies
+- Don't create new schema files without discussing first