From 5ef7901a330ff85b51721da84ccd7bc3b0870c06 Mon Sep 17 00:00:00 2001
From: yoma <yingwaizhiying@gmail.com>
Date: Thu, 16 Jul 2026 14:19:08 +0800
Subject: [PATCH] docs: trim Cloudflare agent runbook

---
 docs/agent-deploy-cloudflare.md | 81 +++++++++------------------------
 1 file changed, 22 insertions(+), 59 deletions(-)

diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.md
index f64c4129..900d410c 100644
--- a/docs/agent-deploy-cloudflare.md
+++ b/docs/agent-deploy-cloudflare.md
@@ -1,74 +1,37 @@
 # AI Agent Cloudflare Deployment
 
-Use this runbook when a user asks an AI agent to deploy EdgeEver from a GitHub repository to Cloudflare.
+Use this contract when deploying EdgeEver from a GitHub repository to Cloudflare.
 
-## Rules
+## Constraints
 
-- Use local deployment only for the first installation or emergency recovery. Connect Cloudflare Workers Builds after the first deployment.
+- Use local deployment only for the first installation or emergency recovery. Routine updates must use Cloudflare Workers Builds.
 - Keep account IDs, resource names, API tokens, domains, and passwords in the git-ignored `.env.local`; never hard-code or commit them.
-- Prefer the repository's deployment scripts. Ask the user only for authorization, domain ownership, or other information that cannot be inferred safely.
-- Do not configure a separate GitHub Actions deployment for the Worker.
+- Use the repository deployment scripts. Do not add a separate GitHub Actions deployment for the Worker.
 
-## Runbook
+## First Installation
 
-1. Prepare the repository:
+Run in order:
 
-   ```sh
-   git clone <repo-url>
-   cd edgeever
-   bun install
-   ```
+```sh
+bun run deploy:setup
+bun run deploy:doctor
+bun run deploy
+```
 
-2. Verify Cloudflare access:
+If the user supplied a custom initial password, replace the first command with:
 
-   ```sh
-   bunx wrangler whoami
-   ```
+```sh
+EDGE_EVER_PASSWORD='<first-login-password>' bun run deploy:setup
+```
 
-   If authentication fails and cannot be completed in the browser, ask the user to authorize Cloudflare before continuing.
+Do not deploy until `deploy:doctor` passes. After deployment, verify the Worker URL, `/api/openapi.json`, and login. The default initial login is `admin` / `admin123`.
 
-3. Initialize the deployment. Use the default first login (`admin` / `admin123`):
+## Automatic Updates
 
-   ```sh
-   bun run deploy:setup
-   ```
+After the first deployment, run:
 
-   If the user supplied another password, run this instead:
+```sh
+bun run deploy:builds:setup
+```
 
-   ```sh
-   EDGE_EVER_PASSWORD='<first-login-password>' bun run deploy:setup
-   ```
-
-   Then check and deploy:
-
-   ```sh
-   bun run deploy:doctor
-   bun run deploy
-   ```
-
-   Fix every `deploy:doctor` failure before deploying.
-
-4. Verify the URL reported by Wrangler:
-
-   ```sh
-   curl -I https://<worker-url>/
-   curl https://<worker-url>/api/openapi.json
-   ```
-
-   Open the site and confirm that login succeeds.
-
-5. Enable automatic updates:
-
-   ```sh
-   bun run deploy:builds:setup
-   ```
-
-   Follow [Cloudflare Workers Builds](cloudflare-workers-builds.md) only when the command requests authorization or an API token.
-
-## Stop and Ask the User
-
-Stop only when Cloudflare authorization cannot be completed, a requested custom domain is unavailable, or account permissions, limits, billing, or an unresolvable resource-name conflict prevents deployment.
-
-## Final Response
-
-Report the deployed URL, initial login, Workers Builds status, and any remaining user action. Confirm that future pushes to `main` automatically deploy the instance.
+Follow [Cloudflare Workers Builds](cloudflare-workers-builds.md) only when the command requests authorization or an API token. Deployment is complete when the verification build succeeds and future pushes to `main` automatically deploy the instance.