@columenlabs/lumen-ship 0.0.0-stage → 0.1.30

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Columen Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+Lumen
+Copyright (c) 2026 Columen Labs. Licensed under the MIT License (see LICENSE).
+
+Lumen draws price and market charts with TradingView Lightweight Charts™
+(https://github.com/tradingview/lightweight-charts), Copyright (c) 2025
+TradingView, Inc., licensed under the Apache License 2.0. Lumen turns off the
+chart's own logo, so per that library's NOTICE, an app that shows these charts
+should link to https://www.tradingview.com/ somewhere a user can find it (an
+About page or footer is enough).
+
+The components under packages/ui/src/ui are based on shadcn/ui
+(https://ui.shadcn.com), MIT License, Copyright (c) 2023 shadcn.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @columenlabs/lumen-ship
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lumen's shipping kit: one release command that writes each release's notes with Claude, the changelog What's new reads, and the lint guards every Lumen app runs. Bash plus a small TypeScript reader, no framework.
+
+- Docs: https://lumen.columenlabs.com/docs/
+- For agents: https://lumen.columenlabs.com/llms.txt
+- Source: https://github.com/columenlabs/lumen (`packages/ship`). MIT.
+
+## Install
+
+```bash
+bun add -d @columenlabs/lumen-ship
+```
+
+Pin it to the same exact version as the other Lumen packages. The command needs `bash`, `git`, `gh` (with REST access to the repo), `jq` and `curl`.
+
+## Releases
+
+`lumen-ship release` cuts a repo's GitHub releases. Run it from the repo root, on each merge to `main` (a CI job) or by hand.
+
+| Command | What it does |
+|---|---|
+| `lumen-ship release` | One patch release at `main` once `cadence.every` merges landed since the newest release tag, or on the first merge `cadence.days` days after it. `FORCE=1` cuts it now |
+| `lumen-ship release minor` | Tags `main` as the next minor. Its notes are the hand-written `docs/releases/v<major>.<minor>.0.md`, which must be on `main` |
+| `lumen-ship release notes` | Sets the newest minor's notes from its file again |
+| `lumen-ship release tag v1.2.3` | Makes the release of a tag that already exists (for a publish job that tags first). `REDO=1` writes its notes again |
+
+`DRY_RUN=1` prints what it would do and creates nothing.
+
+### Notes
+
+Claude writes each release's notes from the merged pull requests since the tag before (commits stand in where there are none), from your prompt. A reply is published only when whole: anything cut short, refused or failed is asked again, at most 3 times, then the release fails. Without `ANTHROPIC_API_KEY` the notes are GitHub's own list of pull requests.
+
+Set `LUMEN_FORBIDDEN_NAMES` (a regex alternation, `A|B`) in a public repo: notes that name one are asked again and never published, and the pull request list shows numbers only.
+
+### Changelog for What's new
+
+With `changelog.path` set, each release's Key takeaways are also committed to `main` as JSON, newest first, and the tag goes on that commit, so the release deploys its own notes. Each takeaway bullet opens with tags: type tags (`[Feature]`, `[Improvement]`, `[Fix]`, `[Performance]`, `[Security]`) become its chips, and tags listed in `changelog.apps` become its `apps`. Ask for them in your prompt:
+
+```md
+- [Fix] [Console] **Exports finish**: ...
+```
+
+```json
+[{ "tag": "v0.3.2", "published_at": "2026-10-24T18:00:00Z",
+   "takeaways": [{ "text": "**Exports finish**: ...", "types": ["fix"], "apps": ["console"] }] }]
+```
+
+Serve it to `WhatsNew` (`LumenShell`'s `releases` prop) with the reader:
+
+```ts
+import { RELEASES_HEADERS, listReleases, type Release } from '@columenlabs/lumen-ship/releases';
+import changelog from './changelog.json';
+
+app.get('/api/releases', (c) =>
+  c.json(
+    { releases: listReleases(changelog as Release[], {
+        limit: c.req.query('limit'),
+        before: c.req.query('before'),
+        canSee: (apps) => apps.some((a) => mayOpen(c, a)),   // optional
+      }) },
+    200,
+    RELEASES_HEADERS,
+  ),
+);
+```
+
+`listReleases` pages newest first (`limit` 1 to 50, 20 by default; `before` an ISO time) and, with `canSee`, keeps a takeaway about some apps only for people who may open one of them.
+
+### `lumen-ship.json`
+
+At the repo root (or the path in `LUMEN_SHIP_CONFIG`):
+
+```json
+{
+  "repo": "owner/name",
+  "notes": { "prompt": ".github/release-prompt.md", "model": "claude-sonnet-5-5", "maxTokens": 16000 },
+  "changelog": { "path": "src/changelog.json", "apps": { "console": "console", "api": "api" } },
+  "tags": "v0.*",
+  "promote": "release",
+  "cadence": { "every": 10, "days": 7 }
+}
+```
+
+| Key | |
+|---|---|
+| `repo` | The GitHub repo the releases go on. Required |
+| `notes.prompt` | A file with the prompt; `{tag}` becomes the release's tag. Required |
+| `notes.model`, `notes.maxTokens` | The model and its output limit (the model thinks first, so keep it large) |
+| `changelog.path` | Where the What's new JSON lives on `main`; left out, no changelog |
+| `changelog.apps` | Tag (lower case) → app id, for takeaways about one app |
+| `tags` | The release tags as a git glob, `v[0-9]*` by default; narrow it when older tags of another scheme sort higher |
+| `promote` | A branch fast-forwarded to each new release (a production deploy branch, say) |
+| `cadence.every`, `cadence.days` | When a patch is due. `RELEASE_EVERY` overrides `every` |
+
+## Lint guards
+
+```bash
+lumen-ship check kit-neutral [paths]   # no name from LUMEN_FORBIDDEN_NAMES (default: src package.json README.md)
+lumen-ship check suppressions          # a useExhaustiveDependencies suppression needs a reason of 3+ words
+lumen-ship check settings-copy         # a Settings section description is one plain line of 64 characters or less
+lumen-ship check magic-numbers         # hard-coded px/rem class values may only go down
+```
+
+Run each from a package folder in its `lint` script. `magic-numbers` reads the repo's `scripts/magic-numbers.baseline` (or `LUMEN_SHIP_BASELINE`): one `<folder> <count>` a line, lowered in the change that removes one.
+
+## Versions
+
+0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

package/bin/lumen-ship

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# lumen-ship: releases and lint guards shared by every app. Run from the repo root.
+#   lumen-ship release [patch | minor | notes | tag v<version>]   see scripts/release.sh
+#   lumen-ship check suppressions | settings-copy | magic-numbers | kit-neutral [paths]
+set -euo pipefail
+here=$(cd "$(dirname "$(readlink -f "$0")")/../scripts" && pwd)
+cmd=${1:-}
+shift || true
+case "$cmd" in
+  release) exec "$here/release.sh" "$@" ;;
+  check)
+    name=${1:-}
+    shift || true
+    case "$name" in
+      suppressions | settings-copy | magic-numbers | kit-neutral) exec "$here/check-$name.sh" "$@" ;;
+    esac
+    echo "usage: lumen-ship check suppressions | settings-copy | magic-numbers | kit-neutral" >&2
+    exit 1
+    ;;
+esac
+echo "usage: lumen-ship release [patch | minor | notes | tag v<version>] | lumen-ship check <name>" >&2
+exit 1

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './releases.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './releases.js';

package/dist/releases.d.ts

@@ -0,0 +1,29 @@
+/** A takeaway's coloured chips in What's new, one or more. */
+export type ReleaseType = 'feature' | 'improvement' | 'fix' | 'performance' | 'security';
+export interface Takeaway {
+    /** One Key takeaways bullet, markdown, its tags taken off. */
+    text: string;
+    types: ReleaseType[];
+    /** The apps it is about, from `changelog.apps` in lumen-ship.json; left out: everyone's. */
+    apps?: string[];
+}
+export interface Release {
+    tag: string;
+    /** ISO time; pages are cut by it, newest first. */
+    published_at: string;
+    takeaways: Takeaway[];
+}
+export interface ListReleasesOptions {
+    /** How many, 1 to 50; 20 when left out or not a number. */
+    limit?: number | string | null;
+    /** Only releases published before this ISO time (the last one of the page before). */
+    before?: string | null;
+    /** Keeps a takeaway about some apps only for people who may open one of them. */
+    canSee?: (apps: string[]) => boolean;
+}
+/** One page of releases, newest first. A release left with no takeaways keeps its tag. */
+export declare function listReleases(releases: Release[], options?: ListReleasesOptions): Release[];
+/** The response headers What's new expects: private, and cached five minutes. */
+export declare const RELEASES_HEADERS: {
+    readonly 'cache-control': 'private, max-age=300';
+};

package/dist/releases.js

@@ -0,0 +1,17 @@
+// What's new: the releases a repo's `lumen-ship release` wrote into its changelog JSON, served the
+// way @columenlabs/lumen-ui's WhatsNew reads them (`GET ?limit=&before=` answering `{releases}`).
+// No framework: an app mounts `listReleases` on whatever router it runs.
+/** One page of releases, newest first. A release left with no takeaways keeps its tag. */
+export function listReleases(releases, options = {}) {
+    const limit = Math.min(Math.max(Number(options.limit) || 20, 1), 50);
+    const { before, canSee } = options;
+    const list = (before ? releases.filter((r) => r.published_at < before) : releases).slice(0, limit);
+    if (!canSee)
+        return list;
+    return list.map((r) => ({
+        ...r,
+        takeaways: r.takeaways.filter((t) => !t.apps?.length || canSee(t.apps)),
+    }));
+}
+/** The response headers What's new expects: private, and cached five minutes. */
+export const RELEASES_HEADERS = { 'cache-control': 'private, max-age=300' };

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@columenlabs/lumen-ship",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.30",
+  "description": "Lumen's shipping kit: release notes, the What's new changelog and lint guards.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./releases": {
+      "types": "./dist/releases.d.ts",
+      "default": "./dist/releases.js"
+    }
+  },
+  "bin": {
+    "lumen-ship": "bin/lumen-ship"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "bin",
+    "scripts"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "homepage": "https://github.com/columenlabs/lumen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/columenlabs/lumen.git",
+    "directory": "packages/ship"
+  },
+  "bugs": "https://github.com/columenlabs/lumen/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {}
+}

package/scripts/check-kit-neutral.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# A shared package names no product: no app's names in code or copy, and no import of an app's
+# own packages. An app passes its names through `configureLumen` and its data through
+# `registerDomains`. The names to refuse are kept outside the repo, in the environment variable
+# LUMEN_FORBIDDEN_NAMES (a regex alternation, `A|B|C`); CI reads it from the repository variable
+# of the same name, and the check is skipped where it is not set. Comments count too.
+# Run from a package folder by its lint script; pass other folders to check those instead.
+set -euo pipefail
+names=${LUMEN_FORBIDDEN_NAMES:-}
+[ -n "$names" ] || exit 0
+targets=("$@")
+[ ${#targets[@]} -gt 0 ] || targets=(src package.json README.md)
+bad=$(grep -rnE "\b($names)\b" "${targets[@]}" || true)
+if [ -n "$bad" ]; then
+  echo "The kit names no product: pass names through configureLumen, data through registerDomains:" >&2
+  echo "$bad" >&2
+  exit 1
+fi

package/scripts/check-magic-numbers.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# No new hard-coded lengths: a pixel or rem value written into a class
+# (`left-[17px]`, `text-[11px]`) is a band-aid sized for one screen, and the next layout change
+# breaks it. Use a token, a CSS variable or a Tailwind scale step instead.
+# The count may only fall: the repo's scripts/magic-numbers.baseline (or LUMEN_SHIP_BASELINE) holds
+# each package's count today, one `<folder> <count>` a line; lower it in the change that removes one.
+# Run from a package folder by its lint script.
+set -euo pipefail
+baseline=${LUMEN_SHIP_BASELINE:-$(git rev-parse --show-toplevel)/scripts/magic-numbers.baseline}
+pkg=$(basename "$PWD")
+# `|| true`: a package with none (grep finds nothing) passes.
+n=$({ grep -rEoh --include=*.tsx --include=*.ts -- '-?\b[a-z-]+-\[-?[0-9.]+(px|rem)\]' src || true; } | wc -l | tr -d ' ')
+base=$( [ -f "$baseline" ] && awk -v p="$pkg" '$1 == p { print $2 }' "$baseline" || true)
+base=${base:-0}
+if [ "$n" -gt "$base" ]; then
+  echo "$pkg: $n hard-coded px/rem class values, baseline $base. Use a token or CSS variable:" >&2
+  grep -rnE --include=*.tsx --include=*.ts -- '-?\b[a-z-]+-\[-?[0-9.]+(px|rem)\]' src >&2
+  exit 1
+fi

package/scripts/check-settings-copy.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# A Settings section's description is one line, never wrapped: a plain string
+# of at most 64 characters, which fits the section header on desktop (the header truncates it on a
+# phone). Run from a package folder by its lint script.
+set -euo pipefail
+MAX=64
+bad=$({ grep -rlE "SettingsSectionDef" src --include='*.tsx' || true; } | xargs -r perl -0777 -ne '
+  while (/icon:\s*\w+,\s*(?:sub:\s*true,\s*)?description:\s*(\x27([^\x27]*)\x27|"([^"]*)"|[^\x27"\s][^,\n]*)/g) {
+    my $text = defined $2 ? $2 : $3;
+    if (!defined $text) { print "$ARGV: description is not a plain string: $1\n"; next; }
+    print "$ARGV: ", length($text), " characters (max '"$MAX"'): $text\n" if length($text) > '"$MAX"';
+  }')
+if [ -n "$bad" ]; then
+  echo "Settings descriptions must fit on one line:" >&2
+  echo "$bad" >&2
+  exit 1
+fi

package/scripts/check-suppressions.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Switching off React's "missing dependency" lint says why, in at least three words: a silenced
+# dependency is how an effect loops or reads stale state, so each one carries its reason for the
+# next reader.
+# Run from a package folder by its lint script.
+set -euo pipefail
+bad=$(grep -rnE "biome-ignore lint/correctness/useExhaustiveDependencies" src \
+  | awk -F'useExhaustiveDependencies:?' '{ n = split($2, w, " "); if (n < 3) { split($0, a, ":"); print a[1] ":" a[2] } }' || true)
+if [ -n "$bad" ]; then
+  echo "A useExhaustiveDependencies suppression needs its reason (three words or more):" >&2
+  echo "$bad" >&2
+  exit 1
+fi

package/scripts/release.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# Cut a repo's GitHub releases with notes Claude writes from the merged pull requests, through the
+# GitHub REST API. Run from the repo's root, which holds lumen-ship.json (see the package README).
+#   lumen-ship release            one patch release at main once `cadence.every` first-parent merges
+#                                 landed since the latest release tag (`tags`, default v[0-9]*),
+#                                 or on the first merge `cadence.days` days after it; FORCE=1
+#                                 cuts it now
+#   lumen-ship release minor      tag main as the next minor; its notes are the hand-written
+#                                 docs/releases/v<major>.<minor>.0.md (required)
+#   lumen-ship release notes      set the latest minor release's notes from its file again
+#   lumen-ship release tag v1.2.3 make the release of a tag that already exists (a publish
+#                                 workflow tagged it); REDO=1 writes its notes again
+#   DRY_RUN=1 lumen-ship release  print what it would do, create nothing
+# With `changelog.path` set, each release's Key takeaways are also committed to main as JSON
+# (What's new reads them, @columenlabs/lumen-ship/releases) and the tag goes on that commit, so
+# the release deploys its own notes. With `promote` set, that branch is fast-forwarded to the
+# release. Needs gh with REST access to the repo, jq and curl; the notes need ANTHROPIC_API_KEY,
+# and without one they are GitHub's own list of pull requests. Notes that name anything in
+# LUMEN_FORBIDDEN_NAMES are asked again, then the release fails (for public repos).
+set -euo pipefail
+CONFIG=${LUMEN_SHIP_CONFIG:-lumen-ship.json}
+[ -f "$CONFIG" ] || { echo "no $CONFIG here: run from the repo root (see lumen-ship's README)" >&2; exit 1; }
+cfg() { jq -r "$1 // empty" "$CONFIG"; }
+REPO=$(cfg .repo)
+[ -n "$REPO" ] || { echo "$CONFIG needs repo (owner/name)" >&2; exit 1; }
+PROMPT_FILE=$(cfg .notes.prompt)
+[ -n "$PROMPT_FILE" ] && [ -f "$PROMPT_FILE" ] || { echo "$CONFIG notes.prompt must name a file" >&2; exit 1; }
+MODEL=$(cfg .notes.model); MODEL=${MODEL:-claude-sonnet-5-5}
+MAX_TOKENS=$(cfg .notes.maxTokens); MAX_TOKENS=${MAX_TOKENS:-16000}
+CHANGELOG=$(cfg .changelog.path)
+APPS=$(jq -c '.changelog.apps // {}' "$CONFIG")
+PROMOTE=$(cfg .promote)
+EVERY=${RELEASE_EVERY:-$(cfg .cadence.every)}; EVERY=${EVERY:-10}
+DAYS=$(cfg .cadence.days); DAYS=${DAYS:-7}
+# The release tags, as a git glob: narrow it when the repo keeps tags of an older scheme.
+TAGS=$(cfg .tags); TAGS=${TAGS:-v[0-9]*}
+DRY_RUN=${DRY_RUN:-0}
+FORCE=${FORCE:-0}
+REDO=${REDO:-0}
+MODE=${1:-patch}
+TMP=${RUNNER_TEMP:-/tmp}
+git fetch -q origin main --tags
+
+named() { # text: the forbidden names it carries, if any
+  [ -n "${LUMEN_FORBIDDEN_NAMES:-}" ] || return 0
+  grep -oiE "\b(${LUMEN_FORBIDDEN_NAMES})\b" <<< "$1" | sort -u | tr '\n' ' ' || true
+}
+
+notes() { # tag sha previous-tag: Claude's notes from the pull requests (or commits) between them
+  local range=${3:+$3..}$2
+  prs=$(git log --first-parent --format=%s "$range" | grep -oE '\(#[0-9]+\)$' | tr -dc '0-9\n' || true)
+  pulls=$(for n in $prs; do
+    gh api "repos/$REPO/pulls/$n" --jq '{number, title, body, login: .user.login}' \
+      || { echo "could not read PR #$n" >&2; return 1; }
+  done) || return 1
+  if [ -n "$pulls" ]; then
+    input=$(jq -r '"## #\(.number) \(.title)\n\((.body // "") | .[0:1500])\n"' <<< "$pulls")
+    if [ -n "${LUMEN_FORBIDDEN_NAMES:-}" ]; then # titles are checked by no one: numbers only
+      list=$(jq -r '"- #\(.number) by @\(.login)"' <<< "$pulls")
+    else
+      list=$(jq -r '"- #\(.number) \(.title) (@\(.login))"' <<< "$pulls")
+    fi
+    count="Pull requests ($(echo "$prs" | wc -w | tr -d ' '))"
+  else # commits straight to main, like a first release: their messages stand in
+    input=$(git log --first-parent --format='## %s%n%b' "$range" | cut -c1-1500)
+    list=$(git log --first-parent --format='- %h' "$range")
+    count="Commits ($(echo "$list" | wc -l | tr -d ' '))"
+  fi
+  prompt=$(sed "s/{tag}/$1/g" "$PROMPT_FILE")
+  body=$(jq -n --arg model "$MODEL" --argjson max "$MAX_TOKENS" --arg text "$prompt"$'\n\n'"$input" \
+    '{model: $model, max_tokens: $max, messages: [{role: "user", content: $text}]}')
+  # The model thinks before it writes, so a small max_tokens runs out. Only a whole reply that
+  # names nothing forbidden is published (a release once went out cut mid-sentence). Anything
+  # else (max_tokens, a refusal, an error, a forbidden name) is asked again, at most 3 times.
+  text=
+  for attempt in 1 2 3; do
+    reply=$(curl -sS https://api.anthropic.com/v1/messages \
+      -H "x-api-key: $ANTHROPIC_API_KEY" -H 'anthropic-version: 2023-06-01' \
+      -H 'content-type: application/json' -d "$body")
+    text=$(jq -r 'if .stop_reason == "end_turn"
+      then [.content[]? | select(.type == "text") | .text] | join("") else "" end' <<< "$reply")
+    if [ -n "$text" ] && [ -n "$(named "$text")" ]; then
+      echo "attempt $attempt named a forbidden name; asking again" >&2
+      text=
+    elif [ -z "$text" ]; then
+      # show why, without the key
+      jq -c '{type, error, stop_reason, model, blocks: [.content[]?.type]}' <<< "$reply" >&2
+    fi
+    [ -n "$text" ] && break
+    sleep $((attempt * 5))
+  done
+  [ -n "$text" ] || return 1
+  printf '%s' "$text"
+  printf '\n\n## %s\n%s\n' "$count" "$list"
+  [ -z "${3:-}" ] || printf '\nFull changelog: https://github.com/%s/compare/%s...%s\n' "$REPO" "$3" "$1"
+}
+
+write_notes() { # tag sha previous-tag [notes-file]: the notes for a release
+  if [ -n "${4:-}" ]; then
+    cat "$4"
+  elif [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+    notes "$1" "$2" "${3:-}" || { echo "Claude wrote no notes for $1" >&2; return 1; }
+  else
+    echo "ANTHROPIC_API_KEY is not set: the notes are GitHub's list of pull requests" >&2
+    gh api -X POST "repos/$REPO/releases/generate-notes" -f tag_name="$1" -f target_commitish="$2" \
+      ${3:+-f previous_tag_name="$3"} --jq .body
+  fi
+}
+
+# Each Key takeaways bullet opens with its type tags, then app tags from changelog.apps:
+# `- [Feature] [Fix] [Console] **Headline**: ...`. Type tags become the takeaway's chips, mapped
+# app tags its `apps` (an app may show it only to people who can open one); unknown tags drop.
+TAGS_JQ='map(capture("^(?<tags>(\\[[A-Za-z]+\\][ \t]*)*)(?<text>.*)$")
+  | [.tags | scan("\\[([A-Za-z]+)\\]")[0] | ascii_downcase] as $tags
+  | {text, types: [$tags[] | select(IN("feature", "improvement", "fix", "performance", "security"))] | unique,
+     apps: [$tags[] | $apps[.] // empty] | unique}
+  | if .apps == [] then del(.apps) else . end)'
+changelog() { # tag published_at notes sha: commit the takeaways to main; prints the commit to tag
+  [ -n "$CHANGELOG" ] || { echo "$4"; return; }
+  bullets=$(printf '%s\n' "$3" | awk '
+    /^#{1,3}[ \t]/ { if (inside) exit; inside = tolower($0) ~ /key takeaways/; next }
+    inside && /^[ \t]*[-*][ \t]+/ { sub(/^[ \t]*[-*][ \t]+/, ""); print }' \
+    | jq -R . | jq -s --argjson apps "$APPS" "$TAGS_JQ")
+  commit=
+  for attempt in 1 2 3; do
+    file=$(gh api "repos/$REPO/contents/$CHANGELOG?ref=main") || break
+    next=$(jq -r .content <<< "$file" | base64 -d | jq --arg tag "$1" --arg at "$2" --argjson t "$bullets" \
+      '[{tag: $tag, published_at: $at, takeaways: $t}] + map(select(.tag != $tag))
+       | sort_by(.published_at) | reverse')
+    # A GITHUB_TOKEN commit starts no workflow, and the patch count skips `changelog:` commits.
+    commit=$(gh api -X PUT "repos/$REPO/contents/$CHANGELOG" -f message="changelog: $1" -f branch=main \
+      -f sha="$(jq -r .sha <<< "$file")" -f content="$(printf '%s\n' "$next" | base64 -w0)" \
+      --jq '[.commit.sha, .commit.parents[0].sha] | join(" ")') && break
+    commit=
+    sleep $((attempt * 2))
+  done
+  [ -n "$commit" ] || echo "could not write $1 to $CHANGELOG" >&2
+  read -r new parent <<< "${commit:-}"
+  # Tag the changelog commit when it sits right on the release; else the release's own commit
+  # (main moved, or the write failed: the release stands and the next one carries its notes).
+  if [ "${parent:-}" = "$4" ]; then echo "$new"; else echo "$4"; fi
+}
+
+promote() { # sha: fast-forward the promote branch to it, creating it the first time
+  [ -n "$PROMOTE" ] || return 0
+  if gh api "repos/$REPO/git/ref/heads/$PROMOTE" > /dev/null 2>&1; then
+    gh api -X PATCH "repos/$REPO/git/refs/heads/$PROMOTE" -f sha="$1" -F force=false > /dev/null
+  else
+    gh api -X POST "repos/$REPO/git/refs" -f ref="refs/heads/$PROMOTE" -f sha="$1" > /dev/null
+  fi
+  echo "$PROMOTE -> $(git log -1 --format='%h' "$1")"
+}
+
+release() { # tag sha previous-tag [notes-file]: a new tag and its release
+  if [ "$DRY_RUN" = 1 ]; then
+    echo "would cut $1 (since ${3:-the start}) at $(git log -1 --format='%h %s' "$2")"
+    [ -z "$PROMOTE" ] || echo "and move $PROMOTE to it"
+    return
+  fi
+  body=$(write_notes "$@") || exit 1
+  bad=$(named "$body")
+  [ -z "$bad" ] || { echo "$1 notes name $bad: not published" >&2; exit 1; }
+  sha=$(changelog "$1" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$body" "$2")
+  at=$(gh api -X POST "repos/$REPO/releases" \
+    -f tag_name="$1" -f target_commitish="$sha" -f name="$1" -f body="$body" --jq .published_at)
+  echo "$1 $(git log -1 --format='%h %s' "$2" 2> /dev/null || echo "$sha") $at"
+  promote "$sha"
+}
+
+LATEST=$(git tag --list "$TAGS" --sort=-v:refname | head -1)
+case "$MODE" in
+  tag)
+    TAG=${2:?usage: lumen-ship release tag v<version>}
+    git rev-parse -q --verify "refs/tags/$TAG" > /dev/null || { echo "no tag $TAG" >&2; exit 1; }
+    PREV=$(git tag --list "$TAGS" --sort=-v:refname | awk -v t="$TAG" 'found { print; exit } $0 == t { found = 1 }')
+    SHA=$(git rev-list -n1 "$TAG")
+    # A tag with no release answers 404, whose error body gh still prints: keep only an id.
+    ID=$(gh api "repos/$REPO/releases/tags/$TAG" --jq .id 2> /dev/null || true)
+    [[ "$ID" =~ ^[0-9]+$ ]] || ID=
+    if [ -n "$ID" ] && [ "$REDO" != 1 ]; then echo "$TAG already has a release"; exit; fi
+    body=$(write_notes "$TAG" "$SHA" "$PREV") || exit 1
+    bad=$(named "$body")
+    [ -z "$bad" ] || { echo "$TAG notes name $bad: not published" >&2; exit 1; }
+    if [ "$DRY_RUN" = 1 ]; then printf 'would release %s (since %s):\n\n%s\n' "$TAG" "${PREV:-the start}" "$body"; exit; fi
+    if [ -n "$ID" ]; then
+      gh api -X PATCH "repos/$REPO/releases/$ID" -f body="$body" --silent
+      echo "$TAG notes written again"
+    else
+      gh api -X POST "repos/$REPO/releases" -f tag_name="$TAG" -f name="$TAG" -f body="$body" --jq .html_url
+    fi
+    ;;
+  minor | notes)
+    [ -n "$LATEST" ] || { echo "no v* tag yet: tag the first release by hand" >&2; exit 1; }
+    IFS=. read -r MAJOR MINOR _ <<< "${LATEST#v}"
+    if [ "$MODE" = minor ]; then
+      TAG="v$MAJOR.$((MINOR + 1)).0"; PREV="v$MAJOR.$MINOR.0"
+    else
+      TAG="v$MAJOR.$MINOR.0"
+    fi
+    FILE="docs/releases/$TAG.md"
+    git show "origin/main:$FILE" > "$TMP/notes.md" 2> /dev/null \
+      || { echo "$FILE is not on main: write the key takeaways first" >&2; exit 1; }
+    if [ "$MODE" = minor ]; then release "$TAG" "$(git rev-parse origin/main)" "$PREV" "$TMP/notes.md"; exit; fi
+    if [ "$DRY_RUN" = 1 ]; then echo "would set $TAG notes from $FILE"; exit; fi
+    id=$(gh api "repos/$REPO/releases/tags/$TAG" --jq .id)
+    at=$(gh api -X PATCH "repos/$REPO/releases/$id" -F body=@"$TMP/notes.md" --jq .published_at)
+    echo "$TAG notes set from $FILE ($at)"
+    changelog "$TAG" "$at" "$(cat "$TMP/notes.md")" "" > /dev/null
+    ;;
+  patch)
+    [ -n "$LATEST" ] || { echo "no v* tag yet: tag the first release by hand" >&2; exit 1; }
+    IFS=. read -r MAJOR MINOR PATCH <<< "${LATEST#v}"
+    # The changelog commits this script writes are not merges.
+    COUNT=$(git rev-list --first-parent --count --invert-grep --grep='^changelog: ' "$LATEST..origin/main")
+    if [ "$COUNT" = 0 ]; then echo "nothing merged since $LATEST"; exit; fi
+    AGE_DAYS=$(( ($(date +%s) - $(git log -1 --format=%ct "$LATEST")) / 86400 ))
+    if [ "$FORCE" != 1 ] && [ "$COUNT" -lt "$EVERY" ] && [ "$AGE_DAYS" -lt "$DAYS" ]; then
+      echo "$COUNT of $EVERY merges, $AGE_DAYS of $DAYS days since $LATEST: no release yet"
+      exit
+    fi
+    release "v$MAJOR.$MINOR.$((PATCH + 1))" "$(git rev-parse origin/main)" "$LATEST"
+    ;;
+  *)
+    echo "usage: lumen-ship release [patch | minor | notes | tag v<version>]" >&2
+    exit 1
+    ;;
+esac