add new newt config options

manage/sites/configure-site.mdx

@@ -33,6 +33,30 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
   **Example**: `https://pangolin.example.com`
 </ResponseField>
 
+<ResponseField name="name" type="string">
+  Site name to use when provisioning with a provisioning key. Supports `{{env.VARIABLE_NAME}}` templating from the process environment. If omitted, Pangolin assigns a random animal-based name (changeable in the dashboard).
+
+  **Example**: `my-edge-site` or `'{{env.SERIAL_NUMBER}}-edge'`
+</ResponseField>
+
+<ResponseField name="provisioning-blueprint-file" type="string">
+  Path to a blueprint YAML file applied **once** at provisioning (imperative bootstrap). Unlike `--blueprint-file`, Newt does not keep reapplying it, so resources you edit in the dashboard are not overwritten on later runs. See [Site provisioning keys](/manage/sites/site-provisioning).
+
+  **Example**: `/path/to/bootstrap.yaml`
+</ResponseField>
+
+<ResponseField name="provisioning-key" type="string">
+  Provisioning key from Pangolin (alternative to a `provisioningKey` field inside the config file). Newt exchanges it once for site credentials, then persists `id` and `secret` to the config file and ignores the key on later runs. See [Site provisioning keys](/manage/sites/site-provisioning).
+
+  **Example**: `spk_...`
+</ResponseField>
+
+<ResponseField name="config-file" type="string">
+  Path to a JSON file where Newt reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and other options). When you use [site provisioning](/manage/sites/site-provisioning), Newt writes `id` and `secret` into this file after a successful exchange.
+
+  **Example**: `/var/newt.json`
+</ResponseField>
+
 <ResponseField name="port" type="integer">
   Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports.
 
@@ -96,7 +120,7 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
 </ResponseField>
 
 <ResponseField name="blueprint-file" type="string">
-  Path to blueprint file to define Pangolin resources and configurations.
+  Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: Newt keeps applying the file, and it remains the source of truth (dashboard changes can be overwritten on the next apply). For a one-time bootstrap blueprint with provisioning keys, use `--provisioning-blueprint-file` instead.
 
   **Example**: `/path/to/blueprint.yaml`
 </ResponseField>
@@ -205,6 +229,24 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
   Newt secret for authentication (equivalent to `--secret`)
 </ResponseField>
 
+<ResponseField name="NEWT_NAME" type="string">
+  Site name when provisioning with a provisioning key (equivalent to `--name`). Supports `{{env.VARIABLE_NAME}}` templating from the environment.
+</ResponseField>
+
+<ResponseField name="NEWT_PROVISIONING_KEY" type="string">
+  Provisioning key string (equivalent to `--provisioning-key`). See [Site provisioning keys](/manage/sites/site-provisioning).
+</ResponseField>
+
+<ResponseField name="PROVISIONING_BLUEPRINT_FILE" type="string">
+  Path to a bootstrap-only blueprint file (equivalent to `--provisioning-blueprint-file`). See [Site provisioning keys](/manage/sites/site-provisioning).
+</ResponseField>
+
+<ResponseField name="CONFIG_FILE" type="string">
+  Path to the JSON config file where Newt loads and persists settings (equivalent to `--config-file`). Use this instead of the default location under the home folder when you want a fixed path (typical for containers and provisioning).
+
+  **Example**: `/var/newt.json`
+</ResponseField>
+
 <ResponseField name="PORT" type="integer">
     Port for the peers to connect to Newt on (equivalent to `--port`)
 </ResponseField>
@@ -221,10 +263,6 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
   **Default**: `9.9.9.9`
 </ResponseField>
 
-<ResponseField name="CONFIG_FILE" type="string">
-  Load the config JSON from this file instead of in the home folder.
-</ResponseField>
-
 <ResponseField name="BLUEPRINT_FILE" type="string">
   Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
 </ResponseField>
@@ -335,7 +373,7 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
 
 ## Loading secrets from files
 
-You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
+You can use `--config-file` or the `CONFIG_FILE` environment variable to set the path of the config file where Newt stores credentials and other settings between runs.
 
 ```
 $ cat ~/.config/newt-client/config.json

manage/sites/site-provisioning.mdx

@@ -24,14 +24,15 @@ With provisioning keys, you create one long-lived token in Pangolin, embed it in
 
 ## How provisioning works
 
-Put the provisioning key in a JSON config file with a `provisioningKey` field (the value is the key string from Pangolin, often shown with an `spk` prefix). Point Newt at that file with `--config-file`, for example:
+You can supply the provisioning key in either of two ways:
+
+**1. Config file**  
+Put the key in a JSON config file in a `provisioningKey` field (the value is the key string from Pangolin, often shown with an `spk` prefix) and point Newt at that file:
 
 ```bash
 newt --config-file /var/newt.json
 ```
 
-A minimal file might only set `endpoint` and `provisioningKey` until the exchange completes; afterward the same file holds `id` and `secret` instead of the key. Other Newt options are documented on [Configure Sites](/manage/sites/configure-site).
-
 ```json
 {
   "endpoint": "https://app.pangolin.net",
@@ -39,9 +40,16 @@ A minimal file might only set `endpoint` and `provisioningKey` until the exchang
 }
 ```
 
-When Newt contacts Pangolin and exchanges the provisioning key for a device-specific ID and secret, it updates the same config file: the provisioning key entry is removed and replaced with the new credentials. After a successful provision, the provisioning key is no longer on the host; only the normal site ID and secret remain for future connections.
+**2. Command line**  
+Pass the key with **`--provisioning-key`** instead of storing it in the file. You still use **`--config-file`** so Newt has a path to write and persist settings; see [Configure Sites](/manage/sites/configure-site) for the rest):
 
-From there Newt authenticates over the websocket, optionally applies declarative YAML if you configured a blueprint, then brings the tunnel online. The high-level sequence is summarized below.
+```bash
+newt --config-file /var/newt.json --endpoint https://app.pangolin.net --provisioning-key 'spk_...'
+```
+
+**After the site is provisioned**, Newt writes the new `id` and `secret` into that config file. On later runs, Newt uses those credentials and ignores the provisioning key (CLI flag or file field), because valid ID and secret are already present. If you used `provisioningKey` in JSON, that entry is removed when the file is updated, so the long-lived token is not left on disk.
+
+From there Newt authenticates over the websocket, optionally applies a blueprint if you passed one, then brings the tunnel online. The high-level sequence is summarized below.
 
 <Frame>
   <img src="/images/site-provisioning-flow.png" alt="Flow: provision with pre-shared key, exchange for ID and secret, apply YAML, pending approval, admin approves" centered />
@@ -51,7 +59,22 @@ From there Newt authenticates over the websocket, optionally applies declarative
 [Pangolin Blueprints](/manage/blueprints) are not required when using provisioning keys. You can provision with the key only and manage resources in the dashboard afterward. Blueprints are optional but convenient when you want resources and settings created automatically from YAML as soon as the site connects.
 </Note>
 
-If you do use blueprints together with provisioning keys, you get a repeatable pattern for large fleets: one key (with appropriate limits), a blueprint file or embedded config, and optional environment-specific values so each host gets distinct resource names or domains without maintaining separate YAML per device.
+### `--provisioning-blueprint-file` vs `--blueprint-file`
+
+When you run Newt with a provisioning key, you can attach a blueprint YAML file in two different ways:
+
+| Flag | Behavior |
+|------|------------|
+| **`--blueprint-file`** | **Declarative.** The blueprint is the ongoing source of truth. Newt keeps applying it, and changes you make in the dashboard can be overwritten the next time the blueprint is applied. |
+| **`--provisioning-blueprint-file`** | **Imperative (bootstrap only).** The file is applied once, at provisioning time. After that, Newt does not keep reapplying it. You can edit resources in the dashboard and those edits will not be overridden by that YAML on later runs. |
+
+Use **`--provisioning-blueprint-file`** when you want automation to create an initial set of resources (for example from a fleet template) but you intend to manage or tune them in the UI afterward. Use `--blueprint-file` when you want the file to remain authoritative, the same as on a normal site without provisioning keys.
+
+```bash
+newt --config-file /var/newt.json --provisioning-blueprint-file /path/to/bootstrap.yaml
+```
+
+If you do use blueprints together with provisioning keys, you get a repeatable pattern for large fleets: one key (with appropriate limits), a blueprint file, and optional environment-specific values so each host gets distinct resource names or domains without maintaining separate YAML per device. Pick the flag above based on whether that YAML should keep governing the site or only run at first connect.
 
 ### Blueprint example and environment templating
 
@@ -92,7 +115,13 @@ Use whatever variables match your deployment (for example asset tags or cloud in
 
 ### Optional site name (`--name`)
 
-You can pass `--name` to Newt when provisioning so the new site gets a specific name. If you omit it, Pangolin assigns a random animal-based name, which you can change later in the dashboard. Predictable names via `--name` help when your automation or blueprint references the site by a stable label.
+You can pass `--name` to Newt when provisioning so the new site gets a specific name. The value supports the same `{{env.VARIABLE_NAME}}` templating as blueprints: placeholders are expanded from the environment where Newt runs before the site is created (for example per-device serials or hostnames).
+
+```bash
+newt --config-file /var/newt.json --name '{{env.SERIAL_NUMBER}}-edge'
+```
+
+If you omit `--name`, Pangolin assigns a random animal-based name, which you can change later in the dashboard. Explicit or templated names help when your automation or blueprint references the site by a stable label.
 
 ## Limits, expiry, and security model