Docs overhaul: v0.22 accuracy pass, teams/partners sections, full-site review

.github/workflows/docs-check.yml

@@ -0,0 +1,18 @@
+name: Docs checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check

CLAUDE.md

@@ -92,14 +92,18 @@ just deploy production   # Deploy to production environment
 │   ├── app.config.ts    # Docus configuration
 │   └── components/      # Custom Vue components
 ├── content/             # Documentation pages (Markdown)
-│   ├── 1.start-here/    # Getting started guides
-│   ├── 2.whats-new/     # Release notes
-│   ├── 3.cloud/         # Cloud documentation
-│   ├── 4.local/         # Local installation
-│   ├── 5.concepts/      # Core concepts
-│   ├── 6.integrations/  # Integration guides
-│   ├── 7.how-to/        # How-to guides
-│   └── 8.reference/     # Technical reference
+│   ├── 0.welcome.md     # Landing page (/ redirects to /welcome)
+│   ├── 01.start-here/   # Getting started guides
+│   ├── 02.whats-new/    # Announcements + changelog
+│   ├── 03.cloud/        # Cloud documentation
+│   ├── 04.teams/        # Teams documentation
+│   ├── 05.partners/     # MSP partner program
+│   ├── 06.local/        # Local installation
+│   ├── 07.concepts/     # Core concepts
+│   ├── 08.integrations/ # Integration guides
+│   ├── 09.how-to/       # How-to guides
+│   └── 10.reference/    # Technical reference
+# Nav order sorts numeric prefixes lexically — keep them zero-padded
 ├── public/              # Static assets
 ├── server/              # Server routes (API)
 ├── nuxt.config.ts       # Nuxt configuration
@@ -174,11 +178,10 @@ pip install basic-memory
 
 When updating docs for a new Basic Memory release, update all of the following:
 
-1. **Homepage version badge** — `content/index.md`: update the version text (e.g., `v0.22 →`) and the `to:` link to point to the new release notes page
-2. **Release notes page** — new minor/major: replace the previous version's page — rename `content/2.whats-new/1.v<OLD>.md` to `1.v<NEW>.md` and rewrite it for the new release. Only the latest release gets a dedicated page (the changelog covers older releases), so the left nav must never show two version entries. Update any inbound links to the old release URL: latest-release cards point to the new page; references to version-specific behavior point to the GitHub release tag. Patch release: append a short note to the current version's page instead
-3. **Changelog** — the `*.changelog.md` page under `content/2.whats-new/` auto-fetches from the GitHub releases API, no manual update needed
-4. **Feature docs** — if the release adds user-facing features, update the relevant guide and reference pages (`content/3.cloud/`, `content/9.reference/`, etc.)
-5. **Deploy** — push to main auto-deploys to development; production requires manual workflow dispatch via GitHub Actions
+1. **Welcome page What's New callout** — `content/0.welcome.md`: update the version text (e.g., `v0.22`) and the headline; the link stays `/whats-new/changelog`
+2. **Changelog page** — `content/2.whats-new/1.changelog.md`: add a section for the new minor/major version at the top, linking the GitHub release tag(s). Patch release: add a short bullet list under its minor version's section instead. The `::github-releases` block at the bottom auto-fetches full release notes from the GitHub API — no manual update needed there. There are no per-version pages — deep links to version-specific behavior point at GitHub release tags
+3. **Feature docs** — if the release adds user-facing features, update the relevant guide and reference pages (`content/3.cloud/`, `content/9.reference/`, etc.)
+4. **Deploy** — push to main auto-deploys to development; production requires manual workflow dispatch via GitHub Actions
 
 ## Documentation Status & Priorities
 

app/app.config.ts

@@ -47,14 +47,17 @@ export default defineAppConfig({
     x: 'https://x.com/basic_memory',
     discord: 'https://discord.gg/tyvKNccgqN',
     reddit: 'https://www.reddit.com/r/basicmemory',
+    linkedin: 'https://www.linkedin.com/company/basicmemory/',
   },
   toc: {
     bottom: {
-      title: 'Community',
+      title: 'Contact Us',
       links: [
+        { label: 'Contact Support', to: '/reference/contact-support' },
+        { label: 'Discord', to: 'https://discord.gg/tyvKNccgqN' },
         { label: 'GitHub', to: 'https://github.com/basicmachines-co/basic-memory' },
         { label: 'X / Twitter', to: 'https://x.com/basic_memory' },
-        { label: 'Discord', to: 'https://discord.gg/tyvKNccgqN' },
+        { label: 'LinkedIn', to: 'https://www.linkedin.com/company/basicmemory/' },
         { label: 'Reddit', to: 'https://www.reddit.com/r/basicmemory' },
       ],
     },

app/components/content/Mermaid.vue

@@ -62,12 +62,28 @@ async function renderMermaid() {
     // Dynamic import to keep bundle size down when mermaid isn't used
     const { renderMermaid: render } = await import('beautiful-mermaid')
 
-    // Use different colors for light/dark mode
-    const svg = await render(props.code.trim(), {
-      bg: isDark.value ? '#1e293b' : '#ffffff',
-      fg: isDark.value ? '#e2e8f0' : '#18181b',
-      transparent: true,
-    })
+    // Enriched theme matching the site palette (orange primary, stone neutral)
+    const svg = await render(props.code.trim(), isDark.value
+      ? {
+          bg: '#1c1917', // stone-900
+          fg: '#e7e5e4', // stone-200
+          accent: '#f97316', // orange-500 — arrow heads, highlights
+          line: '#78716c', // stone-500 — connectors
+          muted: '#a8a29e', // stone-400 — edge labels, secondary text
+          surface: '#292524', // stone-800 — node fill
+          border: '#57534e', // stone-600 — node stroke
+          transparent: true,
+        }
+      : {
+          bg: '#ffffff',
+          fg: '#292524', // stone-800
+          accent: '#ea580c', // orange-600
+          line: '#a8a29e', // stone-400
+          muted: '#78716c', // stone-500
+          surface: '#fafaf9', // stone-50
+          border: '#d6d3d1', // stone-300
+          transparent: true,
+        })
 
     svgContent.value = svg
   } catch (e) {

app/components/content/ThemeImage.vue

@@ -1,7 +1,7 @@
 <template>
   <span class="block">
-    <img :src="light" :alt="alt" class="block dark:hidden rounded-md" />
-    <img :src="dark" :alt="alt" class="hidden dark:block rounded-md" />
+    <img :src="light" :alt="alt" class="block dark:hidden rounded-md border border-neutral-300 dark:border-neutral-700" />
+    <img :src="dark" :alt="alt" class="hidden dark:block rounded-md border border-neutral-300 dark:border-neutral-700" />
   </span>
 </template>
 

app/plugins/signup-attribution.client.ts

@@ -0,0 +1,259 @@
+/**
+ * Signup attribution capture — port of basicmemory.com's
+ * src/lib/signup-attribution.ts. Writes the shared
+ * `bmc_signup_attribution_v1` cookie on `.basicmemory.com` so signups at
+ * app.basicmemory.com can be attributed to a docs first touch. Keep the
+ * cookie name, shape, and semantics in sync with the marketing site.
+ */
+
+const COOKIE_NAME = 'bmc_signup_attribution_v1'
+const COOKIE_DAYS = 90
+const SELF_DOMAINS = ['basicmemory.com', 'app.basicmemory.com', 'localhost']
+const PASSIVE_CHANNELS = [
+  'unknown',
+  'reddit',
+  'google',
+  'facebook',
+  'microsoft',
+  'x_twitter',
+  'youtube',
+  'referral',
+] as const
+
+type PassiveChannel = (typeof PASSIVE_CHANNELS)[number]
+
+interface PassiveAttribution {
+  event_id: string
+  captured_at: string
+  landing_url: string
+  landing_path: string
+  referrer: string | null
+  referrer_host: string | null
+  utm_source: string | null
+  utm_medium: string | null
+  utm_campaign: string | null
+  utm_term: string | null
+  utm_content: string | null
+  gclid: string | null
+  fbclid: string | null
+  msclkid: string | null
+  rdt_cid: string | null
+  rdt_click_id: string | null
+  passive_channel: PassiveChannel
+}
+
+interface SignupAttributionState {
+  first_touch: PassiveAttribution
+  latest_touch: PassiveAttribution
+}
+
+function safeUrl(raw: string): URL | null {
+  try {
+    return new URL(raw)
+  } catch {
+    return null
+  }
+}
+
+function normalizeValue(value: string | null | undefined): string | null {
+  if (!value) return null
+  const normalized = value.trim().toLowerCase()
+  return normalized.length > 0 ? normalized : null
+}
+
+function cookieValue(name: string): string | null {
+  const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const match = document.cookie.match(new RegExp(`(?:^|; )${escapedName}=([^;]*)`))
+  if (!match || !match[1]) return null
+
+  try {
+    return decodeURIComponent(match[1])
+  } catch {
+    return match[1]
+  }
+}
+
+function isPassiveChannel(value: unknown): value is PassiveChannel {
+  return typeof value === 'string' && PASSIVE_CHANNELS.includes(value as PassiveChannel)
+}
+
+function isTouch(value: unknown): value is PassiveAttribution {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<PassiveAttribution>
+  return typeof candidate.event_id === 'string'
+    && typeof candidate.captured_at === 'string'
+    && typeof candidate.landing_url === 'string'
+    && typeof candidate.landing_path === 'string'
+    && isPassiveChannel(candidate.passive_channel)
+}
+
+function isAttributionState(value: unknown): value is SignupAttributionState {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<SignupAttributionState>
+  return isTouch(candidate.first_touch) && isTouch(candidate.latest_touch)
+}
+
+function readAttributionCookie(): SignupAttributionState | null {
+  const rawValue = cookieValue(COOKIE_NAME)
+  if (!rawValue) return null
+
+  try {
+    const parsed = JSON.parse(rawValue)
+    return isAttributionState(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function isSelfDomain(hostname: string): boolean {
+  return SELF_DOMAINS.some(domain => hostname === domain || hostname.endsWith(`.${domain}`))
+}
+
+function referrerHost(): string | null {
+  const referrer = normalizeValue(document.referrer)
+  if (!referrer) return null
+
+  const parsedReferrer = safeUrl(referrer)
+  if (!parsedReferrer) return null
+
+  const hostname = parsedReferrer.hostname.trim().toLowerCase()
+  if (!hostname || isSelfDomain(hostname)) return null
+  return hostname
+}
+
+function sourceToPassiveChannel(source: string | null): PassiveChannel | null {
+  if (!source) return null
+
+  if (source.includes('reddit') || source === 'rdt') return 'reddit'
+  if (source.includes('google')) return 'google'
+  if (source.includes('facebook') || source === 'fb' || source.includes('instagram')) {
+    return 'facebook'
+  }
+  if (source.includes('bing') || source.includes('microsoft')) return 'microsoft'
+  if (source.includes('twitter') || source === 'x') return 'x_twitter'
+  if (source.includes('youtube') || source.includes('youtu')) return 'youtube'
+
+  return null
+}
+
+function passiveChannel(values: {
+  utmSource: string | null
+  rdtCid: string | null
+  rdtClickId: string | null
+  gclid: string | null
+  fbclid: string | null
+  msclkid: string | null
+  referrerHost: string | null
+}): PassiveChannel {
+  const utmChannel = sourceToPassiveChannel(values.utmSource)
+  if (utmChannel) return utmChannel
+  if (values.utmSource) return 'referral'
+  if (values.rdtCid || values.rdtClickId) return 'reddit'
+  if (values.gclid) return 'google'
+  if (values.fbclid) return 'facebook'
+  if (values.msclkid) return 'microsoft'
+  if (values.referrerHost) return sourceToPassiveChannel(values.referrerHost) ?? 'referral'
+  return 'unknown'
+}
+
+function eventId(): string {
+  if (window.crypto && typeof window.crypto.randomUUID === 'function') {
+    return window.crypto.randomUUID()
+  }
+  return `evt_${Date.now()}_${Math.random().toString(36).slice(2, 12)}`
+}
+
+function buildTouch(): PassiveAttribution {
+  const url = new URL(window.location.href)
+  const utmSource = normalizeValue(url.searchParams.get('utm_source'))
+  const rdtCid = normalizeValue(url.searchParams.get('rdt_cid'))
+  const rdtClickId = normalizeValue(cookieValue('_rdt_click_id'))
+  const gclid = normalizeValue(url.searchParams.get('gclid'))
+  const fbclid = normalizeValue(url.searchParams.get('fbclid'))
+  const msclkid = normalizeValue(url.searchParams.get('msclkid'))
+  const host = referrerHost()
+
+  return {
+    event_id: eventId(),
+    captured_at: new Date().toISOString(),
+    landing_url: `${url.origin}${url.pathname}`,
+    landing_path: url.pathname,
+    referrer: host,
+    referrer_host: host,
+    utm_source: utmSource,
+    utm_medium: normalizeValue(url.searchParams.get('utm_medium')),
+    utm_campaign: normalizeValue(url.searchParams.get('utm_campaign')),
+    utm_term: normalizeValue(url.searchParams.get('utm_term')),
+    utm_content: normalizeValue(url.searchParams.get('utm_content')),
+    gclid,
+    fbclid,
+    msclkid,
+    rdt_cid: rdtCid,
+    rdt_click_id: rdtClickId,
+    passive_channel: passiveChannel({
+      utmSource,
+      rdtCid,
+      rdtClickId,
+      gclid,
+      fbclid,
+      msclkid,
+      referrerHost: host,
+    }),
+  }
+}
+
+function hasSignal(touch: PassiveAttribution): boolean {
+  return touch.passive_channel !== 'unknown'
+    || !!touch.referrer_host
+    || !!touch.utm_source
+    || !!touch.utm_medium
+    || !!touch.utm_campaign
+    || !!touch.utm_term
+    || !!touch.utm_content
+    || !!touch.gclid
+    || !!touch.fbclid
+    || !!touch.msclkid
+    || !!touch.rdt_cid
+    || !!touch.rdt_click_id
+}
+
+function writeAttributionCookie(state: SignupAttributionState): void {
+  const expires = new Date()
+  expires.setTime(expires.getTime() + COOKIE_DAYS * 24 * 60 * 60 * 1000)
+
+  let cookie = `${COOKIE_NAME}=${encodeURIComponent(JSON.stringify(state))}`
+  cookie += `;expires=${expires.toUTCString()};path=/;SameSite=Lax`
+
+  const hostname = window.location.hostname.toLowerCase()
+  if (hostname === 'basicmemory.com' || hostname.endsWith('.basicmemory.com')) {
+    cookie += ';domain=.basicmemory.com'
+  }
+  if (window.location.protocol === 'https:') {
+    cookie += ';Secure'
+  }
+
+  document.cookie = cookie
+}
+
+function captureSignupAttribution(): void {
+  const current = readAttributionCookie()
+  const captured = buildTouch()
+  const state = current
+    ? {
+        first_touch: current.first_touch,
+        latest_touch: hasSignal(captured) ? captured : current.latest_touch,
+      }
+    : {
+        first_touch: captured,
+        latest_touch: captured,
+      }
+
+  writeAttributionCookie(state)
+}
+
+export default defineNuxtPlugin(() => {
+  captureSignupAttribution()
+  useRouter().afterEach(() => {
+    captureSignupAttribution()
+  })
+})