From 151fd00e3708031a1e4b79bb786e8adede88e5f3 Mon Sep 17 00:00:00 2001
From: Dawn Parzych <dawn@shorebird.dev>
Date: Fri, 18 Sep 2026 11:14:04 -0500
Subject: [PATCH 01/13] Add changelog page

A searchable, faceted feed of what shipped to Code Push, the CLI,
and the API, with expandable entries carrying detail, a command, and
a doc link. Seeded with one example entry; add to the ENTRIES array
in src/pages/changelog.astro as things ship.

Design: https://claude.ai/design/p/8d6abb36-5f0f-4da2-86d9-636e825acb58

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 astro.config.mjs          |   1 +
 src/pages/changelog.astro | 589 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 590 insertions(+)
 create mode 100644 src/pages/changelog.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index f40ff033..33e73e44 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -120,6 +120,7 @@ export default defineConfig({
           items: [{ autogenerate: { directory: 'flutter-concepts' } }],
         },
         { label: 'Roadmap', link: '/roadmap/' },
+        { label: 'Changelog', link: '/changelog/' },
       ],
       plugins: [
         starlightThemeNova(),
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
new file mode 100644
index 00000000..fe534ef8
--- /dev/null
+++ b/src/pages/changelog.astro
@@ -0,0 +1,589 @@
+---
+// cspell:words rollouts
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+
+interface ChangelogEntry {
+  /** Anchor id and permalink slug for this entry. */
+  id: string;
+  date: string;
+  version: string;
+  area: string;
+  type: 'New' | 'Fixed' | 'Changed' | 'Deprecated';
+  title: string;
+  summary: string;
+  bullets: string[];
+  code?: string;
+  docLink?: { label: string; href: string };
+}
+
+// Hand-written, newest first. Add an entry here when something ships that a
+// developer integrating Code Push would want to know about.
+const ENTRIES: ChangelogEntry[] = [
+  {
+    id: 'staged-rollouts-in-one-command',
+    date: '2026-09-10',
+    version: '1.7.2',
+    area: 'Code Push',
+    type: 'New',
+    title: 'Staged rollouts in one command',
+    summary:
+      'shorebird patch --track=beta now takes --rollout, so a staged patch can start at 5% without a second command.',
+    bullets: [
+      '--rollout takes a whole percentage from 1 to 100. Omit it and the patch goes to the entire track, exactly as before.',
+      'Raise or halt a rollout from the console, or with shorebird patch rollout set 25.',
+      'Rollback still applies to the whole track — halting a rollout leaves the previous patch installed.',
+    ],
+    code: 'shorebird patch android --track=beta --rollout=5',
+    docLink: {
+      label: 'Percentage-based rollouts',
+      href: '/code-push/guides/percentage-based-rollouts/',
+    },
+  },
+];
+
+const TYPE_LABEL_COLOR: Record<ChangelogEntry['type'], string> = {
+  New: 'new',
+  Fixed: 'fixed',
+  Changed: 'changed',
+  Deprecated: 'deprecated',
+};
+
+function formatMonth(iso: string): string {
+  return new Date(iso).toLocaleDateString('en-US', {
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC',
+  });
+}
+
+const areas = [...new Set(ENTRIES.map((e) => e.area))].sort();
+
+const groups: { label: string; items: ChangelogEntry[] }[] = [];
+for (const e of ENTRIES) {
+  const label = formatMonth(e.date);
+  let group = groups.find((g) => g.label === label);
+  if (!group) groups.push((group = { label, items: [] }));
+  group.items.push(e);
+}
+---
+
+<StarlightPage
+  frontmatter={{
+    title: 'Changelog',
+    description: 'Everything we shipped to Code Push, the CLI, and the API.',
+  }}
+>
+  <p>
+    Everything we shipped to Code Push, the CLI, and the API. Expand an entry
+    for the full detail, the command, and the doc it belongs to.
+  </p>
+
+  <div class="cl-toolbar">
+    <div class="cl-search">
+      <svg
+        class="cl-search-icon"
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+      >
+        <circle
+          cx="11"
+          cy="11"
+          r="7"
+          stroke="currentColor"
+          stroke-width="2"></circle>
+        <path
+          d="M21 21l-4.3-4.3"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"></path>
+      </svg>
+      <input
+        id="cl-search"
+        type="text"
+        placeholder="Search the changelog"
+        aria-label="Search the changelog"
+      />
+    </div>
+    <div class="cl-chips" role="group" aria-label="Filter by area">
+      <button class="cl-chip is-active" data-area="All" type="button"
+        >All</button
+      >
+      {
+        areas.map((a) => (
+          <button class="cl-chip" data-area={a} type="button">
+            {a}
+          </button>
+        ))
+      }
+    </div>
+    <span class="cl-count" id="cl-count">
+      {ENTRIES.length} {ENTRIES.length === 1 ? 'entry' : 'entries'}
+    </span>
+  </div>
+
+  <div class="cl-list" id="cl-list">
+    {
+      groups.map((group) => (
+        <div class="cl-group">
+          <h2 class="cl-month">{group.label}</h2>
+          {group.items.map((e) => {
+            const searchText = `${e.title} ${e.summary} ${e.area} ${e.type}`.toLowerCase();
+            return (
+              <article
+                class="cl-entry"
+                id={e.id}
+                data-area={e.area}
+                data-search={searchText}
+              >
+                <button
+                  class="cl-entry-toggle"
+                  type="button"
+                  aria-expanded="false"
+                  aria-controls={`${e.id}-detail`}
+                >
+                  <span
+                    class="cl-badge"
+                    data-type={TYPE_LABEL_COLOR[e.type]}
+                  >
+                    {e.type}
+                  </span>
+                  <span class="cl-badge cl-badge-area">{e.area}</span>
+                  <span class="cl-version">{e.version}</span>
+                  <span class="cl-mark" aria-hidden="true">
+                    +
+                  </span>
+                </button>
+                <h3 class="cl-title">{e.title}</h3>
+                <p class="cl-summary">{e.summary}</p>
+                <div class="cl-detail" id={`${e.id}-detail`} hidden>
+                  <ul class="cl-bullets">
+                    {e.bullets.map((b) => (
+                      <li>{b}</li>
+                    ))}
+                  </ul>
+                  {e.code && (
+                    <pre class="cl-code"><code>$ {e.code}</code></pre>
+                  )}
+                  <div class="cl-footer">
+                    {e.docLink && (
+                      <a href={e.docLink.href} class="cl-doc-link">
+                        {e.docLink.label} →
+                      </a>
+                    )}
+                    <span class="cl-permalink-group">
+                      <span class="cl-permalink">/changelog/#{e.id}</span>
+                      <a
+                        href={`#${e.id}`}
+                        class="cl-copy"
+                        aria-label="Copy link to this entry"
+                        data-copy={`#${e.id}`}
+                      >
+                        ⧉
+                      </a>
+                    </span>
+                  </div>
+                </div>
+              </article>
+            );
+          })}
+        </div>
+      ))
+    }
+  </div>
+
+  <p class="cl-empty" id="cl-empty" hidden>
+    Nothing matches that search — clear the field or pick a different area.
+  </p>
+</StarlightPage>
+
+<script>
+  function init() {
+    const search = document.getElementById(
+      'cl-search',
+    ) as HTMLInputElement | null;
+    const chips = Array.from(
+      document.querySelectorAll<HTMLButtonElement>('.cl-chip'),
+    );
+    const entries = Array.from(
+      document.querySelectorAll<HTMLElement>('.cl-entry'),
+    );
+    const groups = Array.from(
+      document.querySelectorAll<HTMLElement>('.cl-group'),
+    );
+    const countEl = document.getElementById('cl-count');
+    const emptyEl = document.getElementById('cl-empty');
+    if (!search || !countEl || !emptyEl) return;
+
+    let area = 'All';
+
+    function applyFilters() {
+      const q = (search?.value ?? '').trim().toLowerCase();
+      let visibleCount = 0;
+
+      for (const entry of entries) {
+        const matchesArea = area === 'All' || entry.dataset.area === area;
+        const matchesSearch =
+          q === '' || (entry.dataset.search ?? '').includes(q);
+        const visible = matchesArea && matchesSearch;
+        entry.hidden = !visible;
+        if (visible) visibleCount += 1;
+      }
+
+      for (const group of groups) {
+        const hasVisible = group.querySelector('.cl-entry:not([hidden])');
+        group.hidden = !hasVisible;
+      }
+
+      countEl!.textContent = `${visibleCount} ${visibleCount === 1 ? 'entry' : 'entries'}`;
+      emptyEl!.hidden = visibleCount !== 0;
+    }
+
+    search.addEventListener('input', applyFilters);
+
+    for (const chip of chips) {
+      chip.addEventListener('click', () => {
+        area = chip.dataset.area ?? 'All';
+        for (const c of chips) c.classList.toggle('is-active', c === chip);
+        applyFilters();
+      });
+    }
+
+    function setOpen(entry: HTMLElement, open: boolean) {
+      const toggle = entry.querySelector<HTMLButtonElement>(
+        '.cl-entry-toggle',
+      );
+      const detail = entry.querySelector<HTMLElement>('.cl-detail');
+      const mark = entry.querySelector<HTMLElement>('.cl-mark');
+      if (!toggle || !detail || !mark) return;
+      toggle.setAttribute('aria-expanded', String(open));
+      detail.hidden = !open;
+      mark.textContent = open ? '−' : '+';
+    }
+
+    for (const entry of entries) {
+      const toggle = entry.querySelector<HTMLButtonElement>(
+        '.cl-entry-toggle',
+      );
+      toggle?.addEventListener('click', () => {
+        const isOpen = toggle.getAttribute('aria-expanded') === 'true';
+        setOpen(entry, !isOpen);
+      });
+    }
+
+    for (const copyBtn of document.querySelectorAll<HTMLAnchorElement>(
+      '.cl-copy',
+    )) {
+      copyBtn.addEventListener('click', async (ev) => {
+        ev.preventDefault();
+        const hash = copyBtn.dataset.copy ?? '';
+        const url = `${location.origin}${location.pathname}${hash}`;
+        try {
+          await navigator.clipboard.writeText(url);
+        } catch {
+          // Clipboard access can fail (permissions, insecure context); the
+          // link itself still works as a fallback.
+        }
+      });
+    }
+
+    // Open and scroll to the entry named in the URL hash, if any.
+    const targetId = decodeURIComponent(location.hash.replace(/^#/, ''));
+    if (targetId) {
+      const target = document.getElementById(targetId);
+      if (target?.classList.contains('cl-entry')) {
+        setOpen(target, true);
+        target.scrollIntoView({ block: 'start' });
+      }
+    }
+
+    applyFilters();
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+</script>
+
+<style>
+  .cl-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.75rem;
+    margin: 1.5rem 0;
+  }
+
+  .cl-search {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    flex: 1 1 16rem;
+    height: 2.5rem;
+    padding: 0 0.85rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
+    background: var(--sl-color-bg-sidebar);
+  }
+
+  .cl-search-icon {
+    flex-shrink: 0;
+    color: var(--sl-color-gray-3);
+  }
+
+  .cl-search input {
+    flex: 1;
+    min-width: 0;
+    border: 0;
+    outline: 0;
+    background: transparent;
+    color: var(--sl-color-white);
+    font: inherit;
+    font-size: 0.9rem;
+  }
+
+  .cl-search input::placeholder {
+    color: var(--sl-color-gray-3);
+  }
+
+  .cl-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+  }
+
+  .cl-chip {
+    height: 2rem;
+    padding: 0 0.85rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
+    background: transparent;
+    color: var(--sl-color-gray-2);
+    font-size: 0.8rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition:
+      background 0.15s,
+      border-color 0.15s,
+      color 0.15s;
+  }
+
+  .cl-chip:hover {
+    border-color: var(--sl-color-gray-3);
+  }
+
+  .cl-chip.is-active {
+    background: color-mix(in srgb, var(--sl-color-accent) 16%, transparent);
+    border-color: var(--sl-color-accent);
+    color: var(--sl-color-accent-high);
+  }
+
+  .cl-count {
+    margin-left: auto;
+    font-family: var(--sl-font-mono, ui-monospace, monospace);
+    font-size: 0.8rem;
+    color: var(--sl-color-gray-3);
+  }
+
+  .cl-group {
+    margin-top: 2rem;
+  }
+
+  .cl-month {
+    margin: 0 0 0.75rem;
+    font-size: 0.85rem;
+    font-weight: 600;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--sl-color-gray-3);
+    border: 0;
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+  }
+
+  .cl-entry {
+    padding: 1.1rem 0;
+    border-bottom: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+  }
+
+  .cl-entry-toggle {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+    width: 100%;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    cursor: pointer;
+    text-align: left;
+  }
+
+  .cl-badge {
+    height: 1.25rem;
+    padding: 0 0.5rem;
+    border-radius: 999px;
+    font-size: 0.68rem;
+    font-weight: 700;
+    line-height: 1.25rem;
+    letter-spacing: 0.03em;
+    text-transform: uppercase;
+  }
+
+  .cl-badge-area {
+    background: color-mix(in srgb, var(--sl-color-gray-4) 18%, transparent);
+    color: var(--sl-color-gray-2);
+  }
+
+  .cl-badge[data-type='new'] {
+    background: color-mix(in srgb, var(--sl-color-accent) 16%, transparent);
+    color: var(--sl-color-accent-high);
+  }
+
+  .cl-badge[data-type='fixed'] {
+    background: color-mix(in srgb, #22c55e 16%, transparent);
+    color: #16a34a;
+  }
+
+  .cl-badge[data-type='changed'] {
+    background: color-mix(in srgb, #a855f7 16%, transparent);
+    color: #9333ea;
+  }
+
+  .cl-badge[data-type='deprecated'] {
+    background: color-mix(in srgb, #f59e0b 16%, transparent);
+    color: #d97706;
+  }
+
+  :root[data-theme='dark'] .cl-badge[data-type='fixed'] {
+    color: #4ade80;
+  }
+  :root[data-theme='dark'] .cl-badge[data-type='changed'] {
+    color: #d8b4fe;
+  }
+  :root[data-theme='dark'] .cl-badge[data-type='deprecated'] {
+    color: #fbbf24;
+  }
+
+  .cl-version {
+    margin-left: auto;
+    font-family: var(--sl-font-mono, ui-monospace, monospace);
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--sl-color-gray-3);
+  }
+
+  .cl-mark {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.35rem;
+    height: 1.35rem;
+    border-radius: 50%;
+    background: color-mix(in srgb, var(--sl-color-gray-4) 16%, transparent);
+    color: var(--sl-color-gray-2);
+    font-weight: 600;
+    font-size: 0.9rem;
+  }
+
+  .cl-title {
+    margin: 0.6rem 0 0;
+    font-size: 1.1rem;
+    font-weight: 600;
+    color: var(--sl-color-white);
+  }
+
+  .cl-summary {
+    margin: 0.4rem 0 0;
+    max-width: 68ch;
+    font-size: 0.9rem;
+    line-height: 1.6;
+    color: var(--sl-color-gray-2);
+  }
+
+  .cl-detail {
+    margin-top: 1rem;
+    background: var(--sl-color-bg-sidebar);
+    border-radius: 1rem;
+    padding: 1.25rem 1.5rem;
+  }
+
+  .cl-bullets {
+    margin: 0;
+    padding-left: 1.1rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.55rem;
+    font-size: 0.875rem;
+    line-height: 1.6;
+    color: var(--sl-color-gray-2);
+  }
+
+  .cl-code {
+    margin: 1rem 0 0;
+    padding: 0.85rem 1.1rem;
+    border-radius: 0.75rem;
+    background: var(--sl-color-bg);
+    overflow-x: auto;
+    white-space: nowrap;
+    font-family: var(--sl-font-mono, ui-monospace, monospace);
+    font-size: 0.85rem;
+    color: var(--sl-color-gray-1);
+  }
+
+  .cl-footer {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    flex-wrap: wrap;
+    margin-top: 1rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+  }
+
+  .cl-doc-link {
+    font-size: 0.875rem;
+    font-weight: 600;
+  }
+
+  .cl-permalink-group {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-left: auto;
+  }
+
+  .cl-permalink {
+    font-family: var(--sl-font-mono, ui-monospace, monospace);
+    font-size: 0.72rem;
+    color: var(--sl-color-gray-3);
+  }
+
+  .cl-copy {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.6rem;
+    height: 1.6rem;
+    border-radius: 0.4rem;
+    border: 1px solid var(--sl-color-gray-5);
+    color: var(--sl-color-gray-2);
+    font-size: 0.75rem;
+  }
+
+  .cl-copy:hover {
+    border-color: var(--sl-color-gray-3);
+    color: var(--sl-color-white);
+  }
+
+  .cl-empty {
+    margin-top: 1.5rem;
+    padding: 1.5rem 0;
+    border-top: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+    color: var(--sl-color-gray-2);
+  }
+</style>

From 68b829a6d924193ec9c492ae538813198417a1dd Mon Sep 17 00:00:00 2001
From: Dawn Parzych <dawn@shorebird.dev>
Date: Fri, 18 Sep 2026 11:25:09 -0500
Subject: [PATCH 02/13] Fix changelog area to a closed set

Area was a free string derived from whichever entries existed; fix it
to the five actual areas (Code Push, CLI, Console, API, Flutter) so
the filter chips are stable regardless of what's in ENTRIES.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/pages/changelog.astro | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index fe534ef8..a2c08b7a 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -2,12 +2,18 @@
 // cspell:words rollouts
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 
+// The parts of Shorebird a change can be filed under. Fixed on purpose —
+// this drives the area filter chips, so it should stay in sync with the
+// products we actually ship rather than growing a new value per entry.
+const AREAS = ['Code Push', 'CLI', 'Console', 'API', 'Flutter'] as const;
+type Area = (typeof AREAS)[number];
+
 interface ChangelogEntry {
   /** Anchor id and permalink slug for this entry. */
   id: string;
   date: string;
   version: string;
-  area: string;
+  area: Area;
   type: 'New' | 'Fixed' | 'Changed' | 'Deprecated';
   title: string;
   summary: string;
@@ -56,8 +62,6 @@ function formatMonth(iso: string): string {
   });
 }
 
-const areas = [...new Set(ENTRIES.map((e) => e.area))].sort();
-
 const groups: { label: string; items: ChangelogEntry[] }[] = [];
 for (const e of ENTRIES) {
   const label = formatMonth(e.date);
@@ -112,7 +116,7 @@ for (const e of ENTRIES) {
         >All</button
       >
       {
-        areas.map((a) => (
+        AREAS.map((a) => (
           <button class="cl-chip" data-area={a} type="button">
             {a}
           </button>

From ae97ac86ddff243a58e26fc06125ea85a2a043bd Mon Sep 17 00:00:00 2001
From: Mac Carrithers <mac@shorebird.dev>
Date: Fri, 18 Sep 2026 12:00:53 -0600
Subject: [PATCH 03/13] Make changelog entry headers clickable and align the
 filter chips

The toolbar opts out of Starlight's markdown sibling spacing, which was pushing every chip after "All" down by 1rem.

The expand toggle keeps its button on the badge row, but a stretched ::after covers the whole header so the title and summary toggle the entry too. Links inside the header sit above the overlay. The "+" text glyph is replaced with an SVG so it centers in a larger bubble, and the vertical stroke hides when the entry is open.
---
 src/pages/changelog.astro | 137 ++++++++++++++++++++++++++------------
 1 file changed, 95 insertions(+), 42 deletions(-)

diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index a2c08b7a..cf568130 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -1,5 +1,6 @@
 ---
 // cspell:words rollouts
+// cspell:ignore data-type white-space
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 
 // The parts of Shorebird a change can be filed under. Fixed on purpose —
@@ -82,7 +83,7 @@ for (const e of ENTRIES) {
     for the full detail, the command, and the doc it belongs to.
   </p>
 
-  <div class="cl-toolbar">
+  <div class="cl-toolbar not-content">
     <div class="cl-search">
       <svg
         class="cl-search-icon"
@@ -92,12 +93,8 @@ for (const e of ENTRIES) {
         fill="none"
         aria-hidden="true"
       >
-        <circle
-          cx="11"
-          cy="11"
-          r="7"
-          stroke="currentColor"
-          stroke-width="2"></circle>
+        <circle cx="11" cy="11" r="7" stroke="currentColor" stroke-width="2"
+        ></circle>
         <path
           d="M21 21l-4.3-4.3"
           stroke="currentColor"
@@ -124,7 +121,8 @@ for (const e of ENTRIES) {
       }
     </div>
     <span class="cl-count" id="cl-count">
-      {ENTRIES.length} {ENTRIES.length === 1 ? 'entry' : 'entries'}
+      {ENTRIES.length}
+      {ENTRIES.length === 1 ? 'entry' : 'entries'}
     </span>
   </div>
 
@@ -134,7 +132,8 @@ for (const e of ENTRIES) {
         <div class="cl-group">
           <h2 class="cl-month">{group.label}</h2>
           {group.items.map((e) => {
-            const searchText = `${e.title} ${e.summary} ${e.area} ${e.type}`.toLowerCase();
+            const searchText =
+              `${e.title} ${e.summary} ${e.area} ${e.type}`.toLowerCase();
             return (
               <article
                 class="cl-entry"
@@ -142,26 +141,39 @@ for (const e of ENTRIES) {
                 data-area={e.area}
                 data-search={searchText}
               >
-                <button
-                  class="cl-entry-toggle"
-                  type="button"
-                  aria-expanded="false"
-                  aria-controls={`${e.id}-detail`}
-                >
-                  <span
-                    class="cl-badge"
-                    data-type={TYPE_LABEL_COLOR[e.type]}
+                <div class="cl-head">
+                  <button
+                    class="cl-entry-toggle"
+                    type="button"
+                    aria-expanded="false"
+                    aria-controls={`${e.id}-detail`}
                   >
-                    {e.type}
-                  </span>
-                  <span class="cl-badge cl-badge-area">{e.area}</span>
-                  <span class="cl-version">{e.version}</span>
-                  <span class="cl-mark" aria-hidden="true">
-                    +
-                  </span>
-                </button>
-                <h3 class="cl-title">{e.title}</h3>
-                <p class="cl-summary">{e.summary}</p>
+                    <span class="cl-badge" data-type={TYPE_LABEL_COLOR[e.type]}>
+                      {e.type}
+                    </span>
+                    <span class="cl-badge cl-badge-area">{e.area}</span>
+                    <span class="cl-version">{e.version}</span>
+                    <span class="cl-mark" aria-hidden="true">
+                      <svg viewBox="0 0 16 16" width="12" height="12">
+                        <path
+                          d="M2 8h12"
+                          stroke="currentColor"
+                          stroke-width="2"
+                          stroke-linecap="round"
+                        />
+                        <path
+                          class="cl-mark-v"
+                          d="M8 2v12"
+                          stroke="currentColor"
+                          stroke-width="2"
+                          stroke-linecap="round"
+                        />
+                      </svg>
+                    </span>
+                  </button>
+                  <h3 class="cl-title">{e.title}</h3>
+                  <p class="cl-summary">{e.summary}</p>
+                </div>
                 <div class="cl-detail" id={`${e.id}-detail`} hidden>
                   <ul class="cl-bullets">
                     {e.bullets.map((b) => (
@@ -169,7 +181,9 @@ for (const e of ENTRIES) {
                     ))}
                   </ul>
                   {e.code && (
-                    <pre class="cl-code"><code>$ {e.code}</code></pre>
+                    <pre class="cl-code">
+                      <code>$ {e.code}</code>
+                    </pre>
                   )}
                   <div class="cl-footer">
                     {e.docLink && (
@@ -256,21 +270,15 @@ for (const e of ENTRIES) {
     }
 
     function setOpen(entry: HTMLElement, open: boolean) {
-      const toggle = entry.querySelector<HTMLButtonElement>(
-        '.cl-entry-toggle',
-      );
+      const toggle = entry.querySelector<HTMLButtonElement>('.cl-entry-toggle');
       const detail = entry.querySelector<HTMLElement>('.cl-detail');
-      const mark = entry.querySelector<HTMLElement>('.cl-mark');
-      if (!toggle || !detail || !mark) return;
+      if (!toggle || !detail) return;
       toggle.setAttribute('aria-expanded', String(open));
       detail.hidden = !open;
-      mark.textContent = open ? '−' : '+';
     }
 
     for (const entry of entries) {
-      const toggle = entry.querySelector<HTMLButtonElement>(
-        '.cl-entry-toggle',
-      );
+      const toggle = entry.querySelector<HTMLButtonElement>('.cl-entry-toggle');
       toggle?.addEventListener('click', () => {
         const isOpen = toggle.getAttribute('aria-expanded') === 'true';
         setOpen(entry, !isOpen);
@@ -414,6 +422,31 @@ for (const e of ENTRIES) {
     border-bottom: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
   }
 
+  /* A button cannot contain links, so the button holds only the badge row
+     and its ::after stretches over the header to make the title and summary
+     toggle too. Links inside the header sit above that overlay. */
+  .cl-head {
+    position: relative;
+    margin: 0 -0.75rem;
+    padding: 0.5rem 0.75rem;
+    border-radius: 0.75rem;
+    transition: background 0.15s;
+  }
+
+  .cl-head:has(.cl-entry-toggle:hover) {
+    background: color-mix(in srgb, var(--sl-color-gray-4) 8%, transparent);
+  }
+
+  .cl-head:has(.cl-entry-toggle:focus-visible) {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 2px;
+  }
+
+  .cl-head a {
+    position: relative;
+    z-index: 1;
+  }
+
   .cl-entry-toggle {
     display: flex;
     align-items: center;
@@ -425,6 +458,14 @@ for (const e of ENTRIES) {
     background: transparent;
     cursor: pointer;
     text-align: left;
+    outline: 0;
+  }
+
+  .cl-entry-toggle::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
   }
 
   .cl-badge {
@@ -485,13 +526,25 @@ for (const e of ENTRIES) {
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: 1.35rem;
-    height: 1.35rem;
+    width: 1.6rem;
+    height: 1.6rem;
     border-radius: 50%;
     background: color-mix(in srgb, var(--sl-color-gray-4) 16%, transparent);
     color: var(--sl-color-gray-2);
-    font-weight: 600;
-    font-size: 0.9rem;
+    transition: background 0.15s;
+  }
+
+  .cl-mark svg {
+    display: block;
+  }
+
+  .cl-head:has(.cl-entry-toggle:hover) .cl-mark {
+    background: color-mix(in srgb, var(--sl-color-gray-4) 32%, transparent);
+    color: var(--sl-color-white);
+  }
+
+  .cl-entry-toggle[aria-expanded='true'] .cl-mark-v {
+    display: none;
   }
 
   .cl-title {

From a55b990bafaa51fd0387805133454dd8372bf568 Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Sat, 19 Sep 2026 15:13:00 +0530
Subject: [PATCH 04/13] Fix changelog permalinks, copy feedback, and search
 coverage

- The copy button called preventDefault, so the "link still works as a
  fallback" comment was false: a failed clipboard write did nothing.
  Let the link navigate, and show a brief "copied" state on success.
- Open the targeted entry on hashchange too, not just on first load, so
  a permalink followed from the same page expands its entry.
- Search the version, detail bullets, and command, not only the title
  and summary.
- Put the command's pre and code on one line so the template's
  indentation does not render as a leading space.
---
 src/pages/changelog.astro | 44 ++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index cf568130..3c3ddcf1 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -132,8 +132,17 @@ for (const e of ENTRIES) {
         <div class="cl-group">
           <h2 class="cl-month">{group.label}</h2>
           {group.items.map((e) => {
-            const searchText =
-              `${e.title} ${e.summary} ${e.area} ${e.type}`.toLowerCase();
+            const searchText = [
+              e.title,
+              e.summary,
+              e.area,
+              e.type,
+              e.version,
+              ...e.bullets,
+              e.code ?? '',
+            ]
+              .join(' ')
+              .toLowerCase();
             return (
               <article
                 class="cl-entry"
@@ -181,9 +190,7 @@ for (const e of ENTRIES) {
                     ))}
                   </ul>
                   {e.code && (
-                    <pre class="cl-code">
-                      <code>$ {e.code}</code>
-                    </pre>
+                    <pre class="cl-code"><code>$ {e.code}</code></pre>
                   )}
                   <div class="cl-footer">
                     {e.docLink && (
@@ -288,22 +295,32 @@ for (const e of ENTRIES) {
     for (const copyBtn of document.querySelectorAll<HTMLAnchorElement>(
       '.cl-copy',
     )) {
-      copyBtn.addEventListener('click', async (ev) => {
-        ev.preventDefault();
+      // No preventDefault: following the link puts the permalink in the
+      // address bar, which is the fallback when the clipboard is unavailable.
+      copyBtn.addEventListener('click', async () => {
         const hash = copyBtn.dataset.copy ?? '';
         const url = `${location.origin}${location.pathname}${hash}`;
         try {
           await navigator.clipboard.writeText(url);
         } catch {
-          // Clipboard access can fail (permissions, insecure context); the
-          // link itself still works as a fallback.
+          // Clipboard access can fail (permissions, insecure context).
+          return;
         }
+        const label = copyBtn.getAttribute('aria-label') ?? '';
+        copyBtn.textContent = '✓';
+        copyBtn.setAttribute('aria-label', 'Link copied');
+        setTimeout(() => {
+          copyBtn.textContent = '⧉';
+          copyBtn.setAttribute('aria-label', label);
+        }, 1500);
       });
     }
 
-    // Open and scroll to the entry named in the URL hash, if any.
-    const targetId = decodeURIComponent(location.hash.replace(/^#/, ''));
-    if (targetId) {
+    // Open and scroll to the entry named in the URL hash, if any. Also runs
+    // on hashchange, so a permalink followed from this same page opens too.
+    function openFromHash() {
+      const targetId = decodeURIComponent(location.hash.replace(/^#/, ''));
+      if (!targetId) return;
       const target = document.getElementById(targetId);
       if (target?.classList.contains('cl-entry')) {
         setOpen(target, true);
@@ -311,6 +328,9 @@ for (const e of ENTRIES) {
       }
     }
 
+    openFromHash();
+    window.addEventListener('hashchange', openFromHash);
+
     applyFilters();
   }
 

From 3cf311f0c94d125e26b6adec2d38d206d1367dc7 Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Sat, 19 Sep 2026 15:19:05 +0530
Subject: [PATCH 05/13] Serve the changelog as Markdown for agents

Head.astro gives every page a <link rel="alternate" type="text/markdown">
pointing at <path>.md, but [...slug].md.ts only builds those for content
collection pages. The changelog is a standalone .astro page, so its link
pointed at a 404 and Accept: text/markdown on /changelog/ fell back to HTML.

- Move the entries, areas, and month grouping to src/data/changelog.ts so
  the page and the Markdown route read the same data.
- Add src/pages/changelog.md.ts, which renders /changelog.md from it. The
  existing middleware then negotiates /changelog/ to it with no changes.
- List /changelog.md under Optional in llms.txt.
---
 astro.config.mjs          |  6 ++++
 src/data/changelog.ts     | 76 +++++++++++++++++++++++++++++++++++++++
 src/pages/changelog.astro | 74 ++++++--------------------------------
 src/pages/changelog.md.ts | 51 ++++++++++++++++++++++++++
 4 files changed, 144 insertions(+), 63 deletions(-)
 create mode 100644 src/data/changelog.ts
 create mode 100644 src/pages/changelog.md.ts

diff --git a/astro.config.mjs b/astro.config.mjs
index fd2d6aa6..f0c0aa89 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -209,6 +209,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:
+                'What shipped to Code Push, the CLI, and the API, newest first',
+            },
             {
               label: 'OpenAPI specification',
               url: 'https://api.shorebird.dev/openapi.json',
diff --git a/src/data/changelog.ts b/src/data/changelog.ts
new file mode 100644
index 00000000..27bc5526
--- /dev/null
+++ b/src/data/changelog.ts
@@ -0,0 +1,76 @@
+// cspell:words rollouts
+
+// Shared by the changelog page (`src/pages/changelog.astro`) and its
+// agent-facing Markdown twin (`src/pages/changelog.md.ts`), so both always
+// list the same entries.
+
+export const CHANGELOG_TITLE = 'Changelog';
+export const CHANGELOG_DESCRIPTION =
+  'Everything we shipped to Code Push, the CLI, and the API.';
+
+// The parts of Shorebird a change can be filed under. Fixed on purpose —
+// this drives the area filter chips, so it should stay in sync with the
+// products we actually ship rather than growing a new value per entry.
+export const AREAS = ['Code Push', 'CLI', 'Console', 'API', 'Flutter'] as const;
+export type Area = (typeof AREAS)[number];
+
+export interface ChangelogEntry {
+  /** Anchor id and permalink slug for this entry. */
+  id: string;
+  date: string;
+  version: string;
+  area: Area;
+  type: 'New' | 'Fixed' | 'Changed' | 'Deprecated';
+  title: string;
+  summary: string;
+  bullets: string[];
+  code?: string;
+  docLink?: { label: string; href: string };
+}
+
+// Hand-written, newest first. Add an entry here when something ships that a
+// developer integrating Code Push would want to know about.
+export const ENTRIES: ChangelogEntry[] = [
+  {
+    id: 'staged-rollouts-in-one-command',
+    date: '2026-09-10',
+    version: '1.7.2',
+    area: 'Code Push',
+    type: 'New',
+    title: 'Staged rollouts in one command',
+    summary:
+      'shorebird patch --track=beta now takes --rollout, so a staged patch can start at 5% without a second command.',
+    bullets: [
+      '--rollout takes a whole percentage from 1 to 100. Omit it and the patch goes to the entire track, exactly as before.',
+      'Raise or halt a rollout from the console, or with shorebird patch rollout set 25.',
+      'Rollback still applies to the whole track — halting a rollout leaves the previous patch installed.',
+    ],
+    code: 'shorebird patch android --track=beta --rollout=5',
+    docLink: {
+      label: 'Percentage-based rollouts',
+      href: '/code-push/guides/percentage-based-rollouts/',
+    },
+  },
+];
+
+function formatMonth(iso: string): string {
+  return new Date(iso).toLocaleDateString('en-US', {
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC',
+  });
+}
+
+/** `ENTRIES` grouped under "September 2026"-style headings, newest first. */
+export function groupByMonth(
+  entries: ChangelogEntry[],
+): { label: string; items: ChangelogEntry[] }[] {
+  const groups: { label: string; items: ChangelogEntry[] }[] = [];
+  for (const e of entries) {
+    const label = formatMonth(e.date);
+    let group = groups.find((g) => g.label === label);
+    if (!group) groups.push((group = { label, items: [] }));
+    group.items.push(e);
+  }
+  return groups;
+}
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index 3c3ddcf1..9f4eb390 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -1,52 +1,14 @@
 ---
-// cspell:words rollouts
 // cspell:ignore data-type white-space
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-
-// The parts of Shorebird a change can be filed under. Fixed on purpose —
-// this drives the area filter chips, so it should stay in sync with the
-// products we actually ship rather than growing a new value per entry.
-const AREAS = ['Code Push', 'CLI', 'Console', 'API', 'Flutter'] as const;
-type Area = (typeof AREAS)[number];
-
-interface ChangelogEntry {
-  /** Anchor id and permalink slug for this entry. */
-  id: string;
-  date: string;
-  version: string;
-  area: Area;
-  type: 'New' | 'Fixed' | 'Changed' | 'Deprecated';
-  title: string;
-  summary: string;
-  bullets: string[];
-  code?: string;
-  docLink?: { label: string; href: string };
-}
-
-// Hand-written, newest first. Add an entry here when something ships that a
-// developer integrating Code Push would want to know about.
-const ENTRIES: ChangelogEntry[] = [
-  {
-    id: 'staged-rollouts-in-one-command',
-    date: '2026-09-10',
-    version: '1.7.2',
-    area: 'Code Push',
-    type: 'New',
-    title: 'Staged rollouts in one command',
-    summary:
-      'shorebird patch --track=beta now takes --rollout, so a staged patch can start at 5% without a second command.',
-    bullets: [
-      '--rollout takes a whole percentage from 1 to 100. Omit it and the patch goes to the entire track, exactly as before.',
-      'Raise or halt a rollout from the console, or with shorebird patch rollout set 25.',
-      'Rollback still applies to the whole track — halting a rollout leaves the previous patch installed.',
-    ],
-    code: 'shorebird patch android --track=beta --rollout=5',
-    docLink: {
-      label: 'Percentage-based rollouts',
-      href: '/code-push/guides/percentage-based-rollouts/',
-    },
-  },
-];
+import {
+  AREAS,
+  CHANGELOG_DESCRIPTION,
+  CHANGELOG_TITLE,
+  ENTRIES,
+  groupByMonth,
+  type ChangelogEntry,
+} from '~/data/changelog';
 
 const TYPE_LABEL_COLOR: Record<ChangelogEntry['type'], string> = {
   New: 'new',
@@ -55,27 +17,13 @@ const TYPE_LABEL_COLOR: Record<ChangelogEntry['type'], string> = {
   Deprecated: 'deprecated',
 };
 
-function formatMonth(iso: string): string {
-  return new Date(iso).toLocaleDateString('en-US', {
-    month: 'long',
-    year: 'numeric',
-    timeZone: 'UTC',
-  });
-}
-
-const groups: { label: string; items: ChangelogEntry[] }[] = [];
-for (const e of ENTRIES) {
-  const label = formatMonth(e.date);
-  let group = groups.find((g) => g.label === label);
-  if (!group) groups.push((group = { label, items: [] }));
-  group.items.push(e);
-}
+const groups = groupByMonth(ENTRIES);
 ---
 
 <StarlightPage
   frontmatter={{
-    title: 'Changelog',
-    description: 'Everything we shipped to Code Push, the CLI, and the API.',
+    title: CHANGELOG_TITLE,
+    description: CHANGELOG_DESCRIPTION,
   }}
 >
   <p>
diff --git a/src/pages/changelog.md.ts b/src/pages/changelog.md.ts
new file mode 100644
index 00000000..11a46508
--- /dev/null
+++ b/src/pages/changelog.md.ts
@@ -0,0 +1,51 @@
+import {
+  CHANGELOG_DESCRIPTION,
+  CHANGELOG_TITLE,
+  ENTRIES,
+  groupByMonth,
+  type ChangelogEntry,
+} from '~/data/changelog';
+
+// The Markdown twin of `/changelog/`. `[...slug].md.ts` only covers content
+// collection pages, and the changelog is a standalone `.astro` page, so without
+// this route the `<link rel="alternate" type="text/markdown">` that `Head.astro`
+// emits for every page would point at a 404, and `Accept: text/markdown` on
+// `/changelog/` would fall back to HTML.
+export const prerender = true;
+
+function entryToMarkdown(e: ChangelogEntry): string {
+  return [
+    `### ${e.title}`,
+    `**${e.type}** in ${e.area}, version ${e.version}, ${e.date}. Permalink: [/changelog/#${e.id}](/changelog/#${e.id})`,
+    e.summary,
+    e.bullets.map((b) => `- ${b}`).join('\n'),
+    e.code && ['```sh', e.code, '```'].join('\n'),
+    e.docLink && `Docs: [${e.docLink.label}](${e.docLink.href})`,
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+export function GET() {
+  const frontmatter = [
+    '---',
+    `title: ${JSON.stringify(CHANGELOG_TITLE)}`,
+    `description: ${JSON.stringify(CHANGELOG_DESCRIPTION)}`,
+    '---',
+  ].join('\n');
+
+  const body = [
+    frontmatter,
+    `${CHANGELOG_DESCRIPTION} Newest first.`,
+    ...groupByMonth(ENTRIES).flatMap((group) => [
+      `## ${group.label}`,
+      ...group.items.map(entryToMarkdown),
+    ]),
+  ].join('\n\n');
+
+  // As in `[...slug].md.ts`, this header only applies in `astro dev` and
+  // `astro preview`; `public/_headers` sets it in production.
+  return new Response(`${body}\n`, {
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+  });
+}

From 3d897b354c76a19958df60869513b82de5a470f1 Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Sat, 19 Sep 2026 15:23:34 +0530
Subject: [PATCH 06/13] Give each changelog type badge its own color

New used the theme accent, which is gray in Nova, so it looked like the
area badge beside it. New is now green and Fixed moves to blue, the usual
changelog convention.

Light-mode text also darkens to reach 4.5:1 on the tinted pill at this
size: New #166534 (6.2:1), Fixed #1d4ed8 (5.6:1), Changed #7e22ce (5.7:1,
was 4.4:1), and Deprecated #92400e (6.3:1, was 2.8:1). Dark mode already
passed and keeps its shades, with Fixed at #93c5fd (8.7:1).
---
 src/pages/changelog.astro | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index 9f4eb390..e548c510 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -452,29 +452,35 @@ const groups = groupByMonth(ENTRIES);
     color: var(--sl-color-gray-2);
   }
 
+  /* Each type gets its own hue rather than the theme accent, which is gray
+     and made New look like the area badge next to it. Light-mode text shades
+     are dark enough for 4.5:1 contrast on their tinted pill at this size. */
   .cl-badge[data-type='new'] {
-    background: color-mix(in srgb, var(--sl-color-accent) 16%, transparent);
-    color: var(--sl-color-accent-high);
+    background: color-mix(in srgb, #22c55e 16%, transparent);
+    color: #166534;
   }
 
   .cl-badge[data-type='fixed'] {
-    background: color-mix(in srgb, #22c55e 16%, transparent);
-    color: #16a34a;
+    background: color-mix(in srgb, #3b82f6 16%, transparent);
+    color: #1d4ed8;
   }
 
   .cl-badge[data-type='changed'] {
     background: color-mix(in srgb, #a855f7 16%, transparent);
-    color: #9333ea;
+    color: #7e22ce;
   }
 
   .cl-badge[data-type='deprecated'] {
     background: color-mix(in srgb, #f59e0b 16%, transparent);
-    color: #d97706;
+    color: #92400e;
   }
 
-  :root[data-theme='dark'] .cl-badge[data-type='fixed'] {
+  :root[data-theme='dark'] .cl-badge[data-type='new'] {
     color: #4ade80;
   }
+  :root[data-theme='dark'] .cl-badge[data-type='fixed'] {
+    color: #93c5fd;
+  }
   :root[data-theme='dark'] .cl-badge[data-type='changed'] {
     color: #d8b4fe;
   }

From fbcba3807b2bfa43a62eee687dfda321020c0e99 Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:07:59 +0530
Subject: [PATCH 07/13] Fix changelog accessibility, text selection, and
 light-mode styling

- Name each entry toggle by its title, and announce the result count.
- Toggle from the header with a click handler instead of an overlay, so
  the title and summary text can be selected.
- Use hidden="until-found" so find-in-page reaches collapsed details.
- Sort entries by date instead of relying on array order.
- Render backticked text in summaries and bullets as inline code.
- Remove the inline-code border inside the command block, give the
  detail panel a fill in light mode, and keep newlines in commands.
---
 src/data/changelog.ts     |  17 ++++---
 src/pages/changelog.astro | 102 +++++++++++++++++++++++++++-----------
 2 files changed, 84 insertions(+), 35 deletions(-)

diff --git a/src/data/changelog.ts b/src/data/changelog.ts
index 27bc5526..9b9752db 100644
--- a/src/data/changelog.ts
+++ b/src/data/changelog.ts
@@ -28,8 +28,10 @@ export interface ChangelogEntry {
   docLink?: { label: string; href: string };
 }
 
-// Hand-written, newest first. Add an entry here when something ships that a
-// developer integrating Code Push would want to know about.
+// Hand-written; the page sorts them newest first. Add an entry here when
+// something ships that a developer integrating Code Push would want to know
+// about. Wrap commands and flags in backticks in `summary` and `bullets` to
+// render them as inline code, as in Markdown.
 export const ENTRIES: ChangelogEntry[] = [
   {
     id: 'staged-rollouts-in-one-command',
@@ -39,10 +41,10 @@ export const ENTRIES: ChangelogEntry[] = [
     type: 'New',
     title: 'Staged rollouts in one command',
     summary:
-      'shorebird patch --track=beta now takes --rollout, so a staged patch can start at 5% without a second command.',
+      '`shorebird patch --track=beta` now takes `--rollout`, so a staged patch can start at 5% without a second command.',
     bullets: [
-      '--rollout takes a whole percentage from 1 to 100. Omit it and the patch goes to the entire track, exactly as before.',
-      'Raise or halt a rollout from the console, or with shorebird patch rollout set 25.',
+      '`--rollout` takes a whole percentage from 1 to 100. Omit it and the patch goes to the entire track, exactly as before.',
+      'Raise or halt a rollout from the console, or with `shorebird patch rollout set 25`.',
       'Rollback still applies to the whole track — halting a rollout leaves the previous patch installed.',
     ],
     code: 'shorebird patch android --track=beta --rollout=5',
@@ -66,7 +68,10 @@ export function groupByMonth(
   entries: ChangelogEntry[],
 ): { label: string; items: ChangelogEntry[] }[] {
   const groups: { label: string; items: ChangelogEntry[] }[] = [];
-  for (const e of entries) {
+  // Sort rather than trust the array order: one entry out of place would
+  // otherwise start a second heading for its month.
+  const newestFirst = [...entries].sort((a, b) => b.date.localeCompare(a.date));
+  for (const e of newestFirst) {
     const label = formatMonth(e.date);
     let group = groups.find((g) => g.label === label);
     if (!group) groups.push((group = { label, items: [] }));
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index e548c510..a4a08806 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -1,5 +1,5 @@
 ---
-// cspell:ignore data-type white-space
+// cspell:ignore beforematch data-type white-space
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import {
   AREAS,
@@ -51,7 +51,7 @@ const groups = groupByMonth(ENTRIES);
       </svg>
       <input
         id="cl-search"
-        type="text"
+        type="search"
         placeholder="Search the changelog"
         aria-label="Search the changelog"
       />
@@ -68,7 +68,7 @@ const groups = groupByMonth(ENTRIES);
         ))
       }
     </div>
-    <span class="cl-count" id="cl-count">
+    <span class="cl-count" id="cl-count" aria-live="polite">
       {ENTRIES.length}
       {ENTRIES.length === 1 ? 'entry' : 'entries'}
     </span>
@@ -90,6 +90,7 @@ const groups = groupByMonth(ENTRIES);
               e.code ?? '',
             ]
               .join(' ')
+              .replaceAll('`', '')
               .toLowerCase();
             return (
               <article
@@ -101,9 +102,11 @@ const groups = groupByMonth(ENTRIES);
                 <div class="cl-head">
                   <button
                     class="cl-entry-toggle"
+                    id={`${e.id}-toggle`}
                     type="button"
                     aria-expanded="false"
                     aria-controls={`${e.id}-detail`}
+                    aria-labelledby={`${e.id}-title ${e.id}-toggle`}
                   >
                     <span class="cl-badge" data-type={TYPE_LABEL_COLOR[e.type]}>
                       {e.type}
@@ -128,13 +131,29 @@ const groups = groupByMonth(ENTRIES);
                       </svg>
                     </span>
                   </button>
-                  <h3 class="cl-title">{e.title}</h3>
-                  <p class="cl-summary">{e.summary}</p>
+                  <h3 class="cl-title" id={`${e.id}-title`}>
+                    {e.title}
+                  </h3>
+                  <p class="cl-summary">
+                    {e.summary
+                      .split('`')
+                      .map((part, i) => (i % 2 ? <code>{part}</code> : part))}
+                  </p>
                 </div>
-                <div class="cl-detail" id={`${e.id}-detail`} hidden>
+                {/* until-found lets the browser's find-in-page match text in a
+                    collapsed entry; the beforematch handler then opens it. */}
+                <div
+                  class="cl-detail"
+                  id={`${e.id}-detail`}
+                  hidden="until-found"
+                >
                   <ul class="cl-bullets">
                     {e.bullets.map((b) => (
-                      <li>{b}</li>
+                      <li>
+                        {b
+                          .split('`')
+                          .map((part, i) => (i % 2 ? <code>{part}</code> : part))}
+                      </li>
                     ))}
                   </ul>
                   {e.code && (
@@ -210,7 +229,10 @@ const groups = groupByMonth(ENTRIES);
         group.hidden = !hasVisible;
       }
 
-      countEl!.textContent = `${visibleCount} ${visibleCount === 1 ? 'entry' : 'entries'}`;
+      // Only write on a change, so the live region doesn't announce the
+      // count on page load.
+      const count = `${visibleCount} ${visibleCount === 1 ? 'entry' : 'entries'}`;
+      if (countEl!.textContent?.trim() !== count) countEl!.textContent = count;
       emptyEl!.hidden = visibleCount !== 0;
     }
 
@@ -229,15 +251,28 @@ const groups = groupByMonth(ENTRIES);
       const detail = entry.querySelector<HTMLElement>('.cl-detail');
       if (!toggle || !detail) return;
       toggle.setAttribute('aria-expanded', String(open));
-      detail.hidden = !open;
+      if (open) detail.removeAttribute('hidden');
+      else detail.setAttribute('hidden', 'until-found');
     }
 
     for (const entry of entries) {
       const toggle = entry.querySelector<HTMLButtonElement>('.cl-entry-toggle');
-      toggle?.addEventListener('click', () => {
+      if (!toggle) continue;
+      toggle.addEventListener('click', () => {
         const isOpen = toggle.getAttribute('aria-expanded') === 'true';
         setOpen(entry, !isOpen);
       });
+      // Clicking the title or summary toggles too, unless the click was
+      // the end of a text selection or landed on a link.
+      entry.querySelector('.cl-head')?.addEventListener('click', (ev) => {
+        const target = ev.target as Element;
+        if (toggle.contains(target) || target.closest('a')) return;
+        if (window.getSelection()?.toString()) return;
+        toggle.click();
+      });
+      entry
+        .querySelector('.cl-detail')
+        ?.addEventListener('beforematch', () => setOpen(entry, true));
     }
 
     for (const copyBtn of document.querySelectorAll<HTMLAnchorElement>(
@@ -390,18 +425,18 @@ const groups = groupByMonth(ENTRIES);
     border-bottom: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
   }
 
-  /* A button cannot contain links, so the button holds only the badge row
-     and its ::after stretches over the header to make the title and summary
-     toggle too. Links inside the header sit above that overlay. */
+  /* The button holds only the badge row; a click handler on the header
+     makes the title and summary toggle too, while leaving their text
+     selectable. */
   .cl-head {
-    position: relative;
     margin: 0 -0.75rem;
     padding: 0.5rem 0.75rem;
     border-radius: 0.75rem;
+    cursor: pointer;
     transition: background 0.15s;
   }
 
-  .cl-head:has(.cl-entry-toggle:hover) {
+  .cl-head:hover {
     background: color-mix(in srgb, var(--sl-color-gray-4) 8%, transparent);
   }
 
@@ -410,11 +445,6 @@ const groups = groupByMonth(ENTRIES);
     outline-offset: 2px;
   }
 
-  .cl-head a {
-    position: relative;
-    z-index: 1;
-  }
-
   .cl-entry-toggle {
     display: flex;
     align-items: center;
@@ -429,13 +459,6 @@ const groups = groupByMonth(ENTRIES);
     outline: 0;
   }
 
-  .cl-entry-toggle::after {
-    content: '';
-    position: absolute;
-    inset: 0;
-    border-radius: inherit;
-  }
-
   .cl-badge {
     height: 1.25rem;
     padding: 0 0.5rem;
@@ -512,7 +535,7 @@ const groups = groupByMonth(ENTRIES);
     display: block;
   }
 
-  .cl-head:has(.cl-entry-toggle:hover) .cl-mark {
+  .cl-head:hover .cl-mark {
     background: color-mix(in srgb, var(--sl-color-gray-4) 32%, transparent);
     color: var(--sl-color-white);
   }
@@ -543,6 +566,18 @@ const groups = groupByMonth(ENTRIES);
     padding: 1.25rem 1.5rem;
   }
 
+  /* The sidebar background is white in light mode, the same as the page. */
+  :root[data-theme='light'] .cl-detail {
+    background: var(--sl-color-gray-7, var(--sl-color-gray-6));
+  }
+
+  /* hidden="until-found" keeps the box rendered with its content hidden, so
+     drop the spacing that would otherwise leave an empty panel. */
+  .cl-detail[hidden] {
+    margin: 0;
+    padding: 0;
+  }
+
   .cl-bullets {
     margin: 0;
     padding-left: 1.1rem;
@@ -560,12 +595,21 @@ const groups = groupByMonth(ENTRIES);
     border-radius: 0.75rem;
     background: var(--sl-color-bg);
     overflow-x: auto;
-    white-space: nowrap;
+    white-space: pre;
     font-family: var(--sl-font-mono, ui-monospace, monospace);
     font-size: 0.85rem;
     color: var(--sl-color-gray-1);
   }
 
+  /* Starlight's inline-code border and padding would box the command a
+     second time inside the block. */
+  .cl-code code {
+    padding: 0;
+    border: 0;
+    background: none;
+    font-size: inherit;
+  }
+
   .cl-footer {
     display: flex;
     align-items: center;

From 10ce731566ad352c830b48c6c6f3d1dc6ca83acc Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:13:46 +0530
Subject: [PATCH 08/13] Replace the example changelog entry with real releases

The seeded entry described a --rollout flag and CLI 1.7.2, neither of
which exist. Replace it with six changes from CLI 1.6.120 to 1.6.123,
each checked against the release notes and CLI source.

- List the month headings under "On this page".
- Show each entry's date, and label the version as the CLI release,
  with a link to its release notes.
- Add an RSS feed at /changelog.xml, linked from the page and its head.
---
 public/_headers            |   4 +
 src/data/changelog.ts      | 167 +++++++++++++++++++++++++++++++------
 src/pages/changelog.astro  |  59 +++++++++++--
 src/pages/changelog.md.ts  |   5 +-
 src/pages/changelog.xml.ts |  60 +++++++++++++
 5 files changed, 258 insertions(+), 37 deletions(-)
 create mode 100644 src/pages/changelog.xml.ts

diff --git a/public/_headers b/public/_headers
index 84460079..bfb5fa8c 100644
--- a/public/_headers
+++ b/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: *
diff --git a/src/data/changelog.ts b/src/data/changelog.ts
index 9b9752db..22115881 100644
--- a/src/data/changelog.ts
+++ b/src/data/changelog.ts
@@ -1,14 +1,14 @@
-// cspell:words rollouts
+// cspell:words rollforward
 
-// Shared by the changelog page (`src/pages/changelog.astro`) and its
-// agent-facing Markdown twin (`src/pages/changelog.md.ts`), so both always
-// list the same entries.
+// Shared by the changelog page (`src/pages/changelog.astro`), its
+// agent-facing Markdown twin (`src/pages/changelog.md.ts`), and its RSS feed
+// (`src/pages/changelog.xml.ts`), so all three list the same entries.
 
 export const CHANGELOG_TITLE = 'Changelog';
 export const CHANGELOG_DESCRIPTION =
-  'Everything we shipped to Code Push, the CLI, and the API.';
+  'What we shipped to Code Push, the CLI, and the API, newest first.';
 
-// The parts of Shorebird a change can be filed under. Fixed on purpose —
+// The parts of Shorebird a change can be filed under. Fixed on purpose:
 // this drives the area filter chips, so it should stay in sync with the
 // products we actually ship rather than growing a new value per entry.
 export const AREAS = ['Code Push', 'CLI', 'Console', 'API', 'Flutter'] as const;
@@ -17,7 +17,9 @@ export type Area = (typeof AREAS)[number];
 export interface ChangelogEntry {
   /** Anchor id and permalink slug for this entry. */
   id: string;
+  /** Release date, as `YYYY-MM-DD`. */
   date: string;
+  /** The Shorebird CLI release that shipped the change, without the `v`. */
   version: string;
   area: Area;
   type: 'New' | 'Fixed' | 'Changed' | 'Deprecated';
@@ -28,33 +30,139 @@ export interface ChangelogEntry {
   docLink?: { label: string; href: string };
 }
 
-// Hand-written; the page sorts them newest first. Add an entry here when
-// something ships that a developer integrating Code Push would want to know
-// about. Wrap commands and flags in backticks in `summary` and `bullets` to
-// render them as inline code, as in Markdown.
+// Hand-written, in any order; readers see them newest first. Add an entry
+// here when something ships that a developer integrating Code Push would want
+// to know about. Wrap commands and flags in backticks in `summary` and
+// `bullets` to render them as inline code, as in Markdown.
 export const ENTRIES: ChangelogEntry[] = [
   {
-    id: 'staged-rollouts-in-one-command',
-    date: '2026-09-10',
-    version: '1.7.2',
+    id: 'flutter-version-fvm-and-system',
+    date: '2026-09-21',
+    version: '1.6.123',
+    area: 'CLI',
+    type: 'New',
+    title: 'Release with the Flutter version you already use',
+    summary:
+      '`--flutter-version` now accepts `fvm` and `system`, so you no longer have to look up and repeat your Flutter version number.',
+    bullets: [
+      '`--flutter-version=fvm` uses the version fvm resolves for your project from its `.fvmrc`. It requires `fvm` on your `PATH`.',
+      '`--flutter-version=system` uses the version reported by the `flutter` on your `PATH`.',
+      "Shorebird still builds with its own fork of Flutter at that version, not with your fvm or system install. A version Shorebird doesn't support fails the same way as one you name explicitly.",
+    ],
+    code: 'shorebird release android --flutter-version=fvm',
+    docLink: {
+      label: 'Match the Flutter version you already use',
+      href: '/getting-started/flutter-version/#match-the-flutter-version-you-already-use',
+    },
+  },
+  {
+    id: 'failed-patch-checks-for-replacement',
+    date: '2026-09-16',
+    version: '1.6.122',
     area: 'Code Push',
+    type: 'Fixed',
+    title: 'A patch that fails to load is replaced on the same launch',
+    summary:
+      'When a patch fails to load, the device now checks for a replacement patch right away instead of waiting for the next launch.',
+    bullets: [
+      'Previously, reporting the failure suppressed the update check, so the device ran the base release and stayed on the bad patch until it launched again.',
+      'Patch checks now report the patch the device is actually running, so each device is attributed to the right patch.',
+      'These fixes are in the updater built into your app, so they apply to releases built with Shorebird 1.6.122 or later.',
+    ],
+    docLink: {
+      label: 'Patch integrity and automatic rollback',
+      href: '/code-push/rollback/#patch-integrity-and-automatic-rollback',
+    },
+  },
+  {
+    id: 'flutter-3-47-4',
+    date: '2026-09-16',
+    version: '1.6.122',
+    area: 'Flutter',
+    type: 'New',
+    title: 'Flutter 3.47.4 support',
+    summary: 'Shorebird now supports Flutter 3.47.4 and Dart 3.13.3.',
+    bullets: [
+      'iOS: native assets now require iOS 15, raised from iOS 13.',
+      'iOS: a build now warns when Device Support Symbols are missing, instead of failing partway through.',
+      'Windows: Application Control and security policy blocks are handled instead of failing the build.',
+    ],
+    code: 'shorebird release ios --flutter-version=3.47.4',
+    docLink: {
+      label: 'Flutter versions',
+      href: '/getting-started/flutter-version/',
+    },
+  },
+  {
+    id: 'shorebird-apps-commands',
+    date: '2026-09-14',
+    version: '1.6.121',
+    area: 'CLI',
     type: 'New',
-    title: 'Staged rollouts in one command',
+    title: 'Manage apps from the CLI',
     summary:
-      '`shorebird patch --track=beta` now takes `--rollout`, so a staged patch can start at 5% without a second command.',
+      'New `shorebird apps` commands list, rename, delete, and transfer apps without opening the Console.',
     bullets: [
-      '`--rollout` takes a whole percentage from 1 to 100. Omit it and the patch goes to the entire track, exactly as before.',
-      'Raise or halt a rollout from the console, or with `shorebird patch rollout set 25`.',
-      'Rollback still applies to the whole track — halting a rollout leaves the previous patch installed.',
+      '`shorebird apps transfer --org-id <id>` moves an app into another organization. Run `shorebird account orgs` to find the id.',
+      '`shorebird apps rename --name <name>` changes the display name.',
+      "`shorebird apps delete` has no prompt. Pass `--confirm-name` with the app's current display name to confirm.",
     ],
-    code: 'shorebird patch android --track=beta --rollout=5',
+    code: 'shorebird apps transfer --app-id <id> --org-id 42',
     docLink: {
-      label: 'Percentage-based rollouts',
-      href: '/code-push/guides/percentage-based-rollouts/',
+      label: 'Transfer an app',
+      href: '/account/orgs/#transfer-an-app',
+    },
+  },
+  {
+    id: 'shorebird-channels-commands',
+    date: '2026-09-14',
+    version: '1.6.121',
+    area: 'CLI',
+    type: 'New',
+    title: 'Manage channels from the CLI',
+    summary:
+      'New `shorebird channels` commands create, list, and delete the channels (tracks) an app can publish to.',
+    bullets: [
+      'Publishing a patch with `--track=<name>` still creates that channel automatically.',
+      '`shorebird channels delete` is permanent and has no prompt. Pass `--confirm-name` with the channel name to confirm.',
+    ],
+    code: 'shorebird channels create --app-id <id> --name qa',
+    docLink: {
+      label: 'Staging patches',
+      href: '/code-push/guides/staging-patches/',
+    },
+  },
+  {
+    id: 'patches-rollback-and-rollforward',
+    date: '2026-08-28',
+    version: '1.6.120',
+    area: 'CLI',
+    type: 'New',
+    title: 'Roll patches back and forward from the CLI',
+    summary:
+      '`shorebird patches rollback` and `shorebird patches rollforward` do the same as the Rollback and Roll Forward actions in the Console.',
+    bullets: [
+      'Both take `--release-version` and `--patch-number`.',
+      'By default, a patch that is already in the requested state is reported and the command succeeds. Add `--require-change` to exit with an error instead.',
+    ],
+    code: 'shorebird patches rollback --release-version 1.0.0+1 --patch-number 1',
+    docLink: {
+      label: 'Roll back a patch',
+      href: '/code-push/rollback/',
     },
   },
 ];
 
+/** Link to the GitHub release notes for a CLI version. */
+export function releaseNotesUrl(version: string): string {
+  return `https://github.com/shorebirdtech/shorebird/releases/tag/v${version}`;
+}
+
+/** A copy of `entries`, newest first. Same-day entries keep their order. */
+export function newestFirst(entries: ChangelogEntry[]): ChangelogEntry[] {
+  return [...entries].sort((a, b) => b.date.localeCompare(a.date));
+}
+
 function formatMonth(iso: string): string {
   return new Date(iso).toLocaleDateString('en-US', {
     month: 'long',
@@ -63,18 +171,23 @@ function formatMonth(iso: string): string {
   });
 }
 
-/** `ENTRIES` grouped under "September 2026"-style headings, newest first. */
+/**
+ * `ENTRIES` grouped under "September 2026"-style headings, newest first.
+ * `id` ("september-2026") anchors the heading and its table-of-contents link.
+ */
 export function groupByMonth(
   entries: ChangelogEntry[],
-): { label: string; items: ChangelogEntry[] }[] {
-  const groups: { label: string; items: ChangelogEntry[] }[] = [];
+): { id: string; label: string; items: ChangelogEntry[] }[] {
+  const groups: { id: string; label: string; items: ChangelogEntry[] }[] = [];
   // Sort rather than trust the array order: one entry out of place would
   // otherwise start a second heading for its month.
-  const newestFirst = [...entries].sort((a, b) => b.date.localeCompare(a.date));
-  for (const e of newestFirst) {
+  for (const e of newestFirst(entries)) {
     const label = formatMonth(e.date);
     let group = groups.find((g) => g.label === label);
-    if (!group) groups.push((group = { label, items: [] }));
+    if (!group) {
+      const id = label.toLowerCase().replace(' ', '-');
+      groups.push((group = { id, label, items: [] }));
+    }
     group.items.push(e);
   }
   return groups;
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index a4a08806..9813b9ad 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -7,6 +7,7 @@ import {
   CHANGELOG_TITLE,
   ENTRIES,
   groupByMonth,
+  releaseNotesUrl,
   type ChangelogEntry,
 } from '~/data/changelog';
 
@@ -18,17 +19,39 @@ const TYPE_LABEL_COLOR: Record<ChangelogEntry['type'], string> = {
 };
 
 const groups = groupByMonth(ENTRIES);
+
+function formatDay(iso: string): string {
+  return new Date(iso).toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    timeZone: 'UTC',
+  });
+}
 ---
 
 <StarlightPage
   frontmatter={{
     title: CHANGELOG_TITLE,
     description: CHANGELOG_DESCRIPTION,
+    head: [
+      {
+        tag: 'link',
+        attrs: {
+          rel: 'alternate',
+          type: 'application/rss+xml',
+          title: 'Shorebird changelog',
+          href: '/changelog.xml',
+        },
+      },
+    ],
   }}
+  headings={groups.map((g) => ({ depth: 2, slug: g.id, text: g.label }))}
 >
   <p>
-    Everything we shipped to Code Push, the CLI, and the API. Expand an entry
-    for the full detail, the command, and the doc it belongs to.
+    What we shipped to Code Push, the CLI, and the API. Expand an entry for the
+    full detail, the command, and the doc it belongs to. Subscribe with the <a
+      href="/changelog.xml">RSS feed</a
+    >.
   </p>
 
   <div class="cl-toolbar not-content">
@@ -78,7 +101,9 @@ const groups = groupByMonth(ENTRIES);
     {
       groups.map((group) => (
         <div class="cl-group">
-          <h2 class="cl-month">{group.label}</h2>
+          <h2 class="cl-month" id={group.id}>
+            {group.label}
+          </h2>
           {group.items.map((e) => {
             const searchText = [
               e.title,
@@ -112,7 +137,11 @@ const groups = groupByMonth(ENTRIES);
                       {e.type}
                     </span>
                     <span class="cl-badge cl-badge-area">{e.area}</span>
-                    <span class="cl-version">{e.version}</span>
+                    <span class="cl-meta">
+                      <time datetime={e.date}>{formatDay(e.date)}</time>
+                      <span aria-hidden="true">·</span>
+                      <span class="cl-version">CLI {e.version}</span>
+                    </span>
                     <span class="cl-mark" aria-hidden="true">
                       <svg viewBox="0 0 16 16" width="12" height="12">
                         <path
@@ -165,6 +194,9 @@ const groups = groupByMonth(ENTRIES);
                         {e.docLink.label} →
                       </a>
                     )}
+                    <a href={releaseNotesUrl(e.version)} class="cl-notes-link">
+                      Release notes for {e.version}
+                    </a>
                     <span class="cl-permalink-group">
                       <span class="cl-permalink">/changelog/#{e.id}</span>
                       <a
@@ -187,7 +219,7 @@ const groups = groupByMonth(ENTRIES);
   </div>
 
   <p class="cl-empty" id="cl-empty" hidden>
-    Nothing matches that search — clear the field or pick a different area.
+    Nothing matches that search. Clear the field or pick a different area.
   </p>
 </StarlightPage>
 
@@ -511,14 +543,20 @@ const groups = groupByMonth(ENTRIES);
     color: #fbbf24;
   }
 
-  .cl-version {
+  .cl-meta {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
     margin-left: auto;
-    font-family: var(--sl-font-mono, ui-monospace, monospace);
     font-size: 0.75rem;
-    font-weight: 600;
     color: var(--sl-color-gray-3);
   }
 
+  .cl-version {
+    font-family: var(--sl-font-mono, ui-monospace, monospace);
+    font-weight: 600;
+  }
+
   .cl-mark {
     display: inline-flex;
     align-items: center;
@@ -625,6 +663,11 @@ const groups = groupByMonth(ENTRIES);
     font-weight: 600;
   }
 
+  .cl-notes-link {
+    font-size: 0.8rem;
+    color: var(--sl-color-gray-2);
+  }
+
   .cl-permalink-group {
     display: flex;
     align-items: center;
diff --git a/src/pages/changelog.md.ts b/src/pages/changelog.md.ts
index 11a46508..b977372e 100644
--- a/src/pages/changelog.md.ts
+++ b/src/pages/changelog.md.ts
@@ -3,6 +3,7 @@ import {
   CHANGELOG_TITLE,
   ENTRIES,
   groupByMonth,
+  releaseNotesUrl,
   type ChangelogEntry,
 } from '~/data/changelog';
 
@@ -16,7 +17,7 @@ export const prerender = true;
 function entryToMarkdown(e: ChangelogEntry): string {
   return [
     `### ${e.title}`,
-    `**${e.type}** in ${e.area}, version ${e.version}, ${e.date}. Permalink: [/changelog/#${e.id}](/changelog/#${e.id})`,
+    `**${e.type}** in ${e.area}, ${e.date}, Shorebird CLI ${e.version} ([release notes](${releaseNotesUrl(e.version)})). Permalink: [/changelog/#${e.id}](/changelog/#${e.id})`,
     e.summary,
     e.bullets.map((b) => `- ${b}`).join('\n'),
     e.code && ['```sh', e.code, '```'].join('\n'),
@@ -36,7 +37,7 @@ export function GET() {
 
   const body = [
     frontmatter,
-    `${CHANGELOG_DESCRIPTION} Newest first.`,
+    `${CHANGELOG_DESCRIPTION} RSS feed: [/changelog.xml](/changelog.xml)`,
     ...groupByMonth(ENTRIES).flatMap((group) => [
       `## ${group.label}`,
       ...group.items.map(entryToMarkdown),
diff --git a/src/pages/changelog.xml.ts b/src/pages/changelog.xml.ts
new file mode 100644
index 00000000..fcfb6b92
--- /dev/null
+++ b/src/pages/changelog.xml.ts
@@ -0,0 +1,60 @@
+import { CHANGELOG_DESCRIPTION, ENTRIES, newestFirst } from '~/data/changelog';
+
+// RSS 2.0 feed of the changelog, so readers can subscribe instead of checking
+// the page. Written by hand rather than with `@astrojs/rss`, since a flat list
+// of entries needs only a few tags.
+export const prerender = true;
+
+const SITE = 'https://docs.shorebird.dev';
+
+function escapeXml(text: string): string {
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+export function GET() {
+  const entries = newestFirst(ENTRIES);
+  const items = entries.map((e) => {
+    const link = `${SITE}/changelog/#${e.id}`;
+    // Feed readers show the description as plain text, so drop the
+    // backticks that mark inline code on the page.
+    const description = e.summary.replaceAll('`', '');
+    return [
+      '    <item>',
+      `      <title>${escapeXml(`${e.type}: ${e.title}`)}</title>`,
+      `      <link>${link}</link>`,
+      `      <guid isPermaLink="true">${link}</guid>`,
+      `      <pubDate>${new Date(e.date).toUTCString()}</pubDate>`,
+      `      <category>${escapeXml(e.area)}</category>`,
+      `      <description>${escapeXml(description)}</description>`,
+      '    </item>',
+    ].join('\n');
+  });
+
+  const xml = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+    '  <channel>',
+    '    <title>Shorebird changelog</title>',
+    `    <link>${SITE}/changelog/</link>`,
+    `    <atom:link href="${SITE}/changelog.xml" rel="self" type="application/rss+xml" />`,
+    `    <description>${escapeXml(CHANGELOG_DESCRIPTION)}</description>`,
+    '    <language>en-us</language>',
+    entries[0] &&
+      `    <lastBuildDate>${new Date(entries[0].date).toUTCString()}</lastBuildDate>`,
+    ...items,
+    '  </channel>',
+    '</rss>',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  // As in `changelog.md.ts`, this header only applies in `astro dev` and
+  // `astro preview`; `public/_headers` sets it in production.
+  return new Response(`${xml}\n`, {
+    headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+  });
+}

From d73ec705d68b63f25319bf5404f44040d3a8012a Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:19:29 +0530
Subject: [PATCH 09/13] Redesign the changelog list as a timeline

- Put each entry's date and CLI version in a left column, joined by a
  line with a dot in the change type's color. At narrow widths the date
  moves above the badges and the line stays on the left.
- Show live counts on the area chips, dim chips with no matches for the
  current search, and hide areas that have no entries yet.
- Mark the active chip with aria-pressed and a solid fill.
- Replace the permalink text and glyph with a "Copy link" button, and
  shorten the release notes link.
- Keep the chips on one scrolling row on phones.
---
 src/pages/changelog.astro | 556 +++++++++++++++++++++++++-------------
 1 file changed, 370 insertions(+), 186 deletions(-)

diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index 9813b9ad..f07d51f3 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -1,5 +1,5 @@
 ---
-// cspell:ignore beforematch data-type white-space
+// cspell:ignore beforematch data-type nums white-space
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import {
   AREAS,
@@ -20,6 +20,9 @@ const TYPE_LABEL_COLOR: Record<ChangelogEntry['type'], string> = {
 
 const groups = groupByMonth(ENTRIES);
 
+// Only offer a chip for an area that has entries, so no filter starts empty.
+const areas = AREAS.filter((a) => ENTRIES.some((e) => e.area === a));
+
 function formatDay(iso: string): string {
   return new Date(iso).toLocaleDateString('en-US', {
     month: 'short',
@@ -80,27 +83,32 @@ function formatDay(iso: string): string {
       />
     </div>
     <div class="cl-chips" role="group" aria-label="Filter by area">
-      <button class="cl-chip is-active" data-area="All" type="button"
-        >All</button
-      >
       {
-        AREAS.map((a) => (
-          <button class="cl-chip" data-area={a} type="button">
+        ['All', ...areas].map((a) => (
+          <button
+            class:list={['cl-chip', { 'is-active': a === 'All' }]}
+            data-area={a}
+            type="button"
+            aria-pressed={a === 'All' ? 'true' : 'false'}
+          >
             {a}
+            <span class="cl-chip-count">
+              {a === 'All'
+                ? ENTRIES.length
+                : ENTRIES.filter((e) => e.area === a).length}
+            </span>
           </button>
         ))
       }
     </div>
-    <span class="cl-count" id="cl-count" aria-live="polite">
-      {ENTRIES.length}
-      {ENTRIES.length === 1 ? 'entry' : 'entries'}
-    </span>
+    {/* The chips show the counts; this tells screen reader users. */}
+    <span class="sr-only" id="cl-count" aria-live="polite"></span>
   </div>
 
   <div class="cl-list" id="cl-list">
     {
       groups.map((group) => (
-        <div class="cl-group">
+        <section class="cl-group">
           <h2 class="cl-month" id={group.id}>
             {group.label}
           </h2>
@@ -122,98 +130,118 @@ function formatDay(iso: string): string {
                 class="cl-entry"
                 id={e.id}
                 data-area={e.area}
+                data-type={TYPE_LABEL_COLOR[e.type]}
                 data-search={searchText}
               >
-                <div class="cl-head">
-                  <button
-                    class="cl-entry-toggle"
-                    id={`${e.id}-toggle`}
-                    type="button"
-                    aria-expanded="false"
-                    aria-controls={`${e.id}-detail`}
-                    aria-labelledby={`${e.id}-title ${e.id}-toggle`}
-                  >
-                    <span class="cl-badge" data-type={TYPE_LABEL_COLOR[e.type]}>
-                      {e.type}
-                    </span>
-                    <span class="cl-badge cl-badge-area">{e.area}</span>
-                    <span class="cl-meta">
-                      <time datetime={e.date}>{formatDay(e.date)}</time>
-                      <span aria-hidden="true">·</span>
-                      <span class="cl-version">CLI {e.version}</span>
-                    </span>
-                    <span class="cl-mark" aria-hidden="true">
-                      <svg viewBox="0 0 16 16" width="12" height="12">
-                        <path
-                          d="M2 8h12"
-                          stroke="currentColor"
-                          stroke-width="2"
-                          stroke-linecap="round"
-                        />
-                        <path
-                          class="cl-mark-v"
-                          d="M8 2v12"
-                          stroke="currentColor"
-                          stroke-width="2"
-                          stroke-linecap="round"
-                        />
-                      </svg>
-                    </span>
-                  </button>
-                  <h3 class="cl-title" id={`${e.id}-title`}>
-                    {e.title}
-                  </h3>
-                  <p class="cl-summary">
-                    {e.summary
-                      .split('`')
-                      .map((part, i) => (i % 2 ? <code>{part}</code> : part))}
-                  </p>
+                <div class="cl-when">
+                  <time datetime={e.date}>{formatDay(e.date)}</time>
+                  <span class="cl-version">CLI {e.version}</span>
                 </div>
-                {/* until-found lets the browser's find-in-page match text in a
-                    collapsed entry; the beforematch handler then opens it. */}
-                <div
-                  class="cl-detail"
-                  id={`${e.id}-detail`}
-                  hidden="until-found"
-                >
-                  <ul class="cl-bullets">
-                    {e.bullets.map((b) => (
-                      <li>
-                        {b
-                          .split('`')
-                          .map((part, i) => (i % 2 ? <code>{part}</code> : part))}
-                      </li>
-                    ))}
-                  </ul>
-                  {e.code && (
-                    <pre class="cl-code"><code>$ {e.code}</code></pre>
-                  )}
-                  <div class="cl-footer">
-                    {e.docLink && (
-                      <a href={e.docLink.href} class="cl-doc-link">
-                        {e.docLink.label} →
-                      </a>
+                <div class="cl-body">
+                  <div class="cl-head">
+                    <button
+                      class="cl-entry-toggle"
+                      id={`${e.id}-toggle`}
+                      type="button"
+                      aria-expanded="false"
+                      aria-controls={`${e.id}-detail`}
+                      aria-labelledby={`${e.id}-title ${e.id}-toggle`}
+                    >
+                      <span
+                        class="cl-badge"
+                        data-type={TYPE_LABEL_COLOR[e.type]}
+                      >
+                        {e.type}
+                      </span>
+                      <span class="cl-badge cl-badge-area">{e.area}</span>
+                      <span class="cl-mark" aria-hidden="true">
+                        <svg viewBox="0 0 16 16" width="12" height="12">
+                          <path
+                            d="M2 8h12"
+                            stroke="currentColor"
+                            stroke-width="2"
+                            stroke-linecap="round"
+                          />
+                          <path
+                            class="cl-mark-v"
+                            d="M8 2v12"
+                            stroke="currentColor"
+                            stroke-width="2"
+                            stroke-linecap="round"
+                          />
+                        </svg>
+                      </span>
+                    </button>
+                    <h3 class="cl-title" id={`${e.id}-title`}>
+                      {e.title}
+                    </h3>
+                    <p class="cl-summary">
+                      {e.summary
+                        .split('`')
+                        .map((part, i) => (i % 2 ? <code>{part}</code> : part))}
+                    </p>
+                  </div>
+                  {/* until-found lets the browser's find-in-page match text in
+                      a collapsed entry; the beforematch handler then opens it. */}
+                  <div
+                    class="cl-detail"
+                    id={`${e.id}-detail`}
+                    hidden="until-found"
+                  >
+                    <ul class="cl-bullets">
+                      {e.bullets.map((b) => (
+                        <li>
+                          {b
+                            .split('`')
+                            .map((part, i) =>
+                              i % 2 ? <code>{part}</code> : part,
+                            )}
+                        </li>
+                      ))}
+                    </ul>
+                    {e.code && (
+                      <pre class="cl-code"><code>$ {e.code}</code></pre>
                     )}
-                    <a href={releaseNotesUrl(e.version)} class="cl-notes-link">
-                      Release notes for {e.version}
-                    </a>
-                    <span class="cl-permalink-group">
-                      <span class="cl-permalink">/changelog/#{e.id}</span>
+                    <div class="cl-footer">
+                      {e.docLink && (
+                        <a href={e.docLink.href} class="cl-doc-link">
+                          {e.docLink.label} →
+                        </a>
+                      )}
+                      <a
+                        href={releaseNotesUrl(e.version)}
+                        class="cl-notes-link"
+                      >
+                        Release notes ↗
+                      </a>
                       <a
                         href={`#${e.id}`}
                         class="cl-copy"
-                        aria-label="Copy link to this entry"
                         data-copy={`#${e.id}`}
                       >
-                        ⧉
+                        <svg
+                          viewBox="0 0 24 24"
+                          width="14"
+                          height="14"
+                          fill="none"
+                          stroke="currentColor"
+                          stroke-width="2"
+                          stroke-linecap="round"
+                          stroke-linejoin="round"
+                          aria-hidden="true"
+                        >
+                          <path d="M10 13a5 5 0 0 0 7.5.5l3-3a5 5 0 0 0-7-7l-1.7 1.7" />
+                          <path d="M14 11a5 5 0 0 0-7.5-.5l-3 3a5 5 0 0 0 7 7l1.7-1.7" />
+                        </svg>
+                        <span class="cl-copy-label">Copy link</span>
                       </a>
-                    </span>
+                    </div>
                   </div>
                 </div>
               </article>
             );
           })}
-        </div>
+        </section>
       ))
     }
   </div>
@@ -242,29 +270,45 @@ function formatDay(iso: string): string {
     if (!search || !countEl || !emptyEl) return;
 
     let area = 'All';
+    let lastQuery = '';
 
     function applyFilters() {
       const q = (search?.value ?? '').trim().toLowerCase();
       let visibleCount = 0;
+      // Per-area matches for the current search, ignoring the area filter,
+      // so each chip says how many entries picking it would show.
+      const areaCounts = new Map<string, number>([['All', 0]]);
 
       for (const entry of entries) {
-        const matchesArea = area === 'All' || entry.dataset.area === area;
+        const entryArea = entry.dataset.area ?? '';
         const matchesSearch =
           q === '' || (entry.dataset.search ?? '').includes(q);
-        const visible = matchesArea && matchesSearch;
+        if (matchesSearch) {
+          areaCounts.set('All', areaCounts.get('All')! + 1);
+          areaCounts.set(entryArea, (areaCounts.get(entryArea) ?? 0) + 1);
+        }
+        const visible = matchesSearch && (area === 'All' || entryArea === area);
         entry.hidden = !visible;
         if (visible) visibleCount += 1;
       }
 
+      for (const chip of chips) {
+        const n = areaCounts.get(chip.dataset.area ?? '') ?? 0;
+        const countSpan = chip.querySelector('.cl-chip-count');
+        if (countSpan) countSpan.textContent = String(n);
+        chip.classList.toggle('is-empty', n === 0);
+      }
+
       for (const group of groups) {
         const hasVisible = group.querySelector('.cl-entry:not([hidden])');
         group.hidden = !hasVisible;
       }
 
-      // Only write on a change, so the live region doesn't announce the
-      // count on page load.
-      const count = `${visibleCount} ${visibleCount === 1 ? 'entry' : 'entries'}`;
-      if (countEl!.textContent?.trim() !== count) countEl!.textContent = count;
+      // Announce only after the reader changes something, not on page load.
+      if (q !== lastQuery || area !== 'All' || countEl!.textContent) {
+        countEl!.textContent = `${visibleCount} ${visibleCount === 1 ? 'entry' : 'entries'}`;
+      }
+      lastQuery = q;
       emptyEl!.hidden = visibleCount !== 0;
     }
 
@@ -273,7 +317,10 @@ function formatDay(iso: string): string {
     for (const chip of chips) {
       chip.addEventListener('click', () => {
         area = chip.dataset.area ?? 'All';
-        for (const c of chips) c.classList.toggle('is-active', c === chip);
+        for (const c of chips) {
+          c.classList.toggle('is-active', c === chip);
+          c.setAttribute('aria-pressed', String(c === chip));
+        }
         applyFilters();
       });
     }
@@ -321,12 +368,13 @@ function formatDay(iso: string): string {
           // Clipboard access can fail (permissions, insecure context).
           return;
         }
-        const label = copyBtn.getAttribute('aria-label') ?? '';
-        copyBtn.textContent = '✓';
-        copyBtn.setAttribute('aria-label', 'Link copied');
+        const label = copyBtn.querySelector('.cl-copy-label');
+        if (!label) return;
+        label.textContent = 'Copied';
+        copyBtn.classList.add('is-copied');
         setTimeout(() => {
-          copyBtn.textContent = '⧉';
-          copyBtn.setAttribute('aria-label', label);
+          label.textContent = 'Copy link';
+          copyBtn.classList.remove('is-copied');
         }, 1500);
       });
     }
@@ -357,24 +405,31 @@ function formatDay(iso: string): string {
 </script>
 
 <style>
+  /* Toolbar */
+
   .cl-toolbar {
     display: flex;
     flex-wrap: wrap;
     align-items: center;
     gap: 0.75rem;
-    margin: 1.5rem 0;
+    margin: 1.5rem 0 0.5rem;
   }
 
   .cl-search {
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    flex: 1 1 16rem;
+    flex: 1 1 14rem;
     height: 2.5rem;
     padding: 0 0.85rem;
     border: 1px solid var(--sl-color-gray-5);
     border-radius: 999px;
     background: var(--sl-color-bg-sidebar);
+    transition: border-color 0.15s;
+  }
+
+  .cl-search:focus-within {
+    border-color: var(--sl-color-gray-3);
   }
 
   .cl-search-icon {
@@ -400,87 +455,167 @@ function formatDay(iso: string): string {
   .cl-chips {
     display: flex;
     flex-wrap: wrap;
-    gap: 0.5rem;
+    gap: 0.4rem;
   }
 
   .cl-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
     height: 2rem;
-    padding: 0 0.85rem;
+    padding: 0 0.5rem 0 0.8rem;
     border: 1px solid var(--sl-color-gray-5);
     border-radius: 999px;
     background: transparent;
     color: var(--sl-color-gray-2);
     font-size: 0.8rem;
     font-weight: 600;
+    white-space: nowrap;
     cursor: pointer;
     transition:
       background 0.15s,
       border-color 0.15s,
-      color 0.15s;
+      color 0.15s,
+      opacity 0.15s;
   }
 
   .cl-chip:hover {
     border-color: var(--sl-color-gray-3);
   }
 
+  .cl-chip-count {
+    min-width: 1.25rem;
+    padding: 0 0.3rem;
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--sl-color-gray-4) 22%, transparent);
+    font-size: 0.7rem;
+    line-height: 1.25rem;
+    text-align: center;
+    font-variant-numeric: tabular-nums;
+  }
+
   .cl-chip.is-active {
-    background: color-mix(in srgb, var(--sl-color-accent) 16%, transparent);
-    border-color: var(--sl-color-accent);
-    color: var(--sl-color-accent-high);
+    background: var(--sl-color-white);
+    border-color: var(--sl-color-white);
+    color: var(--sl-color-black);
   }
 
-  .cl-count {
-    margin-left: auto;
-    font-family: var(--sl-font-mono, ui-monospace, monospace);
-    font-size: 0.8rem;
-    color: var(--sl-color-gray-3);
+  .cl-chip.is-active .cl-chip-count {
+    background: color-mix(in srgb, var(--sl-color-black) 14%, transparent);
+  }
+
+  .cl-chip.is-empty:not(.is-active) {
+    opacity: 0.45;
+  }
+
+  /* Timeline. Each entry is a date gutter and a body; the bodies' left
+     borders join into one line, with a dot per entry in its type's color. */
+
+  .cl-list {
+    container-type: inline-size;
   }
 
   .cl-group {
-    margin-top: 2rem;
+    margin-top: 2.25rem;
   }
 
   .cl-month {
-    margin: 0 0 0.75rem;
-    font-size: 0.85rem;
-    font-weight: 600;
-    letter-spacing: 0.04em;
+    margin: 0 0 0.5rem;
+    font-size: 0.8rem;
+    font-weight: 700;
+    letter-spacing: 0.06em;
     text-transform: uppercase;
     color: var(--sl-color-gray-3);
     border: 0;
-    padding-bottom: 0.5rem;
-    border-bottom: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+    padding: 0;
+  }
+
+  /* Starlight's content styles put a top margin between sibling blocks,
+     which would open gaps in the timeline line. */
+  .cl-entry,
+  .cl-when,
+  .cl-body,
+  .cl-head {
+    margin: 0;
   }
 
   .cl-entry {
-    padding: 1.1rem 0;
-    border-bottom: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+    --cl-dot: var(--sl-color-gray-4);
+    display: grid;
+    grid-template-columns: 6rem 1fr;
+    column-gap: 1.25rem;
+  }
+
+  .cl-entry[data-type='new'] {
+    --cl-dot: #22c55e;
+  }
+  .cl-entry[data-type='fixed'] {
+    --cl-dot: #3b82f6;
+  }
+  .cl-entry[data-type='changed'] {
+    --cl-dot: #a855f7;
+  }
+  .cl-entry[data-type='deprecated'] {
+    --cl-dot: #f59e0b;
+  }
+
+  .cl-when {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-end;
+    gap: 0.15rem;
+    padding-top: 1.1rem;
+    text-align: right;
+  }
+
+  .cl-when time {
+    font-size: 0.85rem;
+    font-weight: 600;
+    color: var(--sl-color-gray-2);
+  }
+
+  .cl-version {
+    font-family: var(--sl-font-mono, ui-monospace, monospace);
+    font-size: 0.7rem;
+    color: var(--sl-color-gray-3);
+  }
+
+  .cl-body {
+    position: relative;
+    min-width: 0;
+    padding: 1rem 0 1.25rem 1.5rem;
+    border-left: 1px solid var(--sl-color-gray-5);
+  }
+
+  .cl-body::before {
+    content: '';
+    position: absolute;
+    top: 1.5rem;
+    left: -0.3125rem;
+    width: 0.5625rem;
+    height: 0.5625rem;
+    border-radius: 50%;
+    background: var(--cl-dot);
+    box-shadow: 0 0 0 0.25rem var(--sl-color-bg);
   }
 
   /* The button holds only the badge row; a click handler on the header
      makes the title and summary toggle too, while leaving their text
      selectable. */
   .cl-head {
-    margin: 0 -0.75rem;
-    padding: 0.5rem 0.75rem;
-    border-radius: 0.75rem;
+    border-radius: 0.5rem;
     cursor: pointer;
-    transition: background 0.15s;
-  }
-
-  .cl-head:hover {
-    background: color-mix(in srgb, var(--sl-color-gray-4) 8%, transparent);
   }
 
   .cl-head:has(.cl-entry-toggle:focus-visible) {
-    outline: 2px solid var(--sl-color-accent);
-    outline-offset: 2px;
+    outline: 2px solid var(--sl-color-white);
+    outline-offset: 0.35rem;
   }
 
   .cl-entry-toggle {
     display: flex;
     align-items: center;
-    gap: 0.5rem;
+    gap: 0.4rem;
     flex-wrap: wrap;
     width: 100%;
     padding: 0;
@@ -543,30 +678,19 @@ function formatDay(iso: string): string {
     color: #fbbf24;
   }
 
-  .cl-meta {
-    display: flex;
-    align-items: center;
-    gap: 0.4rem;
-    margin-left: auto;
-    font-size: 0.75rem;
-    color: var(--sl-color-gray-3);
-  }
-
-  .cl-version {
-    font-family: var(--sl-font-mono, ui-monospace, monospace);
-    font-weight: 600;
-  }
-
   .cl-mark {
     display: inline-flex;
     align-items: center;
     justify-content: center;
     width: 1.6rem;
     height: 1.6rem;
+    margin-left: auto;
     border-radius: 50%;
     background: color-mix(in srgb, var(--sl-color-gray-4) 16%, transparent);
     color: var(--sl-color-gray-2);
-    transition: background 0.15s;
+    transition:
+      background 0.15s,
+      color 0.15s;
   }
 
   .cl-mark svg {
@@ -583,25 +707,35 @@ function formatDay(iso: string): string {
   }
 
   .cl-title {
-    margin: 0.6rem 0 0;
-    font-size: 1.1rem;
+    margin: 0.5rem 0 0;
+    font-size: 1.05rem;
     font-weight: 600;
+    line-height: 1.4;
     color: var(--sl-color-white);
+    text-decoration: underline 1px transparent;
+    text-underline-offset: 0.2em;
+    transition: text-decoration-color 0.15s;
+  }
+
+  .cl-head:hover .cl-title {
+    text-decoration-color: var(--sl-color-gray-4);
   }
 
   .cl-summary {
-    margin: 0.4rem 0 0;
-    max-width: 68ch;
+    margin: 0.35rem 0 0;
     font-size: 0.9rem;
     line-height: 1.6;
     color: var(--sl-color-gray-2);
   }
 
+  /* Detail */
+
   .cl-detail {
-    margin-top: 1rem;
+    margin-top: 0.9rem;
     background: var(--sl-color-bg-sidebar);
-    border-radius: 1rem;
-    padding: 1.25rem 1.5rem;
+    border: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+    border-radius: 0.75rem;
+    padding: 1rem 1.25rem;
   }
 
   /* The sidebar background is white in light mode, the same as the page. */
@@ -614,6 +748,7 @@ function formatDay(iso: string): string {
   .cl-detail[hidden] {
     margin: 0;
     padding: 0;
+    border: 0;
   }
 
   .cl-bullets {
@@ -621,21 +756,21 @@ function formatDay(iso: string): string {
     padding-left: 1.1rem;
     display: flex;
     flex-direction: column;
-    gap: 0.55rem;
+    gap: 0.45rem;
     font-size: 0.875rem;
     line-height: 1.6;
     color: var(--sl-color-gray-2);
   }
 
   .cl-code {
-    margin: 1rem 0 0;
-    padding: 0.85rem 1.1rem;
-    border-radius: 0.75rem;
+    margin: 0.9rem 0 0;
+    padding: 0.75rem 1rem;
+    border-radius: 0.5rem;
     background: var(--sl-color-bg);
     overflow-x: auto;
     white-space: pre;
     font-family: var(--sl-font-mono, ui-monospace, monospace);
-    font-size: 0.85rem;
+    font-size: 0.82rem;
     color: var(--sl-color-gray-1);
   }
 
@@ -651,46 +786,34 @@ function formatDay(iso: string): string {
   .cl-footer {
     display: flex;
     align-items: center;
-    gap: 1rem;
+    gap: 0.5rem 1.25rem;
     flex-wrap: wrap;
-    margin-top: 1rem;
-    padding-top: 1rem;
-    border-top: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
+    margin-top: 0.9rem;
+    font-size: 0.85rem;
   }
 
   .cl-doc-link {
-    font-size: 0.875rem;
     font-weight: 600;
   }
 
   .cl-notes-link {
-    font-size: 0.8rem;
     color: var(--sl-color-gray-2);
   }
 
-  .cl-permalink-group {
-    display: flex;
-    align-items: center;
-    gap: 0.5rem;
-    margin-left: auto;
-  }
-
-  .cl-permalink {
-    font-family: var(--sl-font-mono, ui-monospace, monospace);
-    font-size: 0.72rem;
-    color: var(--sl-color-gray-3);
-  }
-
   .cl-copy {
-    display: flex;
+    display: inline-flex;
     align-items: center;
-    justify-content: center;
-    width: 1.6rem;
-    height: 1.6rem;
-    border-radius: 0.4rem;
+    gap: 0.35rem;
+    margin-left: auto;
+    padding: 0.2rem 0.6rem;
     border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
     color: var(--sl-color-gray-2);
-    font-size: 0.75rem;
+    font-size: 0.78rem;
+    text-decoration: none;
+    transition:
+      border-color 0.15s,
+      color 0.15s;
   }
 
   .cl-copy:hover {
@@ -698,10 +821,71 @@ function formatDay(iso: string): string {
     color: var(--sl-color-white);
   }
 
+  .cl-copy.is-copied {
+    border-color: #22c55e;
+    color: var(--sl-color-white);
+  }
+
   .cl-empty {
     margin-top: 1.5rem;
     padding: 1.5rem 0;
-    border-top: 1px solid var(--sl-color-gray-6, var(--sl-color-gray-5));
     color: var(--sl-color-gray-2);
   }
+
+  /* Narrow content column (phones, or a squeezed layout): drop the date
+     gutter, move the date above the badges, and let the chips scroll
+     sideways in one row instead of wrapping. */
+  @container (max-width: 34rem) {
+    .cl-entry {
+      grid-template-columns: 1fr;
+      padding-left: 1.25rem;
+      border-left: 1px solid var(--sl-color-gray-5);
+      position: relative;
+    }
+
+    .cl-entry::before {
+      content: '';
+      position: absolute;
+      top: 1.35rem;
+      left: -0.3125rem;
+      width: 0.5625rem;
+      height: 0.5625rem;
+      border-radius: 50%;
+      background: var(--cl-dot);
+      box-shadow: 0 0 0 0.25rem var(--sl-color-bg);
+    }
+
+    .cl-when {
+      flex-direction: row;
+      align-items: baseline;
+      gap: 0.5rem;
+      padding-top: 1rem;
+      text-align: left;
+    }
+
+    .cl-body {
+      padding: 0.4rem 0 1.25rem;
+      border-left: 0;
+    }
+
+    .cl-body::before {
+      content: none;
+    }
+  }
+
+  @media (max-width: 40rem) {
+    .cl-chips {
+      flex-wrap: nowrap;
+      overflow-x: auto;
+      width: 100%;
+      margin: 0 -1rem;
+      padding: 0 1rem;
+      box-sizing: content-box;
+      scrollbar-width: none;
+    }
+
+    .cl-chips::-webkit-scrollbar {
+      display: none;
+    }
+  }
 </style>

From 6748c86ecc73fcc004bc5928e29b9f5a819b09b5 Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:31:22 +0530
Subject: [PATCH 10/13] Move changelog entries to Markdown files checked at
 build

Each entry is now a Markdown file in src/content/changelog/, named for
its permalink: frontmatter for the metadata, then a summary paragraph,
a bullet list, and an optional sh code block. Copy _template.md to add
one; it documents every field.

The build fails with a message naming the file and line when:
- a field is missing or malformed (date not YYYY-MM-DD, a "v" on the
  version, an unknown area or type);
- a CLI or Flutter entry has no version (Console, API, and server-side
  Code Push entries may omit it);
- docLink points at a page that doesn't exist, or at a missing heading;
- the body has anything besides the summary, bullets, and code block.

The page, /changelog.md, and /changelog.xml render the same as before.
---
 .cspell.yaml                                  |   1 +
 src/content.config.ts                         |  10 +
 src/content/changelog/_template.md            |  45 +++
 .../failed-patch-checks-for-replacement.md    |  20 ++
 src/content/changelog/flutter-3-47-4.md       |  22 ++
 .../flutter-version-fvm-and-system.md         |  25 ++
 .../patches-rollback-and-rollforward.md       |  21 ++
 .../changelog/shorebird-apps-commands.md      |  23 ++
 .../changelog/shorebird-channels-commands.md  |  22 ++
 src/data/changelog-schema.ts                  |  51 +++
 src/data/changelog.ts                         | 297 ++++++++++--------
 src/pages/changelog.astro                     |  25 +-
 src/pages/changelog.md.ts                     |  15 +-
 src/pages/changelog.xml.ts                    |   6 +-
 14 files changed, 428 insertions(+), 155 deletions(-)
 create mode 100644 src/content/changelog/_template.md
 create mode 100644 src/content/changelog/failed-patch-checks-for-replacement.md
 create mode 100644 src/content/changelog/flutter-3-47-4.md
 create mode 100644 src/content/changelog/flutter-version-fvm-and-system.md
 create mode 100644 src/content/changelog/patches-rollback-and-rollforward.md
 create mode 100644 src/content/changelog/shorebird-apps-commands.md
 create mode 100644 src/content/changelog/shorebird-channels-commands.md
 create mode 100644 src/data/changelog-schema.ts

diff --git a/.cspell.yaml b/.cspell.yaml
index 431311b0..3a755dd7 100644
--- a/.cspell.yaml
+++ b/.cspell.yaml
@@ -103,6 +103,7 @@ words:
   - previewable
   - recompiles
   - riverpod
+  - rollforward
   - rollouts
   - rsassa
   - sdkman
diff --git a/src/content.config.ts b/src/content.config.ts
index 5e8d8113..1cd6c589 100644
--- a/src/content.config.ts
+++ b/src/content.config.ts
@@ -1,8 +1,10 @@
 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() }),
@@ -10,4 +12,12 @@ export const collections = {
     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,
+  }),
 };
diff --git a/src/content/changelog/_template.md b/src/content/changelog/_template.md
new file mode 100644
index 00000000..b47b447a
--- /dev/null
+++ b/src/content/changelog/_template.md
@@ -0,0 +1,45 @@
+---
+# 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 release shipped, as YYYY-MM-DD with no quotes.
+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, and a #fragment must match a heading on it. Delete both 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.
+-->
diff --git a/src/content/changelog/failed-patch-checks-for-replacement.md b/src/content/changelog/failed-patch-checks-for-replacement.md
new file mode 100644
index 00000000..ff362df3
--- /dev/null
+++ b/src/content/changelog/failed-patch-checks-for-replacement.md
@@ -0,0 +1,20 @@
+---
+title: A patch that fails to load is replaced on the same launch
+date: 2026-09-16
+version: 1.6.122
+area: Code Push
+type: Fixed
+docLink:
+  label: Patch integrity and automatic rollback
+  href: /code-push/rollback/#patch-integrity-and-automatic-rollback
+---
+
+When a patch fails to load, the device now checks for a replacement patch right
+away instead of waiting for the next launch.
+
+- Previously, reporting the failure suppressed the update check, so the device
+  ran the base release and stayed on the bad patch until it launched again.
+- Patch checks now report the patch the device is actually running, so each
+  device is attributed to the right patch.
+- These fixes are in the updater built into your app, so they apply to releases
+  built with Shorebird 1.6.122 or later.
diff --git a/src/content/changelog/flutter-3-47-4.md b/src/content/changelog/flutter-3-47-4.md
new file mode 100644
index 00000000..c7602198
--- /dev/null
+++ b/src/content/changelog/flutter-3-47-4.md
@@ -0,0 +1,22 @@
+---
+title: Flutter 3.47.4 support
+date: 2026-09-16
+version: 1.6.122
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.4 and Dart 3.13.3.
+
+- iOS: native assets now require iOS 15, raised from iOS 13.
+- iOS: a build now warns when Device Support Symbols are missing, instead of
+  failing partway through.
+- Windows: Application Control and security policy blocks are handled instead of
+  failing the build.
+
+```sh
+shorebird release ios --flutter-version=3.47.4
+```
diff --git a/src/content/changelog/flutter-version-fvm-and-system.md b/src/content/changelog/flutter-version-fvm-and-system.md
new file mode 100644
index 00000000..bef5977c
--- /dev/null
+++ b/src/content/changelog/flutter-version-fvm-and-system.md
@@ -0,0 +1,25 @@
+---
+title: Release with the Flutter version you already use
+date: 2026-09-21
+version: 1.6.123
+area: CLI
+type: New
+docLink:
+  label: Match the Flutter version you already use
+  href: /getting-started/flutter-version/#match-the-flutter-version-you-already-use
+---
+
+`--flutter-version` now accepts `fvm` and `system`, so you no longer have to
+look up and repeat your Flutter version number.
+
+- `--flutter-version=fvm` uses the version fvm resolves for your project from
+  its `.fvmrc`. It requires `fvm` on your `PATH`.
+- `--flutter-version=system` uses the version reported by the `flutter` on your
+  `PATH`.
+- Shorebird still builds with its own fork of Flutter at that version, not with
+  your fvm or system install. A version Shorebird doesn't support fails the same
+  way as one you name explicitly.
+
+```sh
+shorebird release android --flutter-version=fvm
+```
diff --git a/src/content/changelog/patches-rollback-and-rollforward.md b/src/content/changelog/patches-rollback-and-rollforward.md
new file mode 100644
index 00000000..20fdb5e1
--- /dev/null
+++ b/src/content/changelog/patches-rollback-and-rollforward.md
@@ -0,0 +1,21 @@
+---
+title: Roll patches back and forward from the CLI
+date: 2026-08-28
+version: 1.6.120
+area: CLI
+type: New
+docLink:
+  label: Roll back a patch
+  href: /code-push/rollback/
+---
+
+`shorebird patches rollback` and `shorebird patches rollforward` do the same as
+the Rollback and Roll Forward actions in the Console.
+
+- Both take `--release-version` and `--patch-number`.
+- By default, a patch that is already in the requested state is reported and the
+  command succeeds. Add `--require-change` to exit with an error instead.
+
+```sh
+shorebird patches rollback --release-version 1.0.0+1 --patch-number 1
+```
diff --git a/src/content/changelog/shorebird-apps-commands.md b/src/content/changelog/shorebird-apps-commands.md
new file mode 100644
index 00000000..055ba95f
--- /dev/null
+++ b/src/content/changelog/shorebird-apps-commands.md
@@ -0,0 +1,23 @@
+---
+title: Manage apps from the CLI
+date: 2026-09-14
+version: 1.6.121
+area: CLI
+type: New
+docLink:
+  label: Transfer an app
+  href: /account/orgs/#transfer-an-app
+---
+
+New `shorebird apps` commands list, rename, delete, and transfer apps without
+opening the Console.
+
+- `shorebird apps transfer --org-id <id>` moves an app into another
+  organization. Run `shorebird account orgs` to find the id.
+- `shorebird apps rename --name <name>` changes the display name.
+- `shorebird apps delete` has no prompt. Pass `--confirm-name` with the app's
+  current display name to confirm.
+
+```sh
+shorebird apps transfer --app-id <id> --org-id 42
+```
diff --git a/src/content/changelog/shorebird-channels-commands.md b/src/content/changelog/shorebird-channels-commands.md
new file mode 100644
index 00000000..d5f16141
--- /dev/null
+++ b/src/content/changelog/shorebird-channels-commands.md
@@ -0,0 +1,22 @@
+---
+title: Manage channels from the CLI
+date: 2026-09-14
+version: 1.6.121
+area: CLI
+type: New
+docLink:
+  label: Staging patches
+  href: /code-push/guides/staging-patches/
+---
+
+New `shorebird channels` commands create, list, and delete the channels (tracks)
+an app can publish to.
+
+- Publishing a patch with `--track=<name>` still creates that channel
+  automatically.
+- `shorebird channels delete` is permanent and has no prompt. Pass
+  `--confirm-name` with the channel name to confirm.
+
+```sh
+shorebird channels create --app-id <id> --name qa
+```
diff --git a/src/data/changelog-schema.ts b/src/data/changelog-schema.ts
new file mode 100644
index 00000000..a18e1ec6
--- /dev/null
+++ b/src/data/changelog-schema.ts
@@ -0,0 +1,51 @@
+import { z } from 'astro/zod';
+
+// Kept apart from `changelog.ts` so `src/content.config.ts` can import it
+// without pulling in `astro:content`.
+
+// The parts of Shorebird a change can be filed under. Fixed on purpose: this
+// drives the area filter chips, so it should stay in sync with the products
+// we actually ship rather than growing a new value per entry.
+export const AREAS = ['Code Push', 'CLI', 'Console', 'API', 'Flutter'] as const;
+export type Area = (typeof AREAS)[number];
+
+// Changes in these areas always ship in a CLI release, so they need a version.
+const VERSIONED_AREAS: readonly Area[] = ['CLI', 'Flutter'];
+
+export const TYPES = ['New', 'Fixed', 'Changed', 'Deprecated'] as const;
+export type ChangeType = (typeof TYPES)[number];
+
+/**
+ * Frontmatter of a `src/content/changelog/*.md` entry. The messages are
+ * written for whoever is adding an entry, since they surface as build errors.
+ */
+export const changelogSchema = z
+  .strictObject({
+    title: z.string().trim().min(1),
+    date: z.date({
+      error: 'date must be YYYY-MM-DD with no quotes, like 2026-09-21',
+    }),
+    // Optional: a Console, API, or server-side Code Push change doesn't ship
+    // in a CLI release.
+    version: z.coerce
+      .string()
+      .regex(
+        /^\d+\.\d+\.\d+$/,
+        'version must be the Shorebird CLI release without a "v", like 1.6.123',
+      )
+      .optional(),
+    area: z.enum(AREAS),
+    type: z.enum(TYPES),
+    docLink: z
+      .strictObject({
+        label: z.string().trim().min(1),
+        href: z.string().trim().min(1),
+      })
+      .optional(),
+  })
+  .refine((d) => d.version || !VERSIONED_AREAS.includes(d.area), {
+    path: ['version'],
+    error:
+      'version is required for CLI and Flutter changes, since they ship in ' +
+      'a CLI release',
+  });
diff --git a/src/data/changelog.ts b/src/data/changelog.ts
index 22115881..baf6ebae 100644
--- a/src/data/changelog.ts
+++ b/src/data/changelog.ts
@@ -1,161 +1,154 @@
-// cspell:words rollforward
+import { readFileSync } from 'node:fs';
+import { getCollection, render } from 'astro:content';
+import { AREAS, type Area, type ChangeType } from './changelog-schema';
 
 // Shared by the changelog page (`src/pages/changelog.astro`), its
 // agent-facing Markdown twin (`src/pages/changelog.md.ts`), and its RSS feed
 // (`src/pages/changelog.xml.ts`), so all three list the same entries.
+//
+// Entries are hand-written, one Markdown file each, in
+// `src/content/changelog/`. Copy `_template.md` there to add one.
+
+export { AREAS, type Area };
 
 export const CHANGELOG_TITLE = 'Changelog';
 export const CHANGELOG_DESCRIPTION =
   'What we shipped to Code Push, the CLI, and the API, newest first.';
 
-// The parts of Shorebird a change can be filed under. Fixed on purpose:
-// this drives the area filter chips, so it should stay in sync with the
-// products we actually ship rather than growing a new value per entry.
-export const AREAS = ['Code Push', 'CLI', 'Console', 'API', 'Flutter'] as const;
-export type Area = (typeof AREAS)[number];
-
 export interface ChangelogEntry {
-  /** Anchor id and permalink slug for this entry. */
+  /** Anchor id and permalink slug for this entry: its file name. */
   id: string;
   /** Release date, as `YYYY-MM-DD`. */
   date: string;
-  /** The Shorebird CLI release that shipped the change, without the `v`. */
-  version: string;
+  /**
+   * The Shorebird CLI release that shipped the change, without the `v`.
+   * Absent for changes that don't ship in the CLI, like Console updates.
+   */
+  version?: string;
   area: Area;
-  type: 'New' | 'Fixed' | 'Changed' | 'Deprecated';
+  type: ChangeType;
   title: string;
+  /** May mark inline code with backticks, as in Markdown. */
   summary: string;
+  /** May mark inline code with backticks, as in Markdown. */
   bullets: string[];
+  /** One command per line, without a leading `$`. */
   code?: string;
   docLink?: { label: string; href: string };
 }
 
-// Hand-written, in any order; readers see them newest first. Add an entry
-// here when something ships that a developer integrating Code Push would want
-// to know about. Wrap commands and flags in backticks in `summary` and
-// `bullets` to render them as inline code, as in Markdown.
-export const ENTRIES: ChangelogEntry[] = [
-  {
-    id: 'flutter-version-fvm-and-system',
-    date: '2026-09-21',
-    version: '1.6.123',
-    area: 'CLI',
-    type: 'New',
-    title: 'Release with the Flutter version you already use',
-    summary:
-      '`--flutter-version` now accepts `fvm` and `system`, so you no longer have to look up and repeat your Flutter version number.',
-    bullets: [
-      '`--flutter-version=fvm` uses the version fvm resolves for your project from its `.fvmrc`. It requires `fvm` on your `PATH`.',
-      '`--flutter-version=system` uses the version reported by the `flutter` on your `PATH`.',
-      "Shorebird still builds with its own fork of Flutter at that version, not with your fvm or system install. A version Shorebird doesn't support fails the same way as one you name explicitly.",
-    ],
-    code: 'shorebird release android --flutter-version=fvm',
-    docLink: {
-      label: 'Match the Flutter version you already use',
-      href: '/getting-started/flutter-version/#match-the-flutter-version-you-already-use',
-    },
-  },
-  {
-    id: 'failed-patch-checks-for-replacement',
-    date: '2026-09-16',
-    version: '1.6.122',
-    area: 'Code Push',
-    type: 'Fixed',
-    title: 'A patch that fails to load is replaced on the same launch',
-    summary:
-      'When a patch fails to load, the device now checks for a replacement patch right away instead of waiting for the next launch.',
-    bullets: [
-      'Previously, reporting the failure suppressed the update check, so the device ran the base release and stayed on the bad patch until it launched again.',
-      'Patch checks now report the patch the device is actually running, so each device is attributed to the right patch.',
-      'These fixes are in the updater built into your app, so they apply to releases built with Shorebird 1.6.122 or later.',
-    ],
-    docLink: {
-      label: 'Patch integrity and automatic rollback',
-      href: '/code-push/rollback/#patch-integrity-and-automatic-rollback',
-    },
-  },
-  {
-    id: 'flutter-3-47-4',
-    date: '2026-09-16',
-    version: '1.6.122',
-    area: 'Flutter',
-    type: 'New',
-    title: 'Flutter 3.47.4 support',
-    summary: 'Shorebird now supports Flutter 3.47.4 and Dart 3.13.3.',
-    bullets: [
-      'iOS: native assets now require iOS 15, raised from iOS 13.',
-      'iOS: a build now warns when Device Support Symbols are missing, instead of failing partway through.',
-      'Windows: Application Control and security policy blocks are handled instead of failing the build.',
-    ],
-    code: 'shorebird release ios --flutter-version=3.47.4',
-    docLink: {
-      label: 'Flutter versions',
-      href: '/getting-started/flutter-version/',
-    },
-  },
-  {
-    id: 'shorebird-apps-commands',
-    date: '2026-09-14',
-    version: '1.6.121',
-    area: 'CLI',
-    type: 'New',
-    title: 'Manage apps from the CLI',
-    summary:
-      'New `shorebird apps` commands list, rename, delete, and transfer apps without opening the Console.',
-    bullets: [
-      '`shorebird apps transfer --org-id <id>` moves an app into another organization. Run `shorebird account orgs` to find the id.',
-      '`shorebird apps rename --name <name>` changes the display name.',
-      "`shorebird apps delete` has no prompt. Pass `--confirm-name` with the app's current display name to confirm.",
-    ],
-    code: 'shorebird apps transfer --app-id <id> --org-id 42',
-    docLink: {
-      label: 'Transfer an app',
-      href: '/account/orgs/#transfer-an-app',
-    },
-  },
-  {
-    id: 'shorebird-channels-commands',
-    date: '2026-09-14',
-    version: '1.6.121',
-    area: 'CLI',
-    type: 'New',
-    title: 'Manage channels from the CLI',
-    summary:
-      'New `shorebird channels` commands create, list, and delete the channels (tracks) an app can publish to.',
-    bullets: [
-      'Publishing a patch with `--track=<name>` still creates that channel automatically.',
-      '`shorebird channels delete` is permanent and has no prompt. Pass `--confirm-name` with the channel name to confirm.',
-    ],
-    code: 'shorebird channels create --app-id <id> --name qa',
-    docLink: {
-      label: 'Staging patches',
-      href: '/code-push/guides/staging-patches/',
-    },
-  },
-  {
-    id: 'patches-rollback-and-rollforward',
-    date: '2026-08-28',
-    version: '1.6.120',
-    area: 'CLI',
-    type: 'New',
-    title: 'Roll patches back and forward from the CLI',
-    summary:
-      '`shorebird patches rollback` and `shorebird patches rollforward` do the same as the Rollback and Roll Forward actions in the Console.',
-    bullets: [
-      'Both take `--release-version` and `--patch-number`.',
-      'By default, a patch that is already in the requested state is reported and the command succeeds. Add `--require-change` to exit with an error instead.',
-    ],
-    code: 'shorebird patches rollback --release-version 1.0.0+1 --patch-number 1',
-    docLink: {
-      label: 'Roll back a patch',
-      href: '/code-push/rollback/',
-    },
-  },
-];
+const BODY_HELP =
+  'The body must be a summary paragraph, then a "- " bullet list, then ' +
+  'optionally one ```sh code block. See src/content/changelog/_template.md.';
 
-/** Link to the GitHub release notes for a CLI version. */
-export function releaseNotesUrl(version: string): string {
-  return `https://github.com/shorebirdtech/shorebird/releases/tag/v${version}`;
+/**
+ * Splits an entry's Markdown body into its summary, bullets, and command.
+ * Only that shape is accepted, so a stray heading or second paragraph fails
+ * the build instead of silently disappearing from the page.
+ */
+function parseBody(
+  file: string,
+  body: string,
+): Pick<ChangelogEntry, 'summary' | 'bullets' | 'code'> {
+  // Report positions as `file:line` in the whole file, frontmatter included,
+  // so they can be clicked in a terminal or editor.
+  let offset = 0;
+  try {
+    const raw = readFileSync(file, 'utf8');
+    const at = raw.indexOf(body);
+    if (at >= 0) offset = raw.slice(0, at).split('\n').length - 1;
+  } catch {
+    // Without the file, line numbers stay relative to the body.
+  }
+  const fail = (line: number | undefined, problem: string): never => {
+    const where = line === undefined ? file : `${file}:${line + offset}`;
+    throw new Error(`${where}: ${problem} ${BODY_HELP}`);
+  };
+
+  // Blank out comments line by line, so line numbers in errors still match.
+  const lines = body
+    .replace(/<!--[\s\S]*?-->/g, (c) => c.replace(/[^\n]/g, ''))
+    .split(/\r?\n/);
+
+  const summary: string[] = [];
+  const bullets: string[] = [];
+  let code: string[] | undefined;
+  let block: 'none' | 'summary' | 'bullet' = 'none';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const n = i + 1;
+    if (line.trim() === '') {
+      block = 'none';
+    } else if (/^(#|>|\d+\.\s)/.test(line)) {
+      fail(n, 'Headings, quotes, and numbered lists are not supported.');
+    } else if (line.startsWith('```')) {
+      if (code) fail(n, 'Only one code block is allowed.');
+      if (!/^```(sh|bash|shell)?\s*$/.test(line)) {
+        fail(n, 'The code block must be ```sh.');
+      }
+      code = [];
+      for (i++; i < lines.length && !lines[i].startsWith('```'); i++) {
+        if (lines[i].trim()) code.push(lines[i].trim().replace(/^\$\s*/, ''));
+      }
+      if (i === lines.length) fail(n, 'This code block is never closed.');
+      block = 'none';
+    } else if (code) {
+      fail(n, 'Nothing can follow the code block.');
+    } else if (/^[-*]\s/.test(line)) {
+      if (summary.length === 0) fail(n, 'The summary paragraph comes first.');
+      bullets.push(line.replace(/^[-*]\s+/, '').trim());
+      block = 'bullet';
+    } else if (block === 'bullet' && /^\s/.test(line)) {
+      bullets[bullets.length - 1] += ` ${line.trim()}`;
+    } else if (block === 'summary') {
+      summary.push(line.trim());
+    } else if (summary.length === 0 && block === 'none') {
+      summary.push(line.trim());
+      block = 'summary';
+    } else {
+      fail(n, `Unexpected text: "${line.trim().slice(0, 40)}".`);
+    }
+  }
+
+  if (summary.length === 0)
+    fail(undefined, 'The summary paragraph is missing.');
+  if (bullets.length === 0) fail(undefined, 'At least one bullet is required.');
+  if (code?.length === 0) fail(undefined, 'The code block is empty.');
+  return {
+    summary: summary.join(' '),
+    bullets,
+    code: code?.join('\n'),
+  };
+}
+
+/**
+ * Fails the build if an internal `docLink` doesn't point at a docs page, or
+ * its `#fragment` doesn't match a heading on that page. Starlight's link
+ * validator only covers links inside docs pages, not these.
+ */
+async function checkDocLink(file: string, href: string): Promise<void> {
+  if (/^https?:\/\//.test(href)) return;
+  const url = new URL(href, 'https://docs.shorebird.dev');
+  const path = url.pathname.replace(/^\/|\/$/g, '');
+  const docs = await getCollection('docs');
+  const doc = docs.find((d) => d.id === path || d.id === `${path}/index`);
+  if (!doc) {
+    throw new Error(
+      `${file}: docLink.href "${href}" doesn't match any docs page. Use the ` +
+        'path from the address bar, like /code-push/rollback/.',
+    );
+  }
+  const fragment = decodeURIComponent(url.hash.slice(1));
+  if (!fragment) return;
+  const { headings } = await render(doc);
+  if (!headings.some((h) => h.slug === fragment)) {
+    throw new Error(
+      `${file}: docLink.href "${href}" links to #${fragment}, but that page ` +
+        `has no such heading. Its headings are: ` +
+        headings.map((h) => `#${h.slug}`).join(', '),
+    );
+  }
 }
 
 /** A copy of `entries`, newest first. Same-day entries keep their order. */
@@ -163,6 +156,34 @@ export function newestFirst(entries: ChangelogEntry[]): ChangelogEntry[] {
   return [...entries].sort((a, b) => b.date.localeCompare(a.date));
 }
 
+let cached: Promise<ChangelogEntry[]> | undefined;
+
+/** Every published entry, newest first, validated. */
+export function getEntries(): Promise<ChangelogEntry[]> {
+  cached ??= (async () => {
+    const files = await getCollection('changelog');
+    const entries = await Promise.all(
+      files.map(async ({ id, data, body, filePath }) => {
+        const file = filePath ?? `src/content/changelog/${id}.md`;
+        if (data.docLink) await checkDocLink(file, data.docLink.href);
+        return {
+          id,
+          ...data,
+          date: data.date.toISOString().slice(0, 10),
+          ...parseBody(file, body ?? ''),
+        };
+      }),
+    );
+    return newestFirst(entries);
+  })();
+  return cached;
+}
+
+/** Link to the GitHub release notes for a CLI version. */
+export function releaseNotesUrl(version: string): string {
+  return `https://github.com/shorebirdtech/shorebird/releases/tag/v${version}`;
+}
+
 function formatMonth(iso: string): string {
   return new Date(iso).toLocaleDateString('en-US', {
     month: 'long',
@@ -172,14 +193,14 @@ function formatMonth(iso: string): string {
 }
 
 /**
- * `ENTRIES` grouped under "September 2026"-style headings, newest first.
+ * Entries grouped under "September 2026"-style headings, newest first.
  * `id` ("september-2026") anchors the heading and its table-of-contents link.
  */
 export function groupByMonth(
   entries: ChangelogEntry[],
 ): { id: string; label: string; items: ChangelogEntry[] }[] {
   const groups: { id: string; label: string; items: ChangelogEntry[] }[] = [];
-  // Sort rather than trust the array order: one entry out of place would
+  // Sort rather than trust the input order: one entry out of place would
   // otherwise start a second heading for its month.
   for (const e of newestFirst(entries)) {
     const label = formatMonth(e.date);
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index f07d51f3..198705d9 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -5,7 +5,7 @@ import {
   AREAS,
   CHANGELOG_DESCRIPTION,
   CHANGELOG_TITLE,
-  ENTRIES,
+  getEntries,
   groupByMonth,
   releaseNotesUrl,
   type ChangelogEntry,
@@ -18,6 +18,7 @@ const TYPE_LABEL_COLOR: Record<ChangelogEntry['type'], string> = {
   Deprecated: 'deprecated',
 };
 
+const ENTRIES = await getEntries();
 const groups = groupByMonth(ENTRIES);
 
 // Only offer a chip for an area that has entries, so no filter starts empty.
@@ -118,7 +119,7 @@ function formatDay(iso: string): string {
               e.summary,
               e.area,
               e.type,
-              e.version,
+              e.version ?? '',
               ...e.bullets,
               e.code ?? '',
             ]
@@ -135,7 +136,9 @@ function formatDay(iso: string): string {
               >
                 <div class="cl-when">
                   <time datetime={e.date}>{formatDay(e.date)}</time>
-                  <span class="cl-version">CLI {e.version}</span>
+                  {e.version && (
+                    <span class="cl-version">CLI {e.version}</span>
+                  )}
                 </div>
                 <div class="cl-body">
                   <div class="cl-head">
@@ -200,7 +203,7 @@ function formatDay(iso: string): string {
                       ))}
                     </ul>
                     {e.code && (
-                      <pre class="cl-code"><code>$ {e.code}</code></pre>
+                      <pre class="cl-code"><code>{e.code.split('\n').map((c) => `$ ${c}`).join('\n')}</code></pre>
                     )}
                     <div class="cl-footer">
                       {e.docLink && (
@@ -208,12 +211,14 @@ function formatDay(iso: string): string {
                           {e.docLink.label} →
                         </a>
                       )}
-                      <a
-                        href={releaseNotesUrl(e.version)}
-                        class="cl-notes-link"
-                      >
-                        Release notes ↗
-                      </a>
+                      {e.version && (
+                        <a
+                          href={releaseNotesUrl(e.version)}
+                          class="cl-notes-link"
+                        >
+                          Release notes ↗
+                        </a>
+                      )}
                       <a
                         href={`#${e.id}`}
                         class="cl-copy"
diff --git a/src/pages/changelog.md.ts b/src/pages/changelog.md.ts
index b977372e..352daf3b 100644
--- a/src/pages/changelog.md.ts
+++ b/src/pages/changelog.md.ts
@@ -1,7 +1,7 @@
 import {
   CHANGELOG_DESCRIPTION,
   CHANGELOG_TITLE,
-  ENTRIES,
+  getEntries,
   groupByMonth,
   releaseNotesUrl,
   type ChangelogEntry,
@@ -17,7 +17,14 @@ export const prerender = true;
 function entryToMarkdown(e: ChangelogEntry): string {
   return [
     `### ${e.title}`,
-    `**${e.type}** in ${e.area}, ${e.date}, Shorebird CLI ${e.version} ([release notes](${releaseNotesUrl(e.version)})). Permalink: [/changelog/#${e.id}](/changelog/#${e.id})`,
+    [
+      `**${e.type}** in ${e.area}, ${e.date}`,
+      e.version &&
+        `, Shorebird CLI ${e.version} ([release notes](${releaseNotesUrl(e.version)}))`,
+      `. Permalink: [/changelog/#${e.id}](/changelog/#${e.id})`,
+    ]
+      .filter(Boolean)
+      .join(''),
     e.summary,
     e.bullets.map((b) => `- ${b}`).join('\n'),
     e.code && ['```sh', e.code, '```'].join('\n'),
@@ -27,7 +34,7 @@ function entryToMarkdown(e: ChangelogEntry): string {
     .join('\n\n');
 }
 
-export function GET() {
+export async function GET() {
   const frontmatter = [
     '---',
     `title: ${JSON.stringify(CHANGELOG_TITLE)}`,
@@ -38,7 +45,7 @@ export function GET() {
   const body = [
     frontmatter,
     `${CHANGELOG_DESCRIPTION} RSS feed: [/changelog.xml](/changelog.xml)`,
-    ...groupByMonth(ENTRIES).flatMap((group) => [
+    ...groupByMonth(await getEntries()).flatMap((group) => [
       `## ${group.label}`,
       ...group.items.map(entryToMarkdown),
     ]),
diff --git a/src/pages/changelog.xml.ts b/src/pages/changelog.xml.ts
index fcfb6b92..d8c94ea9 100644
--- a/src/pages/changelog.xml.ts
+++ b/src/pages/changelog.xml.ts
@@ -1,4 +1,4 @@
-import { CHANGELOG_DESCRIPTION, ENTRIES, newestFirst } from '~/data/changelog';
+import { CHANGELOG_DESCRIPTION, getEntries } from '~/data/changelog';
 
 // RSS 2.0 feed of the changelog, so readers can subscribe instead of checking
 // the page. Written by hand rather than with `@astrojs/rss`, since a flat list
@@ -15,8 +15,8 @@ function escapeXml(text: string): string {
     .replaceAll('"', '&quot;');
 }
 
-export function GET() {
-  const entries = newestFirst(ENTRIES);
+export async function GET() {
+  const entries = await getEntries();
   const items = entries.map((e) => {
     const link = `${SITE}/changelog/#${e.id}`;
     // Feed readers show the description as plain text, so drop the

From b44cb67d9e3ba939608d9b6b981abe7a72da0f75 Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:35:21 +0530
Subject: [PATCH 11/13] Make the changelog discoverable to agents

- Append the changelog to llms-full.txt after the build, since
  starlight-llms-txt only covers docs collection pages.
- List /changelog.md in ai-catalog.json, agent.json, and
  agent-instructions.txt, and tell agents to compare an entry's CLI
  release with `shorebird --version` before suggesting a new flag.
- Say the same at the top of /changelog.md, and stop repeating the
  description there, matching the other Markdown twins.
---
 astro.config.mjs                          | 28 +++++++++++++++++++++++
 public/.well-known/agent-instructions.txt |  1 +
 public/.well-known/agent.json             |  1 +
 public/.well-known/ai-catalog.json        | 11 +++++++++
 src/pages/changelog.md.ts                 |  2 +-
 5 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/astro.config.mjs b/astro.config.mjs
index 67946674..6509d491 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -71,6 +71,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,
@@ -279,6 +306,7 @@ Developer & Agent Interfaces:
       render: renderer,
     }),
     stripUnlistedFromLlmsFull,
+    appendChangelogToLlmsFull,
   ],
   redirects: {
     // Redirects to preserve legacy URLs & resolve agent probes.
diff --git a/public/.well-known/agent-instructions.txt b/public/.well-known/agent-instructions.txt
index c80318af..b7ca212a 100644
--- a/public/.well-known/agent-instructions.txt
+++ b/public/.well-known/agent-instructions.txt
@@ -22,3 +22,4 @@ Developers can always use Shorebird to build, manage releases, and patch Flutter
    - `shorebird preview`: Test patches locally before distributing.
 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, with the Shorebird CLI release for each change. 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.
diff --git a/public/.well-known/agent.json b/public/.well-known/agent.json
index afabfc4b..af29694e 100644
--- a/public/.well-known/agent.json
+++ b/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"
diff --git a/public/.well-known/ai-catalog.json b/public/.well-known/ai-catalog.json
index 4626ee44..b4a03f94 100644
--- a/public/.well-known/ai-catalog.json
+++ b/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",
diff --git a/src/pages/changelog.md.ts b/src/pages/changelog.md.ts
index 352daf3b..2b4c2d45 100644
--- a/src/pages/changelog.md.ts
+++ b/src/pages/changelog.md.ts
@@ -44,7 +44,7 @@ export async function GET() {
 
   const body = [
     frontmatter,
-    `${CHANGELOG_DESCRIPTION} RSS feed: [/changelog.xml](/changelog.xml)`,
+    `Each entry names the Shorebird CLI release that shipped it, if any; compare it with \`shorebird --version\`, and run \`shorebird upgrade\` to get newer changes. RSS feed: [/changelog.xml](/changelog.xml)`,
     ...groupByMonth(await getEntries()).flatMap((group) => [
       `## ${group.label}`,
       ...group.items.map(entryToMarkdown),

From 55bec5eb09c9e73a0a96724a92bc7bfdc1d3bdaa Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:41:11 +0530
Subject: [PATCH 12/13] Catch changelog text that renders differently on the
 page and in .md

- Fail the build on an unclosed backtick, a Markdown link, bold text, or
  a bare <placeholder> in a summary or bullet, and on any Markdown in a
  title. The page renders only backticks, so these showed up as raw
  syntax on the page but rendered (or vanished) in /changelog.md.
- Require docLink.href to start with "/" or "https://"; a relative href
  passed the check but resolved against /changelog/ on the page.
- Order same-day entries by file name instead of collection order.
- When a permalink or month link targets something a filter is hiding,
  clear the filters so the link goes somewhere.
- Build RSS links from `site` in astro.config.mjs.
---
 src/content/changelog/_template.md | 10 +++++--
 src/data/changelog-schema.ts       | 10 ++++++-
 src/data/changelog.ts              | 47 ++++++++++++++++++++++++++++--
 src/pages/changelog.astro          | 32 +++++++++++++-------
 src/pages/changelog.xml.ts         | 14 +++++----
 5 files changed, 89 insertions(+), 24 deletions(-)

diff --git a/src/content/changelog/_template.md b/src/content/changelog/_template.md
index b47b447a..03a38db6 100644
--- a/src/content/changelog/_template.md
+++ b/src/content/changelog/_template.md
@@ -9,7 +9,8 @@
 
 # A short headline, in sentence case.
 title: Roll patches back from the CLI
-# The day the release shipped, as YYYY-MM-DD with no quotes.
+# The day the release shipped, as YYYY-MM-DD with no quotes. 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
@@ -20,8 +21,8 @@ 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, and a #fragment must match a heading on it. Delete both lines if
-# there's no page for it.
+# site, starting with "/", and a #fragment must match a heading on it. Delete
+# both lines if there's no page for it.
 docLink:
   label: Roll back a patch
   href: /code-push/rollback/
@@ -42,4 +43,7 @@ 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.
 -->
diff --git a/src/data/changelog-schema.ts b/src/data/changelog-schema.ts
index a18e1ec6..69f3f1af 100644
--- a/src/data/changelog-schema.ts
+++ b/src/data/changelog-schema.ts
@@ -39,7 +39,15 @@ export const changelogSchema = z
     docLink: z
       .strictObject({
         label: z.string().trim().min(1),
-        href: z.string().trim().min(1),
+        // A relative href would resolve against /changelog/ on the page.
+        href: z
+          .string()
+          .trim()
+          .regex(
+            /^(\/|https:\/\/)/,
+            'docLink.href must start with "/" for a docs page, like ' +
+              '/code-push/rollback/, or with "https://"',
+          ),
       })
       .optional(),
   })
diff --git a/src/data/changelog.ts b/src/data/changelog.ts
index baf6ebae..8a8cbce9 100644
--- a/src/data/changelog.ts
+++ b/src/data/changelog.ts
@@ -41,6 +41,27 @@ const BODY_HELP =
   'The body must be a summary paragraph, then a "- " bullet list, then ' +
   'optionally one ```sh code block. See src/content/changelog/_template.md.';
 
+/**
+ * The page renders only backticks (as inline code), while `/changelog.md`
+ * passes text through as Markdown. Returns what in `text` would render
+ * differently between the two, or `undefined` if nothing would.
+ */
+function inlineProblem(text: string, allowCode = true): string | undefined {
+  const parts = text.split('`');
+  if (!allowCode && parts.length > 1)
+    return 'Backticks are not supported here.';
+  if (parts.length % 2 === 0) return 'A backtick is never closed.';
+  const prose = parts.filter((_, i) => i % 2 === 0).join(' ');
+  if (/\[[^\]]*\]\([^)]*\)/.test(prose)) {
+    return 'Links are not supported in entry text. Put the link in docLink.';
+  }
+  if (/\*\*|__/.test(prose)) return 'Bold text is not supported.';
+  if (/<[^>]*>/.test(prose)) {
+    return 'Wrap placeholders like <id> in backticks, or they vanish from /changelog.md.';
+  }
+  return undefined;
+}
+
 /**
  * Splits an entry's Markdown body into its summary, bullets, and command.
  * Only that shape is accepted, so a stray heading or second paragraph fails
@@ -71,7 +92,9 @@ function parseBody(
     .split(/\r?\n/);
 
   const summary: string[] = [];
+  let summaryLine = 0;
   const bullets: string[] = [];
+  const bulletLines: number[] = [];
   let code: string[] | undefined;
   let block: 'none' | 'summary' | 'bullet' = 'none';
 
@@ -98,6 +121,7 @@ function parseBody(
     } else if (/^[-*]\s/.test(line)) {
       if (summary.length === 0) fail(n, 'The summary paragraph comes first.');
       bullets.push(line.replace(/^[-*]\s+/, '').trim());
+      bulletLines.push(n);
       block = 'bullet';
     } else if (block === 'bullet' && /^\s/.test(line)) {
       bullets[bullets.length - 1] += ` ${line.trim()}`;
@@ -105,6 +129,7 @@ function parseBody(
       summary.push(line.trim());
     } else if (summary.length === 0 && block === 'none') {
       summary.push(line.trim());
+      summaryLine = n;
       block = 'summary';
     } else {
       fail(n, `Unexpected text: "${line.trim().slice(0, 40)}".`);
@@ -115,8 +140,17 @@ function parseBody(
     fail(undefined, 'The summary paragraph is missing.');
   if (bullets.length === 0) fail(undefined, 'At least one bullet is required.');
   if (code?.length === 0) fail(undefined, 'The code block is empty.');
+
+  const summaryText = summary.join(' ');
+  const summaryProblem = inlineProblem(summaryText);
+  if (summaryProblem) fail(summaryLine, summaryProblem);
+  bullets.forEach((b, i) => {
+    const problem = inlineProblem(b);
+    if (problem) fail(bulletLines[i], problem);
+  });
+
   return {
-    summary: summary.join(' '),
+    summary: summaryText,
     bullets,
     code: code?.join('\n'),
   };
@@ -151,9 +185,14 @@ async function checkDocLink(file: string, href: string): Promise<void> {
   }
 }
 
-/** A copy of `entries`, newest first. Same-day entries keep their order. */
+/**
+ * A copy of `entries`, newest first. Same-day entries are ordered by file
+ * name, since the order `getCollection` returns them in isn't guaranteed.
+ */
 export function newestFirst(entries: ChangelogEntry[]): ChangelogEntry[] {
-  return [...entries].sort((a, b) => b.date.localeCompare(a.date));
+  return [...entries].sort(
+    (a, b) => b.date.localeCompare(a.date) || a.id.localeCompare(b.id),
+  );
 }
 
 let cached: Promise<ChangelogEntry[]> | undefined;
@@ -165,6 +204,8 @@ export function getEntries(): Promise<ChangelogEntry[]> {
     const entries = await Promise.all(
       files.map(async ({ id, data, body, filePath }) => {
         const file = filePath ?? `src/content/changelog/${id}.md`;
+        const titleProblem = inlineProblem(data.title, false);
+        if (titleProblem) throw new Error(`${file}: title: ${titleProblem}`);
         if (data.docLink) await checkDocLink(file, data.docLink.href);
         return {
           id,
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index 198705d9..01d688d4 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -319,15 +319,17 @@ function formatDay(iso: string): string {
 
     search.addEventListener('input', applyFilters);
 
+    function selectArea(chip: HTMLButtonElement) {
+      area = chip.dataset.area ?? 'All';
+      for (const c of chips) {
+        c.classList.toggle('is-active', c === chip);
+        c.setAttribute('aria-pressed', String(c === chip));
+      }
+      applyFilters();
+    }
+
     for (const chip of chips) {
-      chip.addEventListener('click', () => {
-        area = chip.dataset.area ?? 'All';
-        for (const c of chips) {
-          c.classList.toggle('is-active', c === chip);
-          c.setAttribute('aria-pressed', String(c === chip));
-        }
-        applyFilters();
-      });
+      chip.addEventListener('click', () => selectArea(chip));
     }
 
     function setOpen(entry: HTMLElement, open: boolean) {
@@ -390,10 +392,18 @@ function formatDay(iso: string): string {
       const targetId = decodeURIComponent(location.hash.replace(/^#/, ''));
       if (!targetId) return;
       const target = document.getElementById(targetId);
-      if (target?.classList.contains('cl-entry')) {
-        setOpen(target, true);
-        target.scrollIntoView({ block: 'start' });
+      const isEntry = target?.classList.contains('cl-entry');
+      if (!target || !(isEntry || target.classList.contains('cl-month'))) {
+        return;
+      }
+      // A search or area filter may be hiding the entry or its month; clear
+      // them, or the link would go nowhere.
+      if (target.closest('.cl-entry[hidden], .cl-group[hidden]')) {
+        search!.value = '';
+        selectArea(chips[0]);
       }
+      if (isEntry) setOpen(target, true);
+      target.scrollIntoView({ block: 'start' });
     }
 
     openFromHash();
diff --git a/src/pages/changelog.xml.ts b/src/pages/changelog.xml.ts
index d8c94ea9..29905ad9 100644
--- a/src/pages/changelog.xml.ts
+++ b/src/pages/changelog.xml.ts
@@ -1,3 +1,4 @@
+import type { APIContext } from 'astro';
 import { CHANGELOG_DESCRIPTION, getEntries } from '~/data/changelog';
 
 // RSS 2.0 feed of the changelog, so readers can subscribe instead of checking
@@ -5,8 +6,6 @@ import { CHANGELOG_DESCRIPTION, getEntries } from '~/data/changelog';
 // of entries needs only a few tags.
 export const prerender = true;
 
-const SITE = 'https://docs.shorebird.dev';
-
 function escapeXml(text: string): string {
   return text
     .replaceAll('&', '&amp;')
@@ -15,10 +14,13 @@ function escapeXml(text: string): string {
     .replaceAll('"', '&quot;');
 }
 
-export async function GET() {
+export async function GET({ site }: APIContext) {
+  // Feed links must be absolute; `site` comes from `astro.config.mjs`.
+  if (!site) throw new Error('changelog.xml needs `site` in astro.config.mjs.');
+  const absolute = (path: string) => new URL(path, site).href;
   const entries = await getEntries();
   const items = entries.map((e) => {
-    const link = `${SITE}/changelog/#${e.id}`;
+    const link = absolute(`/changelog/#${e.id}`);
     // Feed readers show the description as plain text, so drop the
     // backticks that mark inline code on the page.
     const description = e.summary.replaceAll('`', '');
@@ -39,8 +41,8 @@ export async function GET() {
     '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
     '  <channel>',
     '    <title>Shorebird changelog</title>',
-    `    <link>${SITE}/changelog/</link>`,
-    `    <atom:link href="${SITE}/changelog.xml" rel="self" type="application/rss+xml" />`,
+    `    <link>${absolute('/changelog/')}</link>`,
+    `    <atom:link href="${absolute('/changelog.xml')}" rel="self" type="application/rss+xml" />`,
     `    <description>${escapeXml(CHANGELOG_DESCRIPTION)}</description>`,
     '    <language>en-us</language>',
     entries[0] &&

From f9531881ad82facf5522e3cc86849b47e6a13e9c Mon Sep 17 00:00:00 2001
From: Abhishek Doshi <adoshi26.ad@gmail.com>
Date: Thu, 24 Sep 2026 18:57:41 +0530
Subject: [PATCH 13/13] Complete 1.6.120-1.6.123 entries and tighten changelog
 validation

Content, checked against RELEASE_NOTES.md in shorebirdtech/shorebird
(the GitHub release bodies are auto-generated and incomplete):
- Add Flutter 3.47.2, 3.47.3, and 3.47.5 support, and the iOS
  --split-debug-info dSYM fix from 1.6.123.
- The 1.6.122 updater fix ships in Shorebird's Flutter 3.47.4 engine,
  not the CLI, and a failed patch falls back to the last installed
  patch, not the base release; say so.
- Describe the changelog without listing areas that have no entries.

Code:
- Keep command lines as written: strip only a "$ " prompt, never a
  $VARIABLE, and keep indentation and blank lines.
- Draw the "$ " prompt with CSS, so copying a command doesn't copy it,
  and skip it on lines continuing a backslash.
- Reject docLinks to unlisted or draft pages, validate absolute
  docs.shorebird.dev links, and accept standalone pages like /roadmap/.
- Also reject italics, HTML entities, backslash escapes, and bare URLs
  in entry text, which rendered differently on the page and in .md.
- Reject entry file names that collide with a month heading's anchor.
- Dim empty filter chips with a dashed border instead of opacity, which
  dropped their text below 4.5:1 contrast.
- Don't let a malformed URL hash stop the page script.
---
 astro.config.mjs                              |  2 +-
 .../failed-patch-checks-for-replacement.md    | 13 ++---
 src/content/changelog/flutter-3-47-2.md       | 21 ++++++++
 src/content/changelog/flutter-3-47-3.md       | 21 ++++++++
 src/content/changelog/flutter-3-47-5.md       | 20 ++++++++
 .../changelog/ios-split-debug-info-dsym.md    | 16 ++++++
 src/data/changelog.ts                         | 50 +++++++++++++++++--
 src/pages/changelog.astro                     | 40 +++++++++++++--
 8 files changed, 167 insertions(+), 16 deletions(-)
 create mode 100644 src/content/changelog/flutter-3-47-2.md
 create mode 100644 src/content/changelog/flutter-3-47-3.md
 create mode 100644 src/content/changelog/flutter-3-47-5.md
 create mode 100644 src/content/changelog/ios-split-debug-info-dsym.md

diff --git a/astro.config.mjs b/astro.config.mjs
index 6509d491..5a8545eb 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -239,7 +239,7 @@ Developer & Agent Interfaces:
               label: 'Changelog',
               url: 'https://docs.shorebird.dev/changelog.md',
               description:
-                'What shipped to Code Push, the CLI, and the API, newest first',
+                'New features, fixes, and supported Flutter versions in Shorebird, newest first',
             },
             {
               label: 'OpenAPI specification',
diff --git a/src/content/changelog/failed-patch-checks-for-replacement.md b/src/content/changelog/failed-patch-checks-for-replacement.md
index ff362df3..724dc7be 100644
--- a/src/content/changelog/failed-patch-checks-for-replacement.md
+++ b/src/content/changelog/failed-patch-checks-for-replacement.md
@@ -9,12 +9,13 @@ docLink:
   href: /code-push/rollback/#patch-integrity-and-automatic-rollback
 ---
 
-When a patch fails to load, the device now checks for a replacement patch right
-away instead of waiting for the next launch.
+When a patch fails to load, the device now checks for a replacement patch on
+that same launch, instead of waiting for the next one.
 
-- Previously, reporting the failure suppressed the update check, so the device
-  ran the base release and stayed on the bad patch until it launched again.
+- Previously, reporting the failure suppressed the update check, so a device
+  couldn't pick up a fixed patch until it launched again.
 - Patch checks now report the patch the device is actually running, so each
   device is attributed to the right patch.
-- These fixes are in the updater built into your app, so they apply to releases
-  built with Shorebird 1.6.122 or later.
+- These fixes are in the updater built into Shorebird's Flutter engine, so they
+  apply to releases built with Shorebird's Flutter 3.47.4 or later, the default
+  in CLI 1.6.122.
diff --git a/src/content/changelog/flutter-3-47-2.md b/src/content/changelog/flutter-3-47-2.md
new file mode 100644
index 00000000..7fb31f39
--- /dev/null
+++ b/src/content/changelog/flutter-3-47-2.md
@@ -0,0 +1,21 @@
+---
+title: Flutter 3.47.2 support
+date: 2026-08-28
+version: 1.6.120
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.2 and Dart 3.13.2.
+
+- iOS and macOS: Swift package dependencies are always updated.
+- Windows: fixes hot reload failing on file time truncation.
+- Desktop: `--build-name` and `--build-number` are now forwarded to
+  `version.json`.
+
+```sh
+shorebird release android --flutter-version=3.47.2
+```
diff --git a/src/content/changelog/flutter-3-47-3.md b/src/content/changelog/flutter-3-47-3.md
new file mode 100644
index 00000000..19449f46
--- /dev/null
+++ b/src/content/changelog/flutter-3-47-3.md
@@ -0,0 +1,21 @@
+---
+title: Flutter 3.47.3 support
+date: 2026-09-14
+version: 1.6.121
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.3 and Dart 3.13.3.
+
+- Android: fixes license detection for cmdline-tools 23.0 and newer.
+- iOS and macOS: a missing Xcode is now handled instead of failing hard.
+- Windows: fixes Dart cross-compilation.
+- B-series PowerVR GPUs no longer use Vulkan.
+
+```sh
+shorebird release android --flutter-version=3.47.3
+```
diff --git a/src/content/changelog/flutter-3-47-5.md b/src/content/changelog/flutter-3-47-5.md
new file mode 100644
index 00000000..f7d99a5a
--- /dev/null
+++ b/src/content/changelog/flutter-3-47-5.md
@@ -0,0 +1,20 @@
+---
+title: Flutter 3.47.5 support
+date: 2026-09-21
+version: 1.6.123
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.5 and Dart 3.13.4.
+
+- iOS: fixes an occasional crash when debugging on physical iOS 27 devices.
+- Widget Previewer: fixes a crash when re-expanding a preview group.
+- A Dart Development Service startup failure is now handled instead of crashing.
+
+```sh
+shorebird release ios --flutter-version=3.47.5
+```
diff --git a/src/content/changelog/ios-split-debug-info-dsym.md b/src/content/changelog/ios-split-debug-info-dsym.md
new file mode 100644
index 00000000..34a275d3
--- /dev/null
+++ b/src/content/changelog/ios-split-debug-info-dsym.md
@@ -0,0 +1,16 @@
+---
+title: iOS debug symbols now upload to symbol servers
+date: 2026-09-21
+version: 1.6.123
+area: CLI
+type: Fixed
+docLink:
+  label: Release options
+  href: /code-push/release/#options
+---
+
+On iOS, `--split-debug-info` now writes a Mach-O dSYM, so symbol servers ingest
+it and Dart stack traces from production become readable.
+
+- Previously the file was an ELF with no debug ID. Uploads reported finding
+  nothing, while still exiting cleanly.
diff --git a/src/data/changelog.ts b/src/data/changelog.ts
index 8a8cbce9..efa6a39d 100644
--- a/src/data/changelog.ts
+++ b/src/data/changelog.ts
@@ -1,5 +1,6 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { getCollection, render } from 'astro:content';
+import { unlistedPages } from '~/unlisted';
 import { AREAS, type Area, type ChangeType } from './changelog-schema';
 
 // Shared by the changelog page (`src/pages/changelog.astro`), its
@@ -13,7 +14,7 @@ export { AREAS, type Area };
 
 export const CHANGELOG_TITLE = 'Changelog';
 export const CHANGELOG_DESCRIPTION =
-  'What we shipped to Code Push, the CLI, and the API, newest first.';
+  'New features, fixes, and supported Flutter versions in Shorebird, newest first.';
 
 export interface ChangelogEntry {
   /** Anchor id and permalink slug for this entry: its file name. */
@@ -56,9 +57,22 @@ function inlineProblem(text: string, allowCode = true): string | undefined {
     return 'Links are not supported in entry text. Put the link in docLink.';
   }
   if (/\*\*|__/.test(prose)) return 'Bold text is not supported.';
+  // Emphasis needs a closing marker, so `snake_case` and `_template.md` pass.
+  if (/(^|[\s(])([*_])\S(?:[^*_\n]*?\S)?\2(?=$|[\s.,;:!?)])/.test(prose)) {
+    return 'Italic text is not supported.';
+  }
   if (/<[^>]*>/.test(prose)) {
     return 'Wrap placeholders like <id> in backticks, or they vanish from /changelog.md.';
   }
+  if (/&(#\d+|[a-z]+);/i.test(prose)) {
+    return 'Write characters as they are, not as HTML entities like &amp;.';
+  }
+  if (/\\[\\`*_{}[\]()#+\-.!|]/.test(prose)) {
+    return 'Backslash escapes are not supported. Put the text in backticks instead.';
+  }
+  if (/https?:\/\/|www\./.test(prose)) {
+    return 'Links are not supported in entry text. Put the link in docLink.';
+  }
   return undefined;
 }
 
@@ -111,10 +125,14 @@ function parseBody(
         fail(n, 'The code block must be ```sh.');
       }
       code = [];
+      // Keep lines as written: indentation and blank lines can matter, and
+      // only a `$ ` prompt is stripped, never a `$VARIABLE`.
       for (i++; i < lines.length && !lines[i].startsWith('```'); i++) {
-        if (lines[i].trim()) code.push(lines[i].trim().replace(/^\$\s*/, ''));
+        code.push(lines[i].trimEnd().replace(/^\$\s+/, ''));
       }
       if (i === lines.length) fail(n, 'This code block is never closed.');
+      while (code.length && !code[0]) code.shift();
+      while (code.length && !code[code.length - 1]) code.pop();
       block = 'none';
     } else if (code) {
       fail(n, 'Nothing can follow the code block.');
@@ -162,11 +180,25 @@ function parseBody(
  * validator only covers links inside docs pages, not these.
  */
 async function checkDocLink(file: string, href: string): Promise<void> {
-  if (/^https?:\/\//.test(href)) return;
   const url = new URL(href, 'https://docs.shorebird.dev');
+  if (url.origin !== 'https://docs.shorebird.dev') return;
   const path = url.pathname.replace(/^\/|\/$/g, '');
   const docs = await getCollection('docs');
   const doc = docs.find((d) => d.id === path || d.id === `${path}/index`);
+  // Linking an unlisted or draft page would advertise it, which is what
+  // `src/unlisted.ts` exists to prevent (and a draft 404s in production).
+  if (doc && (doc.data.draft || unlistedPages.includes(doc.id))) {
+    throw new Error(
+      `${file}: docLink.href "${href}" is an unlisted or draft page. Link a ` +
+        'published page instead.',
+    );
+  }
+  // Standalone pages like /roadmap/ aren't in the docs collection.
+  const standalone = [
+    `src/pages/${path}.astro`,
+    `src/pages/${path}/index.astro`,
+  ];
+  if (!doc && path && standalone.some((f) => existsSync(f))) return;
   if (!doc) {
     throw new Error(
       `${file}: docLink.href "${href}" doesn't match any docs page. Use the ` +
@@ -204,6 +236,16 @@ export function getEntries(): Promise<ChangelogEntry[]> {
     const entries = await Promise.all(
       files.map(async ({ id, data, body, filePath }) => {
         const file = filePath ?? `src/content/changelog/${id}.md`;
+        // The file name is the entry's anchor, so it can't be a month's.
+        if (
+          /^(january|february|march|april|may|june|july|august|september|october|november|december)-\d{4}$/.test(
+            id,
+          )
+        ) {
+          throw new Error(
+            `${file}: the file name matches a month heading's anchor. Rename it.`,
+          );
+        }
         const titleProblem = inlineProblem(data.title, false);
         if (titleProblem) throw new Error(`${file}: title: ${titleProblem}`);
         if (data.docLink) await checkDocLink(file, data.docLink.href);
diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro
index 01d688d4..25139b1f 100644
--- a/src/pages/changelog.astro
+++ b/src/pages/changelog.astro
@@ -24,6 +24,16 @@ const groups = groupByMonth(ENTRIES);
 // Only offer a chip for an area that has entries, so no filter starts empty.
 const areas = AREAS.filter((a) => ENTRIES.some((e) => e.area === a));
 
+// A command's lines, each marked for whether it gets a `$ ` prompt: not a
+// blank line, and not one continuing the previous line after a backslash.
+function commandLines(code: string): { text: string; prompt: boolean }[] {
+  const lines = code.split('\n');
+  return lines.map((text, i) => ({
+    text,
+    prompt: text.trim() !== '' && !lines[i - 1]?.endsWith('\\'),
+  }));
+}
+
 function formatDay(iso: string): string {
   return new Date(iso).toLocaleDateString('en-US', {
     month: 'short',
@@ -52,8 +62,8 @@ function formatDay(iso: string): string {
   headings={groups.map((g) => ({ depth: 2, slug: g.id, text: g.label }))}
 >
   <p>
-    What we shipped to Code Push, the CLI, and the API. Expand an entry for the
-    full detail, the command, and the doc it belongs to. Subscribe with the <a
+    New features, fixes, and supported Flutter versions in Shorebird. Expand an
+    entry for the full detail, the command, and the doc it belongs to. Subscribe with the <a
       href="/changelog.xml">RSS feed</a
     >.
   </p>
@@ -203,7 +213,7 @@ function formatDay(iso: string): string {
                       ))}
                     </ul>
                     {e.code && (
-                      <pre class="cl-code"><code>{e.code.split('\n').map((c) => `$ ${c}`).join('\n')}</code></pre>
+                      <pre class="cl-code"><code>{commandLines(e.code).map((l, i) => [i > 0 && '\n', <span class:list={['cl-line', { 'is-prompt': l.prompt }]}>{l.text}</span>])}</code></pre>
                     )}
                     <div class="cl-footer">
                       {e.docLink && (
@@ -389,7 +399,12 @@ function formatDay(iso: string): string {
     // Open and scroll to the entry named in the URL hash, if any. Also runs
     // on hashchange, so a permalink followed from this same page opens too.
     function openFromHash() {
-      const targetId = decodeURIComponent(location.hash.replace(/^#/, ''));
+      let targetId = '';
+      try {
+        targetId = decodeURIComponent(location.hash.replace(/^#/, ''));
+      } catch {
+        return; // A malformed hash like #%E0 names nothing on the page.
+      }
       if (!targetId) return;
       const target = document.getElementById(targetId);
       const isEntry = target?.classList.contains('cl-entry');
@@ -519,8 +534,14 @@ function formatDay(iso: string): string {
     background: color-mix(in srgb, var(--sl-color-black) 14%, transparent);
   }
 
+  /* Dim with a dashed border and a quieter pill rather than opacity, so the
+     label keeps its contrast; the chip is still focusable and clickable. */
   .cl-chip.is-empty:not(.is-active) {
-    opacity: 0.45;
+    border-style: dashed;
+  }
+
+  .cl-chip.is-empty:not(.is-active) .cl-chip-count {
+    background: transparent;
   }
 
   /* Timeline. Each entry is a date gutter and a body; the bodies' left
@@ -789,6 +810,15 @@ function formatDay(iso: string): string {
     color: var(--sl-color-gray-1);
   }
 
+  /* The prompt is drawn, not written, so copying a command doesn't copy it.
+     A line continuing the previous one (after a trailing backslash) gets no
+     prompt. */
+  .cl-line.is-prompt::before {
+    content: '$ ';
+    color: var(--sl-color-gray-3);
+    user-select: none;
+  }
+
   /* Starlight's inline-code border and padding would box the command a
      second time inside the block. */
   .cl-code code {