docs: add changelog page and cloud snapshots documentation

- Add auto-updating changelog page that fetches from GitHub releases
- Add cloud snapshots section to cloud guide with CLI commands
- Update CLI reference with snapshot commands and routing flags
- Improve site typography using Tailwind zinc palette
- Remove redundant latest-releases page (replaced by changelog)
- Add MCP configuration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: phernandez

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "basic-memory": {
+      "type": "http",
+      "url": "https://cloud.basicmemory.com/mcp"
+    }
+  }
+}

src/config/navigation.ts

@@ -34,7 +34,7 @@ export const navConfig = {
       title: "What's New",
       items: [
         { title: "What's New", href: '/whats-new' },
-        { title: 'Latest Releases', href: '/latest-releases' },
+        { title: 'Changelog', href: '/changelog' },
       ],
     },
     {

src/pages/changelog.astro

@@ -0,0 +1,302 @@
+---
+import Layout from '@/layouts/Layout.astro'
+import Header from '@/components/Header.astro'
+import Sidebar from '@/components/Sidebar.astro'
+import Footer from '@/components/Footer.astro'
+import { BetaAnnouncementBanner } from '@/components/beta-announcement-banner'
+
+// Fetch releases from GitHub at build time
+const REPO = 'basicmachines-co/basic-memory'
+const response = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=50`, {
+  headers: {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'basic-memory-docs',
+    ...(import.meta.env.GITHUB_TOKEN && {
+      'Authorization': `token ${import.meta.env.GITHUB_TOKEN}`
+    })
+  }
+})
+
+interface GitHubRelease {
+  id: number
+  tag_name: string
+  name: string
+  body: string
+  published_at: string
+  html_url: string
+  prerelease: boolean
+  draft: boolean
+}
+
+const releases: GitHubRelease[] = await response.json()
+const publishedReleases = releases.filter((r: GitHubRelease) => !r.draft)
+
+function formatDate(dateString: string): string {
+  const date = new Date(dateString)
+  return date.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric'
+  })
+}
+
+// Get category from conventional commit prefix
+function getCategory(line: string): { category: string; emoji: string; text: string } {
+  const lower = line.toLowerCase()
+
+  if (lower.startsWith('feat:') || lower.startsWith('feat(')) {
+    return { category: 'Features', emoji: '🚀', text: line.replace(/^feat(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('fix:') || lower.startsWith('fix(')) {
+    return { category: 'Bug Fixes', emoji: '🐛', text: line.replace(/^fix(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('docs:') || lower.startsWith('docs(')) {
+    return { category: 'Documentation', emoji: '📚', text: line.replace(/^docs(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('chore:') || lower.startsWith('chore(')) {
+    return { category: 'Chores', emoji: '🔧', text: line.replace(/^chore(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('refactor:') || lower.startsWith('refactor(')) {
+    return { category: 'Refactoring', emoji: '♻️', text: line.replace(/^refactor(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('perf:') || lower.startsWith('perf(')) {
+    return { category: 'Performance', emoji: '⚡', text: line.replace(/^perf(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('test:') || lower.startsWith('test(')) {
+    return { category: 'Tests', emoji: '🧪', text: line.replace(/^test(\([^)]+\))?:\s*/i, '') }
+  }
+  if (lower.startsWith('breaking:') || lower.includes('breaking change')) {
+    return { category: 'Breaking Changes', emoji: '🚨', text: line.replace(/^breaking(\([^)]+\))?:\s*/i, '') }
+  }
+
+  return { category: 'Changes', emoji: '📦', text: line }
+}
+
+// Parse release body into categorized sections
+function parseReleaseBody(body: string): Map<string, { emoji: string; items: string[] }> {
+  if (!body) return new Map()
+
+  const categories = new Map<string, { emoji: string; items: string[] }>()
+  const lines = body.split('\n')
+
+  let currentSection = ''
+  let currentEmoji = '📦'
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+
+    // Check for markdown headers (## Features, ### Bug Fixes, etc.)
+    const headerMatch = trimmed.match(/^#{2,3}\s+(.+)/)
+    if (headerMatch) {
+      const header = headerMatch[1].toLowerCase()
+      if (header.includes('feature') || header.includes('highlight')) {
+        currentSection = 'Features'
+        currentEmoji = '🚀'
+      } else if (header.includes('bug') || header.includes('fix')) {
+        currentSection = 'Bug Fixes'
+        currentEmoji = '🐛'
+      } else if (header.includes('breaking')) {
+        currentSection = 'Breaking Changes'
+        currentEmoji = '🚨'
+      } else if (header.includes('document')) {
+        currentSection = 'Documentation'
+        currentEmoji = '📚'
+      } else if (header.includes('performance')) {
+        currentSection = 'Performance'
+        currentEmoji = '⚡'
+      } else if (header.includes('chore') || header.includes('internal')) {
+        currentSection = 'Chores'
+        currentEmoji = '🔧'
+      } else if (header.includes('refactor')) {
+        currentSection = 'Refactoring'
+        currentEmoji = '♻️'
+      } else if (header.includes('contributor')) {
+        currentSection = 'New Contributors'
+        currentEmoji = '👋'
+      } else if (header.includes('change')) {
+        currentSection = 'Changes'
+        currentEmoji = '📦'
+      } else {
+        currentSection = headerMatch[1]
+        currentEmoji = '📦'
+      }
+      continue
+    }
+
+    // Check for list items
+    if (trimmed.startsWith('* ') || trimmed.startsWith('- ')) {
+      const itemText = trimmed.substring(2)
+
+      // If no current section, try to categorize by conventional commit prefix
+      if (!currentSection) {
+        const { category, emoji, text } = getCategory(itemText)
+        if (!categories.has(category)) {
+          categories.set(category, { emoji, items: [] })
+        }
+        categories.get(category)!.items.push(text)
+      } else {
+        if (!categories.has(currentSection)) {
+          categories.set(currentSection, { emoji: currentEmoji, items: [] })
+        }
+        categories.get(currentSection)!.items.push(itemText)
+      }
+    }
+  }
+
+  return categories
+}
+
+// Format changelog item with proper links and code styling
+function formatItem(text: string): string {
+  let result = text
+
+  // Convert full GitHub PR URLs to short format: #123
+  result = result.replace(
+    /https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/(\d+)/g,
+    `<a href="https://github.com/${REPO}/pull/$1" class="font-medium text-zinc-700 dark:text-zinc-300 hover:text-zinc-900 dark:hover:text-zinc-100 no-underline hover:underline">#$1</a>`
+  )
+
+  // Convert full GitHub issue URLs to short format
+  result = result.replace(
+    /https:\/\/github\.com\/[^/]+\/[^/]+\/issues\/(\d+)/g,
+    `<a href="https://github.com/${REPO}/issues/$1" class="font-medium text-zinc-700 dark:text-zinc-300 hover:text-zinc-900 dark:hover:text-zinc-100 no-underline hover:underline">#$1</a>`
+  )
+
+  // Link remaining #123 references
+  result = result.replace(
+    /(?<!<a[^>]*>)#(\d+)(?![^<]*<\/a>)/g,
+    `<a href="https://github.com/${REPO}/pull/$1" class="font-medium text-zinc-700 dark:text-zinc-300 hover:text-zinc-900 dark:hover:text-zinc-100 no-underline hover:underline">#$1</a>`
+  )
+
+  // Link @mentions
+  result = result.replace(
+    /@([a-zA-Z0-9_-]+)/g,
+    `<a href="https://github.com/$1" class="font-medium text-zinc-700 dark:text-zinc-300 hover:text-zinc-900 dark:hover:text-zinc-100 no-underline hover:underline">@$1</a>`
+  )
+
+  // Style inline code (backticks) - using Tailwind classes
+  result = result.replace(
+    /`([^`]+)`/g,
+    '<code class="rounded-md bg-zinc-100 dark:bg-zinc-800 px-1.5 py-0.5 font-mono text-sm text-zinc-800 dark:text-zinc-200">$1</code>'
+  )
+
+  // Bold the first part before "by @" if present (the description)
+  const byMatch = result.match(/^(.+?)(\s+by\s+<a)/)
+  if (byMatch) {
+    result = `<span class="text-zinc-900 dark:text-zinc-100">${byMatch[1]}</span>${result.substring(byMatch[1].length)}`
+  }
+
+  // Remove "in https://github.com/..." trailing text
+  result = result.replace(/\s+in\s+https:\/\/github\.com\/[^\s]+/g, '')
+
+  return result
+}
+
+// Order categories for display
+const categoryOrder = ['Breaking Changes', 'Features', 'Bug Fixes', 'Performance', 'Documentation', 'Refactoring', 'Chores', 'Tests', 'Changes', 'New Contributors']
+
+function sortCategories(categories: Map<string, { emoji: string; items: string[] }>): Array<[string, { emoji: string; items: string[] }]> {
+  const entries = Array.from(categories.entries())
+  return entries.sort((a, b) => {
+    const aIndex = categoryOrder.indexOf(a[0])
+    const bIndex = categoryOrder.indexOf(b[0])
+    if (aIndex === -1 && bIndex === -1) return 0
+    if (aIndex === -1) return 1
+    if (bIndex === -1) return -1
+    return aIndex - bIndex
+  })
+}
+---
+
+<Layout title="Changelog" description="Release history for Basic Memory">
+
+  <div class="min-h-screen flex flex-col">
+    <BetaAnnouncementBanner client:load />
+    <Header />
+    <div class="flex flex-1 justify-center">
+      <div class="flex w-full max-w-screen-2xl">
+        <Sidebar />
+        <main class="flex-1 min-w-0 px-6">
+          <article class="max-w-4xl py-8 changelog-article">
+            <div class="mb-12">
+              <h1 class="text-4xl font-bold tracking-tight mb-3">Changelog</h1>
+              <p class="text-lg text-zinc-500 dark:text-zinc-400">
+                All notable changes to <a href={`https://github.com/${REPO}`} class="font-medium text-zinc-700 dark:text-zinc-300 hover:text-zinc-900 dark:hover:text-zinc-100 underline underline-offset-2">Basic Memory</a>
+              </p>
+            </div>
+
+            <div class="space-y-16">
+              {publishedReleases.map((release) => {
+                const categories = parseReleaseBody(release.body)
+                const sortedCategories = sortCategories(categories)
+
+                return (
+                  <section class="relative">
+                    {/* Version header */}
+                    <div class="flex items-baseline gap-4 mb-6">
+                      <a
+                        href={release.html_url}
+                        class="text-3xl font-bold text-zinc-900 dark:text-zinc-100 hover:text-zinc-600 dark:hover:text-zinc-300 transition-colors no-underline"
+                      >
+                        {release.tag_name}
+                      </a>
+                      <time class="text-sm text-zinc-500 dark:text-zinc-400 font-medium">
+                        {formatDate(release.published_at)}
+                      </time>
+                      {release.prerelease && (
+                        <span class="px-2 py-0.5 text-xs font-semibold bg-amber-500/10 text-amber-600 dark:text-amber-400 rounded-full border border-amber-500/20">
+                          Pre-release
+                        </span>
+                      )}
+                    </div>
+
+                    {/* Categories */}
+                    {sortedCategories.length > 0 ? (
+                      <div class="space-y-6">
+                        {sortedCategories.map(([category, { emoji, items }]) => (
+                          <div>
+                            <h3 class="flex items-center gap-2 text-lg font-semibold text-zinc-800 dark:text-zinc-200 mb-3">
+                              <span>{emoji}</span>
+                              <span>{category}</span>
+                            </h3>
+                            <ul class="space-y-2 ml-1">
+                              {items.map((item) => (
+                                <li class="flex gap-3 text-[15px] leading-relaxed text-zinc-600 dark:text-zinc-400">
+                                  <span class="text-zinc-400 dark:text-zinc-600 select-none">•</span>
+                                  <span set:html={formatItem(item)} />
+                                </li>
+                              ))}
+                            </ul>
+                          </div>
+                        ))}
+                      </div>
+                    ) : (
+                      <p class="text-zinc-500 dark:text-zinc-400 italic">No release notes available.</p>
+                    )}
+
+                    {/* Divider */}
+                    <div class="mt-12 border-b border-zinc-200 dark:border-zinc-800" />
+                  </section>
+                )
+              })}
+            </div>
+
+            {/* Footer link */}
+            <div class="mt-16 pt-8 text-center">
+              <a
+                href={`https://github.com/${REPO}/releases`}
+                class="inline-flex items-center gap-2 text-sm font-medium text-zinc-500 dark:text-zinc-400 hover:text-zinc-700 dark:hover:text-zinc-200 transition-colors no-underline"
+              >
+                View all releases on GitHub
+                <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
+                </svg>
+              </a>
+            </div>
+          </article>
+          <Footer />
+        </main>
+      </div>
+    </div>
+  </div>
+</Layout>

src/pages/guides/cli-reference.mdx

@@ -18,7 +18,11 @@ You can use the shorter command alias `bm` instead of `basic-memory` for all com
 
 ### cloud
 
-Manage Basic Memory Cloud authentication, projects, and file uploads. Requires active subscription.
+Manage Basic Memory Cloud authentication, projects, and file uploads.
+
+<Note>
+Cloud commands require a Basic Memory Cloud subscription.
+</Note>
 
 ```bash
 # Authenticate with cloud
@@ -134,20 +138,21 @@ basic-memory --project=personal mcp
 
 #### Local/Cloud Routing Flags
 
-When cloud mode is enabled, you can force routing to local or cloud using these flags:
+The `tools` commands support `--local` and `--cloud` flags to control routing when cloud mode is enabled:
 
 ```bash
-# Force local MCP server even when cloud mode is enabled
-basic-memory --local mcp
+# Force local routing for tool commands
+bm tools search-notes --query "api" --local
+bm tools recent-activity --local
 
 # Force cloud routing
-basic-memory --cloud mcp
-
-# These flags work with mcp, project, and tool commands
-basic-memory --local project list
-basic-memory --cloud tool search-notes --query "api"
+bm tools search-notes --query "api" --cloud
 ```
 
+<Note>
+These flags are available on `tools` subcommands like `search-notes`, `recent-activity`, `build-context`, etc. The `mcp` command always runs locally.
+</Note>
+
 <Note>
 The `--local` flag is useful when you want to work with local files while cloud mode is configured. The `--cloud` flag ensures operations go through the cloud even if local files exist.
 </Note>