@kurtbruns/kestrel 1.12.0 → 1.14.0

package/docs/README.md

@@ -4,7 +4,7 @@ These pages cover deploying and running your own Kestrel, from an empty reposito
 
 ## Get started
 
-Follow these steps, from an empty repository to a live newsletter. Each one ends with a check, so you know it worked before you move on.
+These are the steps to deploy a Kestrel instance and get it ready to send. Each one ends with a check, so you know it worked before you move on.
 
 1. [Deploy the app](get-started/02-deploy.md)
 1. [Lock the dashboard with Access](get-started/03-access.md)
@@ -16,7 +16,8 @@ Follow these steps, from an empty repository to a live newsletter. Each one ends
 
 Each one stands on its own. Pick the ones you need.
 
-- [Connect Claude to the API](guides/01-connect-claude.md)
+- [Allow Claude to connect](guides/01-allow-claude.md)
+- [Automate with a service token](guides/02-automate.md)
 - [Notifications through Cloudflare's email](guides/03-notifications.md)
 - [Rate-limit the subscribe form](guides/05-rate-limit.md)
 - [As your list grows](guides/09-as-your-list-grows.md)

package/docs/get-started/02-deploy.md

@@ -63,7 +63,7 @@ Your instance's repository holds its configuration, its database migrations, and
     npm run dev
     ```
 
-    Open http://localhost:8787/dashboard/, and run `npm run seed` in a second terminal to load a demo publication. Email goes to a stand-in, so nothing reaches a real inbox. Stop the server with <kbd>Ctrl</kbd>+<kbd>C</kbd> when you're done.
+    Open http://localhost:8787/dashboard/, and run `npm run seed` in a second terminal to load a demo publication. Email goes to a stand-in, so nothing reaches a real inbox. Press Ctrl+C to stop the server when you're done.
 
 ## 2. Sign in to Cloudflare
 
@@ -85,7 +85,7 @@ Every command from here on acts on your Cloudflare account through the Wrangler
 
 ## 3. Create the database and the image bucket
 
-Each command creates the resource and writes its id or name into the `production` block of `wrangler.jsonc`, under the binding the app already uses, so there's nothing to copy.
+Each command creates the resource and writes it into the `production` block of `wrangler.jsonc`, under the binding the app already uses. Name `--env production` on each one, or Wrangler writes to the top level, which is local development.
 
 1. Create the database:
 
@@ -93,29 +93,28 @@ Each command creates the resource and writes its id or name into the `production
     npx wrangler d1 create kestrel-production --env production --binding DB --update-config
     ```
 
-    It prints the new database's settings, then a snippet it says to add to your configuration. Wrangler has already added it: it fills in the `database_id` of the production `DB` binding with the database's real id, in place of `REPLACE_WITH_PRODUCTION_D1_ID`, so there's nothing to paste.
-
 1. Create the bucket for images:
 
     ```bash
     npx wrangler r2 bucket create kestrel-media-production --env production --binding MEDIA --update-config
     ```
 
-    It prints a snippet to add to your configuration too. There's nothing to paste here either: the production `MEDIA` binding already names this bucket, so it stays as it is.
-
-Wrangler rewrites the whole of `wrangler.jsonc` in its own layout when it saves: tabs, and one value per line. Your comments and settings stay; only the spacing changes.
-
-Name `--env production` on every Wrangler command that creates or binds a resource. Without it, Wrangler writes to the top level, which is local development.
+Each prints a snippet to add to your configuration. There's nothing to paste: `--update-config` has filled in the database's id, and the `MEDIA` binding already names the bucket. Wrangler also rewrites `wrangler.jsonc` in its own layout, with tabs and one value per line, and your settings stay.
 
 ## 4. Configure production
 
 `wrangler.jsonc` holds two sets of settings. The top level is for local development, so leave it alone. The `production` block under `env` is yours to fill in.
 
-1. Open `wrangler.jsonc` and change the values marked here in the `production` block. It's shown compactly here; in your file, after section 3, each value is on its own line:
+1. Open `wrangler.jsonc` and change the values marked here in the `production` block. Only the settings you change are shown; leave the others as they are:
 
     ```jsonc
     "production": {
-      "routes": [{ "pattern": "newsletter.example.com", "custom_domain": true }], // ← your app's hostname
+      "routes": [
+        {
+          "pattern": "newsletter.example.com", // ← your app's hostname
+          "custom_domain": true
+        }
+      ],
       "d1_databases": [
         {
           "binding": "DB",
@@ -136,24 +135,22 @@ Name `--env production` on every Wrangler command that creates or binds a resour
 
     What each one does:
 
-    - **`routes`** puts the app on your hostname when you deploy. Cloudflare creates the DNS record and the certificate. Your domain must be in the same Cloudflare account, and the hostname can't already have a CNAME record; delete one if it does. The block also turns off the `workers.dev` addresses, so the app answers only on your hostname.
-    - **`PROVIDER` stays empty.** [Connect Amazon SES](04-ses.md) sets it. Until then the app runs without an email provider: posts can be written and previewed, but scheduling, test emails, and signups are refused. Never set it to `fake`, the top level's value, even when a wrangler warning suggests copying it: `fake` delivers nothing, and the app refuses it on your hostname.
-    - **`ARCHIVE_BASE_PATH`** is permanent once the first post goes out. Every post sent carries its `/archive/…` link, and changing the prefix later breaks the links already mailed. Keep `/archive` unless you have a reason not to.
-    - **`FROM_ADDRESS`** is the address every email comes from. Keep it on your sending hostname, and set `SENDING_DOMAIN` to the part after the `@`.
+    - `routes` puts the app on your hostname when you deploy. Cloudflare creates the DNS record and the certificate. Your domain must be in the same Cloudflare account, and the hostname can't already have a CNAME record; delete one if it does. The block also turns off the `workers.dev` addresses, so the app answers only on your hostname.
+    - `PROVIDER` stays empty until [Connect Amazon SES](04-ses.md) sets it. Until then the app runs without an email provider: posts can be written and previewed, but scheduling, test emails, and signups are refused. Never set it to `fake`, the top level's value, even when a wrangler warning suggests copying it: `fake` delivers nothing, and the app refuses it on your hostname.
+    - `ARCHIVE_BASE_PATH` is permanent once the first post goes out. Every post sent carries its `/archive/…` link, and changing the prefix later breaks the links already mailed. Keep `/archive` unless you have a reason not to.
+    - `FROM_ADDRESS` is the address every email comes from. Keep it on your sending hostname, and set `SENDING_DOMAIN` to the part after the `@`.
 
-    Change every `example.com` value, the route included, even before you connect a provider. The app checks its settings but can't see the route: it refuses to run while `APP_ORIGIN`, `SENDING_DOMAIN`, or `FROM_ADDRESS`, or `ARCHIVE_ORIGIN` or `MEDIA_PUBLIC_BASE` if you set them, is still on `example.com`, since its links and the address your email comes from would name a domain that isn't yours.
+    Change every `example.com` value, the route included. The app refuses to run while any of its settings still names `example.com`.
 
     Every other setting has a working default. [Configuration](../reference/01-configuration.md) lists them all, and what the app refuses.
 
-1. Check the file. This regenerates the binding types, and fails if the configuration doesn't parse:
+1. Check the file. It fails if the configuration doesn't parse:
 
     ```bash
     npm run typecheck
     ```
 
-    Wrangler prints the binding types it generated and ends with a reminder to run it again whenever you change `wrangler.jsonc`. The type check that follows prints nothing when it passes.
-
-1. Commit your settings and push them to your repository. An upgrade changes only the release your instance runs, so your settings stay as they are:
+1. Commit your settings and push them to your repository:
 
     ```bash
     git commit -am "Configure production"
@@ -202,7 +199,7 @@ This deploys the release your instance runs, with your settings. The output ends
 
     In a browser, `https://newsletter.example.com/dashboard/` says the editor is locked until you set up Access. That's expected.
 
-1. In a browser, `https://newsletter.example.com/` shows the newsletter's public landing page. Its subscribe page, `/subscribe`, says signups aren't open yet, until Connect Amazon SES.
+1. In a browser, `https://newsletter.example.com/` shows the newsletter's public home page. Its subscribe page, `/subscribe`, says signups aren't open yet, until Connect Amazon SES.
 
 If the public pages instead say the newsletter is temporarily unavailable, and `/health` answers `500` with a body like `{"error":"invalid_config","variable":"APP_ORIGIN",…}`, the setting it names is missing, malformed, or still on `example.com`. Fix it in `wrangler.jsonc`, commit, and deploy again.
 

package/docs/get-started/03-access.md

@@ -33,9 +33,9 @@ The editor lives under `/dashboard`, and the API under `/api`. One application c
     | Path | What it covers |
     | --- | --- |
     | `dashboard` | the editor |
-    | `api` | everything the editor and Claude read and change: posts, sends, subscribers, settings, and the in-app docs |
+    | `api` | everything the editor and Claude read and change: posts, sends, subscribers, settings, the in-app docs, and the MCP server Claude Desktop and claude.ai connect to (`/api/mcp`) |
 
-    Each path covers everything under it. Leave every other path out. The landing page, the archive, subscribing, unsubscribing, images, and your email provider's webhooks must stay public.
+    Each path covers everything under it. Leave every other path out. The home page, the archive, subscribing, unsubscribing, images, and your email provider's webhooks must stay public.
 
 1. **(Optional)** Choose how long a sign-in lasts. The application's session duration defaults to 24 hours, so everyone signs in again each day. You can set anything from immediately to one month, as Cloudflare's [session management](https://developers.cloudflare.com/cloudflare-one/access-controls/access-settings/session-management/) describes. A longer session suits a publisher on their own computer, and a shorter one is safer on a shared one.
 
@@ -49,10 +49,12 @@ Every Access application denies everyone until a policy allows them.
     - **Action:** Allow
     - **Include:** the **Emails** selector, with your email address
 
-1. Keep the login method a new Zero Trust organization starts with: you sign in with your Cloudflare account. To sign in another way, such as a one-time code by email, add it under **Zero Trust → Integrations → Identity providers** first.
-
 1. Select **Create**.
 
+Cloudflare's own login is on by default, and admits members of your Cloudflare account, so the email in your `Publishers` policy should be one. To let someone sign in another way, such as a one-time code by email, add it under **Zero Trust → Integrations → Identity providers**.
+
+The app accepts only two kinds of policy on this application. One is an Allow policy on people's emails, like this one. The other is a Service Auth policy on a service token, from [Automate with a service token](../guides/02-automate.md). A login through any other kind, such as a certificate, a device check, or an identity provider that gives no email, is refused with a `401`, and the editor says so.
+
 ## 4. Give the app its two values
 
 The app verifies each login against your team domain, and checks that it was issued for this application.
@@ -61,7 +63,7 @@ The app verifies each login against your team domain, and checks that it was iss
 
 1. Find the application's audience tag. Under **Access controls → Applications**, select **Configure** on your application. On the **Additional settings** tab, copy the **Application Audience (AUD) Tag**.
 
-1. Store the team domain as a secret. The command prompts you for the value. Enter the hostname alone, without `https://`. If you paste it with `https://` or a trailing slash, the app drops them. Anything else that isn't a hostname is refused, naming `ACCESS_TEAM_DOMAIN`:
+1. Store the team domain as a secret. The command prompts you for the value. Enter the hostname alone, without `https://`:
 
     ```bash
     npx wrangler secret put ACCESS_TEAM_DOMAIN --env production
@@ -73,7 +75,7 @@ The app verifies each login against your team domain, and checks that it was iss
     npx wrangler secret put ACCESS_AUD --env production
     ```
 
-    A secret takes effect as soon as you store it, with no redeploy. The app needs both values. While only one is stored, it refuses its configuration and names the missing one: the editor says so, `/health` answers `500` with `"variable":"ACCESS_AUD"`, and the public pages say the newsletter is temporarily unavailable. Storing the second clears it.
+    A secret takes effect as soon as you store it, with no redeploy.
 
 1. **(Optional, recommended)** Limit the editor to named people. The Access policy decides who can sign in. This list keeps that true if the policy is widened later, for another app or by mistake. Enter a comma-separated list of email addresses at the prompt:
 
@@ -92,7 +94,7 @@ The app verifies each login against your team domain, and checks that it was iss
 1. In the same window, open `https://newsletter.example.com/api/whoami`. It shows you as a signed-in person, verified through Access:
 
     ```
-    {"principal":{"kind":"human","email":"you@example.com"},"auth":{"mode":"access"}}
+    {"principal":{"kind":"human","email":"you@example.com","client":null},"auth":{"mode":"access"}}
     ```
 
 1. The public pages still need no login:
@@ -105,6 +107,6 @@ The app verifies each login against your team domain, and checks that it was iss
     {"status":"ok","service":"kestrel"}
     ```
 
-If the editor says the configuration needs a fix, store the secret it names. If Cloudflare lets you in but the editor answers `401`, check the two secrets for a typo, or `ACCESS_ALLOWED_EMAILS` may leave out your address.
+If the editor says the configuration needs a fix, store the secret it names. The app needs both values, so while only one is stored, `/health` answers `500` naming the other, and the public pages say the newsletter is temporarily unavailable. If Cloudflare lets you in but the editor answers `401`, check the two secrets for a typo, or `ACCESS_ALLOWED_EMAILS` may leave out your address. If the editor says Access let you in but didn't say who you are, your login carried no email: sign out, and sign in through the `Publishers` policy.
 
 Next, [connect Amazon SES](04-ses.md).

package/docs/get-started/04-ses.md

@@ -1,6 +1,6 @@
 # Connect Amazon SES
 
-Kestrel sends the newsletter's posts through Amazon SES, Amazon's email service. SES only delivers the mail: Kestrel keeps the list, each subscriber's consent, and the record of every send. AWS reviews your account before it lets you send to anyone but yourself. This page asks for that early, and you test in the sandbox while you wait.
+Kestrel sends the newsletter's posts through Amazon SES, Amazon's email service. SES only delivers the mail: Kestrel keeps the list, each subscriber's consent, and the record of every send. SES prices every email alike, with no split between transactional and marketing mail, and costs the least at every list size above a tiny one. AWS reviews your account before it lets you send to anyone but yourself. This page asks for that early, and you test in the sandbox while you wait.
 
 In this guide, you verify your sending hostname with SES and add a DMARC record. You forward readers' replies to the publisher's inbox, and ask AWS for production access. You also route bounces and complaints to the app through SNS. Then you give the app its AWS credentials, set the provider, and deploy.
 
@@ -227,7 +227,7 @@ Until now the app has run with no email provider connected, refusing to send. Se
     }
     ```
 
-    On Workers Paid, also add `"SUBREQUEST_BUDGET": "10000"`, the plan's limit, so each minute sends more. Leave it out on Workers Free. [As your list grows](../guides/09-as-your-list-grows.md) says when the plan is worth it.
+    On Workers Paid, also add `"SUBREQUEST_BUDGET": "10000"`, the plan's limit, so each minute sends more. Leave it out on Workers Free, which suits a list of up to about 1,000 subscribers. [As your list grows](../guides/09-as-your-list-grows.md) says why.
 
     When AWS grants production access, set `SES_MAX_SEND_RATE` to the maximum send rate on the **Account dashboard**, and deploy again. The app keeps to that rate, so SES doesn't throttle your send.
 

package/docs/get-started/05-verify.md

@@ -77,7 +77,7 @@ Every email carries an unsubscribe link, and a header that lets mail clients sho
 
 ## 6. Check that bounces and complaints come back
 
-When an address bounces or marks your mail as spam, SES tells the app through SNS. The app then stops mailing that address. SES has test addresses that act out each case without reaching a real person, and the sandbox lets you mail them.
+When an address bounces or marks your mail as spam, SES tells the app through SNS. The app then stops mailing that address: a bounce suppresses it, and a complaint unsubscribes it. SES has test addresses that act out each case without reaching a real person, and the sandbox lets you mail them.
 
 1. Open `https://newsletter.example.com/subscribe`, and subscribe each test address:
 
@@ -86,9 +86,9 @@ When an address bounces or marks your mail as spam, SES tells the app through SN
 
     Each one gets a confirmation email, which bounces or is marked as spam.
 
-1. In the editor, **Subscribers** lists both addresses as **Pending**, each with a **Suppressed** flag. The app never mails a suppressed address again.
+1. In the editor, **Subscribers** lists the bounce address as **Pending** with a **bounced** flag, and the complaint address as **Unsubscribed**. Open its row: its page says it left by a complaint. The app mails neither again.
 
-If an address has no flag, SES's events aren't reaching the app. Check the configuration set and the SNS subscription in [Connect Amazon SES](04-ses.md#6-send-bounces-and-complaints-to-sns).
+If the bounce address has no flag, or the complaint address is still pending, SES's events aren't reaching the app. Check the configuration set and the SNS subscription in [Connect Amazon SES](04-ses.md#6-send-bounces-and-complaints-to-sns).
 
 ## 7. Read the logs
 
@@ -122,7 +122,7 @@ The checks leave test addresses on the list. Erase them, so the publisher starts
 
 1. Erase your second address too, if it won't be a reader.
 
-Erasing keeps a do-not-contact marker, but the person can subscribe again through the subscribe page. Erasing your own address doesn't lock you out.
+Erasing keeps only the address, so it's never mailed again, but the person can subscribe again through the subscribe page. Erasing your own address doesn't lock you out.
 
 When every section gives the result it describes, your instance is ready for subscribers.
 

package/docs/get-started/06-go-live.md

@@ -18,8 +18,9 @@ If someone else is the publisher, let them sign in first:
 
 Each of these guides adds one thing, and you can come back to any of them later.
 
-- [Connect Claude to the API](../guides/01-connect-claude.md), so Claude can draft, proofread, and schedule posts through the same API the editor uses.
+- [Allow Claude to connect](../guides/01-allow-claude.md), so the publisher can connect Claude Desktop, claude.ai, or Claude Code, and have it draft, proofread, and schedule posts as them, through the same API the editor uses.
+- [Automate with a service token](../guides/02-automate.md), so a script can call the API with a service token, when no one is signed in.
 - [Notifications through Cloudflare's email](../guides/03-notifications.md), so problems are reported even when the email provider has stopped sending.
 - [Rate-limit the subscribe form](../guides/05-rate-limit.md), before the subscribe link is shared widely.
-- [As your list grows](../guides/09-as-your-list-grows.md), from about 5,000 subscribers.
+- [As your list grows](../guides/09-as-your-list-grows.md), from about 1,000 subscribers.
 - [Upgrade to a new release](../guides/07-upgrade.md), when one comes out.

package/docs/guides/01-allow-claude.md

@@ -0,0 +1,68 @@
+# Allow Claude to connect
+
+Connecting Claude to the instance lets the publisher draft, test, and schedule posts by asking for them in Claude. Claude works through the same API as the dashboard, and its changes show as the publisher's, via Claude.
+
+In this guide, you turn on Cloudflare's Managed OAuth for the Access application that locks the dashboard, then connect Claude, or send the publisher the address to connect to.
+
+To run a script or scheduled job with no one present, use a service token instead, as [Automate with a service token](02-automate.md) describes.
+
+## Before you begin
+
+You need:
+
+- The dashboard locked with Access, from [Lock the dashboard with Access](../get-started/03-access.md).
+- A deployed instance. Claude Desktop and claude.ai reach it from Anthropic's servers, so they can't reach one running on your own computer.
+
+## 1. Turn on Managed OAuth
+
+Managed OAuth lets an app such as Claude act with a person's account, the way the editor does in their browser. Cloudflare marks it as beta, and its [Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/) page describes it.
+
+1. In **Zero Trust**, go to **Access controls → Applications**, and select **Edit** on your application.
+
+1. On the **Additional settings** tab, select the **OAuth** filter, and find **Managed OAuth (Beta)**.
+
+1. Turn on **Managed OAuth**.
+
+1. Turn on **Allow localhost clients** and **Allow loopback clients**. Claude Code receives the person's approval on their own computer, at a `localhost` or `127.0.0.1` address.
+
+1. Under **Allowed redirect URIs**, add Claude's address, so Claude Desktop and claude.ai can connect:
+
+    ```
+    https://claude.ai/api/mcp/auth_callback
+    ```
+
+    Access accepts Claude only with an address listed here. Leave it out if no one will connect Claude Desktop or claude.ai.
+
+1. Set the **Grant session duration** to 1 week. A connection renews itself while it's in use until this ends, and then Claude asks the person to approve it again. Cloudflare recommends one to two weeks for a command-line tool.
+
+1. Save the application.
+
+1. Check that a request with no sign-in now says where an app signs in:
+
+    ```bash
+    curl -si https://newsletter.example.com/api/whoami
+    ```
+
+    It answers `401`, and its `www-authenticate` line starts with `Bearer` and names `resource_metadata`. Without Managed OAuth, Cloudflare answers with a redirect to its login page instead. A browser still gets the login page either way.
+
+## 2. Connect Claude, or send the publisher the address
+
+The publisher connects at the instance's address followed by `/api/mcp`:
+
+```
+https://newsletter.example.com/api/mcp
+```
+
+If you're the publisher, connect now, as [Connect Claude](../publishing/08-connect-claude.md) describes. If someone else is, send them that address and a link to the same page.
+
+## Who can connect
+
+Anyone the `Publishers` policy lets into the dashboard can connect Claude, since they sign in the same way. To stop someone connecting, remove them from that policy. If you set `ACCESS_ALLOWED_EMAILS`, store the list again without them: the app checks it on every request, so it takes effect at once.
+
+## Check it
+
+1. Connect Claude Desktop or claude.ai, as [Connect Claude](../publishing/08-connect-claude.md) describes. The connector lists Kestrel's tools, such as **Get the publication** and **Save a draft**.
+
+1. Ask Claude what the publication is called. It answers with the name the dashboard shows.
+
+If Claude can't connect, [Claude can't connect](../publishing/06-troubleshooting.md#claude-cant-connect) lists what it reports and the fix.

package/docs/guides/02-automate.md

@@ -0,0 +1,88 @@
+# Automate with a service token
+
+A service token lets a script or scheduled job call the API, such as a job that drafts a weekly digest. Kestrel labels these changes **a service token**, rather than with a person's name.
+
+In this guide, you create a service token, allow it in through the Access application, give it to your script, and check that it works. To connect Claude as yourself instead, follow [Allow Claude to connect](01-allow-claude.md).
+
+## Before you begin
+
+You need:
+
+- The dashboard locked with Access, from [Lock the dashboard with Access](../get-started/03-access.md).
+- The script or job that will call the API, and somewhere it keeps secrets.
+
+## 1. Create a service token
+
+A service token is a Client ID and a Client Secret that a program sends with each request. It carries no email, so the app tells it apart from a person's sign-in.
+
+1. In **Zero Trust**, go to **Access controls → Service credentials → Service Tokens**, and select **Create Service Token**.
+
+1. Name it for what will use it, such as `kestrel-automation`, and choose a **Service Token Duration**. A year is a good default.
+
+1. Select **Generate token**.
+
+1. Copy the **Client ID** and the **Client Secret**. Cloudflare shows the secret only once.
+
+## 2. Allow the token in
+
+The application lets in only the people its `Publishers` policy names, so the token needs a policy of its own on the same application.
+
+1. Under **Access controls → Applications**, select **Configure** on the application from [Lock the dashboard with Access](../get-started/03-access.md#2-create-the-access-application).
+
+1. Add a policy:
+
+    - **Policy name:** `Automation`
+    - **Action:** Service Auth
+    - **Include:** the **Service Token** selector, with your token
+
+1. Save the application.
+
+This policy is the only thing that lets the token in. `ACCESS_ALLOWED_EMAILS` doesn't apply to it, since it has no email.
+
+## 3. Give the token to your script
+
+The script sends the two values as headers on every request: `CF-Access-Client-Id` with the Client ID, and `CF-Access-Client-Secret` with the Client Secret.
+
+1. Store the Client ID and the Client Secret where your script reads secrets, such as its environment, your CI's secrets, or a password manager. Never commit the secret to a repository.
+
+1. Have the script send both headers with every request to `https://newsletter.example.com/api/…`. For example, this request saves a new draft:
+
+    ```bash
+    curl -s https://newsletter.example.com/api/posts \
+      -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
+      -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
+      -H "Content-Type: application/json" \
+      -d '{"subject":"Weekly digest","markdown":"# This week\n\nThree things worth reading."}'
+    ```
+
+## Check it
+
+1. Call `GET /api/whoami` with the two headers. The app answers with a program's identity, not a person's:
+
+    ```bash
+    curl -s https://newsletter.example.com/api/whoami \
+      -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
+      -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"
+    ```
+
+    ```
+    {"principal":{"kind":"service","token_id":"e367c0ffee5eb4.access","client":null},"auth":{"mode":"access"}}
+    ```
+
+    The `token_id` is the Client ID Zero Trust shows beside your token. If it's a different one, the script is using another token.
+
+1. Call `GET /api/posts`. It answers with the posts the editor shows.
+
+1. Open a draft in the editor, and have the script save a change to it. The editor shows that the draft was changed elsewhere, last edited by **a service token**.
+
+If the script gets a `401`, a `403`, or a login page, check the policy from section 2, and the token's two values. The policy's action must be Service Auth, since the app refuses a login through any other kind of policy with a `401` whose `reason` is `access_unidentified`. Check that the token hasn't expired, too.
+
+## Renew or revoke a token
+
+A service token stops working when its duration ends. Before then, extend it on the token under **Access controls → Service credentials → Service Tokens**, or create a new token, add it to the `Automation` policy, give it to the script, and then delete the old one.
+
+To stop a script at once, delete its token there. Its next request is refused.
+
+## More information
+
+The API reference describes every route: its method and path, the body it takes, its refusals, and an example. The editor's **API** tab shows it, and a program reads it as Markdown: `GET /api/reference.md` is the index, and `GET /api/reference/<resource>.md` holds one resource's routes in full. `GET /api/openapi.json` is the same reference as an OpenAPI 3.1 document, for a tool that imports one.

package/docs/guides/09-as-your-list-grows.md

@@ -1,6 +1,6 @@
 # As your list grows
 
-A new instance runs on Cloudflare's free Workers plan with your starting Amazon SES limits. That suits a list of up to about 5,000 subscribers. Past that, two limits matter: how fast SES lets you send, and how many database writes the free plan allows a day.
+A new instance runs on Cloudflare's free Workers plan with your starting Amazon SES limits. Workers Free suits a list of up to about 1,000 subscribers. Past about 5,000, one send can use up the day's database writes and stop the newsletter until midnight UTC. Two limits matter as the list grows: how fast SES lets you send, and how many database writes the free plan allows a day.
 
 In this guide, you raise your SES limits, which helps on either plan, and upgrade to Workers Paid, which a larger list needs. Then you see how long a send takes after each.
 
@@ -10,7 +10,7 @@ SES caps how many emails your account sends a day, and how many a second. A send
 
 1. Ask AWS for a higher daily quota and a maximum send rate of 50, as AWS's [Increasing your Amazon SES sending quotas](https://docs.aws.amazon.com/ses/latest/dg/manage-sending-quotas-request-increase.html) describes.
 
-1. When AWS grants it, the SES **Account dashboard** shows your new rate. In `wrangler.jsonc`, set the `production` block's [`SES_MAX_SEND_RATE`](../reference/01-configuration.md#ses_max_send_rate) to match.
+1. When AWS grants it, the SES **Account dashboard** shows your new rate. In `wrangler.jsonc`, set the `production` block's `SES_MAX_SEND_RATE` to match, as [Configuration](../reference/01-configuration.md#vars) describes.
 
 1. Commit the change, and push it:
 
@@ -27,11 +27,13 @@ SES caps how many emails your account sends a day, and how many a second. A send
 
 ## 2. Upgrade to Workers Paid
 
-On the free plan, [D1](https://developers.cloudflare.com/d1/platform/pricing/) allows a fixed number of database writes a day. A send to about 7,000 recipients uses them all, and then the whole app stops until midnight UTC. Until you upgrade, the app warns the publisher before a send or an import that could use up the day. It's recommended to upgrade from about 5,000 subscribers.
+On the free plan, [D1](https://developers.cloudflare.com/d1/platform/pricing/) allows 100,000 written rows a day, reset at midnight UTC. A send writes about 14 rows a recipient, receipts included, and an import about 7 for each new subscriber. So at 1,000 subscribers, an import of the whole list and two sends on one day use about a third of the day. Once the day's rows are spent, the whole app stops until midnight UTC, the SES webhook with it, so that day's bounces and complaints are lost, and suppress or unsubscribe no one.
+
+It's recommended to upgrade from about 1,000 subscribers. Past that, the Dashboard and the Subscribers screen say so, and so does an import that would take the list past it. Past about 5,000, a send that could use up the day on its own also warns before it's scheduled. The app doesn't count the day's writes, so between the two, two large sends or several imports and a send on one UTC day can still use it up without a warning at that moment.
 
 1. Upgrade your Cloudflare account to the $5 [Workers Paid plan](https://developers.cloudflare.com/workers/platform/pricing/), which has no daily limit on writes.
 
-1. In `wrangler.jsonc`, add `"SUBREQUEST_BUDGET": "10000"` to the `production` block's `vars`. It tells the app it's on Workers Paid, so each minute sends far more ([`SUBREQUEST_BUDGET`](../reference/01-configuration.md#subrequest_budget)).
+1. In `wrangler.jsonc`, add `"SUBREQUEST_BUDGET": "10000"` to the `production` block's `vars`. It tells the app it's on Workers Paid, so each minute sends far more. [Configuration](../reference/01-configuration.md#vars) describes `SUBREQUEST_BUDGET`.
 
 1. Commit the change, and push it:
 
@@ -46,6 +48,8 @@ On the free plan, [D1](https://developers.cloudflare.com/d1/platform/pricing/) a
     npx wrangler deploy --env production
     ```
 
+Over years, one more limit can matter: on the free plan, one [D1 database](https://developers.cloudflare.com/d1/platform/limits/) holds at most 500 MB, and every send keeps a row for each recipient in its record. Workers Paid raises it to 10 GB.
+
 ## How long a send takes
 
 | Setup | 1,000 subscribers | 5,000 subscribers | 10,000 subscribers |