feat: search multiple NetBox instances with isolated host identities

README.md

@@ -103,7 +103,7 @@ Re-run it at any time to change settings without editing the file manually:
 netssh configure
 ```
 
-The wizard walks through NetBox connection, SSH defaults, resolver strategies, cache TTL, and an optional command alias,
+The wizard lets you add, edit, and remove named NetBox instances, then walks through SSH defaults, resolver strategies, cache TTL, and an optional command alias,
 then saves to `~/.config/netssh.yaml`.
 
 ### Manual config
@@ -142,7 +142,44 @@ shortcuts:
   strip_hyphens: false # if true, fsn1-web01 → fsn1web01 (cache-only resolution)
 ```
 
-Any value can be overridden with environment variables (`NETSSH_NETBOX_URL`, `NETSSH_NETBOX_TOKEN`, etc.).
+Single-instance and shared settings can be overridden with environment variables (`NETSSH_NETBOX_URL`, `NETSSH_NETBOX_TOKEN`, etc.).
+
+### Multiple NetBox instances
+
+Use `netssh configure` to manage instances, or replace the `netbox:` section with a `netboxes:` list:
+
+```yaml
+netboxes:
+  - name: office
+    url: https://netbox.office.example
+    token: nbt_office-token
+  - name: lab
+    url: https://netbox.lab.example
+    token: nbt_lab-token
+```
+
+Names must be unique and contain only letters, digits, underscores, or hyphens. Names are normalized to lowercase. Each instance has its own token and optional `token_version`; SSH, resolver, and shortcut settings apply to all instances. Configure either `netbox:` or `netboxes:`. Existing single-instance files continue to work; the wizard migrates them to a named `default` instance when saved.
+
+The legacy `NETSSH_NETBOX_URL` and `NETSSH_NETBOX_TOKEN` variables apply to single-instance configuration. They are ignored when the file contains only a named `netboxes:` list.
+
+Each NetBox keeps its own inventory of devices and virtual machines; either inventory may be empty. The interactive search queries all instances in parallel, including when one already has cached matches. Results show the instance as part of the hostname, for example `office/web01`. If an instance is unavailable, available results and cached hosts remain visible with a warning.
+
+```sh
+netssh                              # search all instances interactively
+netssh office/web01                 # choose an instance explicitly
+netssh admin@lab/web01 uptime
+netssh web01                        # accepted only if the live lookup is unambiguous
+netssh cache refresh                 # refresh all instances
+netssh cache refresh --instance lab  # refresh just one instance
+netssh notes set office/web01 "Office maintenance"
+netssh notes show lab/web01 --netbox --kind device
+```
+
+For direct connections without an instance prefix, every instance must be reachable to verify uniqueness. A qualified target queries only its own instance and can use a fresh cached IP while other instances are offline. Qualified shortcuts such as `office/web01` also support configured domain suffixes and hyphen folding.
+
+Cache entries and generated aliases retain the instance name (`office_web01` and `lab_web01`). Named-instance caches live in a configuration-specific subdirectory beneath the configured cache path, so changing an endpoint cannot reuse another server's cached IPs. Run `netssh cache refresh` after adding or changing instances. A failed full refresh leaves the cache and its refresh timestamp unchanged; a per-instance refresh preserves the other instances and does not mark the whole cache as refreshed.
+
+Local notes remain keyed by the NetBox URL, host kind, and canonical hostname. Migrating a single instance or renaming it preserves its notes. Use `instance/hostname` and `--kind` for uncached local notes; these operations work offline. NetBox comments and interface/IP lookups always use the selected instance's credentials.
 
 ### Short command alias