+## Sources of Truth

+

+There are two separate host tables, with separate ownership:

+

+| Table | File / Location | Owner | What Belongs There |

+| --- | --- | --- | --- |

+| Local table | `inventory/hosts-local.yaml` in this repo | Us / Bogdan local workstation | Local lab hosts, local defaults, local key paths, and local overrides required for this Mac |

+| NextGen table | `nextgen@192.168.2.103:/home/nextgen/projects/ssh-infrastructure/inventory/hosts.yaml` | NextGen / upstream | Company-managed NextGen host list: porta, pbx, radius, voip, network gear, and upstream defaults |

+

+Operational rule:

+

+```text

+inventory/hosts-local.yaml is our local source of truth.

+inventory/hosts.yaml is a local copy of the NextGen upstream table.

+```

+

+Do not put local-only fixes into the upstream table unless they are true for

+NextGen as well. Keep Mac/local requirements in `inventory/hosts-local.yaml`.

+

+The effective local config is generated from both files:

+

+```text

+inventory/hosts.yaml        <- copied/synced from nextgen upstream

+inventory/hosts-local.yaml  <- maintained locally by us

+  -> tools/generate-configs.py

+  -> generated/client.conf

+  -> ~/.ssh/config

+```

+

+Critical local overrides currently required:

+

+```yaml

+entrypoints:

+  is_jumper:

+    identity_file: ~/.ssh/keys/is-jumper_ed25519

+    identities_only: true

+

+jumps:

+  j1:

+    user: bogdan.timofte

+  j2:

+    user: bogdan.timofte

+```

+

+The sync script updates only the local copy of the upstream table:

+

+```bash

+tools/sync-hosts-from-upstream.sh

+```

+

+After every sync, verify the local overlay still produces the right effective

+config:

+

+```bash

+ssh -G j1 | grep -E '^(hostname|user|port) '

+ssh -G is-jumper | grep -E '^(hostname|user|identityfile|identitiesonly) '

+```

+

+Expected:

+

+```text

+user bogdan.timofte

+identityfile ~/.ssh/keys/is-jumper_ed25519

+```

+