@kurtbruns/kestrel 1.21.0 → 1.22.0

package/docs/guides/07-upgrade.md

@@ -2,27 +2,29 @@
 
 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.
 
-## 2. Install the release
-
-Each step here changes only your instance's repository. Nothing reaches your deployed app until section 5.
-
-1. Start from a clean repository, so the upgrade's commit holds only the upgrade and going back undoes nothing else:
+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
     ```
 
-    If it lists anything, commit it first, as its own commit, or move it out of the repository.
+    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.
 
 1. Install the release. Replace `X.Y.Z` with its version:
 

package/docs/publishing/06-troubleshooting.md

@@ -97,6 +97,7 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.21.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",

package/packages/kestrel/lib/oauth.mjs

@@ -26,14 +26,15 @@ 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, so what a person runs never reads as Claude's.
- * CLAUDE_CODE_CHILD_SESSION is set only by Claude Code, on what its tools launch. CLAUDECODE
+ * 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; and
- * a `screen` session or a background launcher Claude Code started passes it on, so what a person
- * later runs inside one reads as Claude Code's.
+ * 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;

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

@@ -6,12 +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.
-- **Anything not yet committed.** If the page's `git status` lists anything, show the person and ask whether to commit it first, as its own commit. If they'd rather not, the upgrade waits until the repository is clean. Never let it go into the upgrade's commit: the page's **Go back** reverts that commit, and would undo it too.
+- **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.