@kurtbruns/kestrel 1.10.0 → 1.11.0

package/docs/publishing/06-troubleshooting.md

@@ -0,0 +1,74 @@
+# Troubleshooting
+
+When a send needs you, its page and the dashboard's health block say so in a red or amber line. Red needs you to act, and amber is worth a look. Find the line's words below for what it means and what to do.
+
+**Set a notifications address, so a problem reaches you without your watching.** Set it under **Settings → Notifications**, in **Send notifications to**. With none set, Kestrel emails you nothing. [Notifications](06-troubleshooting.md#notifications), below, lists what you're told.
+
+## A send is waiting or held
+
+A problem with your email provider never marks anyone unsent. The send waits where it is, and carries on from there once the problem clears.
+
+- **"The provider is refusing the account".** Your provider won't take mail from your account, and its own words follow, with the fix they point to. The fix is almost always in your Amazon SES account or Kestrel's deployment, and the message names it. A spent daily sending quota frees up within a day, and you can ask AWS for a higher one, as [As your list grows](../guides/09-as-your-list-grows.md) describes.
+- **"No email provider is connected".** The send is held until one is connected ([Connect Amazon SES](../get-started/04-ses.md)), and goes out once it is.
+- **"The provider is unavailable".** An outage or a rate limit on the provider's side. The send retries on its own, so there's nothing to do.
+- **"Still sending … after it started".** A send is taking longer than expected, and may be retrying. If the line stays, read the app's logs, as [Read the logs](../get-started/05-verify.md#7-read-the-logs) describes.
+- **"The fire time passed … and the send has not started".** The Cloudflare Cron Trigger that starts sends on time isn't running. The send goes out as soon as it runs again. Check the Worker's trigger, as [`triggers.crons`](../reference/01-configuration.md#triggerscrons) describes.
+- **"The provider never answered for …".** Rarely, Kestrel can't tell whether your provider took some emails, and sending again could mail those readers twice. **Resolve…** on the send's page asks you to decide. **Assume not sent** is the safe default: those readers may miss this post, but get your next one. Choose **Assume sent** only when you know they got it.
+
+## Before a send
+
+- **"The template or publication details changed this email's look after your last test".** Send a new test of the post, since your last one no longer shows what goes out.
+- **The daily database writes warning.** On Cloudflare's free Workers plan, a large send may use up the day's writes, and then the app stops working until midnight UTC. [Bring your existing list](01-your-list.md#limits) explains the limit, and when to upgrade to Workers Paid.
+
+## Reading a send's record
+
+A send's page becomes its permanent record once it finishes. Its counts cover everyone the send went to:
+
+| Count | What it means |
+| --- | --- |
+| **Delivered** | Your provider confirmed the email reached the reader's mail server. |
+| **Bounced** | The receiving server turned the email away. |
+| **Complained** | The reader marked the email as spam. |
+| **Unsent** | Kestrel couldn't hand the email to your provider. |
+
+Delivered always means confirmed, not just accepted by your provider. Confirmations can lag by days, so counts keep rising after a send finishes. Some emails are never confirmed at all, so a send can read **Settling** for good, which is normal.
+
+**Unsent recipients** are still on your list, and get your next post. A recipient is unsent when their own email kept failing, with the provider's words on the row, or when you chose **Assume not sent**.
+
+## Bounces and complaints
+
+Kestrel acts on these for you, so a bad address can't keep hurting your sending reputation:
+
+- **A hard bounce** means the address can't receive mail. Kestrel never mails it again.
+- **A soft bounce** is temporary, such as a full mailbox. The address stays on your list.
+- **A complaint** means the reader marked your email as spam. Kestrel never mails them again.
+
+Under **Subscribers**, a suppressed address keeps its status and carries a label saying why. When a recent send's bounces reach about 5% of its recipients, the dashboard warns you. That's about the rate at which email providers start to review a sender, so check the addresses on its record.
+
+### Lifting a suppression
+
+Lift one only when you know the address works again, such as a reader who tells you their mailbox is fixed. Mailing an address that keeps failing can hurt every send after it. **Unblock**, in a subscriber's ⋯ menu, lifts a block. The dashboard can't lift a bounce or a complaint, but [Claude](07-working-with-claude.md) can, when you ask. Past records keep the bounce or complaint where it happened.
+
+## An import is refused
+
+Kestrel refuses a file it can't read with certainty, and says what's wrong and where. Nothing on your list changes.
+
+- **Not in the format.** The file isn't a Kestrel CSV or a plain list. Convert it first, with Claude or by hand.
+- **A column or value the format doesn't take,** named with its row and column. Fix it in the file, or move a column of your old service's into `evidence`.
+- **Too many rows** for one import. Split the file.
+- **Too large.** An import takes up to 10 MB.
+
+[The file format](01-your-list.md#the-file-format) describes what each column takes.
+
+## Notifications
+
+With an address set, Kestrel emails you:
+
+- when a send finishes, with how many emails were accepted, unsent, and skipped
+- when your provider refuses your account, or no provider is connected
+- when a send stays in progress too long, waits for you to resolve it, or misses its time
+- when Claude imports a list for you
+
+Each links to the page it's about, and is sent once while the problem lasts. A bounce spike shows on the dashboard but isn't emailed. **Send a test notification** checks that one arrives.
+
+By default, notifications go through your newsletter's own email provider. So when that provider refuses your account, the notification about it can't reach you either. You can send them another way, as [Notifications through Cloudflare's email](../guides/03-notifications.md) describes.

package/docs/publishing/07-working-with-claude.md

@@ -1,48 +1,29 @@
 # Working with Claude
 
-Claude works through the same API as the dashboard, so it can do what you do in the dashboard, and nothing more. It drafts, proofreads, tests, schedules, and reports, and everything it changes shows in the dashboard as Claude's.
+Ask Claude in plain words, the way you'd ask a colleague. It works through the same API as the dashboard, so it can do what you can do there, and nothing more. Everything it changes shows in the dashboard as Claude's.
 
-This page covers what to ask Claude for, the lines the app holds for any client, and the lines Claude keeps on its own. Setting Claude up is a job for whoever runs your Kestrel: [Connect Claude to the API](../guides/01-connect-claude.md) walks through it. Claude reads these same pages from your Kestrel, so it explains things in the words you see here.
+To set Claude up, follow [Connect Claude to the API](../guides/01-connect-claude.md). Claude reads these same pages from your Kestrel, so it explains things in the words you see here.
 
 ## What to ask Claude
 
-Ask in plain words, the way you'd ask a colleague. Claude reads the API reference, `GET /api/reference`, before its first call, and works out the rest.
+- **Draft or proofread a post.** Give it notes, an outline, or a draft. It saves a new version you can open in the dashboard. If you edited the post meanwhile, its save is refused, and it works from your version or asks you.
+- **Test and schedule a post.** Name the post and when it should go out. Claude schedules it, sends a test of exactly what will go out, and tells you how to cancel. It can also cancel a send or move it.
+- **Check how a send did.** Claude reads the send's record and reports what was delivered, unsent, bounced, or complained.
+- **Lift a bounce or a complaint.** The dashboard can't, so ask Claude when you know an address works again. [Lifting a suppression](06-troubleshooting.md#lifting-a-suppression) says when that's wise.
+- **Recover an earlier version.** Every save keeps a whole version of a post, and Claude can read them back.
+- **Import a list.** Its `/migrate-list` skill asks what anything ambiguous in your old service's export means, and converts a few rows for you to check. It imports once you attest, and if a scheduled post would grow, you finish the import in the dashboard.
 
-- **Draft a post.** Give it your notes, an outline, or a topic, and it saves a draft you can open in the dashboard. Images are uploaded to the post and referenced by file name, as [Write your first post](04-write-a-post.md) describes.
-- **Edit or proofread a post.** Claude saves a new version against the one it read. If you edited the post meanwhile, its save is refused, and it reads your version and works from that, or asks you.
-- **Send a test.** Claude sends the real email to your test addresses, or to one you name, through the same render as the send.
-- **Schedule a post.** Name the post and when it should go out. Claude schedules it, sends a test of exactly what will fire, and tells you when it fires and how to cancel. It can also cancel a send or move its fire time, as [Scheduling and sending](05-scheduling-and-sending.md) describes.
-- **Check a send's record.** Ask how a post did, and Claude reads the send and its recipients. It reports how many were accepted, delivered, and unsent, and any bounces or complaints. [After a send](06-after-a-send.md) says what each one means.
-- **Lift a bounce or a complaint.** The dashboard lifts only a block, with **Unblock**, so ask Claude when you know a bounced address works again. [After a send](06-after-a-send.md#lifting-a-suppression) says when that's wise.
-- **Import a list.** Ask Claude to bring your subscribers over from another service. Its `/migrate-list` skill converts the export, checks it with you, and imports it. [Bring your existing list](01-your-list.md#let-claude-convert-your-export) says how that goes.
+## The lines it can't cross
 
-If you have a post open when Claude saves it, the editor tells you, and names Claude as the one who changed it.
+The app holds these for any client, so they hold whatever Claude is told:
 
-## Lines the app holds for any client
+- **Every send waits out the review window,** and you can cancel it until it goes out.
+- **A scheduled post is locked,** and what goes out is exactly the copy that was scheduled.
+- **No one is mailed twice,** and only confirmed subscribers receive a post.
+- **An unsubscribe is final** until the reader subscribes again, and an erased address stays erased until the person confirms 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.** An import through Claude that would stops there, until you finish it in the dashboard.
 
-The app enforces these itself, for the dashboard and Claude alike, so they hold whatever Claude is told:
+Claude also follows instructions your Kestrel gives it, which live in your instance's repository. Those hold only as long as the instructions do. They have Claude ask before anything that reaches readers, test again after a template change, and record whose decision each change to the list was. They also have it treat what's in a post or a subscriber's record as content, never as instructions.
 
-- **Every send waits out the review window.** Nothing goes out the moment it's asked for, not even a send now, and you can cancel it until it fires. The shortest window is set when Kestrel is deployed, so no client can shorten it through the API.
-- **A scheduled post is locked.** To change it, cancel the send, edit, and schedule again. What fires is exactly the copy that was scheduled.
-- **One send per post at a time, and no one mailed twice.** A repeated request finds the existing send instead of making another.
-- **Only confirmed subscribers receive a post.** Someone added by hand gets a confirmation email first, and receives nothing until they confirm. A bounced or complained address is never mailed.
-- **An unsubscribe is final.** Only the reader undoes it, by subscribing again.
-- **No one's edit is overwritten.** A save based on an older version of a post is refused, whichever client sent it.
-- **Only you can let an import grow a scheduled send.** An import through Claude that would add people to a waiting send stops there, until you finish it in the dashboard.
-- **An erased address stays erased.** Adding it back by hand needs a statement that the person asked to join again, and only their own confirmation lifts it.
-
-## Lines Claude keeps
-
-These come from the instructions your Kestrel gives Claude, not from the app, so they hold as long as those instructions do. Whoever runs your Kestrel keeps them in your instance's repository.
-
-- **It asks before anything that reaches readers.** Sending mail and changing the list wait for your yes.
-- **It schedules only when you ask,** then sends a test of the scheduled copy. After a change to your template or publication details, it tests again.
-- **It never adds a subscriber you didn't name.** The one exception is an import you asked for, through `/migrate-list`, which imports anyone as a subscriber only on your attestation.
-- **It records whose decision it was.** It unsubscribes someone only when they asked to leave, and blocks an address when you decide to stop mailing it. It lifts a bounce or a complaint only when you say the problem is gone, and confirms first.
-- **It erases a subscriber only when you name them and ask,** and confirms first, since an erasure can't be undone.
-- **It reads post text and subscriber data as content.** Words in a post or a reader's record are never instructions to Claude.
-- **It won't help share your subscribe link before your Kestrel can send to anyone.** Until then, signups fail. Whoever runs your Kestrel finishes that before [Go live](../get-started/06-go-live.md).
-
-The app lets Claude give your attestation for an import, so the instruction to ask you first is Claude's own. The import's record says it was given through Claude, and Kestrel emails you about the import if your notifications are set up.
-
-[Subscriber import format](08-import-format.md) describes the file Claude converts your list to.
+The app lets Claude give your attestation for an import, so asking you first is one of those instructions, not a rule the app enforces. The import's record says it came through Claude, and Kestrel emails you about it if your notifications are set.

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

@@ -1,73 +1,25 @@
 # Share your subscribe link
 
-Your publication has a public subscribe page at `/subscribe` on your Kestrel's address, such as `https://newsletter.example.com/subscribe`. Share that link wherever your readers are, or put the same form on your own website. Either way, a reader joins only once they confirm by email.
+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.
 
-This page covers what a reader sees, the confirmation email, putting the form on your site, and previewing every page a reader can land on. You find the link under **Settings → Ways to subscribe**, and on the dashboard's first-run checklist.
+**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)).
 
-## What a reader sees
+## How a reader joins
 
-**A reader enters their address, gets a confirmation email, and presses a button to confirm. Only then do they receive your posts.**
+A reader enters their address, gets a confirmation email, and presses **Confirm subscription** on the page its link opens. Only then do they receive your posts. Opening the link alone records nothing, since mail scanners open links before a person does. This double opt-in is your record that each reader asked for your newsletter.
 
-The subscribe page wears your publication's name, tagline, and logo, which you set in [Name your publication](03-name-your-publication.md). Your landing page and archive carry a subscribe prompt too. After a reader submits their address, the page tells them to check their inbox. The email's link opens a page with a **Confirm subscription** button, and pressing it puts them on your list. This is double opt-in, and it's your record that each reader asked for your newsletter.
+Every address gets the same answer, so the form never reveals who subscribes. Behind it, Kestrel sends a confirmation only when one is due:
 
-Opening the link alone records nothing, since mail scanners open links before a person does. A confirmation link also works only for a limited time. An expired link offers to send a fresh one.
-
-## Addresses already on your list, or that left
-
-**Every address gets the same answer, so the form never reveals who subscribes.**
-
-The page always says to check the inbox, whatever the address is. Behind it, Kestrel sends a confirmation only when one is due:
-
-- **Already subscribed:** no email goes out, and they stay subscribed.
-- **Waiting to confirm:** they get a confirmation, but at most one every 15 minutes, however often the form is submitted. A confirmation link works for 7 days, and an older one offers to send a fresh link.
-- **Unsubscribed earlier:** they get a confirmation, and confirming it puts them back on your list.
-- **Bounced, complained, or blocked:** no email goes out. [After a send](06-after-a-send.md) covers those addresses.
-- **Erased at their request:** they get a confirmation, and confirming lifts the erasure, so they're back on your list.
+- **Already subscribed, bounced, complained, or blocked:** no email goes out.
+- **Waiting to confirm:** at most one confirmation every 15 minutes, however often the form is submitted. A link works for 7 days, and an expired one offers a fresh link.
+- **Unsubscribed earlier, or erased at their request:** they get a confirmation, and confirming puts them back on your list.
 
 ## The confirmation email
 
-**You can change its words in Settings → Confirmation email. Its layout and its link are fixed.**
-
-The section shows the email as a reader gets it. Choose **Edit** to change four things:
-
-- **Subject line**
-- **Message**, the line above the confirm button
-- **Button label**
-- **Reassurance line**, a quiet footer for anyone who didn't sign up. Leave it blank to omit it.
-
-A required field left blank uses Kestrel's default wording, and **Reset to Kestrel default** brings all of it back. Save with the page's save bar.
-
-What you can't change keeps every confirmation working. The email always opens with your publication's name and logo, so a reader sees who's asking first. Kestrel adds the confirm link itself, so no edit can leave it out. The confirmation isn't a post, so it doesn't use your email template and has no unsubscribe link. The words on the page the link opens are fixed too, so what a reader agrees to can't be edited away.
+Change its subject, message, button label, and reassurance line under **Settings → Confirmation email**. Kestrel adds your name, your logo, and the confirm link itself, so no edit can leave them out. The confirmation isn't a post, so it doesn't use your email template.
 
 ## Put the form on your own site
 
-**Copy the form from Settings → Ways to subscribe → Embed a form, and paste it into any page you control.**
-
-Choose a look first:
-
-- **Styled** looks like your subscribe page, with its own fonts and colors carried along, so it fits anywhere.
-- **Plain** is bare markup that takes your site's styles, or the browser's own controls where your site has none.
-
-The section shows the form as it will look beside the HTML that makes it. Choose **Copy HTML**, then paste it into your site. The form heads itself "Subscribe to" your publication's name.
-
-A reader who submits it lands on your Kestrel's own check-your-inbox page, and confirms by email as on the subscribe page.
-
-## Preview every reader page
-
-**Settings → Reader pages shows each page a reader can land on, exactly as they see it, without walking through the steps.**
-
-Pick a page from the list: the subscribe form and its check-your-inbox page, the confirm and unsubscribe pages, or your landing page, archive, and a post page. Pages a reader rarely meets, such as an expired link or an archive with no posts yet, are there too. **Desktop** and **Phone** show each at either width. These are samples, so nothing on them subscribes or unsubscribes anyone.
-
-## When signups aren't open yet
-
-**The form takes no addresses until whoever runs your Kestrel connects email.**
-
-Until then, the subscribe page says the newsletter isn't taking subscribers yet, and the dashboard and Settings say so too. You can still share the link, and it opens once email is connected. [Connect Amazon SES](../get-started/04-ses.md) is that step.
-
-Whoever runs your Kestrel can also limit how often anyone submits the form, which slows down abuse. [Rate-limit the subscribe form](../guides/05-rate-limit.md) covers it.
-
-## Already have a list somewhere else
-
-**Import it instead of asking everyone to sign up again.** Readers who opted in with your old service come with that record of their consent. [Bring your existing list](01-your-list.md) covers importing and exporting.
+**Settings → Ways to subscribe → Embed a form** gives you HTML to paste into any page you control. **Styled** looks like your subscribe page, and **Plain** takes your site's own styles. A reader who submits it confirms by email, as on the subscribe page.
 
-Next, send your first post: [Scheduling and sending](05-scheduling-and-sending.md).
+**Settings → Reader pages** shows every page a reader can land on, at desktop and phone widths, without walking through the steps. You can also limit how often anyone submits the form, which slows down abuse ([Rate-limit the subscribe form](../guides/05-rate-limit.md)).

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

@@ -1,48 +1,30 @@
 # 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, subscribe yourself, and set where Kestrel emails you. It's the second step of **Set up your publication** on your dashboard.
+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.
 
-This page covers whether email is connected, what to check in a test, how Kestrel tells you something's wrong, and what changes as your list grows.
-
-## Email is connected
-
-If nothing on your dashboard says otherwise, it is. While no email provider is connected, Kestrel says so wherever a send would fail. Until your first post, the dashboard's checklist shows **Connect Amazon SES** in place of this step. After that, an amber line on the dashboard reads "No email provider connected, so nothing can be sent yet." The Schedule dialog says the post can't be scheduled yet, and its buttons are unavailable.
-
-**Settings → Email sender** shows your From address, sending domain, and email provider, read-only. Connecting a provider is for whoever runs your Kestrel, in [Connect Amazon SES](../get-started/04-ses.md) and [Verify it works](../get-started/05-verify.md).
+If you're bringing a list of more than about 5,000 subscribers, upgrade to Cloudflare's Workers Paid plan before you import it. On the free plan, a large import and a send can use up the day's database writes. Then the app stops working until midnight UTC. [As your list grows](../guides/09-as-your-list-grows.md) walks through the upgrade.
 
 ## Send yourself a test
 
-A test shows you exactly what readers get, and you can send one before you write any post. Choose **Template** in the sidebar, then **Send test email**, and send a sample post to your own inboxes. [Name your publication](03-name-your-publication.md) covers the template, and [Write your first post](04-write-a-post.md#test-emails) covers what a test is.
+Choose **Template** in the sidebar, then **Send test email**, and send a sample post to your own inboxes. When it arrives, check:
 
-When it arrives, look at:
-
-- **The From name and address.** They're what readers see first.
-- **Your logo and name,** as your template prints them.
-- **Where it lands:** the inbox, Promotions, or spam. If it lands in spam, tell whoever runs your Kestrel. [Sending-domain DNS](../reference/02-sending-domain-dns.md) covers what they check.
-- **A reply.** Reply to the test, and check that it reaches your inbox. Kestrel never sees replies, so this depends on [forwarding set up by whoever runs your Kestrel](../get-started/04-ses.md#3-receive-replies-at-your-from-address).
+- **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)).
+- **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
 
-Subscribing with a personal address shows you what a new reader sees. Use your public subscribe page, at your publication's address followed by `/subscribe`. The confirmation email arrives with your wording. Once you confirm, you 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 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.
 
-## How Kestrel tells you something's wrong
+## Set your notifications address
 
-Kestrel tells you in three places: your inbox, the dashboard, and the Schedule dialog. Most of the time, none of them says anything.
+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.
 
-- **Notifications.** Set your address under **Settings → Notifications**, in **Send notifications to**, and save. **Send a test notification** checks that one arrives. With no address set, nothing is emailed. [After a send](06-after-a-send.md#notifications) lists what you're told.
-- **The dashboard's health block.** It appears only when something needs attention, and stays until it clears. Red needs you to act, and amber is worth a look.
-- **Warnings when you schedule.** The Schedule dialog warns you before you schedule something that could go wrong. [Scheduling and sending](05-scheduling-and-sending.md#warnings-in-the-schedule-dialog) covers them.
+## If email isn't connected
 
-Whoever runs your Kestrel chooses how notifications are sent. [Notifications through Cloudflare's email](../guides/03-notifications.md) covers a way that reaches you even when your email provider refuses your account.
+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 a few limits, and Kestrel tells you before or when it reaches each one. Raising each is a change for whoever runs your Kestrel, on the plans and accounts they chose, as [Go live](../get-started/06-go-live.md#as-your-list-grows) describes.
-
-- **Your provider's daily sending quota.** A send that hits it waits, and the dashboard shows why. It resumes on its own once the quota frees up, and nobody is mailed twice. Amazon SES reports a spent quota as refusing your account, so its email reaches you only if your notifications go another way ([Notifications](06-after-a-send.md#notifications)).
-- **How long a send takes.** It grows with your list, and depends on your provider's sending rate and the hosting plan whoever runs your Kestrel chose. [Go live](../get-started/06-go-live.md#as-your-list-grows) gives the rates.
-- **Daily database writes on the free hosting plan.** A large send or import can use up the day's writes. Then the whole app stops until midnight UTC. On that plan, Kestrel warns you before a send to more than 5,000 recipients. It also warns you before an import that would use most of the day's writes. Neither warning stops you. [Bring your existing list](01-your-list.md#limits) explains more.
-
-From about 5,000 subscribers, it's recommended that whoever runs your Kestrel moves to the paid hosting plan, which has no daily limit on writes.
+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, and [As your list grows](../guides/09-as-your-list-grows.md) covers raising each.
 
-Next, [Bring your existing list](01-your-list.md).

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

@@ -0,0 +1,34 @@
+# Edit your email template
+
+You write each post in Markdown, and the template is the HTML frame it's sent in, like a layout in a static site generator. `{{ .Post.Body }}` marks where your post goes, and the rest is plain HTML around it. The built-in template works as it comes, so changing it is optional.
+
+To change it, choose **Template** in the sidebar, edit the HTML, and choose **Save changes**. **Start from example** offers two starting points. **Signed** ends each post with your logo, name, and tagline, and **Plain** has just your post and the footer links.
+
+## What every template needs
+
+Kestrel won't save a template without `{{ .Post.Body }}` and `{{ .Email.UnsubscribeURL }}`. Every email has to carry the post and a way to leave. The two **Required** pills above the editor turn green or red as your template gains or loses them.
+
+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.
+
+## Variables
+
+A variable is replaced with its value in each email. Type it exactly as shown, or it renders as empty.
+
+| Variable | What it holds |
+| --- | --- |
+| `{{ .Post.Body }}` | Your post, rendered from Markdown. Required. |
+| `{{ .Post.Subject }}` | The post's subject line. |
+| `{{ .Publication.Name }}` | Your publication's name. |
+| `{{ .Publication.Tagline }}` | Your tagline. |
+| `{{ .Publication.Logo }}` | Your logo as an image, or nothing when no logo is set. |
+| `{{ .Publication.LogoURL }}` | Your logo's address, or empty. |
+| `{{ .Publication.Address }}` | Your mailing address, or empty. |
+| `{{ .Email.SentTo }}` | The address this email was sent to. |
+| `{{ .Email.UnsubscribeURL }}` | This reader's one-click unsubscribe link. Required. |
+| `{{ .Email.ViewInBrowserURL }}` | The post's public page. |
+
+## Test it
+
+**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.

package/docs/publishing/README.md

@@ -1,26 +1,27 @@
 # Publishing with Kestrel
 
-These pages cover writing and sending your newsletter in the dashboard, from naming your publication to what happens after each send. Deploying and running Kestrel itself is covered in [Self-hosting](../README.md).
+These pages get you publishing in the dashboard, and cover the decisions to make before they matter. Deploying and running Kestrel itself is covered in [Self-hosting](../README.md).
 
 ## Set up your publication
 
-The steps your dashboard lists until your first post, in the same order.
+The steps to set up a new publication, in the order the dashboard's setup checklist lists them.
 
 1. [Name your publication](03-name-your-publication.md)
 1. [Check your setup](10-check-your-setup.md)
 1. [Bring your existing list](01-your-list.md)
-1. [Write your first post](04-write-a-post.md)
+1. [Write and send a post](04-write-a-post.md)
 1. [Share your subscribe link](09-share-your-subscribe-link.md)
 
-## Sending
+## Go further
 
-Scheduling a post, what happens when it goes out, and the rules every send keeps.
+Things you choose to do once you're running.
 
-- [Scheduling and sending](05-scheduling-and-sending.md)
-- [After a send](06-after-a-send.md)
-- [Sending rules](02-sending-rules.md)
+- [Edit your email template](11-email-template.md)
+- [Working with Claude](07-working-with-claude.md)
 
-## More
+## Rules and troubleshooting
 
-- [Working with Claude](07-working-with-claude.md)
-- [Subscriber import format](08-import-format.md)
+What the law asks of every send, and what to do when something goes wrong.
+
+- [Sending rules](02-sending-rules.md)
+- [Troubleshooting](06-troubleshooting.md)

package/docs/reference/01-configuration.md

@@ -30,7 +30,7 @@ None of these can be read or changed from inside the app, by the editor or by Cl
 
 ### `PROVIDER`
 
-Until it's set, or while it's empty, the app runs with no provider connected. You can write and preview posts, 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`.
+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`.
 
 `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.
 
@@ -38,11 +38,11 @@ Until it's set, or while it's empty, the app runs with no provider connected. Yo
 
 `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 `@`.
 
-Neither one is your 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, your emails and reader pages show no name at all.
+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.
 
 ### `ARCHIVE_BASE_PATH`
 
-Every post you send carries its archive link, `ARCHIVE_BASE_PATH` followed by the post's slug, and those links are permanent. Changing the prefix later breaks every link already mailed, so pick it before your first send. To keep links from an older install working, set it to the prefix they use, such as `/newsletter`.
+Every post sent carries its archive link, `ARCHIVE_BASE_PATH` followed by the post's slug, and those links are permanent. Changing the prefix later breaks every link already mailed, so pick it before the first send. To keep links from an older install working, set it to the prefix they use, such as `/newsletter`.
 
 A missing leading slash is added, and a trailing slash is dropped.
 
@@ -64,9 +64,9 @@ This setting is the subrequest cap. The app keeps database queries under theirs
 
 It's also how the app tells Workers Free from Workers Paid. At the default, the app runs on 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. Above it, up to 10,000 ([Import format](../publishing/08-import-format.md#limits)).
+- 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 you've imported), 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](../get-started/06-go-live.md#as-your-list-grows)). Neither warning stops you. Above the default, neither appears.
+- 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.
 
 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.
 
@@ -74,7 +74,7 @@ Never set it above your plan's limit. A minute that hits the cap is cut off mid-
 
 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.
 
-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 you can schedule. It lives in deploy config on purpose, so neither the editor nor Claude can shorten it.
+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.
 
 ### `ARCHIVE_ORIGIN` and `MEDIA_PUBLIC_BASE`
 

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

@@ -27,7 +27,7 @@ SES generates the DKIM values. Copy them exactly as SES lists them, since they d
 
 SPF needs no record of yours on SES's default path, since it passes for a subdomain of `amazonses.com`. An SPF record, at `bounce.send`, comes only with the optional custom MAIL FROM domain.
 
-Email Routing adds MX, SPF, and DKIM records at `send` itself, the DKIM one under the selector `cf2024-1`. They're for mail sent *to* your From address, so readers' replies reach you ([Connect Amazon SES](../get-started/04-ses.md#3-receive-replies-at-your-from-address)). They don't affect your sending: inboxes check SES's mail for SPF at its return path, and for DKIM against SES's own keys.
+Email Routing adds MX, SPF, and DKIM records at `send` itself, the DKIM one under the selector `cf2024-1`. They're for mail sent *to* your From address, so readers' replies reach the publisher ([Connect Amazon SES](../get-started/04-ses.md#3-receive-replies-at-your-from-address)). They don't affect your sending: inboxes check SES's mail for SPF at its return path, and for DKIM against SES's own keys.
 
 ### SPF: authorize the return path
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.10.0",
+  "version": "1.11.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/claude/skills/migrate-list/SKILL.md

@@ -8,12 +8,12 @@ argument-hint: "[path to the export]"
 
 An import adds people to the list, and a wrong guess about who agreed to be emailed can't be taken back. So this skill holds no facts about any service's export, which change without notice. It holds a method that checks itself against the file in hand and against Kestrel's own plan.
 
-The publisher's page on the import format is the authority: `GET /api/docs/import-format.md` on the instance, or `node_modules/@kurtbruns/kestrel/docs/publishing/08-import-format.md`. If anything here seems to disagree with it or with the API, they win; say so.
+The authority on the import format is the "The file format" section of the publisher's page "Bring your existing list": `GET /api/docs/your-list.md` on the instance, or `node_modules/@kurtbruns/kestrel/docs/publishing/01-your-list.md`. If anything here seems to disagree with it or with the API, they win; say so.
 
 ## Before you start
 
 - **Read the truth from the instance, every time.** Call `GET /api/imports/format` and `GET /api/reference` at the start of each migration. They give the columns, the values each takes, the outcomes, the attestation, and this deployment's `limits`. Never write the format from memory, or from this file.
-- **Explain it in Kestrel's words.** For what to tell the publisher about the format, the row limit, and the Workers Free advice, read the publisher page "Bring your existing list" at `GET /api/docs/your-list.md`, with this deployment's numbers from `GET /api/imports/format`. Use them rather than your own account of the format.
+- **Explain it in Kestrel's words.** For what to tell the publisher about the format, the row limit, and the Workers Free advice, read the rest of that page, above "The file format", with this deployment's numbers from `GET /api/imports/format`. Use them rather than your own account of the format.
 - **Convert to the format the route names as `preferred`,** the full CSV. Fall back to a plain list only when the export holds nothing but addresses, and tell the publisher what a plain list loses, from the route's own `loses`.
 - **Work outside the repository.** Make a working folder outside this repository, such as `~/kestrel-migration/`, for the export, the converter, its tests, and the converted pieces. They hold real addresses, so nothing from the list is ever committed here. A fixture that must be committed uses made-up rows only.
 

package/docs/guides/08-try-locally.md

@@ -1,108 +0,0 @@
-# Try Kestrel locally first
-
-You can run Kestrel on your own computer to look around before you deploy it. It needs no Cloudflare account and no Git host. Email goes to a stand-in on your computer, so nothing reaches a real inbox.
-
-In this guide, you write a new instance into an empty folder, start the app, and open the editor. Then you fill it with a demo publication, and empty it again. The folder can become your instance's repository later.
-
-## Before you begin
-
-- [Node.js](https://nodejs.org/) 22 or later
-
-## 1. Write a new instance
-
-An instance is a small folder of your own. It holds the instance's settings and names the release of Kestrel it runs, which installs from npm as `@kurtbruns/kestrel`.
-
-1. Make an empty folder, and go into it:
-
-    ```bash
-    mkdir newsletter
-    cd newsletter
-    ```
-
-1. Write a new instance into it:
-
-    ```bash
-    npx @kurtbruns/kestrel init
-    ```
-
-    It writes the instance's files, and lists the commands to run next. The folder doesn't need to be a Git repository.
-
-1. Install the release and its tools:
-
-    ```bash
-    npm install
-    ```
-
-## 2. Start the app
-
-1. Copy the local settings:
-
-    ```bash
-    cp .dev.vars.example .dev.vars
-    ```
-
-    They're for your computer only, and send email to the stand-in.
-
-1. Start the app:
-
-    ```bash
-    npm run dev
-    ```
-
-    The first time, it creates the local database and asks you to confirm its migrations. Answer yes. The server keeps running in this terminal, and its output ends with the address it's ready on.
-
-1. Open http://localhost:8787/dashboard/ to see the editor. There's nothing to sign in with on your computer. If another app already uses port 8787, Kestrel picks a free port instead, and the `Ready on` line shows it.
-
-## 3. Load the demo publication
-
-The demo fills the editor with posts, subscribers, and sends that already went out, so you can see the app in use.
-
-1. In a second terminal, in the same folder, load the demo:
-
-    ```bash
-    npm run seed
-    ```
-
-    It replaces everything in the local database, and lists links to the editor and the demo's published posts.
-
-1. To empty the local database again, and see the app as a new instance starts:
-
-    ```bash
-    npm run reset
-    ```
-
-1. To stop the server, press <kbd>Ctrl</kbd>+<kbd>C</kbd> in its terminal. Your local content stays for the next `npm run dev`.
-
-## Check it
-
-1. The app answers. If `npm run dev` picked another port, use the one on its `Ready on` line here and below:
-
-    ```bash
-    curl http://localhost:8787/health
-    ```
-
-    ```
-    {"status":"ok","service":"kestrel"}
-    ```
-
-1. After `npm run seed`, http://localhost:8787/ shows the demo publication's public landing page, with its posts.
-
-## Keep the folder for your instance
-
-If you came here from Deploy the app, your folder is already a repository: go back to [Sign in to Cloudflare](../get-started/02-deploy.md#2-sign-in-to-cloudflare).
-
-When you're ready to deploy, this folder can be your instance's repository. You need [Git](https://git-scm.com/) and a GitHub account for this part. The folder's `.gitignore` already keeps your local settings, the local database, and the installed packages out of it.
-
-1. On GitHub, [create a new repository](https://github.com/new) named `newsletter`. It can be private. Leave it empty, with no README, license, or `.gitignore`.
-
-1. Make the folder a repository, and commit the instance. Replace `YOUR_USERNAME` with your GitHub username:
-
-    ```bash
-    git init
-    git add -A
-    git commit -m "Start a Kestrel instance"
-    git remote add origin https://github.com/YOUR_USERNAME/newsletter.git
-    git push -u origin HEAD
-    ```
-
-Then check [what deploying needs](../get-started/02-deploy.md#before-you-begin) and [choose your hostnames](../get-started/02-deploy.md#choose-your-hostnames). Then [deploy the app](../get-started/02-deploy.md#2-sign-in-to-cloudflare) from signing in to Cloudflare onward.