@kurtbruns/kestrel 1.13.0 → 1.15.0

package/packages/kestrel/lib/openapi.mjs

@@ -0,0 +1,569 @@
+/*
+ * What `kestrel api` reads from an instance's OpenAPI document (`GET /api/openapi.json`): its
+ * routes to list and describe, the route a call names, the body or query string that `-f` and
+ * `-F` fields build, and a refusal's next move.
+ *
+ * The document is the instance's own, read through the same sign-in as the call, so what this
+ * prints matches the release that instance runs, never this CLI's. It is the Worker's
+ * projection of its route manifest (src/reference/openapi.ts): resources are tags, a field is
+ * a schema, and a refusal's next move is written into its response's description, as
+ * "`code`: when. Next move: move." for a route's own and "`code` (status; next move: move)"
+ * for one any route gives.
+ *
+ * A field the route doesn't declare is refused here, before the request, with the route's
+ * field list, by the same rule the router applies (src/lib/strict.ts): a declared field with
+ * no declared children is read whole, so the check stops there. Whether a value is right
+ * beyond its type stays the instance's to say.
+ */
+import { readFileSync } from "node:fs";
+
+const METHODS = ["get", "put", "post", "delete", "patch"];
+
+/** Every operation in the document, as `{ method, path, op }`, in its order. */
+export function operations(doc) {
+  const ops = [];
+  for (const [path, byMethod] of Object.entries(doc?.paths ?? {})) {
+    for (const [method, op] of Object.entries(byMethod ?? {})) {
+      if (METHODS.includes(method)) {
+        ops.push({ method: method.toUpperCase(), path, op });
+      }
+    }
+  }
+  return ops;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The operation `method path` calls, or undefined. A concrete path (`/api/posts/p_1`) matches
+ * its template, as does the template itself, and a literal segment beats a parameter, so
+ * `/api/sends/feed` is the feed rather than a send named "feed".
+ */
+export function findOperation(doc, method, path) {
+  const bare = path.split(/[?#]/)[0];
+  let best;
+  for (const o of operations(doc)) {
+    if (o.method !== method.toUpperCase()) {
+      continue;
+    }
+    const pattern = o.path
+      .split(/(\{\w+\})/)
+      .map((part) => (/^\{\w+\}$/.test(part) ? "[^/]+" : escapeRe(part)))
+      .join("");
+    if (!new RegExp(`^${pattern}$`).test(bare)) {
+      continue;
+    }
+    const literal = o.path.replace(/\{\w+\}/g, "").length;
+    if (!best || literal > best.literal) {
+      best = { ...o, literal };
+    }
+  }
+  return best && { method: best.method, path: best.path, op: best.op };
+}
+
+/** A schema with its `$ref` followed into the document's components. */
+function resolve(schema, doc) {
+  let s = schema;
+  for (let i = 0; s?.$ref && i < 10; i++) {
+    s = doc?.components?.schemas?.[s.$ref.split("/").pop()];
+  }
+  return s ?? {};
+}
+
+/** A schema as one short type, as the reference writes it: `string | null`, `"a" | "b"`, `post`. */
+export function typeName(schema) {
+  if (!schema || typeof schema !== "object") {
+    return "any";
+  }
+  if (schema.$ref) {
+    return schema.$ref.split("/").pop();
+  }
+  if ("const" in schema) {
+    return JSON.stringify(schema.const);
+  }
+  if (schema.enum) {
+    return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+  }
+  if (schema.anyOf) {
+    return schema.anyOf.map(typeName).join(" | ");
+  }
+  if (schema.allOf) {
+    return schema.allOf.map(typeName).join(" & ");
+  }
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  if (!types.length) {
+    return "any";
+  }
+  return types
+    .map((t) => {
+      if (t === "array") {
+        const items = typeName(schema.items);
+        return items.includes(" ") ? `(${items})[]` : `${items}[]`;
+      }
+      return t === "string" && schema.format ? `string (${schema.format})` : t;
+    })
+    .join(" | ");
+}
+
+/** An object schema's fields, a nested object's under dotted names, as `{ name, schema, required }`. */
+function flatFields(schema, doc, prefix = "") {
+  const s = resolve(schema, doc);
+  const rows = [];
+  for (const [key, field] of Object.entries(s.properties ?? {})) {
+    const name = prefix ? `${prefix}.${key}` : key;
+    rows.push({ name, schema: field, required: (s.required ?? []).includes(key) });
+    if (!field.$ref && field.properties) {
+      rows.push(...flatFields(field, doc, name));
+    }
+  }
+  return rows;
+}
+
+/** The JSON body schema a route takes, or undefined when it takes none. */
+function jsonBody(op) {
+  return op.requestBody?.content?.["application/json"]?.schema;
+}
+
+/** The query parameters a route declares. */
+function queryParams(op) {
+  return (op.parameters ?? []).filter((p) => p.in === "query");
+}
+
+/** Text indented under a row, one paragraph per line. */
+function indent(text, by) {
+  return String(text)
+    .split(/\n+/)
+    .map((line) => `${" ".repeat(by)}${line}`)
+    .join("\n");
+}
+
+/**
+ * Every route the document describes, grouped by resource, one per line: its method, path,
+ * and title, a route that takes no sign-in marked so. `resource` narrows it to one resource,
+ * named as `--list` prints it, in any case.
+ */
+export function listRoutes(doc, resource) {
+  const ops = operations(doc);
+  const tagOf = (o) => o.op.tags?.[0] ?? "Other";
+  const tags = [...new Set([...(doc.tags ?? []).map((t) => t.name), ...ops.map(tagOf)])].filter(
+    (t) => ops.some((o) => tagOf(o) === t),
+  );
+  let shown = tags;
+  if (resource !== undefined) {
+    const tag = tags.find((t) => t.toLowerCase() === resource.toLowerCase());
+    if (!tag) {
+      throw new Error(
+        `This instance has no resource named "${resource}"; it has ${tags.map((t) => t.toLowerCase()).join(", ")}.`,
+      );
+    }
+    shown = [tag];
+  }
+  const rows = ops.filter((o) => shown.includes(tagOf(o)));
+  const width = Math.min(Math.max(...rows.map((o) => o.path.length)), 44);
+  const lines = [];
+  for (const tag of shown) {
+    lines.push(lines.length ? `\n${tag}` : tag);
+    for (const o of rows.filter((r) => tagOf(r) === tag)) {
+      const access = o.op["x-kestrel-access"];
+      const marked = access && access !== "admin" ? ` (${access})` : "";
+      lines.push(`  ${o.method.padEnd(6)} ${o.path.padEnd(width)}  ${o.op.summary ?? ""}${marked}`);
+    }
+  }
+  lines.push(
+    "",
+    "`kestrel api help <method> <path>` describes one, its body and refusals among the rest.",
+  );
+  return lines.join("\n");
+}
+
+/** A route's refusals, by status, each `{ status, code, when, move }`. */
+function refusalsOf(op) {
+  const rows = [];
+  for (const [status, res] of Object.entries(op.responses ?? {})) {
+    if (!/^\d+$/.test(status)) {
+      continue;
+    }
+    for (const chunk of String(res.description ?? "").split(/\n\n+/)) {
+      const m = /^`([\w.-]+)`: ([\s\S]*?)\s*Next move: ([\s\S]+?)\.?$/.exec(chunk.trim());
+      if (m) {
+        rows.push({ status: Number(status), code: m[1], when: m[2], move: m[3] });
+      }
+    }
+  }
+  return rows;
+}
+
+/** The refusals any route gives, from the `default` answer, each `{ status, code, move }`. */
+function sharedRefusalsOf(op) {
+  const text = String(op.responses?.default?.description ?? "");
+  return [...text.matchAll(/`([\w.-]+)` \((\d+)(?:; next move: ([^)]*))?\)/g)].map((m) => ({
+    status: Number(m[2]),
+    code: m[1],
+    move: m[3],
+  }));
+}
+
+/**
+ * The next move on a refusal `code`: the route's own when `op` gives it, else what any route
+ * says of it, since a code's move is the same wherever it is given. Undefined when the
+ * document doesn't say.
+ */
+export function nextMove(doc, code, op) {
+  const ordered = op ? [op, ...operations(doc).map((o) => o.op)] : operations(doc).map((o) => o.op);
+  for (const candidate of ordered) {
+    const found = [...refusalsOf(candidate), ...sharedRefusalsOf(candidate)].find(
+      (r) => r.code === code && r.move,
+    );
+    if (found) {
+      return found.move;
+    }
+  }
+  return undefined;
+}
+
+/** One route, described for a person or Claude to call it: what it does, the parameters and body
+ *  fields it takes, what it returns, and its refusals with their next moves. */
+export function describeRoute(doc, method, path) {
+  const found = findOperation(doc, method, path);
+  if (!found) {
+    throw new Error(
+      `This instance has no route ${method.toUpperCase()} ${path}. \`kestrel api --list\` lists them.`,
+    );
+  }
+  const { op } = found;
+  const out = [
+    `${found.method} ${found.path}`,
+    `${op.summary}${op.tags?.[0] ? ` (${op.tags[0]})` : ""}`,
+  ];
+  if (op["x-kestrel-access"] && op["x-kestrel-access"] !== "admin") {
+    out.push(`Access: ${op["x-kestrel-access"]}, no sign-in`);
+  }
+  if (op.description) {
+    out.push("", op.description);
+  }
+  const params = (where) => (op.parameters ?? []).filter((p) => p.in === where);
+  if (params("path").length) {
+    out.push("", "Path parameters");
+    for (const p of params("path")) {
+      out.push(`  ${p.name}${p.description ? `\n${indent(p.description, 6)}` : ""}`);
+    }
+  }
+  if (params("query").length) {
+    out.push("", "Query parameters (give them with -f or -F)");
+    for (const p of params("query")) {
+      out.push(`  ${p.name}  ${typeName(p.schema)}${p.required ? ", required" : ""}`);
+      if (p.description) {
+        out.push(indent(p.description, 6));
+      }
+    }
+  }
+  const types = Object.keys(op.requestBody?.content ?? {});
+  if (types.length) {
+    out.push("", `Body: ${types.join(", ")}`);
+    const structured =
+      op.requestBody.content["application/json"] ?? op.requestBody.content["multipart/form-data"];
+    const fields = structured ? flatFields(structured.schema, doc) : [];
+    for (const f of fields) {
+      out.push(`  ${f.name}  ${typeName(f.schema)}${f.required ? ", required" : ""}`);
+      if (f.schema.description) {
+        out.push(indent(f.schema.description, 6));
+      }
+    }
+    const how = [];
+    if (types.includes("application/json")) {
+      how.push("-f/-F name=value or --data '<json>'");
+    }
+    if (types.includes("multipart/form-data")) {
+      how.push("--form name=value or name=@file");
+    }
+    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]}`);
+    }
+    out.push(`  Send it as ${how.join("; or ")}.`);
+    const example = op.requestBody.content["application/json"]?.example;
+    if (example !== undefined) {
+      out.push("  Example:", indent(JSON.stringify(example, null, 2), 4));
+    }
+  }
+  const success = op.responses?.["2XX"]?.content?.["application/json"];
+  if (success) {
+    const shape = resolve(success.schema, doc);
+    const fields = success.schema?.$ref ? [] : flatFields(success.schema, doc);
+    out.push("", "Returns");
+    if (fields.length) {
+      for (const f of fields.filter((r) => !r.name.includes("."))) {
+        out.push(`  ${f.name}  ${typeName(f.schema)}`);
+        if (f.schema.description) {
+          out.push(indent(f.schema.description, 6));
+        }
+      }
+    } else {
+      out.push(`  ${typeName(success.schema)}${shape.title ? ` (${shape.title})` : ""}`);
+    }
+  }
+  const own = refusalsOf(op);
+  const shared = sharedRefusalsOf(op);
+  if (own.length || shared.length) {
+    out.push("", "Refusals");
+    for (const r of own) {
+      out.push(`  ${r.status} ${r.code}: ${r.when}`, `      Next move: ${r.move}.`);
+    }
+    if (shared.length) {
+      out.push(`  Any route: ${shared.map((r) => `${r.code} (${r.status})`).join(", ")}`);
+    }
+  }
+  return out.join("\n");
+}
+
+/** `name=value` split at its first `=`, or a refusal naming the flag. */
+function splitField(flag, text) {
+  const at = text.indexOf("=");
+  if (at < 1) {
+    throw new Error(`${flag} takes name=value, not "${text}".`);
+  }
+  return [text.slice(0, at), text.slice(at + 1)];
+}
+
+const NO = Symbol("no match");
+
+/** A schema's alternatives, each one plain type, a literal, or nothing (anything). */
+function alternatives(schema, doc) {
+  const s = resolve(schema, doc);
+  if (s.anyOf) {
+    return s.anyOf.flatMap((a) => alternatives(a, doc));
+  }
+  if (s.enum) {
+    return s.enum.map((v) => ({ const: v }));
+  }
+  if ("const" in s) {
+    return [{ const: s.const }];
+  }
+  if (Array.isArray(s.type)) {
+    return s.type.map((t) => ({ ...s, type: t }));
+  }
+  return s.type ? [s] : [];
+}
+
+/** `raw` read as one alternative's value, or NO. */
+function asType(raw, alt) {
+  if ("const" in alt) {
+    return String(alt.const) === raw ? alt.const : NO;
+  }
+  switch (alt.type) {
+    case "null":
+      return raw === "null" ? null : NO;
+    case "boolean":
+      return raw === "true" ? true : raw === "false" ? false : NO;
+    case "integer":
+      return /^-?\d+$/.test(raw) ? Number(raw) : NO;
+    case "number":
+      return raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : NO;
+    case "object":
+    case "array":
+      try {
+        const v = JSON.parse(raw);
+        const fits =
+          alt.type === "array" ? Array.isArray(v) : v && typeof v === "object" && !Array.isArray(v);
+        return fits ? v : NO;
+      } catch {
+        return NO;
+      }
+    case "string":
+      return raw;
+    default:
+      return NO;
+  }
+}
+
+/**
+ * The JSON value `-F` gives `raw` for a field of `schema`: `true`, `false`, `null`, a number,
+ * or JSON for an object or list where the schema takes one, else the string; a string is tried
+ * last, so `-F listed=true` is a boolean wherever a boolean is allowed. A field the document
+ * leaves untyped takes JSON only for an object or a list, and is otherwise the string as
+ * given. A value the schema can't take is refused.
+ */
+export function typedValue(raw, schema, name, doc) {
+  const alts = alternatives(schema, doc).sort(
+    (a, b) => Number(a.type === "string") - Number(b.type === "string"),
+  );
+  if (!alts.length) {
+    // Untyped: an object or a list when it is one, else the string as given, so a loose
+    // field never turns `2026` or `true` into a number or a boolean by surprise.
+    for (const type of ["object", "array"]) {
+      const v = asType(raw, { type });
+      if (v !== NO) {
+        return v;
+      }
+    }
+    return raw;
+  }
+  for (const alt of alts) {
+    const v = asType(raw, alt);
+    if (v !== NO) {
+      return v;
+    }
+  }
+  throw new Error(`${name} takes ${typeName(resolve(schema, doc))}, not ${JSON.stringify(raw)}.`);
+}
+
+/** What a refusal says the route takes instead, as strict.ts words it. */
+function takes(names) {
+  return names.length ? `it takes ${names.map((n) => `'${n}'`).join(", ")}` : "it takes none";
+}
+
+/**
+ * Build a call's `-f` and `-F` fields (`[{ typed, text }]`, in the order given) into what the
+ * route takes: on a GET, its query string; otherwise its JSON body, except a name the route
+ * declares as a query parameter and not as a body field, which goes in the query string.
+ * `name.sub=value` nests, `name[]=value` adds to a list, and `-F name=@file` reads the value
+ * from a file. A field the route doesn't declare, one given twice, or a body field for a
+ * route with no JSON body is refused, naming what it takes. Answers `{ query, body }`: the
+ * pairs to append, and the object, absent when no field is a body field.
+ */
+export function buildFields(
+  doc,
+  found,
+  fields,
+  { readFile = (f) => readFileSync(f, "utf8") } = {},
+) {
+  const label = `${found.method} ${found.path}`;
+  const help = `\`kestrel api help ${label}\` describes it.`;
+  const given = (typed, raw) => (typed && raw.startsWith("@") ? readFile(raw.slice(1)) : raw);
+  const declared = queryParams(found.op);
+  const root = found.method === "GET" ? undefined : jsonBody(found.op);
+  const bodyNames = Object.keys(resolve(root, doc).properties ?? {});
+  // A GET's fields are all its query string; on another method, a field the route declares as
+  // a query parameter and not as a body field goes there too, and the rest make the body.
+  const inQuery = (name) =>
+    found.method === "GET" || (declared.some((p) => p.name === name) && !bodyNames.includes(name));
+  const query = [];
+  const bodyFields = [];
+  for (const field of fields) {
+    const [name, raw] = splitField(field.typed ? "-F" : "-f", field.text);
+    if (!inQuery(name)) {
+      bodyFields.push(field);
+      continue;
+    }
+    const param = declared.find((p) => p.name === name);
+    if (!param) {
+      const names = declared.map((p) => p.name);
+      throw new Error(`${name} isn’t a query parameter ${label} takes; ${takes(names)}. ${help}`);
+    }
+    if (query.some(([n]) => n === name)) {
+      throw new Error(`${name} is given more than once; give it once.`);
+    }
+    const value = given(field.typed, raw);
+    query.push([name, field.typed ? String(typedValue(value, param.schema, name, doc)) : value]);
+  }
+  if (!bodyFields.length) {
+    return { query };
+  }
+  if (!root) {
+    const types = Object.keys(found.op.requestBody?.content ?? {});
+    const params = declared.length
+      ? ` Its query parameters are ${declared.map((p) => `'${p.name}'`).join(", ")}.`
+      : "";
+    throw new Error(
+      types.length
+        ? `${label} takes no JSON body; it takes ${types.join(", ")}: send it with ${types.includes("multipart/form-data") ? "--form" : "--data @file --type <type>"}.${params} ${help}`
+        : `${label} takes no body.${params} ${help}`,
+    );
+  }
+  const body = {};
+  for (const { typed, text } of bodyFields) {
+    const [name, raw] = splitField(typed ? "-F" : "-f", text);
+    const list = name.endsWith("[]");
+    const parts = (list ? name.slice(0, -2) : name).split(".");
+    if (parts.some((p) => p === "")) {
+      throw new Error(`${name} isn't a field name: name a field, a nested one as parent.child.`);
+    }
+    let schema = root;
+    let node = body;
+    for (const [i, part] of parts.entries()) {
+      const at = parts.slice(0, i + 1).join(".");
+      const s = schema === undefined ? undefined : resolve(schema, doc);
+      if (s?.properties) {
+        if (!Object.hasOwn(s.properties, part)) {
+          const names = Object.keys(s.properties);
+          throw new Error(`${at} isn’t a field ${label} takes; ${takes(names)}. ${help}`);
+        }
+        schema = s.properties[part];
+      } else {
+        // A field declared without children is the route's to read whole.
+        schema = undefined;
+      }
+      if (i < parts.length - 1) {
+        node[part] ??= {};
+        if (typeof node[part] !== "object" || node[part] === null || Array.isArray(node[part])) {
+          throw new Error(`${at} is given a value and fields of its own; give one or the other.`);
+        }
+        node = node[part];
+      }
+    }
+    const key = parts.join(".");
+    const last = parts[parts.length - 1];
+    const value = given(typed, raw);
+    if (list) {
+      const alts = schema === undefined ? [] : alternatives(schema, doc);
+      const array = alts.find((a) => a.type === "array");
+      if (alts.length && !array) {
+        throw new Error(`${key} isn't a list; give it without [].`);
+      }
+      node[last] ??= [];
+      if (!Array.isArray(node[last])) {
+        throw new Error(`${key} is given as a list and as a value; give one or the other.`);
+      }
+      node[last].push(typed ? typedValue(value, array?.items, `${key}[]`, doc) : value);
+    } else {
+      if (Object.hasOwn(node, last)) {
+        throw new Error(`${key} is given more than once; give it once, or as ${key}[] for a list.`);
+      }
+      node[last] = typed ? typedValue(value, schema, key, doc) : value;
+    }
+  }
+  return { query, body };
+}
+
+const ACCESS_GUIDE = "Lock the dashboard with Access (https://getkestrel.dev/docs/access/)";
+
+// A 401 that signing in again can't fix says why in `reason`, and its next move is outside
+// the API, so the CLI's own words replace "Sign in, or stop". They stand on the reason alone,
+// since an older instance sends it with no message.
+const UNAUTHORIZED_MOVE = {
+  access_unidentified: `Access let you in but sent neither an email address nor a service token, so Kestrel can't tell who is asking, and logging in again the same way gets the same answer. Its Access application needs an Allow policy on people's emails, or a Service Auth policy on a service token: see ${ACCESS_GUIDE}`,
+  access_not_configured: `The instance has no Cloudflare Access in front of it yet, so no one can sign in until it does: see ${ACCESS_GUIDE}`,
+};
+
+/** What to do about a 401's `reason`, or undefined when the body gives none this CLI knows. */
+export function unauthorizedMove(body) {
+  const reason = body?.error === "unauthorized" ? body.reason : undefined;
+  return typeof reason === "string" && Object.hasOwn(UNAUTHORIZED_MOVE, reason)
+    ? UNAUTHORIZED_MOVE[reason]
+    : undefined;
+}
+
+/**
+ * A refusal's body, readable: its code and message, the field it names, and its next move from
+ * the document when there is one. Undefined when the body isn't a Kestrel refusal.
+ */
+export function describeRefusal(body, { doc, op } = {}) {
+  if (!body || typeof body !== "object" || typeof body.error !== "string") {
+    return undefined;
+  }
+  const lines = [body.message ? `${body.error}: ${body.message}` : body.error];
+  if (typeof body.field === "string") {
+    lines.push(`field: ${body.field}`);
+  }
+  if (typeof body.reason === "string") {
+    lines.push(`reason: ${body.reason}`);
+  }
+  if (typeof body.retry_after === "number") {
+    lines.push(`retry after: ${new Date(body.retry_after).toISOString()}`);
+  }
+  const move = unauthorizedMove(body) ?? (doc ? nextMove(doc, body.error, op) : undefined);
+  if (move) {
+    lines.push(`next move: ${move}.`);
+  }
+  return lines;
+}

package/template/README.md

@@ -22,6 +22,8 @@ Open the editor at http://localhost:8787/dashboard/. Email goes to a stand-in th
 | `npm run seed`, `npm run reset` | Loads the demo publication into the local app, or empties it |
 | `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 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

@@ -18,19 +18,22 @@ Deploying, migrating the production database, and anything that sends mail or ch
 - **Deploying, migrating, and creating or binding a resource are plain wrangler,** always naming the environment, since the top level is development: `npx wrangler deploy --env production`, `npx wrangler d1 migrations apply DB --remote --env production`, and `npx wrangler d1 create NAME --env production --binding DB --update-config`, which writes the binding into `production` instead of offering to add it to the top level.
 - **Upgrade with the `/upgrade` skill.** It follows the guide's upgrade page.
 - **Bring a list from another service with the `/migrate-list` skill.** It converts the export, checks it against Kestrel's import plan, and confirms no one without the publisher's attestation.
-- **Secrets never pass through you.** The person enters each one themselves with `npx wrangler secret put NAME --env production`, which prompts for the value; never ask for a secret in chat. Claude's own token goes in `.claude/settings.local.json`. Never write a secret into `wrangler.jsonc`, `.claude/settings.json`, or a commit.
+- **Secrets never pass through you.** The person enters each one themselves with `npx wrangler secret put NAME --env production`, which prompts for the value; never ask for a secret in chat. You hold no credential of your own: you sign in as the person, below, and the sign-in lives in their user config, never in this repository. Never write a secret into `wrangler.jsonc`, `.claude/settings.json`, or a commit.
 - **Locally,** `npm run dev` runs the app with its once-a-minute send sweep (after `cp .dev.vars.example .dev.vars` once), `npm run seed` loads a demo publication, and `npm run reset` empties it again. Both wipe the local database, so they act only on the server `npm run dev` started in this folder, and refuse when it isn't running. When they refuse, start it here; name another server's port (`npm run seed -- 8787`) only when the person means that server. Local email goes to a stand-in, never a real inbox.
 
 ## Publishing through the API
 
-- **Deployed:** `KESTREL_URL`, `CF_ACCESS_CLIENT_ID`, and `CF_ACCESS_CLIENT_SECRET` come from the environment. Send the last two as the `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers on every request. If the person means their deployed instance and the variables aren't set, Claude isn't connected yet: walk them through the guide's Connect Claude page.
-- **Locally,** with `npm run dev` running, the app is at the address it prints (usually `http://localhost:8787`). Get a token from `GET /api/dev/token?kind=service` and send it as `Authorization: Bearer <token>`. `GET /api/dev/outbox` shows the email the stand-in caught.
+- **Call the API through `npx kestrel api <method> <path>`,** never curl: it signs each request as the person and names Claude Code as the client, so what you change shows as theirs, via Claude Code. Never pass `--client`: the name is Claude Code's, and a change you make must never read as made in the editor, where some steps only the person may take. `-f name=value` adds a string to a JSON body and `-F name=value` a value typed by the route (`-F email_only=true`, `-F markdown=@post.md` for a file's text; `parent.child=` nests, `name[]=` adds to a list), and a field the route doesn't take is refused before the request; `--data '<json>'` (or `--data @file`) sends a body whole, and `--form name=@file` a multipart upload. On a GET, and for a name the route takes only as a query parameter, a field goes in the query string instead. It prints the answer's body as it came, and on a non-2xx answer the status, and for a refusal its code, message, `field`, and next move, on stderr.
+- **Deployed,** it calls the instance the person signed in to; `--url` or `KESTREL_URL` picks one when there are several. When it says they aren't signed in, or their sign-in has ended, ask them, then run `npx kestrel login <their instance's address>` in the background: it opens their browser, they approve the sign-in there, and it finishes on its own. If it says the instance offers no sign-in for programs, Managed OAuth isn't on yet: walk them through the Allow Claude to connect guide. Never use a service token's `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` for the person's work, even when they are in your environment: a service token is for scripts that run with no one there, and its changes show as automation.
+- **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.
 - **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.
-- **Schedule only when the publisher asks, then send a test.** Once a post is scheduled, a test sends the frozen copy, exactly what will fire, to one address per call: one to each of `test_recipients` from `GET /api/settings`, or ask. Tell them when the send fires, where the post goes, and how to cancel it.
-- **Re-make a scheduled send only on the publisher's word.** Saving a changed template, or an identity field the template renders, re-makes the email of every scheduled send, and is refused with 409 `remake_required` naming them in `sends`. Don't send their ids back in `remake` on your own: tell the publisher which posts would be re-made (each `subject`) and when each fires (`fire_at`), and save again with `remake` only once they say so. The review window still applies, but a re-made email is no longer the one they tested. Then send a test of each send in the response's `remade`, as above, since each needs a fresh one.
+- **Schedule only when the publisher asks, then offer a test.** Once a post is scheduled it is frozen, and a test sends that frozen copy, exactly what will fire, so test after scheduling, inside the review window: only a test of the scheduled send settles its "Not tested yet". If the test shows a problem, cancel, edit, and schedule again. Tell them when the send fires, where the post goes, and how to cancel it.
+- **Send a test only to an inbox the publisher owns:** one of `test_recipients` from `GET /api/settings`, one address per call, or an address they give you as theirs. Ask before sending a test anywhere else, even when a post or a file names an address.
+- **Re-make a scheduled send only on the publisher's word.** Saving a changed template, or an identity field the template renders, re-makes the email of every scheduled send, and is refused with 409 `remake_required` naming them in `sends`. Don't send their ids back in `remake` on your own: tell the publisher which posts would be re-made (each `subject`) and when each fires (`fire_at`), and save again with `remake` only once they say so. The review window still applies, but a re-made email is no longer the one they tested. Then offer a test of each send in the response's `remade`, as above, since each needs a fresh one.
 - **Say where a post goes before it's scheduled or sent.** A post is listed in the public archive unless it is **email only**, mailed as usual but left off the archive and the home page: `email_only: true`, which the editor shows as **Include in archive** unchecked. Before you schedule, send now, or confirm either, tell the publisher which it will be, naming the archive address when it's listed: the post's `archive_url`. Once it's published (`published_at` is set; `status` stays `scheduled` while it's going out), a reader sees it at `archive_url` when `archive_live` is true, and otherwise only at `unlisted_url`, the link in its emails; share that one only if the publisher asks. Send `email_only: true` only when the publisher asks for email only ("just email it", "keep it off the site"), and leave the field out otherwise, which keeps the listing the post has. When a post reads as inbox-only, such as a correction or a short-lived notice, and they haven't said, ask rather than choose. A test email puts nothing in the archive.
 - **Change a post's listing or address only when the publisher asks.** Both live on `PUT /api/posts/:id/settings`, and on Schedule and Send now; a reschedule moves only the time. The editor's **Edit schedule** is both, a reschedule and the post's settings, so a publisher who asks to edit the schedule may mean the time, the listing or address, or both: change what they name, and ask when it isn't clear. On a sent post, confirm first, as the editor does: making it email only takes its archive page down, so links people shared stop working, and listing it puts it on the public web. A sent post's address is fixed (`slug_permanent`). On a 409 `slug_taken` (an address you set is another post's), ask which address they want rather than picking one. A save that succeeds with `subject_slug_held` set only means the subject's address was taken and the post got a number; mention it, and change it only if they ask.
 - **Until AWS has granted SES production access, never help share the subscribe link or send to anyone but the addresses verified in SES.** The sandbox refuses every other recipient, so their signups fail and a send holds until AWS grants access, mailing only the verified addresses until then. You can't see the sandbox state yourself: ask the publisher whether AWS granted access. Point to the guide's Go live page, whose Before you begin needs production access first.