diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index 79af9ef36a0..755e5601103 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -199,7 +199,15 @@ After the fixed server is live, perform another ordinary hot restart. Require `adoptedRunIds` or `finalizedWhileDownRunIds`; an ACP-backed original should be finalized and have a queued retry rather than be adopted. -Tailscale/private-auth dev mode: +First-time private-auth dev mode: + +> If the target host already has Paperclip and Tailscale running, reuse the +> existing managed service and advertised URL. Issue work and package-preview +> deployment must not repeat onboarding, change Tailscale Serve, request a +> Tailscale operator grant, or issue a new certificate unless the task +> explicitly authorizes a network-topology change. Check the current runtime +> and listener first; the bind commands below are setup commands for a fresh +> local instance, not prerequisites for every preview. ```sh pnpm dev --bind lan diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.md index 950b572e034..cf0559666f7 100644 --- a/docs/deploy/local-development.md +++ b/docs/deploy/local-development.md @@ -42,6 +42,12 @@ This does: Default `pnpm dev` stays in `local_trusted` with loopback-only binding. +The commands in this section configure a fresh local instance. When a managed +Paperclip host already has Tailscale and its app service running, first reuse +the existing service and advertised URL. A feature task or package preview +must not reconfigure Tailscale Serve, request an operator grant, or create a +certificate unless that network change is an explicit task requirement. + To open Paperclip to a private network with login enabled: ```sh diff --git a/docs/deploy/tailscale-private-access.md b/docs/deploy/tailscale-private-access.md index bb40fa305a3..d0f8842abe7 100644 --- a/docs/deploy/tailscale-private-access.md +++ b/docs/deploy/tailscale-private-access.md @@ -3,7 +3,15 @@ title: Tailscale Private Access summary: Run Paperclip with Tailscale-friendly bind presets and connect from other devices --- -Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only `localhost`. +Use this for first-time operator setup when you want to access Paperclip over +Tailscale (or a private LAN/VPN) instead of only `localhost`. + +> **Existing managed host:** if Tailscale and Paperclip are already running, +> reuse the current service and advertised URL. Do not run these setup steps, +> modify Tailscale Serve, request an operator grant, or issue a certificate as +> part of ordinary feature, QA, or package-preview work. Those are separate +> operator-owned topology changes and must be explicitly requested by the +> task. ## 1. Start Paperclip in private authenticated mode @@ -25,6 +33,7 @@ pnpm dev --bind lan Legacy aliases still map to `authenticated/private + bind=lan`: +```sh pnpm dev --authenticated-private pnpm dev --tailscale-auth ```