# CLAUDE.md — MakerFLOSS_Troubleshooting

Operating guide for working in this repo. This is a **troubleshooting workspace**
for MakerFLOSS hosts at the Orange Makerspace.

## What this repo is

Reference + thin runbooks. It does **not** hold authoritative IPs/topology/secrets
— those live in the source repos. Keep it that way; link, don't copy.

## Source repos (authoritative — most fixes land here)

- `~/Projects/AnsibleBaobabV4` — canonical infra-as-code: makerfloss VPS,
  `makerfloss1`, `mf04`, `wg1` WireGuard plane, Netbird control plane, all
  containers. Git remote = baobab Forgejo. Has Ansible vault (`prod`).
- `~/Projects/MakerFLOSS_Mikrotik` — the CRS310 switch. Ansible vault
  (`makerfloss`). Strict lockout-safety rules — read its CLAUDE.md before
  touching the device.
- `~/Projects/MakerFLOSS` — docs/slides site (docs.makerfloss.eu).

## Rules (decided 2026-06-09)

1. **Fixes go to the relevant source repo's `main`.** Apply directly there, then
   run. For live switch/infra, follow that repo's idempotency + lockout-safety
   rules (run device plays twice; enable VLAN-filtering last; detached
   self-reverting jobs for mgmt changes).
2. **Access path for Claude (on fisi): Netbird, on-demand only.** Bring the
   overlay up for the task, `netbird down` immediately after. Prefer the
   VPS-bastion path when it suffices (no tunnel on fisi at all). **Isolation is
   a hard requirement** — nothing from the makerspace should be able to reach
   fisi/the homelab. See [access.md](access.md) §C.
3. **Reference, don't duplicate.** When you need a fact, link to the source-repo
   file. If you cache a value here, note it can drift.
4. **Log real work** in [incidents/](incidents/) — symptom, root cause, the
   source-repo commit, verification.
5. **Never commit secrets.** Vault keys live under `~/.ansible/vault-keys/`.

## Start-of-session checklist

1. [access.md](access.md) — pick a reach path for where you are.
2. [network-map.md](network-map.md) — confirm host/subnet (note the open
   question about makerspace addressing).
3. [runbooks/](runbooks/) — find or write the runbook.
4. Verify with evidence before claiming a fix works.