@kurtbruns/kestrel 1.13.0 → 1.15.0

package/docs/publishing/08-connect-claude.md

@@ -0,0 +1,60 @@
+# Connect Claude
+
+Connecting Claude to Kestrel lets you publish by asking Claude. It drafts, tests, and schedules posts as you, and its changes show as yours, via Claude.
+
+**Your Kestrel instance has to allow this first,** as [Allow Claude to connect](../guides/01-allow-claude.md) describes.
+
+How you connect depends on where you talk to Claude:
+
+- **In Claude Desktop or claude.ai,** add Kestrel as a connector.
+- **In Claude Code,** add Kestrel as a connector, or sign in with the Kestrel CLI to use the API directly.
+
+## Claude Desktop or claude.ai
+
+1. In Claude, go to **Customize → Connectors**, select **Add**, then **Add custom connector**.
+1. Name it, and enter your publication's address followed by `/api/mcp`, such as `https://newsletter.example.com/api/mcp`.
+1. Under **OAuth client**, choose **Register automatically**.
+1. Select **Add**, then sign in the way you do for the dashboard, and approve the sign-in.
+
+On a Team or Enterprise plan, an Owner of your Claude organization adds the connector under **Organization settings → Connectors** instead, and you then select **Connect** on it. Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) has the details.
+
+To check it works, ask Claude what your publication is called.
+
+## Claude Code
+
+Claude Code can use the same connector as Claude Desktop and claude.ai. To reach the whole API instead, images included, sign Claude Code in with the Kestrel CLI:
+
+1. Run this, with your publication's address:
+
+    ```bash
+    npx kestrel login https://newsletter.example.com
+    ```
+
+1. Approve the sign-in in the browser that opens. The terminal then says who you're signed in as.
+
+The sign-in stays on your computer. Opened in your instance's repository, Claude Code then calls Kestrel's API as you through `kestrel api`, the way `gh` calls GitHub, following your instance's instructions for Claude. Its changes show as yours, via Claude Code.
+
+## How long a sign-in lasts
+
+The sign-in renews itself while you use Claude, until your instance's grant session ends, a week if it follows the setup guide. Then Claude asks you to approve a new one.
+
+To disconnect, remove the connector under **Customize → Connectors**. To sign out of the Kestrel CLI, run `npx kestrel logout`.
+
+## Working with Claude
+
+Ask Claude in plain words, the way you'd ask a colleague, and ask it what it can do: it knows its tools, and reads these pages from Kestrel. For example:
+
+- "Proofread my draft titled 'First frost' and schedule it to go out Friday at 7am."
+- "Add jack@example.com to the list."
+- "Import the subscribers in this CSV from my old newsletter."
+
+Whatever Claude is asked, Kestrel holds these for any client:
+
+- **Every send waits out the review window,** and you can cancel it until it goes out.
+- **What goes out is exactly the copy that was scheduled.** A scheduled post is locked.
+- **No one is mailed twice,** and only confirmed subscribers receive a post.
+- **An unsubscribe is final** until the reader subscribes again.
+- **No one's edit is overwritten.** A save based on an older version is refused.
+- **Only you can let an import grow a scheduled send,** in the dashboard.
+
+Changes Claude makes show in the dashboard as yours, such as "Scheduled by you@example.com via Claude".

package/docs/publishing/09-share-your-subscribe-link.md

@@ -1,6 +1,6 @@
 # Share your subscribe link
 
-Your publication's subscribe page is at `/subscribe` on your Kestrel's address, such as `https://newsletter.example.com/subscribe`. Copy it from the dashboard's checklist or **Settings → Ways to subscribe**, and share it wherever your readers are. A reader joins only once they confirm by email.
+Your publication's subscribe page is at `/subscribe` on your publication's address, such as `https://newsletter.example.com/subscribe`. Copy it from the dashboard's checklist or **Settings → Ways to subscribe**, and share it wherever your readers are. A reader joins only once they confirm by email.
 
 **Signups open only once an email provider is connected.** Until then, the page says the newsletter isn't taking subscribers yet, and the dashboard says so too. You can share the link anyway, and it opens once email is connected ([Connect Amazon SES](../get-started/04-ses.md)).
 

package/docs/publishing/10-check-your-setup.md

@@ -1,30 +1,23 @@
 # Check your setup
 
-Before your readers get anything, see it arrive yourself, and make sure a problem will reach you without your watching for it. Send yourself a test and reply to it, subscribe yourself, and set where Kestrel emails you.
+Before your readers get anything, check three things yourself: your email arrives and replies reach you, subscribing works, and problems will reach you.
 
-If you're bringing a list of more than about 1,000 subscribers, upgrade to Cloudflare's Workers Paid plan before you import it. 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. [As your list grows](../guides/09-as-your-list-grows.md) walks through the upgrade.
+**Email has to be connected first.** Until it is, nothing can be sent, and the dashboard's checklist shows **Connect Amazon SES** in place of this step, as [Connect Amazon SES](../get-started/04-ses.md) describes.
 
-## Send yourself a test
+## 1. Send yourself a test
 
 Choose **Template** in the sidebar, then **Send test email**, and send a sample post to your own inboxes. When it arrives, check:
 
-- **The From name and address,** which readers see first. They're set when Kestrel is deployed ([Connect Amazon SES](../get-started/04-ses.md#8-set-the-provider-and-deploy)).
+- **The From name and address,** which readers see first. They're set when your instance is deployed.
 - **Where it lands:** the inbox, Promotions, or spam. If it lands in spam, check your sending domain's records, as [Sending-domain DNS](../reference/02-sending-domain-dns.md) describes.
 - **A reply.** Reply to the test, and check that it reaches your inbox. Kestrel never sees replies, so this depends on [forwarding your From address](../get-started/04-ses.md#3-receive-replies-at-your-from-address).
 
-## Subscribe yourself
+## 2. Subscribe yourself
 
-Open your subscribe page, from the link under **Settings → Ways to subscribe**, and subscribe with a personal address. Then confirm. You see what a new reader sees, and you then appear under **Subscribers** as **Confirmed**. [Share your subscribe link](09-share-your-subscribe-link.md) covers the page and the confirmation email.
+Open your subscribe page from **Settings → Ways to subscribe**, subscribe with a personal address, and confirm. You see what a new reader sees, and you appear under **Subscribers** as **Confirmed**.
 
-## Set your notifications address
+## 3. Set your notifications address
 
-Under **Settings → Notifications**, fill in **Send notifications to**, save, and choose **Send a test notification**. Kestrel then emails you when a send finishes or needs you. [Notifications](06-troubleshooting.md#notifications) lists what you're told, and why a second way to send them is worth asking for.
-
-## If email isn't connected
-
-Until an email provider is connected, nothing can be sent, and the dashboard says so. The checklist shows **Connect Amazon SES** in place of this step, as [Connect Amazon SES](../get-started/04-ses.md) describes. **Settings → Email sender** shows your From address, sending domain, and provider, read-only.
-
-## As your list grows
-
-A growing list meets your Amazon SES daily sending quota, longer sends, and on Cloudflare's free Workers plan, a cap on daily database writes. Kestrel tells you when you reach each one (on the free plan, from about 1,000 subscribers), and [As your list grows](../guides/09-as-your-list-grows.md) covers raising each.
+Under **Settings → Notifications**, fill in **Send notifications to**, save, and choose **Send a test notification**. Kestrel then emails you when a send finishes or needs you, as [Notifications](06-troubleshooting.md#notifications) lists.
 
+**If you're bringing more than about 1,000 subscribers, upgrade to Cloudflare's Workers Paid plan before you import.** [Bring your existing list](01-your-list.md#limits) explains why.

package/docs/publishing/11-email-template.md

@@ -33,4 +33,4 @@ A variable is replaced with its value in each email. Type it exactly as shown, o
 
 **Send test email** on the **Template** page sends a sample post through your saved template, so you see it in a real inbox. With unsaved edits, the button reads **Save & send test**, since a test always uses the saved template.
 
-A change to the template re-makes the email of every scheduled post, as [Schedule and send](04-write-a-post.md#schedule-and-send) describes.
+A change to the template, or to a publication detail it shows, re-makes the email of every scheduled post, with the same content and send time. Kestrel asks before it saves, and each re-made post then asks you to send a new test. A change is refused while a post is within its last few minutes before sending. Posts already sending or sent never change.

package/docs/publishing/README.md

@@ -4,7 +4,7 @@ These pages get you publishing in the dashboard, and cover the decisions to make
 
 ## Set up your publication
 
-The steps to set up a new publication, in the order the dashboard's setup checklist lists them. Once you've started a post, they stay on the dashboard as **Finish setting up** until you publish your first post, one that goes to your subscribers and onto your site. That's the fourth step.
+These are the steps to set up your publication. If you're starting without a list, skip importing one.
 
 1. [Name your publication](03-name-your-publication.md)
 1. [Check your setup](10-check-your-setup.md)
@@ -17,7 +17,7 @@ The steps to set up a new publication, in the order the dashboard's setup checkl
 Things you choose to do once you're running.
 
 - [Edit your email template](11-email-template.md)
-- [Working with Claude](07-working-with-claude.md)
+- [Connect Claude](08-connect-claude.md)
 
 ## Rules and troubleshooting
 

package/docs/reference/01-configuration.md

@@ -10,142 +10,189 @@ In local development, `npm run dev` reads the top level of `wrangler.jsonc` and
 
 None of these can be read or changed from inside the app, by the editor or by Claude. Settings in the editor shows the public ones, read-only.
 
+This is the `production` block a new instance starts with. [Deploy the app](../get-started/02-deploy.md) fills in its database and hostnames:
+
+```jsonc
+"production": {
+  "name": "kestrel-production",
+  "routes": [{ "pattern": "newsletter.example.com", "custom_domain": true }],
+  "workers_dev": false,
+  "preview_urls": false,
+  "triggers": { "crons": ["* * * * *"] },
+  "observability": { "enabled": true },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "kestrel-production",
+      "database_id": "REPLACE_WITH_PRODUCTION_D1_ID",
+      "migrations_dir": "migrations"
+    }
+  ],
+  "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "kestrel-media-production" }],
+  "vars": {
+    "PROVIDER": "",
+    "APP_ORIGIN": "https://newsletter.example.com",
+    "ARCHIVE_BASE_PATH": "/archive",
+    "SENDING_DOMAIN": "send.example.com",
+    "FROM_ADDRESS": "Newsletter <newsletter@send.example.com>",
+    "AWS_REGION": "us-east-1"
+  }
+}
+```
+
 ## Vars
 
-| Var | What it is | Default |
-| --- | --- | --- |
-| `PROVIDER` | the email provider: `ses`, or `fake` for local development | none: no provider connected |
-| `APP_ORIGIN` | the origin the app is served from: scheme and host, no path | required |
-| `ARCHIVE_BASE_PATH` | the path the archive lives under | `/archive` |
-| `FROM_ADDRESS` | the `From:` of every email | required with a real provider |
-| `SENDING_DOMAIN` | the sending domain, shown in Settings | none |
-| `AWS_REGION` | the SES region | `us-east-1` in the template, required with SES |
-| `SES_MAX_SEND_RATE` | your SES account's maximum send rate, in messages a second | `14` |
-| `SUBREQUEST_BUDGET` | how many subrequests one minute's send work may use | `50` |
-| `MIN_LEAD_SECONDS` | the least time every send stays cancelable before it goes out | `300` |
-| `ARCHIVE_ORIGIN` | the origin archive links use, to put the archive on your website | `APP_ORIGIN` |
-| `MEDIA_PUBLIC_BASE` | the base URL images are served from | `APP_ORIGIN` + `/media` |
-| `NOTIFY_FROM` | the sender of notifications through Cloudflare's email | `Kestrel <kestrel@` + the app's hostname + `>` |
-| `ALLOW_FAKE_PROVIDER` | `true` lets `fake` run on a real hostname, for a demo that mails no one on purpose | unset |
+Vars go in the environment block's `vars`. Every value is a string.
+
+- `PROVIDER` optional
+
+    The email provider: `ses`, or `fake` for local development. Default: none, so no provider is connected. Refused unless it's exactly `ses`, `fake`, or `none`: a misspelling, or `SES`, is never taken for another. `resend`, which earlier releases supported, is refused with a pointer to [Connect Amazon SES](../get-started/04-ses.md#switch-an-instance-that-already-sends).
+
+    Until it's set, or while it's empty, the app runs with no provider connected. Posts can be written and previewed, but everything that would send email is refused: scheduling, sending now, test emails, and the confirmation emails that signups need. The subscribe page says signups aren't open yet, and Settings shows **No email provider connected**. Setting it to `none` means the same. A new instance's `production` block declares it empty, so wrangler doesn't warn that the top level's value is missing there. [Connect Amazon SES](../get-started/04-ses.md) changes it to `ses`.
+
+    `fake` delivers nothing. It records a send as if every recipient accepted it. Local development runs on it, and names it on purpose in the top level of `wrangler.jsonc`. Never copy it into `production`, whatever wrangler suggests: every subscriber would be recorded as sent the post, and never get it. The app refuses `fake` unless `APP_ORIGIN` is on `localhost` or `127.0.0.1`, since on a real hostname it would open signups whose confirmations go nowhere.
+
+- `ALLOW_FAKE_PROVIDER` optional
+
+    `true` lets `fake` run on a real hostname, for a hosted demo that mails no one on purpose. No other deployment needs it. With `fake`, it must be `true` when set; every other provider ignores it.
+
+- `APP_ORIGIN` required
 
-### `PROVIDER`
+    The origin the app is served from: scheme and host, no path. Refused unless it's a plain `http` or `https` origin with no path, and never on `example.com` or a name under it, unless `PROVIDER` is `fake`. A trailing slash is dropped.
 
-Until it's set, or while it's empty, the app runs with no provider connected. Posts can be written and previewed, but everything that would send email is refused: scheduling, sending now, test emails, and the confirmation emails that signups need. The subscribe page says signups aren't open yet, and Settings shows **No email provider connected**. Setting it to `none` means the same. A new instance's `production` block declares it empty, `"PROVIDER": ""`, so wrangler doesn't warn that the top level's value is missing there. [Connect Amazon SES](../get-started/04-ses.md) changes it to `ses`.
+- `AWS_REGION` required with SES
 
-`fake` delivers nothing. It records a send as if every recipient accepted it. Local development runs on it, and names it on purpose in the top level of `wrangler.jsonc`. Never copy it into `production`, whatever wrangler suggests: every subscriber would be recorded as sent the post, and never get it. The app refuses `fake` unless `APP_ORIGIN` is on `localhost` or `127.0.0.1`. A hosted demo that runs `fake` on a real hostname on purpose sets `ALLOW_FAKE_PROVIDER` to `true`, which no other deployment needs, and which no other provider reads.
+    The SES region. The template sets `us-east-1`.
 
-### `FROM_ADDRESS` and `SENDING_DOMAIN`
+- `FROM_ADDRESS` required with a real provider
 
-`FROM_ADDRESS` is the only address mail is sent from, and the identity your provider authenticates. `SENDING_DOMAIN` is for display: Settings shows it beside the From address. The app never checks that the two match, so set `SENDING_DOMAIN` to the part of `FROM_ADDRESS` after the `@`.
+    The `From:` of every email, and the identity your provider authenticates. Refused unless it's an email address, optionally with a display name in front, like `Name <address>`, and never on `example.com`, unless `PROVIDER` is `fake`.
 
-Neither one is the publication's name, tagline, or logo. You set those in the editor, under **Settings → Publication identity**. Until you do, the From address's display name stands in for the name, and with neither, the emails and reader pages show no name at all.
+    It isn't the publication's name, tagline, or logo. You set those in the editor, under **Settings → Publication identity**. Until you do, the From address's display name stands in for the name, and with neither, the emails and reader pages show no name at all.
 
-### `ARCHIVE_BASE_PATH`
+- `SENDING_DOMAIN` optional
 
-A listed post's archive address is `ARCHIVE_BASE_PATH` followed by the post's slug. Emails link through each post's unlisted link, `/email/<token>` on `APP_ORIGIN`, which forwards to the archive address, so changing the prefix later breaks no email that carries one, only archive addresses people have shared. Emails sent by 1.11 or earlier carry the archive address itself, and changing the prefix breaks those. To keep links from an older install working, set it to the prefix they use, such as `/newsletter`.
+    The sending domain, shown in Settings beside the From address. The app never checks that it matches `FROM_ADDRESS`, so set it to the part of `FROM_ADDRESS` after the `@`. Never on `example.com`, unless `PROVIDER` is `fake`.
 
-A missing leading slash is added, and a trailing slash is dropped.
+- `ARCHIVE_BASE_PATH` optional
 
-### `SES_MAX_SEND_RATE`
+    The path the archive lives under. Default: `/archive`. A missing leading slash is added, and a trailing slash is dropped.
 
-The app sends SES one request a second, the most SES takes, and each request carries one second of this rate, up to 50 recipients. Set it to the maximum send rate on your SES **Account dashboard**. To send faster, ask AWS to raise that rate to 50 before you move to Workers Paid: on Workers Free, a rate of 50 sends nearly four times as many recipients a minute as 14, and a higher rate adds nothing there. That's `1` in the sandbox, and whatever AWS grants after that. The default, 14, is a common starting rate, not your account's.
+    A listed post's archive address is `ARCHIVE_BASE_PATH` followed by the post's slug. Emails link through each post's unlisted link, `/email/<token>` on `APP_ORIGIN`, which forwards to the archive address, so changing the prefix later breaks no email that carries one, only archive addresses people have shared. Emails sent by 1.11 or earlier carry the archive address itself, and changing the prefix breaks those. To keep links from an older install working, set it to the prefix they use, such as `/newsletter`.
 
-A rate set too high only means SES throttles some requests. Those recipients wait for the next minute, and no one is mailed twice.
+- `SES_MAX_SEND_RATE` optional
 
-### `SUBREQUEST_BUDGET`
+    Your SES account's maximum send rate, in messages a second. Default: `14`, a common starting rate, not your account's. Refused unless it's a whole number above zero.
 
-Cloudflare caps how many subrequests one run of a Worker may make. Database queries and outbound requests both count. It also caps database queries alone: 50 a run on Workers Free, and 1,000 on Workers Paid. Each minute's send work is one run, so a large send goes out over several minutes, each stopping short of both caps.
+    The app sends SES one request a second, the most SES takes, and each request carries one second of this rate, up to 50 recipients. Set it to the maximum send rate on your SES **Account dashboard**: `1` in the sandbox, and whatever AWS grants after that. To send faster, ask AWS to raise that rate to 50 before you move to Workers Paid: on Workers Free, a rate of 50 sends nearly four times as many recipients a minute as 14, and a higher rate adds nothing there. A rate set too high only means SES throttles some requests. Those recipients wait for the next minute, and no one is mailed twice.
 
-This setting is the subrequest cap. The app keeps database queries under theirs on its own.
+- `SUBREQUEST_BUDGET` optional
 
-- **The default, 50,** is the Workers Free limit, and safe on any plan. A minute sends four SES requests: 56 recipients at a send rate of 14, and 200 at a rate of 50 or more.
-- **On Workers Paid,** which allows 10,000, set `"SUBREQUEST_BUDGET": "10000"`. A minute then sends about 50 SES requests, one a second: about 700 recipients at a rate of 14, and about 2,500 at 50 or more.
-- **If you raised the Worker's own limit** with `limits.subrequests`, you may set this to match.
+    How many subrequests one minute's send work may use, which also tells the app which Workers plan it's on. Default: `50`, the Workers Free limit, and safe on any plan. Refused unless it's a whole number above zero. A value below 30 is raised to 30, the least a minute needs to send anything and still send a notification.
 
-It's also how the app tells Workers Free from Workers Paid. At the default, the app runs on Free's limits:
+    Cloudflare caps how many subrequests one run of a Worker may make. Database queries and outbound requests both count. It also caps database queries alone: 50 a run on Workers Free, and 1,000 on Workers Paid. Each minute's send work is one run, so a large send goes out over several minutes, each stopping short of both caps. This setting is the subrequest cap. The app keeps database queries under theirs on its own.
 
-- One import takes up to 1,000 rows, since Free's 10 ms of CPU a request can't plan and commit more. Above it, up to 10,000 ([Limits in detail](../publishing/01-your-list.md#limits-in-detail)).
-- An export reads 1,000 rows a page. Above it, 10,000.
-- 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. So the Dashboard and the Subscribers screen recommend Workers Paid once the confirmed list passes 1,000, and so does an import plan that would take it past. The app also warns before a send to more than 5,000 recipients ([As your list grows](../guides/09-as-your-list-grows.md)). None of these stops you. Above the default, none appears, so set it on an account already on Workers Paid.
+    - At the default, a minute sends four SES requests: 56 recipients at a send rate of 14, and 200 at a rate of 50 or more.
+    - On Workers Paid, which allows 10,000, set `"SUBREQUEST_BUDGET": "10000"`. A minute then sends about 50 SES requests, one a second: about 700 recipients at a rate of 14, and about 2,500 at 50 or more.
+    - If you raised the Worker's own limit with `limits.subrequests`, you may set this to match.
 
-Never set it above your plan's limit. A minute that hits the cap is cut off mid-batch, and the send stalls until a later minute picks it up. A value below 30 is raised to 30, the least a minute needs to send anything and still send a notification.
+    Never set it above your plan's limit. A minute that hits the cap is cut off mid-batch, and the send stalls until a later minute picks it up.
 
-### `MIN_LEAD_SECONDS`
+    At the default, the app runs on Workers Free's limits. One import takes up to 1,000 rows, since Free's 10 ms of CPU a request can't plan and commit more, and an export reads 1,000 rows a page. Above it, both take 10,000 ([Limits in detail](../publishing/01-your-list.md#limits-in-detail)). 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. So the Dashboard and the Subscribers screen recommend Workers Paid once the confirmed list passes 1,000, and so does an import plan that would take it past. The app also warns before a send to more than 5,000 recipients ([As your list grows](../guides/09-as-your-list-grows.md)). None of these stops you. Above the default, none appears, so set it on an account already on Workers Paid.
 
-Every send stays visible and cancelable for at least this long before it goes out, whether it's scheduled, sent now, or moved. It's the window to catch a mistake, including one in a send Claude prepared.
+- `MIN_LEAD_SECONDS` optional
 
-The floor is 60, since sends go out from a once-a-minute schedule. The ceiling is 86400, one day. It's the least wait before every send, not a limit on how far ahead a post can be scheduled. It lives in deploy config on purpose, so neither the editor nor Claude can shorten it.
+    The least time every send stays cancelable before it goes out, whether it's scheduled, sent now, or moved. Default: `300`, five minutes. Refused unless it's a whole number from 60 to 86400, one day.
 
-### `ARCHIVE_ORIGIN` and `MEDIA_PUBLIC_BASE`
+    It's the window to catch a mistake, including one in a send Claude prepared. The floor is 60, since sends go out from a once-a-minute schedule. It's the least wait before every send, not a limit on how far ahead a post can be scheduled. It lives in deploy config on purpose, so neither the editor nor Claude can shorten it.
 
-Leave them unset to keep everything on the app's own hostname.
+- `ARCHIVE_ORIGIN` optional
 
-`ARCHIVE_ORIGIN` points archive links at another origin, such as your website, `https://example.com`. The app doesn't answer there on its own. A Worker route on that domain, such as `example.com/archive*` in the environment's `routes`, sends the archive path to the app. Links already mailed keep working, since the app still answers on its own hostname. Crawlers read your website's own `robots.txt` for the archive pages there. The app's `/llms.txt` stays on the app's hostname, and its archive link points at your website.
+    The origin archive links use, to put the archive on your website. Default: `APP_ORIGIN`. Refused unless it's a plain `http` or `https` origin with no path, and never on `example.com`, unless `PROVIDER` is `fake`. A trailing slash is dropped.
 
-`MEDIA_PUBLIC_BASE` serves images from another base URL, such as a custom domain on the image bucket. The app's own `/media` path sends `Content-Security-Policy: sandbox` and `X-Content-Type-Options: nosniff` with every file, so a file in the bucket never runs as a page. A bucket's custom domain sends neither, so add both with a Response Header Transform Rule on that hostname.
+    The app doesn't answer on that origin on its own. A Worker route on that domain, such as `example.com/archive*` in the environment's `routes`, sends the archive path to the app. Links already mailed keep working, since the app still answers on its own hostname. Crawlers read your website's own `robots.txt` for the archive pages there. The app's `/llms.txt` stays on the app's hostname, and its archive link points at your website.
 
-### `NOTIFY_FROM`
+- `MEDIA_PUBLIC_BASE` optional
 
-Used only with the `NOTIFY` binding. It must be an address on a domain set up for Cloudflare's email. Without the binding, notifications come from `FROM_ADDRESS`, through your email provider.
+    The base URL images are served from, such as a custom domain on the image bucket. Default: `APP_ORIGIN` followed by `/media`. Refused unless it's a plain `http` or `https` URL, which may have a path, and never on `example.com`, unless `PROVIDER` is `fake`. A trailing slash is dropped.
+
+    The app's own `/media` path sends `Content-Security-Policy: sandbox` and `X-Content-Type-Options: nosniff` with every file, so a file in the bucket never runs as a page. A bucket's custom domain sends neither, so add both with a Response Header Transform Rule on that hostname.
+
+- `NOTIFY_FROM` optional
+
+    The sender of notifications through Cloudflare's email. Default: `kestrel@` on the app's hostname, named Kestrel, such as `Kestrel <kestrel@newsletter.example.com>`. It's used only with the `NOTIFY` binding, and must be an address on a domain set up for Cloudflare's email.
 
 ## Secrets
 
-| Secret | What it is | Needed for |
-| --- | --- | --- |
-| `ACCESS_TEAM_DOMAIN` | your Zero Trust team domain, such as `your-team.cloudflareaccess.com`; an `https://` or trailing slash is dropped | every deployment |
-| `ACCESS_AUD` | the Access application's audience tag | every deployment |
-| `ACCESS_ALLOWED_EMAILS` | a comma-separated list of the people allowed to sign in | optional |
-| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | the IAM user's access key | SES |
-| `SNS_TOPIC_ARN` | the SNS topic the SES webhook accepts; it refuses every other topic | SES |
-| `SES_CONFIGURATION_SET` | the configuration set named on every email, so SES reports bounces and complaints; a name SES can't find in the region holds every list send until it's fixed | SES, recommended |
+Store each with `npx wrangler secret put NAME --env production`, which prompts for the value.
+
+- `ACCESS_TEAM_DOMAIN` required
+
+    Your Zero Trust team domain, such as `your-team.cloudflareaccess.com`. An `https://` or `http://` in front and a trailing slash are dropped, but anything else, such as a path or a port, is refused, since it would fail every sign-in. [Lock the dashboard with Access](../get-started/03-access.md#4-give-the-app-its-two-values) shows where to find it.
+
+- `ACCESS_AUD` required
+
+    The Access application's audience tag. It's set together with `ACCESS_TEAM_DOMAIN` or not at all: with only one, the app could verify no sign-in and would let no one into the editor, so it refuses and names the missing one.
+
+- `ACCESS_ALLOWED_EMAILS` optional
 
-`ACCESS_ALLOWED_EMAILS` applies to people only. A service token, such as the one Claude uses, carries no email, so the Access policy alone decides whether it gets in.
+    A comma-separated list of the people allowed to sign in. Without it, the app lets in anyone the Access policy allows, so it keeps the editor limited to named people if the policy is widened later. It applies to people only. A service token, the credential a script uses, carries no email, so the Access policy alone decides whether it gets in.
 
-Never set `DEV_AUTH_SECRET` on a deployed environment. It's local development's stand-in for Access, and a deployed instance ignores it anyway. The app honors it only when the environment looks like local development: `PROVIDER` is `fake`, Access isn't set up, and `APP_ORIGIN` is on `localhost` or `127.0.0.1`. A real provider, Access, or a real hostname each turns it off, and Access becomes the only way in.
+- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` required with SES
+
+    The IAM user's access key, which sends through SES.
+
+- `SNS_TOPIC_ARN` required with SES
+
+    The SNS topic the SES webhook accepts. The webhook refuses a report from every other topic, and logs `webhook.refused` naming both.
+
+- `SES_CONFIGURATION_SET` optional, recommended with SES
+
+    The configuration set named on every email, so SES reports bounces and complaints. A name SES can't find in the region holds every list send until it's fixed.
+
+- `DEV_AUTH_SECRET` never on a deployed environment
+
+    Local development's stand-in for Access. A deployed instance ignores it anyway. The app honors it only when the environment looks like local development: `PROVIDER` is `fake`, Access isn't set up, and `APP_ORIGIN` is on `localhost` or `127.0.0.1`. A real provider, Access, or a real hostname each turns it off, and Access becomes the only way in.
 
 ## Bindings and triggers
 
 Wrangler doesn't carry bindings or vars over from the top level of `wrangler.jsonc` to an environment. Each environment's block declares its own.
 
-| Setting | What it is | Default |
-| --- | --- | --- |
-| `name` | the Worker's name, such as `kestrel-production` | required |
-| `routes` | the app's hostname, attached on deploy, and any route on your website | required |
-| `workers_dev`, `preview_urls` | the Worker's `workers.dev` and preview addresses | `false` in the template |
-| `triggers.crons` | the once-a-minute schedule, `* * * * *` | required |
-| `observability` | Workers Logs, where the app's log lines land | on |
-| `d1_databases`, binding `DB` | the database: posts, subscribers, sends, and settings | required |
-| `r2_buckets`, binding `MEDIA` | the bucket for images and your logo | required |
-| `send_email`, binding `NOTIFY` | Cloudflare's email, for notifications | none |
+- `name` required
 
-### `routes`, `workers_dev`, and `preview_urls`
+    The Worker's name, such as `kestrel-production`.
 
-The template turns off the `workers.dev` addresses, so the app answers only on your hostname. That's where your Access application and any rate-limiting rule apply. Each deploy replaces the Worker's routes with the ones in the file, so add a route here, never in the dashboard.
+- `routes` required
 
-### `triggers.crons`
+    The app's hostname, attached on deploy, and any route on your website. Each deploy replaces the Worker's routes with the ones in the file, so add a route here, never in the dashboard.
 
-The schedule runs every minute. It sends whatever is due, and the notifications about it. Without it, nothing scheduled ever goes out.
+- `workers_dev` and `preview_urls` optional
 
-### `observability`
+    The Worker's `workers.dev` and preview addresses. The template sets both to `false`, so the app answers only on your hostname. That's where your Access application and any rate-limiting rule apply.
 
-Every invocation is logged, with no sampling. Sampling could drop the one minute that reports a stuck or missed send.
+- `triggers.crons` required
 
-### `NOTIFY`
+    The once-a-minute schedule, `* * * * *`. It sends whatever is due, and the notifications about it. Without it, nothing scheduled ever goes out.
 
-When declared, notifications go through Cloudflare's email instead of your provider, so they still arrive when your provider refuses your account. Local development ignores it, and sends notifications to a stand-in that delivers nothing.
+- `observability` optional
 
-## What the app refuses
+    Workers Logs, where the app's log lines land. On in the template. Every invocation is logged, with no sampling, since sampling could drop the one minute that reports a stuck or missed send.
 
-The app checks its configuration on every request. It refuses to run on one that would do the wrong thing quietly:
+- `DB` required
+
+    The `d1_databases` binding for the database: posts, subscribers, sends, and settings.
+
+- `MEDIA` required
+
+    The `r2_buckets` binding for the bucket of images and your logo.
+
+- `NOTIFY` optional
+
+    The `send_email` binding for Cloudflare's email. When declared, notifications go through it instead of your email provider, so they still arrive when your provider refuses your account. Without it, notifications come from `FROM_ADDRESS`, through your provider. Local development ignores it, and sends notifications to a stand-in that delivers nothing.
+
+## What the app refuses
 
-- `PROVIDER`, when set, must be exactly `ses`, `fake`, or `none`. A misspelling, or `SES`, is refused, never taken for another. `resend`, which earlier releases supported, is refused with a pointer to [Connect Amazon SES](../get-started/04-ses.md#switch-an-instance-that-already-sends).
-- `fake` runs only when `APP_ORIGIN` is on `localhost` or `127.0.0.1`, unless `ALLOW_FAKE_PROVIDER` is `true`. On a real hostname it would open signups whose confirmations go nowhere, and record every send as delivered. With `fake`, `ALLOW_FAKE_PROVIDER`, when set, must be `true`; every other provider ignores it.
-- `APP_ORIGIN` must be a plain `http` or `https` origin, with no path. So must `ARCHIVE_ORIGIN`, when set. `MEDIA_PUBLIC_BASE`, when set, must be a plain `http` or `https` URL, and may have a path. A trailing slash is dropped from each.
-- A real provider needs `FROM_ADDRESS`, and every secret the table marks for it. SES also needs `AWS_REGION`. `FROM_ADDRESS` must then be an email address, optionally with a display name in front, like `Name <address>`.
-- None of `APP_ORIGIN`, `ARCHIVE_ORIGIN`, `MEDIA_PUBLIC_BASE`, `SENDING_DOMAIN`, or `FROM_ADDRESS` may still be on `example.com` or a name under it, the template's placeholder. That holds with no provider connected too, since every link the app builds would name it. Only `fake` allows it.
-- `SUBREQUEST_BUDGET`, `MIN_LEAD_SECONDS`, and `SES_MAX_SEND_RATE` must be whole numbers above zero. `MIN_LEAD_SECONDS` must also be within its bounds. Any other value is refused, never adjusted. The one exception is a `SUBREQUEST_BUDGET` below 30, which is raised to 30.
-- In local development, `SIMULATE_SENDS` must be off (`off`, `0`, `false`, `no`, or empty), `not-connected` to run as a deployment with no email provider yet, or the provider a local send models: `ses` or `generic` (also `1`, `on`, `true`, or `yes`), optionally followed by `:none` for no injected failures or `:realistic`, the default. Case doesn't matter. A deployed instance ignores it.
-- `ACCESS_TEAM_DOMAIN` and `ACCESS_AUD` are set together or not at all. With only one, the app could verify no sign-in and would let no one into the editor, so it refuses and names the missing one. `ACCESS_TEAM_DOMAIN` must be your team's hostname, such as `your-team.cloudflareaccess.com`. An `https://` or `http://` in front and a trailing slash are dropped, but anything else, such as a path or a port, is refused, since it would fail every sign-in.
+The app checks its configuration on every request. It refuses to run on one that would do the wrong thing quietly, and each setting above says what it refuses. In local development, `SIMULATE_SENDS` must also be off (`off`, `0`, `false`, `no`, or empty), `not-connected` to run as a deployment with no email provider yet, or the provider a local send models: `ses` or `generic` (also `1`, `on`, `true`, or `yes`), optionally followed by `:none` for no injected failures or `:realistic`, the default. Case doesn't matter. A deployed instance ignores it.
 
 Until it's fixed, no sends go out, and each place says what its reader can act on:
 

package/docs/reference/02-sending-domain-dns.md

@@ -58,8 +58,8 @@ DMARC tells an inbox what to do with mail that fails both SPF and DKIM, and asks
 _dmarc.send.example.com.  TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
 ```
 
-- **`p=none`** is monitor mode. Inboxes report on failing mail, but deliver it as usual.
-- **`rua`** is where reports go. They arrive as attachments, usually one a day from each inbox provider.
+- `p=none` is monitor mode. Inboxes report on failing mail, but deliver it as usual.
+- `rua` is where reports go. They arrive as attachments, usually one a day from each inbox provider.
 
 Leave alignment relaxed, the default, with no `aspf=s` or `adkim=s`. With a custom MAIL FROM domain, your return path is a subdomain of your sending name, so strict SPF alignment would fail.
 

package/migrations/0013_who_acted_client.sql

@@ -0,0 +1,20 @@
+-- 0013_who_acted_client: the client a change came through (SPEC §11, Who acted).
+--
+-- Who acted is a person or a service token, plus the client the request came through, which
+-- names itself on each request in one short lowercase word (`editor`, `claude-code`). A
+-- revision already records its author (a person's email, or `service`) and an import its
+-- principal; each now records the client beside it. It is null when the request named none,
+-- and always on a service token's row, since the token already names the program.
+--
+-- What can't be recovered: no client was recorded before this, and nothing tells a person's
+-- change in the editor from one through another program, so every row a person made is read
+-- as the editor's, the one client they were offered. Those rows are rewritten once; a service
+-- token's are left as they are.
+
+ALTER TABLE post_revisions ADD COLUMN client TEXT
+  CHECK (client = lower(client) AND length(client) BETWEEN 1 AND 32);
+ALTER TABLE imports ADD COLUMN client TEXT
+  CHECK (client = lower(client) AND length(client) BETWEEN 1 AND 32);
+
+UPDATE post_revisions SET client = 'editor' WHERE author IS NOT NULL AND author <> 'service';
+UPDATE imports SET client = 'editor' WHERE principal_kind = 'human';

package/migrations/0014_send_acts.sql

@@ -0,0 +1,25 @@
+-- 0014_send_acts: who acted on a send, and when (SPEC §6, §11, Who acted).
+--
+-- A send's acts are a log: each schedule, Send now, reschedule, cancel, and Resolve adds a row with
+-- who acted (the who-acted shape as JSON: `{"kind":"human","email":…,"client":…}` or
+-- `{"kind":"service","token_id":…,"client":null}`) and when, written in the same batch as the
+-- change it records. A schedule, Send now, or reschedule keeps the fire time it set, and a Resolve
+-- the resolution it chose. The send view's latest actor of each act is read from it.
+--
+-- What can't be recovered: no act was recorded before this, so a send made before it has no
+-- rows, and reads as acted on by no one recorded.
+
+CREATE TABLE send_acts (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  send_id    TEXT NOT NULL REFERENCES sends (id),
+  act        TEXT NOT NULL CHECK (act IN ('schedule', 'send_now', 'reschedule', 'cancel', 'resolve')),
+  at         INTEGER NOT NULL,
+  actor      TEXT NOT NULL
+             CHECK (json_valid(actor) AND json_extract(actor, '$.kind') IN ('human', 'service')),
+  fire_at    INTEGER CHECK ((fire_at IS NOT NULL) = (act IN ('schedule', 'send_now', 'reschedule'))),
+  resolution TEXT
+             CHECK ((resolution IS NOT NULL) = (act = 'resolve')
+                    AND (resolution IS NULL OR resolution IN ('unsent', 'accepted')))
+) STRICT;
+
+CREATE INDEX idx_send_acts_send ON send_acts (send_id, id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "type": "module",
   "description": "An open-source, self-hosted newsletter app where you own the list and the archive. Work in the editor, or just ask Claude. Runs on Cloudflare Workers.",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "dist/public/",
     "bin/",
     "cli/",
+    "packages/kestrel/lib/",
     "template/",
     "demo/",
     "migrations/",