docs: move getting-started out of guides

docs/site/getting-started/update-machines.md

@@ -0,0 +1,129 @@
+# Update Machines
+
+The Clan command line interface enables you to update machines remotely over SSH.
+In this guide we will teach you how to set a `targetHost` in Nix,
+and how to define a remote builder for your machine closures.
+
+
+## Setting `targetHost`
+
+Set the machine’s `targetHost` to the reachable IP address of the new machine.
+This eliminates the need to specify `--target-host` in CLI commands.
+
+```{.nix title="clan.nix" hl_lines="9"}
+{
+# Ensure this is unique among all clans you want to use.
+meta.name = "my-clan";
+
+inventory.machines = {
+    # Define machines here.
+    # The machine name will be used as the hostname.
+    jon = {
+        deploy.targetHost = "root@192.168.192.4"; # (1)
+    };
+};
+# [...]
+}
+```
+
+The use of `root@` in the target address implies SSH access as the `root` user.
+Ensure that the root login is secured and only used when necessary.
+
+## Multiple Target Hosts
+
+You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](/guides/networking/networking.md).
+
+## Updating Machine Configurations
+
+Execute the following command to update the specified machine:
+
+```bash
+clan machines update jon
+```
+
+All machines can be updated simultaneously by omitting the machine name:
+
+```bash
+clan machines update
+```
+
+---
+
+## Advanced Usage
+
+The following options are only needed for special cases, such as limited resources, mixed environments, or private flakes.
+
+### Setting `buildHost`
+
+If the machine does not have enough resources to run the NixOS **evaluation** or **build** itself,
+it is also possible to specify a `buildHost` instead.
+During an update, clan will ssh into the `buildHost` and run `nixos-rebuild` from there.
+
+!!! Note
+    The `buildHost` option should be set directly within your machine’s Nix configuration, **not** under `inventory.machines`.
+
+
+```{.nix hl_lines="5" .no-copy}
+clan {
+    # ...
+    machines = {
+        "jon" = {
+            clan.core.networking.buildHost = "root@<host_or_ip>";
+        };
+    };
+};
+```
+
+### Overriding configuration with CLI flags
+
+`buildHost` / `targetHost`, and other network settings can be temporarily overridden for a single command:
+
+For the full list of flags refer to the [Clan CLI](/reference/cli/index.md)
+
+```bash
+# Build on a remote host
+clan machines update jon --build-host root@192.168.1.10
+
+# Build locally (useful for testing or when the target has limited resources)
+clan machines update jon --build-host local
+```
+
+!!! Note
+    Make sure the CPU architecture of the `buildHost` matches that of the `targetHost`
+
+    For example, if deploying to a macOS machine with an ARM64-Darwin architecture, you need a second macOS machine with the same architecture to build it.
+
+
+### Excluding a machine from `clan machine update`
+
+To exclude machines from being updated when running `clan machines update` without any machines specified,
+one can set the `clan.deployment.requireExplicitUpdate` option to true:
+
+```{.nix hl_lines="5" .no-copy}
+clan {
+    # ...
+    machines = {
+        "jon" = {
+            clan.deployment.requireExplicitUpdate = true;
+        };
+    };
+};
+```
+
+This is useful for machines that are not always online or are not part of the regular update cycle.
+
+### Uploading Flake Inputs
+
+When updating remote machines, flake inputs are usually fetched by the build host.
+However, if flake inputs require authentication (e.g., private repositories),
+
+Use the `--upload-inputs` flag to upload all inputs from your local machine:
+
+```bash
+clan machines update jon --upload-inputs
+```
+
+This is particularly useful when:
+- The flake references private Git repositories
+- Authentication credentials are only available on local machine
+- The build host doesn't have access to certain network resources