@kurtbruns/kestrel 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -10,6 +10,17 @@ 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.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 +433,8 @@ 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.11.0...HEAD
+[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,49 @@
 # 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.
-
-### Demo data
+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.
 
-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, or empty it again:
 
 ```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
+npm run reset
 ```
 
-### Calling the API
+When you're ready to deploy, this folder can be your instance's repository. Push it to an empty GitHub repository, then follow [Deploy the app](docs/get-started/02-deploy.md#2-sign-in-to-cloudflare) from signing in to Cloudflare.
 
-The editor is one client of Kestrel's HTTP API, and Claude is the other. Locally, mint a token to call it yourself:
+## Run your own
 
-```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
-```
+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. [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 editor's **API** tab lists every route.
+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. Both are in the editor's **Docs** tab, and an instance serves every page as Markdown for Claude to read.
 
-## 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/dist/public/dashboard/app.js

@@ -798,7 +798,7 @@ linus@example.com\r
       <div class="table-wrap"><table class="imp-sample"><thead><tr>${yo.map(k=>o`<th><code>${k}</code></th>`)}</tr></thead>
       <tbody>${f.map(k=>o`<tr>${yo.map(T=>o`<td>${k[T]??""}</td>`)}</tr>`)}</tbody></table></div>
       <p class="field-hint">Optional columns: ${_.map((k,T)=>o`${T?", ":""}<code>${k}</code>`)}.</p>
-      <div class="row imp-links"><button type="button" class="ghost" data-template="csv">Download example file (CSV)</button><a class="ghost-link" href="#/docs/import-format">Import format reference →</a></div>`}function c(){return o`<p class="imp-text">A <code>.txt</code> file with one address per line.</p>
+      <div class="row imp-links"><button type="button" class="ghost" data-template="csv">Download example file (CSV)</button><a class="ghost-link" href="#/docs/your-list/the-file-format">Import format reference →</a></div>`}function c(){return o`<p class="imp-text">A <code>.txt</code> file with one address per line.</p>
       ${_t(bo,o`${ho.replace(/\r\n/g,`
 `).trim()}`,ho)}
       <p class="imp-text">Next you’ll say what they are: subscribed (the default), unsubscribed, or bounced.</p>