docs: improve Tailscale feature docs

docs/commands/config.md

@@ -29,6 +29,13 @@ User config lives under the OS user config directory. Repo-local `crabbox.yaml`
 
 ```yaml
 profile: project-check
+tailscale:
+  enabled: true
+  network: auto
+  tags:
+    - tag:crabbox
+  hostnameTemplate: crabbox-{slug}
+  authKeyEnv: CRABBOX_TAILSCALE_AUTH_KEY
 capacity:
   market: spot
   strategy: most-available
@@ -54,3 +61,14 @@ env:
     - NODE_OPTIONS
     - PROJECT_*
 ```
+
+`tailscale.enabled` requests tailnet join for new managed Linux leases.
+`tailscale.network` selects the SSH target resolution path:
+
+- `auto`: prefer Tailscale when lease metadata exists and SSH is reachable;
+- `tailscale`: require the tailnet path;
+- `public`: force the provider/public host.
+
+Brokered `--tailscale` leases use Worker-minted one-off auth keys. Direct
+provider leases read a local one-off key from `tailscale.authKeyEnv`; do not
+store that key in repo config.

docs/features/tailscale.md

@@ -156,3 +156,4 @@ Related docs:
 - [Runner bootstrap](runner-bootstrap.md)
 - [Interactive desktop and VNC](interactive-desktop-vnc.md)
 - [Security](../security.md)
+- [Troubleshooting](../troubleshooting.md#tailscale-path-fails)

docs/infrastructure.md

@@ -100,6 +100,14 @@ CRABBOX_TAILSCALE_TAILNET=-              # or explicit tailnet/org
 CRABBOX_TAILSCALE_TAGS=tag:crabbox       # allowlist/default tags
 ```
 
+Operator checklist:
+
+1. Create a Tailscale OAuth client with the `auth_keys` scope.
+2. Limit the OAuth client to tags Crabbox may assign, usually `tag:crabbox`.
+3. Store the client ID and secret as Worker secrets.
+4. Set `CRABBOX_TAILSCALE_TAGS` to the same allowed tag list.
+5. Verify with `crabbox warmup --tailscale --network tailscale`.
+
 The Worker mints one-off ephemeral pre-approved auth keys per lease and injects
 the key only into cloud-init. Lease records and provider labels store only
 non-secret Tailscale metadata such as hostname, FQDN, 100.x address, state, and

docs/troubleshooting.md

@@ -4,6 +4,7 @@ Read when:
 
 - a lease fails to create;
 - SSH never becomes ready;
+- tailnet reachability behaves unexpectedly;
 - sync behaves unexpectedly;
 - Actions hydration times out;
 - docs deployment fails.
@@ -163,6 +164,45 @@ Fixes:
 - inspect provider console output for cloud-init failures;
 - retry the lease if bootstrap failed before creating the ready marker.
 
+## Tailscale Path Fails
+
+Symptoms:
+
+- `--tailscale` lease creation fails with `tailscale_unavailable`,
+  `tailscale_disabled`, or `invalid_tailscale_tags`;
+- `--network tailscale` says the lease has no tailnet address;
+- `--network tailscale` says the tailnet host is unreachable over SSH;
+- `--network auto` falls back to `public`.
+
+Checks:
+
+```sh
+bin/crabbox config show
+bin/crabbox inspect --id blue-lobster
+bin/crabbox inspect --id blue-lobster --json
+bin/crabbox ssh --id blue-lobster --network tailscale
+tailscale status
+tailscale ping <tailscale-fqdn-or-100.x-address>
+```
+
+Fixes:
+
+- for brokered leases, configure Worker secrets
+  `CRABBOX_TAILSCALE_CLIENT_ID` and `CRABBOX_TAILSCALE_CLIENT_SECRET`;
+- keep `CRABBOX_TAILSCALE_ENABLED` unset or `1`; set it to `0` only to disable
+  brokered Tailscale intentionally;
+- ensure requested tags are in the Worker `CRABBOX_TAILSCALE_TAGS` allowlist;
+- ensure the local client is joined to the same tailnet and ACLs allow SSH to
+  the tagged node;
+- use `--network public` to prove the provider SSH path independently;
+- use `--network auto` when fallback to public is acceptable;
+- use `--network tailscale` when a missing or unreachable tailnet path should
+  fail the command.
+
+Crabbox still uses OpenSSH and per-lease SSH keys over the selected host.
+Tailscale SSH, Serve, Funnel, and direct VNC binding are not part of managed
+lease support.
+
 ## Sync Looks Wrong
 
 Symptoms: