@kurtbruns/kestrel 1.12.0 → 1.14.0

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

@@ -10,6 +10,8 @@ Kestrel won't save a template without `{{ .Post.Body }}` and `{{ .Email.Unsubscr
 
 Wrap a part in `{{ if .IsEmail }}` and `{{ end }}` to keep it off each post's public page. The starting templates do this with the unsubscribe link, the View in browser link, and the mailing address.
 
+A region is a marked part, not a general `if`: `.IsEmail` is its only condition, there's no `else`, and regions don't nest. Kestrel won't save a template with a region left open, an `{{ end }}` with nothing to close, another condition, or `{{ .Post.Body }}` inside a region, which would leave the post's page empty. Keep each region's two tags inside the same element, outside any attribute, and not loose between a table's rows or cells, where the browser would move what's inside. A template that breaks that rule saves, but every email shows the built-in template instead until it's fixed, and the preview and a test say so. An unsubscribe link inside a region is fine, since every email still carries it.
+
 ## Variables
 
 A variable is replaced with its value in each email. Type it exactly as shown, or it renders as empty.
@@ -31,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.
-- The app warns before a send to more than 5,000 recipients (fewer on a day with imports), and on an import plan that, with the day's earlier imports, would use most of a day's writes. Either may use up D1's daily allowance of 100,000 rows written, which stops the app until midnight UTC ([As your list grows](../guides/09-as-your-list-grows.md)). Neither warning stops you. Above the default, neither appears.
+    - 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.
+    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/0012_unsubscribe_cause.sql

@@ -0,0 +1,139 @@
+-- 0012_unsubscribe_cause: each mark has one owner (SPEC §7).
+--
+-- The consent state is the person's, and now keeps why they left: their own unsubscribe
+-- (`reader`), the publisher on their request (`publisher`), a complaint about the mail
+-- (`complaint`), an erasure (`erased`), or a list brought from elsewhere that says they left
+-- with no cause (`import`). The suppression is only the sender's side: a bounce, an import's
+-- bounce, or a block. A complaint and an erasure, which were suppressions, become unsubscribes
+-- with their cause, and the suppression reasons that held them go.
+--
+-- `unsubscribe_cause` is set while a subscriber has left and not confirmed since: on every
+-- unsubscribed row, and on a pending row that left and signed up again, where it is kept
+-- until they confirm, as `unsubscribed_at` is. An erased subscriber holds only the address
+-- and when, so its unsubscribe token, origin, and opt-in may now be empty, and only on such
+-- a row. A column can be neither added with those rules nor made nullable in place, so the
+-- table is rebuilt, copying every row once, with its indexes made again.
+--
+-- What can't be recovered:
+-- - Every unsubscribe before this reads as the reader's own. The record never said whether
+--   the reader, the publisher, or an import unsubscribed someone, so `reader` stands for all.
+-- - An erasure that found a bounce, a complaint, or a block already on the address kept that
+--   one and left no trace of itself, so its address migrates as that suppression alone (a
+--   complaint's as unsubscribed by a complaint), with no subscriber saying it was erased. Its
+--   bounce or block keeps the detail it had.
+-- - An erasure's marker on an address with a confirmed or unsubscribed subscriber came from an
+--   import that said the address was erased. The person is now unsubscribed by an erasure and
+--   their record stripped, as an erasure here would. A pending subscriber with the marker
+--   signed up again after it, so they stay pending, keeping that they left by an erasure until
+--   they confirm.
+-- - A complaint suppression becomes an unsubscribe whatever the subscriber's state, as every
+--   complaint now is. An address it held with no subscriber is recorded as one, unsubscribed
+--   by a complaint, so the publisher still can't add it back by hand. Nobody was erased, so it
+--   gets an unsubscribe token, with how they joined recorded as unknown.
+
+CREATE TABLE subscribers_next (
+  id                 TEXT PRIMARY KEY,
+  email              TEXT NOT NULL UNIQUE CHECK (email = lower(email)),
+  status             TEXT NOT NULL DEFAULT 'pending'
+                       CHECK (status IN ('pending', 'confirmed', 'unsubscribed')),
+  confirm_token      TEXT UNIQUE,
+  confirm_sent_at    INTEGER,
+  confirm_attempt_at INTEGER,
+  unsub_token        TEXT UNIQUE,
+  created_at         INTEGER NOT NULL,
+  confirmed_at       INTEGER,
+  unsubscribed_at    INTEGER,
+  origin             TEXT DEFAULT 'kestrel'
+                       CHECK (origin = lower(origin) AND length(origin) BETWEEN 1 AND 40),
+  opt_in             TEXT DEFAULT 'double' CHECK (opt_in IN ('double', 'single', 'unknown')),
+  consent_evidence   TEXT CHECK (consent_evidence IS NULL OR json_valid(consent_evidence)),
+  import_id          TEXT REFERENCES imports (id),
+  unsubscribe_cause  TEXT
+                       CHECK (unsubscribe_cause IN ('reader', 'publisher', 'complaint', 'erased', 'import')),
+  CHECK (status <> 'unsubscribed' OR unsubscribe_cause IS NOT NULL),
+  CHECK (status <> 'confirmed' OR unsubscribe_cause IS NULL),
+  CHECK ((unsub_token IS NOT NULL AND origin IS NOT NULL AND opt_in IS NOT NULL)
+         OR (status = 'unsubscribed' AND unsubscribe_cause = 'erased'))
+) STRICT;
+
+-- Every unsubscribe before this reads as the reader own, as does a pending row that left.
+INSERT INTO subscribers_next (id, email, status, confirm_token, confirm_sent_at, confirm_attempt_at,
+                              unsub_token, created_at, confirmed_at, unsubscribed_at, origin, opt_in,
+                              consent_evidence, import_id, unsubscribe_cause)
+SELECT id, email, status, confirm_token, confirm_sent_at, confirm_attempt_at,
+       unsub_token, created_at, confirmed_at, unsubscribed_at, origin, opt_in,
+       consent_evidence, import_id,
+       (SELECT 'reader' WHERE status = 'unsubscribed' OR (status = 'pending' AND unsubscribed_at IS NOT NULL))
+  FROM subscribers;
+
+DROP TABLE subscribers;
+ALTER TABLE subscribers_next RENAME TO subscribers;
+CREATE INDEX idx_subscribers_status ON subscribers (status);
+CREATE INDEX idx_subscribers_created ON subscribers (created_at);
+
+-- A complaint is leaving: its subscriber is unsubscribed by it, the stronger cause. One who
+-- had not left leaves when the complaint came, and one who had keeps when they left.
+UPDATE subscribers
+   SET unsubscribed_at = (SELECT p.created_at FROM suppressions p WHERE p.email = subscribers.email)
+ WHERE status <> 'unsubscribed' AND unsubscribed_at IS NULL
+   AND email IN (SELECT email FROM suppressions WHERE reason IN ('complaint', 'import_complaint'));
+
+UPDATE subscribers SET status = 'unsubscribed', unsubscribe_cause = 'complaint'
+ WHERE email IN (SELECT email FROM suppressions WHERE reason IN ('complaint', 'import_complaint'));
+
+INSERT INTO subscribers (id, email, status, unsub_token, created_at, unsubscribed_at, origin, opt_in, unsubscribe_cause)
+SELECT lower(hex(randomblob(16))), p.email, 'unsubscribed', lower(hex(randomblob(32))), p.created_at, p.created_at,
+       'unknown', 'unknown', 'complaint'
+  FROM suppressions p
+ WHERE p.reason IN ('complaint', 'import_complaint')
+   AND NOT EXISTS (SELECT 1 FROM subscribers s WHERE s.email = p.email);
+
+-- An erasure marker: the person is unsubscribed by the erasure, their record holding only
+-- the address and when, with both tokens and how they joined discarded.
+UPDATE subscribers
+   SET status = 'unsubscribed',
+       unsubscribe_cause = 'erased',
+       created_at = (SELECT p.created_at FROM suppressions p WHERE p.email = subscribers.email),
+       unsubscribed_at = (SELECT p.created_at FROM suppressions p WHERE p.email = subscribers.email),
+       confirmed_at = NULL,
+       confirm_token = NULL,
+       confirm_sent_at = NULL,
+       confirm_attempt_at = NULL,
+       unsub_token = NULL,
+       origin = NULL,
+       opt_in = NULL,
+       consent_evidence = NULL,
+       import_id = NULL
+ WHERE status IN ('confirmed', 'unsubscribed')
+   AND email IN (SELECT email FROM suppressions WHERE reason = 'erased');
+
+UPDATE subscribers
+   SET unsubscribe_cause = 'erased',
+       unsubscribed_at = COALESCE(unsubscribed_at,
+                                  (SELECT p.created_at FROM suppressions p WHERE p.email = subscribers.email))
+ WHERE status = 'pending'
+   AND email IN (SELECT email FROM suppressions WHERE reason = 'erased');
+
+INSERT INTO subscribers (id, email, status, unsub_token, created_at, unsubscribed_at, origin, opt_in, unsubscribe_cause)
+SELECT lower(hex(randomblob(16))), p.email, 'unsubscribed', NULL, p.created_at, p.created_at,
+       NULL, NULL, 'erased'
+  FROM suppressions p
+ WHERE p.reason = 'erased'
+   AND NOT EXISTS (SELECT 1 FROM subscribers s WHERE s.email = p.email);
+
+-- The suppression keeps only the sender side. A STRICT table CHECK cannot be altered, so
+-- it is rebuilt with the three reasons left, and the rows the others held, now carried by
+-- their subscribers, are left behind.
+CREATE TABLE suppressions_next (
+  email      TEXT PRIMARY KEY CHECK (email = lower(email)),
+  reason     TEXT NOT NULL CHECK (reason IN ('bounce', 'manual', 'import_bounce')),
+  detail     TEXT,
+  created_at INTEGER NOT NULL
+) STRICT;
+
+INSERT INTO suppressions_next (email, reason, detail, created_at)
+  SELECT email, reason, detail, created_at FROM suppressions
+   WHERE reason IN ('bounce', 'manual', 'import_bounce');
+
+DROP TABLE suppressions;
+ALTER TABLE suppressions_next RENAME TO suppressions;

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.12.0",
+  "version": "1.14.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",

package/template/README.md

@@ -22,6 +22,8 @@ Open the editor at http://localhost:8787/dashboard/. Email goes to a stand-in th
 | `npm run seed`, `npm run reset` | Loads the demo publication into the local app, or empties it |
 | `npm run sync-migrations` | Copies the installed release's migrations into `migrations/` |
 | `npm run check-context` | Compares the Claude files in `.claude/` with the installed release's |
+| `npx -p @kurtbruns/kestrel kestrel login <url>` | Signs Claude Code in to the deployed instance as you, in your browser |
+| `npx -p @kurtbruns/kestrel kestrel api <method> <path>` | Calls the API as you, via Claude Code (`--local` for the local app); `--list` lists the routes and `help <method> <path>` describes one |
 | `npx wrangler deploy --env production` | Deploys the instance |
 | `npx wrangler d1 migrations apply DB --remote --env production` | Applies new migrations to the production database |