@kurtbruns/kestrel 1.20.0 → 1.22.0

package/docs/get-started/02-deploy.md

@@ -167,7 +167,7 @@ Create Kestrel's tables in the production database:
 npx wrangler d1 migrations apply DB --remote --env production
 ```
 
-It lists the migrations it's about to apply and asks you to confirm. It applies only the ones the database hasn't seen, so running it again is harmless.
+It lists the migrations it's about to apply and asks you to confirm. Run by Claude, or in any other shell that isn't interactive, it answers its own prompt and applies them without asking. It applies only the ones the database hasn't seen, so running it again is harmless.
 
 ## 6. Deploy
 
@@ -175,7 +175,7 @@ It lists the migrations it's about to apply and asks you to confirm. It applies
 npx wrangler deploy --env production
 ```
 
-This deploys the release your instance runs, with your settings. The output ends with the hostname the app now answers on. Deploying also registers the once-a-minute schedule that sends posts, which you can see under the Worker's **Triggers** tab in the Cloudflare dashboard.
+This deploys the release your instance runs, with your settings. Near its end, the output names the hostname the app now answers on, then its schedule and a version ID. Deploying also registers the once-a-minute schedule that sends posts, which you can see under the Worker's **Triggers** tab in the Cloudflare dashboard.
 
 Always name `--env production`, here and on every wrangler command that stores a secret. Without it, wrangler deploys the top level, local development, as a second Worker that answers nowhere and never sends. It takes the top level's `name` in `wrangler.jsonc`, such as `newsletter-dev`. If that happens, remove it by that name:
 

package/docs/get-started/05-ses.md

@@ -51,7 +51,7 @@ The same form sets a custom MAIL FROM domain, so SPF also passes for your domain
 
 ## 2. Add a DMARC record
 
-DMARC tells inboxes what to do with mail that fails its checks, and sends you reports about it. SES doesn't add this record, so you add it yourself. It starts in monitor mode, which reports without blocking anything.
+DMARC tells inboxes what to do with mail that fails its checks, and can ask them to send you reports. The `rua` tag that asks for them is optional, and the policy works without it. SES doesn't add this record, so you add it yourself. It starts in monitor mode, `p=none`, which blocks nothing, your own mail included. It only monitors: inboxes still deliver mail that fails, so it doesn't stop anyone sending as your domain.
 
 1. In the Cloudflare dashboard, open your domain's DNS records, and add a record:
 
@@ -309,7 +309,7 @@ Replies to a post go to your From address, `newsletter@send.example.com`, which
 
 1. Under **Routing Rules**, select **Create routing rule**. For **Email pattern**, enter `newsletter`, the part of your From address before the `@`, and select `send.example.com`. Set **Action** to **Send to an email**, select the publisher's inbox as the **Destination**, and save.
 
-1. **(Optional)** Give your DMARC reports an inbox too. If the address in your DMARC record doesn't receive mail, add a rule that forwards `dmarc` the same way. Then change the record's `rua` to `mailto:dmarc@send.example.com`.
+1. **(Optional)** Forward your DMARC reports too, if you collect them and the address in your DMARC record doesn't receive mail. Add a rule that forwards `dmarc` the same way. Then change the record's `rua` to `mailto:dmarc@send.example.com`. Reports come about once a day from each inbox provider that received your mail. A day or two after your next email goes out, check that they arrive. Email Routing's **Activity log** shows each forward's status.
 
 1. Check that your From address receives mail. This now lists Cloudflare's three `route` mail servers:
 

package/docs/get-started/07-verify.md

@@ -102,7 +102,7 @@ The app writes a log line for each thing it does, and Cloudflare keeps them for
 
 1. Filter on `event` equal to `send.scheduled`. Your two sends from section 4 are there, and `send.canceled` shows the one you canceled. Each line that records an action says who took it. Its `principal` is `human` or `service`, and its `client` names the program a person used, such as `editor`.
 
-1. Filter on `level` equal to `error`. A healthy instance shows nothing.
+1. Filter on `level` equal to `error`. A healthy instance shows nothing. An occasional `d1.unavailable` line at `warn` is a brief database stall the next run makes up for, and needs nothing. The same line every minute means work isn't getting done, so if you set up alerts, alert on it repeating as well as on `error`.
 
 To follow one send, narrow the time range and filter on its `sendId`, since a long range may show only a sample. On the Free plan, Cloudflare stops keeping logs for the rest of the day once its daily allowance is used, as [its pricing page](https://developers.cloudflare.com/observability/pricing/) describes.
 

package/docs/guides/03-notifications.md

@@ -19,7 +19,7 @@ Cloudflare's email sends only from a domain set up with Email Routing. Use your
 
 1. Add `newsletter.example.com` to Email Routing. Cloudflare adds subdomains from your domain's own settings: select `example.com`, then **Settings**, and add `newsletter` under **Subdomains**.
 
-1. Cloudflare adds MX, SPF, and DKIM records for `newsletter.example.com`, and locks them. Wait until they show as added.
+1. Cloudflare adds the DNS records it needs for `newsletter.example.com`. Wait until the new row reads **Status: Enabled** and **DNS records: Locked**.
 
 Avoid turning on Email Routing for a domain that already receives mail elsewhere, such as `example.com` with Google Workspace. Email Routing takes over that domain's MX records. Don't send notifications from `send.example.com` either, since your email provider sends from it. Email Routing there to forward readers' replies, as [Connect Amazon SES](../get-started/05-ses.md#8-receive-replies-at-your-from-address) sets up, is fine, since it only receives.
 
@@ -27,27 +27,25 @@ Avoid turning on Email Routing for a domain that already receives mail elsewhere
 
 Cloudflare's email delivers only to addresses you've verified with it. Sending to a verified address is free on any plan. Notifications can go to several addresses, such as the publisher's and yours, and each one needs verifying.
 
-1. Under **Email Routing**, go to **Destination Addresses**, and add each address saved for notifications.
+1. Under **Email Routing**, go to **Destination addresses**, and add each address saved for notifications that isn't already verified there.
 
-1. Open the email Cloudflare sends to each address, and select **Verify email address**. If it's the publisher's address, ask them to do this step.
+1. Open the email Cloudflare sends to each one, and select **Verify email address**. If it's the publisher's address, ask them to do this step.
 
-A verified address belongs to your Cloudflare account, so every environment in it can use it.
+A verified address belongs to your Cloudflare account, so every environment in it can use it. If the publisher adds or changes a notifications address later, verify the new one too.
 
 ## 3. Add the binding and deploy
 
 A `send_email` binding named `NOTIFY` moves notifications to Cloudflare's email. Without it, they go through your provider.
 
-1. In `wrangler.jsonc`, add the binding to the `production` block:
+1. In `wrangler.jsonc`, add the binding to `env.production`, beside `r2_buckets` and not inside `vars`:
 
     ```jsonc
-    "send_email": [
-      { "name": "NOTIFY", "allowed_destination_addresses": ["you@example.com"] } // ← the notifications addresses
-    ],
+    "send_email": [{ "name": "NOTIFY" }],
     ```
 
-    `allowed_destination_addresses` is optional. It limits the binding to the addresses you list, so a changed setting in the editor can't send notifications anywhere else. Leave it out to allow any address you've verified. If the publisher adds or changes a notifications address later, verify the new one and add it here too.
+    Give the binding only its name. This file is committed to your repository, so keep the notifications addresses out of it.
 
-1. **(Optional)** Notifications come from `Kestrel <kestrel@newsletter.example.com>`. To use another address on that hostname, set `NOTIFY_FROM` in the block's `vars`:
+1. **(Optional)** Notifications come from `Kestrel <kestrel@newsletter.example.com>`. To use another address on that hostname, set `NOTIFY_FROM` in `env.production.vars`:
 
     ```jsonc
     "NOTIFY_FROM": "Kestrel <alerts@newsletter.example.com>",
@@ -62,7 +60,8 @@ A `send_email` binding named `NOTIFY` moves notifications to Cloudflare's email.
 1. Commit the change, and push it:
 
     ```bash
-    git commit -am "Send notifications through Cloudflare's email"
+    git add wrangler.jsonc
+    git commit -m "Send notifications through Cloudflare's email"
     git push
     ```
 
@@ -72,17 +71,22 @@ A `send_email` binding named `NOTIFY` moves notifications to Cloudflare's email.
     npx wrangler deploy --env production
     ```
 
+    The output lists the binding as `env.NOTIFY (unrestricted)`. Cloudflare still delivers only to the addresses you verified.
+
 ## Check it
 
 1. In the editor, open **Settings → Notifications**. **Sent through** reads "Cloudflare Email, separate from your newsletter's provider", and **From address** shows `Kestrel <kestrel@newsletter.example.com>`.
 
-1. Select **Send a test notification**. It arrives at each notifications address, and **Last notification** shows it as delivered.
+1. Select **Send a test notification**. **Last notification** shows it as delivered.
+
+1. Check that the test arrives at each notifications address. If it's in the spam folder, mark it **Not spam**.
 
-If the test isn't delivered to an address, **Last notification** shows Cloudflare's reason, such as an address that isn't verified, after the address when there are several. The other addresses still get it. Cloudflare's Email Routing summary lists notifications as dropped even when they're delivered, so check the notifications inbox rather than the summary.
+1. In Email Routing's **Activity log**, the test shows as **Delivered**. Go by this rather than Email Routing's summary, which [Cloudflare says](https://developers.cloudflare.com/email-service/platform/limits/) can list it as dropped even when it's delivered.
 
 ## What notifications don't cover
 
 - **The schedule stopping.** The same once-a-minute schedule that sends posts also notices problems. If the schedule itself stops, nothing tells you. [Read the logs](../get-started/07-verify.md#7-read-the-logs) to check that `sweep.tick` still arrives every minute.
+- **The database being down.** Noticing a problem and telling you both need the database. [Read the logs](../get-started/07-verify.md#7-read-the-logs) to check for `d1.unavailable` repeating.
 - **A notification that can't get through.** The app tries each one up to five times, a minute apart. A failure shows under **Settings → Notifications**, and in the logs as `notify.failed`.
 - **Problems while no address is set.** With the address blank, the app sends nothing, and saves nothing up for later.
 

package/docs/guides/07-upgrade.md

@@ -2,16 +2,26 @@
 
 A new release of Kestrel is a new version of the `@kurtbruns/kestrel` package. Upgrading changes the version your instance's repository names, brings in the release's database changes, and deploys. The app can't undo a database change, so you note a restore point first.
 
-In this guide, you read what changed, install the release, and note where your database stands. Then you apply the database changes, deploy, and check the new version. If you run a staging environment, upgrade it first, and repeat each step for production once it checks out.
+In this guide, you first read what changed and check that your repository is clean, which changes nothing. Then you install the release, note where your database stands, apply the database changes, deploy, and check the new version. If you run a staging environment, upgrade it first, and repeat each step for production once it checks out.
 
-## 1. Read what changed
+## 1. Check before you change anything
 
-A release can ask you to change a setting or a record before it runs. The changelog says so, release by release.
+A release can ask you to change a setting or a record before it runs. The changelog says so, release by release. The upgrade also has to start from a clean repository.
 
 1. Find the version you run. In the editor, open the **Docs** or **API** tab. The foot of its contents list shows the version, then the commit. Your instance's `package.json` names it too, as the version of `@kurtbruns/kestrel`.
 
 1. Read the [release notes](https://github.com/kurtbruns/kestrel/releases) for every version after yours, up to the one you're moving to. Each release opens with an **Upgrading from…** paragraph that says what to do. Its **Breaking** entries say what changed underneath you.
 
+1. Check that your repository is clean, so the upgrade's commit holds only the upgrade and going back undoes nothing else:
+
+    ```bash
+    git status
+    ```
+
+    It has to say `nothing to commit, working tree clean`. If it lists anything, untracked files included, the upgrade waits until it doesn't.
+
+Nothing has changed yet. If you aren't going on, stop here.
+
 ## 2. Install the release
 
 Each step here changes only your instance's repository. Nothing reaches your deployed app until section 5.
@@ -24,6 +34,12 @@ Each step here changes only your instance's repository. Nothing reaches your dep
 
     Your `package.json` now names exactly that version. Kestrel's versions aren't semantic versioning, so your instance never moves to a release you didn't choose.
 
+    If npm stops with `ERESOLVE` and names wrangler, your `package.json` pins a wrangler older than the release needs. The error's `peer wrangler@` line gives the range it needs. Install both together, with that range in place of `WRANGLER_RANGE`:
+
+    ```bash
+    npm install @kurtbruns/kestrel@X.Y.Z "wrangler@WRANGLER_RANGE"
+    ```
+
 1. Bring in the release's database migrations:
 
     ```bash
@@ -91,7 +107,7 @@ A release changes the database only by adding a migration. Applying it keeps eve
 npx wrangler d1 migrations apply DB --remote --env production
 ```
 
-It lists the migrations it's about to apply, and asks you to confirm. When a release has none, it says there's nothing to apply. Run it on every upgrade.
+It lists the migrations it's about to apply, and asks you to confirm. Run by Claude, or in any other shell that isn't interactive, it answers its own prompt and applies them without asking. When a release has none, it says there's nothing to apply. Run it on every upgrade.
 
 ## 5. Deploy
 
@@ -99,7 +115,7 @@ It lists the migrations it's about to apply, and asks you to confirm. When a rel
 npx wrangler deploy --env production
 ```
 
-The output ends with your app's hostname.
+Near its end, the output names your app's hostname, then its schedule and a version ID.
 
 ## Check it
 

package/docs/publishing/03-name-your-publication.md

@@ -6,6 +6,14 @@ All three are optional, and you can change them at any time. How they appear in
 
 Write the tagline as one line that says what the newsletter covers and how often it goes out, such as "Monthly notes on the birds of the Hudson Valley." Until your first post, it's the only line on your home page that says what readers are signing up for. It's also what AWS sees if it reviews your site when you [request production access](../get-started/06-production-access.md).
 
+## Choose a logo
+
+**Use a square PNG, JPEG, WebP, or GIF, at least 256 × 256 pixels, on a solid background.** Drop it on the logo under **Settings → Publication identity**, or choose **Upload**, which reads **Replace** once you have a logo. It saves right away, without **Save changes**. If that would change scheduled emails, Kestrel asks you to confirm first.
+
+Kestrel makes a 256 × 256 PNG from your image before uploading it, so the original's file size doesn't matter. A wider or taller image is cropped to its center square, and a smaller one is scaled up and looks soft. An animated GIF keeps its first frame. Emails show the logo at 44 × 44 pixels, so a simple mark reads better than fine detail.
+
+A transparent background shows whatever is behind the logo, and the built-in templates turn dark when a reader's mail app is in dark mode. A solid background keeps a dark mark visible there.
+
 ## When to provide a mailing address
 
 **If your newsletter is mostly your own writing, you probably don't need one. If an email is mainly selling something, add one.**

package/docs/publishing/04-write-a-post.md

@@ -10,7 +10,7 @@ The editor takes Markdown, and Kestrel saves as you type. The same Markdown beco
 
 - A blank line starts a new paragraph.
 - The opening lines are the preview a mail client shows beside the subject.
-- Paste or drop an image to add it: PNG, JPEG, WebP, or GIF, up to 5 MB. Kestrel may change its file name, turning spaces into hyphens and numbering a name the post already has, and inserts the new name for you.
+- Paste or drop an image to add it: PNG, JPEG, WebP, or GIF, up to 5 MB. A file named for a different format than it really is, like a JPEG called `photo.png`, is refused until you rename it. Kestrel may change its file name, turning spaces into hyphens and numbering a name the post already has, and inserts the new name for you.
 
 ## Schedule and send
 

package/docs/publishing/06-troubleshooting.md

@@ -97,11 +97,13 @@ Nothing on your list changes. Kestrel refuses a file it can't read with certaint
 [Connect Claude](08-connect-claude.md) covers connecting it. Most failures are in your instance's Cloudflare Access setup, and [Allow Claude to connect](../guides/01-allow-claude.md#check-it) lists their fixes. When connecting fails:
 
 - **Claude says it couldn't connect, or the sign-in failed.** Check that the connector's address is your publication's address followed by `/api/mcp`, and that your instance is deployed, not running on your own computer. If both are right, your instance's Access setup needs the fix.
+- **Claude Code says Dynamic Client Registration was rejected.** `claude mcp login` fails with `Dynamic Client Registration rejected (HTTP 404)`, and a new session shows the connector as failed with the same words. Start `claude`, run `/mcp`, choose the connector, choose Authenticate, and sign in in the browser. The sign-in is stored, so later sessions connect. Nothing on your instance is wrong. `claude mcp login` looks for sign-in details at the standard well-known addresses before reading your instance's own answer, so it never reaches Access. The MCP specification has a client do that only as a fallback.
 - Signing in shows `invalid_target`, or `kestrel login` says your instance "doesn't offer a sign-in for programs". Your instance's Access setup needs the fix.
 - `kestrel login` or `kestrel api` reports a `401`. Access signed you in, but Kestrel refused the sign-in, and your instance's Access setup needs the fix. If either names `access_unidentified`, it's the "Access let you in" problem below. If `kestrel api` says your sign-in has ended, sign in again as [Connect Claude](08-connect-claude.md#claude-code) describes.
 - `kestrel api` says it couldn't renew your sign-in because its Access team answered 404 (not found). First check which instance it called: when you don't name one, it prints a line naming it before "the only instance you're signed in to", which may not be the one you meant. Name yours with `--url`. If it is yours, the Access team domain was most likely renamed or removed since you signed in. Sign in again with `npx kestrel login` and your instance's address, which finds the team it uses now.
 - **"Access let you in, but didn't say who you are".** Your login carried neither an email nor a service token. Sign out, then sign in through the policy that lets you in by email. If you have no such policy, your instance's Access setup needs the fix.
 - **Claude's changes read "via the API".** Claude called the API some way other than `kestrel api`, which names Claude Code. Your instance's instructions for Claude Code have it use `kestrel api` once they're brought up to date, as [Install the release](../guides/07-upgrade.md#2-install-the-release) describes. Changes reading "a service token" mean Claude still uses one, and [Connect Claude](08-connect-claude.md#claude-code) signs it in as you instead.
+- **A change reads "via the Kestrel CLI".** The person it names made it with `kestrel api` outside Claude Code, by hand or through a script, so there's nothing to fix. If Claude Code made it, update Claude Code to v2.1.172 or later: an older one reads this way, and the dashboard can stop saying "Claude is connected."
 
 If someone else set up Kestrel for you, pass this along to them.
 

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

@@ -52,14 +52,14 @@ In Cloudflare, set every `CNAME` for DKIM to **DNS only**, not proxied. SES repo
 
 ### DMARC: publish a policy and collect reports
 
-DMARC tells an inbox what to do with mail that fails both SPF and DKIM, and asks it to send you reports. It's a `TXT` record at `_dmarc.send.example.com`:
+DMARC tells an inbox what to do with mail that fails both SPF and DKIM, and can ask it to send you reports. It's a `TXT` record at `_dmarc.send.example.com`:
 
 ```
 _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, and it only monitors. Inboxes deliver failing mail as usual, so it doesn't stop anyone sending as your domain. It's where to start because it blocks nothing, your own mail included.
+- `rua` is where reports go. It's optional, and the policy works without it, though [Google's DMARC setup page](https://knowledge.workspace.google.com/admin/security/set-up-dmarc) recommends including it. Reports 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.20.0",
+  "version": "1.22.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",
@@ -68,21 +68,21 @@
   "dependencies": {
     "@css-inline/css-inline-wasm": "^0.21.2",
     "aws4fetch": "^1.0.20",
-    "jose": "^6.2.12",
-    "marked": "^18.0.12"
+    "jose": "^6.2.14",
+    "marked": "^18.1.3"
   },
   "peerDependencies": {
-    "wrangler": "^4.152.0"
+    "wrangler": "^4.156.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.6",
-    "@cloudflare/vitest-plugin": "^1.4.7",
-    "@types/node": "^22.20.1",
-    "esbuild": "0.28.1",
-    "happy-dom": "^20.14.5",
+    "@biomejs/biome": "2.6.4",
+    "@cloudflare/vitest-plugin": "^1.4.11",
+    "@types/node": "^22.20.5",
+    "esbuild": "0.28.2",
+    "happy-dom": "^21.0.4",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
-    "wrangler": "^4.152.0"
+    "wrangler": "^4.156.0"
   },
   "allowScripts": {
     "esbuild": true,

package/packages/kestrel/lib/api.mjs

@@ -5,11 +5,12 @@
  * Deployed, it sends the access token `kestrel login` stored, refreshing it from the
  * refresh token when it is about to expire or Access has turned it away, and storing what
  * comes back. Locally there is no Access: the target is this directory's dev server, and
- * the credential is the dev server's human token, so a local run is a person via Claude
- * Code just as a deployed one is. Every request carries `Kestrel-Client: claude-code`
- * unless `--client` names another program, so a person's own script can name itself. It
- * never names the editor: the server trusts the name it is sent (SPEC, Trusted, not guarded),
- * and the editor's name lifts a step only a person in the editor may take (SPEC §7).
+ * the credential is the dev server's human token, so a local run is a person through a
+ * client just as a deployed one is. Every request names its client in `Kestrel-Client`:
+ * `defaultClient` says which, unless `--client` names another program, so a person's own script
+ * can name itself. It never names the editor: the server trusts the name it is sent (SPEC,
+ * Trusted, not guarded), and the editor's name lifts a step only a person in the editor may take
+ * (SPEC §7).
  *
  * It prints the answer's body as it came, so a script or Claude reads a refusal whole; a
  * non-2xx answer also prints its status, and a refusal's code, message, field, and next move,
@@ -24,10 +25,13 @@ import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { readSignIn, readSignIns, withCredentialsLock, writeSignInHeld } from "./credentials.mjs";
 import { devTarget } from "./dev-api.mjs";
+import { fileMediaType } from "./media-types.mjs";
 import {
-  DEFAULT_CLIENT,
+  CLAUDE_CODE_CLIENT,
+  defaultClient,
   instanceOrigin,
   isLoopback,
+  KESTREL_CLI_CLIENT,
   needsRefresh,
   refreshTokens,
   SignInError,
@@ -54,14 +58,16 @@ const USAGE = `Usage: kestrel api <method> <path> [options]
   --form <name=value>           a multipart field, repeatable; name=@file attaches a file
   --url <url>                   the instance (default: KESTREL_URL, else the only one you're signed in to)
   --local                       this directory's dev server, started by kestrel dev
-  --client <name>               your own script's Kestrel-Client name (default ${DEFAULT_CLIENT});
-                                never editor, which only the editor names itself
+  --client <name>               your own script's Kestrel-Client name (default ${CLAUDE_CODE_CLIENT}
+                                when Claude Code runs this, otherwise ${KESTREL_CLI_CLIENT}); never
+                                editor, which only the editor names itself
 
 The routes, fields, and refusals come from the instance's own /api/openapi.json, so they
 match the release it runs. A field the route doesn't take is refused before the request.`;
 
-// The name only the editor sends; `kestrel api` refuses to claim it (SPEC §7, §11).
-const EDITOR_CLIENT = "editor";
+// The name only the editor sends; `kestrel api` refuses to claim it (SPEC §7, §11). Mirrored
+// from shared/who_acted.ts, since the CLI is plain Node; a spec holds the two equal.
+export const EDITOR_CLIENT = "editor";
 
 // The server's rule for a client name (shared/who_acted.ts), mirrored since the CLI is plain
 // Node; a spec holds the two equal. Checking it here, after the trim fetch applies to a header
@@ -227,7 +233,8 @@ async function requestBody({ data, type, forms }) {
       const value = field.slice(at + 1);
       if (value.startsWith("@")) {
         const file = value.slice(1);
-        form.append(name, new Blob([readFileSync(file)]), basename(file));
+        const type = fileMediaType(file);
+        form.append(name, new Blob([readFileSync(file)], { type }), basename(file));
       } else {
         form.append(name, value);
       }
@@ -416,7 +423,7 @@ export async function apiCommand(argv) {
   let call;
   try {
     const args = parseApiArgs(argv);
-    const client = args.client ?? DEFAULT_CLIENT;
+    const client = args.client ?? defaultClient();
     call = await openTarget(args, client);
     if (args.mode === "list") {
       console.log(listRoutes(await readOpenApi(call), args.resource));

package/packages/kestrel/lib/login.mjs

@@ -13,7 +13,7 @@ import { signedInFetch } from "./api.mjs";
 import { credentialsFile, readSignIn, readSignIns, writeSignIn } from "./credentials.mjs";
 import {
   authorizeUrl,
-  DEFAULT_CLIENT,
+  defaultClient,
   discover,
   exchangeCode,
   instanceOrigin,
@@ -86,7 +86,7 @@ export async function signIn(origin, { browser }) {
   } finally {
     listener.close();
   }
-  const res = await signedInFetch(origin, PROTECTED_PATH, { client: DEFAULT_CLIENT });
+  const res = await signedInFetch(origin, PROTECTED_PATH, { client: defaultClient() });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
     const move = unauthorizedMove(body);

package/packages/kestrel/lib/media-types.mjs

@@ -0,0 +1,34 @@
+/*
+ * A file's media type, read from its extension. An instance reads an upload's format from its
+ * bytes and holds the label to them, but this client also calls instances on older releases,
+ * which read only what the multipart part declares and refuse one with no type, so it states one:
+ * `kestrel api --form` does, and so does `kestrel seed`, which imports this rather than keep
+ * its own copy (the client may not import from cli/, but cli/ imports from the client).
+ */
+import { basename } from "node:path";
+
+/**
+ * The extensions of the raster formats an instance takes as an image. The Worker's list is
+ * src/lib/image_types.ts, mirrored since the client is plain Node; a spec holds the two equal.
+ */
+export const IMAGE_TYPE_BY_EXTENSION = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+/** What a file goes as when its extension says nothing: a statement of no kind, not a guess. */
+const UNKNOWN_MEDIA_TYPE = "application/octet-stream";
+
+/**
+ * The media type a file's name says it is, in any case (a camera's `IMG_0042.JPG`), read just as
+ * the server reads a name's claim (shared/images.ts), so the two agree on a file called `.png`.
+ */
+export function fileMediaType(path) {
+  const name = basename(path);
+  return (
+    IMAGE_TYPE_BY_EXTENSION[name.slice(name.lastIndexOf(".")).toLowerCase()] ?? UNKNOWN_MEDIA_TYPE
+  );
+}

package/packages/kestrel/lib/oauth.mjs

@@ -19,8 +19,26 @@ import { createServer } from "node:http";
 /** The path discovery and the sign-in's check ask: protected, and it answers who signed in. */
 export const PROTECTED_PATH = "/api/whoami";
 
-/** The name `kestrel api` gives its requests, unless told another (SPEC §11, Who acted). */
-export const DEFAULT_CLIENT = "claude-code";
+// The names `kestrel api` gives itself (SPEC §11, Who acted). Mirrored from shared/who_acted.ts,
+// since the client is plain Node; a spec holds them equal.
+export const CLAUDE_CODE_CLIENT = "claude-code";
+export const KESTREL_CLI_CLIENT = "kestrel-cli";
+
+/**
+ * The name a request carries unless told another: Claude Code's when Claude Code ran this
+ * process, and the command's own otherwise, as in a terminal a person opened themselves.
+ * CLAUDE_CODE_CHILD_SESSION is set only by Claude Code, on what it launches. CLAUDECODE
+ * won't do: IDE extensions also set it in their integrated terminals, where a person types.
+ *
+ * That makes the name truthful in the normal case, not proven, as with every client name. Claude
+ * Code older than v2.1.172 doesn't set the variable, so its calls read as the command's own; a
+ * command typed after Claude Code's `!` runs in its shell, with output landing in the transcript,
+ * so it reads as Claude Code's; and a `screen` session or a background launcher Claude Code
+ * started passes the variable on, so what a person later runs inside one reads as Claude Code's.
+ */
+export function defaultClient() {
+  return process.env.CLAUDE_CODE_CHILD_SESSION === "1" ? CLAUDE_CODE_CLIENT : KESTREL_CLI_CLIENT;
+}
 
 // How long before its expiry an access token is refreshed rather than sent.
 const REFRESH_MARGIN_MS = 60_000;

package/packages/kestrel/lib/openapi.mjs

@@ -278,7 +278,7 @@ export function describeRoute(doc, method, path) {
     }
     const raw = types.filter((t) => t !== "application/json" && t !== "multipart/form-data");
     if (raw.length) {
-      how.push(`the file itself, with --data @file --type ${raw[0]}`);
+      how.push(`the file itself, with --data @file --type <its own type> (${raw.join(", ")})`);
     }
     out.push(`  Send it as ${how.join("; or ")}.`);
     const example = op.requestBody.content["application/json"]?.example;

package/template/README.md

@@ -23,7 +23,7 @@ Open the editor at http://localhost:8787/dashboard/. Email goes to a stand-in th
 | `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 kestrel login <url>` | Signs Claude Code in to the deployed instance as you, in your browser |
-| `npx 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 kestrel api <method> <path>` | Calls the API as you (`--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 |
 

package/template/claude/CLAUDE.md

@@ -29,7 +29,7 @@ Deploying, migrating the production database, and anything that sends mail or ch
 - **Locally,** with `npm run dev` running, add `--local`: it calls this folder's dev server as its stand-in person, via Claude Code, with no sign-in. `GET /api/dev/outbox` shows the email the stand-in caught.
 - **`npx kestrel api --list` lists the instance's routes** (`--list sends` one resource's), and **`npx kestrel api help <method> <path>` describes one**: its parameters, body fields, answer, and refusals with their next moves. Both read the instance's own OpenAPI document, so they match the release it runs.
 - **Read `GET /api/reference.md` first:** how to authenticate, what a status and an error body tell you and the refusals any route can give, paging, acting safely, and every route on one line. **Before calling a route, read its resource's reference,** `GET /api/reference/<resource>.md` (the index names it, such as `sends.md`): the object the routes return, and each route's parameters, body, answer, refusals (each with what to do next), and an example. Read a resource's reference once per conversation, not before every call.
-- **Posts with images:** upload each image from a file on disk (an image pasted into the chat isn't one; ask the person to save it into this folder), then reference it in the Markdown by the `filename` the upload answers, with alt text, `![a short description](cover.jpg)`, never by the upload's `url`. That name may differ from the one you sent, since spaces and characters that would break a reference become hyphens, and a name the post already has gets a number. An upload never replaces an image: to swap one, upload the new image, reference its `filename`, and delete the old one. The preview warns on a `url` reference, on a name the post doesn't have, on a reference that didn't become an image, and on an uploaded image the post doesn't use.
+- **Posts with images:** upload each image from its original file, asking the person to save it into this folder (the Claude desktop app saves a pasted image to a temporary folder, converted and under a generated name, so it can be uploaded but isn't the file they had), then reference it in the Markdown by the `filename` the upload answers, with alt text, `![a short description](cover.jpg)`, never by the upload's `url`. That name may differ from the one you sent, since spaces and characters that would break a reference become hyphens, and a name the post already has gets a number. An upload never replaces an image: to swap one, upload the new image, reference its `filename`, and delete the old one. The preview warns on a `url` reference, on a name the post doesn't have, on a reference that didn't become an image, and on an uploaded image the post doesn't use.
 - **Never overwrite someone else's edit.** A save names the revision it was based on (the posts reference says how). On `stale_revision`, someone else changed the post (the refusal's `author` says who): read it again and re-apply your change to the newer revision, or ask.
 - **Offer only what a post's or a send's `actions` list,** as the reference's Acting safely says, so a post with no `schedule` or `send_now` (no email provider connected) isn't offered for sending. Read the answer to an act, or its refusal, before telling the publisher what happened or deciding again: it carries the resource as it now stands.
 - **Resolve a wedged send only on the publisher's choice.** Relay the `wedged` condition's message and ask which `resolution` they want, in the words the editor's Resolve dialog shows them: `unsent` is **Assume not sent**, which puts those readers in front of the next post, and `accepted` is **Assume sent**, which records them as sent. Never choose it yourself.

package/template/claude/skills/upgrade/SKILL.md

@@ -6,11 +6,13 @@ argument-hint: "[X.Y.Z]"
 
 # Upgrade the instance
 
-An upgrade moves the instance to a newer release of `@kurtbruns/kestrel`. The guide's upgrade page is the procedure: `node_modules/@kurtbruns/kestrel/docs/guides/07-upgrade.md`. Read it now, and again after installing the new release, whose page then replaces it. Follow it section by section, running each step's commands as written. This skill holds only what the page leaves to you, and never adds or replaces a step. If anything here seems to disagree with the page, the page wins; say so.
+An upgrade moves the instance to a newer release of `@kurtbruns/kestrel`. The guide's upgrade page is the procedure: `node_modules/@kurtbruns/kestrel/docs/guides/07-upgrade.md`. Read it now, and again after installing the new release, whose page then replaces it from the step after the install. Follow it section by section, running each step's commands as written. This skill holds only what the page leaves to you, and never adds or replaces a step. If anything here seems to disagree with the page, the page wins; say so.
 
 ## What's yours to judge
 
-- **Which release, and what it asks.** The installed version is in `package.json`. Read every changelog section between it and the target (the release notes at `https://github.com/kurtbruns/kestrel/releases`, or the new `CHANGELOG.md` once installed). Name each **Breaking** entry and each step in an *Upgrading* paragraph, and say what it means for this instance.
+- **Which release, and what it asks.** The installed version is in `package.json`. Read every changelog section between it and the target, in the release notes at `https://github.com/kurtbruns/kestrel/releases`, and work out what each **Breaking** entry and each step in an *Upgrading* paragraph means for this instance.
+- **Anything not yet committed.** If the page's `git status` lists anything, report what it lists and stop until it lists nothing. How it gets clean is the person's call, so don't offer to commit it or move it.
+- **The go-ahead.** The page's section 1 changes nothing, and neither do you until this is settled. Name the releases, each **Breaking** entry, and each *Upgrading* step, say what each means for this instance, and ask whether to go ahead. Run nothing from section 2 until they say yes. "Not now" ends the upgrade with nothing changed.
 - **The context check.** `npm run check-context` compares this repository's Claude files with the release's. Show the person what it reports. When Kestrel changed a file the person has edited, show what changed, merge it with their edits, and run the command it suggests to record the merge. A change marked as bearing on safety comes first.
 - **The local try.** Ask the person to try what they care about on `npm run dev` before anything reaches production.
 - **The checks.** Report each one's result. A failure stops the upgrade until it's fixed or the person decides.