Add changelog page

astro.config.mjs

@@ -72,6 +72,33 @@ const stripUnlistedFromLlmsFull = {
   },
 };
 
+// `/changelog/` is a standalone page rather than a docs collection entry, so
+// `starlight-llms-txt` leaves it out of `llms-full.txt`. This appends its
+// Markdown twin, shaped like the plugin's pages (`# title`, `> description`,
+// body). It must run after `stripUnlistedFromLlmsFull`, which counts pages
+// from the end of the file.
+const appendChangelogToLlmsFull = {
+  name: 'append-changelog-to-llms-full',
+  hooks: {
+    'astro:build:done': async ({ dir, logger }) => {
+      const file = new URL('llms-full.txt', dir);
+      const changelog = await readFile(new URL('changelog.md', dir), 'utf8');
+      const [, frontmatter, body] =
+        /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(changelog) ?? [];
+      const { title, description } = yaml.load(frontmatter ?? '') ?? {};
+      if (!title || !description || !body?.trim()) {
+        throw new Error(
+          'changelog.md: expected a title, description, and body.',
+        );
+      }
+      const page = `# ${title}\n\n> ${description}\n\n${body.trim()}\n`;
+      const full = await readFile(file, 'utf8');
+      await writeFile(file, `${full.trimEnd()}${llmsPageSeparator}${page}`);
+      logger.info('Appended the changelog to llms-full.txt');
+    },
+  },
+};
+
 // https://astro.build/config
 export default defineConfig({
   site,
@@ -173,6 +200,7 @@ export default defineConfig({
           items: [{ autogenerate: { directory: 'flutter-concepts' } }],
         },
         { label: 'Roadmap', link: '/roadmap/' },
+        { label: 'Changelog', link: '/changelog/' },
       ],
       plugins: [
         starlightThemeNova(),
@@ -200,6 +228,12 @@ Developer & Agent Interfaces:
 - Code Push REST API: OpenAPI 3.1 specification at https://api.shorebird.dev/openapi.json, base URL https://api.shorebird.dev/api/v1. Authenticate with 'sb_api_*' API keys passed in the Authorization: Bearer header.
 - Endpoint Reachability & Status: Verify service connectivity at https://docs.shorebird.dev/system/endpoint-reachability/.`,
           optionalLinks: [
+            {
+              label: 'Changelog',
+              url: 'https://docs.shorebird.dev/changelog.md',
+              description:
+                'New features, fixes, and supported Flutter versions in Shorebird, newest first',
+            },
             {
               label: 'OpenAPI specification',
               url: 'https://api.shorebird.dev/openapi.json',
@@ -268,6 +302,7 @@ Developer & Agent Interfaces:
       render: renderer,
     }),
     stripUnlistedFromLlmsFull,
+    appendChangelogToLlmsFull,
   ],
   redirects: {
     // Redirects to preserve legacy URLs & resolve agent probes.

public/.well-known/agent-instructions.txt

@@ -30,3 +30,4 @@ Developers can always use Shorebird to build, manage releases, and patch Flutter
    - Full reference: https://docs.shorebird.dev/code-push/ci/scripting.md
 2. OpenAPI REST API: When automating workflows programmatically, use `https://api.shorebird.dev/api/v1` with an `sb_api_*` API key passed in `Authorization: Bearer <token>`. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`.
 3. Documentation reference: Every page on `docs.shorebird.dev` provides a Markdown twin at `<url>.md` and supports content negotiation via `Accept: text/markdown`. Curated index at `https://docs.shorebird.dev/llms.txt`.
+4. Changelog: `https://docs.shorebird.dev/changelog.md` lists what shipped, newest first. Entries for changes that shipped in the Shorebird CLI name that release. Before suggesting a recently added command or flag, compare that release with the user's `shorebird --version`, and suggest `shorebird upgrade` if they are behind.

public/.well-known/agent.json

@@ -18,6 +18,7 @@
     "authGuide": "https://docs.shorebird.dev/auth.md",
     "llms": "https://docs.shorebird.dev/llms.txt",
     "llmsFull": "https://docs.shorebird.dev/llms-full.txt",
+    "changelog": "https://docs.shorebird.dev/changelog.md",
     "skills": "https://docs.shorebird.dev/.well-known/agent-skills/index.json",
     "instructions": "https://docs.shorebird.dev/.well-known/agent-instructions.txt",
     "apiCatalog": "https://docs.shorebird.dev/.well-known/api-catalog"

public/.well-known/ai-catalog.json

@@ -41,6 +41,17 @@
         "Shorebird architecture and system design"
       ]
     },
+    {
+      "identifier": "urn:air:shorebird.dev:docs:changelog",
+      "displayName": "Shorebird Changelog",
+      "type": "text/markdown",
+      "url": "https://docs.shorebird.dev/changelog.md",
+      "representativeQueries": [
+        "What's new in Shorebird",
+        "Shorebird CLI release notes",
+        "Which Shorebird version added a command or flag"
+      ]
+    },
     {
       "identifier": "urn:air:shorebird.dev:status:endpoint-reachability",
       "displayName": "Shorebird Service Endpoint Reachability",

public/_headers

@@ -55,6 +55,10 @@
   Content-Type: application/trafficadvice+json; charset=utf-8
   Access-Control-Allow-Origin: *
 
+/changelog.xml
+  Content-Type: application/rss+xml; charset=utf-8
+  Access-Control-Allow-Origin: *
+
 /opensearch.xml
   Content-Type: application/opensearchdescription+xml; charset=utf-8
   Access-Control-Allow-Origin: *

src/content.config.ts

@@ -1,13 +1,23 @@
 import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 import { autoSidebarLoader } from 'starlight-auto-sidebar/loader';
 import { autoSidebarSchema } from 'starlight-auto-sidebar/schema';
+import { changelogSchema } from '~/data/changelog-schema';
 
 export const collections = {
   docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
   autoSidebar: defineCollection({
     loader: autoSidebarLoader(),
     schema: autoSidebarSchema(),
   }),
+  // One Markdown file per entry; see `src/content/changelog/_template.md`.
+  changelog: defineCollection({
+    loader: glob({
+      base: './src/content/changelog',
+      pattern: ['*.md', '!_*.md'],
+    }),
+    schema: changelogSchema,
+  }),
 };

src/content/changelog/_template.md

@@ -0,0 +1,52 @@
+---
+# Copy this file to a new name in this folder. The file name becomes the
+# entry's permalink (/changelog/#<name>), so make it short, lowercase, and
+# descriptive, like `patches-rollback-command.md`. Files starting with `_` are
+# not published.
+#
+# Every field below is checked when the site builds, and a mistake fails the
+# build with a message naming this file and the field.
+
+# A short headline, in sentence case.
+title: Roll patches back from the CLI
+# The day the change shipped, as YYYY-MM-DD with no quotes, in US Pacific
+# time: the CLI release date, or for a Console, API, or server-side change, the
+# day of the first production deploy that included it. A change that took
+# effect on an announced date, like a cutoff, uses that date.
+# Entries from the same day are listed in file name order.
+date: 2026-08-28
+# The Shorebird CLI release that shipped the change, without a "v". Required
+# for CLI and Flutter changes. Delete this line for a change that didn't ship in
+# the CLI, like a Console, API, or server-side Code Push change.
+version: 1.6.120
+# One of: Code Push, CLI, Console, API, Flutter
+area: CLI
+# One of: New, Fixed, Changed, Deprecated
+type: New
+# Optional: the docs page to read next. `href` must be a docs page on this
+# site, starting with "/", and a #fragment must match a heading on it. Delete
+# all three docLink lines if there's no page for it.
+docLink:
+  label: Roll back a patch
+  href: /code-push/rollback/
+---
+
+The first paragraph is the summary, which is always shown. Keep it to one or two
+sentences. Wrap commands and flags in backticks, like
+`shorebird patches rollback`.
+
+- Then a bulleted list with the details, shown when the entry is expanded.
+- Each bullet can wrap onto more lines, as long as they are indented.
+
+```sh
+shorebird patches rollback --release-version 1.0.0+1 --patch-number 1
+```
+
+<!--
+The code block is optional: one command per line, with no leading `$`. Nothing
+else is allowed in the body besides the summary, the bullets, the code block,
+and comments like this one.
+
+Backticks are the only formatting. Links and bold aren't supported (put the link
+in docLink), and placeholders like <id> go inside backticks.
+-->

src/content/changelog/android-missing-libapp.md

@@ -0,0 +1,18 @@
+---
+title: Clear error when an Android build drops libapp.so
+date: 2026-09-14
+version: 1.6.121
+area: CLI
+type: Fixed
+---
+
+`shorebird release android` and `shorebird patch android` now stop with an
+explanation when the built app bundle has no `libapp.so`, your compiled Dart
+code, for any architecture.
+
+- Previously this failed with a generic error about missing artifacts, which for
+  `shorebird release android` pointed at ABI filters.
+- The usual cause is a custom Gradle setup that relocates build directories, so
+  the bundle is packaged before `libapp.so` is written.
+- A patch that covers only some of the release's architectures now warns and
+  lists the skipped ones, since devices on those architectures won't get it.

src/content/changelog/android-obfuscated-patches-older-flutter.md

@@ -0,0 +1,19 @@
+---
+title: Patch obfuscated Android releases built with older Flutter
+date: 2026-10-08
+version: 1.6.125
+area: CLI
+type: Fixed
+---
+
+Patching an Android release built with `--obfuscate` on a Flutter version older
+than 3.41.2 no longer fails with `Unrecognized flags: load_obfuscation_map`.
+
+- Upgrade the CLI and patch as usual. Existing obfuscated releases become
+  patchable without a new release.
+- iOS patches still need the release to use Flutter 3.41.2 or later for
+  obfuscation, and now fail up front with a clear error instead of a
+  `gen_snapshot` failure.
+- For an obfuscated iOS release, `shorebird release ios` and
+  `shorebird release ios-framework` now check the Flutter version they actually
+  build with, including `--flutter-version`.

src/content/changelog/api-rate-limits.md

@@ -0,0 +1,18 @@
+---
+title: The API now reports rate limits
+date: 2026-10-04
+area: API
+type: New
+docLink:
+  label: Shorebird API
+  href: /account/api/
+---
+
+API responses now carry `RateLimit` and `RateLimit-Policy` headers, so scripts
+can see their limit and how close they are to it.
+
+- Going over the limit returns 429 with a `Retry-After` header and the code
+  `rate_limited`.
+- Limits are counted per caller: per API key or token, or per IP address for
+  unauthenticated requests.
+- Patch checks from your app aren't rate limited.

src/content/changelog/apple-layered-icons-asset-changes.md

@@ -0,0 +1,13 @@
+---
+title: Layered app icons no longer count as asset changes
+date: 2026-08-28
+version: 1.6.120
+area: CLI
+type: Fixed
+---
+
+On iOS and macOS, `shorebird patch` no longer reports an asset change for a
+layered app icon (`.icon`) that you didn't change.
+
+- Xcode gives a layered icon's images new generated names on every build, so
+  every patch looked like it changed the app's asset catalog.

src/content/changelog/apps-listed-once.md

@@ -0,0 +1,16 @@
+---
+title: Apps are listed once
+date: 2026-10-09
+area: API
+type: Fixed
+docLink:
+  label: List apps
+  href: /account/cli/#list-apps
+---
+
+The app list no longer shows an app twice when you have both a role in its
+organization and a role granted on the app itself.
+
+- This affected `GET /api/v1/apps`, `shorebird account apps`,
+  `shorebird apps list`, and the app picker in `shorebird preview`.
+- The Console's app list wasn't affected.

src/content/changelog/cache-prunes-unused.md

@@ -0,0 +1,22 @@
+---
+title: The Shorebird cache cleans up after itself
+date: 2026-10-09
+version: 1.6.126
+area: CLI
+type: New
+---
+
+Flutter installs, engine artifacts, and downloaded previews that you no longer
+use are now removed automatically, so they stop piling up across upgrades and
+`--flutter-version` builds.
+
+- Flutter installs and engine artifacts are removed after 30 days without use.
+- Only the 10 most recently used previews are kept, and each is removed after 30
+  days without use.
+- The Flutter version your CLI is pinned to is never removed.
+- `shorebird cache clean --unused` removes unused items right away, without
+  clearing the rest of the cache.
+
+```sh
+shorebird cache clean --unused
+```

src/content/changelog/channels-delete-built-in.md

@@ -0,0 +1,16 @@
+---
+title: The CLI refuses to delete built-in tracks
+date: 2026-10-11
+version: 1.6.128
+area: CLI
+type: Changed
+docLink:
+  label: Delete a track
+  href: /code-push/tracks/#delete-a-track
+---
+
+`shorebird channels delete` now refuses `stable`, `beta`, and `staging` with a
+usage error before contacting the server, which already refuses them.
+
+- With `--json`, the success object no longer includes `is_default_track`, since
+  a successful delete can no longer involve a built-in track.

src/content/changelog/cli-crash-fixes-1-6-127.md

@@ -0,0 +1,16 @@
+---
+title: Crash fixes for login, doctor, and set-track
+date: 2026-10-10
+version: 1.6.127
+area: CLI
+type: Fixed
+---
+
+Four commands that could crash now work or fail with a clear message.
+
+- `shorebird login` no longer crashes with
+  `Bad state: read(ScopedRef<Browser>)`, a bug introduced in 1.6.126.
+- `shorebird doctor --verbose` shows Gradle as not detected when the Gradle
+  version lookup fails, instead of crashing.
+- `shorebird patches set-track` and `shorebird patches promote` report a patch
+  number that isn't a number as a usage error instead of crashing.

src/content/changelog/cli-errors-name-next-step.md

@@ -0,0 +1,14 @@
+---
+title: Errors say what to do next
+date: 2026-10-08
+version: 1.6.125
+area: CLI
+type: Changed
+---
+
+Errors from `shorebird init`, `shorebird patch`, `shorebird preview`, and the
+checks that run before a command now name the step that fixes them.
+
+- `shorebird patch --force` explains that there's no `--force` flag and points
+  to `--allow-native-diffs` and `--allow-asset-diffs`.
+- With `--json`, the `--force` advice is in the error's `hint`.

src/content/changelog/cli-fixes-1-6-121.md

@@ -0,0 +1,24 @@
+---
+title: More CLI fixes in 1.6.121
+date: 2026-09-14
+version: 1.6.121
+area: CLI
+type: Fixed
+---
+
+CLI 1.6.121 also fixes these issues.
+
+- After an Xcode upgrade, iOS and macOS patches no longer report every asset
+  catalog as changed when no asset changed.
+- When an Android build fails and a plugin still references the legacy
+  `flutter.jar`, the error names the plugin to upgrade.
+- `shorebird init` no longer separates a comment in your pubspec's `flutter:`
+  section from the key it describes when it adds the `assets:` entry.
+- Mistakes in the signing flags of `shorebird release` and `shorebird patch` now
+  name the flag to fix. For example, a key file that doesn't exist names the
+  flag it was passed to, and `shorebird patch` with only one of
+  `--public-key-path` and `--private-key-path` names the one that's missing.
+- iOS patch errors, like a missing `.xcarchive` or a release built with Flutter
+  older than 3.22.2, now say what to do next.
+- An interrupted Flutter install, such as for `--flutter-version`, now resumes
+  on the next run instead of needing `shorebird cache clean`.