@kurtbruns/kestrel 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -10,6 +10,67 @@ To move a running instance from one version to another, follow [Upgrade to a new
 
 <!-- Add entries under Added / Changed / Fixed / Breaking. One operator-facing line each; see .claude/rules/changelog.md. Upgrade steps (a migration, a new setting) go once, in the Upgrading paragraph, never on an entry. -->
 
+## [1.12.0] - 2026-10-16
+
+**Upgrading from 1.11.0.** Five database migrations, which `npm run sync-migrations` brings in: apply them before you deploy with `npx wrangler d1 migrations apply DB --remote --env production` (and `--local` for local development). `0007_sends_progress_at` adds a column recording when each send last handed anyone off, and writes no rows. `0008_notifications_sandbox` rebuilds the small notifications table to admit a new kind, copying its rows once. `0009_post_email_only` adds each post's listing, reading every existing post as listed in the archive, so the archive shows what it did before; it adds a column with a default and rewrites no rows. `0010_unlisted_links` gives every post its unlisted link, and records that every send made before it links its archive address, so those addresses keep answering whatever the post's listing; a send scheduled between the migration and the deploy counts as one made before. It writes each post row once. `0011_sends_render_warnings` adds a column keeping what the render found wrong with each scheduled email, reading every earlier send as having found nothing; it adds a column with a default and rewrites no rows. Run `npm run check-context` in your instance's repository: this release changes the operator's Claude context, and a copy you've edited is merged by hand. An instance verified with an earlier release has its test post in the archive: open it under **Sent** and select **Remove from archive…**. Two API changes can break a script of yours, listed under Breaking: one that reads a send's halt `cause` reads new values, and one that sets a slug by hand handles a 409 `slug_taken` by choosing another, where it used to get a numbered slug.
+
+### Breaking
+
+- A send's halt `cause`, on the API and in the `refused` condition, takes new values so each names its own fix: `opt_in`, `sending_pool`, `unsupported`, `mail_from`, `sandbox`, `paused`, `set_paused`, and this send's own `content` and `invalid_request`. `suspended` now means only an account AWS shut down (a paused account or configuration set is `paused` or `set_paused`), and an SES MAIL FROM refusal is `mail_from` rather than `sender`.
+- A slug sent by hand (`slug` on `POST /api/posts`, `PUT /api/posts/:id`, `PUT /api/posts/:id/settings`, or a schedule) that another post holds is now refused with a 409 `slug_taken`, and one that isn't lowercase words joined by single hyphens with a 400 `slug_invalid`, where before it was numbered or rewritten silently. A change to a sent post's slug is a 409 `slug_permanent` (SPEC §4).
+
+### Added
+
+- `GET /api/whoami` names a service token by its Client ID, as `tokenId`, so you can check which token Claude is using, and Resolve's note on a wedged send names the token that resolved it. Each service call is logged as `auth.service`, and an Access sign-in that is neither a person nor a service token as `auth.unidentified` (warn), with the names of the claims it carried and never their values (SPEC §11, §12).
+- The publisher is emailed, at most once a day and naming no one, when the SES sandbox refuses a signup's confirmation, since the reader was told a link is on its way (SPEC §7, §8).
+- A recent send with no delivery, bounce, or complaint receipt at all an hour after it went out says so, amber, on its record and the dashboard, as `no_receipts` in its conditions: SES's reports are probably not reaching the webhook, so its bounces and complaints suppress no one. Connect Amazon SES now sets a longer SNS retry policy on the topic, and mentions a dead-letter queue as optional (SPEC §8).
+- **Email only**: a post can be sent to subscribers without being listed in the public archive or on the home page, and its archive address answers nothing (SPEC §5). Uncheck **Include in archive** in the editor's new **Post settings**, or in the Schedule, Send now, or Edit schedule dialog, and change it later on a sent post's page (**Remove from archive…**, which takes its archive address down while keeping it the post's, or **Add to archive…**; both ask first). Its page answers at the email's unlisted link and asks search engines not to index it. A draft's head and the Drafts and Sent lists mark it with an envelope and "Email only" in muted text, a scheduled post's banner says where it's going, and a post in the archive carries no mark. The API carries it as `email_only` on posts and sends, on the schedule and Send now bodies, and through `PUT /api/posts/:id/settings`, which also sets the slug; a reschedule still moves only the time. Every post the API answers carries its two addresses, absolute, as `archive_url` and `unlisted_url`, with `published_at` (when its send started) and `archive_live` (whether the archive address shows it now).
+- **Unlisted links**: every email's "view in browser" link is now the post's own permanent link, `/email/<token>` on the app's origin, in place of its archive address (SPEC §5). It forwards to the archive page while the post is listed and is the page while it's email only, so changing `ARCHIVE_BASE_PATH` or moving the archive no longer breaks links in emails sent from now on. Emails sent before keep linking their archive address, which keeps working. The API carries `unlisted_token` on a post and `links.unlisted` on a send.
+- The operator's Claude context tells Claude to say whether a post will be in the archive, and at which address, before scheduling or sending it; to send it as email only only when the publisher asks; and to confirm before taking a sent post out of the archive or putting it in, which the API doesn't ask about the way the dashboard does. `npm run check-context` offers the change to an existing instance.
+- The dashboard keeps setup's steps after the first post, as a **Finish setting up** card, until the first post listed in the archive goes out. Its last step, **Publish your first post** (formerly Write your first post), is the one that clears it, done once a post that goes to subscribers and onto the site starts sending, so a test send that's email only, like Verify it works' own, leaves the publisher their guided start. **Check your setup** is guidance and never shows as done.
+
+### Changed
+
+- The operator's Claude context: on `remake_required`, Claude now tells the publisher which scheduled posts a template or identity change would re-make and when each fires, and confirms only on their word, then tests each re-made send. Re-making a frozen email is the publisher's deliberate act (SPEC §2), which the editor asks about and the API leaves to the client.
+- A post save refused as 409 `stale_revision` now carries the post as it stands and its `markdown`, so a client can re-apply its change without reading the post again.
+- A route that takes no body (a post's preview, cancelling a send, and the like) now accepts a request declaring `Content-Type: application/json` with an empty body, which HTTP helpers send by habit, instead of refusing it with 415. A body sent to such a route is still refused.
+- Each SES refusal gets its own advice, checked against AWS's docs, and says who makes the fix: a paused configuration set, a paused or suspended account, a custom MAIL FROM domain's MX record, a missing dedicated IP pool, an account not signed up for SES, and the sandbox are told apart, and a quota spent in the sandbox points to production access. The line now says "No one has been marked unsent because of this", which stays true on a send with readers unsent for their own reasons. Troubleshooting lists each refusal with its fix (SPEC §12).
+- A rate limit that refuses the first request of three retries in a row shows in amber, on the dashboard and the send's page, that `SES_MAX_SEND_RATE` is set above your SES account's rate, rather than reading as an outage with nothing to do (SPEC §12).
+- The operator's Claude context: the sandbox caution says a send holds in the sandbox, mailing only verified addresses, rather than marking the rest unsent.
+- A send is flagged as **in flight too long** only when it has handed off no one for 30 minutes and nothing else explains it (a provider refusing the account, an outage it is waiting out, or a send awaiting Resolve), rather than 30 minutes after it started. A large send going out at your SES rate on Workers Free is no longer flagged, emailed about, or logged as `send.stuck`, however long it takes; one the sweep has stopped moving still is, shows no time to finish, and its email and message say nothing has gone out and why that points at the sweep (SPEC §12).
+- A post's archive address moves from beside the subject into **Post settings** (top right of the editor), which save nothing until **Save**: one field with the base fixed and only the slug to type, following the subject until you do. A slug that's malformed or another post's is now refused with a message rather than numbered behind your back, and a subject whose slug another post has takes the next number (`spring-update-2`) and says so. The Schedule, Send now, and Edit schedule dialogs show the same settings under the time and apply them with the act, and a scheduled post's banner names where it's going ("Sends by email and publishes at <its archive address>" or "Sends by email only"). The web version's strip now says only that the page isn't public yet. The address is fixed once the post starts sending (SPEC §4). The API refuses a bad slug as `slug_invalid` or `slug_taken`, a change to a sent post's as `slug_permanent`, and answers `subject_slug_held` on a post's read, saves, and settings changes when the subject's address is another post's and the post got a number.
+- A post's archive page is now sent with `Cache-Control: no-cache` (it was cached for an hour), so taking a post out of the archive takes effect at once. Behind a CDN, more of those requests reach the Worker.
+- A sent post's page is split into **The post** and **Delivery** (the record, unchanged). The post shows its link as one field with **Copy** and **Open ↗**, and below it whether the post is in your archive or email only, with **Remove from archive…** or **Add to archive…**.
+- A scheduled send's **Reschedule** is now **Edit schedule**, on its card under Sent and on the editor's banner: one dialog for the send time and the post's settings, with **Save**, which saves either or both, the settings first, and a toast that says whether the send was rescheduled or only its settings saved. The settings alone can be saved up to the send time.
+- A sent post's recipient list opens on **All** rather than **Failures**, its switch now reading **All | Delivered | Failures**. The failures are still counted in the tiles above it, one switch away.
+- Verify it works sends its test post as **Email only**, and ends by erasing the SES simulator addresses and any test subscriber that won't be a reader.
+- The demo publication (`npm run seed`) opens with the operator's own test send, made as Verify it works makes one: email only, to one test address, before the list came in. It shows under **Sent** with the **Email only** label, and the archive leaves it out. Its scheduled post, **A quick note**, says how to send a post as email only.
+
+### Fixed
+
+- A scheduled post keeps its render warnings, such as an image the post references but never uploaded: scheduling and Send now answer with them, and a preview or test of the scheduled email reports them, where before a test of it always came back clean. A template or identity change that re-makes the email keeps the new render's (SPEC §5).
+- An SES refusal of the key's signature that AWS answers with a 400 (an incomplete or invalid signature, an expired request, a missing token) now holds the send as a credentials refusal with no reader consumed, as a wrong key already did, instead of marking each reader failed for good (SPEC §12).
+- In the SES sandbox, a list send no longer marks every unverified reader unsent and finishes quietly. It mails your verified addresses, holds with "The provider is refusing the account" and advice to request production access, and goes to everyone else once AWS grants it, mailing no one twice. A reader whose address contains your From address is no longer taken for an unverified sender, which held every send (SPEC §12).
+- An SES answer that isn't a reader's fault no longer marks a batch of readers unsent. A request SES didn't receive whole or a limit is retried, a refusal of the email itself holds that send for you with SES's words without holding other posts, an invalid batch that names one reader refuses only that reader, the same failure on several readers of one request with none taken holds the batch, and an answer Kestrel doesn't recognize waits for **Resolve…** rather than being guessed. A malformed address on an imported list is left out of the request and marked unsent alone (SPEC §10, §12).
+- A batch SES answers with a server error, or aborts, is no longer sent again, since AWS says such an answer can follow emails it already took: its readers wait for **Resolve…** (SPEC §10).
+- When SES refuses a badly signed request and echoes back what it was sent, the access key ID, the signature, and any session token are now removed from its words before they reach a held send's page, the email about it, a failed delivery's record, or the log (SPEC §9, §12).
+- SES's bounces and complaints are no longer lost when the webhook can't fetch SNS's signing certificate: it answers 503, so SNS retries, where before it refused the message as forged and SNS discarded it for good. A message whose SNS signature doesn't hold, or from another SNS topic, is still refused, now logged as `webhook.refused` at error with the topic that came and the one expected; a request with no SNS signature at all is refused without one (SPEC §10, §12).
+- A test send that isn't sent says why, in the editor and on the API (`not_sent`): your provider's own words and the fix where it's known, so a test the SES sandbox refuses for an unverified address no longer just says to send again. A test your provider never answers says it may have arrived, rather than reading as a server error, and both are logged as `test.refused` and `test.unknown` (SPEC §5, §12).
+- A send that SES keeps partly refusing, as a daily quota frees up a few at a time, is one refusal until SES takes a batch with nothing refused: you're emailed about it once, its page keeps the time the refusal began, and its retries keep spacing out up to an hour apart instead of starting over every few minutes. The readers SES took are still recorded as sent at once, and the rest wait with no retry spent (SPEC §12).
+- A post that comes due while another send is held by SES refusing the account, or by an outage, now waits with it instead of firing: it asks SES nothing, reads as held with the same next retry, and goes out once SES answers. You're emailed once per refusal rather than once per send, and an outage where SES doesn't answer no longer leaves a batch of each new post waiting for Resolve. A held post goes to your list as it stands when it actually goes out (SPEC §6, §12).
+- A send paused for a provider outage reads **Backing off**, with when it next retries, on its page, the Sent list, and the dashboard, and shows no time to finish, even while a batch the provider never answered waits for Resolve. Before, it read as sending normally for up to an hour (SPEC §12).
+
+## [1.11.0] - 2026-10-15
+
+**Upgrading from 1.10.0.** No database migrations. Run `npm run check-context` in your instance's repository: `/migrate-list` now reads the import format from "Bring your existing list".
+
+### Changed
+
+- The Publishing docs are reorganized around what a publisher has to do or decide. Their sections are **Set up your publication**, **Go further** (Edit your email template, Working with Claude), and **Rules and troubleshooting** (Sending rules, Troubleshooting). Write and send a post covers scheduling too, Troubleshooting replaces After a send with each problem a send or an import reports, in its own words, and the import format is the last section of Bring your existing list, which opens with when to upgrade to Workers Paid.
+- In Self-hosting, **As your list grows** is its own guide (raising Amazon SES limits and upgrading to Workers Paid, with how long a send takes after each), Verify it works ends by checking SES production access, and Go live hands over to the publisher, including letting them sign in through Access. The pages call whoever writes the newsletter the publisher. Try Kestrel locally first moves into the README, now the front page for someone deciding whether to run Kestrel, and working on Kestrel's own source moves to CONTRIBUTING.md.
+- The Markdown of each removed page (`import-format`, `scheduling-and-sending`, `after-a-send`, `try-locally`) still answers at its old address, with the page that now holds its content. The import screen's **Import format reference →** opens the file format section.
+- The operator's Claude context: `/migrate-list` reads the import format from `GET /api/docs/your-list.md`, since the separate import format page is gone.
+
 ## [1.10.0] - 2026-10-14
 
 **Upgrading from 1.9.0.** No database migrations. Run `npm run check-context` in your instance's repository: this release changes the operator's Claude context (a new `/migrate-list` skill, and rules for erasing, for choosing between unsubscribing and blocking, and for reading the docs as Markdown), and a copy you've edited is merged by hand. Three API changes can break a script of yours, listed under Breaking. One that adds suppressions sends `reason: "manual"` or none, reads what was stored from the answer's `suppression`, and takes a 200 with `added: false` as already suppressed. One that clears suppressions takes a 409 `erasure_marker` on an erased address as final. One that reads `GET /api/docs` reads `sets` in place of `landing`.
@@ -422,7 +483,9 @@ The first tagged release: a self-contained newsletter app on a Cloudflare Worker
 - A build-version stamp: every instance reports its version, commit, and build time, read-only in the editor and at `GET /api/version`.
 - This changelog and a semantic-versioning release process.
 
-[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.10.0...HEAD
+[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.12.0...HEAD
+[1.12.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.12.0
+[1.11.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.11.0
 [1.10.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.10.0
 [1.9.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.9.0
 [1.8.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.8.0

package/README.md

@@ -1,59 +1,48 @@
 # Kestrel
 
-Kestrel is a newsletter app you run yourself on Cloudflare. You write a post in Markdown, preview it exactly as the email, and send it to a double-opt-in list. The list, the consent, the record of every send, and a permanent archive of every post stay with you. Bring an existing list in, and take the whole list out, in one documented format. Write in the editor by hand, or with Claude through the same API.
+Kestrel is an open-source newsletter app you run yourself, on Cloudflare and Amazon SES. You own the list, the proof each reader opted in, the record of every send, and a permanent archive of every post.
+
+You write in Markdown, preview the exact email, and schedule it with a window to cancel. Bring your list from another service, and take it out whenever you like. Work in the editor, or ask Claude to do it through the same API.
 
 See [getkestrel.dev](https://getkestrel.dev) to learn more about Kestrel.
 
-## Run your own
+## Try it locally
+
+You can run Kestrel on your own computer to look around, with [Node.js](https://nodejs.org/) 22 or later. It needs no Cloudflare account, and email goes to a stand-in, so nothing reaches a real inbox.
 
-Kestrel installs from npm as [`@kurtbruns/kestrel`](https://www.npmjs.com/package/@kurtbruns/kestrel). Your instance lives in a small repository of your own, which holds its settings and names the release it runs:
+In an empty folder, write a new instance and install it:
 
 ```bash
 npx @kurtbruns/kestrel init
+npm install
 ```
 
-To look around before you deploy, [Try Kestrel locally first](docs/guides/08-try-locally.md) runs it with demo content and no Cloudflare account. [Get started](docs/README.md#get-started) takes you from an empty repository to a live newsletter, and [Upgrade to a new release](docs/guides/07-upgrade.md) moves an instance to a newer one.
-
-The docs are two sets, one per job. [Self-hosting](docs/README.md) is for whoever deploys and runs Kestrel. [Publishing](docs/publishing/README.md) is for whoever writes and sends the newsletter: setting up the publication, the list, writing, sending, and the rules a newsletter keeps. Both are in the editor's **Docs** tab, which opens on Publishing, and an instance serves every page as Markdown for Claude to read.
-
-## Work on Kestrel
-
-This repository is Kestrel's source. To run it on your computer, with [Node.js](https://nodejs.org/) 22 or later:
+Copy the local settings, and start the app:
 
 ```bash
-npm install
 cp .dev.vars.example .dev.vars
 npm run dev
 ```
 
-Open the editor at http://localhost:8787/dashboard/. There's nothing to sign in with locally, and email goes to a stand-in that never reaches a real inbox. `.dev.vars.example` explains each local setting, including how the stand-in mimics SES on a send.
+The first time, it asks you to confirm the local database's migrations. Then open http://localhost:8787/dashboard/, with nothing to sign in with. If port 8787 is taken, the `Ready on` line shows the one it picked.
 
-### Demo data
-
-The app starts empty. To explore it with content, load **Field Notes**, a demo publication kept as Markdown in [`demo/`](demo/):
+In a second terminal, load a demo publication with posts, subscribers, and past sends:
 
 ```bash
-npm run seed                          # load the demo
-npm run simulate-send -- --in 90s     # schedule a send and print a link to watch it go out
-npm run reset                         # back to an empty instance
+npm run seed
 ```
 
-### Calling the API
-
-The editor is one client of Kestrel's HTTP API, and Claude is the other. Locally, mint a token to call it yourself:
+To start over, reset the app to the state a new instance starts in: no posts, subscribers, or settings, with the first-run dashboard and its setup checklist:
 
 ```bash
-TOKEN=$(curl -s http://localhost:8787/api/dev/token?kind=service | jq -r .token)
-curl -H "Authorization: Bearer $TOKEN" http://localhost:8787/api/posts
+npm run reset
 ```
 
-The editor's **API** tab lists every route.
+When you're ready to deploy your own instance, see the [setup guide](https://getkestrel.dev/docs/), which contains instructions for deploying and running Kestrel.
 
-## Going further
+## Contributing
 
-- **What Kestrel guarantees:** [`docs/SPEC.md`](docs/SPEC.md). How the admin UI is built: [`docs/DESIGN.md`](docs/DESIGN.md).
-- **Working on the code:** [`.claude/CLAUDE.md`](.claude/CLAUDE.md) has the commands, conventions, and module boundaries.
-- **Releases:** [`CHANGELOG.md`](CHANGELOG.md).
+To work on Kestrel's own source, see [CONTRIBUTING.md](CONTRIBUTING.md). Releases are recorded in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

package/cli/reset.mjs

@@ -20,4 +20,6 @@ export async function resetCommand(argv) {
     "[reset] done — the local database is a fresh install (no posts, subscribers, or settings).",
   );
   console.log(`  view the first-run dashboard: ${url || `${base}/dashboard/`}`);
+  // An open editor tab holds the settings it read when it loaded (the old name and logo).
+  console.log("  reload any dashboard tab already open, so it reads the fresh install.");
 }

package/cli/seed.mjs

@@ -142,4 +142,6 @@ export async function seedCommand(argv) {
   for (const a of summary.urls.archive) {
     console.log(`    archived post: ${a}`);
   }
+  // An open editor tab holds the settings it read when it loaded (the old name and logo).
+  console.log("  reload any dashboard tab already open, so it reads the new publication.");
 }

package/demo/README.md

@@ -6,7 +6,7 @@ Everything `npm run seed` loads into a local dev server, apart from the subscrib
 - **`posts/`**: one folder per post, a page bundle: the post is `index.md`, and any image it shows sits beside it (`1-the-hovering-hunter/kestrel.webp`). The post refers to the image by its filename, as in `![…](kestrel.webp)`, so the link resolves when you preview the Markdown, and the seed attaches the file to that post. The number in a folder's name sets its place: sent posts go out oldest first in that order, and a post's id (and so its editor URL) follows its position.
 - **`field-notes-logo.png`**: the publication logo, named by `publication.md`.
 
-The worker bundles the Markdown files (the `rules` entry in `wrangler.jsonc`) and parses them in `src/dev/demo.ts`, which lists each post's folder; add a post by adding its folder and one line there. `npm run dev` watches this folder, so an edit here is in the next seed. `cli/seed.mjs` uploads the images through the running dev server, which stores them in local R2. The subscribers, the four completed sends, and the scheduled send's fire time come from the timeline in `src/dev/seed.ts`.
+The worker bundles the Markdown files (the `rules` entry in `wrangler.jsonc`) and parses them in `src/dev/demo.ts`, which lists each post's folder; add a post by adding its folder and one line there. `npm run dev` watches this folder, so an edit here is in the next seed. `cli/seed.mjs` uploads the images through the running dev server, which stores them in local R2. The subscribers, the four completed sends, and the scheduled send's fire time come from the timeline in `src/dev/seed.ts`. The first post, `0-test-email`, is the operator's test send, made the way Verify it works has them make one: email only, to their own second address alone, before the list came in. That address subscribed just before it and unsubscribed just after, so it's in no later send.
 
 ## Front matter
 
@@ -28,8 +28,10 @@ A post:
 |---|---|---|
 | `subject` | yes | The subject line, which is also the post's title in the list. |
 | `slug` | yes | The post's path in the archive. |
-| `status` | yes | `sent`, `scheduled`, or `draft`. The seed timeline has four completed sends, so at most four posts can be `sent`. |
+| `status` | yes | `sent`, `scheduled`, or `draft`. The seed timeline has four completed sends, so at most four posts can be `sent` without `sent_to`. |
 | `edited` | no | Drafts only: when the draft was last edited, as `2 days ago`. |
+| `email_only` | no | Sent or scheduled posts: `true` to send it without listing it in the archive or on the home page. |
+| `sent_to` | no | Sent posts only: a test send to just these addresses, comma-separated, before the list is imported, instead of a timeline send. Keep them on `.example`. |
 
 ## The images
 

package/demo/posts/0-test-email/index.md

@@ -0,0 +1,13 @@
+---
+subject: Test email
+slug: test-email
+status: sent
+email_only: true
+sent_to: proof@fieldnotes.example
+---
+
+# Test email
+
+This is the test send that proved Field Notes works end to end, before its list came in: subscribing, confirming, scheduling, and a real send landing in a real inbox.
+
+It went out as email only, so it isn't in the archive or on the home page. Its web version still opens from the email, which is how you're reading this.

package/demo/posts/5-a-quick-note/index.md

@@ -8,4 +8,6 @@ status: scheduled
 
 Not every issue has to be long. Sometimes the best newsletter is a quick note that there's something new to read, watch, or listen to.
 
+A note like this one doesn't always belong in your archive. To send it as email only, uncheck **Include in archive** in its Post settings.
+
 Thanks for reading Field Notes.