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 1/6] 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 2/6] 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 3/6] 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 4/6] 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 5/6] 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 6/6] 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;
   }