docs: say a Cloud environment is protected before asking for a request

docs/getting-started/deploy-project.md

@@ -59,6 +59,31 @@ For a preview deployment per branch:
 npx veryfront@latest push --branch feature-x
 ```
 
+## Environment access
+
+Veryfront Cloud creates `preview`, `staging`, and `production` as protected by
+default, so check the preview URL in a browser signed in to Veryfront as a
+member of the project.
+
+A protected environment serves only that signed-in browser. Every other request
+gets a `302` to `https://veryfront.com/sign-in`, on every path including API
+routes:
+
+```bash
+curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
+  https://<project>.production.veryfront.com/api/health
+302 https://veryfront.com/sign-in?from=https%3A%2F%2F...%2Fapi%2Fhealth
+```
+
+`VERYFRONT_API_TOKEN` does not open a protected environment. It authenticates
+the CLI against the Cloud API, not deployment traffic, so `curl`, a CI smoke
+test, or an uptime monitor sees the sign-in redirect either way.
+
+To serve an environment to everyone, open **Environments** in Veryfront Studio,
+select the environment, turn on **Public Environment**, and confirm
+**Make Public**. Keep protection on for environments that serve internal or
+unreleased work.
+
 ## Deploy to Veryfront Cloud
 
 After checking the preview, deploy the exact pushed source digest:
@@ -94,15 +119,22 @@ container example.
 
 ## Verify it worked
 
-Deploy prints the environment URL. Request that URL and confirm the deployed
-page responds:
+Deploy prints the environment URL. Request that URL and print the status line,
+so a sign-in redirect is visible instead of passing silently:
 
 ```bash
-curl -sSf <environment-url>
+curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' <environment-url>
 ```
 
-Then request an API route the project serves. For the agent route from
-[Create API](./create-api.md):
+A public environment answers `200`. A protected environment answers `302` to
+`https://veryfront.com/sign-in`; open the URL in a signed-in browser, or make
+the environment public, as described in
+[Environment access](#environment-access). Do not check with a bare
+`curl -sSf <environment-url>`: `curl` does not treat a `302` as a failure, so
+that command exits `0` with an empty body whether or not the deployment works.
+
+Once the environment is public, request an API route the project serves. For
+the agent route from [Create API](./create-api.md):
 
 ```bash
 curl -sSf -N -X POST <environment-url>/api/ag-ui \

tests/docs/guide-content.test.ts

@@ -189,6 +189,30 @@ describe("guide content contracts", () => {
     );
   });
 
+  it("tells the reader a Cloud environment is protected before asking for a request", async () => {
+    // Veryfront Cloud environments are protected by default: an anonymous
+    // request to the environment URL gets a 302 to
+    // https://veryfront.com/sign-in on every path, API routes included, and
+    // VERYFRONT_API_TOKEN does not change that. Verified against published
+    // 0.1.1229:
+    //   curl -s -o /dev/null -w '%{http_code} %{redirect_url}' \
+    //     https://support-agent.production.veryfront.com/api/health
+    //   -> 302 https://veryfront.com/sign-in?from=...
+    // A verification step written as a bare `curl -sSf <environment-url>`
+    // therefore exits 0 with an empty body whether or not the deployment
+    // works, so the page has to name the redirect and print the status code.
+    const doc = await Deno.readTextFile(
+      "docs/getting-started/deploy-project.md",
+    );
+    const prose = doc.replace(/\s+/g, " ");
+
+    assertStringIncludes(prose, "protected by default");
+    assertStringIncludes(prose, "https://veryfront.com/sign-in");
+    assertStringIncludes(prose, "Public Environment");
+    assertStringIncludes(doc, "-w '%{http_code} %{redirect_url}\\n'");
+    assertEquals(doc.includes("```bash\ncurl -sSf <environment-url>\n```"), false);
+  });
+
   it("uses serve for local production builds", async () => {
     const docs = [
       "docs/getting-started/deploy-project.md",