diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml
new file mode 100644
index 0000000..f303f72
--- /dev/null
+++ b/.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
diff --git a/CLAUDE.md b/CLAUDE.md
index d17fb05..8e6d0ce 100644
--- a/CLAUDE.md
+++ b/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
 
diff --git a/app/app.config.ts b/app/app.config.ts
index 2a0cedb..bc9e946 100644
--- a/app/app.config.ts
+++ b/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' },
       ],
     },
diff --git a/app/components/content/Mermaid.vue b/app/components/content/Mermaid.vue
index 9a72aab..832ae97 100644
--- a/app/components/content/Mermaid.vue
+++ b/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) {
diff --git a/app/components/content/ThemeImage.vue b/app/components/content/ThemeImage.vue
index 28e8ccc..ee6fe53 100644
--- a/app/components/content/ThemeImage.vue
+++ b/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>
 
diff --git a/app/plugins/signup-attribution.client.ts b/app/plugins/signup-attribution.client.ts
new file mode 100644
index 0000000..7b49b56
--- /dev/null
+++ b/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()
+  })
+})
diff --git a/content/0.welcome.md b/content/0.welcome.md
new file mode 100644
index 0000000..11e3e7e
--- /dev/null
+++ b/content/0.welcome.md
@@ -0,0 +1,95 @@
+---
+title: Welcome
+description: Real memory for your AI. A knowledge base you own.
+navigation:
+  icon: i-lucide-hand
+seo:
+  title: Basic Memory
+  description: Real memory for your AI. A knowledge base you own — a knowledge graph written in plain Markdown that works with every AI tool.
+---
+
+**Basic Memory** is real memory for your AI — a knowledge base you own. Built-in AI memory is small, vendor-owned, and usually invisible. Basic Memory is large, structured, and inspectable: a knowledge graph written in plain Markdown. Open it in any editor, hand it to any AI tool, and keep it forever.
+
+::note{icon="i-lucide-megaphone"}
+**New in v0.22:** team-safe cloud push and pull, search improvements, and MCP reliability fixes. See the [Changelog](/whats-new/changelog).
+::
+
+## Pick your path
+
+:::card-group
+::card
+---
+title: What is Basic Memory?
+icon: i-lucide-lightbulb
+to: /start-here/what-is-basic-memory
+---
+How persistent AI memory works, and why it beats chat history.
+::
+
+::card
+---
+title: Quickstart — Cloud
+icon: i-lucide-cloud
+to: /start-here/quickstart-cloud
+---
+Connect Basic Memory Cloud and create your first note in 2 minutes, no install required.
+::
+
+::card
+---
+title: Quickstart — Local
+icon: i-lucide-terminal
+to: /start-here/quickstart-local
+---
+Run the open-source version on your machine. Your files never leave your computer.
+::
+
+::card
+---
+title: Set Up Local Projects
+icon: i-lucide-map
+to: /local/getting-started
+---
+After installing locally: create projects and choose where your notes are saved on disk.
+::
+:::
+
+## Go deeper
+
+:::card-group
+::card
+---
+title: Connect your AI tools
+icon: i-lucide-plug
+to: /integrations
+---
+Claude, ChatGPT, Codex, Gemini, Cursor, VS Code, Obsidian, and more via MCP.
+::
+
+::card
+---
+title: Teams
+icon: i-lucide-users
+to: /teams/about
+---
+Share one knowledge base with your team — roles, invites, and real-time editing.
+::
+
+::card
+---
+title: Open source
+icon: i-simple-icons-github
+to: https://github.com/basicmachines-co/basic-memory
+---
+Run locally, self-host, contribute, or just explore the code.
+::
+
+::card
+---
+title: AI-friendly docs
+icon: i-lucide-bot
+to: /reference/llms-txt
+---
+These docs support llms.txt, so your AI assistant can read them directly.
+::
+:::
diff --git a/content/1.start-here/.navigation.yml b/content/01.start-here/.navigation.yml
similarity index 100%
rename from content/1.start-here/.navigation.yml
rename to content/01.start-here/.navigation.yml
diff --git a/content/1.start-here/1.what-is-basic-memory.md b/content/01.start-here/1.what-is-basic-memory.md
similarity index 78%
rename from content/1.start-here/1.what-is-basic-memory.md
rename to content/01.start-here/1.what-is-basic-memory.md
index af13b5a..ba32da7 100644
--- a/content/1.start-here/1.what-is-basic-memory.md
+++ b/content/01.start-here/1.what-is-basic-memory.md
@@ -3,9 +3,9 @@ title: What is Basic Memory
 description: An overview of what Basic Memory is and how it works.
 ---
 
-Basic Memory is a knowledge base that you and your AI assistant share. It stores notes as Markdown files so your work stays readable, portable, and searchable.
+Basic Memory is real memory for your AI — a knowledge base you own. It stores notes as plain Markdown files, so your work stays readable, portable, and searchable.
 
-Instead of losing valuable insights in conversation history, you build a persistent knowledge base where both you and AI can read, write, and enhance each other's work.
+Instead of losing valuable insights in conversation history, you build a persistent knowledge base that every AI tool you use can read, write, and enhance — Claude, ChatGPT, Codex, OpenClaw, Hermes, and all your team's agents, working from one shared memory.
 
 ---
 :video{autoplay controls loop muted src="https://basicmemory.com/videos/explainer-video.mp4"}
@@ -21,6 +21,7 @@ Instead of losing valuable insights in conversation history, you build a persist
 - **You own your data** - Plain Markdown files you control
 - **Structured knowledge** - Observations and relations create a semantic graph
 - **Works with any AI** - Claude, ChatGPT, and other MCP-compatible assistants
+- **One memory for all your agents** - every tool reads the same knowledge base; with [Teams](/teams/about), so does your whole team
 
 ---
 
@@ -64,7 +65,7 @@ Use the hosted cloud service or run everything locally - your choice.
 
 ## How it works
 
-Basic Memory runs an MCP server that can read and write Markdown files. A SQLite index keeps search fast. Your assistant calls tools like `search_notes`, `read_note`, and `write_note` to work with your notes.
+Basic Memory stores your notes as Markdown files and keeps a search index over them. Your AI assistant connects through MCP and calls tools like `search_notes`, `read_note`, and `write_note` to work with your notes.
 
 ::mermaid
 ---
@@ -76,8 +77,8 @@ code: |
       end
 
       subgraph Basic Memory
-          M[MCP Server]
-          I[Index]
+          M[MCP Tools]
+          I[Search Index]
       end
 
       subgraph Storage
@@ -147,7 +148,7 @@ We needed to choose an authentication approach for the new API.
 
 **Key concepts:**
 - **Observations** - Categorized facts: `[decision]`, `[requirement]`, `[risk]`, etc.
-- **Relations** - Links to other notes: `[[Other Note]]` in simple WiliLink format
+- **Relations** - Links to other notes: `[[Other Note]]` in simple WikiLink format
 - **Tags** - Searchable metadata: `#security`, `#api`
 
 ::tip 
@@ -168,27 +169,13 @@ Each note becomes an **entity** with structured data:
 ::mermaid
 ---
 code: |
-  flowchart TD
-      subgraph "Knowledge Graph"
-          E1[API Authentication]
-          E2[API Security Spec]
-          E3[User Service]
-          E4[Token Refresh]
-      end
-
-      subgraph "API Authentication: Facts"
-          O1[JWT]
-          O2[Tokens exgire]
-          O3[Rate limiting]
-      end
-
-      E1 -->|implements| E2
-      E1 -->|depends_on| E3
-      E1 -->|relates_to| E4
-
-      E1 -->|decision| O1
-      E1 -->|requirement| O2
-      E1 -->|risk| O3
+  flowchart LR
+      E1[API Authentication] -->|implements| E2[API Security Spec]
+      E1 -->|depends_on| E3[User Service]
+      E1 -->|relates_to| E4[Token Refresh]
+      E1 -->|decision| O1[Use JWT tokens]
+      E1 -->|requirement| O2[Tokens expire in 24h]
+      E1 -->|risk| O3[Rate limit logins]
 ---
 ::
 
@@ -204,13 +191,12 @@ When you ask a question, the AI doesn't just return one note. It traverses the g
 ---
 code: |
   flowchart LR
-      Q[Your Question] --> S[search_notes]
-      S --> R[Matching Notes]
-
-      R --> G[Relationed Notes]
-      R -->|Build| C[Context]
-      C --> A[AI Response]
-      G -->|Follow| R
+      Q[Your question] --> S[search_notes]
+      S --> M[Matching notes]
+      M --> B[build_context]
+      B --> R[Related notes]
+      R --> C[Full context]
+      C --> A[AI answer]
 ---
 ::
 
@@ -260,7 +246,7 @@ Built-in AI memory shows you a short digest at best - not the full context the A
 - **Edit what your AI knows** - Modify, delete, or reorganize knowledge anytime
 - **Watch changes happen** - See exactly what your AI adds or updates
 - **Keep your memory** - Plain Markdown files you own forever
-- **Audit trail** - Every note has a history; you can see what was added when
+- **Audit trail** - In the cloud, every note keeps full [version history](/cloud/file-history); locally, notes are plain files you can track with git
 - **No surprises** - The AI can only know what's in your files; no hidden context
 - **Portable knowledge** - Plain markdown means you're never locked in; chat with one AI, bring your knowledge to the next
 
@@ -282,32 +268,15 @@ AI agents work best when they can observe the results of their actions. Basic Me
 ---
 code: |
   flowchart LR
-      A[Conversation] --> B[AI Writes Memory]
-      B --> C[Human Reviews/Edits]
-      C --> D[AI Reads Context]
+      A[Conversation] --> B[AI writes notes]
+      B --> C[You review & refine]
+      C --> D[AI reads context]
       D --> A
 ---
 ::
 
 Each cycle reinforces learning. You ask questions, the AI searches and responds, creates notes from the conversation, and you review and refine. The knowledge base grows with each iteration.
 
-### Knowledge growth over time
-
-::mermaid
----
-code: |
-  flowchart TD
-      subgraph "The Loop"
-          A[Ask Question] --> B[AI Searches Memory]
-          B --> C[AI Responds + Writes]
-          C --> D[You Review & Refine]
-          D --> E[Knowledge Base Grows]
-          E --> B
-      end
----
-::
-
-
 ### Knowledge refinement over time
 
 Each conversation builds on previous context, creating increasingly refined understanding:
@@ -315,13 +284,12 @@ Each conversation builds on previous context, creating increasingly refined unde
 ::mermaid
 ---
 code: |
-  flowchart TD
+  flowchart LR
       A[Conversation 1] --> B[Memory v1]
       B --> C[Conversation 2]
-      C --> D[Memory v2 - refined]
+      C --> D[Memory v2 · refined]
       D --> E[Conversation 3]
-      E --> F[Memory v3 - richer]
-      F --> G[...]
+      E --> F[Memory v3 · richer]
 ---
 ::
 
@@ -329,6 +297,14 @@ The result: your AI gets smarter about *your* work with every interaction.
 
 ---
 
+## One memory for your whole team
+
+Teams is the big unlock in Basic Memory Cloud: a shared workspace where one knowledge base serves you, your teammates, and every AI agent connected to it. A decision captured in one teammate's Claude session becomes context for another's Codex run. Everyone's agents read and write the same graph, so team knowledge compounds the same way personal knowledge does.
+
+See [Basic Memory Teams](/teams/about) for workspaces, roles, and invitations.
+
+---
+
 ## Where it runs
 
 ### Cloud
@@ -337,8 +313,9 @@ Basic Memory Cloud provides:
 - **Hosted MCP endpoint** - Connect without installing anything
 - **Access from any device** - Use your memory from desktop, mobile, cli, multiple AIs
 - **Web app** - Browse and edit notes in your browser
-- **Local sync** - Sync your notes locally for easy management
-- **Snapshots** - Point-in-time backups, automaticly done daily or manual as needed
+- **Local sync** - Pull and push your notes to a local folder
+- **Team workspaces** - one shared knowledge base for your team and all their agents
+- **Snapshots** - Point-in-time backups, automatically done daily or manual as needed
 
 ### Local
 
@@ -362,16 +339,16 @@ Basic Memory uses the [Model Context Protocol (MCP)](https://modelcontextprotoco
 - `search_notes` - Full-text search
 - `edit_note` - Incremental editing
 - `build_context` - Load related notes
-- `list_memory_projects` - Manage projects
+- `list_memory_projects` - List your projects
 - ...and many more
 
 **Compatible assistants:**
 - Claude Desktop
 - Claude Code
-- ChatGPT (Pro/Max)
+- ChatGPT (Plus/Pro)
 - Google Gemini
 - Cursor
-- VS Code (with MCP extension)
+- VS Code (Copilot Chat)
 - Codex
 
 ---
@@ -409,9 +386,9 @@ Install locally and run everything on your machine.
 ---
 title: Getting Started
 icon: i-lucide-rocket
-to: /start-here/getting-started
+to: /local/getting-started
 ---
-Full installation guide with configuration options.
+Set up projects and choose where your notes are saved.
 ::
 
 ::card
@@ -431,4 +408,13 @@ to: /reference/mcp-tools-reference
 ---
 All available tools for AI assistants.
 ::
+
+::card
+---
+title: Teams
+icon: i-lucide-users
+to: /teams/about
+---
+One shared memory for your team and every agent connected to it.
+::
 :::
diff --git a/content/1.start-here/2.quickstart-cloud.md b/content/01.start-here/2.quickstart-cloud.md
similarity index 55%
rename from content/1.start-here/2.quickstart-cloud.md
rename to content/01.start-here/2.quickstart-cloud.md
index 37e9e47..7dca24e 100644
--- a/content/1.start-here/2.quickstart-cloud.md
+++ b/content/01.start-here/2.quickstart-cloud.md
@@ -19,9 +19,9 @@ code: |
 
 ## 1. Create an account
 
-Sign up at [app.basicmemory.com](https://app.basicmemory.com). You'll need an active subscription to use the MCP endpoint.
+Sign up at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=quickstart-cloud). You'll need an active subscription to use the MCP endpoint.
 
-![Cloud signup page](/screenshots/cloud/signup.png)
+After sign-up, the app prepares your workspace and opens a seeded **Getting Started** project — a short tutorial you can read (and edit) in place. A floating onboarding guide walks you through the same steps as this page: connect your agent, write your first note, and watch it appear live. The in-app **Help Center** (account menu → Help) keeps the same walkthrough available anytime — your MCP endpoint, setup guides, and a quick test prompt.
 
 ---
 
@@ -35,61 +35,35 @@ https://cloud.basicmemory.com/mcp
 
 ### For Claude Desktop
 
-::steps
-### Open Settings
-In Claude Desktop or Claude.ai, go to **Settings → Claude → Connectors**
-
-![Claude Settings - Connectors](/screenshots/claude/settings-connectors.png)
-
-### Add Custom Connector
-Click **Add custom connector** and enter:
-- **Name**: Basic Memory
-- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
-
-![Claude - Add connector dialog](/screenshots/claude/add-connector.png)
-
-### Authenticate
-Click **Connect** to start the OAuth flow. You'll be redirected to Basic Memory to authorize access.
+1. In Claude Desktop or Claude.ai, go to **Settings → Claude → Connectors** and click **Add custom connector**.
+2. Enter the name **Basic Memory** and the server URL `https://cloud.basicmemory.com/mcp`, then click **Connect** and complete the OAuth flow.
+3. Confirm Basic Memory appears in the tools menu in chat.
 
-![OAuth authorization](/screenshots/claude/oauth-connect.png)
-
-![OAuth authorization](/screenshots/claude/oauth-authorize.png)
-
-### Configure Tools (Optional)
-Click **Configure** to customize which tools are enabled.
-
-![Claude - Configure tools](/screenshots/claude/configure-tools.png)
-
-### Verify Setup
-Confirm Basic Memory appears in the tools menu (+ icon in chat).
-
-![Claude - Tools menu](/attachments/claude-tools-menu.png)
-::
+Full walkthrough with screenshots: [Claude Desktop](/integrations/claude-desktop).
 
 ### For ChatGPT
 
 ::note
-ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers.
+ChatGPT requires a **Plus or Pro subscription** to use remote MCP servers.
 ::
 
 ::steps
-### Enable MCP
-Open **Settings → Beta features** and enable MCP
-
-### Add Endpoint
-Add the Basic Memory endpoint URL: `https://cloud.basicmemory.com/mcp`
+### Add the MCP server
+In ChatGPT, go to **Settings → Developer → Custom MCP Servers** and add the Basic Memory endpoint URL: `https://cloud.basicmemory.com/mcp`
 
 ### Authenticate
 Complete the OAuth flow when prompted
 ::
 
+See the [ChatGPT integration guide](/integrations/chatgpt) for the full walkthrough, including the per-chat step for enabling the connector.
+
 ::tip
 Watch the [ChatGPT setup video](https://youtube.com/watch?v=NvU0Jo38P_k) for a complete walkthrough.
 ::
 
 ### For other assistants
 
-See the [Integrations](/integrations/claude-desktop) section for setup guides for:
+See the [Integrations](/integrations) section for setup guides for:
 - [Google Gemini](/integrations/gemini)
 - [Cursor](/integrations/cursor)
 - [VS Code](/integrations/vscode)
@@ -105,13 +79,13 @@ Ask your assistant:
 List my basic memory projects
 ```
 
-**Expected response:**
+**Expected response** — something like:
 ```bash
 You have 1 project:
-- main (default) - /app/data/basic-memory - 0 notes
+- getting-started (default)
 ```
 
-![Claude - Project list response](/screenshots/claude/project-list-response.png)
+New accounts start with the seeded **Getting Started** tutorial project as the default.
 
 ::warning
 If you get an error, check the [Troubleshooting](/reference/troubleshooting) guide.
@@ -124,34 +98,30 @@ If you get an error, check the [Troubleshooting](/reference/troubleshooting) gui
 Try this prompt:
 
 ```bash
-Create a note called "Getting Started" with a summary of what Basic Memory does.
+Create a note called "My First Note" with a summary of what Basic Memory does.
 ```
 
 Your assistant will use the `write_note` tool to create a Markdown file in your cloud storage.
 
 **Example conversation:**
 ```bash
-You: Create a note called "Getting Started" with a summary of what Basic Memory does.
+You: Create a note called "My First Note" with a summary of what Basic Memory does.
 
 AI: I'll create a note summarizing Basic Memory for you.
 
 [Uses write_note tool]
 
-I've created "Getting Started" in your knowledge base. The note covers:
+I've created "My First Note" in your knowledge base. The note covers:
 - What Basic Memory is
 - How the knowledge format works
 - Key features like semantic search and relations
 ```
 
-![Claude - Creating first note](/screenshots/claude/create-first-note.png)
-
 ---
 
 ## 5. View your notes
 
-Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes) to see your new note.
-
-![Web app - First note](/screenshots/cloud-app/first-note.png)
+Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes) to see your new note in the sidebar. Notes written by your agent appear live — no refresh needed — and show up in the **Activity** view alongside your own edits.
 
 **What you can do in the web app:**
 - Browse all your notes in the folder tree
@@ -161,6 +131,18 @@ Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes) to see your
 - Manage multiple projects
 - Create snapshots for backup
 
+::tip
+See the [Web App guide](/cloud/web-app) for the full tour — editing modes, keyboard shortcuts, projects, import, and settings.
+::
+
+---
+
+## 6. Invite your team
+
+Basic Memory is better shared — one knowledge base for you, your teammates, and every agent connected to it. A decision captured in your Claude session becomes context for a teammate's Codex run.
+
+Invite people from **Settings → Members** in the web app — they get an email, sign in, and start working in the shared projects right away. See [Basic Memory Teams](/teams/about) for workspaces, roles, and seats.
+
 ---
 
 ## What you can do now
@@ -187,12 +169,12 @@ AI: [Creates note with observations and tags]
 
 You: "What do I know about coffee brewing?"
 
-Claude: [Searches knowledge base, finds your pour-over note]
+AI: [Searches knowledge base, finds your pour-over note]
 "Based on your notes, you've been exploring pour-over techniques..."
 
 You: "Add a section about water temperature to my coffee notes"
 
-Claude: [Uses edit_note to append new content]
+AI: [Uses edit_note to append new content]
 ```
 
 ---
@@ -224,7 +206,7 @@ title: Cloud Sync
 icon: i-lucide-refresh-cw
 to: /cloud/cloud-sync
 ---
-Set up bidirectional sync with local files.
+Edit locally and sync with push and pull.
 ::
 
 ::card
diff --git a/content/1.start-here/3.quickstart-local.md b/content/01.start-here/3.quickstart-local.md
similarity index 71%
rename from content/1.start-here/3.quickstart-local.md
rename to content/01.start-here/3.quickstart-local.md
index 13e466e..00bb2ff 100644
--- a/content/1.start-here/3.quickstart-local.md
+++ b/content/01.start-here/3.quickstart-local.md
@@ -17,6 +17,10 @@ code: |
 
 ---
 
+::tip
+**Prefer not to install anything?** Basic Memory Cloud connects your AI in about 2 minutes — [sign up at basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=quickstart-local) and follow the [cloud quickstart](/start-here/quickstart-cloud).
+::
+
 ## 1. Install Basic Memory
 
 Choose your installation method. All installs include semantic search for hybrid (keyword + meaning-based) search.
@@ -30,7 +34,7 @@ brew install basic-memory
 ```
 
 ::note
-`brew trust` tells Homebrew you accept code from this third-party tap. Recent Homebrew versions warn about untrusted taps, and Homebrew 6 will require the trust step before installing or upgrading from them. On older Homebrew versions the command doesn't exist yet — just skip it.
+`brew trust` accepts code from this third-party tap. On older Homebrew versions the command doesn't exist yet — just skip it. Details in [Local Installation](/local/local-install).
 ::
 
 ### All platforms (uv)
@@ -42,7 +46,7 @@ uv tool install basic-memory
 ```
 
 ::note
-**Requirements:** Python 3.13 or higher. Check with `python --version`.
+**Requirements:** Python 3.12 or higher. Check with `python --version`.
 ::
 
 ### Verify installation
@@ -51,24 +55,13 @@ uv tool install basic-memory
 basic-memory --version
 ```
 
-**Expected output:**
-```bash
-basic-memory, version 0.19.x
-```
+You should see the installed version printed. If it's older than the [latest release](https://github.com/basicmachines-co/basic-memory/releases), run `bm update` (`bm` is a short alias for `basic-memory`).
 
 ---
 
 ## 2. Configure Claude Desktop
 
-Edit your Claude Desktop config file:
-
-| Platform | Config Location |
-|----------|-----------------|
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Linux | `~/.config/Claude/claude_desktop_config.json` |
-
-Add this configuration:
+Add Basic Memory to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -81,19 +74,15 @@ Add this configuration:
 }
 ```
 
-::warning
-**ENOENT error?** Use the full path to uvx. Find it with `which uvx` and replace `"uvx"` with the full path (e.g., `"/Users/yourname/.local/bin/uvx"`).
-::
+Installed with Homebrew? Use `"command": "basic-memory", "args": ["mcp"]` instead. **Restart Claude Desktop** after editing.
 
-**Restart Claude Desktop** after editing the config.
+Config file locations per platform and ENOENT fixes: [Claude Desktop → Local Setup](/integrations/claude-desktop#local-setup).
 
 ---
 
 ## 3. Verify the connection
 
-In Claude Desktop, click the **tools icon** (hammer) in the bottom-right of the chat interface. You should see Basic Memory tools listed.
-
-![Claude - Tools menu with Basic Memory](/screenshots/claude/tools-menu-local.png)
+In Claude Desktop, open the **search and tools** menu in the chat input area. You should see Basic Memory tools listed.
 
 Ask Claude:
 
@@ -107,8 +96,6 @@ You have 1 project:
 - main (default) - ~/basic-memory - 0 notes
 ```
 
-![Claude - Project list](/screenshots/claude/project-list-response.png)
-
 ---
 
 ## 4. Create your first note
@@ -116,28 +103,26 @@ You have 1 project:
 Try this prompt:
 
 ```bash
-Create a note called "Getting Started" with a summary of what Basic Memory does.
+Create a note called "My First Note" with a summary of what Basic Memory does.
 ```
 
-Claude will create a Markdown file at `~/basic-memory/Getting Started.md`.
+Claude will create a Markdown file at `~/basic-memory/My First Note.md`.
 
 **Example conversation:**
 ```bash
-You: Create a note called "Getting Started" with a summary of what Basic Memory does.
+You: Create a note called "My First Note" with a summary of what Basic Memory does.
 
 Claude: I'll create a note for you.
 
 [Uses write_note tool]
 
-Done! I've created "Getting Started.md" in your basic-memory folder.
+Done! I've created "My First Note.md" in your basic-memory folder.
 It includes an overview of Basic Memory's key features:
 - Knowledge storage in Markdown
 - Semantic observations and relations
 - Search across your knowledge base
 ```
 
-![Claude - Creating first note](/screenshots/claude/create-first-note.png)
-
 ---
 
 ## 5. View your notes
@@ -148,7 +133,7 @@ Your notes are stored at `~/basic-memory` by default. You can:
 
 ```bash
 # View in terminal
-cat ~/basic-memory/Getting\ Started.md
+cat ~/basic-memory/My\ First\ Note.md
 
 # Open folder
 open ~/basic-memory  # macOS
@@ -167,13 +152,13 @@ After creating a few notes, your folder might look like:
 
 ```bash
 ~/basic-memory/
-├── Getting Started.md
+├── My First Note.md
 ├── projects/
 │   └── API Design.md
 ├── research/
 │   └── Database Optimization.md
 └── meetings/
-    └── Team Standup 2024-01-15.md
+    └── Team Standup 2026-06-15.md
 ```
 
 ---
@@ -226,17 +211,7 @@ basic-memory project add "my-notes" ~/Documents/notes
 basic-memory project default "my-notes"
 ```
 
-Restart Claude Desktop for changes to take effect.
-
-### Skip project selection prompts
-
-If you only use one project, add to `~/.basic-memory/config.json`:
-
-```json
-{
-  "default_project": "main"
-}
-```
+Restart Claude Desktop for changes to take effect. For more on projects and default-project configuration, see [Set Up Local Projects](/local/getting-started).
 
 ---
 
@@ -250,7 +225,7 @@ basic-memory status
 basic-memory project list
 
 # View project statistics
-basic-memory project info
+basic-memory project info main
 
 # Import Claude conversations
 basic-memory import claude conversations
@@ -258,8 +233,8 @@ basic-memory import claude conversations
 # Import ChatGPT conversations
 basic-memory import chatgpt
 
-# Force re-sync all files
-basic-memory sync
+# Rebuild the search index
+basic-memory reindex
 ```
 
 ---
diff --git a/content/2.whats-new/.navigation.yml b/content/02.whats-new/.navigation.yml
similarity index 100%
rename from content/2.whats-new/.navigation.yml
rename to content/02.whats-new/.navigation.yml
diff --git a/content/02.whats-new/0.teams.md b/content/02.whats-new/0.teams.md
new file mode 100644
index 0000000..9062653
--- /dev/null
+++ b/content/02.whats-new/0.teams.md
@@ -0,0 +1,55 @@
+---
+title: Introducing Teams
+description: One shared memory for your whole team and every AI agent they use.
+---
+
+**Basic Memory Teams** puts your whole team — and every AI agent they use — on one shared memory. A decision captured in one teammate's Claude session becomes context for another's Codex run. Invite teammates into a shared cloud workspace, work from the same projects, and everyone's agents reach the shared knowledge automatically.
+
+Teams adds a **team workspace alongside your personal one** — your own notes and projects stay where they are, and you switch between workspaces in the app whenever you want.
+
+::note{icon="i-lucide-users"}
+Teams is a cloud feature and requires a subscription with one or more seats. Billing is per seat. Your personal cloud workspace (and any local projects) keep working alongside it.
+::
+
+## What you get
+
+- **Three workspaces, side by side** — local, personal cloud, and your team's shared workspace. Switch between personal and team workspaces in the app; local projects stay on your machine, reachable from the CLI and MCP alongside them.
+- **A shared workspace for the team** — projects everyone on the team can read and write.
+- **Roles** — five levels, from read-only **viewer** to **owner**, with **editor**, **user admin**, and **admin** tiers in between.
+- **Email invitations** — invite teammates by email; a seat is only used once they accept.
+- **One source of truth for every agent** — Claude, Codex, and the rest discover team projects across every workspace you can access, with no extra setup.
+
+## Invite your team
+
+Invite members by email from **Settings → Members** — they sign in, pick up their role, and start working in the shared projects right away. Roles, statuses, and member management are covered in [Members and Roles](/teams/members-and-roles).
+
+## Get started
+
+:::card-group
+::card
+---
+title: Teams Guide
+icon: i-lucide-users
+to: /teams/about
+---
+Roles, invitations, seats, and project sharing — the full walkthrough.
+::
+
+::card
+---
+title: Web App
+icon: i-lucide-layout-panel-left
+to: /cloud/web-app
+---
+Browse, edit, and collaborate on notes in the browser.
+::
+
+::card
+---
+title: Changelog
+icon: i-lucide-megaphone
+to: /whats-new/changelog
+---
+What shipped in each release, including v0.22's team-safe cloud push and pull.
+::
+:::
diff --git a/content/02.whats-new/1.changelog.md b/content/02.whats-new/1.changelog.md
new file mode 100644
index 0000000..3272ddd
--- /dev/null
+++ b/content/02.whats-new/1.changelog.md
@@ -0,0 +1,80 @@
+---
+title: Changelog
+description: What shipped in each Basic Memory release.
+---
+
+Notable changes in each Basic Memory release, most recent first. For complete patch-by-patch notes, see [All releases](#all-releases) below.
+
+---
+
+## v0.22 — Team-safe cloud push and pull
+
+*June 2026 · [v0.22.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.22.0) · [v0.22.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.22.1)*
+
+v0.22.0 makes cloud sync safe for teams. New **`bm cloud push`** and **`bm cloud pull`** commands transfer changes additively — they never delete files on the destination — so you can collaborate on a shared team workspace without risking a teammate's work. They model `git push` / `git pull`: conflict-aware, with `--on-conflict` options (`fail`, `keep-cloud`, `keep-local`, `keep-both`) when a file differs on both sides. The mirror-style `bm cloud sync` command remains personal-only and exits with an error on team workspaces.
+
+Also in v0.22.0: search improvements, more capable `bm tool` and `bm status` commands, and a long list of MCP tool and embedding reliability fixes. See [Cloud Sync](/cloud/cloud-sync) for the full push/pull workflow.
+
+**The v0.22.1 patch** fixed first-run reliability and shipped a few MCP fixes and parity additions:
+
+- Fresh installs no longer get stuck when the projects table is empty — Basic Memory routes you to project setup and promotes your first project to the default automatically
+- Sync skips projects without a valid local path and ignores stale projects left in the database but missing from your config
+- MCP qualified project routes resolve workspace display names and tenant ids correctly
+- `search_notes` comma-splits `note_types`, `entity_types`, and `categories`, matching how tags already behave
+- `write_note` gains a `workspace` parameter for parity with `edit_note`
+- Faster CLI startup — heavy imports are deferred out of the command path
+
+---
+
+## v0.21 — Workspace-aware everywhere
+
+*May–June 2026 · [v0.21.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.0)*
+
+Every MCP tool and CLI command now routes through the same workspace/project model, and search and sync are noticeably faster.
+
+- **Cross-workspace discovery** — MCP project listing spans every accessible cloud workspace, so team projects show up without switching workspaces first, and `bm project list` includes projects from every workspace
+- **Create projects by workspace** — `create_memory_project(workspace=...)` from MCP, and `bm project add --visibility` for cloud projects
+- **Parameter aliases** — MCP tools accept training-data-friendly aliases (`q` / `search` / `text` for `query`, etc.) so assistants reach for them naturally
+- **`bm orphans`** — lists entities with no incoming or outgoing relations in the knowledge graph — notes not yet linked to anything
+- **Breaking change** — unquoted multi-word text before a wikilink no longer parses as a custom relation type. Use single-token types like `relates_to [[Target]]`, or quote multi-word types: `"relates to" [[Target]]`
+
+Notable patches: v0.21.5 fixed workspace/project routing for MCP, and v0.21.6 consolidated the satellite repositories into the main `basic-memory` tree and shipped a redesigned Claude Code plugin — a memory bridge with a guided setup interview, capture skills, and team workspace support — alongside Codex, Hermes, and OpenClaw integration packages.
+
+---
+
+## v0.20 — Auto-update
+
+*March 2026 · [v0.20.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.20.0)*
+
+A default-on auto-update system keeps CLI installs current, with a new **`bm update`** command (`--check` to check only). Install-source detection handles Homebrew and uv tool installs with the right upgrade flow for each, and MCP servers check silently in the background. Patches fixed API-key authentication for CLI cloud commands (previously only OAuth worked) and Homebrew update detection.
+
+---
+
+## v0.19 — Semantic search and schemas
+
+*March 2026 · [v0.19.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.19.0)*
+
+The biggest release of the docs era:
+
+- **Semantic vector search** for SQLite and Postgres with FastEmbed embeddings and hybrid keyword + vector fusion
+- **Schema system** — `schema_infer`, `schema_validate`, and `schema_diff` for validating and evolving note structure
+- **Per-project cloud routing** with API key authentication — route individual projects through cloud while others stay local
+- **JSON output mode** for MCP tools and CLI commands
+- **Project-prefixed permalinks** for unambiguous cross-project references
+- **`write_note` overwrite guard** — writing to an existing path returns an error unless `overwrite=true`
+- Upgraded to FastMCP 3.0 with tool annotations
+
+Upgrading from v0.18? The [v0.19.0 release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.19.0) cover the configuration and behavior changes.
+
+---
+
+## All releases
+
+Full release notes for every version, from [GitHub](https://github.com/basicmachines-co/basic-memory/releases):
+
+::github-releases
+---
+repo: basicmachines-co/basic-memory
+limit: 30
+---
+::
diff --git a/content/2.whats-new/3.hermes-plugin.md b/content/02.whats-new/3.hermes-plugin.md
similarity index 77%
rename from content/2.whats-new/3.hermes-plugin.md
rename to content/02.whats-new/3.hermes-plugin.md
index 775f939..b557a81 100644
--- a/content/2.whats-new/3.hermes-plugin.md
+++ b/content/02.whats-new/3.hermes-plugin.md
@@ -3,7 +3,7 @@ title: Hermes Plugin
 description: Give Hermes Agent persistent Basic Memory — search-before-answer recall, auto-capture, and 10 agent tools.
 ---
 
-The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memory) plugin gives [Hermes Agent](https://github.com/NousResearch/hermes-agent) a persistent knowledge graph across sessions.
+The [hermes-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes) plugin gives [Hermes Agent](https://github.com/NousResearch/hermes-agent) a persistent knowledge graph across sessions.
 
 [Basic Memory](/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. Hermes ships with no external memory provider by default — this plugin replaces that with a real graph your agent reads from and writes to as plain Markdown.
 
@@ -23,7 +23,7 @@ The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memor
 ## Quick Install
 
 ```bash
-hermes plugins install basicmachines-co/hermes-basic-memory
+hermes plugins install basicmachines-co/basic-memory --path integrations/hermes
 ```
 
 Activate it in `~/.hermes/config.yaml`:
@@ -36,7 +36,7 @@ memory:
 Restart the gateway (`hermes gateway restart`) and verify with `hermes memory status`.
 
 ::note
-The agent tools and auto-capture work out of the box. The native `/bm-*` slash commands need a Hermes Agent-side patch on releases through `v0.14.0` / `v2026.5.16` — see the warning in the full guide.
+The agent tools and auto-capture work out of the box. The native `/bm-*` slash commands need a Hermes Agent-side patch on current Hermes Agent releases — see the warning in the [full guide](/integrations/hermes).
 ::
 
 ## Next Steps
@@ -53,9 +53,9 @@ Full guide with configuration, tool reference, slash commands, and the slash-com
 
 ::card
 ---
-title: GitHub Repository
+title: Plugin on GitHub
 icon: i-lucide-github
-to: https://github.com/basicmachines-co/hermes-basic-memory
+to: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes
 ---
 Source code, issues, and contributing guide.
 ::
diff --git a/content/2.whats-new/4.cloud.md b/content/02.whats-new/4.cloud.md
similarity index 74%
rename from content/2.whats-new/4.cloud.md
rename to content/02.whats-new/4.cloud.md
index f22e77d..dcbedb2 100644
--- a/content/2.whats-new/4.cloud.md
+++ b/content/02.whats-new/4.cloud.md
@@ -1,5 +1,5 @@
 ---
-title: Basic Memory Cloud
+title: Cloud App Updates
 description: Cloud UI updates and new features.
 ---
 
@@ -10,7 +10,7 @@ Work with your knowledge base across multiple devices using cloud sync and stora
 The Basic Memory web app has been rebuilt around a fast, three-pane layout (sidebar, note list, note detail) where notes open ready to edit.
 
 - **Three editing modes** — a **Rich editor** for WYSIWYG writing, a **Source mode** for plain Markdown and frontmatter, and a **Preview** with clickable wiki links.
-- **See all your Projects at once** - see all your projects at once in the **Projects** list.
+- **Projects at a glance** — browse and manage every project in your workspace from the **Projects** list.
 - **Share notes** — create a public, read-only link for any saved note.
 - **Keyboard-first** — a command palette (Cmd/Ctrl + K) and shortcuts for everything.
 - **Live updates** — see changes made by your agent in real time, and save your own changes instantly.
@@ -19,7 +19,7 @@ For the full walkthrough, see the [Web App Guide](/cloud/web-app).
 
 ## Teams
 
-You can now share a cloud workspace with your team. Invite members by email, assign roles (owner, editor, viewer), and collaborate on the same projects — your AI assistant reaches team projects automatically across workspaces.
+You can now share a cloud workspace with your team. Invite members by email, assign roles, and collaborate on the same projects — your AI assistant reaches team projects automatically across workspaces.
 
 See the [Teams guide](/teams/about) to get started.
 
@@ -35,7 +35,7 @@ Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Cre
 
 ## File History
 
-Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note to see its full timeline, compare an earlier version side-by-side with the current one, and apply changes back into the live note. It's the fast, per-note answer to "I want to undo something" — distinct from [Snapshots](/cloud/cloud-snapshots), which are project-wide point-in-time backups.
+Every save now creates a new version of a note automatically. Open **File history** on any note to step through its timeline, compare versions, and bring earlier content back — the fast, per-note answer to "I want to undo something," distinct from workspace-wide [Snapshots](/cloud/cloud-snapshots). See [File History](/cloud/file-history).
 
 ## Next Steps
 
diff --git a/content/2.whats-new/6.agent-skills.md b/content/02.whats-new/6.agent-skills.md
similarity index 58%
rename from content/2.whats-new/6.agent-skills.md
rename to content/02.whats-new/6.agent-skills.md
index 4ceab50..97520bc 100644
--- a/content/2.whats-new/6.agent-skills.md
+++ b/content/02.whats-new/6.agent-skills.md
@@ -7,33 +7,24 @@ AI assistants are powerful, but they don't automatically know the best way to or
 
 [Basic Memory](/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. Skills make the AI better at using it — so your notes are more consistent, your tasks are tracked reliably, and your conversations produce lasting value.
 
-## Available Skills
+## Skill highlights
 
 | Skill | What it does for you |
 |-------|---------------------|
 | **memory-notes** | Your AI writes well-structured notes automatically — with consistent formatting, links between notes, and proper metadata |
 | **memory-tasks** | Track tasks in notes that survive across conversations — your AI picks up where you left off |
-| **memory-schema** | Your AI learns your note patterns and helps keep them consistent over time |
+| **memory-continue** | Resume prior work — your AI rebuilds context from the knowledge graph |
 | **memory-reflect** | Your AI reviews conversations and saves the important parts as notes |
-| **memory-defrag** | Split bloated files, merge duplicates, and reorganize your notes |
-| **memory-lifecycle** | Move notes through stages (draft → active → archive) using folders |
-| **memory-metadata-search** | Your AI searches notes by properties like status, tags, and custom fields |
-| **memory-ingest** | Process transcripts, emails, and documents into structured notes |
-| **memory-research** | Your AI researches topics on the web and saves findings as notes |
 
-## Quick Install
+…plus skills for capture, curation, schemas, defrag, metadata search, research, and more — see the full list on the [Agent Skills guide](/integrations/skills).
 
-```bash
-npx skills add basicmachines-co/basic-memory-skills
-```
-
-Or install a single skill:
+## Quick Install
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks
+npx skills add basicmachines-co/basic-memory/skills
 ```
 
-Works with Claude Desktop, Claude Code, Cursor, Windsurf, and other AI tools that support markdown-based skill files.
+Works with Claude Desktop, Claude Code, Cursor, Windsurf, and other AI tools that support markdown-based skill files. Installation options, per-agent targeting, and usage examples are on the [Agent Skills guide](/integrations/skills).
 
 ## Next Steps
 
@@ -49,10 +40,10 @@ Full guide with installation options, skill details, and recommended combination
 
 ::card
 ---
-title: GitHub Repository
+title: Skills on GitHub
 icon: i-lucide-github
-to: https://github.com/basicmachines-co/basic-memory-skills
+to: https://github.com/basicmachines-co/basic-memory/tree/main/skills
 ---
-Source code, contributing guide, and issue tracker.
+Source, contributing guide, and issue tracker in the basic-memory monorepo.
 ::
 :::
diff --git a/content/2.whats-new/7.openclaw-plugin.md b/content/02.whats-new/7.openclaw-plugin.md
similarity index 69%
rename from content/2.whats-new/7.openclaw-plugin.md
rename to content/02.whats-new/7.openclaw-plugin.md
index 31cec03..6bd9bae 100644
--- a/content/2.whats-new/7.openclaw-plugin.md
+++ b/content/02.whats-new/7.openclaw-plugin.md
@@ -3,7 +3,7 @@ title: OpenClaw Plugin
 description: Give OpenClaw agents persistent Basic Memory with search, auto-capture, and bundled skills.
 ---
 
-The [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-memory) plugin gives your OpenClaw agent a persistent memory across sessions — zero configuration required.
+The [openclaw-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw) plugin gives your OpenClaw agent a persistent memory across sessions — zero configuration required.
 
 [Basic Memory](/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. This plugin connects it to OpenClaw so your agent remembers past conversations, decisions, and context.
 
@@ -16,15 +16,16 @@ The [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-m
 - **Search across everything** — Searches your notes, knowledge graph, and active tasks at once
 - **Automatically saves conversation highlights** — Records important conversation turns as daily notes
 - **Loads your recent work at startup** — Active tasks and recent notes are ready when you begin a new session
-- **14 agent tools** — Full Basic Memory toolset including search, read, write, edit, schema, and project management
-- **7 slash commands** — `/remember`, `/recall`, `/tasks`, `/reflect`, `/defrag`, `/schema`, `/bm-setup`
-- **6 bundled skills** — memory-notes, memory-tasks, memory-schema, memory-reflect, memory-defrag, memory-metadata-search
+- **Agent tools** — search, read, write, edit, schema validation, and project/workspace listing
+- **Slash commands** — `/remember`, `/recall`, `/tasks`, and more, plus one command per bundled skill
+- **Bundled skills** — workflow skills for notes, tasks, schemas, reflection, defrag, and more — no separate install needed
 - **Multi-project & cloud routing** — Access every project in your knowledge base with transparent local/cloud routing
 
 ## Quick Install
 
 ```bash
 openclaw plugins install @basicmemory/openclaw-basic-memory
+openclaw plugins enable openclaw-basic-memory --slot memory
 openclaw gateway restart
 ```
 
@@ -44,9 +45,9 @@ Full guide with configuration options, tool reference, and slash commands.
 
 ::card
 ---
-title: GitHub Repository
+title: Plugin on GitHub
 icon: i-lucide-github
-to: https://github.com/basicmachines-co/openclaw-basic-memory
+to: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw
 ---
 Source code, issues, and contributing guide.
 ::
diff --git a/content/2.whats-new/8.ai-friendly-docs.md b/content/02.whats-new/8.ai-friendly-docs.md
similarity index 51%
rename from content/2.whats-new/8.ai-friendly-docs.md
rename to content/02.whats-new/8.ai-friendly-docs.md
index 42ef0dd..f2c18ef 100644
--- a/content/2.whats-new/8.ai-friendly-docs.md
+++ b/content/02.whats-new/8.ai-friendly-docs.md
@@ -1,5 +1,5 @@
 ---
-title: AI-Friendly Documentation
+title: AI-Friendly Docs
 description: Access Basic Memory docs as clean markdown for AI agents using llms.txt and content negotiation.
 ---
 
@@ -13,27 +13,7 @@ Ask your AI to read the docs and it just works:
 Fetch https://docs.basicmemory.com/llms.txt and read the Basic Memory documentation
 ```
 
-## Access Methods
-
-| Method | URL | What you get |
-|--------|-----|--------------|
-| **Index** | `/llms.txt` | List of all pages with direct markdown links |
-| **Full docs** | `/llms-full.txt` | Complete documentation in one file |
-| **Raw markdown** | `/raw/<path>.md` | Any single page as markdown |
-| **Content negotiation** | Any page + `Accept: text/markdown` | Returns markdown instead of HTML |
-
-## Quick Examples
-
-```bash
-# Get the full docs index
-curl https://docs.basicmemory.com/llms.txt
-
-# Fetch a specific page as markdown
-curl https://docs.basicmemory.com/raw/start-here/what-is-basic-memory.md
-
-# Content negotiation — same URL, markdown response
-curl -H "Accept: text/markdown" https://docs.basicmemory.com/start-here/what-is-basic-memory
-```
+Every page is available as an `/llms.txt` index, a single-file `/llms-full.txt`, raw per-page markdown, and via content negotiation — the full details, URLs, and examples live on the [AI-Friendly Docs reference](/reference/llms-txt).
 
 ## Next Steps
 
diff --git a/content/3.cloud/.navigation.yml b/content/03.cloud/.navigation.yml
similarity index 100%
rename from content/3.cloud/.navigation.yml
rename to content/03.cloud/.navigation.yml
diff --git a/content/3.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md
similarity index 53%
rename from content/3.cloud/01.cloud-guide.md
rename to content/03.cloud/01.cloud-guide.md
index 0438ed9..c555818 100644
--- a/content/3.cloud/01.cloud-guide.md
+++ b/content/03.cloud/01.cloud-guide.md
@@ -24,33 +24,7 @@ Basic Memory Cloud uses Remote MCP to connect to AI assistants. The connection U
 https://cloud.basicmemory.com/mcp
 ```
 
-::steps
-### Open Claude Settings
-
-In Claude Web or Desktop, go to **Settings → Claude → Connectors**
-
-### Add Custom Connector
-
-Click **Add custom connector** and enter:
-- **Name**: Basic Memory
-- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
-
-Click **Add**
-
-### Authenticate
-
-Click **Connect** to authenticate and grant permissions to Claude.
-
-This opens an OAuth flow to authorize Claude to access your Basic Memory Cloud account.
-
-### Configure Tools (Optional)
-
-Click **Configure** to customize which tools are enabled. You can enable or disable specific tools and configure permissions.
-
-### Verify Setup
-
-Confirm Basic Memory is available in the "search and tools" menu for a chat. All your notes will be saved to your cloud instance.
-::
+In Claude Web or Desktop, add a custom connector under **Settings → Claude → Connectors** with that URL, then click **Connect** and complete the OAuth flow. Your notes save to your cloud instance.
 
 ::tip
 For detailed Claude setup instructions, see the [Claude Desktop Integration](/integrations/claude-desktop) guide.
@@ -61,7 +35,7 @@ For detailed Claude setup instructions, see the [Claude Desktop Integration](/in
 ## Setup with ChatGPT
 
 ::note
-ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers.
+ChatGPT requires a **Plus or Pro subscription** to use remote MCP servers.
 ::
 
 For detailed ChatGPT setup instructions, see the [ChatGPT Integration](/integrations/chatgpt) guide.
@@ -75,9 +49,9 @@ Browse, edit, and collaborate on your cloud notes directly in your browser at [a
 **Key features:**
 - **Edit notes** - A rich editor, plain Markdown source mode, and a read-only preview with clickable wiki links
 - **Collaborate with AI** - Connect an agent and watch it write alongside you in the same note
-- **Import conversations** - Import ChatGPT, Claude, or JSON data
+- **Import data** - Bring in project ZIPs, Claude or ChatGPT exports, or memory-json from **Settings → Import**
 - **Manage projects** - Create, switch between, and manage projects
-- **Upload files** - Bulk upload markdown files and directories
+- **Upload folders as ZIP** - Zip a folder and import it into any writable project — no CLI needed
 - **Download archives** - Export projects as zip files for backup
 
 ::tip
@@ -88,133 +62,53 @@ For the complete web app guide including editing modes, drafts, AI collaboration
 
 ## Command Line Tools
 
-The CLI tools are **optional** but enable advanced features like project management, file upload, and bidirectional sync.
+The CLI tools are **optional** but enable advanced features like project management, file upload, and local file sync.
 
-**Requirements**: Basic Memory CLI v0.16.0 or later. See [Getting Started](/start-here/getting-started) for installation.
+**Requirements**: an up-to-date Basic Memory CLI (`bm update`). See [Local Installation](/local/local-install) for installation.
 
 ::note{icon="i-lucide-info"}
 **Why use the CLI?**
 - Manage multiple projects from terminal
 - Upload entire folders to cloud
-- Set up bidirectional sync with local files
+- Sync local files with push and pull
 - Automate workflows with scripts
 ::
 
 ### Quick Start
 
 ```bash
-# 1. Authenticate
+# Authenticate — OAuth in the browser, validates your subscription
 bm cloud login
 
-# 2. Check Status
+# Check the connection: cloud host, API key status, OAuth token status
 bm cloud status
 
-# 3. List Projects
+# List projects across your workspaces
 bm project list
-```
-
-### Authentication
-
-Basic Memory uses JWT-based cloud authentication with OAuth 2.1 and automatic subscription validation.
-
-#### Login to Cloud
-
-```bash
-bm cloud login
-```
-
-**What happens:**
-1. Opens browser to OAuth authorization page
-2. Handles PKCE challenge/response automatically
-3. Validates active subscription status
-4. Stores JWT token in `~/.basic-memory/basic-memory-cloud.json`
-5. Token automatically refreshed when needed
-
-A confirmation code will be displayed in both the browser and terminal. Confirm the codes match and press the **Confirm** button on the web page.
-
-After login:
-```
-✅ Successfully authenticated with Basic Memory Cloud!
-Verifying subscription access...
-✓ Cloud mode enabled
-CLI commands use cloud routing unless a project is explicitly set to local mode
-✓ Tokens saved to ~/.basic-memory/basic-memory-cloud.json
-```
-
-### Per-project Cloud Routing
-
-You can route specific projects through cloud while keeping others local:
-
-```bash
-# Save or create an API key
-bm cloud api-key save bmc_...
-bm cloud api-key create "my-laptop"
 
-# Route one project through cloud
-bm project set-cloud research
-
-# Revert to local for that project
-bm project set-local research
-```
-
-::tip
-For the full routing model — including priority levels, hybrid setups, and common configurations — see [Local & Cloud Routing](/cloud/routing).
-::
-
-**If no subscription:**
-```
-Active subscription required
-Subscribe at: https://basicmemory.com/subscribe
+# Create a cloud project (--cloud is required; add --default to make it the default)
+bm project add my-new-project --cloud
 ```
 
-#### Check Status
+`bm cloud login` authenticates the CLI — it does **not** change project routing or start syncing files. Projects stay local unless you route them through cloud with `bm project set-cloud <name>`; revert with `bm project set-local <name> --local-path <path>`. See [Local & Cloud Routing](/cloud/routing) for the full routing model.
 
-```bash
-bm cloud status
-```
-
-Shows: authentication status, subscription status, last sync time, cloud project count, tenant information, and sync directory configuration.
-
-#### Logout
-
-```bash
-bm cloud logout
-```
+If you log in without an active subscription, you'll see **"Active subscription required"** — subscribe at [basicmemory.com/subscribe](https://basicmemory.com/subscribe?utm_source=docs&utm_medium=docs&utm_campaign=cloud-guide).
 
-Removes `~/.basic-memory/basic-memory-cloud.json` and clears cached credentials.
-
-### Project Management
-
-```bash
-# Create a new cloud project
-bm project add my-new-project
-
-# Create and set as default
-bm project add my-new-project --default
-
-# List all cloud projects
-bm project list
-```
-
-Example output:
-```
-           Basic Memory Projects
-┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
-┃ Name ┃ Path                   ┃ Default ┃
-┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
-│ main │ /app/data/basic-memory │ ✓       │
-└──────┴────────────────────────┴─────────┘
-```
+`bm cloud logout` removes your OAuth tokens. A saved API key is **not** removed — it keeps working for cloud-routed projects, so delete it separately if you need to revoke access.
 
 ::tip
-For more project management commands, see `bm project --help` or the [CLI Reference](/reference/cli-reference).
+The full command walkthrough — sign-in options, API keys, workspaces, routing, sync, and snapshots — lives on the [Cloud CLI](/cloud/cloud-cli) page.
 ::
 
 ---
 
 ## Upload Files to Cloud
 
-Upload local files or directories to cloud projects using `bm cloud upload`:
+::note{icon="i-lucide-upload"}
+**No CLI needed for one-off uploads.** In the web app, **Settings → Import → Project ZIP** imports a zipped folder into any writable project — pick the team and target project, optionally a destination folder, and upload (ZIPs up to 100MB; markdown files are indexed automatically). The **Activity** view tracks the job after it starts.
+::
+
+For scripted or repeated uploads, use `bm cloud upload` from the CLI:
 
 ```bash
 # Upload a directory to existing project
@@ -251,7 +145,7 @@ bm project list
 After sync completes, the notes are available in the [web app](https://app.basicmemory.com) and for AI conversations.
 
 ::tip
-For bidirectional sync (editing both locally and in cloud), see the [Cloud Sync Guide](/cloud/cloud-sync).
+To edit both locally and in cloud, sync with push/pull — see the [Cloud Sync Guide](/cloud/cloud-sync).
 ::
 
 ---
@@ -273,8 +167,11 @@ bm cloud snapshot create "Before reorganization"
 # List all snapshots
 bm cloud snapshot list
 
-# Browse and restore files
-bm cloud snapshot browse snap_abc123
+# Browse snapshot contents
+bm cloud snapshot browse snap_abc123 --prefix notes/
+
+# Restore a file from a snapshot
+bm cloud restore notes/example.md --snapshot snap_abc123
 ```
 
 ::tip
@@ -299,12 +196,14 @@ bm cloud login
 bm cloud upload ~/basic-memory --project main --create-project
 ```
 
+Prefer the browser? Zip your `~/basic-memory` folder and import it via **Settings → Import → Project ZIP** — no CLI required.
+
 **Use when:**
 - You want to move to cloud-only
 - One-time migration is sufficient
 - Don't need ongoing local-cloud sync
 
-### Option 2: Bidirectional Sync (Hybrid Workflow)
+### Option 2: Local File Sync (Hybrid Workflow)
 
 Set up sync to work both locally and in cloud:
 
@@ -313,21 +212,22 @@ Set up sync to work both locally and in cloud:
 bm cloud login
 bm cloud setup
 
-# Add existing project with sync enabled
-bm project add main --local-path ~/basic-memory
+# Add your existing project as a cloud project with a local sync path
+bm project add main --cloud --local-path ~/basic-memory
 
-# Initial sync (resync creates baseline)
-bm cloud bisync --name main --resync --dry-run  # preview first
-bm cloud bisync --name main --resync             # establish baseline
+# First push (preview, then upload your local files)
+bm cloud push --name main --dry-run
+bm cloud push --name main
 
-# Ongoing sync (run after local or cloud changes)
-bm cloud bisync --name main
+# Ongoing: pull cloud changes down, push local changes up
+bm cloud pull --name main
+bm cloud push --name main
 ```
 
 **Use when:**
 - You want to edit both locally (Obsidian, VS Code) and in cloud
 - Need offline access
-- Want automatic bidirectional sync
+- Want changes to flow both ways
 
 ::note{icon="i-lucide-info"}
 Both methods preserve all your notes, relations, and tags. Choose based on whether you want cloud-only or hybrid local+cloud workflow. See the [Cloud Sync Guide](/cloud/cloud-sync) for detailed sync configuration.
@@ -357,7 +257,7 @@ title: Cloud Sync Guide
 icon: i-lucide-refresh-cw
 to: /cloud/cloud-sync
 ---
-Set up bidirectional sync for local editing.
+Sync local files with push and pull.
 ::
 
 ::card
diff --git a/content/03.cloud/02.web-app.md b/content/03.cloud/02.web-app.md
new file mode 100644
index 0000000..ea6156a
--- /dev/null
+++ b/content/03.cloud/02.web-app.md
@@ -0,0 +1,219 @@
+---
+title: Web App
+description: The Basic Memory Cloud web app — layout, navigation, projects, import, and settings.
+---
+
+The Basic Memory web app at [app.basicmemory.com](https://app.basicmemory.com) is a full-featured interface for working with your knowledge base. Notes open ready to edit, your AI assistant can join you live, and everything is saved as plain Markdown. Anything your AI assistant can do, you can do here too.
+
+::theme-image{light="/screenshots/cloud-app/v2-overview-light.png" dark="/screenshots/cloud-app/v2-overview-dark.png" alt="Web App Overview"}
+::
+
+This page is the tour of the app itself. Writing and shortcuts live on the [Note Editor](/cloud/note-editor) page; working with agents lives on [AI Collaboration](/cloud/ai-collaboration).
+
+---
+
+## Layout
+
+The app is organized into three panes:
+
+| Pane | Contents |
+|------|----------|
+| **Sidebar** | Pinned notes, your workspaces (personal and teams) with their project trees, search, Graph and Activity, your account menu |
+| **Note list** | Notes in the current folder or project, grouped by date |
+| **Note detail** | The selected note, opened ready to edit |
+
+Click a folder in the sidebar to filter the note list. Select a note to open it in the detail pane.
+
+---
+
+## Navigating notes
+
+### Browse by folder
+
+Expand folders in the sidebar to navigate your project structure. Click a folder to filter the note list to that location.
+
+### Filter with tabs
+
+Switch between views above the note list:
+
+| Tab | Shows |
+|-----|-------|
+| **All** | Every note in the current folder/project |
+| **Pinned** | Notes you've pinned for quick access |
+
+### Search notes
+
+Open search from the sidebar (or **Cmd/Ctrl + K**) to search by title or content. Search spans **all your projects** by default — use the scope controls to narrow to a workspace, project, or folder.
+
+::theme-image{light="/screenshots/cloud-app/v2-search-light.png" dark="/screenshots/cloud-app/v2-search-dark.png" alt="Search notes"}
+::
+
+### Pin important notes
+
+Open a note's `⋮` menu (or use the command palette) and choose **Pin Note**. Pinned notes appear in the Pinned tab.
+
+---
+
+## Activity
+
+The **Activity** view in the sidebar keeps you aware of what's happening across the workspace — operations in progress (imports, indexing, large edits) and recent completed changes from every member **and connected agent**, with direct links to the affected notes. When your assistant writes a note over MCP, it shows up here live.
+
+---
+
+## Explore the graph
+
+Open **Graph** in the sidebar for the Knowledge Graph, then pick a view: **Project** (cards), **Structured**, or **Explore** — a 2D/3D rendering of your knowledge graph, notes as nodes, relations as links. Drag to orbit, scroll to zoom, click a node to open the note, and filter by relation type or search for a note to focus on.
+
+---
+
+## Projects
+
+Projects are top-level containers. Each has its own folder tree, notes, and sync configuration.
+
+### Switch projects
+
+Use the project selector in the sidebar to switch between projects.
+
+### Manage projects
+
+Go to **Settings → Projects** to create new projects, download a project as a ZIP, or delete a project. To upload files, use **Upload Notes** from a project or folder's context menu in the sidebar, or import a zipped folder via **Settings → Import → Project ZIP**.
+
+::theme-image{light="/screenshots/cloud-app/v2-manage-projects-light.png" dark="/screenshots/cloud-app/v2-manage-projects-dark.png" alt="Manage projects"}
+::
+
+::tip
+Upload entire folders and folder trees via the [command line tools](/cloud/cloud-guide#command-line-tools) — directory structure is preserved.
+::
+
+---
+
+## Import data
+
+Bring existing content into a writable project from **Settings → Import** — pick the team, target project, and an optional destination folder.
+
+| Import type | File |
+|-------------|------|
+| **Project ZIP** | A ZIP of a folder of Markdown files — directory structure is preserved (up to 100MB) |
+| **Claude** | `conversations.json` from a Claude export |
+| **ChatGPT** | The conversations JSON from a ChatGPT export (extract it from ChatGPT's export ZIP) |
+| **memory-json** | Entity/relation JSON exported from the memory-json MCP server |
+
+1. Go to **Settings → Import**
+2. Select the import type
+3. Choose a target project (or use the default)
+4. Set a destination folder (default: `imports`)
+5. Upload your file and start the import
+
+::theme-image{light="/screenshots/cloud-app/v2-import-light.png" dark="/screenshots/cloud-app/v2-import-dark.png" alt="Import data"}
+::
+
+::note
+Imported conversations are converted to Basic Memory's knowledge format automatically.
+::
+
+---
+
+## Snapshots
+
+Create point-in-time backups of your cloud data from **Settings → Snapshots** (select a workspace first). Use them before major changes like bulk imports or reorganizations.
+
+::tip
+For complete snapshot management including creating, browsing, and restoring snapshots, see the [Cloud Snapshots Guide](/cloud/cloud-snapshots).
+::
+
+---
+
+## Settings
+
+Access settings from the user menu (your avatar at the bottom of the sidebar) or the command palette.
+
+::theme-image{light="/screenshots/cloud-app/v2-settings-light.png" dark="/screenshots/cloud-app/v2-settings-dark.png" alt="Settings"}
+::
+
+| Section | What it does |
+|---------|--------------|
+| **General** | Account and profile settings, Look & Feel (mode, theme, note list), and editor preferences |
+| **Teams** | Your [teams and workspaces](/teams/about) at a glance |
+| **Members** | Invite and manage [team members, roles, and invitations](/teams/members-and-roles) |
+| **Billing** | Manage payment and [subscription seats](/teams/seats-and-billing) |
+| **Projects** | Create, download, and delete projects (team downloads require User Admin or above) |
+| **Import** | Import project ZIPs, Claude/ChatGPT exports, or memory-json |
+| **MCP** | Connect AI assistants via MCP |
+| **Notifications** | Choose what the app notifies you about |
+| **API Keys** | Create and manage [API keys](/cloud/api-keys) for programmatic access |
+| **Snapshots** | Manage [point-in-time backups](/cloud/cloud-snapshots) per workspace |
+| **Audit Logs** | Review workspace activity (team admins) |
+| **Shared Notes** | Manage public [share links](/cloud/shared-notes) for your notes |
+| **Version** | App version information |
+
+::note
+Sections like **Members**, **Billing**, **Snapshots**, and **Audit Logs** appear based on your workspace and role. See [Teams](/teams/about) for collaboration features.
+::
+
+You can also customize appearance — see [Themes](/cloud/themes).
+
+---
+
+## Tips for Effective Use
+
+### Organize with folders
+
+Create a folder structure inside each project that matches how you think:
+
+```bash
+my-project/
+├── research/       # Learning and exploration
+├── decisions/      # Decision records
+├── meetings/       # Meeting notes
+└── archive/        # Completed/old content
+```
+
+### Use pinned notes
+
+Pin your most-accessed notes (project overviews, quick references) for one-click access.
+
+### Create snapshots before big changes
+
+Before reorganizing folders, bulk importing, or deleting lots of notes, create a manual snapshot.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Note Editor
+icon: i-lucide-pencil
+to: /cloud/note-editor
+---
+Editing modes, formatting, drafts, and keyboard shortcuts.
+::
+
+::card
+---
+title: AI Collaboration
+icon: i-lucide-sparkles
+to: /cloud/ai-collaboration
+---
+Connect an agent and watch it write alongside you.
+::
+
+::card
+---
+title: Teams
+icon: i-lucide-users
+to: /teams/about
+---
+Share a workspace and collaborate with your team.
+::
+
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Sync local files with push and pull to edit locally and in cloud.
+::
+:::
diff --git a/content/03.cloud/03.note-editor.md b/content/03.cloud/03.note-editor.md
new file mode 100644
index 0000000..777a0c3
--- /dev/null
+++ b/content/03.cloud/03.note-editor.md
@@ -0,0 +1,189 @@
+---
+title: Note Editor
+description: Editing modes, markdown formatting, frontmatter, drafts, note management, and keyboard shortcuts in the web app.
+---
+
+Notes in the [web app](/cloud/web-app) open ready to edit, and everything you write is saved as plain Markdown.
+
+---
+
+## Editing modes
+
+The app has three modes, switchable from the toolbar or with keyboard shortcuts:
+
+| Mode | Shortcut | Description |
+|------|----------|-------------|
+| **Rich editor** | Cmd/Ctrl + Shift + I | WYSIWYG editing — type and format directly, with tables, code blocks, callouts, and task lists |
+| **Source mode** | Cmd/Ctrl + Shift + R | Plain Markdown editing with full frontmatter visible — for power users |
+| **Preview** | Cmd/Ctrl + Shift + P | Read-only rendered view with clickable `[[wiki links]]` for navigating your knowledge graph |
+
+::theme-image{light="/screenshots/cloud-app/v2-edit-mode-light.png" dark="/screenshots/cloud-app/v2-edit-mode-dark.png" alt="Rich editor mode"}
+::
+
+And here's the same note in **Preview** mode, with clickable wiki links:
+
+::theme-image{light="/screenshots/cloud-app/v2-edit-preview-light.png" dark="/screenshots/cloud-app/v2-edit-preview-dark.png" alt="Preview mode"}
+::
+
+::tip
+Press **Cmd/Ctrl + Option + Z** to toggle Zen mode — a distraction-free full-screen editor. Press **Escape** to drop back to Preview from the editor.
+::
+
+### Markdown formatting
+
+The rich editor supports full Markdown including:
+- Headers, bold, italic, inline code
+- Code blocks with syntax highlighting
+- Tables
+- Links and images
+- Task lists (`- [ ]` and `- [x]`)
+- Basic Memory semantic syntax (observations, relations)
+
+Press **Cmd/Ctrl + /** to see all formatting shortcuts.
+
+### Edit frontmatter
+
+Open the **Frontmatter** panel from the toolbar (or the command palette) to edit a note's YAML metadata separately from its content.
+
+::theme-image{light="/screenshots/cloud-app/v2-frontmatter-light.png" dark="/screenshots/cloud-app/v2-frontmatter-dark.png" alt="Edit Frontmatter"}
+::
+
+---
+
+## Drafts
+
+Start typing in an empty editor — or press **Cmd/Ctrl + N** for a new note — to create a **draft**.
+
+- A new draft saves into the current project automatically once it has meaningful content (a title, tags, or body text).
+- Use **Save Draft** in the command palette to save immediately without waiting.
+- Once saved, the note syncs like any other and is available to your AI assistant.
+
+::note
+Saved notes are written automatically as you edit. Status dots tell you the state: unsaved, saving, or draft — no dot means saved.
+::
+
+---
+
+## Creating and managing notes
+
+### Create a note
+
+- Start typing in an empty editor, or
+- Press **Cmd/Ctrl + N**, or
+- Open the command palette (**Cmd/Ctrl + K**) → **New Note**
+
+::theme-image{light="/screenshots/cloud-app/v2-new-note-light.png" dark="/screenshots/cloud-app/v2-new-note-dark.png" alt="New note"}
+::
+
+### Move notes
+
+- Use a note's `⋮` menu → **Move** to relocate it to another folder, or
+- Drag the note card from the list onto the desired folder, or
+- Drag a folder in the tree to move an entire directory.
+
+### Delete notes
+
+Open a note's `⋮` menu → **Delete**.
+
+::warning
+Deletion is permanent. Create a snapshot before bulk deletions if you want the ability to restore.
+::
+
+### Copy permalink and rename
+
+From a note's `⋮` menu you can **Rename Note** and **Copy link for your agent**; the command palette also offers **Copy Permalink**.
+
+### Share a note
+
+From a note's `⋮` menu, choose **Share note** to create a public, read-only link anyone can open without an account. See [Shared Notes](/cloud/shared-notes).
+
+### See a note's history
+
+Every save creates a new version. Click the **File history** icon (clock) in a note's toolbar to browse the timeline, compare any earlier version against the current one, and merge old content back in. See [File History](/cloud/file-history).
+
+---
+
+## Keyboard Shortcuts
+
+The web app is designed for keyboard-first navigation. Press **Cmd/Ctrl + /** to see the full list in the app.
+
+### Command palette
+
+Press **Cmd/Ctrl + K** to open the command palette and search for any action — navigate to notes, settings, the graph, or projects; create a new note; switch view modes; change theme; or run note and editor actions.
+
+::theme-image{light="/screenshots/cloud-app/v2-command-light.png" dark="/screenshots/cloud-app/v2-command-dark.png" alt="Command palette"}
+::
+
+### Formatting
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd/Ctrl + B** | Bold |
+| **Cmd/Ctrl + I** | Italic |
+| **Cmd/Ctrl + E** | Inline code |
+| **Cmd/Ctrl + Option + 1** | Heading 1 |
+| **Cmd/Ctrl + Option + 2** | Heading 2 |
+| **Cmd/Ctrl + Option + 3** | Heading 3 |
+| **Cmd/Ctrl + D** | Task checkbox |
+
+### Structure
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd/Ctrl + ]** | Indent list |
+| **Cmd/Ctrl + [** | Outdent list |
+
+### View
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd/Ctrl + Shift + I** | Rich editor |
+| **Cmd/Ctrl + Shift + P** | Preview |
+| **Cmd/Ctrl + Shift + R** | Source mode |
+| **Escape** | Preview from editor |
+
+### Global
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd/Ctrl + K** | Commands |
+| **Cmd/Ctrl + N** | New note |
+| **Cmd/Ctrl + Option + E** | Focus editor |
+| **Cmd/Ctrl + Option + Z** | Toggle Zen mode |
+| **Cmd/Ctrl + /** | Keyboard shortcuts |
+
+::theme-image{light="/screenshots/cloud-app/v2-shortcuts-light.png" dark="/screenshots/cloud-app/v2-shortcuts-dark.png" alt="Keyboard shortcuts"}
+::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: AI Collaboration
+icon: i-lucide-sparkles
+to: /cloud/ai-collaboration
+---
+Connect an agent and watch it write alongside you.
+::
+
+::card
+---
+title: File History
+icon: i-lucide-history
+to: /cloud/file-history
+---
+Every save is a version — browse, compare, and merge back.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+The semantic structure for observations and relations.
+::
+:::
diff --git a/content/03.cloud/04.ai-collaboration.md b/content/03.cloud/04.ai-collaboration.md
new file mode 100644
index 0000000..fae9423
--- /dev/null
+++ b/content/03.cloud/04.ai-collaboration.md
@@ -0,0 +1,71 @@
+---
+title: AI Collaboration
+description: Connect an agent to the web app and watch it write alongside you — live, in the same note.
+---
+
+The [web app](/cloud/web-app) treats your AI assistant as a real collaborator — you can watch it write, and steer it, in the same note you're editing. It's the same shared memory your agents reach over MCP, with a front-row seat.
+
+---
+
+## Connect an agent
+
+Click **Connect Agent** in the editor to start or resume an agent session for the workspace. When an agent is connected, the button shows its live status (for example, "Claude live").
+
+## Work on a selection
+
+Select text in the editor and it appears in the agent pane, where you can send a request about it — a rewrite, a summary, or a next step. The agent's changes stream into the note as it works.
+
+## The agent pane
+
+The agent pane shows the session: what the agent is working on, its progress, and a place to steer it ("Ask for a rewrite, summary, or next step…"). Updates flow into the note in real time, so you can follow along while it writes.
+
+## Send a note to any agent
+
+Every note has a stable link your agents can use: open the `⋮` menu and choose **Copy link for your agent**, then paste it into any connected AI tool — "add a summary section to this note" — and watch the change land live.
+
+## See what your agents did
+
+Agent writes over MCP appear in the [**Activity** view](/cloud/web-app#activity) alongside your teammates' edits — with direct links to the affected notes. On a team, everyone's agents share the same knowledge base; see [Basic Memory Teams](/teams/about).
+
+---
+
+## The loop in practice
+
+1. **AI creates** detailed notes during conversations — or writes alongside you with Connect Agent
+2. **You browse and refine** in the web app
+3. **AI references** your refined notes in future conversations
+
+Each cycle makes your AI better at answering from your actual knowledge.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: AI Assistant Guide
+icon: i-lucide-bot
+to: /reference/ai-assistant-guide
+---
+Teach your assistant when and how to use Basic Memory.
+::
+
+::card
+---
+title: Teams
+icon: i-lucide-users
+to: /teams/about
+---
+One shared memory for your team and every agent connected to it.
+::
+
+::card
+---
+title: Note Editor
+icon: i-lucide-pencil
+to: /cloud/note-editor
+---
+Editing modes, drafts, and keyboard shortcuts.
+::
+:::
diff --git a/content/3.cloud/03.cloud-sync.md b/content/03.cloud/05.cloud-sync.md
similarity index 54%
rename from content/3.cloud/03.cloud-sync.md
rename to content/03.cloud/05.cloud-sync.md
index 3333c8e..7d148f9 100644
--- a/content/3.cloud/03.cloud-sync.md
+++ b/content/03.cloud/05.cloud-sync.md
@@ -11,25 +11,23 @@ The Basic Memory Cloud CLI provides seamless integration between local and cloud
 
 The cloud CLI enables you to:
 
-- **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled
+- **Per-project routing** - Route individual projects through cloud with `bm project set-cloud`; the rest stay local
 - **Project-scoped sync** - Each project independently manages its sync configuration
 - **Explicit operations** - Sync only what you want, when you want
-- **Team-safe push/pull** - Additive, git-style transfers that work on shared Team workspaces
-- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync (Personal workspaces)
+- **Team-safe push/pull** - Additive, git-style transfers that work on Personal and Team workspaces alike
 - **Offline access** - Work locally, sync when ready
 
-### Personal vs Team Workspaces
+### The sync commands
 
 | Command | Direction | Behavior | Personal | Team |
 |---------|-----------|----------|----------|------|
 | `bm cloud pull` | cloud → local | **additive** — never deletes local | ✅ | ✅ |
 | `bm cloud push` | local → cloud | **additive** — never deletes cloud | ✅ | ✅ |
 | `bm cloud sync` | local → cloud | **mirror** — deletes cloud files missing locally | ✅ | ❌ |
-| `bm cloud bisync` | local ↔ cloud | **mirror** — can delete/overwrite both sides | ✅ | ❌ |
 
-`sync` and `bisync` are mirror operations: one tree becomes authoritative and files missing on the other side get deleted. That is correct for a Personal workspace (one user, one source of truth) but unsafe on a shared Team bucket, where it could delete a teammate's files. On Team workspaces these commands exit early with a clear error and point you at `push`/`pull`.
+**`push` and `pull` are the standard workflow.** They are additive — they never delete files on the destination — and conflict-aware, so they are safe everywhere, including shared Team workspaces where a mirror operation could delete a teammate's files.
 
-`push` and `pull` are additive (they never delete on the destination), so they are safe on both Personal and Team workspaces.
+`sync` is a mirror operation: your local tree becomes authoritative and cloud files missing locally get deleted. That can be useful on a Personal workspace when local is the single source of truth, but it is blocked on Team workspaces, where it exits early with a clear error pointing you at `push`/`pull`.
 
 ---
 
@@ -38,8 +36,8 @@ The cloud CLI enables you to:
 Before using Basic Memory Cloud sync, you need:
 
 - **Active Subscription**: An active Basic Memory Cloud subscription
-- **Subscribe**: Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe)
-- **Basic Memory CLI**: See [Getting Started](/start-here/getting-started#local-installation) for installation
+- **Subscribe**: Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe?utm_source=docs&utm_medium=docs&utm_campaign=cloud-sync)
+- **Basic Memory CLI**: See [Install Basic Memory locally](/local/local-install) for installation
 
 ::warning
 If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error.
@@ -52,12 +50,12 @@ If you attempt to log in without an active subscription, you'll receive a "Subsc
 
 **Use sync when:**
 - You want to edit notes locally in your preferred editor
-- You need bidirectional sync (changes flow both ways automatically)
+- You want changes to flow both ways (pull cloud changes down, push local changes up)
 - You're working with large knowledge bases
 - You want offline access with periodic syncing
 
 **Alternatives to sync:**
-- **Web Editor**: Upload and edit files in the [Cloud web interface](/cloud/cloud-guide#web-editor)
+- **Web App**: Upload and edit files in the [Cloud web app](/cloud/web-app)
 - **MCP Tools Only**: Use AI assistants to manage notes entirely in cloud
 ::
 
@@ -71,7 +69,7 @@ Projects can exist in three states:
 
 1. **Cloud-only** - Project exists on cloud, no local copy
 2. **Cloud + Local (synced)** - Project has a local working directory that syncs
-3. **Local-only** - Project exists locally (when cloud mode is disabled)
+3. **Local-only** - Project exists only on your machine (the default for `bm project add`)
 
 **Example:**
 
@@ -81,29 +79,27 @@ Projects can exist in three states:
 # - work: wants local sync at ~/work-notes
 # - temp: cloud-only, no local sync needed
 
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work-notes
-bm project add temp  # No local sync
+bm cloud sync-setup research ~/Documents/research
+bm cloud sync-setup work ~/work-notes
+# temp needs no setup — it stays cloud-only
 
-# Now you can sync individually (after initial --resync):
-bm cloud bisync --name research
-bm cloud bisync --name work
-# temp stays cloud-only
+# Now you can sync individually:
+bm cloud pull --name research
+bm cloud pull --name work
 ```
 
 **What happens under the covers:**
-- Config stores `cloud_projects` dict mapping project names to local paths
-- Each project gets its own bisync state in `~/.basic-memory/bisync-state/{project}/`
-- Rclone syncs using single remote: `basic-memory-cloud`
+- Config stores each project as an entry with a `local_sync_path` in `~/.basic-memory/config.json`
+- Rclone transfers files using a tenant-scoped remote per workspace (`basic-memory-cloud` for your Personal workspace)
 - Projects can live anywhere on your filesystem
 
 ---
 
 ## Quick Start
 
-### 1. Enable Cloud Mode
+### 1. Sign in to Cloud
 
-Authenticate and enable cloud mode:
+Authenticate the CLI:
 
 ```bash
 bm cloud login
@@ -112,8 +108,9 @@ bm cloud login
 **What this does:**
 1. Opens browser to Basic Memory Cloud authentication page
 2. Stores authentication token
-3. Enables cloud mode - all CLI commands now work against cloud
-4. Validates your subscription status
+3. Validates your subscription status
+
+Login doesn't change project routing or start syncing — projects stay local unless you route or sync them explicitly.
 
 ### 2. Set Up Sync
 
@@ -127,7 +124,11 @@ bm cloud setup
 1. Installs rclone automatically (if needed)
 2. Fetches your tenant information from cloud
 3. Generates scoped S3 credentials for sync
-4. Configures single rclone remote: `basic-memory-cloud`
+4. Configures a tenant-scoped rclone remote for the workspace (`basic-memory-cloud` for your Personal workspace)
+
+::note
+**Team workspaces need their own setup.** Run `bm cloud setup --workspace <slug>` once per team workspace before push/pull — otherwise the commands abort with "Workspace is not set up for sync."
+::
 
 ### 3. Add Projects with Sync
 
@@ -135,45 +136,47 @@ Create projects with optional local sync paths:
 
 ```bash
 # Create cloud project without local sync
-bm project add research
+bm project add research --cloud
 
 # Create cloud project WITH local sync
-bm project add research --local-path ~/Documents/research
+bm project add research --cloud --local-path ~/Documents/research
 
-# Or configure sync for existing project
+# Or configure sync for an existing cloud project
 bm cloud sync-setup research ~/Documents/research
 ```
 
-### 4. Sync Your Project
+### 4. Pull the Project Down
 
-Establish the initial sync baseline. **Always preview with `--dry-run` first:**
+Fetch the cloud copy into your local directory. **Preview with `--dry-run` first:**
 
 ```bash
-# Step 1: Preview the initial sync
-bm cloud bisync --name research --resync --dry-run
+# Step 1: Preview what would transfer
+bm cloud pull --name research --dry-run
 
-# Step 2: If all looks good, run the actual sync
-bm cloud bisync --name research --resync
+# Step 2: Fetch cloud files into your local directory
+bm cloud pull --name research
 ```
 
-::note{icon="i-lucide-info"}
-**Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, don't use `--resync` unless you need to force a new baseline.
-::
+`pull` is additive — it fetches new and changed files without deleting anything local.
 
-### 5. Subsequent Syncs
+### 5. Daily Workflow
 
-After the first sync, just run bisync without `--resync`:
+Pull before you start, edit locally, push when you're done:
 
 ```bash
-bm cloud bisync --name research
+# Fetch changes made in the web app, by MCP tools, or by teammates
+bm cloud pull --name research
+
+# ... edit files locally ...
+
+# Upload your changes to the cloud
+bm cloud push --name research
 ```
 
-**What happens:**
-1. Rclone compares local and cloud states
-2. Syncs changes in both directions
-3. Auto-resolves conflicts (newer file wins)
-4. Basic Memory reindexes all changed files
-5. Updates `last_sync` timestamp in config
+**What happens on `push`:**
+1. New and changed local files transfer to cloud
+2. If a file differs on both sides, the command aborts and lists the conflicts
+3. The cloud instance detects the new files and reindexes them automatically
 
 ::note
 **Reindexing after sync**: Basic Memory automatically reindexes all synced changes to update the knowledge graph.
@@ -186,8 +189,8 @@ bm cloud status
 ```
 
 You should see:
-- `Mode: Cloud (enabled)`
-- `Cloud instance is healthy`
+- `OAuth: token valid`
+- `Cloud connected`
 
 ---
 
@@ -199,13 +202,10 @@ You should see:
 |---------|-----------|----------|
 | `bm cloud pull` | Cloud → Local | Fetch cloud changes additively (Personal + Team) |
 | `bm cloud push` | Local → Cloud | Upload local changes additively (Personal + Team) |
-| `bm cloud bisync` | Local ↔ Cloud | Two-way mirror (Personal only, recommended for solo use) |
 | `bm cloud sync` | Local → Cloud | One-way mirror, make cloud match local (Personal only) |
 | `bm cloud check` | Verify | Check if files match (Personal only) |
 
-If you collaborate on a shared Team workspace, use **`push`/`pull`**. If you are the only writer (a Personal workspace), the mirror commands `sync`/`bisync` give you a single source of truth.
-
-### Team Workspaces: Push and Pull (Additive, Git-Style)
+### Push and Pull (Additive, Git-Style)
 
 `push` and `pull` model `git push` / `git pull`:
 
@@ -244,23 +244,7 @@ bm cloud pull --name research --on-conflict keep-both
 ```
 
 ::note
-`push`/`pull` are deliberately simple, conflict-aware transfers — not a full reconciler. They compare the current state of both sides without a sync baseline. On Team workspaces, use `bm cloud pull --dry-run` / `bm cloud push --dry-run` to preview differences (`bm cloud check` is Personal-only).
-::
-
-### Two-Way Sync (Recommended)
-
-```bash
-# First time - establish baseline
-bm cloud bisync --name research --resync
-
-# Subsequent syncs
-bm cloud bisync --name research
-```
-
-**Conflict resolution:** When the same file is edited both locally and in cloud, the newer file wins (based on modification time).
-
-::warning
-`bisync` is a two-way mirror that can delete and overwrite on both sides, so it is limited to Personal workspaces. On Team workspaces, use `bm cloud pull` then `bm cloud push` instead.
+`push`/`pull` are deliberately simple, conflict-aware transfers — not a full reconciler. They compare the current state of both sides without a sync baseline. Use `--dry-run` to preview differences before transferring (`bm cloud check` is Personal-only).
 ::
 
 ### One-Way Sync
@@ -274,10 +258,11 @@ Makes cloud identical to local — including deleting cloud files that are missi
 ### Preview Changes (Dry Run)
 
 ```bash
-bm cloud bisync --name research --dry-run
+bm cloud pull --name research --dry-run
+bm cloud push --name research --dry-run
 ```
 
-Shows what would change without actually syncing.
+Shows what would transfer without actually syncing.
 
 ### Verify Integrity
 
@@ -285,7 +270,7 @@ Shows what would change without actually syncing.
 bm cloud check --name research
 ```
 
-Compares file checksums without making changes.
+Compares file checksums without making changes (Personal workspaces only).
 
 ---
 
@@ -295,35 +280,36 @@ Compares file checksums without making changes.
 
 ```bash
 # Setup multiple projects
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work-notes
-bm project add personal --local-path ~/personal
-
-# Establish baselines
-bm cloud bisync --name research --resync
-bm cloud bisync --name work --resync
-bm cloud bisync --name personal --resync
-
-# Daily workflow: sync everything
-bm cloud bisync --name research
-bm cloud bisync --name work
-bm cloud bisync --name personal
+bm project add research --cloud --local-path ~/Documents/research
+bm project add work --cloud --local-path ~/work-notes
+bm project add personal --cloud --local-path ~/personal
+
+# Daily workflow: pull, edit, push
+bm cloud pull --name research
+bm cloud pull --name work
+bm cloud pull --name personal
+
+# ... edit locally ...
+
+bm cloud push --name research
+bm cloud push --name work
+bm cloud push --name personal
 ```
 
 ### Mixed Usage
 
 ```bash
 # Projects with sync
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work
+bm project add research --cloud --local-path ~/Documents/research
+bm project add work --cloud --local-path ~/work
 
 # Cloud-only projects
-bm project add archive
-bm project add temp-notes
+bm project add archive --cloud
+bm project add temp-notes --cloud
 
 # Sync only the configured ones
-bm cloud bisync --name research
-bm cloud bisync --name work
+bm cloud pull --name research
+bm cloud pull --name work
 # archive and temp-notes stay cloud-only
 ```
 
@@ -340,27 +326,28 @@ Basic Memory uses `.bmignore` for global ignore patterns (similar to `.gitignore
 **Default patterns:**
 
 ```gitignore
-# Version control
-.git/**
+# Hidden files and version control
+.*
+.git
 
 # Python
-__pycache__/**
+__pycache__
 *.pyc
-.venv/**
+.venv
 
 # Node.js
-node_modules/**
+node_modules
 
 # Basic Memory internals
-memory.db/**
-memory.db-shm/**
-memory.db-wal/**
-
-# OS files
-.DS_Store/**
-
-# Environment files
-.env/**
+*.db
+*.db-shm
+*.db-wal
+config.json
+
+# Editors and OS files
+.obsidian
+.DS_Store
+*.tmp
 ```
 
 ::note
@@ -381,68 +368,35 @@ bm cloud logout
 bm cloud login
 ```
 
-### First Bisync Requires --resync
-
-**Problem:** Bisync fails on first run
-
-**Solution:**
-```bash
-bm cloud bisync --name research --resync
-```
-
-This establishes the initial baseline state.
-
-### Empty Directory Issues
-
-**Problem:** "Empty prior Path1 listing. Cannot sync to an empty directory"
-
-**Solution:** Add at least one file before running `--resync`:
-```bash
-echo "# Research Notes" > ~/Documents/research/README.md
-bm cloud bisync --name research --resync
-```
-
-### Bisync State Corruption
-
-**Problem:** Bisync fails with errors about corrupted state
-
-**Solution:**
-```bash
-bm cloud bisync-reset research
-bm cloud bisync --name research --resync
-```
-
-### Too Many Deletes
+### Push or Pull Reports Conflicts
 
-**Problem:** "max delete limit (25) exceeded"
+**Problem:** "pull aborted: N file(s) differ between local and cloud"
 
-**Solution:** Review what's being deleted, then force resync if correct:
+**Solution:** This is the conflict guard working as intended. Preview the differences, then choose what survives:
 ```bash
-bm cloud bisync --name research --dry-run
-bm cloud bisync --name research --resync
+bm cloud pull --name research --dry-run
+bm cloud pull --name research --on-conflict keep-both
 ```
 
 ### Project Not Configured for Sync
 
-**Problem:** "Project has no local_sync_path configured"
+**Problem:** "Error: Project 'research' has no local sync path configured"
 
 **Solution:**
 ```bash
 bm cloud sync-setup research ~/Documents/research
-bm cloud bisync --name research --resync
+bm cloud pull --name research
 ```
 
 ---
 
-## Disable Cloud Mode
-
-Return to local mode:
+## Sign out
 
 ```bash
 bm cloud logout
 ```
 
-All `bm` commands now work with local projects.
+Logout removes your stored OAuth tokens (a saved API key survives and keeps routing cloud projects). It doesn't change project routing — to route a project locally again, use `bm project set-local <name> --local-path <path>`.
 
 ---
 
@@ -473,30 +427,31 @@ bm cloud status             # Check cloud mode and instance health
 bm cloud setup              # Install rclone and configure credentials
 ```
 
-### Project Management
+### Project Setup
 
 ```bash
-bm project list                           # List cloud projects
-bm project add <name>                     # Create cloud project (no sync)
-bm project add <name> --local-path <path> # Create with local sync
-bm cloud sync-setup <name> <path>       # Add sync to existing project
-bm project rm <name>                      # Delete project
+bm project add <name> --cloud                     # Create cloud project (no sync)
+bm project add <name> --cloud --local-path <path> # Create with local sync
+bm cloud sync-setup <name> <path>                 # Add sync to an existing cloud project
 ```
 
+Full project and auth commands (list, remove, login, status): [CLI Reference](/reference/cli-reference).
+
 ### File Synchronization
 
 ```bash
-# Two-way sync (recommended)
-bm cloud bisync --name <project>          # After first --resync
-bm cloud bisync --name <project> --resync # First time / force baseline
-bm cloud bisync --name <project> --dry-run
-bm cloud bisync --name <project> --verbose
-
-# One-way sync (local → cloud)
+# Standard workflow (Personal + Team)
+bm cloud pull --name <project>            # Fetch cloud changes (additive)
+bm cloud push --name <project>            # Upload local changes (additive)
+bm cloud pull --name <project> --dry-run
+bm cloud push --name <project> --dry-run
+bm cloud pull --name <project> --on-conflict keep-both
+
+# One-way mirror (local → cloud, Personal only)
 bm cloud sync --name <project>
 bm cloud sync --name <project> --dry-run
 
-# Integrity check
+# Integrity check (Personal only)
 bm cloud check --name <project>
 
 # List remote files
@@ -509,18 +464,18 @@ bm project ls --name <project>
 
 **Basic Memory Cloud uses project-scoped sync:**
 
-1. **Enable cloud mode** - `bm cloud login`
+1. **Sign in** - `bm cloud login`
 2. **Install rclone** - `bm cloud setup`
-3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research`
-4. **Preview first sync** - `bm cloud bisync --name research --resync --dry-run`
-5. **Establish baseline** - `bm cloud bisync --name research --resync`
-6. **Daily workflow** - `bm cloud bisync --name research`
+3. **Add projects with sync** - `bm project add research --cloud --local-path ~/Documents/research`
+4. **Preview the first pull** - `bm cloud pull --name research --dry-run`
+5. **Pull the project down** - `bm cloud pull --name research`
+6. **Daily workflow** - pull, edit locally, then `bm cloud push --name research`
 
 **Key benefits:**
 - Each project independently syncs (or doesn't)
 - Projects can live anywhere on disk
 - Explicit sync operations (no magic)
-- Safe by design (max delete limits, conflict resolution)
+- Safe by design (additive transfers, conflict guard)
 - Full offline access (work locally, sync when ready)
 
 ---
diff --git a/content/3.cloud/05.cloud-snapshots.md b/content/03.cloud/06.cloud-snapshots.md
similarity index 76%
rename from content/3.cloud/05.cloud-snapshots.md
rename to content/03.cloud/06.cloud-snapshots.md
index aaf6344..7698e32 100644
--- a/content/3.cloud/05.cloud-snapshots.md
+++ b/content/03.cloud/06.cloud-snapshots.md
@@ -30,7 +30,7 @@ Manage snapshots directly in your browser at [app.basicmemory.com](https://app.b
 
 ### View Snapshots
 
-Go to **Settings → Snapshots** to see all snapshots with creation time and description.
+Go to **Settings → Snapshots** and select a workspace to see its snapshots with creation time and description.
 
 ![Snapshots list](/screenshots/cloud-app/snapshots-list.png)
 
@@ -44,7 +44,7 @@ Go to **Settings → Snapshots** to see all snapshots with creation time and des
 
 ### Restore from a Snapshot
 
-1. Click on a snapshot → **Restore Files**
+1. On the snapshot's row, click **Restore**
 2. Filter by project or search for specific files
 3. Select files or folders to restore
 4. Click **Restore** to copy them back
@@ -67,10 +67,7 @@ Manage snapshots from the command line with `bm cloud snapshot` commands.
 bm cloud snapshot create "Before reorganization"
 ```
 
-**Output:**
-```
-Created snapshot: snap_abc123 (2026-01-27T10:30:00)
-```
+The command confirms the snapshot with its ID (a UUID), creation time, and description.
 
 ### List Snapshots
 
@@ -78,17 +75,12 @@ Created snapshot: snap_abc123 (2026-01-27T10:30:00)
 bm cloud snapshot list
 ```
 
-**Output:**
-```
-snap_abc123  "Before reorganization"  Jan 27, 2026  42 MB
-snap_xyz789  "daily-auto"             Jan 26, 2026  41 MB
-snap_def456  "daily-auto"             Jan 25, 2026  40 MB
-```
+Lists your snapshots in a table: ID, description, whether it was automatic, and creation time.
 
 ### View Snapshot Details
 
 ```bash
-bm cloud snapshot show snap_abc123
+bm cloud snapshot show <snapshot-id>
 ```
 
 ### Browse Snapshot Contents
@@ -96,41 +88,33 @@ bm cloud snapshot show snap_abc123
 View files in a snapshot without restoring:
 
 ```bash
-bm cloud snapshot browse snap_abc123
-```
-
-**Output:**
-```
-notes/project.md
-notes/ideas.md
-research/analysis.md
-meetings/2026-01-15.md
+bm cloud snapshot browse <snapshot-id>
 ```
 
-Filter by path:
+Lists the files in the snapshot with their sizes. Paths start with the project name (e.g. `my-project/notes/ideas.md`). Filter by path:
 
 ```bash
-bm cloud snapshot browse snap_abc123 --path notes/
+bm cloud snapshot browse <snapshot-id> --prefix my-project/notes/
 ```
 
 ### Restore Files
 
-Restore a specific file:
+Restore paths start with the project name, exactly as `snapshot browse` shows them. Restore a specific file:
 
 ```bash
-bm cloud snapshot restore snap_abc123 --file notes/important.md
+bm cloud restore my-project/notes/important.md --snapshot <snapshot-id>
 ```
 
 Restore an entire folder:
 
 ```bash
-bm cloud snapshot restore snap_abc123 --path research/
+bm cloud restore my-project/research/ --snapshot <snapshot-id>
 ```
 
 ### Delete a Snapshot
 
 ```bash
-bm cloud snapshot delete snap_abc123
+bm cloud snapshot delete <snapshot-id>
 ```
 
 ::warning
@@ -187,9 +171,9 @@ You can rely on automatic snapshots for basic protection, but manual snapshots a
 
 ### Restore Didn't Work
 
-1. Check file permissions in your project
-2. Verify the file path is correct
-3. Try restoring to a different location first
+1. Confirm the exact path exists in the snapshot: `bm cloud snapshot browse <snapshot-id> --prefix <path>`
+2. Make sure the path is project-prefixed, exactly as browse shows it (e.g. `my-project/notes/file.md`)
+3. Re-run the restore with the corrected path — files always restore to their original location
 
 ---
 
@@ -211,7 +195,7 @@ title: Cloud Sync
 icon: i-lucide-refresh-cw
 to: /cloud/cloud-sync
 ---
-Set up bidirectional sync with local files.
+Sync local files with push and pull.
 ::
 
 ::card
diff --git a/content/03.cloud/07.themes.md b/content/03.cloud/07.themes.md
new file mode 100644
index 0000000..dc76d89
--- /dev/null
+++ b/content/03.cloud/07.themes.md
@@ -0,0 +1,48 @@
+---
+title: Themes
+description: Personalize the web app with color themes and light, dark, or system mode.
+---
+
+The Basic Memory web app ships with a set of curated color themes, each with coordinated palettes for light and dark mode. Pick both under **Settings → General**, in the **Look & Feel** card.
+
+---
+
+## Color mode
+
+Use the **Mode** control to choose **Light**, **Dark**, or **System**. System follows your operating system's preference and switches automatically.
+
+---
+
+## Choosing a theme
+
+The **Theme** control shows a row of color swatches — each previews a theme's palette, labeled with the theme's name. Click a swatch to apply it instantly, no save needed.
+
+- Themes and mode are independent: every theme has coordinated colors for both light and dark, so switching mode keeps your theme.
+- Theme choices are saved locally in this browser — pick your theme on each device you use.
+- The theme applies across the whole app — sidebar, editor, preview, and settings.
+
+Try a few — clicking around is faster than reading about them.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Web App Guide
+icon: i-lucide-layout-panel-left
+to: /cloud/web-app
+---
+The full tour — editing modes, shortcuts, projects, and settings.
+::
+
+::card
+---
+title: Keyboard Shortcuts
+icon: i-lucide-keyboard
+to: /cloud/note-editor#keyboard-shortcuts
+---
+Switch view modes and run commands without the mouse.
+::
+:::
diff --git a/content/3.cloud/07.api-keys.md b/content/03.cloud/08.api-keys.md
similarity index 79%
rename from content/3.cloud/07.api-keys.md
rename to content/03.cloud/08.api-keys.md
index 668b349..0846e12 100644
--- a/content/3.cloud/07.api-keys.md
+++ b/content/03.cloud/08.api-keys.md
@@ -25,16 +25,12 @@ In the [web app](https://app.basicmemory.com), go to **Settings → API Keys**
 
 ### Click Create Key
 
-Click **Create New API Key**
+Keys are grouped by workspace. Click **Create Key** next to the workspace you want the key for (Personal or a Team), then confirm with **Create**.
 
 ### Name Your Key
 
 Enter a descriptive name like "Claude Desktop" or "Work Laptop"
 
-### Set Expiration (Optional)
-
-Choose when the key should expire, or leave blank for no expiration
-
 ### Copy Your Key
 
 **Important:** Copy the key immediately. It's only shown once and cannot be retrieved later.
@@ -43,7 +39,7 @@ The key looks like: `bmc_abc123def456...`
 ::
 
 ::warning
-Store your API key securely. Anyone with the key can access your Basic Memory account. Never commit keys to version control or share them publicly.
+Store your API key securely. Each key belongs to a specific workspace — anyone with the key can access that workspace. Never commit keys to version control or share them publicly.
 ::
 
 ---
@@ -52,16 +48,17 @@ Store your API key securely. Anyone with the key can access your Basic Memory ac
 
 ### With Claude Desktop
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Claude Desktop connects to Basic Memory Cloud through its **Connectors** OAuth flow, not an API key — see [Claude Desktop](/integrations/claude-desktop). If you specifically need bearer-token auth (for example on an account without browser OAuth), bridge through a stdio proxy in `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "basic-memory": {
-      "url": "https://cloud.basicmemory.com/mcp",
-      "headers": {
-        "Authorization": "Bearer bmc_your_key_here"
-      }
+      "command": "npx",
+      "args": [
+        "mcp-remote", "https://cloud.basicmemory.com/mcp",
+        "--header", "Authorization: Bearer bmc_your_key_here"
+      ]
     }
   }
 }
@@ -72,12 +69,13 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 Add to `~/.codex/config.toml`:
 
 ```toml
-[[mcp_servers]]
-name = "basic-memory"
+[mcp_servers.basic-memory]
 url = "https://cloud.basicmemory.com/mcp"
 bearer_token_env_var = "BASIC_MEMORY_API_KEY"
 ```
 
+Full walkthrough (key export, shell setup): [Codex integration](/integrations/codex).
+
 Then set the environment variable:
 
 ```bash
@@ -103,7 +101,7 @@ curl -H "Authorization: Bearer bmc_your_key_here" \
 
 ### With Basic Memory CLI (per-project routing)
 
-Save a key and route only selected projects through cloud:
+Save a key for the CLI to use:
 
 ```bash
 # Save an existing key from the web app
@@ -111,15 +109,9 @@ bm cloud api-key save bmc_your_key_here
 
 # Or create and save a new key (requires active OAuth session — run bm cloud login first)
 bm cloud api-key create "work-laptop"
-
-# Route one project through cloud
-bm project set-cloud research
-
-# Revert that project to local routing
-bm project set-local research
 ```
 
-This lets you keep a hybrid setup where some projects stay local and others use cloud. See [Local & Cloud Routing](/cloud/routing) for the full routing model, priority levels, and common configurations.
+The key authenticates cloud-routed projects — for routing projects through cloud (`bm project set-cloud` / `set-local`), see [Local & Cloud Routing](/cloud/routing).
 
 ---
 
@@ -156,7 +148,6 @@ If you suspect a key has been compromised, revoke it immediately and create a ne
 ### Do
 
 - **Use descriptive names** - "Claude Desktop Work" is better than "key1"
-- **Set expiration dates** - Especially for temporary access
 - **Use environment variables** - Don't hardcode keys in config files
 - **Revoke unused keys** - Clean up keys you no longer need
 - **Create separate keys** - One per device or application
@@ -194,7 +185,7 @@ Example: `bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv`
 | Best for | CLI, scripts, automation | Interactive apps |
 | Token refresh | No (long-lived) | Yes (short-lived + refresh) |
 | Revocation | Per-key | Per-session |
-| Scopes | Full access | Configurable |
+| Access | Full workspace access (project-scoped keys available via API) | Full account access |
 
 Use **API keys** for:
 - Command-line tools
diff --git a/content/3.cloud/09.shared-notes.md b/content/03.cloud/09.shared-notes.md
similarity index 59%
rename from content/3.cloud/09.shared-notes.md
rename to content/03.cloud/09.shared-notes.md
index da640b5..77b61c3 100644
--- a/content/3.cloud/09.shared-notes.md
+++ b/content/03.cloud/09.shared-notes.md
@@ -1,9 +1,13 @@
 ---
 title: Shared Notes
-description: Create a public, read-only link to a note so anyone can view it — no account required.
+description: Publish a note as a public, read-only link for people outside your workspace.
 ---
 
-Shared Notes let you publish a single note as a public, read-only web page. Anyone with the link can read it without signing in — handy for sharing a document, a spec, or a writeup with people outside your workspace.
+Shared Notes are **public** shares: publish a single note as a read-only web page that anyone with the link can read, no account required — handy for a document, a spec, or a writeup you want to show people outside your workspace.
+
+::tip
+**Sharing with your team doesn't need a link.** Teammates see notes automatically through [team projects](/teams/team-projects) — everyone in the workspace (or everyone you've granted access on a shared project) already has them. Use Shared Notes only for readers outside Basic Memory.
+::
 
 ::theme-image{light="/screenshots/cloud-app/v2-shared-note-public-note-light.png" dark="/screenshots/cloud-app/v2-shared-note-public-note-dark.png" alt="A shared note"}
 ::
@@ -21,10 +25,7 @@ Open a saved note, then use its `⋮` menu → **Share note**.
 ::theme-image{light="/screenshots/cloud-app/v2-shared-note-button-light.png" dark="/screenshots/cloud-app/v2-shared-note-button-dark.png" alt="Share note action in the note menu"}
 ::
 
-Basic Memory creates a public link and shows it in a dialog:
-
-> **Share note** — A public read-only link for this note was created.
-> ⚠️ Anyone with this link can view the note without signing in.
+A dialog opens with a warning — "Anyone with this link can view the note without signing in." — and a **Create Link** button. Click it to generate the public link, then **Copy** to copy it.
 
 ::theme-image{light="/screenshots/cloud-app/v2-shared-note-dialog-light.png" dark="/screenshots/cloud-app/v2-shared-note-dialog-dark.png" alt="Share note dialog with the public link and Copy button"}
 ::
@@ -36,14 +37,14 @@ https://cloud.basicmemory.com/s/<token>
 ```
 
 ::note
-Only **saved** notes can be shared. A [draft](/cloud/web-app#drafts) has to be saved to a project first — once it has a project and path, the **Share note** action appears.
+Only **saved** notes can be shared. A [draft](/cloud/note-editor#drafts) has to be saved to a project first — once it has a project and path, the **Share note** action appears.
 ::
 
 ---
 
 ## What the recipient sees
 
-The shared link opens a clean, full-page rendered view of the note. Visitors:
+The shared link opens a clean, full-page rendered view of the note, with a **Readable/Full** toggle to switch between a comfortable reading width and the full content width. Visitors:
 
 - **Don't need an account** and **can't edit** — it's read-only.
 - Can follow `[[wiki links]]` in the note (they render as preview links).
@@ -56,18 +57,16 @@ If a link is invalid, disabled, or revoked, the page simply returns a generic "n
 
 ## Manage your shares
 
-Go to **Settings → Shared Notes** to see and manage every link you've created.
+Go to **Settings → Shared Notes** to see and manage every link in the workspace — in a team workspace, that includes links created by teammates.
 
 ::theme-image{light="/screenshots/cloud-app/v2-shared-note-settings-light.png" dark="/screenshots/cloud-app/v2-shared-note-settings-dark.png" alt="Shared Notes settings"}
 ::
 
-From a note's `⋮` menu or the settings screen you can:
-
-| Action | What it does |
-|--------|--------------|
-| **Sharing link** | View and copy the existing public link |
-| **Disable** / **Enable** | Pause a link without deleting it, then turn it back on later |
-| **Stop sharing** | Permanently revoke the link |
+| Action | Where | What it does |
+|--------|-------|--------------|
+| **Sharing link** | Note's `⋮` menu | View and copy the existing public link |
+| **Disable** / **Enable** | Settings → Shared Notes | Pause a link without deleting it, then turn it back on later |
+| **Stop sharing** | Both | Permanently revoke the link |
 
 Moving or renaming a note **doesn't break** its share link — the link follows the note. Deleting the note retires the link.
 
@@ -75,7 +74,7 @@ Moving or renaming a note **doesn't break** its share link — the link follows
 
 ## Who can share
 
-In a [team workspace](/teams/about), **owners and editors** can create, disable, and revoke share links. **Viewers** can't manage shares. In a personal workspace, you manage your own.
+In a [team workspace](/teams/about), any member except a **Viewer** — Editors, User Admins, Admins, and Owners — can create, disable, and revoke share links. In a personal workspace, you manage your own.
 
 ---
 
diff --git a/content/3.cloud/11.restore-lost-content.md b/content/03.cloud/10.restore-lost-content.md
similarity index 70%
rename from content/3.cloud/11.restore-lost-content.md
rename to content/03.cloud/10.restore-lost-content.md
index 978c2b8..469c020 100644
--- a/content/3.cloud/11.restore-lost-content.md
+++ b/content/03.cloud/10.restore-lost-content.md
@@ -42,10 +42,10 @@ See [File History](/cloud/file-history) for the full reference, including who ca
 
 ## Snapshots
 
-Snapshots are project-wide point-in-time backups. Use them when you need to roll back more than one note — a deleted folder, a botched reorganization, or a project you wish you hadn't deleted.
+Snapshots are workspace-wide point-in-time backups. Use them when you need to roll back more than one note — a deleted folder, a botched reorganization, or a project you wish you hadn't deleted.
 
 ::note{icon="i-lucide-info"}
-Basic Memory Cloud creates snapshots automatically every day, and you can create manual ones before risky changes. As long as the content existed in some snapshot, you can get it back. For the snapshots reference itself — what they are, retention, automatic vs manual — see [Cloud Snapshots](/cloud/cloud-snapshots).
+Basic Memory Cloud creates snapshots automatically every day, and you can create manual ones before risky changes. As long as the content existed in some snapshot, you can get it back. For the snapshots reference itself — what they are, automatic vs manual, CLI options — see [Cloud Snapshots](/cloud/cloud-snapshots).
 ::
 
 ### 1. Find a snapshot from before the loss
@@ -61,7 +61,7 @@ Settings → Snapshots
 ```
 ::
 
-Pick the most recent snapshot with a timestamp **before** the change you regret. Note its ID (e.g. `snap_abc123`) — you'll use it in the restore step.
+Pick the most recent snapshot with a timestamp **before** the change you regret. Note its ID (a UUID) — you'll use it in the restore step.
 
 ::tip
 Not sure when the loss happened? Pick the snapshot just before your last known-good edit. Worst case, restore a single file to a sandbox folder first and confirm it has what you expect before doing a bigger restore.
@@ -75,16 +75,16 @@ Before restoring, peek at what the snapshot actually contains — it saves a ste
 
 ```bash
 # List everything in the snapshot
-bm cloud snapshot browse snap_abc123
+bm cloud snapshot browse <snapshot-id>
 
 # List a specific folder
-bm cloud snapshot browse snap_abc123 --path notes/
+bm cloud snapshot browse <snapshot-id> --prefix my-project/notes/
 
 # Show snapshot metadata
-bm cloud snapshot show snap_abc123
+bm cloud snapshot show <snapshot-id>
 ```
 
-The web app's snapshot browser does the same thing under **Settings → Snapshots → (snapshot)**.
+The web app's snapshot browser does the same thing under **Settings → Snapshots** — select the workspace, then the snapshot.
 
 ---
 
@@ -95,7 +95,7 @@ Restore is targeted — you pick the file, folder, or project you want back, not
 #### A single note
 
 ```bash
-bm cloud snapshot restore snap_abc123 --file notes/important.md
+bm cloud restore my-project/notes/important.md --snapshot <snapshot-id>
 ```
 
 Or in the web app: browse the snapshot, find the file, choose **Restore**.
@@ -103,7 +103,7 @@ Or in the web app: browse the snapshot, find the file, choose **Restore**.
 #### A folder
 
 ```bash
-bm cloud snapshot restore snap_abc123 --path research/
+bm cloud restore my-project/research/ --snapshot <snapshot-id>
 ```
 
 Restores everything under that path as it existed in the snapshot.
@@ -113,7 +113,7 @@ Restores everything under that path as it existed in the snapshot.
 If you lost most of a project — or deleted it — restore the project root:
 
 ```bash
-bm cloud snapshot restore snap_abc123 --path <project-name>/
+bm cloud restore <project-name>/ --snapshot <snapshot-id>
 ```
 
 ::note
@@ -138,20 +138,20 @@ You can recover a deleted project the same way: find a snapshot from before the
 
 ```bash
 bm cloud snapshot list
-bm cloud snapshot browse snap_abc123 --path my-project/
-bm cloud snapshot restore snap_abc123 --path my-project/
+bm cloud snapshot browse <snapshot-id> --prefix my-project/
+bm cloud restore my-project/ --snapshot <snapshot-id>
 ```
 
-You may need to re-create the project entry in the workspace before the restored files appear as a live project — open the app, go to **Settings → Projects**, and verify.
+Restore recreates the project entry automatically if it's missing — after restoring, open **Settings → Projects** to confirm the project reappeared.
 
 ---
 
 ## What if the snapshot is too old?
 
-Snapshots cover the recent history of your cloud workspace. If the content you want is older than your retention window, two backstops:
+If no snapshot predates the loss — the content was created and deleted between snapshots, or the change is very old — two backstops:
 
-- **Local sync mirror.** If you had [hybrid editing](/cloud/edit-locally-and-in-the-app) set up, your local folder is an independent copy. Check there.
-- **A project ZIP download.** If you'd previously downloaded the project as a ZIP (Manage Projects → Download), unpack it locally and re-upload to the project.
+- **Local sync copy.** If you had [cloud sync](/cloud/cloud-sync) set up, your local folder is an independent copy. Check there.
+- **A project ZIP download.** If you'd previously downloaded the project as a ZIP (**Settings → Projects** → the project's `⋮` menu → **Download**), unpack it locally and re-upload to the project.
 
 For ongoing safety: take a manual snapshot before any change you might want to roll back. They're free and instant.
 
@@ -161,10 +161,18 @@ bm cloud snapshot create "Before reorganizing research/"
 
 ---
 
+## Still stuck? Contact support
+
+If you've lost content and no snapshot or backstop covers it, don't give up — Basic Memory runs **nightly backups** of cloud data independently of your snapshots, and we may be able to recover it for you.
+
+Email `support@basicmemory.com` — or use the **feedback button** in the app's lower-left navbar — with your account email, the workspace and project, roughly when the content was lost, and what it was. See [Contact Support](/reference/contact-support) for what else to include.
+
+---
+
 ## Related
 
 - [File History](/cloud/file-history) — per-note version timeline and diff/merge restore
-- [Cloud Snapshots](/cloud/cloud-snapshots) — the full snapshot reference (creation, retention, browsing, CLI options)
-- [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app) — bidirectional sync gives you a local backstop
+- [Cloud Snapshots](/cloud/cloud-snapshots) — the full snapshot reference (creation, browsing, restore, CLI options)
+- [Cloud Sync](/cloud/cloud-sync) — a synced local folder gives you a local backstop
 - [Copy Content Between Workspaces](/teams/copy-between-workspaces) — for restoring from a downloaded project ZIP
 - [CLI Reference](/reference/cli-reference) — every `bm cloud snapshot` command
diff --git a/content/3.cloud/12.file-history.md b/content/03.cloud/11.file-history.md
similarity index 88%
rename from content/3.cloud/12.file-history.md
rename to content/03.cloud/11.file-history.md
index 70bc1ab..6a5e50b 100644
--- a/content/3.cloud/12.file-history.md
+++ b/content/03.cloud/11.file-history.md
@@ -3,7 +3,7 @@ title: File History
 description: Per-note version history in the cloud — open File history on any note to see every saved version and restore or merge in old content.
 ---
 
-Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note to see its full timeline, compare an earlier version side-by-side with the current one, and apply changes back into the live note. It's the fast, per-note answer to "I want to undo something" — distinct from [Snapshots](/cloud/cloud-snapshots), which are project-wide point-in-time backups.
+Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note to see its full timeline, compare an earlier version side-by-side with the current one, and apply changes back into the live note. It's the fast, per-note answer to "I want to undo something" — distinct from [Snapshots](/cloud/cloud-snapshots), which are workspace-wide point-in-time backups.
 
 ::note{icon="i-lucide-history"}
 File history is a cloud feature. Versions are created automatically on every save — no setup, nothing to turn on.
@@ -51,14 +51,15 @@ A few states will gray out the **Apply** button:
 
 - **Unsaved edits in the main editor.** Save your current draft first, then apply from history.
 - **"File history is catching up."** Your most recent save hasn't reached the storage layer yet. Wait a moment and refresh.
-- **"Current file version changed; refresh before applying."** Someone (or something) wrote the note while you were merging. Refresh history and reapply on top of the new current.
+
+Apply can also **fail after clicking** with *"Current file version changed; refresh before applying."* — someone (or something) wrote the note while you were merging. Refresh history and reapply on top of the new current version.
 
 ---
 
 ## Who can see and use it
 
-- **View history** — anyone with read access to the note (viewers, editors, owners).
-- **Apply a version** — anyone with edit access (editors and owners). Viewers can browse history but can't write.
+- **View history** — anyone with read access to the note (Viewer and above).
+- **Apply a version** — anyone with edit access (Editor and above). Viewers can browse history but can't write.
 
 In a [team workspace](/teams/about), this follows the project's normal access rules.
 
@@ -89,6 +90,6 @@ For more on the architecture, see the Tigris case study: [Own Your AI Context wi
 ## Related
 
 - [Restore Lost Content](/cloud/restore-lost-content) — when to use File history vs. Snapshots
-- [Cloud Snapshots](/cloud/cloud-snapshots) — project-wide point-in-time backups
+- [Cloud Snapshots](/cloud/cloud-snapshots) — workspace-wide point-in-time backups
 - [Web App](/cloud/web-app) — the editor and surrounding UI
 - [Teams](/teams/about) — permissions in a shared workspace
diff --git a/content/03.cloud/12.cloud-cli.md b/content/03.cloud/12.cloud-cli.md
new file mode 100644
index 0000000..df64833
--- /dev/null
+++ b/content/03.cloud/12.cloud-cli.md
@@ -0,0 +1,191 @@
+---
+title: Cloud CLI
+description: Use Basic Memory Cloud from the terminal for status checks, API keys, sync, routing, recovery, and automation.
+---
+
+You do **not** need the CLI to use Basic Memory Cloud. The web app and hosted MCP endpoint are enough for most people.
+
+Install the CLI when you want Cloud to participate in terminal workflows:
+
+- Check Cloud connection and project status.
+- Manage API keys for scripts or MCP clients.
+- Sync a Cloud project with a local Markdown folder.
+- Route selected local projects through Cloud.
+- Create and restore Cloud snapshots.
+- Automate repeatable knowledge tasks from shell scripts or CI jobs.
+
+::note{icon="i-lucide-cloud"}
+Cloud CLI commands use the same Cloud account, workspaces, projects, and permissions as the web app and hosted MCP endpoint.
+::
+
+---
+
+## Install and check the CLI
+
+If you have not installed Basic Memory locally yet, use `uv`:
+
+```bash
+uv tool install basic-memory
+```
+
+Confirm the command is available:
+
+```bash
+bm --version
+```
+
+Update an older install:
+
+```bash
+bm update
+```
+
+See [Install Basic Memory locally](/local/local-install) for Homebrew and local MCP setup.
+
+---
+
+## Sign in to Cloud
+
+Use browser-based login for an interactive terminal:
+
+```bash
+bm cloud login
+bm cloud status
+```
+
+`bm cloud login` authenticates the CLI. It does not automatically move local projects into Cloud or start syncing files.
+
+For automation, scripts, shared terminals, or clients that need bearer-token authentication, use an API key:
+
+```bash
+# Save an existing key from Settings -> API Keys
+bm cloud api-key save bmc_your_key_here
+
+# Or create and save a new key from the CLI
+# Requires an active `bm cloud login` session
+bm cloud api-key create "work-laptop"
+```
+
+See [API Keys](/cloud/api-keys) for the full key workflow and security guidance.
+
+---
+
+## Inspect workspaces and projects
+
+List the Cloud workspaces available to your account:
+
+```bash
+bm cloud workspace list
+```
+
+Set the default workspace used by Cloud commands when one is not specified:
+
+```bash
+bm cloud workspace set-default acme
+```
+
+List projects across local and Cloud workspaces:
+
+```bash
+bm project list
+```
+
+`bm project list` is the fastest sanity check when a terminal command or local MCP server is not using the project you expected.
+
+---
+
+## Route selected local projects through Cloud
+
+Routing is for hybrid setups where you have the CLI or a local MCP server installed, but want specific projects to use Cloud.
+
+```bash
+# Route one project through Cloud
+bm project set-cloud research
+
+# Route a project through a specific workspace
+bm project set-cloud research --workspace acme
+
+# Return the project to local routing
+bm project set-local research --local-path ~/Documents/research
+```
+
+Routing is separate from file sync. A Cloud-routed project can be used by CLI and local MCP commands without keeping a local Markdown mirror.
+
+See [Local & Cloud Routing](/cloud/routing) for the routing model, precedence, and troubleshooting.
+
+---
+
+## Sync Cloud with local files
+
+Use Cloud Sync when you want a local Markdown folder and a Cloud project to stay aligned. The additive `push` and `pull` commands work the same on personal and team workspaces. These commands assume the Cloud project already exists — create one in the web app or with `bm project add research --cloud`:
+
+```bash
+bm cloud setup
+bm cloud sync-setup research ~/Documents/research
+
+# Fetch cloud changes, then upload local ones
+bm cloud pull --name research
+bm cloud push --name research --dry-run
+bm cloud push --name research
+```
+
+See [Cloud Sync](/cloud/cloud-sync) for the full workflow reference, including conflict handling with `--on-conflict`.
+
+---
+
+## Recover content from the terminal
+
+Cloud snapshots are available from the CLI:
+
+```bash
+bm cloud snapshot list
+bm cloud snapshot create "Before reorganization"
+bm cloud snapshot browse SNAPSHOT_ID --prefix research/
+bm cloud restore research/important-note.md --snapshot SNAPSHOT_ID
+```
+
+The CLI asks for confirmation before restore operations. Use `--force` only when you intentionally want to skip confirmation.
+
+See [Cloud Snapshots](/cloud/cloud-snapshots) and [Recover Notes](/cloud/restore-lost-content).
+
+---
+
+## Related reference
+
+:::card-group
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Complete command and option reference.
+::
+
+::card
+---
+title: API Keys
+icon: i-lucide-key
+to: /cloud/api-keys
+---
+Create keys for automation and bearer-token MCP clients.
+::
+
+::card
+---
+title: Local & Cloud Routing
+icon: i-lucide-route
+to: /cloud/routing
+---
+Choose which projects use local or Cloud operations.
+::
+
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Keep local Markdown folders aligned with Cloud projects.
+::
+:::
diff --git a/content/3.cloud/08.routing.md b/content/03.cloud/13.routing.md
similarity index 66%
rename from content/3.cloud/08.routing.md
rename to content/03.cloud/13.routing.md
index b0edbc2..487093d 100644
--- a/content/3.cloud/08.routing.md
+++ b/content/03.cloud/13.routing.md
@@ -30,13 +30,15 @@ Routing decisions follow a priority order — the most specific level wins:
 |----------|-------|-----------|--------------|
 | Highest | **Per-command** | `--local` / `--cloud` flags | Override for a single command |
 | Medium | **Per-project** | `bm project set-cloud` / `set-local` | Persistent setting for a specific project |
-| Lowest | **Global** | `bm cloud login` / `logout` | Default for all projects |
+| Lowest | **Default** | — | Local. Projects run on your machine unless routed |
+
+Credentials (`bm cloud login` or an API key) don't change routing — they just let cloud-routed calls authenticate.
 
 **Examples:**
 
-- Global cloud mode is active, but `bm project set-local research` keeps the `research` project on your machine.
-- You're in local-only mode, but `bm project set-cloud shared-notes` routes just that project through cloud.
-- You need a quick cloud check: `bm search_notes --cloud "meeting notes"` overrides everything for that one call.
+- Everything defaults to local; `bm project set-cloud shared-notes` routes just that project through cloud.
+- A cloud-routed project stays cloud-routed until you run `bm project set-local` — logging out doesn't change it.
+- You need a quick check against a cloud project: `bm tool search-notes "meeting notes" --project shared-notes` — routing follows the project, so the call runs against cloud.
 
 ---
 
@@ -65,18 +67,26 @@ bm project set-cloud research
 
 After this, all MCP tool calls for the `research` project go through your cloud instance.
 
+::warning
+**`set-cloud` changes routing only — it doesn't upload your notes.** Upload existing content first (`bm cloud upload ~/Documents/research --project research --create-project`) or expect to populate the cloud project separately. Your local files stay on disk, but they're removed from the local index and the stored local path is cleared.
+::
+
 ### Check Routing Status
 
 ```bash
-# See which projects are cloud-routed
+# See each project's routing in the CLI Route column
+bm project list
+
+# Verify cloud credentials and connectivity
 bm cloud status
 ```
 
 ### Revert to Local
 
 ```bash
-# Switch a project back to local
-bm project set-local research
+# Switch a project back to local (--local-path is required —
+# set-cloud cleared the stored local path)
+bm project set-local research --local-path ~/Documents/research
 ```
 
 The project returns to local mode immediately. Your cloud data remains in the cloud — this only changes where new requests are handled.
@@ -91,13 +101,10 @@ No configuration needed. Every project runs on your machine. This is how Basic M
 
 ### All Cloud
 
-Log in and everything routes through cloud:
-
-```bash
-bm cloud login
-```
+Two ways to live fully in the cloud:
 
-All projects use your cloud instance. Use `bm cloud logout` to return to local-only.
+- **Skip the CLI entirely** — connect your AI tools directly to the hosted MCP endpoint (`https://cloud.basicmemory.com/mcp`) and use the web app. Nothing local to route.
+- **Route every registered project through cloud** — `bm project set-cloud <name>` for each project (after uploading its content).
 
 ### Hybrid (Local + Cloud)
 
@@ -124,13 +131,13 @@ This is useful when you want to:
 Start local and move projects to cloud one at a time:
 
 ```bash
-# 1. Start with everything local (default)
+# 1. Start with everything local (default); save cloud credentials once
+bm cloud api-key save bmc_your_key_here   # or: bm cloud login
 
-# 2. Upload a project to cloud
+# 2. Upload a project's content to cloud
 bm cloud upload ~/my-notes --project my-notes --create-project
 
-# 3. Route that project to cloud
-bm cloud api-key save bmc_your_key_here
+# 3. Route the (locally registered) project to cloud
 bm project set-cloud my-notes
 
 # 4. Repeat for other projects as needed
@@ -145,7 +152,7 @@ Cloud-routed projects need credentials. Basic Memory supports two methods:
 | Method | Best for | How to set up |
 |--------|----------|---------------|
 | **API keys** | CLI, hybrid setups, automation | `bm cloud api-key save bmc_...` |
-| **Browser login** | Interactive use, global cloud mode | `bm cloud login` |
+| **Browser login** | Interactive use | `bm cloud login` |
 
 Both methods work for any cloud-routed project. API keys are preferred for hybrid setups because they don't require opening a browser.
 
@@ -159,3 +166,36 @@ See [API Keys](/cloud/api-keys) for detailed setup instructions.
 - **Cloud mode** — Requests are forwarded to `cloud.basicmemory.com` using your credentials (API key or login token). The cloud instance processes the request and returns the result.
 
 In both cases, the same tools and commands work identically. The only difference is where the work happens.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Keep local folders and cloud projects aligned.
+::
+
+::card
+---
+title: Cloud CLI
+icon: i-lucide-terminal
+to: /cloud/cloud-cli
+---
+The full command walkthrough for cloud workflows.
+::
+
+::card
+---
+title: API Keys
+icon: i-lucide-key
+to: /cloud/api-keys
+---
+Credentials for cloud-routed projects.
+::
+:::
diff --git a/content/4.teams/.navigation.yml b/content/04.teams/.navigation.yml
similarity index 100%
rename from content/4.teams/.navigation.yml
rename to content/04.teams/.navigation.yml
diff --git a/content/04.teams/1.about.md b/content/04.teams/1.about.md
new file mode 100644
index 0000000..27bd31d
--- /dev/null
+++ b/content/04.teams/1.about.md
@@ -0,0 +1,112 @@
+---
+title: Basic Memory Teams
+description: One shared knowledge base for your team and every AI agent connected to it.
+---
+
+Basic Memory Teams puts your whole team — and every AI agent they use — on one shared memory. Anything a teammate writes is immediately available to everyone else and to their agents: a decision captured in one person's Claude session becomes context for another's Codex run. Edit notes together in real time, hand work off between humans and agents, and build one connected knowledge base instead of scattered copies.
+
+::note{icon="i-lucide-users"}
+**Teams requires a subscription with one or more seats.** Billing is per seat. Joining or starting a team doesn't change anything about your existing setup — your personal cloud subscription (if you have one) and any local projects keep working exactly as before. Teams adds a team workspace alongside them.
+::
+
+---
+
+## Workspaces
+
+Your account can have more than one workspace. Each keeps its own projects, notes, and members.
+
+| Workspace | Who can access it | Notes |
+|-----------|-------------------|-------|
+| **Local** | Just you, on your machine | No team features; runs entirely on your computer |
+| **Personal** | Just you | Your personal cloud subscription and notes |
+| **Team** | Your team | Shared projects, members, roles, and seats |
+
+In the app, each workspace — personal and every team — appears as its own section in the sidebar. Projects and notes are scoped to the workspace you're in; local projects stay on your machine, reachable from the CLI and MCP alongside them.
+
+---
+
+## Working together in real time
+
+When two people open the same note, they see each other's edits as they happen. The editor is built on CRDTs (Yjs), so every keystroke syncs instantly across collaborators with no merge conflicts to resolve. A presence avatar appears in the note header for each active collaborator — each one gets a distinct color so you can tell at a glance who's typing where.
+
+### AI agents as collaborators
+
+AI agents work with the shared knowledge base through MCP. They read the shared knowledge graph for context and write structured observations and relations back into it, so the more your team uses Basic Memory, the better your AI gets at answering from your team's actual knowledge. When an agent writes or updates a note, the change appears in the Activity feed alongside your teammates' edits.
+
+### Activity feed
+
+The **Activity** view in the app keeps you aware of what's happening across the workspace. It shows operations in progress (imports, indexing, large edits) and recent completed changes — from every team member and agent — with direct links to the affected notes.
+
+---
+
+## File history — undo on the file level
+
+Every save creates a new version of a note, automatically. If a teammate overwrites something or an agent edits go sideways, open **File history** on the note to step back through the timeline, compare any version against the current one, and merge content back in. Restored content saves as a _new_ version, so nothing is ever lost.
+
+See [File History](/cloud/file-history) for the full reference, or [Restore Lost Content](/cloud/restore-lost-content) for the broader recovery decision guide (File history for a single note, Snapshots for bigger rollbacks).
+
+---
+
+## Security and isolation
+
+Each team gets its **own** isolated database and file storage in the cloud — there is no shared tenancy at the data layer. Your team's knowledge is physically separated from every other team's. Authentication runs through [WorkOS AuthKit](https://workos.com/authkit) for enterprise-grade identity management.
+
+---
+
+## Explore Teams
+
+:::card-group
+::card
+---
+title: Members and Roles
+icon: i-lucide-users
+to: /teams/members-and-roles
+---
+Roles, member statuses, invitations, and member management.
+::
+
+::card
+---
+title: Seats and Billing
+icon: i-lucide-credit-card
+to: /teams/seats-and-billing
+---
+Per-seat billing, seat usage, and the grace period.
+::
+
+::card
+---
+title: Team Projects
+icon: i-lucide-folder-kanban
+to: /teams/team-projects
+---
+Project visibility, sharing, and workspace targeting.
+::
+
+::card
+---
+title: Joining a Team Workspace
+icon: i-lucide-door-open
+to: /teams/join-a-team
+---
+Got an invite? Your first-day walkthrough.
+::
+
+::card
+---
+title: Copy Content Between Workspaces
+icon: i-lucide-copy
+to: /teams/copy-between-workspaces
+---
+Bring personal notes into the team workspace.
+::
+
+::card
+---
+title: Partners (MSP)
+icon: i-lucide-handshake
+to: /partners/about
+---
+Run Basic Memory for your customers as a managed service provider.
+::
+:::
diff --git a/content/04.teams/2.members-and-roles.md b/content/04.teams/2.members-and-roles.md
new file mode 100644
index 0000000..24fd272
--- /dev/null
+++ b/content/04.teams/2.members-and-roles.md
@@ -0,0 +1,102 @@
+---
+title: Members and Roles
+description: Invite teammates, assign roles, and manage members in a team workspace.
+---
+
+Every member of a team has a role that determines what they can do, and a status that tracks their seat. This page is the canonical reference for both, plus the inviter's side of getting people in. Joining a team yourself? See [Joining a Team Workspace](/teams/join-a-team).
+
+---
+
+## Roles
+
+| Role | Can do |
+|------|--------|
+| **Viewer** | Read-only access to workspace projects and notes (can edit a [shared project](/teams/team-projects) if granted edit access on it) |
+| **Editor** | Read and write notes, and create projects |
+| **User Admin** | Everything an editor can, plus manage members and invitations, view the audit log, and download project archives |
+| **Admin** | Everything a user admin can, plus manage API keys |
+| **Owner** | Everything an admin can, plus manage billing, snapshots, rename the team, and transfer ownership. A team can have only one member with the Owner role. |
+
+Once an invitation has been extended to a user, members also have a **status**:
+
+- **Pending** — invited, but hasn't finished linking their account yet
+- **Active** — accepted the invitation, claiming a seat, with full access according to their role
+- **Suspended** — access paused because the team stayed over its seat allocation past the 14-day grace period; reactivating is instant once a seat frees up
+- **Deactivated** — removed from the team; their history is preserved and their seat is released
+
+::theme-image{light="/screenshots/cloud-app/v2-team-invite-light.png" dark="/screenshots/cloud-app/v2-team-invite-dark.png" alt="Team members list"}
+::
+
+---
+
+## Inviting members
+
+Owners, admins, and user admins invite people by email from **Settings → Members** — click **Invite Member**.
+
+::steps
+### Send an invitation
+
+Enter the person's email address and choose a role. You can assign any role at or below your own — Owner is never an invite option.
+
+::theme-image{light="/screenshots/cloud-app/v2-team-invitation-light.png" dark="/screenshots/cloud-app/v2-team-invitation-dark.png" alt="Invite Member dialog"}
+::
+
+### They accept by email
+
+The invitee gets an email with an accept link, signs in with the invited address, and becomes an active member. The full invitee-side walkthrough is on [Joining a Team Workspace](/teams/join-a-team).
+
+::theme-image{light="/screenshots/cloud-app/v2-team-accept-invite-email.png" dark="/screenshots/cloud-app/v2-team-accept-invite-email.png" alt="Email invitation"}
+::
+::
+
+::note{icon="i-lucide-credit-card"}
+**Seats are assigned when an invitation is claimed, not when it's sent.** Inviting someone doesn't consume a seat until they accept — so a pending invitation won't be billed until the person joins.
+::
+
+---
+
+## Managing members
+
+From **Settings → Members**, anyone with the **User Admin** role or above can:
+
+- **Change a member's role** — promote a viewer to editor, or vice versa. Roles can only be assigned at or below your own, and only the owner can act on another owner.
+- **Deactivate a member** — removes their access and frees their seat. Their authored history stays intact.
+- **Reactivate a member** — restores access, reassigning a seat if one is available.
+
+Only the **owner** can:
+
+- **Transfer ownership** — hand the workspace (and its subscription) to another member. The new owner takes over billing and management.
+- **Rename the team.**
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Seats and Billing
+icon: i-lucide-credit-card
+to: /teams/seats-and-billing
+---
+Per-seat billing, the grace period, and seat management.
+::
+
+::card
+---
+title: Joining a Team Workspace
+icon: i-lucide-door-open
+to: /teams/join-a-team
+---
+The invitee's first-day walkthrough.
+::
+
+::card
+---
+title: Team Projects
+icon: i-lucide-folder-kanban
+to: /teams/team-projects
+---
+Project visibility, sharing, and workspace targeting.
+::
+:::
diff --git a/content/04.teams/3.seats-and-billing.md b/content/04.teams/3.seats-and-billing.md
new file mode 100644
index 0000000..2aaa059
--- /dev/null
+++ b/content/04.teams/3.seats-and-billing.md
@@ -0,0 +1,59 @@
+---
+title: Seats and Billing
+description: Per-seat team billing, seat usage, and the grace period.
+---
+
+Teams billing is **per seat**. The number of seats on your subscription sets how many active members the workspace can have.
+
+- Each active member occupies one seat.
+- Deactivating a member frees their seat for someone else.
+- Reactivating a member requires an available seat.
+- Pending invitations don't consume a seat until they're accepted.
+- If your team grows past your current seat allocation, there's a **14-day grace period** before any restrictions kick in — so a new hire never gets locked out while you're adding seats. Members over the limit after the grace period are **suspended** (access paused, data intact) until a seat frees up.
+
+---
+
+## Managing seats and payment
+
+Manage seats and payment from **Settings → Billing**.
+
+::theme-image{light="/screenshots/cloud-app/v2-team-manage-billing-light.png" dark="/screenshots/cloud-app/v2-team-manage-billing-dark.png" alt="Seats and billing"}
+::
+
+Track current seat usage from the same screen:
+
+::theme-image{light="/screenshots/cloud-app/v2-team-usage-light.png" dark="/screenshots/cloud-app/v2-team-usage-dark.png" alt="Team seat usage"}
+::
+
+Team details, the billing contact, and seat usage are also visible under **Settings → Teams**:
+
+::theme-image{light="/screenshots/cloud-app/v2-settings-teams-light.png" dark="/screenshots/cloud-app/v2-settings-teams-dark.png" alt="Team settings and seat usage"}
+::
+
+::note
+Billing and ownership transfer are **owner** actions — see [Members and Roles](/teams/members-and-roles) for who can do what.
+::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Members and Roles
+icon: i-lucide-users
+to: /teams/members-and-roles
+---
+Roles, invitations, and member management.
+::
+
+::card
+---
+title: Partners (MSP)
+icon: i-lucide-handshake
+to: /partners/about
+---
+Managing Basic Memory for customers? Partner billing works differently.
+::
+:::
diff --git a/content/04.teams/4.team-projects.md b/content/04.teams/4.team-projects.md
new file mode 100644
index 0000000..96d5039
--- /dev/null
+++ b/content/04.teams/4.team-projects.md
@@ -0,0 +1,106 @@
+---
+title: Team Projects
+description: Project visibility, sharing, and working with team projects from the app, MCP, and CLI.
+---
+
+Projects are how a team organizes its knowledge base. Every project in a team workspace has a visibility, and every member's access follows their [role](/teams/members-and-roles).
+
+---
+
+## Project visibility
+
+Team projects come in three visibilities. The right one depends on who needs to see the work:
+
+| Visibility | Who can see it | When to use |
+|------------|----------------|-------------|
+| **Standard** (`workspace`) — _default_ | Everyone in the team, based on their team role | Most team work — the open, shared knowledge base |
+| **Shared** (`shared`) | Only people you grant access to, each with **view** or **edit** access | Sensitive topics (hiring, contracts, security audits) where you want a controlled group |
+| **Private** (`private`) | Just you | Drafts and scratch work that isn't ready for the team |
+
+When you create a cloud project, you can set its visibility from the CLI:
+
+```bash
+# Standard — visible to everyone in the team workspace (default)
+bm project add team-wiki --cloud --workspace acme --visibility workspace
+
+# Shared — only people you grant access to
+bm project add hiring-2026 --cloud --workspace acme --visibility shared
+
+# Private — just you
+bm project add my-scratch --cloud --workspace acme --visibility private
+```
+
+See the [CLI Reference](/reference/cli-reference) for full `bm project add` options.
+
+---
+
+## Working with team projects
+
+Once you're part of a team, projects show up everywhere you work:
+
+- **In the app** — Select the project in the sidebar.
+- **In your AI assistant (MCP)** — your assistant's project list spans every cloud workspace you can access, so it reaches team projects without extra setup.
+- **In the CLI** — `bm project list` shows projects across all your workspaces.
+
+### Workspace commands
+
+```bash
+# List the cloud workspaces available to you
+bm cloud workspace list
+
+# Set the default workspace for CLI and MCP routing
+bm cloud workspace set-default acme
+```
+
+You can also target a specific workspace when creating a project, either from the CLI (`--workspace`) or from MCP (`create_memory_project(workspace="acme")`).
+
+### Targeting a team project explicitly
+
+If a project name exists in more than one workspace (say, `research` in both your personal and team workspaces), resolution prefers your default workspace — or asks you to disambiguate. To be explicit, use a **workspace-qualified memory URL**:
+
+```text
+memory://acme/research/architecture-decisions
+```
+
+The form is `memory://<workspace-slug>/<project>/<path>`. From the CLI, pass `--workspace` on the command instead.
+
+---
+
+## Bringing existing notes into a team project
+
+When you join (or start) a team, you'll often want to promote work from your personal workspace into the shared one. Cross-workspace transfers are a **copy** workflow — export from the source, import into the target, verify, then optionally delete the original.
+
+See [Copy Content Between Workspaces](/teams/copy-between-workspaces) for the project ZIP, single-note, MCP, and local-sync workflows, along with caveats around wikilinks, permissions, and share links.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Copy Content Between Workspaces
+icon: i-lucide-copy
+to: /teams/copy-between-workspaces
+---
+Move personal notes into the team workspace.
+::
+
+::card
+---
+title: Local & Cloud Routing
+icon: i-lucide-route
+to: /cloud/routing
+---
+Run some projects locally and others in the cloud.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Full `bm project` and `bm cloud workspace` commands.
+::
+:::
diff --git a/content/4.teams/2.join-a-team.md b/content/04.teams/5.join-a-team.md
similarity index 72%
rename from content/4.teams/2.join-a-team.md
rename to content/04.teams/5.join-a-team.md
index 246f8d5..3131e3d 100644
--- a/content/4.teams/2.join-a-team.md
+++ b/content/04.teams/5.join-a-team.md
@@ -15,9 +15,9 @@ You got an invite to a Basic Memory [team workspace](/teams/about). This page wa
 
 Open the invitation email and click the **Accept invitation** link. It opens an accept page in the app.
 
-- Sign in with the email the invite was sent to.
+- Click **Accept** — the app then routes you through sign-in.
+- Sign in with the email the invite was sent to (you'll create an account during sign-in if you don't have one).
 - If you're already signed in with a different account, the app will prompt you to sign in again with the invited email.
-- If this is your first time, you'll create an account during sign-in.
 
 On first sign-in, your account is linked to the pending membership, and you become an active team member.
 
@@ -26,19 +26,11 @@ On first sign-in, your account is linked to the pending membership, and you beco
 
 ## 2. Find the projects
 
-The sidebar shows the teams and projects you have access to. Open one to see its folders and notes.
+Your team appears as its own section in the sidebar, alongside your personal workspace, with its projects listed underneath. Open one to see its folders and notes.
 
-Your **role** determines what you can do:
+Your **role** determines what you can do — from read-only **Viewer** up to **Owner**, with Editor, User Admin, and Admin tiers in between. The full capability table is on [Members and Roles](/teams/members-and-roles).
 
-| Role | You can |
-|------|---------|
-| **Viewer** | Read-only access to projects and notes |
-| **Editor** | Read and write notes, and create projects |
-| **User Admin** | Everything an editor can, plus manage members and invitations |
-| **Admin** | Everything a user admin can, plus manage API keys, snapshots, and view audit log |
-| **Owner** | Everything an admin can, plus manage billing, rename team, and transfer ownership. A team can have only one member with the Owner role. |
-
-Not sure of your role? Open **Settings → Teams** to see it next to your name. If you need a different role, ask an owner or .
+Not sure of your role? Open **Settings → Teams** to see your teams and your role in each. If you need a different role, ask an owner, admin, or user admin — they manage members from **Settings → Members**.
 
 ---
 
@@ -48,7 +40,7 @@ Your assistant works with the team workspace through the same MCP endpoint as yo
 
 - **Claude Desktop / Claude Code** — see [Claude Desktop](/integrations/claude-desktop) or [Claude Code](/integrations/claude-code). Use the OAuth flow; your assistant will see team projects automatically once you've accepted the invite.
 - **ChatGPT** — see [ChatGPT](/integrations/chatgpt).
-- **Codex / Cursor / VS Code / Obsidian** — see the [integrations index](/integrations/claude-desktop).
+- **Codex / Cursor / VS Code / Obsidian** — see the [integrations index](/integrations).
 - **CLI** — `bm cloud login` once, then `bm project list` shows projects across every workspace you can access (personal and team).
 
 ::tip
@@ -67,7 +59,7 @@ bm cloud workspace set-default acme
 bm project list --workspace acme
 ```
 
-From MCP, pass the workspace through `create_memory_project(workspace="acme")` or use a [project-prefixed permalink](/concepts/memory-urls).
+From MCP, pass the workspace through `create_memory_project(workspace="acme")`, or reference notes with a workspace-qualified memory URL — `memory://acme/research/note-title`. See [Team Projects](/teams/team-projects) for the full targeting guide.
 
 ---
 
@@ -77,7 +69,7 @@ A few good first steps in any new team workspace:
 
 - **Browse the project tree** to see what your team already has.
 - **Search a topic you care about** — see what's already been written.
-- **Pin** the projects or notes you'll come back to.
+- **Pin** the notes you'll come back to.
 - **Read the team's conventions** if they've documented any (look for an `onboarding`, `README`, or `team-norms` note).
 
 ---
@@ -90,7 +82,8 @@ Already have personal notes you want to share with the team? Cross-workspace tra
 
 ## Related
 
-- [Teams](/teams/about) — workspaces, roles, invitations, billing
+- [Teams](/teams/about) — the team workspace overview
+- [Members and Roles](/teams/members-and-roles) — roles, invitations, member management
 - [Web App](/cloud/web-app) — the three-pane editor and shortcuts
 - [Copy Content Between Workspaces](/teams/copy-between-workspaces) — bring personal notes into the team workspace
-- [Integrations](/integrations/claude-desktop) — connect your AI assistant
+- [Integrations](/integrations) — connect your AI assistant
diff --git a/content/4.teams/3.copy-between-workspaces.md b/content/04.teams/6.copy-between-workspaces.md
similarity index 89%
rename from content/4.teams/3.copy-between-workspaces.md
rename to content/04.teams/6.copy-between-workspaces.md
index 2e0ad02..78bb044 100644
--- a/content/4.teams/3.copy-between-workspaces.md
+++ b/content/04.teams/6.copy-between-workspaces.md
@@ -15,7 +15,7 @@ You'll often want to promote work from your personal workspace into a [team work
 
 A few things to know about any cross-workspace copy:
 
-- **You need read access** to the source project and **write access** (editor or owner) to the target project.
+- **You need read access** to the source project and **write access** to the target project. Downloading a whole project as a ZIP additionally requires the **User Admin** role or above in the source workspace.
 - **Imported content takes on the target's permissions.** It picks up the target workspace's project visibility, sharing rules, and member access. Source-side permissions don't follow it.
 - **Share links don't follow content.** Existing [Shared Notes](/cloud/shared-notes) links live on the original. If you want a shared link in the new location, create one there after importing.
 - **Wikilinks are preserved as text.** A `[[Wiki Link]]` only _resolves_ in the target workspace if the linked note is also present there. For best results, **copy linked notes together** so the graph stays intact.
@@ -34,7 +34,7 @@ In the app, switch to the **source workspace** and open **Settings → Projects*
 
 ### Switch to the target
 
-Switch to the **target workspace** in the workspace selector.
+Find the **target workspace's** section in the sidebar.
 
 ### Import the ZIP
 
@@ -101,12 +101,12 @@ See the [MCP Tools Reference](/reference/mcp-tools-reference) for full parameter
 
 ## Copy via local sync (power-user)
 
-If both projects already have [local sync](/cloud/cloud-sync) set up, you can move files in the filesystem and let bisync push them up:
+If both projects already have [local sync](/cloud/cloud-sync) set up, you can move files in the filesystem and push them up:
 
-1. Run `bm cloud bisync` for both projects so each is up to date locally.
+1. Run `bm cloud pull` for both projects so each is up to date locally.
 2. In your file manager (or with `cp -r`), copy the notes or folder from the source project's local path into the target project's local path.
-3. Run `bm cloud bisync --name <target-project>` to push the new files to the target workspace.
-4. Verify in the app, then delete from the source side and bisync again.
+3. Run `bm cloud push --name <target-project>` to upload the new files to the target workspace.
+4. Verify in the app, then delete the originals from the source project in the app or via MCP (push is additive, so local deletions don't propagate).
 
 This is the fastest option when you have lots of notes and both projects already sync to your machine.
 
@@ -122,6 +122,6 @@ Within a single workspace, you can rename and move notes and folders freely from
 
 - [Teams](/teams/about) — workspaces, roles, and project sharing
 - [Web App](/cloud/web-app) — projects, downloads, and imports
-- [Cloud Sync](/cloud/cloud-sync) — bidirectional sync setup
+- [Cloud Sync](/cloud/cloud-sync) — push/pull sync setup
 - [Shared Notes](/cloud/shared-notes) — public links for individual notes
 - [MCP Tools Reference](/reference/mcp-tools-reference) — `read_note`, `write_note`, `delete_note`
diff --git a/content/05.partners/.navigation.yml b/content/05.partners/.navigation.yml
new file mode 100644
index 0000000..2365a9a
--- /dev/null
+++ b/content/05.partners/.navigation.yml
@@ -0,0 +1,2 @@
+title: Partners
+icon: i-lucide-handshake
diff --git a/content/05.partners/1.about.md b/content/05.partners/1.about.md
new file mode 100644
index 0000000..6748cf7
--- /dev/null
+++ b/content/05.partners/1.about.md
@@ -0,0 +1,99 @@
+---
+title: Partner Program
+description: Run Basic Memory for your customers — isolated workspaces, SSO, consolidated invoicing, and a full audit trail for MSPs.
+---
+
+The Basic Memory partner program is built for **managed service providers** who operate Basic Memory on behalf of their customers. You provision and manage customer organizations from a dedicated partner portal; Basic Memory bills you once, and you bill your customers however you like.
+
+What you get as a partner:
+
+- **A partner portal to provision customers** — create a customer and their [isolated workspace](/partners/customer-provisioning) is live in minutes: its own database and file storage, physically separated from every other tenant
+- **SSO for your customers** — connect each customer's identity provider ([WorkOS-brokered](/partners/customer-sso)); their users sign in with corporate credentials and can be provisioned automatically on first sign-in
+- **Consolidated invoicing** — one usage-based invoice to your account, with [per-customer statements and CSV exports](/partners/billing) to drive your own rebilling
+- **A full audit log** — every action your staff takes is [recorded](/partners/team-and-audit), and customers see the administrative actions you perform on their workspace, labeled as their MSP
+
+Each customer gets the full Basic Memory Cloud product: the web app, the hosted MCP endpoint for their AI tools, team members and roles, snapshots, and file history — one shared memory for their whole organization and every agent connected to it.
+
+::note{icon="i-lucide-handshake"}
+**The partner program is invite-only.** Basic Memory sets up your partner account and emails your designated owner a claim link. To become a partner, contact us at `hello@basicmemory.com` — and see [basicmemory.com/partners](https://basicmemory.com/partners) for the program overview.
+::
+
+---
+
+## The partner portal
+
+Partner staff work from the portal at **`/partner`**, separate from the customer-facing app:
+
+| Section | What it's for |
+|---------|---------------|
+| **Dashboard** | Seat commitment, utilization, and period-to-date billing at a glance |
+| **Customers** | Managed customer organizations and their workspaces |
+| **Billing** | Usage statements behind your official invoices, CSV exports, seat purchases |
+| **Team** | Your partner staff and their scoped roles |
+| **Audit Log** | A record of everything partner staff do |
+
+A **Getting started** checklist on the Dashboard walks new partners through setup: claim your account, invite your team, add your first customer, set up customer SSO, and review billing.
+
+---
+
+## Getting set up
+
+::steps
+### Claim your invitation
+
+Basic Memory emails your account owner a one-time claim link. Open it, sign in, accept the Terms of Service, and claim the invitation. You can claim while the account is still in draft.
+
+### Activate your subscription
+
+Until payment is set up, the Dashboard shows an **Activate your subscription** banner. An owner or billing member clicks **Set up payment** and completes checkout. Activation is automatic once payment lands — customer onboarding, seats, and billing unlock immediately.
+
+### Invite your team
+
+From **Team**, invite staff with [scoped roles](/partners/team-and-audit). Each invitee gets a one-time claim link.
+
+### Add your first customer
+
+From **Customers**, click **Add customer**. This [provisions the customer's isolated workspace](/partners/customer-provisioning).
+::
+
+---
+
+## Explore
+
+:::card-group
+::card
+---
+title: Customer Provisioning
+icon: i-lucide-building-2
+to: /partners/customer-provisioning
+---
+Add customers, manage seat caps, and handle the customer lifecycle.
+::
+
+::card
+---
+title: Customer SSO
+icon: i-lucide-key-round
+to: /partners/customer-sso
+---
+Connect each customer's identity provider with JIT provisioning.
+::
+
+::card
+---
+title: Billing
+icon: i-lucide-receipt
+to: /partners/billing
+---
+Seat-day metering, consolidated invoices, and rebilling statements.
+::
+
+::card
+---
+title: Team and Audit
+icon: i-lucide-shield-check
+to: /partners/team-and-audit
+---
+Partner staff roles and the full audit trail.
+::
+:::
diff --git a/content/05.partners/2.customer-provisioning.md b/content/05.partners/2.customer-provisioning.md
new file mode 100644
index 0000000..e04516f
--- /dev/null
+++ b/content/05.partners/2.customer-provisioning.md
@@ -0,0 +1,62 @@
+---
+title: Customer Provisioning
+description: Create customer workspaces, set seat caps, and manage the customer lifecycle from the partner portal.
+---
+
+The **Customers** page in the partner portal is where you create and operate customer organizations. Each customer gets a **dedicated, isolated workspace** — its own database and file storage, physically separated from every other customer and tenant. There is no shared data layer between your customers.
+
+---
+
+## Add a customer
+
+Click **Add customer** on the Customers page. Provisioning creates the customer's organization and workspace automatically — no infrastructure work on your side.
+
+The customer list shows each customer's **status, workspace, seat cap, JIT state, and billing label**. SSO state lives on the customer's detail page.
+
+---
+
+## Seat caps
+
+Each customer can have an optional **seat cap** — a per-customer limit on assigned seats:
+
+- Leave the cap blank for no per-customer limit; the customer is then bounded only by your account-wide [seat commitment](/partners/billing).
+- If an assignment would exceed the customer's cap, it's denied until you raise the cap.
+- The customer's detail page shows assigned seats, cap, available seats, and utilization.
+
+---
+
+## Customer lifecycle
+
+From a customer's detail page:
+
+- **Suspend** — pauses access for all of the customer's users. Their data is kept and seats stay assigned.
+- **Reactivate** — restores access for the customer's users.
+- **Archive** — the offboarding path: access ends and all open seats are closed. You confirm by typing the customer's slug.
+
+::note{icon="i-lucide-eye"}
+**Transparency for your customers.** Administrative actions your staff take on a customer — lifecycle changes (create, suspend, reactivate, archive) and SSO changes — appear in the customer's own audit trail, labeled as performed by their MSP. Billing-metadata updates stay internal to your portal.
+::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Customer SSO
+icon: i-lucide-key-round
+to: /partners/customer-sso
+---
+Connect the customer's identity provider before their users sign in.
+::
+
+::card
+---
+title: Billing
+icon: i-lucide-receipt
+to: /partners/billing
+---
+How customer seats turn into seat-days on your invoice.
+::
+:::
diff --git a/content/05.partners/3.customer-sso.md b/content/05.partners/3.customer-sso.md
new file mode 100644
index 0000000..0d58bb4
--- /dev/null
+++ b/content/05.partners/3.customer-sso.md
@@ -0,0 +1,58 @@
+---
+title: Customer SSO
+description: Connect each customer's identity provider through WorkOS, with JIT provisioning on first sign-in.
+---
+
+Customers sign in with **their own identity provider** — for example Microsoft Entra ID via SAML — brokered through WorkOS. You configure it per customer from the SSO panel on the customer's detail page.
+
+---
+
+## Set up SSO
+
+::steps
+### Verify the customer's email domain
+
+Domain verification is the entry point — enter the customer's domain (e.g. `acme.com`) and verify it. The SSO setup controls appear once a domain is verified.
+
+### Open the setup portal
+
+Click **Start SSO setup** (or **Reconfigure SSO**). This opens the **WorkOS Admin Portal directly in a new tab** — portal links expire about 5 minutes after generation, so there's nothing to copy or email. Complete the identity-provider connection there yourself, or on a screen-share with the customer's IT admin.
+
+### Optionally require SSO
+
+Turn on the require-SSO policy to make the customer's identity provider the only sign-in path for their users.
+::
+
+---
+
+## JIT provisioning
+
+With SSO active and **JIT (just-in-time) provisioning** enabled, a user from the customer's verified domain is provisioned into the customer's workspace automatically on first sign-in — and starts consuming a seat.
+
+::warning
+**JIT is on by default for new customers.** As soon as SSO is active, users from the verified domain will auto-provision and consume seats on first sign-in. If you want to control membership manually, turn JIT off on the customer's detail page *before* completing SSO setup.
+::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Customer Provisioning
+icon: i-lucide-building-2
+to: /partners/customer-provisioning
+---
+Seat caps and the customer lifecycle.
+::
+
+::card
+---
+title: Billing
+icon: i-lucide-receipt
+to: /partners/billing
+---
+JIT-provisioned users consume seats — here's how they're metered.
+::
+:::
diff --git a/content/05.partners/4.billing.md b/content/05.partners/4.billing.md
new file mode 100644
index 0000000..6c4f63f
--- /dev/null
+++ b/content/05.partners/4.billing.md
@@ -0,0 +1,63 @@
+---
+title: Billing
+description: Consolidated invoicing for MSPs — seat-day metering, committed minimums, and per-customer rebilling statements.
+---
+
+Basic Memory bills your partner account **once, monthly**, based on actual seat usage across all your customers — with per-customer statements so you can rebill on your own terms. There is no fixed recurring charge beyond your committed-seat minimum.
+
+---
+
+## How seat-days are metered
+
+- Billing periods are **UTC calendar months**.
+- Each UTC date on which a member has an active seat assignment counts as **one seat-day** for that member. Adding and removing the same member on the same date counts once; a seat removed mid-day still counts for that day.
+- `seat-months = seat-days ÷ days in the month`.
+- Your monthly charge is **whichever is larger**: actual seat-months used, or your committed-seat minimum (prorated for partial months).
+
+This means short-lived users cost you days, not months — and your floor is predictable.
+
+---
+
+## The Billing tab
+
+- **Billing periods** — actual, minimum, and billable seat-months per period, with subtotal, payment status, and a link to the official invoice.
+- **Customer statements** — per-customer seat-days, seat-months, and active-user counts for any period, with **Export CSV** for your PSA or accounting system.
+- **Billing portal** — opens the payment portal for official invoices and payment methods.
+
+::note{icon="i-lucide-receipt"}
+Customer statements and CSV exports are **rebilling support data for your own invoicing** — they are not invoices. The only official invoice is the one issued to your partner account.
+::
+
+---
+
+## Seats and capacity
+
+- The Dashboard shows committed seats, assigned seats, available seats, and utilization.
+- **Add seats** schedules a commitment increase effective at the next UTC month boundary. Seat purchases are an **Owner or Billing role** action.
+- If a customer's [seat cap](/partners/customer-provisioning) would be exceeded, new assignments to that customer are denied until you raise the cap.
+- At your account-wide commitment: with overage disabled, new assignments are blocked until a scheduled increase lands; with overage enabled, extra seats are allowed and metered as overage.
+- Billing contacts get an email alert at **90% utilization** or when overage starts accruing.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Customer Provisioning
+icon: i-lucide-building-2
+to: /partners/customer-provisioning
+---
+Per-customer seat caps and lifecycle.
+::
+
+::card
+---
+title: Team and Audit
+icon: i-lucide-shield-check
+to: /partners/team-and-audit
+---
+Which roles can purchase seats and view billing.
+::
+:::
diff --git a/content/05.partners/5.team-and-audit.md b/content/05.partners/5.team-and-audit.md
new file mode 100644
index 0000000..9dfd856
--- /dev/null
+++ b/content/05.partners/5.team-and-audit.md
@@ -0,0 +1,62 @@
+---
+title: Team and Audit
+description: Partner staff roles with scoped capabilities, and the full audit trail of partner actions.
+---
+
+Your partner staff get **scoped roles** — sales and support people don't need billing access, and billing people don't need to touch SSO. Everything anyone does is recorded in the audit log.
+
+---
+
+## Partner staff roles
+
+| Role | Can do |
+|------|--------|
+| **Owner** | Full control, including ownership transfer and seat purchases. An account always keeps at least one owner, and only owners can grant the owner role |
+| **Admin** | Manage customers, SSO, team, and billing — except seat purchases (Owner and Billing only) |
+| **Billing** | Billing reads, the billing portal, and seat purchases |
+| **Support** | Customer reads and SSO setup links |
+| **Viewer** | Read-only customer and billing views |
+
+Manage staff from the **Team** page: invite by email with a role (each invitee gets a one-time claim link), suspend and reactivate members, and revoke pending invitations.
+
+::note
+Partner staff roles are separate from the [team roles](/teams/members-and-roles) inside customer workspaces — partner roles govern the portal, team roles govern a workspace.
+::
+
+---
+
+## The audit log
+
+The **Audit Log** page records everything partner staff do — customer lifecycle changes, SSO configuration, seat assignments, team management, billing actions — with who did it and when.
+
+Your customers get transparency too: administrative actions on their organization — lifecycle changes (create, suspend, reactivate, archive) and SSO changes — appear in **their** audit trail, labeled as performed by their MSP. Your billing metadata stays internal to your portal.
+
+---
+
+## Getting help
+
+Partner account, billing, and provisioning questions are handled directly by the Basic Memory team — email `hello@basicmemory.com`.
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Partner Program
+icon: i-lucide-handshake
+to: /partners/about
+---
+The program overview and getting set up.
+::
+
+::card
+---
+title: Team Roles (customer workspaces)
+icon: i-lucide-users
+to: /teams/members-and-roles
+---
+The five roles inside each customer's workspace.
+::
+:::
diff --git a/content/5.local/.navigation.yml b/content/06.local/.navigation.yml
similarity index 100%
rename from content/5.local/.navigation.yml
rename to content/06.local/.navigation.yml
diff --git a/content/5.local/1.local-install.md b/content/06.local/1.local-install.md
similarity index 59%
rename from content/5.local/1.local-install.md
rename to content/06.local/1.local-install.md
index a7bf0cb..4cb69b4 100644
--- a/content/5.local/1.local-install.md
+++ b/content/06.local/1.local-install.md
@@ -5,6 +5,10 @@ description: Install Basic Memory locally and choose where notes live.
 
 Local mode runs the MCP server on your machine and stores notes in local folders you control.
 
+::note
+Followed [Quickstart: Local](/start-here/quickstart-local)? You've already done this — continue to [Set Up Local Projects](/local/getting-started) or [CLI Basics](/local/cli-basics).
+::
+
 ## Install the CLI
 
 ::code-group
@@ -23,9 +27,9 @@ brew install basic-memory
 If you install with Homebrew: `brew trust` tells Homebrew you accept code from this third-party tap. Recent Homebrew versions warn about untrusted taps, and Homebrew 6 will require the trust step before installing or upgrading from them. On older Homebrew versions the command doesn't exist yet — just skip it.
 ::
 
-## Start the MCP server
+## Connect your MCP client
 
-Configure your MCP client to run the server:
+Configure your MCP client to run the local server. For Claude Desktop, add this to `claude_desktop_config.json` ([file locations per platform](/integrations/claude-desktop#local-setup)):
 
 ```json [claude_desktop_config.json]
 {
@@ -38,16 +42,15 @@ Configure your MCP client to run the server:
 }
 ```
 
-Restart your MCP client after editing the config.
+::note
+**Installed with Homebrew?** Use `"command": "basic-memory", "args": ["mcp"]` instead — `uvx` only exists if you installed uv. If your client can't find the command, use the full path (`which basic-memory`).
+::
+
+Restart your MCP client after editing the config. Other clients — Codex, Cursor, VS Code, Gemini — are covered in [Integrations](/integrations).
 
 ## Choose where notes live
 
-By default, notes are stored in a `main` project under `~/basic-memory`. You can point Basic Memory to any folder by creating a project and setting it as default.
-
-```bash
-bm project add "work" ~/Documents/work-notes
-bm project default "work"
-```
+By default, notes are stored in a `main` project under `~/basic-memory` — see [Set Up Local Projects](/local/getting-started) to point Basic Memory at any folder.
 
 ## Next steps
 
diff --git a/content/1.start-here/4.getting-started.md b/content/06.local/2.getting-started.md
similarity index 90%
rename from content/1.start-here/4.getting-started.md
rename to content/06.local/2.getting-started.md
index 407cb90..b6a98f2 100644
--- a/content/1.start-here/4.getting-started.md
+++ b/content/06.local/2.getting-started.md
@@ -3,10 +3,8 @@ title: Getting Started
 description: Configure where notes are saved and manage multiple projects.
 ---
 
-Ready to set up Basic Memory? Start with the quickstart guides:
+Already installed? (If not, start with [Quickstart: Local](/start-here/quickstart-local).) This page covers what comes next: where your notes are saved, working with multiple projects, and keeping Basic Memory updated.
 
-:::card-group
-::card
 ---
 title: "Quickstart: Cloud"
 icon: i-lucide-cloud
@@ -35,13 +33,13 @@ By default, Basic Memory saves notes in a project called `main` in `~/basic-memo
 
 Ask your AI assistant directly:
 
-```bash
+```text
 Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory
 ```
 
 Then:
 
-```bash
+```text
 Set the default project to "my project"
 ```
 
@@ -80,7 +78,7 @@ When you start a conversation, the AI will:
 4. Remember your choice throughout the session
 
 **Example:**
-```bash
+```text
 You: "Let's work on documentation"
 
 Claude: I see you have 3 projects: main, work-notes, personal
@@ -101,12 +99,10 @@ You: "Create a new project called 'work-notes' in ~/Documents/work"
 
 **For users who primarily work in one project:**
 
-Set a default fallback project in `~/.basic-memory/config.json`:
+Set a default fallback project — it's the same setting the command above writes:
 
-```json
-{
-  "default_project": "main"
-}
+```bash
+basic-memory project default "main"
 ```
 
 With this set, the AI uses your default project when no project is specified.
diff --git a/content/5.local/2.cli-basics.md b/content/06.local/3.cli-basics.md
similarity index 68%
rename from content/5.local/2.cli-basics.md
rename to content/06.local/3.cli-basics.md
index e779b78..a2488f8 100644
--- a/content/5.local/2.cli-basics.md
+++ b/content/06.local/3.cli-basics.md
@@ -28,21 +28,29 @@ bm project default "research"
 bm tool search-notes "authentication"
 ```
 
-Semantic modes:
+When semantic search is enabled (the default), plain searches already run in **hybrid** mode. Use these flags to force a specific retrieval mode:
 
 ```bash
 bm tool search-notes "authentication architecture" --hybrid
 bm tool search-notes "login flow" --vector
 ```
 
+Search observations by category (e.g. every `[decision]` you've captured):
+
+```bash
+bm tool search-notes --entity-type observation --category decision
+```
+
 ## Read and write notes
 
 ```bash
-bm tool read-note "docs/api-auth.md"
+bm tool read-note "docs/api-auth"
 
 echo "New note content" | bm tool write-note --title "Notes" --folder "drafts"
 ```
 
+`read-note` accepts a title, permalink, or file path as the identifier.
+
 ## Schema workflows
 
 ```bash
@@ -51,6 +59,8 @@ bm schema validate person
 bm schema diff person
 ```
 
+Infer a schema from existing notes, validate notes against it, and detect drift — see the [Schema System](/concepts/schema-system) for concepts and the full workflow.
+
 ## Format files
 
 ```bash
diff --git a/content/5.local/3.mcp-tools-local.md b/content/06.local/4.mcp-tools-local.md
similarity index 60%
rename from content/5.local/3.mcp-tools-local.md
rename to content/06.local/4.mcp-tools-local.md
index 6cc3a15..4d6aee8 100644
--- a/content/5.local/3.mcp-tools-local.md
+++ b/content/06.local/4.mcp-tools-local.md
@@ -7,7 +7,7 @@ MCP tools are the same in Cloud and Local. In local mode, they operate on folder
 
 ## Use tools in local mode
 
-When you run the local MCP server, tools read and write local project folders by default.
+Once your MCP client runs the local server (see [Local install](/local/local-install#connect-your-mcp-client)), tools read and write your local project folders — unless you've routed a project through cloud with [per-project routing](/cloud/routing).
 
 ## Common tools
 
@@ -16,12 +16,9 @@ When you run the local MCP server, tools read and write local project folders by
 - `write_note` to create or update a note
 - `edit_note` to append or replace sections
 - `schema_validate`, `schema_infer`, `schema_diff` for schema workflows
-- `build_context` for memory URL graph traversal
+- `build_context` for graph traversal via [memory:// URLs](/concepts/memory-urls)
 
-`search_notes` and `read_note` also support terminal-friendly formats:
-- `output_format=\"default\"` (structured)
-- `output_format=\"ascii\"` (plain table/preview)
-- `output_format=\"ansi\"` (colorized table/preview)
+Most tools default to `output_format="text"` (human-readable) and also accept `"json"` (machine-readable); `build_context` defaults to `"json"` — see the [MCP Tools Reference](/reference/mcp-tools-reference) for per-tool defaults.
 
 ## Example
 
diff --git a/content/5.local/4.user-guide.md b/content/06.local/5.user-guide.md
similarity index 78%
rename from content/5.local/4.user-guide.md
rename to content/06.local/5.user-guide.md
index 5ed9463..25023dd 100644
--- a/content/5.local/4.user-guide.md
+++ b/content/06.local/5.user-guide.md
@@ -60,7 +60,7 @@ Done! I've created "Authentication Approaches.md" with:
 This creates a Markdown file with semantic markup in your knowledge base.
 
 ::tip
-You can store your knowledge at any location. `~/basic-memory` is the default project location. See [Getting Started](/start-here/getting-started#choosing-where-your-notes-are-saved) for more information.
+You can store your knowledge at any location. `~/basic-memory` is the default project location. See [Getting Started](/local/getting-started#choosing-where-notes-are-saved) for more information.
 ::
 
 ### Direct File Creation
@@ -145,15 +145,13 @@ Find specific information:
 
 Basic Memory uses special `memory://` URLs to reference knowledge:
 
-### URL Formats
-
 ```bash
-memory://title                   # Reference by title
-memory://folder/title            # Reference by folder and title
-memory://permalink               # Reference by permalink
-memory://path/relation_type/*    # Follow all relations of type
+memory://coffee-brewing-methods            # Reference by permalink
+memory://coffee-brewing-methods/relates_to/*  # Follow relations
 ```
 
+See [Memory URLs](/concepts/memory-urls) for the full addressing syntax, including project-prefixed forms.
+
 ### Using Memory URLs
 
 Reference existing knowledge in conversations:
@@ -165,88 +163,71 @@ You: "Take a look at memory://coffee-brewing-methods and let's discuss improveme
 Claude will load that specific document and any related context.
 
 ::tip
-Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same (unless you configure otherwise).
+Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same (unless you enable `update_permalinks_on_move` — see [Configuration](/reference/configuration)).
 ::
 
 ---
 
-## Building Knowledge Connections
+## Memory URL resolution (local server)
 
-### Creating Relations
+At runtime, the local MCP server resolves memory URLs in this order:
 
-Use WikiLink syntax to connect knowledge:
-
-```bash
-## Relations
-- implements [[Authentication System]]
-- requires [[Database Schema]]
-- relates_to [[Security Guidelines]]
-```
+### 1. Project constraints
 
-### Common Relation Types
+If the MCP server was started with `BASIC_MEMORY_MCP_PROJECT=research`, unprefixed URLs (and URLs prefixed with `research`) resolve in the `research` project. A URL prefixed with a *different* known project returns an error rather than resolving:
 
-| Type | Use for |
-|------|---------|
-| `implements` | One thing implements another |
-| `requires` | Dependencies |
-| `relates_to` | General connections |
-| `part_of` | Hierarchy relationships |
-| `extends` | Extensions or enhancements |
-| `pairs_with` | Things that work together |
-| `inspired_by` | Source of ideas |
-| `replaces` | Supersedes another document |
+```text
+memory://docs/auth       →  resolves in "research"
+memory://main/docs/auth  →  error: project is constrained to "research"
+```
 
-### Adding Observations
+### 2. Explicit project prefix
 
-Structure facts with semantic categories:
+If no constraint is set, the URL is checked for a project prefix. The first path segment is always compared against known project names; when it matches, that segment is stripped and used as the project context:
 
-```bash
-## Observations
-- [decision] We chose JWT tokens for stateless auth
-- [requirement] Must support 2FA for sensitive operations
-- [technique] Use bcrypt for password hashing
-- [issue] Rate limiting needed for login attempts
-- [fact] Average response time is 50ms
-- [question] Should we support OAuth?
+```text
+memory://main/specs/api-design
+         ^^^^                    →  project = "main"
+              ^^^^^^^^^^^^^^^^   →  path = "specs/api-design"
 ```
 
----
+If the first segment doesn't match any known project, the entire path is treated as a note path.
 
-## Multi-Project Workflows
+### 3. Default project fallback
 
-### How Projects Work
+If no constraint exists and no project prefix matches, the URL resolves in the default project:
 
-Basic Memory supports multiple projects for organizing different knowledge bases. When you start a conversation, the AI will:
+```text
+memory://docs/auth  →  resolves in default project (typically "main")
+```
 
-1. Check your available projects
-2. Suggest the most active project based on recent activity
-3. Ask which project to use for this conversation
-4. Remember your choice throughout the session
+::note
+Prefix detection always runs — it isn't controlled by configuration. The `permalinks_include_project` setting governs whether *generated permalinks* include the project slug; see [Configuration](/reference/configuration).
+::
 
-**Example conversation:**
-```bash
-You: "Let's work on documentation"
+---
 
-Claude: I see you have 3 projects: main, work-notes, personal
-Your most active project is work-notes.
-Should I use work-notes for this task?
+## Building Knowledge Connections
 
-You: "Yes, let's use work-notes"
+Connect knowledge with relations and structure facts with categorized observations:
 
-Claude: I'll use the 'work-notes' project for our session.
+```markdown
+## Observations
+- [decision] We chose JWT tokens for stateless auth
+- [requirement] Must support 2FA for sensitive operations
+
+## Relations
+- implements [[Authentication System]]
+- requires [[Database Schema]]
 ```
 
-### Single Project Users
+Categories and relation types are open-ended — use whatever fits. The full syntax, conventions, and edge cases live in [Observations and Relations](/concepts/observations-and-relations).
 
-If you only use one project, you can skip the selection prompt. Add this to `~/.basic-memory/config.json`:
+---
 
-```json
-{
-  "default_project": "main"
-}
-```
+## Multi-Project Workflows
 
-This sets your fallback project when no explicit project is passed. You can still override by specifying a different project.
+Basic Memory supports multiple projects for organizing different knowledge bases — the AI checks your projects at the start of a conversation and remembers your choice for the session. Project setup, creation commands, and the default-project fallback are covered in [Set Up Local Projects](/local/getting-started).
 
 ### Single Project Mode (Locked)
 
@@ -349,6 +330,7 @@ Claude: [Uses edit_note with append operation]
 - `prepend` - Add content to beginning
 - `find_replace` - Replace specific text
 - `replace_section` - Replace entire section by heading
+- `insert_before_section` / `insert_after_section` - Insert content adjacent to a section heading
 
 ### Smart File Organization
 
@@ -471,23 +453,23 @@ No manual sync needed for normal workflows.
 basic-memory status
 
 # View project information
-basic-memory project info
+basic-memory project info main
 ```
 
 ### Force Re-sync
 
-If something seems out of sync:
+Sync runs automatically — file changes are picked up in real time. If something still seems out of sync:
 
 ```bash
-# Re-sync all files
-basic-memory sync
+# Rebuild the search index
+basic-memory reindex
 
-# Reset and rebuild database (use if issues persist)
-basic-memory reset
+# Reset and rebuild the database (use if issues persist)
+basic-memory reset --reindex
 ```
 
 ::warning
-`basic-memory reset` rebuilds the entire database from your files. This is safe (files are never deleted) but may take time for large knowledge bases.
+`basic-memory reset` deletes only the index database — your files are never touched. Pass `--reindex` to rebuild the index from your files afterward (a plain reset leaves the index empty until the next reindex). Rebuilding may take time for large knowledge bases.
 ::
 
 ---
@@ -565,25 +547,12 @@ The database syncs regardless of how you edit files.
 
 ## Troubleshooting
 
-### Changes Not Syncing
-
-1. Check sync status: `basic-memory status`
-2. Verify file permissions
-3. Check if file matches ignore patterns
-4. Reset database: `basic-memory reset`
-
-### Claude Can't Find Knowledge
-
-1. Confirm files are in correct project directory
-2. Check frontmatter formatting (valid YAML)
-3. Use `memory://` URLs for direct references
-4. Trigger re-sync: `basic-memory sync`
+The two most common symptoms:
 
-### Performance Issues
+- **Changes not showing up** — check `basic-memory status`, then rebuild the index with `basic-memory reindex`
+- **Claude can't find knowledge** — confirm the files are in the right project and the frontmatter is valid YAML
 
-1. Check database size: `basic-memory project info`
-2. Archive old content
-3. Adjust sync delay in config (default: 1000ms)
+For the full runbook — sync, search, install, config, and logs — see [Troubleshooting](/reference/troubleshooting).
 
 ### Getting Help
 
@@ -595,7 +564,7 @@ The database syncs regardless of how you edit files.
 basic-memory --help
 
 # Help for specific commands
-basic-memory sync --help
+basic-memory status --help
 basic-memory project --help
 ```
 
diff --git a/content/6.concepts/5.canvas.md b/content/06.local/6.canvas.md
similarity index 75%
rename from content/6.concepts/5.canvas.md
rename to content/06.local/6.canvas.md
index 590d51d..6f3395f 100644
--- a/content/6.concepts/5.canvas.md
+++ b/content/06.local/6.canvas.md
@@ -2,15 +2,22 @@
 title: Canvas Visualizations
 description: Create visual knowledge maps using Obsidian's Canvas feature to understand relationships between concepts
 ---
-# Canvas Visualizations
 
 Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. These visualizations help you understand relationships between concepts, map out processes, and visualize your knowledge structure.
 
+::note
+Canvas is a **local-only** tool — it writes `.canvas` files for [Obsidian](/integrations/obsidian) alongside your notes. In cloud workspaces, use the [Explore graph view](/cloud/web-app#explore-the-graph) instead.
+::
+
 ## Creating Canvas Visualizations
 
 Ask Claude to create a visualization by describing what you want to map:
 
-- **Example Requests** — - "Create a canvas visualization of my project components and their relationships." - "Make a concept map showing the main themes from our discussion about climate change." - "Can you make a canvas diagram of the perfect pour over method?"
+**Example requests:**
+
+- "Create a canvas visualization of my project components and their relationships."
+- "Make a concept map showing the main themes from our discussion about climate change."
+- "Can you make a canvas diagram of the perfect pour over method?"
 
 <img src="/attachments/Canvas.png" alt="Canvas Visualization Example" />
 
@@ -22,10 +29,7 @@ Basic Memory can create several types of visual maps:
 - **Concept Maps** — Create visual representations of ideas and their relationships
 - **Process Diagrams** — Map workflows, sequences, and procedures
 - **Thematic Analysis** — Organize ideas around central themes
-
-### Relationship Networks
-
-Show how different entities relate to each other in your knowledge base.
+- **Relationship Networks** — Show how different entities relate to each other in your knowledge base
 
 ## Visualization Sources
 
@@ -98,3 +102,27 @@ The resulting file is fully compatible with Obsidian's Canvas feature and can be
 ::note
 **Provide context** about what documents or concepts to include for the best results.
 ::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Obsidian Integration
+icon: i-lucide-hexagon
+to: /integrations/obsidian
+---
+Open your canvases and vault in Obsidian.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+The note structure canvases visualize.
+::
+:::
diff --git a/content/6.concepts/.navigation.yml b/content/07.concepts/.navigation.yml
similarity index 100%
rename from content/6.concepts/.navigation.yml
rename to content/07.concepts/.navigation.yml
diff --git a/content/6.concepts/0.vs-built-in-memory.md b/content/07.concepts/0.vs-built-in-memory.md
similarity index 85%
rename from content/6.concepts/0.vs-built-in-memory.md
rename to content/07.concepts/0.vs-built-in-memory.md
index 7260122..4240402 100644
--- a/content/6.concepts/0.vs-built-in-memory.md
+++ b/content/07.concepts/0.vs-built-in-memory.md
@@ -5,7 +5,20 @@ description: How to use Basic Memory alongside the memory features in Claude, Ch
 
 Your AI tools already have built-in memory features. Basic Memory doesn't replace them — it works alongside them. This page explains what each system is good at and how to use them together effectively.
 
-For a broader comparison of Basic Memory with all the alternatives — including Obsidian, database-only memory services, and more — see [Why Basic Memory](/start-here/why-basic-memory).
+::tip
+**Why choose? Get the best of both.** Tell your agent to save this to its memory — one paste, and its built-in memory carries the routing rule from then on:
+
+```text
+Save this to your memory: Use Basic Memory as my long-term knowledge
+store — record durable decisions, research, and context there as notes.
+Keep your built-in memory for short-term working context, and have your
+memories reference Basic Memory notes for the details. Use Basic
+Memory's search_notes, recent_activity, and build_context tools to find
+information before answering questions about past work.
+```
+
+Built-in memory becomes the short-term cache; Basic Memory becomes the long-term store — and each knows about the other. For fuller standing instructions (skills, project settings, CLAUDE.md/AGENTS.md), see the [AI Assistant Guide](/reference/ai-assistant-guide).
+::
 
 ---
 
@@ -18,7 +31,7 @@ For a broader comparison of Basic Memory with all the alternatives — including
 
 **Claude Code** has two built-in systems:
 - **CLAUDE.md files** — Instructions you write for how Claude should work in a project. Coding standards, build commands, architectural conventions.
-- **Auto memory** — Notes Claude writes itself when it notices patterns or preferences. Stored in `~/.claude/projects/` as markdown files. The first 200 lines of `MEMORY.md` load into every session.
+- **Auto memory** — Notes Claude writes itself when it notices patterns or preferences. Stored in `~/.claude/projects/` as markdown files, indexed by a `MEMORY.md` file whose first 200 lines load into every session.
 
 **ChatGPT** has two memory systems:
 - **Saved memories** — Facts you tell it to remember ("I'm vegetarian," "I live in San Francisco"). These persist until you delete them, and total capacity is limited to roughly 1,200–1,400 words — once full, nothing new is saved until you delete entries. ChatGPT may also save details on its own if they seem useful. The Manage Memories panel lets you view and delete entries; to change one, ask ChatGPT in chat.
@@ -128,7 +141,7 @@ How notes, observations, and relations work.
 ---
 title: Integrations
 icon: i-lucide-plug
-to: /integrations/claude-desktop
+to: /integrations
 ---
 Connect Basic Memory to your AI tool.
 ::
diff --git a/content/6.concepts/1.knowledge-format.md b/content/07.concepts/1.knowledge-format.md
similarity index 85%
rename from content/6.concepts/1.knowledge-format.md
rename to content/07.concepts/1.knowledge-format.md
index e3de28e..e0201b5 100644
--- a/content/6.concepts/1.knowledge-format.md
+++ b/content/07.concepts/1.knowledge-format.md
@@ -8,7 +8,7 @@ Basic Memory is a knowledge base that you and your AI share. Everything is store
 This page explains how those files are structured and how that structure turns a folder of notes into a connected knowledge graph.
 
 ::tip
-Using Basic Memory Cloud? The knowledge format is the same — create notes through AI conversations or edit them directly in the [Web Editor](/cloud/cloud-guide#web-editor).
+Using Basic Memory Cloud? The knowledge format is the same — create notes through AI conversations or edit them directly in the [web app](/cloud/note-editor).
 ::
 
 ---
@@ -59,7 +59,7 @@ permalink: authentication-design
 - **title** — The name of the note. Used for linking and display.
 - **type** — What kind of note this is (e.g. `note`, `meeting`, `decision`). You can use any type you want.
 - **tags** — For organization and filtering.
-- **permalink** — A stable identifier for this note. Generated automatically from the title if you don't set one. Stays the same even if you move the file.
+- **permalink** — A stable identifier for this note. Generated automatically from the file's path (and prefixed with the project name by default) if you don't set one. Stays the same even if you later move the file.
 
 ::tip
 Frontmatter is just standard YAML. You can add any fields you want — `status`, `priority`, `author`, `due_date`, whatever is useful for your workflow. The AI can set these automatically when creating notes, and you can search by them later with metadata search. If you want to formalize which fields a note type should have, that's what [schemas](/concepts/schema-system) are for.
@@ -88,6 +88,8 @@ The power of observations is that each one is indexed individually. When you sea
 Basic Memory recognizes `[category]` syntax as observations but won't confuse them with markdown checkboxes (`[ ]` or `[x]`).
 ::
 
+For category conventions, tags, and worked examples, see the deep dive: [Observations and Relations](/concepts/observations-and-relations).
+
 ---
 
 ## Relations
@@ -101,7 +103,7 @@ Relations link notes together using `[[wiki-link]]` syntax:
 - relates_to [[Session Management]]
 ```
 
-The word before the link becomes the relationship type. Like categories, you can use any relation type — `implements`, `inspired_by`, `blocks`, `part_of`, `contrasts_with`, whatever describes the connection. Relation types are a single token; for a multi-word type, **quote it**: `"depends on" [[User Database Schema]]`. A list item that's just a wikilink (or has unquoted prose before it) is indexed as a generic `links_to` connection.
+The word before the link becomes the relationship type. Like categories, you can use any relation type — `implements`, `inspired_by`, `blocks`, `part_of`, `contrasts_with`, whatever describes the connection. Quoting rules and edge cases (multi-word types, bare wikilinks) are covered in [Observations and Relations](/concepts/observations-and-relations).
 
 You can also reference other notes inline anywhere in the document:
 
@@ -112,6 +114,8 @@ addresses the concerns raised in [[Security Review Q4]].
 
 Relations can link to notes that don't exist yet. When those notes are created later, the connections are already in place.
 
+For relation-type conventions and how inline references index, see [Observations and Relations](/concepts/observations-and-relations).
+
 ---
 
 ## The Knowledge Graph
@@ -124,7 +128,7 @@ This graph is what makes Basic Memory more than a folder of files. When the AI u
 
 ## Permalinks
 
-Every note has a permalink — a stable identifier derived from its title. Permalinks are how Basic Memory addresses notes internally and how `memory://` URLs work:
+Every note has a permalink — a stable identifier derived from its file path (project-prefixed by default). Permalinks are how Basic Memory addresses notes internally and how `memory://` URLs work — and by default they stay unchanged when a file is renamed or moved:
 
 ```
 memory://authentication-design
@@ -136,20 +140,7 @@ Permalinks stay the same even if you rename or move the file. For more on how me
 
 ## File Organization
 
-Organize your files however you want. Flat folders, nested hierarchies, topic-based groupings — the knowledge graph is built from the content of your notes, not from where they sit on disk.
-
-```
-knowledge/
-  projects/
-    auth-design.md
-    api-roadmap.md
-  meetings/
-    2026-03-01-standup.md
-  decisions/
-    database-choice.md
-```
-
-The graph connects everything regardless of folder structure.
+Organize your files however you want — the knowledge graph is built from the content of your notes, not from where they sit on disk. See [Projects and Folders](/concepts/projects-and-folders) for organizing with projects and folder structure.
 
 ---
 
diff --git a/content/6.concepts/2.projects-and-folders.md b/content/07.concepts/2.projects-and-folders.md
similarity index 81%
rename from content/6.concepts/2.projects-and-folders.md
rename to content/07.concepts/2.projects-and-folders.md
index ff751e7..e385d6f 100644
--- a/content/6.concepts/2.projects-and-folders.md
+++ b/content/07.concepts/2.projects-and-folders.md
@@ -11,7 +11,7 @@ A project is a separate knowledge base. Each project maps to a folder on disk (o
 
 Think of projects the way you think of separate notebooks, not separate pages in the same notebook.
 
-When you run a command or an AI tool like `write_note`, it targets whichever project is currently active. You can switch projects at any time, and one project is always set as the default so you do not have to specify it every time.
+When you run a command or an AI tool like `write_note`, it targets the project you name — each call carries a `project` parameter or CLI argument. If you don't specify one, it goes to the **default project**, and you can target a different project at any time, including mid-conversation.
 
 ## Creating and managing projects
 
@@ -40,10 +40,10 @@ Switch to a different project in conversation using the MCP tool:
 Switch to the "personal" project.
 ```
 
-The AI will call `switch_project` behind the scenes. You can also use the CLI:
+The AI will simply pass `project="personal"` on its next tool calls — there's no switch step; it discovers your projects with `list_memory_projects`. From the CLI, change the fallback for commands that don't specify a project:
 
 ```bash
-bm project switch "personal"
+bm project default "personal"
 ```
 
 ## When to use multiple projects
@@ -58,6 +58,7 @@ Here are some common patterns:
 - **Multiple clients.** Each client gets a project. Their notes, decisions, and context stay contained. You can switch between clients mid-conversation.
 - **A coding project's docs folder.** Point a project at the `docs/` folder inside a repo. The AI builds context about that specific codebase without pulling in unrelated notes.
 - **A writing project.** A book, a course, or a research paper. Give it a project so its outline, drafts, and references form their own knowledge graph.
+
 If you're unsure, start with one project. You can always create another later and move notes into it.
 
 ## Folders within a project
@@ -78,7 +79,7 @@ This is a perfectly good layout. So is a flat folder with everything at the top
 
 ## Mixing local and cloud projects
 
-Starting in v0.19, you can keep some projects local and route others to Basic Memory Cloud. Your personal notes stay on your machine. Your work projects sync to the cloud and are accessible from any device. Both are available in the same conversation.
+You can keep some projects local and route others to Basic Memory Cloud. Your personal notes stay on your machine. Your work projects sync to the cloud and are accessible from any device. Both are available in the same conversation.
 
 This is configured through per-project cloud routing. Each project independently decides whether it talks to a local database or a cloud instance.
 
@@ -86,14 +87,14 @@ For setup details, see the [Local and Cloud Routing](/cloud/routing) guide.
 
 ## Project-prefixed permalinks
 
-When you have multiple projects, Basic Memory automatically prefixes note permalinks with the project name to prevent ambiguity:
+By default, Basic Memory prefixes newly generated permalinks with the project name, so notes with the same title in different projects stay distinct:
 
 ```
 memory://work/architecture/auth-system
 memory://personal/reading-list
 ```
 
-This means a note called "Auth System" in your work project and a note called "Auth System" in your personal project are distinct and addressable. The prefix is added automatically when notes are indexed. You do not need to manage it yourself.
+This means a note called "Auth System" in your work project and a note called "Auth System" in your personal project are distinct and addressable. The prefix is added when a permalink is generated — existing permalinks aren't rewritten. You don't need to manage it yourself.
 
 For more on how memory URLs work, see [Memory URLs](/concepts/memory-urls).
 
diff --git a/content/6.concepts/3.observations-and-relations.md b/content/07.concepts/3.observations-and-relations.md
similarity index 94%
rename from content/6.concepts/3.observations-and-relations.md
rename to content/07.concepts/3.observations-and-relations.md
index b6169cd..9141a3a 100644
--- a/content/6.concepts/3.observations-and-relations.md
+++ b/content/07.concepts/3.observations-and-relations.md
@@ -78,7 +78,7 @@ We decided to follow the approach from [[API Design Principles]]
 because it aligns with our [[Team Standards]].
 ```
 
-These inline references also create connections in the knowledge graph. The difference is that relations in a dedicated `## Relations` section have explicit types (depends_on, relates_to), while inline references create a general "references" connection. Both are useful.
+These inline references also create connections in the knowledge graph. The difference is that relations in a list with a leading word have explicit types (`depends_on`, `relates_to`), while inline references create a generic `links_to` connection. Both are useful.
 
 ## Why this matters
 
@@ -104,7 +104,7 @@ Categories, tags, and relation types give your AI assistant structured metadata
 
 If you want to ensure consistency across similar notes, Basic Memory's schema system (introduced in v0.19) can validate that notes of a certain type contain the observations and relations you expect.
 
-For example, you could define a schema that requires every "person" note to have a `name` observation and a `works_at` relation. The schema validates notes when they're written and flags anything that's missing.
+For example, you could define a schema that requires every "person" note to have a `name` observation and a `works_at` relation. You can then validate notes on demand — ask your AI to check them (the `schema_validate` tool) or run `bm schema validate` — and the report flags anything that's missing. Validation warns rather than blocking writes.
 
 ::note
 See [Schema System](/concepts/schema-system) for details on defining and applying schemas.
diff --git a/content/6.concepts/4.memory-urls.md b/content/07.concepts/4.memory-urls.md
similarity index 53%
rename from content/6.concepts/4.memory-urls.md
rename to content/07.concepts/4.memory-urls.md
index a25ea26..1f3f1f1 100644
--- a/content/6.concepts/4.memory-urls.md
+++ b/content/07.concepts/4.memory-urls.md
@@ -11,12 +11,15 @@ Every note in Basic Memory has an address — a `memory://` URL that works like
 
 ## Basic forms
 
-### By title/permalink
+### By title or permalink
 
 ```text
 memory://auth-approaches-2024
+memory://Auth Approaches 2024
 ```
 
+Both a permalink and an exact note title resolve.
+
 ### By path
 
 ```text
@@ -35,7 +38,7 @@ memory://auth*
 
 ## Project-prefixed URLs
 
-With project-prefixed permalink behavior enabled (default), memory URLs can include project scope:
+Memory URLs can include project scope as the first path segment:
 
 ```text
 memory://main/docs/authentication
@@ -48,19 +51,13 @@ This is useful when the same note title exists in multiple projects.
 
 ## Cross-project references in links
 
-Within notes, project namespace syntax is normalized:
+Within notes, project namespace syntax is normalized — you can write it in a relation:
 
-```text
-project::note-path
+```markdown
+- relates_to [[research::specs/api]]
 ```
 
-is treated as:
-
-```text
-project/note-path
-```
-
-This improves cross-project resolution and keeps links explicit.
+The `project::note-path` form is treated as `project/note-path`, and the same syntax works inside `memory://` URLs. This improves cross-project resolution and keeps links explicit.
 
 ---
 
@@ -74,44 +71,7 @@ Behind the scenes, tools like `read_note` and `build_context` accept memory URLs
 
 ## Resolution behavior
 
-At runtime, Basic Memory resolves memory URLs in this order:
-
-### 1. Project constraints
-
-If the MCP server was started with `BASIC_MEMORY_MCP_PROJECT=research`, all URLs are resolved within the `research` project regardless of any prefix in the URL:
-
-```text
-memory://docs/auth  →  resolves in "research" project only
-```
-
-### 2. Explicit project prefix
-
-If no constraint is set, the URL is checked for a project prefix. The first path segment is compared against known project names:
-
-```text
-memory://main/docs/auth       →  resolves in "main" project
-memory://research/specs/api   →  resolves in "research" project
-```
-
-### 3. Default project fallback
-
-If no constraint exists and no project prefix matches, the URL resolves in the default project:
-
-```text
-memory://docs/auth  →  resolves in default project (typically "main")
-```
-
-### Project-prefix extraction
-
-When `permalinks_include_project` is enabled (the default), Basic Memory checks whether the first path segment of a URL matches a known project name. If it does, that segment is stripped and used as the project context:
-
-```text
-memory://main/specs/api-design
-         ^^^^                    →  project = "main"
-              ^^^^^^^^^^^^^^^^   →  path = "specs/api-design"
-```
-
-If the first segment doesn't match any known project, the entire path is treated as a note path within the default project.
+URLs resolve to a project by explicit prefix first, then fall back to the default project. The full resolution order — including local-server project constraints — is covered in the [local User Guide](/local/user-guide#memory-url-resolution-local-server); these controls aren't exposed in cloud.
 
 ---
 
@@ -141,6 +101,6 @@ title: AI Assistant Guide
 icon: i-lucide-bot
 to: /reference/ai-assistant-guide
 ---
-Patterns for memory URL usage in assistant workflows.
+Teach your assistant when and how to use Basic Memory.
 ::
 :::
diff --git a/content/6.concepts/6.schema-system.md b/content/07.concepts/6.schema-system.md
similarity index 94%
rename from content/6.concepts/6.schema-system.md
rename to content/07.concepts/6.schema-system.md
index 0de665b..f4f1263 100644
--- a/content/6.concepts/6.schema-system.md
+++ b/content/07.concepts/6.schema-system.md
@@ -78,7 +78,7 @@ Want me to add it as an optional field?
 
 **Writing with schema guidance:**
 
-When a schema exists for a note type, your AI uses it as a creation guide automatically. It includes all required fields and relevant optional ones without you having to ask.
+When a schema exists for a note type, your AI can use it as a creation guide — ask it to check the schema when writing, or install the [memory-schema skill](/integrations/skills) to make this automatic.
 
 Your schemas do double duty: they help you maintain consistency *and* they guide AI assistants toward producing notes that match your preferred format.
 
@@ -104,7 +104,6 @@ By default, schemas give gentle warnings when something's missing — they don't
 |------|-------------|-------------|
 | **Warn** (default) | Reports what's missing but doesn't block anything | Active writing, gradual adoption |
 | **Strict** | Treats missing fields as errors | Mature schemas, enforced workflows |
-| **Off** | No checking | Temporarily disable while restructuring |
 
 Start with warn mode. Move to strict only after your note patterns have settled down and you're confident in the schema.
 
@@ -218,7 +217,7 @@ These are just starting points. The real power is that you can describe *any* st
 
 > "Make a schema for project decisions — the context, what we chose, what we rejected, and why."
 
-The AI reads your schemas automatically when creating notes of that type, so once a schema exists, your notes just come out consistent.
+With the [memory-schema skill](/integrations/skills) installed (or a standing instruction to check schemas), the AI consults your schemas when creating notes of that type, so your notes come out consistent.
 
 ---
 
@@ -461,24 +460,22 @@ status: published
 Validation checks both the body fields (`name`, `role`) and the frontmatter fields (`tags`, `status`):
 
 ```bash
-$ bm schema validate people/grace-hopper.md
-✓ grace-hopper: valid (0 warnings)
+bm schema validate people/grace-hopper.md
 ```
 
+The result is a table of notes with their warning and error counts — a valid note shows zero of each.
+
 If a note has a frontmatter value outside the allowed enum:
 
 ```yaml
 ---
 title: Iris West
 type: person
-status: archived   # not in [draft, published]
+status: retired   # not in [draft, published, archived]
 ---
 ```
 
-```bash
-$ bm schema validate people/iris-west.md
-⚠ iris-west: frontmatter field 'status' enum mismatch (got 'archived', expected one of: draft, published)
-```
+Validation reports: `Frontmatter key 'status' has invalid value: retired (allowed: draft, published, archived)`.
 
 If a required frontmatter key is missing (no `?` suffix), validation warns or errors depending on the mode:
 
@@ -488,10 +485,7 @@ settings:
     status: string   # required — no ? suffix
 ```
 
-```bash
-$ bm schema validate people/hank-pym.md
-⚠ hank-pym: missing required frontmatter field: status
-```
+Validation reports: `Missing required frontmatter key: status`.
 
 ::note
 Frontmatter rules use the same picoschema syntax as body fields. Add `?` for optional, `(array)` for lists, and `(enum)` for constrained values.
@@ -505,9 +499,6 @@ Frontmatter rules use the same picoschema syntax as body fields. Add `?` for opt
 # Analyze your existing notes to discover patterns
 bm schema infer person
 
-# Save the inferred schema as a note
-bm schema infer person --save
-
 # Validate a single note
 bm schema validate people/ada-lovelace.md
 
@@ -579,16 +570,10 @@ status: active
 **Validation:**
 
 ```bash
-$ bm schema validate people/ada-lovelace.md
-✓ ada-lovelace: valid (0 warnings)
+bm schema validate people/ada-lovelace.md
 ```
 
-If `[name]` were missing:
-
-```bash
-$ bm schema validate people/ada-lovelace.md
-⚠ ada-lovelace: missing required field: name
-```
+A valid note shows zero warnings and errors in the results table. If `[name]` were missing, validation would report: `Missing required field: name (expected [name] observation)`.
 
 ---
 
@@ -629,6 +614,6 @@ title: AI Assistant Guide
 icon: i-lucide-bot
 to: /reference/ai-assistant-guide
 ---
-How assistants can use schema tools in workflows.
+Teach your assistant when and how to use Basic Memory.
 ::
 :::
diff --git a/content/6.concepts/7.semantic-search.md b/content/07.concepts/7.semantic-search.md
similarity index 87%
rename from content/6.concepts/7.semantic-search.md
rename to content/07.concepts/7.semantic-search.md
index 0a636da..450bc6a 100644
--- a/content/6.concepts/7.semantic-search.md
+++ b/content/07.concepts/7.semantic-search.md
@@ -153,36 +153,7 @@ To manually rebuild the search index (e.g., after switching providers):
 bm reindex --embeddings
 ```
 
-### Platform compatibility
-
-| Platform | FastEmbed (local) | OpenAI (API) |
-|---|---|---|
-| macOS ARM64 (Apple Silicon) | Yes | Yes |
-| macOS x86_64 (Intel Mac) | No (see workaround) | Yes |
-| Linux x86_64 | Yes | Yes |
-| Linux ARM64 | Yes | Yes |
-| Windows x86_64 | Yes | Yes |
-
-### Intel Mac workaround
-
-The default local embedding model doesn't run on Intel Macs. You have two options:
-
-**Option 1: Use OpenAI embeddings (recommended)**
-
-Requires an [OpenAI API subscription](https://platform.openai.com/api-keys) — create a key there and set it as an environment variable.
-
-```bash
-export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai
-export OPENAI_API_KEY=sk-...
-bm reindex --embeddings
-```
-
-**Option 2: Pin ONNX Runtime**
-
-```bash
-uv pip install 'onnxruntime<1.24'
-bm reindex --embeddings
-```
+Running on an Intel Mac? See [Platform compatibility](#platform-compatibility) below for a workaround.
 
 ---
 
@@ -224,7 +195,7 @@ This means a search for "water temperature for brewing" can surface the specific
 
 ### How results are ranked
 
-Search results return whole notes ranked by relevance, with the matched chunk text showing which part of the note was most relevant.
+Results are returned as note-level items — plus individual observations and relations — ranked by their best-matching chunks, with the matched chunk text showing which part of the note was most relevant.
 
 ### Hybrid fusion
 
@@ -254,15 +225,15 @@ Each chunk has a content hash. When notes are re-synced or reindexed, unchanged
 
 ## Configuration
 
-| Config field | Env var | Default | Description |
-|---|---|---|---|
-| `semantic_search_enabled` | `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED` | `true` | Enable semantic search |
-| `semantic_embedding_provider` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER` | `"fastembed"` | `"fastembed"` (local) or `"openai"` (API) |
-| `semantic_embedding_model` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL` | `"bge-small-en-v1.5"` | Embedding model identifier |
-| `semantic_embedding_dimensions` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_DIMENSIONS` | auto-detected | 384 (FastEmbed), 1536 (OpenAI) |
-| `semantic_embedding_batch_size` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE` | `64` | Texts per embedding batch |
-| `semantic_vector_k` | `BASIC_MEMORY_SEMANTIC_VECTOR_K` | `100` | Vector candidate count |
-| `semantic_min_similarity` | `BASIC_MEMORY_SEMANTIC_MIN_SIMILARITY` | `0.55` | Minimum similarity threshold |
+The settings you're most likely to tune:
+
+| Config field | Default | Description |
+|---|---|---|
+| `semantic_search_enabled` | `true` | Enable semantic search |
+| `semantic_embedding_provider` | `"fastembed"` | Common values: `fastembed` (local), `openai` (API) |
+| `semantic_min_similarity` | `0.55` | Minimum similarity threshold |
+
+The full list — models, dimensions, batch size, vector candidates, env vars — is in the [Configuration reference](/reference/configuration#semantic-search-settings).
 
 ### Similarity threshold
 
@@ -325,21 +296,26 @@ export OPENAI_API_KEY=sk-...
 bm reindex --embeddings
 ```
 
-**Option 2: Pin ONNX Runtime**
+**Option 2: Pin ONNX Runtime** (uv installs)
 
 ```bash
-uv pip install 'onnxruntime<1.24'
+uv tool install basic-memory --with 'onnxruntime<1.24'
 bm reindex --embeddings
 ```
 
+For MCP configs that launch via `uvx`, use `uvx --with 'onnxruntime<1.24' basic-memory mcp`. Homebrew installs can't pin the runtime — use the OpenAI option or switch to a uv install.
+
 ---
 
 ## Reindexing
 
 ```bash
-# Rebuild both search index and embeddings
+# Incremental reindex of search index and embeddings (skips unchanged content)
 bm reindex
 
+# Force a full rebuild, re-embedding everything
+bm reindex --full
+
 # Rebuild only vector embeddings
 bm reindex --embeddings
 
@@ -355,7 +331,7 @@ bm reindex -p my-project
 - **First time** — Happens automatically on first startup
 - **Switching provider or model** — Embeddings from different models aren't compatible
 - **After a database reset** — `bm reset` clears everything
-- **Troubleshooting** — A fresh reindex can fix index issues
+- **Troubleshooting** — a full rebuild (`bm reindex --full`) can fix index issues; the default run is incremental and skips unchanged content
 
 ---
 
diff --git a/content/6.concepts/8.metadata-search.md b/content/07.concepts/8.metadata-search.md
similarity index 84%
rename from content/6.concepts/8.metadata-search.md
rename to content/07.concepts/8.metadata-search.md
index 823ee6e..1ce06a4 100644
--- a/content/6.concepts/8.metadata-search.md
+++ b/content/07.concepts/8.metadata-search.md
@@ -11,6 +11,10 @@ Metadata search is a parameter on the same [`search_notes`](/reference/mcp-tools
 Frontmatter is structured data. The richer your frontmatter, the sharper your search. A note with `type: meeting`, `status: open`, `priority: high`, and `attendees: [...]` is reachable from many more angles than one with just a title.
 ::
 
+::note
+Observation categories such as `[decision]`, `[rule]`, or `[follow-up]` are not frontmatter fields — see [Searching observations by category](#searching-observations-by-category) below instead of `metadata_filters`.
+::
+
 ---
 
 ## What's in your frontmatter
@@ -94,7 +98,7 @@ Both ends included; the value must be exactly two items:
 | _(scalar)_ | string / number / bool / date | Exact match |
 | _(array)_ | list of scalars | All values must be present (for list fields) |
 | `$in` | non-empty list | Any of |
-| `$gt`, `$gte`, `$lt`, `$lte` | number | Comparison (gte/lte inclusive) |
+| `$gt`, `$gte`, `$lt`, `$lte` | number or string | Comparison (gte/lte inclusive); strings compare lexicographically — dates as ISO strings |
 | `$between` | `[min, max]` | Inclusive range, exactly 2 values |
 
 ::note
@@ -125,11 +129,13 @@ search_notes(metadata_filters={"tags": ["security"]})
 Multiple tags in the shorthand mean _all of them_:
 
 ```python
-search_notes("tag:tier1,alpha")   # comma-separated
-search_notes("tag:tier1 alpha")   # space-separated
+search_notes("tag:tier1,alpha")       # comma-separated
+search_notes("tag:tier1 tag:alpha")   # repeated tag: tokens
 # Both require BOTH tags to be present.
 ```
 
+A bare word after a `tag:` token isn't a tag — `"tag:tier1 alpha"` filters on `tier1` and treats `alpha` as ordinary query text.
+
 If a key appears in both a shortcut and `metadata_filters`, the explicit filter wins.
 
 ---
@@ -207,12 +213,33 @@ confidence: 0.6
 | Specs with confidence above 0.7 | `{"type": "spec", "confidence": {"$gt": 0.7}}` |
 | Anything high or critical priority | `{"priority": {"$in": ["high", "critical"]}}` |
 | Specs in confidence range [0.5, 0.9] | `{"type": "spec", "confidence": {"$between": [0.5, 0.9]}}` |
+| Decisions since April | `{"type": "decision", "date": {"$gte": "2026-04-01"}}` — dates compare as ISO strings |
 | Notes tagged both `security` AND `oauth` | `{"tags": ["security", "oauth"]}` |
 | "OAuth" matches in still-open work | use `search_notes("OAuth", metadata_filters={"status": "in-progress"})` |
 | Anything with nested `schema.confidence` ≥ 0.7 | `{"schema.confidence": {"$gte": 0.7}}` |
 
 ---
 
+## Searching observations by category
+
+Observation categories (`- [decision] ...`, `- [rule] ...`) live on observations, not in frontmatter — so they get their own filter, `categories`, instead of `metadata_filters`:
+
+```python
+# All decision observations, anywhere
+search_notes(categories=["decision"])
+
+# Decisions mentioning auth
+search_notes("auth", categories=["decision"], entity_types=["observation"])
+```
+
+Matching is exact, and when you pass `categories` without `entity_types`, results default to observations. From the CLI:
+
+```bash
+bm tool search-notes "auth" --entity-type observation --category decision
+```
+
+---
+
 ## Type handling
 
 - **Strings** match exactly (case-sensitive).
diff --git a/content/7.integrations/.navigation.yml b/content/08.integrations/.navigation.yml
similarity index 100%
rename from content/7.integrations/.navigation.yml
rename to content/08.integrations/.navigation.yml
diff --git a/content/08.integrations/0.index.md b/content/08.integrations/0.index.md
new file mode 100644
index 0000000..94a13c2
--- /dev/null
+++ b/content/08.integrations/0.index.md
@@ -0,0 +1,149 @@
+---
+title: Connect AI tools
+description: Choose an AI client or extension and connect it to Basic Memory.
+---
+
+Basic Memory is most useful when the AI tools you already use can read and write the same shared knowledge base. Start with the tool you use most, then connect others to the same workspace as needed.
+
+::tip
+For Basic Memory Cloud, the fastest path is the **Connect Your AI Tool** walkthrough in the web app's Help Center (account menu → **Help**) — it has your MCP endpoint with a copy button, Claude and ChatGPT setup guides, and a quick test prompt:
+
+```text
+https://cloud.basicmemory.com/mcp
+```
+
+For local/open-source Basic Memory, use the local MCP server from your computer. See [Local MCP tools](/local/mcp-tools-local).
+::
+
+---
+
+## Recommended Cloud Connections
+
+These are the best starting points for most Basic Memory Cloud users.
+
+:::card-group
+::card
+---
+title: Claude
+icon: i-simple-icons-anthropic
+to: /integrations/claude-desktop
+---
+Connect Claude Desktop through a custom remote MCP connector — once added to your Claude account, it's also available on claude.ai and mobile.
+::
+
+::card
+---
+title: Claude Code
+icon: i-simple-icons-anthropic
+to: /integrations/claude-code
+---
+Give Claude Code access to shared project knowledge while you work in a repository.
+::
+
+::card
+---
+title: Codex
+icon: i-lucide-code
+to: /integrations/codex
+---
+Use Basic Memory from the Codex app and CLI.
+::
+
+::card
+---
+title: ChatGPT
+icon: i-simple-icons-openai
+to: /integrations/chatgpt
+---
+Connect ChatGPT as a custom MCP app, with notes about the extra per-chat step.
+::
+:::
+
+---
+
+## Coding And Local Editors
+
+Use these when you work from a code editor, terminal agent, or synced Markdown folder.
+
+:::card-group
+::card
+---
+title: Gemini CLI
+icon: i-simple-icons-googlegemini
+to: /integrations/gemini
+---
+Connect Google's command-line AI agent through MCP.
+::
+
+::card
+---
+title: Cursor
+icon: i-lucide-mouse-pointer-2
+to: /integrations/cursor
+---
+Use Basic Memory knowledge while coding in Cursor.
+::
+
+::card
+---
+title: VS Code
+icon: i-lucide-code-2
+to: /integrations/vscode
+---
+Work with Basic Memory from VS Code and local Markdown files.
+::
+
+::card
+---
+title: Obsidian
+icon: i-lucide-notebook
+to: /integrations/obsidian
+---
+Use Obsidian as a local editor for Basic Memory Markdown projects.
+::
+:::
+
+---
+
+## Extensions And Agent Workflows
+
+These integrations add richer workflows on top of the core MCP connection.
+
+:::card-group
+::card
+---
+title: Agent Skills
+icon: i-lucide-sparkles
+to: /integrations/skills
+---
+Optional instruction packs that teach agents when and how to use Basic Memory well.
+::
+
+::card
+---
+title: OpenClaw
+icon: i-lucide-bot
+to: /integrations/openclaw
+---
+Use the OpenClaw plugin for bundled Basic Memory tools and skills.
+::
+
+::card
+---
+title: Hermes
+icon: i-lucide-send
+to: /integrations/hermes
+---
+Use Hermes for Basic Memory-aware agent workflows.
+::
+:::
+
+---
+
+## Choosing Cloud Or Local
+
+- **Use Cloud** when you want the web app, remote MCP, collaboration, and the same knowledge available from multiple tools or devices.
+- **Run locally** when you want files and indexing to stay on your machine, or when your AI client expects a local stdio MCP server.
+- **Use both** when you want Cloud for shared projects and local files for editor-first workflows.
+
+Not sure? Start with [Quickstart: Cloud](/start-here/quickstart-cloud).
diff --git a/content/7.integrations/1.claude-desktop.md b/content/08.integrations/01.claude-desktop.md
similarity index 53%
rename from content/7.integrations/1.claude-desktop.md
rename to content/08.integrations/01.claude-desktop.md
index 70e4e15..fc1ce92 100644
--- a/content/7.integrations/1.claude-desktop.md
+++ b/content/08.integrations/01.claude-desktop.md
@@ -11,26 +11,34 @@ Basic Memory describes its tools to Claude through the Model Context Protocol, s
 
 ::steps
 ### Sign Up
-Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=claude-desktop)
 
-### Add Remote MCP Connector
-In Claude Desktop, go to **Settings > Claude > Connectors**
+### Open Settings
+In Claude Desktop or Claude.ai, go to **Settings → Claude → Connectors**
 
-Click "Add connector" and enter:
+![Claude Settings - Connectors](/screenshots/claude/settings-connectors.png)
+
+### Add Custom Connector
+Click **Add custom connector** and enter:
 - **Name**: Basic Memory
 - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
 
-![Add connector](/claude-settings-add-connector.png)
+![Claude - Add connector dialog](/screenshots/claude/add-connector.png)
 
 ### Authenticate
-Click "Connect" and follow the OAuth flow to grant permissions
+Click **Connect** to start the OAuth flow. You'll be redirected to Basic Memory to authorize access.
+
+![OAuth authorization](/screenshots/claude/oauth-connect.png)
+
+### Configure Tools (Optional)
+Click **Configure** to customize which tools are enabled.
 
-![Configure connector](/claude-settings-configure.png)
+![Claude - Configure tools](/screenshots/claude/configure-tools.png)
 
 ### Verify Setup
-In Claude, click the tools icon to see Basic Memory tools
+Confirm Basic Memory appears in the tools menu in chat.
 
-![Tools menu](/claude-settings-tools.png)
+![Claude - Tools menu](/attachments/claude-tools-menu.png)
 
 Try prompting: `List my projects`
 
@@ -44,7 +52,42 @@ See the [Cloud Guide](/cloud/cloud-guide) for web editor usage and troubleshooti
 
 ## Local Setup
 
-For local installation, follow the [Quickstart: Local](/start-here/quickstart-local) guide. It walks you through installing Basic Memory and configuring Claude Desktop in a few minutes.
+Install Basic Memory first — see [Quickstart: Local](/start-here/quickstart-local) for the Homebrew and uv install commands.
+
+### Edit the Claude Desktop config
+
+| Platform | Config Location |
+|----------|-----------------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Add this configuration:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": ["basic-memory", "mcp"]
+    }
+  }
+}
+```
+
+::note
+**Installed with Homebrew?** Use `"command": "basic-memory", "args": ["mcp"]` instead — `uvx` only exists if you installed uv.
+::
+
+::warning
+**ENOENT error?** Use the full path to the command. Find it with `which uvx` (or `which basic-memory` for Homebrew installs) and replace the `"command"` value with the full path (e.g., `"/Users/yourname/.local/bin/uvx"`).
+::
+
+### Restart and verify
+
+Restart Claude Desktop, then open the **search and tools** menu in the chat input area — Basic Memory tools should be listed.
+
+![Claude - Tools menu with Basic Memory](/screenshots/claude/tools-menu-local.png)
 
 ---
 
@@ -82,17 +125,16 @@ You can also reference specific notes with `memory://` URLs. Learn more in [Memo
 ### Tools not appearing
 - **Cloud**: Re-open Claude Desktop after adding the connector. Check that the connector URL is exactly `https://cloud.basicmemory.com/mcp`.
 - **Local**: Verify `uv` is installed (`which uvx`), check config JSON syntax, and restart Claude Desktop.
-- **Advanced research is on**: Research mode runs in a separate environment that can't reach any MCP connectors. See [Claude Research Mode](/integrations/claude-research-mode).
+- **Advanced research is on**: research runs in a separate environment that can't reach MCP connectors — ask Basic Memory questions in a normal chat instead.
 
 ### Tools appear but return errors
-- Check Basic Memory is installed: `basic-memory --version`
-- Verify sync status: `basic-memory status`
-- Check file permissions in your `~/basic-memory` directory
+- **Cloud**: check the [Activity view](/cloud/web-app#activity) for failed operations, or remove and re-add the connector.
+- **Local**: check Basic Memory is installed (`basic-memory --version`), verify sync status (`basic-memory status`), and check file permissions in your `~/basic-memory` directory.
 
-### Changes not showing up
+### Changes not showing up (local)
 - Real-time sync is on by default. Run `basic-memory status` to confirm.
 - Make sure the file is in the correct project directory.
-- If needed, run the watcher manually: `basic-memory watch`
+- If the index is stale, rebuild it with `bm reindex` (file watching runs automatically inside the MCP server).
 
 ### Project selection
 Projects are selected at the start of each conversation. For single-project setups, set a default in `~/.basic-memory/config.json`:
diff --git a/content/7.integrations/2.claude-code.md b/content/08.integrations/02.claude-code.md
similarity index 83%
rename from content/7.integrations/2.claude-code.md
rename to content/08.integrations/02.claude-code.md
index fed4cec..f594367 100644
--- a/content/7.integrations/2.claude-code.md
+++ b/content/08.integrations/02.claude-code.md
@@ -11,7 +11,7 @@ Claude Code is powerful, but every session starts from zero. Basic Memory gives
 
 ::steps
 ### Sign Up
-Create your account at [app.basicmemory.com](https://app.basicmemory.com).
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=claude-code).
 
 ### Add Remote MCP Server
 In your terminal, add the remote MCP server:
@@ -21,14 +21,14 @@ claude mcp add -s user -t http basic-memory-cloud https://cloud.basicmemory.com/
 ```
 
 ### Authenticate
-Follow the OAuth flow in Claude Code to grant permissions.
+In Claude Code, run `/mcp`, select **basic-memory-cloud**, and choose **Authenticate** to complete the OAuth flow in your browser.
 
 ### Verify
-Run `/mcp` in Claude Code and confirm Basic Memory tools are listed.
+Re-run `/mcp` and confirm the Basic Memory tools are listed.
 ::
 
 ::tip
-See the [Cloud Guide](/cloud/cloud-guide) for detailed instructions and troubleshooting.
+The [Cloud Guide](/cloud/cloud-guide) covers the rest of cloud — web app, CLI, snapshots, and migration. For problems, see [Troubleshooting](/reference/troubleshooting).
 ::
 
 ---
@@ -88,7 +88,7 @@ Install [agent skills](/integrations/skills) to teach Claude Code best practices
 
 **Notes not syncing?**
 - Check sync status: `basic-memory status`
-- Look for errors in `~/.basic-memory/logs/`
+- Look for errors in `~/.basic-memory/basic-memory.log`
 
 ---
 
@@ -97,9 +97,6 @@ Install [agent skills](/integrations/skills) to teach Claude Code best practices
 ### Claude Code already has CLAUDE.md and auto memory. Why add Basic Memory?
 Claude Code's built-in memory is great for project instructions and short learnings. Basic Memory adds a full knowledge base on top — searchable notes with semantic connections, observations, and relations that span across projects and AI tools. Think of CLAUDE.md as "how to work here" and Basic Memory as "everything we know." See [Using Basic Memory with Built-in AI Memory](/concepts/vs-built-in-memory) for a deeper comparison.
 
-### How does Basic Memory work alongside CLAUDE.md?
-They complement each other. `CLAUDE.md` holds project instructions and coding standards. Basic Memory holds evolving knowledge — decisions, architecture notes, research, meeting notes, and context that grows over time. Claude Code's auto memory captures small preferences; Basic Memory captures structured knowledge you can search, link, and reuse across any AI tool.
-
 ---
 
 ::note
@@ -124,7 +121,7 @@ title: MCP Tools Reference
 icon: i-lucide-wrench
 to: /reference/mcp-tools-reference
 ---
-Full reference for all 17 Basic Memory tools.
+Full reference for every Basic Memory tool.
 ::
 
 ::card
diff --git a/content/7.integrations/5.codex.md b/content/08.integrations/03.codex.md
similarity index 94%
rename from content/7.integrations/5.codex.md
rename to content/08.integrations/03.codex.md
index 26b1e16..ca3f05b 100644
--- a/content/7.integrations/5.codex.md
+++ b/content/08.integrations/03.codex.md
@@ -58,8 +58,12 @@ To point the app at a Basic Memory running on your own machine, start a local HT
 ::steps
 ### Start a local server
 
+Install Basic Memory first if you haven't — see [Quickstart: Local](/start-here/quickstart-local) — or run it without installing via `uvx`:
+
 ```bash
 basic-memory mcp --transport streamable-http --port 8000
+# or, with no install:
+uvx basic-memory mcp --transport streamable-http --port 8000
 ```
 
 This exposes Basic Memory at `http://localhost:8000/mcp`.
@@ -183,7 +187,7 @@ For the full list of tools Codex can use, see the [MCP Tools Reference](/referen
 
 ## Troubleshooting
 
-**Codex CLI can't find Basic Memory** — Verify it's installed (`basic-memory --version`), check MCP config (`codex mcp list`), and reinstall if needed:
+**Codex CLI can't find Basic Memory** — Check the MCP config (`codex mcp list`) and re-add the server if the entry looks wrong; for a local uvx setup, verify uvx can run it (`uvx basic-memory --version`):
 
 ```bash
 codex mcp remove basic-memory
diff --git a/content/7.integrations/3.chatgpt.md b/content/08.integrations/04.chatgpt.md
similarity index 67%
rename from content/7.integrations/3.chatgpt.md
rename to content/08.integrations/04.chatgpt.md
index 126d829..b92c759 100644
--- a/content/7.integrations/3.chatgpt.md
+++ b/content/08.integrations/04.chatgpt.md
@@ -10,7 +10,7 @@ ChatGPT supports remote MCP servers, giving it access to your Basic Memory knowl
 ::steps
 ### Sign Up
 
-Create your account at [app.basicmemory.com](https://app.basicmemory.com).
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=chatgpt).
 
 ### Get Your MCP Endpoint
 
@@ -18,7 +18,7 @@ Your remote MCP URL: `https://cloud.basicmemory.com/mcp`
 
 ### Configure ChatGPT
 
-In ChatGPT, go to **Settings > Developer > Custom MCP Servers** and add:
+In ChatGPT, go to **Settings → Apps & Connectors → Advanced settings** and enable **Developer mode**. Then click **Create** and enter:
 
 - **Name**: Basic Memory
 - **Server URL**: `https://cloud.basicmemory.com/mcp`
@@ -33,7 +33,7 @@ When chatting, enable Basic Memory from the MCP server selector to start using y
 ::
 
 ::tip
-See the [Cloud Setup Guide](/cloud/cloud-guide) for detailed instructions.
+See the [Cloud Guide](/cloud/cloud-guide) for account setup, the web app, and sync options.
 ::
 
 ## Try It
@@ -42,27 +42,27 @@ Once connected, ask ChatGPT to work with your knowledge base:
 
 - **Search**: "Find my notes about authentication design"
 - **Retrieve**: "Show me the full contents of my API documentation"
-- **Semantic search**: "Find notes conceptually related to microservice architecture" (requires full MCP access)
+- **Semantic search**: "Find notes conceptually related to microservice architecture" — the default `search` tool already searches semantically (hybrid mode)
 
 ChatGPT will call the appropriate tools behind the scenes, searching and fetching documents as needed.
 
 ## Important Notes
 
 ::warning
-**ChatGPT Plus or Pro subscription required.** MCP integration is not available on ChatGPT's free tier.
+**A paid ChatGPT plan is required** (Plus, Pro, Business/Team, Enterprise, or Edu). MCP integration is not available on the free tier.
 ::
 
 ::note
 **Default vs full MCP access**
 
-By default, ChatGPT exposes two tools: `search` for finding content and `fetch` for retrieving documents. To unlock all 17+ MCP tools — including `write_note`, `edit_note`, semantic search with text/vector/hybrid modes, and project management — explicitly enable the Basic Memory MCP server in ChatGPT's developer settings.
+In ChatGPT's standard search and deep-research contexts, connectors only call two tools: `search` and `fetch`. Conversations with the Developer-mode connector enabled get the full tool set — `write_note`, `edit_note`, explicit search modes, and project management.
 
 See the [MCP Tools Reference](/reference/mcp-tools-reference) for full tool documentation and the [Semantic Search](/concepts/semantic-search) guide for search mode details.
 ::
 
 ## Troubleshooting
 
-**"MCP server not available"** — Confirm you have a ChatGPT Plus or Pro subscription. MCP is not available on the free tier.
+**"MCP server not available"** — Confirm you're on a paid ChatGPT plan. MCP is not available on the free tier.
 
 **Authentication errors** — Re-add the MCP server in ChatGPT settings and complete the OAuth flow again.
 
@@ -86,7 +86,7 @@ title: MCP Tools Reference
 icon: i-lucide-wrench
 to: /reference/mcp-tools-reference
 ---
-Complete documentation for all 17+ MCP tools.
+Complete documentation for every MCP tool.
 ::
 
 ::card
diff --git a/content/7.integrations/4.gemini.md b/content/08.integrations/05.gemini.md
similarity index 86%
rename from content/7.integrations/4.gemini.md
rename to content/08.integrations/05.gemini.md
index e1e5f5a..292cc19 100644
--- a/content/7.integrations/4.gemini.md
+++ b/content/08.integrations/05.gemini.md
@@ -11,7 +11,7 @@ No local install needed -- Basic Memory Cloud gives you hosted MCP access.
 
 ::steps
 ### Sign Up
-Create your account at [app.basicmemory.com](https://app.basicmemory.com).
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=gemini).
 
 ### Add the Remote MCP Server
 
@@ -20,7 +20,7 @@ gemini mcp add -t http basic-memory-cloud https://cloud.basicmemory.com/mcp
 ```
 
 ### Authenticate
-Follow the OAuth flow to grant Gemini access to your Basic Memory account.
+Start `gemini` — your browser opens to authorize Basic Memory Cloud (or run `/mcp auth basic-memory-cloud` inside Gemini).
 
 ### Verify
 
@@ -112,7 +112,7 @@ For the full list of available tools, see the [MCP Tools Reference](/reference/m
 
 ## Troubleshooting
 
-**Gemini can't find Basic Memory** -- Verify it's installed (`basic-memory --version`), then check `gemini mcp list`. If the entry looks wrong, remove and re-add it:
+**Gemini can't find Basic Memory** -- Verify uvx can run it (`uvx basic-memory --version`), then check `gemini mcp list`. If the entry looks wrong, remove and re-add it:
 ```bash
 gemini mcp remove basic-memory
 gemini mcp add basic-memory bash -c "uvx basic-memory mcp"
@@ -120,7 +120,7 @@ gemini mcp add basic-memory bash -c "uvx basic-memory mcp"
 
 **memory:// URLs not resolving** -- Make sure the note exists in your current project and that sync is running (`basic-memory status`).
 
-**Notes not updating** -- Check file permissions in your knowledge base directory and look for errors in `~/.basic-memory/logs`.
+**Notes not updating** -- Check file permissions in your knowledge base directory and look for errors in `~/.basic-memory/basic-memory.log`.
 
 ---
 
diff --git a/content/7.integrations/10.openclaw.md b/content/08.integrations/06.openclaw.md
similarity index 71%
rename from content/7.integrations/10.openclaw.md
rename to content/08.integrations/06.openclaw.md
index ee5b820..633632a 100644
--- a/content/7.integrations/10.openclaw.md
+++ b/content/08.integrations/06.openclaw.md
@@ -3,11 +3,11 @@ title: "OpenClaw Plugin"
 description: "Give OpenClaw agents persistent Basic Memory with composited search, auto-capture, slash commands, and bundled workflow skills."
 ---
 
-The [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-memory) plugin connects Basic Memory to OpenClaw, giving agents persistent, searchable memory stored as plain Markdown files. Agents gain composited memory search, automatic context recall, conversation capture, slash commands, and bundled workflow skills — all with zero configuration.
-The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/openclaw-basic-memory).
+The [openclaw-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw) plugin connects Basic Memory to OpenClaw, giving agents persistent, searchable memory stored as plain Markdown files. Agents gain composited memory search, automatic context recall, conversation capture, slash commands, and bundled workflow skills — all with zero configuration.
+The plugin is open source and lives in the basic-memory monorepo — browse the source in [`integrations/openclaw`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw).
 
 ::tip
-Requires [OpenClaw](https://openclaw.dev) and a local Basic Memory installation. The plugin auto-installs the `bm` CLI on first startup if it's not already on your PATH.
+Requires [OpenClaw](https://openclaw.dev) and [uv](https://docs.astral.sh/uv/) (`brew install uv` or the curl installer). The plugin auto-installs the `bm` CLI via uv on first startup if it's not already on your PATH.
 ::
 
 ---
@@ -18,6 +18,7 @@ Install the plugin and restart the gateway:
 
 ```bash
 openclaw plugins install @basicmemory/openclaw-basic-memory
+openclaw plugins enable openclaw-basic-memory --slot memory
 openclaw gateway restart
 ```
 
@@ -31,8 +32,8 @@ The plugin works out of the box with `enabled: true`. For advanced setups, confi
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `project` | — | Basic Memory project name |
-| `projectPath` | — | Path to project directory |
+| `project` | `openclaw-{hostname}` | Basic Memory project name |
+| `projectPath` | `.` (workspace root) | Path to project directory |
 | `memoryDir` | `memory/` | Directory for memory files |
 | `memoryFile` | `MEMORY.md` | Primary memory file name |
 | `autoCapture` | `true` | Record conversation turns as daily notes |
@@ -67,7 +68,7 @@ The plugin maintains a long-lived Basic Memory process over stdio, avoiding star
 
 ### Multi-Project & Cloud Access
 
-Because the plugin uses the full Basic Memory stack, your OpenClaw agent has access to every project in your knowledge base — not just a single workspace. Use `list_memory_projects` to browse projects and switch between them on the fly.
+Because the plugin uses the full Basic Memory stack, your OpenClaw agent has access to every project in your knowledge base — not just a single workspace. Use `list_memory_projects` to browse projects, then pass the optional `project` parameter on any tool call to operate on a different project.
 
 This also means your agent benefits from [local/cloud routing](/cloud/routing). You can keep the agent's own memory local while routing shared or team projects through Basic Memory Cloud, or run everything in the cloud for cross-device access. The agent uses the same tools either way — routing is transparent.
 
@@ -81,7 +82,7 @@ In practice, your OpenClaw agent gets:
 
 ## Agent Tools
 
-The plugin exposes 14 tools to your OpenClaw agent:
+The plugin exposes Basic Memory's tools to your OpenClaw agent:
 
 | Tool | Description |
 |------|-------------|
@@ -90,7 +91,7 @@ The plugin exposes 14 tools to your OpenClaw agent:
 | `search_notes` | Full-text and semantic search across notes |
 | `read_note` | Read a note by title, permalink, or memory:// URL |
 | `write_note` | Create or update a note |
-| `edit_note` | Incremental edits (append, prepend, find/replace) |
+| `edit_note` | Incremental edits (append, prepend, find/replace, replace section) |
 | `delete_note` | Delete a note from the knowledge base |
 | `move_note` | Move a note with database consistency |
 | `build_context` | Navigate the knowledge graph via memory:// URLs |
@@ -104,33 +105,27 @@ The plugin exposes 14 tools to your OpenClaw agent:
 
 ## Slash Commands
 
+Three built-ins, plus one command per bundled skill (the skill name minus the `memory-` prefix):
+
 | Command | Description |
 |---------|-------------|
-| `/bm-setup` | Initialize Basic Memory configuration |
+| `/bm-setup` | Install or update the Basic Memory CLI (requires uv) |
 | `/remember` | Save something to memory |
 | `/recall` | Search and retrieve from memory |
 | `/tasks` | Manage structured task notes |
 | `/reflect` | Review conversations and extract insights |
 | `/defrag` | Split bloated files, merge duplicates, restructure |
 | `/schema` | Schema lifecycle — infer, validate, detect drift |
+| `/notes`, `/ingest`, `/lifecycle`, `/metadata-search`, `/research` | One per remaining bundled skill |
 
 ---
 
 ## Bundled Skills
 
-The plugin ships with 6 pre-built skills that teach agents best practices for Basic Memory workflows:
-
-| Skill | Purpose |
-|-------|---------|
-| **memory-notes** | Core note format — frontmatter, observations, relations |
-| **memory-tasks** | Structured task tracking that survives context compaction |
-| **memory-schema** | Schema lifecycle — infer, validate, detect drift |
-| **memory-reflect** | Review conversations, extract insights, consolidate knowledge |
-| **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy |
-| **memory-metadata-search** | Query notes by custom frontmatter fields |
+The plugin bundles a core subset of the [skills collection](/integrations/skills) — drawn from the same source, covering note format, tasks, schemas, reflection, defrag, metadata search, ingest, lifecycle, and research. No separate install needed for those.
 
 ::note
-These are the same skills available in the standalone [skills collection](/integrations/skills), bundled for convenience.
+Skills not bundled (like memory-capture, memory-continue, memory-curate, and memory-literary-analysis) can be installed from the [full collection](/integrations/skills).
 ::
 
 ---
@@ -178,7 +173,7 @@ Understand schema validation for structured notes.
 ---
 title: GitHub Repository
 icon: i-lucide-github
-to: https://github.com/basicmachines-co/openclaw-basic-memory
+to: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw
 ---
 Source code, issues, and contributing guide.
 ::
diff --git a/content/7.integrations/11.hermes.md b/content/08.integrations/07.hermes.md
similarity index 72%
rename from content/7.integrations/11.hermes.md
rename to content/08.integrations/07.hermes.md
index 73325f0..ebf4e9b 100644
--- a/content/7.integrations/11.hermes.md
+++ b/content/08.integrations/07.hermes.md
@@ -1,13 +1,13 @@
 ---
 title: "Hermes Plugin"
-description: "Give Hermes Agent persistent Basic Memory: search-before-answer recall, per-turn capture, end-of-session summaries, 10 agent tools, slash commands, and a bundled skill."
+description: "Give Hermes Agent persistent Basic Memory: search-before-answer recall, per-turn capture, end-of-session summaries, agent tools, slash commands, and a bundled skill."
 ---
 
-The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memory) plugin connects Basic Memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent), giving agents a persistent knowledge graph stored as plain Markdown. Hermes ships with no external memory provider by default; this plugin replaces that with a real graph — search-before-answer recall, automatic conversation capture, end-of-session summaries, and a curated set of `bm_*` tools the agent can call directly.
-The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/hermes-basic-memory).
+The [hermes-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes) plugin connects Basic Memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent), giving agents a persistent knowledge graph stored as plain Markdown. Hermes ships with no external memory provider by default; this plugin replaces that with a real graph — search-before-answer recall, automatic conversation capture, end-of-session summaries, and a curated set of `bm_*` tools the agent can call directly.
+The plugin is open source and lives in the basic-memory monorepo — browse the source in [`integrations/hermes`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes).
 
 ::warning
-**Slash commands need a Hermes Agent-side patch on current releases.** The plugin's agent tools (`bm_*`) and auto-capture work as documented once installed. The native `/bm-*` **slash commands**, however, do not appear in gateway sessions on Hermes Agent releases through `v0.14.0` / `v2026.5.16` (verified 2026-05-16). This is a Hermes Agent plugin-loading gap — exclusive memory-provider plugins aren't loaded during gateway slash-command discovery — not a plugin bug. The plugin ships a best-effort workaround, but it isn't sufficient for gateway startup discovery in affected builds. Until the upstream Hermes fix lands, apply the Hermes Agent-side patch documented in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md). This affects only the slash-command surface; nothing else in this page depends on it.
+**Slash commands may need a Hermes Agent-side patch.** The plugin's agent tools (`bm_*`) and auto-capture work as documented once installed. On affected Hermes Agent releases, the native `/bm-*` **slash commands** don't appear in gateway sessions — a Hermes plugin-loading gap (exclusive memory-provider plugins aren't loaded during gateway slash-command discovery), not a plugin bug. **How to tell if you're affected:** install the plugin, restart the gateway, and type `/bm-` — if no commands autocomplete, apply the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md) (it also lists affected versions). This affects only the slash-command surface; nothing else on this page depends on it.
 ::
 
 ::tip
@@ -21,7 +21,7 @@ Requires [Hermes Agent](https://github.com/NousResearch/hermes-agent) and [`uv`]
 Install the plugin:
 
 ```bash
-hermes plugins install basicmachines-co/hermes-basic-memory
+hermes plugins install basicmachines-co/basic-memory --path integrations/hermes
 ```
 
 Then activate it in `~/.hermes/config.yaml`:
@@ -111,7 +111,7 @@ In practice the Hermes agent gets:
 
 ## Agent Tools
 
-The plugin exposes 10 tools (a curated subset of Basic Memory's MCP surface):
+The plugin exposes a curated subset of Basic Memory's MCP surface:
 
 | Tool | Description |
 |------|-------------|
@@ -135,7 +135,7 @@ Every read/write tool also accepts `project` / `project_id` for per-call routing
 ## Slash Commands
 
 ::note
-On Hermes Agent releases through `v0.14.0` / `v2026.5.16`, these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md) — see the warning at the top of this page. The agent tools above are unaffected.
+On affected Hermes Agent releases, these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md) — see the warning at the top of this page. The agent tools above are unaffected.
 ::
 
 For direct, in-session use without going through the agent:
@@ -155,7 +155,7 @@ For direct, in-session use without going through the agent:
 
 ## Bundled Skill
 
-The plugin ships a `basic-memory` skill that gives the agent a longer reference doc on top of the always-on guidance: the note format, cross-project routing, permalink shapes, and a worked discovery → route → write → verify recipe. It's opt-in via `skill:view basic-memory:basic-memory`.
+The plugin ships a `basic-memory` skill — a longer reference doc on top of the short usage guidance the plugin always injects into the agent's context. It covers the note format, cross-project routing, permalink shapes, and a worked discovery → route → write → verify recipe. It's opt-in via `skill:view basic-memory:basic-memory`.
 
 ---
 
@@ -202,7 +202,7 @@ The sibling plugin for OpenClaw agents.
 ---
 title: GitHub Repository
 icon: i-lucide-github
-to: https://github.com/basicmachines-co/hermes-basic-memory
+to: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes
 ---
 Source code, issues, and contributing guide.
 ::
diff --git a/content/7.integrations/6.cursor.md b/content/08.integrations/08.cursor.md
similarity index 79%
rename from content/7.integrations/6.cursor.md
rename to content/08.integrations/08.cursor.md
index 1954c43..af5f93f 100644
--- a/content/7.integrations/6.cursor.md
+++ b/content/08.integrations/08.cursor.md
@@ -11,10 +11,10 @@ Cursor's built-in memories store short preference strings. Basic Memory gives it
 
 ::steps
 ### Sign Up
-Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=cursor)
 
 ### Configure Remote MCP in Cursor
-Go to **Settings > Developer > Edit Config**, select **MCP Tools**, click **Add Custom MCP**, and add:
+Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root — you can also reach this from **Cursor Settings → MCP**:
 
 ```json
 {
@@ -43,7 +43,7 @@ See the [Cloud Setup Guide](/cloud/cloud-guide) for detailed instructions and tr
 
 ::steps
 ### Configure MCP
-Cursor supports MCP natively. Add Basic Memory following the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol):
+Cursor supports MCP natively. Add Basic Memory to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) — see the [Cursor MCP docs](https://cursor.com/docs/context/mcp):
 
 ```json
 {
@@ -96,9 +96,9 @@ For the full list of available tools, see the [MCP Tools Reference](/reference/m
 
 ## Troubleshooting
 
-**MCP tools not appearing** — Verify Basic Memory is installed (`basic-memory --version`), check your JSON config syntax, and restart Cursor. Try an absolute path to `uvx` if needed.
+**MCP tools not appearing** — Verify uvx can run it (`uvx basic-memory --version`), check your JSON config syntax, and restart Cursor. Try an absolute path to `uvx` if needed.
 
-**Tools appear but don't work** — Run `basic-memory status` to check sync. Verify project directory permissions and that `which basic-memory` resolves.
+**Tools appear but don't work** — Verify project directory permissions. If you installed the CLI (`uv tool install basic-memory`), run `basic-memory status` to check sync — `which basic-memory` only resolves for installed setups, not uvx.
 
 **Cloud connection issues** — See the [Cloud Setup Guide](/cloud/cloud-guide) for OAuth troubleshooting.
 
diff --git a/content/7.integrations/7.vscode.md b/content/08.integrations/09.vscode.md
similarity index 63%
rename from content/7.integrations/7.vscode.md
rename to content/08.integrations/09.vscode.md
index 784ada0..56a0cc6 100644
--- a/content/7.integrations/7.vscode.md
+++ b/content/08.integrations/09.vscode.md
@@ -13,10 +13,14 @@ Basic Memory Cloud lets you edit locally in VS Code while keeping notes synced t
 
 ::steps
 ### Sign Up for Basic Memory Cloud
-Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=vscode)
 
-### Enable Cloud Mode
-Authenticate and enable cloud mode:
+::note
+The sync workflow needs the Basic Memory CLI — see [Local Installation](/local/local-install) for setup.
+::
+
+### Log In to Basic Memory Cloud
+Authenticate with your account:
 
 ```bash
 bm cloud login
@@ -31,50 +35,47 @@ bm cloud setup
 
 This installs rclone automatically and configures your cloud credentials.
 
-::note
-Sync requires the Basic Memory CLI. See [Local Installation](/local/local-install) for setup.
-::
-
 ### Create Project with Local Sync
 Point Basic Memory to your local workspace:
 
 ```bash
 # For a project-specific docs folder
-bm project add my-project --local-path ~/workspace/my-project/docs
+bm project add my-project --cloud --local-path ~/workspace/my-project/docs
 
 # Or for a shared knowledge base
-bm project add knowledge --local-path ~/Documents/knowledge
+bm project add knowledge --cloud --local-path ~/Documents/knowledge
 ```
 
-### Establish Sync Baseline
-Preview and run the initial sync:
+Full setup mechanics — conflicts, one-way mirrors, team workspaces — are in the [Cloud Sync Guide](/cloud/cloud-sync).
+
+### Pull Your Project Down
+Preview and run the initial pull:
 
 ```bash
 # Preview first (recommended)
-bm cloud bisync --name my-project --resync --dry-run
+bm cloud pull --name my-project --dry-run
 
-# Establish baseline
-bm cloud bisync --name my-project --resync
+# Fetch the cloud files
+bm cloud pull --name my-project
 ```
 
-Only use `--resync` for the first sync.
-
 ### Edit in VS Code
 Open your local directory in VS Code. Edit files with full IDE features -- syntax highlighting, markdown preview, split editors, and search all work out of the box.
 
 ### Sync Changes
-After editing locally or making changes in cloud, run bidirectional sync:
+Pull cloud changes down before you start, push local changes up when you're done:
 
 ```bash
-bm cloud bisync --name my-project
+bm cloud pull --name my-project
+bm cloud push --name my-project
 ```
 
-Changes flow both directions. Edit locally or in the cloud, both stay in sync.
+Changes flow both directions — additively, so nothing gets deleted on either side.
 
 ::
 
 ::note
-**Bidirectional sync**: `bisync` keeps local and cloud in sync automatically. Newer files win conflicts. For one-way sync and advanced configuration, see the [Cloud Sync Guide](/cloud/cloud-sync).
+**Additive sync**: `pull` and `push` never delete files on the destination. If the same note changed on both sides, the command aborts and lists the conflicts — resolve with `--on-conflict`. See the [Cloud Sync Guide](/cloud/cloud-sync) for details.
 ::
 
 ---
@@ -88,7 +89,7 @@ If you're running Basic Memory locally (no cloud), setup is simple:
 uv tool install basic-memory
 
 # Add a project pointing to a folder
-bm project add my-project --local-path ~/workspace/my-project/docs
+bm project add my-project ~/workspace/my-project/docs
 ```
 
 Then open that folder in VS Code. That's it -- your markdown files are the knowledge base. Every edit you make is automatically synced to the knowledge graph.
@@ -116,7 +117,7 @@ bm tool search-notes "how to handle errors" --hybrid
 bm tool recent-activity --timeframe "2 days"
 
 # Write a quick note
-bm tool write-note --title "API Design Decision" --folder "decisions"
+echo "Decided to version the API from day one" | bm tool write-note --title "API Design Decision" --folder "decisions"
 ```
 
 Set up aliases in your shell profile (`.bashrc`, `.zshrc`, etc.) for faster access:
@@ -129,7 +130,7 @@ alias recent="bm tool recent-activity"
 
 ### Copilot Chat with MCP
 
-VS Code's Copilot Chat now supports MCP servers. You can add Basic Memory as an MCP server in your VS Code settings and use it directly through Copilot -- search your knowledge base, write notes, and build context without leaving the chat panel. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for setup details.
+VS Code's Copilot Chat now supports MCP servers. Add Basic Memory in your VS Code MCP settings — local: command `uvx` with args `["basic-memory", "mcp"]`; cloud: the remote endpoint `https://cloud.basicmemory.com/mcp` — and use it directly through Copilot: search your knowledge base, write notes, and build context without leaving the chat panel. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for setup details.
 
 ---
 
@@ -142,7 +143,7 @@ Check sync status with `bm status` and verify file permissions in your project d
 VS Code's built-in search works for text matches. For knowledge graph queries and semantic search, use the CLI: `bm tool search-notes "your query"`.
 
 **Cloud sync conflicts?**
-Run `bm cloud bisync --name my-project --dry-run` to preview before syncing. See the [Cloud Sync Guide](/cloud/cloud-sync) for conflict resolution.
+Run `bm cloud pull --name my-project --dry-run` to preview before syncing, and use `--on-conflict` to choose what survives. See the [Cloud Sync Guide](/cloud/cloud-sync) for conflict resolution.
 
 ---
 
diff --git a/content/7.integrations/8.obsidian.md b/content/08.integrations/10.obsidian.md
similarity index 76%
rename from content/7.integrations/8.obsidian.md
rename to content/08.integrations/10.obsidian.md
index 30f7116..783df48 100644
--- a/content/7.integrations/8.obsidian.md
+++ b/content/08.integrations/10.obsidian.md
@@ -21,10 +21,10 @@ Sync requires the Basic Memory CLI. See [Local Installation](/local/local-instal
 
 ::steps
 ### Sign Up for Basic Memory Cloud
-Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=obsidian)
 
-### Enable Cloud Mode
-Authenticate and enable cloud mode:
+### Log In to Basic Memory Cloud
+Authenticate with your account:
 
 ```bash
 bm cloud login
@@ -44,39 +44,44 @@ Point Basic Memory to your Obsidian vault:
 
 ```bash
 # If you have an existing vault
-bm project add my-vault --local-path ~/path/to/obsidian-vault
+bm project add my-vault --cloud --local-path ~/path/to/obsidian-vault
 
 # Or create a new project
-bm project add notes --local-path ~/Documents/notes
+bm project add notes --cloud --local-path ~/Documents/notes
 ```
 
-### Establish Sync Baseline
-Preview and run the initial sync:
+### First Sync
+**Existing vault?** The new cloud project is empty — push your notes up to seed it:
 
 ```bash
-# Preview first (recommended)
-bm cloud bisync --name my-vault --resync --dry-run
+bm cloud push --name my-vault --dry-run
+bm cloud push --name my-vault
+```
+
+**Notes already in cloud?** Pull them down instead:
 
-# If all looks good, establish baseline
-bm cloud bisync --name my-vault --resync
+```bash
+bm cloud pull --name my-vault --dry-run
+bm cloud pull --name my-vault
 ```
 
-Only use `--resync` for the first sync.
+The login/setup mechanics are covered in full in the [Cloud Sync Guide](/cloud/cloud-sync).
 
 ### Open Your Vault in Obsidian
 Open your local directory as a vault in Obsidian. You get full graph view, plugins, and editing.
 
 ### Sync Changes
-After editing in Obsidian or making changes via AI assistants in the cloud, sync both directions:
+After editing in Obsidian, push your changes up; after changes land in the cloud (AI assistants, web app), pull them down:
 
 ```bash
-bm cloud bisync --name my-vault
+bm cloud pull --name my-vault
+bm cloud push --name my-vault
 ```
 
 ::
 
 ::note
-**Bidirectional sync**: `bisync` keeps local and cloud in sync. Changes flow both ways, with newer files winning conflicts. For one-way sync and advanced options, see the [Cloud Sync Guide](/cloud/cloud-sync).
+**Additive sync**: `pull` and `push` never delete files on the destination. If the same note changed on both sides, the command aborts and lists the conflicts — resolve with `--on-conflict`. See the [Cloud Sync Guide](/cloud/cloud-sync) for details.
 ::
 
 ---
@@ -137,7 +142,7 @@ Use [schemas](/concepts/schema-system) to keep your notes consistent whether you
 
 **Canvas files not opening**: Update to the latest Obsidian version and enable the Canvas core plugin.
 
-**Notes not syncing to cloud**: Run `bm cloud bisync --name <project>` after editing. See the [Cloud Sync Guide](/cloud/cloud-sync) for details.
+**Notes not syncing to cloud**: Run `bm cloud push --name <project>` after editing. See the [Cloud Sync Guide](/cloud/cloud-sync) for details.
 
 ## Next Steps
 
@@ -149,7 +154,7 @@ Use [schemas](/concepts/schema-system) to keep your notes consistent whether you
   Define consistent structures for your notes.
   ::
   ::card{title="Cloud Sync" to="/cloud/cloud-sync"}
-  Set up bidirectional sync between local and cloud.
+  Sync your vault with cloud using push and pull.
   ::
   ::card{title="Claude Desktop" to="/integrations/claude-desktop"}
   Connect your AI assistant to the same knowledge base.
diff --git a/content/7.integrations/9.skills.md b/content/08.integrations/11.skills.md
similarity index 61%
rename from content/7.integrations/9.skills.md
rename to content/08.integrations/11.skills.md
index 5e349db..d313876 100644
--- a/content/7.integrations/9.skills.md
+++ b/content/08.integrations/11.skills.md
@@ -4,7 +4,7 @@ description: Pre-built skills that teach AI agents how to use Basic Memory effec
 ---
 
 Agent skills are markdown instruction files (`SKILL.md`) that teach AI coding agents best practices for using Basic Memory's MCP tools. Your agent already has access to the tools — skills teach it *when* and *how* to use them effectively, with examples and patterns for specific workflows.
-The skills are open source — browse the full collection on [GitHub](https://github.com/basicmachines-co/basic-memory-skills).
+The skills are open source and live in the basic-memory monorepo — browse the full collection in [`skills/`](https://github.com/basicmachines-co/basic-memory/tree/main/skills). (The former `basic-memory-skills` repository is now just a distribution target; development happens in the monorepo.)
 
 ::tip
 Skills work with Claude Desktop, Claude Code, Cursor, Windsurf, and any agent that supports markdown-based skill files.
@@ -16,24 +16,31 @@ Skills work with Claude Desktop, Claude Code, Cursor, Windsurf, and any agent th
 
 ### npx (Recommended)
 
+`npx` ships with Node.js — if you don't have it, [install Node.js](https://nodejs.org/en/download) first.
+
 Install all skills at once:
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills
+npx skills add basicmachines-co/basic-memory/skills
 ```
 
 Or install a single skill:
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks
+npx skills add basicmachines-co/basic-memory/skills --skill memory-tasks
 ```
 
-Target a specific agent:
+Target a specific agent, or list what's available first:
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills --agent claude
+npx skills add basicmachines-co/basic-memory/skills --agent claude
+npx skills add basicmachines-co/basic-memory/skills --list
 ```
 
+::note
+If your installed Skills CLI can't load `basicmachines-co/basic-memory/skills`, update the CLI or copy the `memory-*` directories manually (see below).
+::
+
 ### Claude Desktop
 
 1. Open **Settings → Capabilities**
@@ -45,27 +52,48 @@ npx skills add basicmachines-co/basic-memory-skills --agent claude
 Clone the repo and copy skill folders to your agent's skills directory:
 
 ```bash
-git clone https://github.com/basicmachines-co/basic-memory-skills.git
-cp -r basic-memory-skills/memory-notes ~/.claude/skills/
+git clone https://github.com/basicmachines-co/basic-memory.git
+cp -r basic-memory/skills/memory-notes ~/.claude/skills/
 ```
 
 For project-scoped skills, copy to `.claude/skills/` in your project root instead.
 
 ---
 
+## Using skills
+
+You don't need special syntax — once installed, skills activate when your request matches what they teach. Asking "where did we leave off?" pulls in `memory-continue`; pasting a meeting transcript triggers `memory-ingest`.
+
+When you want a specific behavior, name the skill in plain language:
+
+```text
+"Use the /memory-notes skill to write up what we just discussed."
+"Use /memory-continue to pick up where we left off on the auth refactor."
+"Run /memory-defrag on my knowledge base and tell me what you'd clean up."
+"Use /memory-research to look into Model Context Protocol and save what you find."
+```
+
+In Claude Code and Codex, installed skills are also literal slash commands — typing `/memory-notes` on its own invokes it directly.
+
+---
+
 ## Available Skills
 
 | Skill | Purpose |
 |-------|---------|
 | **memory-notes** | Core note format — frontmatter, observations, relations, memory:// URLs |
+| **memory-capture** | Capture the state of a working thread into a single coherent note |
+| **memory-continue** | Resume prior work by rebuilding context from the knowledge graph |
 | **memory-tasks** | Structured task tracking that survives context compaction |
 | **memory-schema** | Schema lifecycle — infer, validate, create definitions, detect drift |
+| **memory-curate** | Find orphan notes, propose relations, merge duplicates, build hub notes |
 | **memory-reflect** | Review conversations, extract insights, consolidate knowledge |
 | **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy |
 | **memory-lifecycle** | Status transitions through folder-based organization, archive-never-delete |
 | **memory-metadata-search** | Query notes by custom frontmatter fields (equality, range, array filters) |
 | **memory-ingest** | Process transcripts, emails, and documents into structured notes |
 | **memory-research** | Web research synthesized into knowledge entities |
+| **memory-literary-analysis** | Analyze a complete literary work into a structured knowledge graph |
 
 ::note
 Start with **memory-notes** — it covers foundational note-writing patterns that all other skills build on.
@@ -79,6 +107,10 @@ Start with **memory-notes** — it covers foundational note-writing patterns tha
 
 **memory-schema** — Schema lifecycle management. Discovers unschemaed notes, infers schemas from existing content, creates and edits definitions, validates notes against schemas, and detects drift.
 
+**memory-capture** — Captures the state of a working thread into a single coherent note — synthesizing where it landed, not an append-log. Re-captures rewrite the same note in place.
+
+**memory-continue** — Resumes prior work by rebuilding context from the knowledge graph — `build_context` via memory:// URLs, recent activity, and search. The "where were we?" skill.
+
 ### Knowledge Maintenance
 
 **memory-reflect** — Inspired by sleep-time compute patterns. Reviews recent conversations, extracts insights, and consolidates them into your knowledge base. Works well as a scheduled daily or twice-daily routine.
@@ -87,6 +119,8 @@ Start with **memory-notes** — it covers foundational note-writing patterns tha
 
 **memory-lifecycle** — Entity lifecycle management. Manages status transitions through folder-based organization with an archive-never-delete philosophy — information is preserved through moves, not removal.
 
+**memory-curate** — Knowledge-graph curation. Finds orphan notes and suggests links, proposes typed relations, merges duplicates, audits tags and folders, and builds hub notes.
+
 ### Advanced Workflows
 
 **memory-metadata-search** — Structured metadata search. Query notes by custom frontmatter fields using equality, range, array, and nested filters. Useful for finding notes by status, priority, or any custom YAML fields.
@@ -95,6 +129,8 @@ Start with **memory-notes** — it covers foundational note-writing patterns tha
 
 **memory-research** — Performs web research and synthesizes findings into Basic Memory entities. Use for researching companies, people, technologies, or any topic you want to capture in your knowledge base.
 
+**memory-literary-analysis** — Analyzes a complete literary work into a structured knowledge graph — characters, themes, chapters, locations, symbols, and literary devices.
+
 ---
 
 ## Recommended Combinations
@@ -111,10 +147,10 @@ Capture web research and process external documents into structured knowledge.
 :br
 Keep your knowledge base organized with regular reflection, defragmentation, and lifecycle management.
 
-**Everything** — Install all 9 skills for comprehensive memory management across ingestion, organization, reflection, and lifecycle.
+**Everything** — Install the full set for comprehensive memory management across capture, ingestion, organization, reflection, and lifecycle.
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills
+npx skills add basicmachines-co/basic-memory/skills
 ```
 
 ---
@@ -151,10 +187,10 @@ The tools that skills teach agents to use effectively.
 
 ::card
 ---
-title: GitHub Repository
+title: Skills on GitHub
 icon: i-lucide-github
-to: https://github.com/basicmachines-co/basic-memory-skills
+to: https://github.com/basicmachines-co/basic-memory/tree/main/skills
 ---
-Source code, contributing guide, and issue tracker.
+Source, contributing guide, and issue tracker in the basic-memory monorepo.
 ::
 :::
diff --git a/content/8.how-to/.navigation.yml b/content/09.how-to/.navigation.yml
similarity index 100%
rename from content/8.how-to/.navigation.yml
rename to content/09.how-to/.navigation.yml
diff --git a/content/8.how-to/1.project-documentation.md b/content/09.how-to/1.project-documentation.md
similarity index 80%
rename from content/8.how-to/1.project-documentation.md
rename to content/09.how-to/1.project-documentation.md
index da2f7d4..a9aa7a7 100644
--- a/content/8.how-to/1.project-documentation.md
+++ b/content/09.how-to/1.project-documentation.md
@@ -7,17 +7,21 @@ Basic Memory turns your project's `docs/` folder into a shared knowledge base th
 
 ## Setting Up
 
-Point Basic Memory at a docs folder in your project:
+Create a project for your documentation — ask your AI, and it works the same on cloud and local:
 
-```bash
-# Create a docs folder if you don't have one
-mkdir docs
+```text
+Create a new project called "my-project-docs"
+```
+
+The AI calls `create_memory_project` behind the scenes.
 
-# Register it as a Basic Memory project
-basic-memory project add my-project ~/code/my-project/docs
+**Cloud is a great home for project docs**: browse and edit them in the [web app](/cloud/web-app), give the whole [team](/teams/about) (and their agents) access, and publish any page externally with a [share link](/cloud/shared-notes). Prefer docs living inside the repo? On a local install, point the project at your `docs/` folder instead:
+
+```bash
+bm project add my-project ~/code/my-project/docs
 ```
 
-That's it. Your AI assistant can now read and write documentation in that folder. You'll end up with a structure like this:
+That's it. Your AI assistant can now read and write documentation in that project. You'll end up with a structure like this:
 
 ```
 my-project/
@@ -46,7 +50,7 @@ Your AI creates a well-structured decision record with the context, rationale, a
 
 If you want all your ADRs to follow the same structure, ask the AI to create a schema:
 
-> "Create a schema for our architecture decision records. They should always have a status, context, decision, and consequences section."
+> "Create a schema for our architecture decision records. They should always record a status, context, decision, and consequences."
 
 The AI writes a schema note like this:
 
@@ -60,14 +64,14 @@ schema:
   status: string, current decision status
   context: string, background and problem statement
   decision: string, what was decided
-  consequences?(array, outcomes of the decision): string
+  consequences(array, outcomes of the decision): string
   supersedes?: ADR, previous decision this replaces
 settings:
   validation: warn
 ---
 ```
 
-From that point on, every ADR the AI creates follows this structure. You can validate existing ones too:
+Schema fields are satisfied by observations — an ADR with `- [status] accepted` and `- [decision] Use JWT tokens` passes; markdown headings alone don't count (see [Schema System](/concepts/schema-system)). From that point on, every ADR the AI creates follows this structure. You can validate existing ones too:
 
 ```bash
 bm schema validate adr
@@ -109,7 +113,7 @@ You can also search by specific note properties when you know what you're lookin
 
 > "What patterns have we documented for error handling?"
 
-These use metadata search -- filtering by type, status, tags, and other frontmatter fields. You can also use the `tag:` shorthand in searches, like `tag:api` or `tag:security`.
+The AI combines the right filters for each: `status` on an ADR is an observation category, so it filters with `categories=["status"]`; tags and note types are frontmatter, filtered with [metadata search](/concepts/metadata-search). You can also use the `tag:` shorthand in searches, like `tag:api` or `tag:security`.
 
 For a deeper dive, see [Semantic Search](/concepts/semantic-search).
 
diff --git a/content/8.how-to/2.writing-organization.md b/content/09.how-to/2.writing-organization.md
similarity index 93%
rename from content/8.how-to/2.writing-organization.md
rename to content/09.how-to/2.writing-organization.md
index d8a408b..d3b8d0a 100644
--- a/content/8.how-to/2.writing-organization.md
+++ b/content/09.how-to/2.writing-organization.md
@@ -7,12 +7,22 @@ Basic Memory is a knowledge base that you and your AI share. You write notes in
 
 This page walks through setting up a writing project, developing characters and plot, tracking research, and using schemas and search to keep everything consistent as the project grows.
 
+::note
+**This isn't about AI writing your book.** The failure mode is slop — generated text you never read. Use the agent the other way around: to organize and clarify *your* thinking. You write; it tracks the characters, connections, timelines, and research so nothing gets lost. Everything in the knowledge base should be something you've read and own.
+::
+
 ## Setting Up a Writing Project
 
-Create a dedicated Basic Memory project for your writing:
+Create a dedicated project — ask your AI, and it works the same on cloud and local:
+
+```text
+Create a new project called "my-novel"
+```
+
+A cloud project lets you write from any device and read your notes in the [web app](/cloud/web-app); on a local install you can point the project at a folder instead:
 
 ```bash
-basic-memory project add my-novel ~/writing/my-novel
+bm project add my-novel ~/writing/my-novel
 ```
 
 Then organize your folders however makes sense. A common structure:
diff --git a/content/8.how-to/3.research-learning.md b/content/09.how-to/3.research-learning.md
similarity index 87%
rename from content/8.how-to/3.research-learning.md
rename to content/09.how-to/3.research-learning.md
index 60d6b46..ae905a8 100644
--- a/content/8.how-to/3.research-learning.md
+++ b/content/09.how-to/3.research-learning.md
@@ -28,9 +28,9 @@ The AI creates a detailed note with observations categorized by approach, tagged
 To get consistent structure across all your research notes, set up a schema:
 
 ```
-You: "Create a schema for my research notes. Each one should have
-     sections for key findings, sources, open questions, and connections
-     to other topics."
+You: "Create a schema for my research notes. Each one should record
+     key findings, sources, open questions, and connections to other
+     topics."
 ```
 
 Now every research note the AI writes follows the same format. You can validate notes against the schema later, and your whole research library stays organized without extra effort. See [Schema System](/concepts/schema-system) for details.
@@ -58,7 +58,7 @@ The AI reads across your existing notes, identifies patterns, and produces a new
 
 ## Finding and Exploring Your Research
 
-This is where Basic Memory v0.19 really shines. Once you've built up a collection of research notes, you need to find things -- and not just by exact title.
+This is where Basic Memory really shines. Once you've built up a collection of research notes, you need to find things -- and not just by exact title.
 
 ### Semantic Search
 
@@ -82,11 +82,11 @@ You: "Find notes with status: needs-review"
 You: "Search for tag:open-question in my energy storage project"
 ```
 
-Combine these with semantic search when you need precision. For example, find all notes tagged `literature-review` that relate to a specific concept. See [Semantic Search](/concepts/semantic-search) for the full query syntax.
+Combine these with semantic search when you need precision. For example, find all notes tagged `battery-technology` that relate to a specific concept. See [Semantic Search](/concepts/semantic-search) for the full query syntax.
 
 ### Exploring Connections
 
-Use `build_context` to follow the links between notes:
+Ask your AI to build context around a note to follow its links:
 
 ```
 You: "Show me what connects to my solid-state batteries note"
@@ -114,12 +114,12 @@ You: "Create a literature-review note on the latest solid-state
 
 Once you find a structure that works, lock it in with a schema. A research schema might require:
 
-- A "Key Findings" section with categorized observations
-- A "Sources" section for references
-- An "Open Questions" section
-- A "Relations" section linking to related topics
+- `key-finding` observations for the takeaways
+- `source` observations for references
+- `open-question` observations for what's unresolved
+- Relations linking to related topics
 
-The AI follows the schema automatically. When you come back to your research after a break, everything is in the same format and easy to scan.
+Schemas validate observations, relations, and frontmatter — not markdown headings. With the schema in place (and a [schema-aware assistant](/concepts/schema-system)), every research note comes out in the same format and easy to scan.
 
 ## Learning Workflows
 
diff --git a/content/8.how-to/4.note-taking.md b/content/09.how-to/4.note-taking.md
similarity index 91%
rename from content/8.how-to/4.note-taking.md
rename to content/09.how-to/4.note-taking.md
index 05c54bd..a1a75f5 100644
--- a/content/8.how-to/4.note-taking.md
+++ b/content/09.how-to/4.note-taking.md
@@ -89,7 +89,7 @@ tags: [marketing, strategy, q1-planning]
 
 Notice the `type: meeting` in the frontmatter. Note types help you categorize and filter your knowledge base — meeting, lecture, idea, code-review, or whatever types make sense for your work.
 
-Also notice that the AI used `edit_note` to enhance your existing note rather than creating a new one. Basic Memory's write protection means the AI won't accidentally overwrite your content — it adds to it.
+Behind the scenes, the AI enhances your existing note with `edit_note` rather than creating a new one. Basic Memory's write protection means the AI won't accidentally overwrite your content — it adds to it.
 
 ## Learning and Lecture Notes
 
@@ -138,7 +138,7 @@ Ask by meaning, not keywords:
 
 > "What do I know about Sarah's marketing proposals?"
 
-Semantic search finds relevant notes even when your query uses different words than your notes do. If you wrote about "conversion rates declining" and search for "budget concerns," it still surfaces the right meeting notes because they're semantically related.
+Semantic search finds relevant notes even when your query uses different words than your notes do. If you wrote about "budget concerns" and search for "spending pushback," it still surfaces the right meeting notes because they're semantically related.
 
 ### Metadata Search
 
@@ -146,7 +146,7 @@ For more precise filtering, search by note properties:
 
 > "Show me all meeting notes from this month."
 
-> "Find notes with action items assigned to Sarah."
+> "Find all meeting notes with status open."
 
 > "List all notes tagged with q1-planning."
 
@@ -166,7 +166,7 @@ You can create schemas for any repeating note type:
 
 > "Create a schema for code review notes with files reviewed, issues found, and suggested fixes."
 
-The AI validates notes against schemas as it creates them, so your knowledge base stays organized without extra effort from you.
+The AI follows the schema's structure when creating typed notes, and you can validate anytime — "Validate my meeting notes against the schema" — with warn mode as the gentle default. Your knowledge base stays organized without extra effort from you.
 
 ## Progressive Note Building
 
@@ -184,7 +184,7 @@ Notes don't have to be finished in one sitting. Basic Memory supports an iterati
 
 > "Review the e-commerce planning note and add connections to our previous e-commerce projects, Stripe integration docs, and Q2 revenue goals."
 
-Each iteration uses `edit_note` to append or update sections. The note's history reflects contributions from both you and the AI — and Basic Memory tracks who made each update.
+Each iteration uses `edit_note` to append or update sections. The note grows through contributions from both you and the AI — and in [Basic Memory Cloud](/cloud/file-history), every save is a version you can step back through.
 
 ## Best Practices
 
diff --git a/content/8.how-to/5.personal-knowledge.md b/content/09.how-to/5.personal-knowledge.md
similarity index 90%
rename from content/8.how-to/5.personal-knowledge.md
rename to content/09.how-to/5.personal-knowledge.md
index 7573e08..3938ba5 100644
--- a/content/8.how-to/5.personal-knowledge.md
+++ b/content/09.how-to/5.personal-knowledge.md
@@ -9,7 +9,7 @@ Think of it as a personal life graph. Every note you write — about a goal, a h
 
 ## Getting Started
 
-If you haven't set up Basic Memory yet, see the [getting started guide](/start-here/getting-started). Once it's running, you can start building your personal knowledge base by simply talking to your AI:
+If you haven't set up Basic Memory yet, see the [getting started guide](/local/getting-started). Once it's running, you can start building your personal knowledge base by simply talking to your AI:
 
 > "Create a note about my goal to run a half marathon by December. I've been running 3 times a week and just finished my first 5K in 28 minutes."
 
@@ -63,7 +63,7 @@ This kind of cross-domain insight is only possible because the AI has access to
 
 ### Semantic Search
 
-Basic Memory v0.19 introduces semantic vector search, which means you can search by *meaning* rather than exact words. This is especially powerful for personal knowledge:
+Basic Memory's semantic search means you can search by *meaning* rather than exact words. This is especially powerful for personal knowledge:
 
 > "What patterns do I notice about what energizes me?"
 
@@ -87,7 +87,7 @@ Combining semantic and metadata search gives you powerful ways to review and ana
 
 ## Keeping Things Organized with Schemas
 
-Schemas are a v0.19 feature that let you define consistent structure for different kinds of notes. For personal knowledge management, this means your goals always have the same fields, your reflections follow the same format, and your weekly reviews are easy to compare.
+Schemas let you define consistent structure for different kinds of notes. For personal knowledge management, this means your goals always have the same fields, your reflections follow the same format, and your weekly reviews are easy to compare.
 
 > "Create a schema for goal tracking with fields for status, target date, progress notes, and related life domain."
 
@@ -147,14 +147,15 @@ Personal knowledge is, well, personal. Basic Memory is designed with this in min
 
 **Local-first by default** — Your notes live as markdown files on your machine. Nothing leaves your computer unless you choose to sync it.
 
-**Per-project routing** — With v0.19's per-project routing, you can keep personal notes in a local-only project while routing work projects to the cloud. Your journal entries and health notes stay on your laptop; your team documentation syncs to Basic Memory Cloud. Different projects, different rules.
+**Per-project routing** — you can keep personal notes in a local-only project while routing work projects through Basic Memory Cloud. Your journal entries and health notes stay on your laptop; your work projects run against cloud (to move existing notes there, [push them up](/cloud/cloud-sync) first). Different projects, different rules — see [Local & Cloud Routing](/cloud/routing).
 
 ```bash
 # Personal notes stay local
-basic-memory project add personal ~/notes/personal
+bm project add personal ~/notes/personal
 
-# Work notes can sync to cloud
-basic-memory project add work ~/notes/work --cloud
+# Work notes route through cloud
+bm project add work ~/notes/work
+bm project set-cloud work
 ```
 
 **Choose your level of detail** — You control what goes into your knowledge base. Focus on patterns and insights rather than raw personal details if that feels more comfortable. "I noticed conflict avoidance makes things worse" is more useful than a play-by-play of an argument.
diff --git a/content/1.start-here/5.why-basic-memory.md b/content/1.start-here/5.why-basic-memory.md
deleted file mode 100644
index 627327a..0000000
--- a/content/1.start-here/5.why-basic-memory.md
+++ /dev/null
@@ -1,131 +0,0 @@
----
-title: Why Basic Memory
-description: Your AI already has memory features. Here's why you still want a knowledge base you own — and how Basic Memory is different from the alternatives.
----
-
-Every AI tool is adding memory. Claude builds a memory summary from your chats, and Claude Code has CLAUDE.md and auto memory. ChatGPT remembers facts about you. Obsidian users have been doing this with markdown for years. And a new wave of startups is building memory-as-a-service on top of databases.
-
-So why Basic Memory?
-
-Because none of these solve the whole problem. They each handle a piece of it, but they leave gaps that matter more as your knowledge grows.
-
----
-
-## The three alternatives
-
-### 1. Built-in AI memory
-
-Claude, ChatGPT, Cursor, and others now ship with some form of memory. Claude builds an editable memory summary from your chat history, with a separate memory for each Project. Claude Code has CLAUDE.md files and auto memory. ChatGPT has saved memories and reference chat history. These are useful for quick preferences and recurring context — "I use TypeScript," "I'm vegetarian," "use 2-space indentation."
-
-**Where it falls short:**
-
-- **Capacity-limited.** ChatGPT's saved memories top out around 1,200–1,400 words total — once full, nothing new is saved until you delete entries. Claude keeps one rolling summary per account (plus one per Project). Claude Code's auto memory index caps at 200 lines. None of them can hold a detailed architecture decision, a meeting summary, or a research synthesis.
-- **Siloed.** Claude's memory only works in Claude. ChatGPT's only works in ChatGPT. Each one also learns only from its own conversations — it can't ingest your docs, repos, or existing notes. If you use more than one AI tool, your knowledge is fragmented. A decision captured in Claude Code isn't available when you switch to Cursor or ChatGPT.
-- **Search stops at chat history.** Claude can search past conversations and ChatGPT can reference chat history, but there's no semantic search over structured knowledge, no knowledge graph, no way to ask "find everything related to our authentication approach" and get structured results.
-- **Not yours to keep.** Your memories live in your account on that platform — they're not portable files. If the platform changes its terms, shuts down, or you switch tools, your memories don't come with you.
-
-Basic Memory works alongside built-in memory — it doesn't replace it. Use built-in memory for preferences. Use Basic Memory for everything deeper. See [Basic Memory vs Built-in AI Memory](/concepts/vs-built-in-memory) for the detailed comparison.
-
----
-
-### 2. Obsidian
-
-Obsidian is excellent — and it's the approach closest to Basic Memory's philosophy. Plain markdown files, wiki links, graph view, local-first. With the recent addition of headless mode and CLI commands, Obsidian can even be integrated with AI tools through skills and automation.
-
-If you're already an Obsidian user, you're halfway to Basic Memory's worldview. The question is what you get by adding Basic Memory on top.
-
-**What Basic Memory adds to the Obsidian experience:**
-
-- **Semantic search.** Obsidian's search finds exact text matches. Basic Memory finds notes about "error handling" when you wrote "exception management" — it searches by meaning, not just keywords. Hybrid search combines vector similarity with text matching for the best of both.
-- **A semantic knowledge graph.** Basic Memory parses observations and relations from your notes to build a typed knowledge graph. You can ask "what depends on this decision?" and traverse connections across your entire knowledge base — not just follow backlinks, but navigate structured relationships.
-- **Schemas.** Define what a meeting note or decision record should contain. The AI validates notes against schemas automatically, keeping your knowledge base consistent as it grows.
-- **Cloud access.** Your knowledge is available from any device, with any AI tool. Basic Memory Cloud means your notes aren't stuck on one machine — use them from Claude Desktop at work, ChatGPT on your phone, or Cursor on your laptop.
-- **Cross-tool portability.** Notes created in Claude Code are searchable in ChatGPT, editable in Cursor, and visible in Obsidian. One knowledge base, every AI tool you use.
-
-The best part: you don't have to choose. [Obsidian is a great companion](/integrations/obsidian) for Basic Memory. Point both at the same folder and you get Obsidian's graph view and rich editing, plus AI-powered semantic search, schemas, and cloud access on top.
-
----
-
-### 3. Database-only memory services
-
-A growing number of startups offer AI memory as a service — Mem0, Letta, Supermemory, and others. They store memories in databases behind APIs, often with vector search and cloud infrastructure.
-
-**Where it falls short:**
-
-- **You can't read what the AI knows.** Your knowledge lives in a database you access through an API. You can't open a file, read what's there, fix a mistake, or reorganize your notes. The AI's understanding of you is opaque.
-- **You can't edit it naturally.** Want to refine a decision the AI captured? You need to go through the API or a dashboard. You can't just open a markdown file in your editor and fix it.
-- **Vendor lock-in.** Your knowledge is in a proprietary format in someone else's database. If the service shuts down, changes pricing, or pivots, migrating is painful — if it's possible at all.
-- **Not built for humans.** These tools treat memory as something the AI manages *about* you. Basic Memory treats knowledge as something you and your AI build *together*. You're a participant, not a subject.
-
-Plain text files from 1975 are still readable today. Can you say that about any proprietary database format?
-
----
-
-## What makes Basic Memory different
-
-Basic Memory takes a different position from all three alternatives:
-
-**Your memory is a file you can read.** Not a database entry you can't see. Not a single sentence in a settings page. A full markdown note with observations, relations, and tags — readable in any editor, trackable with git, portable forever.
-
-**Your AI is a collaborator, not a recorder.** Both you and your AI read and write the same files. You capture rough notes, the AI structures them. The AI writes a summary, you refine it. Knowledge flows in both directions.
-
-**It works across every AI tool.** Notes created in Claude Code are available in ChatGPT, Cursor, Gemini, or any MCP-compatible tool. One knowledge base, many interfaces.
-
-**Search finds meaning, not just keywords.** Semantic search finds notes about "login security" even when you wrote "authentication hardening." Combined with text search, metadata filtering, and knowledge graph traversal, you can find anything in your knowledge base.
-
-**Structure grows with you.** Start with simple notes. Add observations and relations when they're useful. Define schemas when you want consistency. The system meets you where you are.
-
----
-
-## The best of all worlds
-
-You don't have to choose one approach. The strongest setup combines them:
-
-- **Built-in memory** for quick preferences your AI tool handles automatically
-- **Basic Memory** for structured knowledge, decisions, research, and context
-- **Obsidian** for visual graph exploration and rich editing alongside Basic Memory
-- **Git** for version history on your knowledge base
-
-Basic Memory is the connective layer that makes your knowledge available everywhere, searchable by meaning, and yours to keep.
-
----
-
-## Get started
-
-:::card-group
-::card
----
-title: "Quickstart: Cloud"
-icon: i-lucide-cloud
-to: /start-here/quickstart-cloud
----
-Connect in 2 minutes, no install needed.
-::
-
-::card
----
-title: "Quickstart: Local"
-icon: i-lucide-hard-drive
-to: /start-here/quickstart-local
----
-Run everything on your machine.
-::
-
-::card
----
-title: Basic Memory vs Built-in AI Memory
-icon: i-lucide-layers
-to: /concepts/vs-built-in-memory
----
-Detailed comparison with Claude, ChatGPT, and Cursor memory.
-::
-
-::card
----
-title: What is Basic Memory
-icon: i-lucide-book-open
-to: /start-here/what-is-basic-memory
----
-How it works under the hood.
-::
-:::
diff --git a/content/9.reference/.navigation.yml b/content/10.reference/.navigation.yml
similarity index 100%
rename from content/9.reference/.navigation.yml
rename to content/10.reference/.navigation.yml
diff --git a/content/9.reference/1.cli-reference.md b/content/10.reference/1.cli-reference.md
similarity index 91%
rename from content/9.reference/1.cli-reference.md
rename to content/10.reference/1.cli-reference.md
index a47d0fd..908d70d 100644
--- a/content/9.reference/1.cli-reference.md
+++ b/content/10.reference/1.cli-reference.md
@@ -98,6 +98,7 @@ bm reindex -p main
 |------|-------------|
 | `--search`, `-s` | Rebuild only the full-text search index |
 | `--embeddings`, `-e` | Rebuild only vector embeddings |
+| `--full` | Force a complete rebuild and re-embed (the default run is incremental and skips unchanged content) |
 | `--project`, `-p` | Target a specific project (default: all projects) |
 
 When neither `--search` nor `--embeddings` is specified, both are rebuilt.
@@ -139,7 +140,7 @@ bm orphans --project research
 
 ### `bm update`
 
-Check for a newer Basic Memory release and install it when supported. Basic Memory also checks for updates automatically in the background for CLI installs (Homebrew, `uv tool`, `uvx`); MCP server processes check silently and never block.
+Check for a newer Basic Memory release and install it when supported. Basic Memory also checks for updates automatically in the background for Homebrew and `uv tool` installs (uvx environments are skipped — uvx resolves its own cache); MCP server processes check silently and never block.
 
 ```bash
 # Check for updates and install if available
@@ -266,7 +267,7 @@ bm project default main
 
 ### `bm project move`
 
-Move a local project to a new filesystem location. Updates the configured path in the database.
+Update a local project's configured filesystem path. This changes configuration only — move the files to the new path yourself (Basic Memory does not move them).
 
 ```bash
 bm project move research /new/path/to/research
@@ -341,22 +342,16 @@ bm cloud push --name research
 bm cloud pull --name research --on-conflict keep-cloud
 
 # One-way mirror: local → cloud (Personal workspaces only)
-bm cloud sync
-
-# Two-way mirror: local ↔ cloud (Personal workspaces only)
-bm cloud bisync
+bm cloud sync --name research
 
 # Verify file integrity between local and cloud (Personal only)
-bm cloud check
-
-# Clear bisync state
-bm cloud bisync-reset
+bm cloud check --name research
 
 # Configure local sync for an existing cloud project
 bm cloud sync-setup research ~/Documents/research
 ```
 
-`push`/`pull` are additive (never delete on the destination) and abort on conflicts by default, git-style. `sync`/`bisync` are destructive mirrors and are blocked on Team workspaces. See the [Cloud Sync guide](/cloud/cloud-sync) for details.
+`push`/`pull` are additive (never delete on the destination) and abort on conflicts by default, git-style. `sync` is a destructive mirror and is blocked on Team workspaces. See the [Cloud Sync guide](/cloud/cloud-sync) for details.
 
 ### Snapshots
 
@@ -413,7 +408,7 @@ bm schema validate person
 # Validate one specific note
 bm schema validate people/ada-lovelace.md
 
-# Strict mode — treat warnings as errors
+# Strict mode — exit 1 if any validation errors are found
 bm schema validate person --strict
 
 # Machine-readable output
@@ -425,7 +420,7 @@ bm schema validate person --project research
 
 | Flag | Description |
 |------|-------------|
-| `--strict` | Treat validation warnings as errors (exit code 1 on any issue) |
+| `--strict` | Exit with code 1 if any validation errors are found (warnings never affect the exit code) |
 | `--json` | Machine-readable JSON output |
 | `--project` | Target a specific project |
 | `--local` | Force local routing |
@@ -442,9 +437,6 @@ bm schema infer person
 # Lower the threshold to include less common fields
 bm schema infer person --threshold 0.1
 
-# Save the inferred schema directly as a schema note
-bm schema infer person --save
-
 # Machine-readable output
 bm schema infer person --json
 
@@ -500,6 +492,9 @@ echo "# My Note" | bm tool write-note --title "My Note" --folder notes
 
 # Set the note type at creation time
 bm tool write-note --title "Standup" --folder meetings --type meeting
+
+# Replace an existing note (past the overwrite guard)
+bm tool write-note --title "API Notes" --folder specs --content "..." --overwrite
 ```
 
 | Flag | Description |
@@ -509,6 +504,7 @@ bm tool write-note --title "Standup" --folder meetings --type meeting
 | `--content` | Note content (reads from stdin if omitted) |
 | `--tags` | Tags to apply |
 | `--type` | Frontmatter note type (e.g. `meeting`, `task`) |
+| `--overwrite` | Replace an existing note at the same path (past the overwrite guard) |
 | `--project` | Target project |
 | `--local` | Force local routing |
 | `--cloud` | Force cloud routing |
@@ -518,14 +514,11 @@ bm tool write-note --title "Standup" --folder meetings --type meeting
 ```bash
 bm tool read-note "specs/api-notes"
 bm tool read-note my-note --include-frontmatter
-bm tool read-note my-note --page 2 --page-size 5
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--include-frontmatter` | Include YAML frontmatter in output |
-| `--page` | Page number for pagination (default `1`) |
-| `--page-size` | Results per page (default `10`) |
 | `--project` | Target project |
 | `--local` | Force local routing |
 | `--cloud` | Force cloud routing |
@@ -540,7 +533,7 @@ bm tool edit-note my-note --operation replace_section --section "## Notes" --con
 
 | Flag | Description |
 |------|-------------|
-| `--operation` | Edit operation: `append`, `prepend`, `find_replace`, `replace_section` (required) |
+| `--operation` | Edit operation: `append`, `prepend`, `find_replace`, `replace_section`, `insert_before_section`, `insert_after_section` (required; the insert operations also require `--section`) |
 | `--content` | Content for the edit (required) |
 | `--find-text` | Text to find (required for `find_replace`) |
 | `--section` | Section heading (required for `replace_section`) |
@@ -575,6 +568,9 @@ bm tool search-notes --tag python --tag async
 bm tool search-notes --meta status=draft
 bm tool search-notes --type person --type meeting
 
+# Search observations by category
+bm tool search-notes "auth" --entity-type observation --category decision
+
 # Search modes
 bm tool search-notes "how to speed up the app" --hybrid
 bm tool search-notes "how to speed up the app" --vector
@@ -598,6 +594,7 @@ bm tool search-notes "api" --page 2 --page-size 20
 | `--status` | Filter by frontmatter status |
 | `--type` | Filter by frontmatter type (repeatable) |
 | `--entity-type` | Filter by result type: `entity`, `observation`, `relation` (repeatable) |
+| `--category` | Filter observation results to exact categories (repeatable) |
 | `--meta` | Filter by frontmatter `key=value` (repeatable) |
 | `--filter` | JSON metadata filter (advanced) |
 | `--after_date` | Date filter (e.g., `2d`, `1 week`) |
@@ -639,7 +636,7 @@ bm tool recent-activity --type entity --type observation
 | `--depth` | Context depth (default `1`) |
 | `--timeframe` | Time window (default `7d`) |
 | `--page` | Page number (default `1`) |
-| `--page-size` | Results per page (default `50`) |
+| `--page-size` | Results per page (default `10`) |
 | `--project` | Target project |
 | `--local` | Force local routing |
 | `--cloud` | Force cloud routing |
@@ -649,7 +646,7 @@ bm tool recent-activity --type entity --type observation
 These are CLI wrappers around the schema MCP tools with JSON output:
 
 ```bash
-bm tool schema-validate --entity-type person
+bm tool schema-validate person
 bm tool schema-infer person
 bm tool schema-diff person
 bm tool list-projects
@@ -662,6 +659,7 @@ bm tool list-workspaces
 
 ```bash
 bm import claude conversations
+bm import claude projects
 bm import chatgpt
 bm import memory-json /path/to/export.json
 ```
@@ -671,7 +669,7 @@ bm import memory-json /path/to/export.json
 ## Notes on defaults
 
 - If `--project` is omitted, Basic Memory falls back to `default_project` when configured.
-- All `bm tool` subcommands support `--workspace` for cloud workspace targeting.
+- Most `bm tool` subcommands accept `--project-id` (the project's external UUID from `bm project list --json`) to disambiguate same-named projects across cloud workspaces.
 - `--local` and `--cloud` flags are available on most commands for routing overrides.
 
 ---
diff --git a/content/10.reference/10.contact-support.md b/content/10.reference/10.contact-support.md
new file mode 100644
index 0000000..3d2168d
--- /dev/null
+++ b/content/10.reference/10.contact-support.md
@@ -0,0 +1,98 @@
+---
+title: Contact Support
+description: Get help with Basic Memory Cloud accounts, billing, workspaces, private data, invitations, and product issues.
+navigation: false
+---
+
+For private account, billing, or Cloud workspace help, email:
+
+```text
+support@basicmemory.com
+```
+
+You can also reach us with the **feedback button** in the web app's lower-left navbar. Use email or feedback when the issue involves information that should not be posted publicly. (For sales and partner inquiries, use `hello@basicmemory.com`.)
+
+---
+
+## Email support for private issues
+
+Contact support when you need help with:
+
+- Account access or sign-in problems.
+- Billing, subscriptions, seats, or checkout.
+- Cloud workspace access, invitations, or team membership.
+- Private projects, notes, or shared-note links.
+- API keys, OAuth sessions, or suspected credential exposure.
+- Product bugs that require private workspace context.
+
+::warning
+Never post API keys, OAuth tokens, billing information, private notes, or invitation links in public support channels.
+::
+
+---
+
+## What to include
+
+To help diagnose the problem, include:
+
+- The email address you use for Basic Memory Cloud.
+- The workspace name, if relevant.
+- What you expected to happen.
+- What happened instead.
+- The page, command, or AI client where the issue occurred.
+- Screenshots or error text with secrets removed.
+
+For CLI issues, these commands are usually safe to include after checking for private paths or tokens:
+
+```bash
+bm --version
+bm status
+bm project list
+bm cloud status
+```
+
+Do not include full API keys, OAuth tokens, raw private notes, or billing details unless support specifically asks for them through a trusted channel.
+
+---
+
+## Public help
+
+Use public channels for general questions, local open-source issues, and reproducible bugs that do not require private context:
+
+- [Basic Memory Discord](https://discord.gg/tyvKNccgqN)
+- [GitHub issues](https://github.com/basicmachines-co/basic-memory/issues)
+
+Public channels are best for installation issues, local MCP configuration, feature requests, documentation problems, and open-source bug reports.
+
+---
+
+## Related guides
+
+:::card-group
+::card
+---
+title: Troubleshooting
+icon: i-lucide-life-buoy
+to: /reference/troubleshooting
+---
+Diagnose common Cloud, MCP, sync, local install, and search issues.
+::
+
+::card
+---
+title: Teams
+icon: i-lucide-users
+to: /teams/about
+---
+Understand workspaces, members, roles, seats, and invitations.
+::
+
+::card
+---
+title: API Keys
+icon: i-lucide-key
+to: /cloud/api-keys
+---
+Create and revoke Cloud API keys safely.
+::
+:::
diff --git a/content/9.reference/2.mcp-tools-reference.md b/content/10.reference/2.mcp-tools-reference.md
similarity index 71%
rename from content/9.reference/2.mcp-tools-reference.md
rename to content/10.reference/2.mcp-tools-reference.md
index edd080b..41ee0ca 100644
--- a/content/9.reference/2.mcp-tools-reference.md
+++ b/content/10.reference/2.mcp-tools-reference.md
@@ -19,9 +19,11 @@ Most tools accept these optional parameters. They are **not** repeated in every
 
 | Parameter | Type | Default | Notes |
 |---|---|---|---|
-| `project` | string | resolved via fallback | Constrained project env → explicit parameter → `default_project` config |
-| `workspace` | string | — | Cloud workspace name or tenant ID |
-| `output_format` | `"text"` or `"json"` | `"text"` | Machine-readable JSON output. `build_context` defaults to `"json"`; all other tools default to `"text"` |
+| `project` | string | resolved via fallback | Project name. Constrained project env → explicit parameter → `default_project` config |
+| `project_id` | string | — | Project external UUID from `list_memory_projects`. Prefer this when the same project name exists in more than one workspace |
+| `output_format` | `"text"` or `"json"` | `"text"` | Machine-readable JSON output. `build_context` defaults to `"json"`; most other tools default to `"text"` |
+
+`workspace` is not a universal parameter. It appears on the note-writing tools (`write_note`, `edit_note`) and on the tools that create or delete cloud projects. For ordinary read, search, and schema calls, use `project` or `project_id`.
 
 ---
 
@@ -38,11 +40,14 @@ Create or update a markdown note.
 | `directory` | string | Yes | Relative folder path |
 | `tags` | list[string] or string | No | Comma-separated string accepted |
 | `note_type` | string | No | Default `note`. Sets the `type` frontmatter field (e.g., `person`, `meeting`, `decision`) |
-| `metadata` | object | No | Extra frontmatter fields merged into the note's YAML header |
-| `overwrite` | boolean | No | Default `false`. Must be `true` to replace an existing note. Without this, writing to an existing path returns an error. Set `write_note_overwrite_default: true` in config to change the default |
+| `metadata` | object or JSON string | No | Extra frontmatter fields merged into the note's YAML header |
+| `overwrite` | boolean | No | Default follows `write_note_overwrite_default` config (`false` unless changed). Pass `true` to replace an existing note; without it, writing to an existing path returns an error |
+| `workspace` | string | No | Cloud workspace to write into (name or tenant ID) |
 
 The `note_type` parameter controls the `type` field in frontmatter, which is used for schema resolution and filtering. The `metadata` parameter accepts any key-value pairs that get written directly into the note's frontmatter — useful for custom fields like `status`, `priority`, or `due_date`.
 
+Aliases accepted for `directory`: `folder`, `dir`, and `path`.
+
 ### `read_note`
 
 Read note content by title/permalink/memory URL.
@@ -66,6 +71,7 @@ Edit an existing note incrementally.
 | `section` | string | Conditional | Required for `replace_section`, `insert_before_section`, `insert_after_section` |
 | `find_text` | string | Conditional | Required for `find_replace` |
 | `expected_replacements` | integer | No | Default `1` |
+| `workspace` | string | No | Cloud workspace containing the note (name or tenant ID) |
 
 ### `move_note`
 
@@ -89,11 +95,11 @@ Delete a note or directory.
 
 ### `read_content`
 
-Read raw file content by path or permalink. Returns the file's raw bytes — useful for non-markdown files like images, PDFs, or binary attachments.
+Read a file's content by path or permalink. Text files return as plain text; images are resized/optimized for display; other binary files return base64-encoded (subject to size limits). Useful for non-markdown files like images, PDFs, or attachments.
 
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
-| `path` | string | Yes | File path, permalink, or `memory://...` URL |
+| `path` | string | Yes | File path, permalink, or `memory://...` URL. Aliases: `file_path`, `filepath`, `file` |
 
 ### `view_note`
 
@@ -102,8 +108,6 @@ Render a note as a formatted artifact for display in MCP clients. Returns the no
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
 | `identifier` | string | Yes | Note title, permalink, or `memory://...` URL |
-| `page` | integer | No | Pagination page number |
-| `page_size` | integer | No | Results per page |
 
 ---
 
@@ -119,10 +123,11 @@ Main search tool with text, vector, and hybrid modes plus structured filters.
 | `page` | integer | No | Default `1` |
 | `page_size` | integer | No | Default `10` |
 | `search_type` | string | No | Default `None` — resolves to `hybrid` when semantic search is enabled, `text` otherwise. Options: `text`, `title`, `permalink`, `vector`, `semantic`, `hybrid` |
-| `note_types` | list[string] | No | Frontmatter type filter (e.g., `["person", "meeting"]`) |
-| `entity_types` | list[string] | No | Result type filter: `entity`, `observation`, `relation` |
+| `note_types` | list[string] or string | No | Case-insensitive frontmatter `type` filter (e.g., `["person", "meeting"]`). Aliases: `note_type`, `types` |
+| `entity_types` | list[string] or string | No | Knowledge graph result filter: `entity`, `observation`, `relation`. Alias: `entity_type` |
+| `categories` | list[string] or string | No | Exact observation category filter (e.g., `["decision", "rule"]`). When provided without `entity_types`, results default to observations. |
 | `after_date` | string | No | Date/time filter (ISO format) |
-| `metadata_filters` | object | No | Structured metadata filters |
+| `metadata_filters` | object or JSON string | No | Structured metadata filters |
 | `tags` | list[string] | No | Tag filter shorthand |
 | `status` | string | No | Status shorthand |
 | `min_similarity` | float | No | Overrides global `semantic_min_similarity` threshold per query |
@@ -130,8 +135,10 @@ Main search tool with text, vector, and hybrid modes plus structured filters.
 
 The `search_type` parameter controls the search strategy. `hybrid` is the default — it combines keyword and semantic search. `text` is keyword-only. `vector` and `semantic` are equivalent — pure meaning-based similarity. See [Semantic Search](/concepts/semantic-search) for details on each mode.
 
+Use `categories` for observation categories such as `[decision]`, `[rule]`, or `[follow-up]`. `metadata_filters` only checks note frontmatter, so `metadata_filters={"category": "decision"}` matches a frontmatter field named `category`, not observation categories. The singular `category` is accepted as an alias, and comma-separated strings work (`categories="decision,rule"`). Matching is exact, and categories only exist on observations — explicitly passing `entity_types=["entity"]` alongside `categories` returns nothing.
+
 ::note
-**Parameter aliases.** `search_notes` accepts `q`, `search`, or `text` as aliases for `query`, so assistants can use the parameter name they reach for naturally. Search responses also include a result total for pagination.
+**Parameter aliases.** `search_notes` accepts `q`, `search`, or `text` as aliases for `query`; `all_projects` for `search_all_projects`; `page_number` for `page`; and `limit` / `per_page` for `page_size`. Search responses also include a result total for pagination.
 ::
 
 ### `build_context`
@@ -160,7 +167,7 @@ Build context graph from a memory URL. Traverses the knowledge graph from a star
 
 ### `recent_activity`
 
-Recent activity in one project or cross-project discovery mode. When called without a `project` parameter, returns activity across all projects.
+Recent activity in one project or cross-project discovery mode. When no project can be resolved at all (no parameter, no default project), it returns activity across all projects (discovery mode); otherwise it uses the resolved project.
 
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
@@ -176,11 +183,11 @@ Recent activity in one project or cross-project discovery mode. When called with
 
 ### `list_memory_projects`
 
-List projects and project stats. Returns name, path, default status, note count, and last sync time for each project. In cloud mode, this discovers projects across **every** accessible workspace, not just the current one — so a team's projects show up without switching workspaces first.
+List projects and project stats. Returns name, path, default status, note count, external project ID, and sync/workspace metadata for each project. In cloud mode, this discovers projects across **every** accessible workspace, not just the current one — so a team's projects show up without switching workspaces first.
 
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
-| `workspace` | string | No | Limit results to a specific cloud workspace (name or tenant ID) |
+| `output_format` | `"text"` or `"json"` | No | Use `"json"` when an agent needs exact `project_id` values for later tool calls |
 
 ### `create_memory_project`
 
@@ -200,6 +207,7 @@ Remove a project from Basic Memory config.
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
 | `project_name` | string | Yes | Name of the project to remove |
+| `workspace` | string | No | Cloud workspace selector when deleting from a specific workspace |
 
 ### `list_directory`
 
@@ -213,7 +221,7 @@ List directory contents with optional depth and glob filter.
 
 ### `canvas`
 
-Create Obsidian canvas files for visual knowledge graph exploration.
+Create Obsidian canvas files for visual knowledge graph exploration. Local-only — see [Canvas Visualizations](/local/canvas).
 
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
@@ -240,6 +248,7 @@ Validate notes against their schema. Pass `note_type` to validate all notes of a
 |---|---|---|---|
 | `note_type` | string | Conditional | Note type to validate (e.g., `person`). One of `note_type` or `identifier` required |
 | `identifier` | string | Conditional | Specific note path or permalink to validate |
+| `output_format` | `"text"` or `"json"` | No | Machine-readable validation report |
 
 ### `schema_infer`
 
@@ -249,6 +258,7 @@ Analyze existing notes of a type and suggest a schema based on common patterns.
 |---|---|---|---|
 | `note_type` | string | Yes | Note type to analyze (e.g., `person`) |
 | `threshold` | float | No | Minimum field frequency for inclusion (default `0.25`) |
+| `output_format` | `"text"` or `"json"` | No | Machine-readable inference report |
 
 ### `schema_diff`
 
@@ -257,15 +267,14 @@ Compare a schema definition against actual note usage to detect drift.
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
 | `note_type` | string | Yes | Note type to compare (e.g., `person`) |
+| `output_format` | `"text"` or `"json"` | No | Machine-readable drift report |
 
 ---
 
 ## Discovery tools
 
-### Cloud discovery tools
-
-- **`cloud_info()`** — Returns cloud connection information including authentication status, subscription details, and tenant info. No parameters.
-- **`release_notes()`** — Returns the latest Basic Memory release notes and changelog. No parameters.
+- **`cloud_info()`** — Returns an overview of Basic Memory Cloud: features and how to get set up (`bm cloud login`). No parameters.
+- **`release_notes()`** — Returns bundled release-notes highlights for the installed version. No parameters.
 
 ---
 
diff --git a/content/10.reference/3.ai-assistant-guide.md b/content/10.reference/3.ai-assistant-guide.md
new file mode 100644
index 0000000..13e39ef
--- /dev/null
+++ b/content/10.reference/3.ai-assistant-guide.md
@@ -0,0 +1,117 @@
+---
+title: AI Assistant Guide
+description: Teach your AI assistant when and how to use Basic Memory — skills, project instructions, and CLAUDE.md/AGENTS.md.
+---
+
+Connecting Basic Memory over MCP gives your assistant the tools. It doesn't teach it *when* to reach for them. A few standing instructions are the difference between an assistant that occasionally writes a note and one that actually maintains your knowledge base — searching before it answers, capturing decisions as they happen, and linking new notes into the graph.
+
+There are three ways to give those instructions, from least to most effort.
+
+---
+
+## 1. Install Agent Skills (recommended)
+
+[Agent Skills](/integrations/skills) are packaged instructions that teach agents Basic Memory best practices — the note format, when to capture, how to search and resume work, schema workflows, and knowledge-base maintenance. If your client supports skills, this replaces hand-written guidance:
+
+```bash
+npx skills add basicmachines-co/basic-memory/skills
+```
+
+That installs the full set. To start smaller, add just one: `npx skills add basicmachines-co/basic-memory/skills --skill memory-notes` — the core note-writing skill — and add others as you need them.
+
+---
+
+## 2. Add project-level instructions
+
+If you'd rather write your own guidance — or your client doesn't support skills — put it where your assistant reads standing instructions:
+
+- **Claude Projects** — in Claude (web or desktop), open your project's settings and paste your guidance into the **project instructions**. Every conversation in that project starts with it.
+- **Claude Code** — add it to the repo's `CLAUDE.md`. Claude Code loads it automatically in that repository.
+- **Codex and other coding agents** — add it to `AGENTS.md` in the repo root, the convention most coding agents read.
+- **Other clients** — use the custom-instructions or system-prompt field your client provides.
+
+### A starting instruction block
+
+Paste this and adapt it to your workflow:
+
+```markdown
+## Basic Memory
+
+You have persistent memory through Basic Memory's MCP tools.
+
+- Before answering questions about prior work or decisions, search first:
+  `search_notes`, then `build_context` on relevant `memory://` URLs.
+- Capture important decisions, findings, and context as notes with
+  `write_note` during the conversation — don't wait to be asked.
+- Structure notes semantically: observations as `- [category] fact #tag`
+  and relations as `- relates_to [[Other Note]]`. Use exact titles of
+  existing notes in wikilinks so they resolve.
+- Update existing notes with `edit_note` instead of creating duplicates.
+- If the target project is ambiguous, ask once, then stick with it.
+```
+
+::note
+Want more to work from? The [extended AI assistant guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) is a full instruction document you can download and customize, and a [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md) ships as an MCP resource inside Basic Memory itself.
+::
+
+---
+
+## 3. Say it in the conversation
+
+Instructions don't have to be configured up front. Basic Memory is designed so you can direct it naturally as you work:
+
+```text
+"Make sure you add observations and relations to this note."
+"Search my notes before answering — what did we decide about auth?"
+"Record this decision in Basic Memory."
+```
+
+Your assistant can even write a note about *how you like your notes* — and find it again in the next conversation.
+
+::tip
+**Using your tool's built-in memory too?** There's a paste-once routing rule that teaches the agent to treat built-in memory as the short-term cache and Basic Memory as the long-term store — see [Using Basic Memory with Built-in AI Memory](/concepts/vs-built-in-memory).
+::
+
+---
+
+## What good usage looks like
+
+- **Search before answering.** Questions like "what did we decide about X?" should trigger `search_notes`, not a guess from the conversation so far.
+- **Capture as you go.** Decisions, requirements, and findings get recorded when they happen, structured with observations and relations.
+- **Build context on follow-ups.** `build_context` with a `memory://` URL pulls in a note *and* its connected notes, so continuation conversations start warm.
+- **Edit, don't duplicate.** Existing notes grow with `edit_note`; new notes link back to what they extend.
+
+For the full tool surface — parameters, aliases, defaults — see the [MCP Tools Reference](/reference/mcp-tools-reference).
+
+---
+
+## Related
+
+:::card-group
+::card
+---
+title: Agent Skills
+icon: i-lucide-sparkles
+to: /integrations/skills
+---
+Packaged instructions that teach agents Basic Memory best practices.
+::
+
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+Complete tool documentation with parameters and examples.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+The note structure your assistant should write.
+::
+:::
diff --git a/content/9.reference/4.technical-information.md b/content/10.reference/4.technical-information.md
similarity index 86%
rename from content/9.reference/4.technical-information.md
rename to content/10.reference/4.technical-information.md
index ce9aab9..b146c28 100644
--- a/content/9.reference/4.technical-information.md
+++ b/content/10.reference/4.technical-information.md
@@ -23,7 +23,7 @@ Basic Memory consists of:
 
 ## Model Context Protocol (MCP)
 
-Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), an open standard for enabling AI models to access external tools:
+Basic Memory implements the [Model Context Protocol](https://modelcontextprotocol.io), an open standard for enabling AI models to access external tools:
 
 - **Standardized Interface** — Common protocol for tool integration
 - **Tool Registration** — Basic Memory registers as a tool provider
@@ -80,13 +80,16 @@ Categorized facts and information about entities
 ### Relations
 Connections between entities that form the knowledge graph
 
+### Tags
+Additional categorization for entities and observations
+
 ::
 
-This structure emerges from simple text patterns in standard Markdown:
+This structure emerges from simple text patterns in standard Markdown. The example below is saved as `Coffee Notes/Coffee Brewing Methods.md` — its frontmatter sets an explicit `permalink`, which overrides the path-derived one:
 
 ### Example Markdown Input
 
-```bash
+```markdown
 ---
 title: Coffee Brewing Methods
 type: note
@@ -125,8 +128,6 @@ resulting in unique flavor profiles, body, and mouthfeel. The key variables in a
 - affects [[Flavor Extraction]]
 ```
 
-### Parsed JSON Structure
-
 ### Resulting JSON Entity Structure
 ```json
 {
@@ -140,7 +141,7 @@ resulting in unique flavor profiles, body, and mouthfeel. The key variables in a
         "title": "Coffee Brewing Methods",
         "type": "note",
         "permalink": "coffee/coffee-brewing-methods",
-        "tags": "['#coffee', '#brewing', '#methods', '#demo']"
+        "tags": ["#coffee", "#brewing", "#methods", "#demo"]
       },
       "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c",
       "content_type": "text/markdown",
@@ -164,22 +165,22 @@ resulting in unique flavor profiles, body, and mouthfeel. The key variables in a
       ],
       "relations": [
         {
-          "from_id": "coffee/coffee-bean-origins",
-          "to_id": "coffee/coffee-brewing-methods",
-          "relation_type": "pairs_with",
-          "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods",
-          "to_name": "Coffee Brewing Methods"
+          "from_id": "coffee/coffee-brewing-methods",
+          "to_id": "coffee/proper-grinding-technique",
+          "relation_type": "requires",
+          "permalink": "coffee/coffee-brewing-methods/requires/coffee/proper-grinding-technique",
+          "to_name": "Proper Grinding Technique"
         },
         {
-          "from_id": "coffee/flavor-extraction",
-          "to_id": "coffee/coffee-brewing-methods",
-          "relation_type": "affected_by",
-          "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods",
-          "to_name": "Coffee Brewing Methods"
+          "from_id": "coffee/coffee-brewing-methods",
+          "to_id": "coffee/flavor-extraction",
+          "relation_type": "affects",
+          "permalink": "coffee/coffee-brewing-methods/affects/coffee/flavor-extraction",
+          "to_name": "Flavor Extraction"
         }
       ],
-      "created_at": "2025-03-06T14:01:23.445071",
-      "updated_at": "2025-03-06T13:34:48.563606"
+      "created_at": "2025-03-06T13:34:48.563606",
+      "updated_at": "2025-03-06T14:01:23.445071"
     }
   ]
 }
@@ -187,17 +188,6 @@ resulting in unique flavor profiles, body, and mouthfeel. The key variables in a
 
 Basic Memory understands how to build context via its semantic graph.
 
-### Entity Model
-
-Basic Memory's core data model consists of:
-
-- **Entities** — Documents in your knowledge base
-- **Observations** — Facts or statements about entities
-- **Relations** — Connections between entities
-- **Tags** — Additional categorization for entities and observations
-
-The system parses Markdown files to extract this structured information while preserving the human-readable format.
-
 ### Files as Source of Truth
 
 Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git.
@@ -300,7 +290,7 @@ The Basic Memory system is built with a modular architecture:
   ::div{label="Interface Layer"}
   **MCP Server** — AI integration layer
 
-  - **Standardized Tools** — 17 MCP tools for AI access
+  - **Standardized Tools** — a comprehensive set of MCP tools for AI access
   - **Real-Time Access** — Live knowledge base queries
   - **Secure Auth** — JWT-based authentication for cloud
   - **Cross-Platform** — Works with Claude, VS Code, Cursor
@@ -325,3 +315,27 @@ Basic Memory embodies several key principles:
   - **AI-Native**: Designed specifically for AI collaboration
   - **Privacy-Preserving**: No data collection or tracking
 ::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+The markdown patterns behind the entity model.
+::
+
+::card
+---
+title: Configuration
+icon: i-lucide-settings
+to: /reference/configuration
+---
+Every config field and environment variable.
+::
+:::
diff --git a/content/9.reference/5.troubleshooting.md b/content/10.reference/5.troubleshooting.md
similarity index 80%
rename from content/9.reference/5.troubleshooting.md
rename to content/10.reference/5.troubleshooting.md
index 1c25a55..f93b4d6 100644
--- a/content/9.reference/5.troubleshooting.md
+++ b/content/10.reference/5.troubleshooting.md
@@ -63,7 +63,7 @@ This guide covers common issues and their solutions. For live help, visit our [D
    bm cloud login
    ```
 
-3. **Check subscription status**:
+3. **Check authentication and connection status**:
    ```bash
    bm cloud status
    ```
@@ -89,7 +89,7 @@ bm cloud login
 **Problem:** "Active subscription required" message.
 
 **Solution:**
-1. Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe)
+1. Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe?utm_source=docs&utm_medium=docs&utm_campaign=troubleshooting)
 2. Complete subscription
 3. Run `bm cloud login` again
 
@@ -124,56 +124,21 @@ bm cloud login
 
 3. **Check .gitignore patterns** - Files matching ignore patterns are skipped
 
-4. **Reset the database**:
+4. **Rebuild the index** (or reset if issues persist):
    ```bash
-   basic-memory reset
+   basic-memory reindex
+   # heavier: drop and rebuild the database
+   basic-memory reset --reindex
    ```
    ::warning
-   This re-indexes all files. May take time for large knowledge bases.
+   Plain `basic-memory reset` only deletes the index — pass `--reindex` to rebuild it from your files. May take time for large knowledge bases.
    ::
 
-### Sync In Progress
-
-**Problem:** Operations failing with "sync in progress" message.
-
-**Solution:** Wait for sync to complete, then retry. Check progress with:
-```bash
-basic-memory status
-```
-
 ### Cloud Sync Issues
 
-**Problem:** Bisync not working.
-
-**Solutions:**
-
-1. **Re-run setup**:
-   ```bash
-   bm cloud setup
-   ```
-
-2. **First bisync requires --resync**:
-   ```bash
-   bm cloud bisync --name research --resync
-   ```
+**Problem:** Push or pull not working — setup errors, conflicts, or "no local sync path configured".
 
-3. **Empty directory error** - Add at least one file:
-   ```bash
-   echo "# Notes" > ~/Documents/research/README.md
-   bm cloud bisync --name research --resync
-   ```
-
-4. **Bisync state corruption** - Reset state:
-   ```bash
-   bm cloud bisync-reset research
-   bm cloud bisync --name research --resync
-   ```
-
-5. **Too many deletes error** - Review changes, then force:
-   ```bash
-   bm cloud bisync --name research --dry-run
-   bm cloud bisync --name research --resync
-   ```
+The [Cloud Sync Guide's troubleshooting section](/cloud/cloud-sync#troubleshooting) owns the fixes: re-running setup, previewing transfers with `--dry-run`, resolving conflicts with `--on-conflict`, and configuring sync paths.
 
 ---
 
@@ -204,9 +169,9 @@ basic-memory status
    memory://my-note-title
    ```
 
-4. **Trigger a re-sync**:
+4. **Rebuild the search index**:
    ```bash
-   basic-memory sync
+   basic-memory reindex
    ```
 
 ### Entity Not Found
@@ -215,8 +180,8 @@ basic-memory status
 
 **Solutions:**
 
-1. **Search for the note**:
-   ```
+1. **Search for the note** — ask your AI assistant:
+   ```text
    Find notes about [topic]
    ```
 
@@ -237,9 +202,9 @@ basic-memory status
 
 **Solutions:**
 
-1. **Check database size**:
+1. **Check knowledge base statistics**:
    ```bash
-   basic-memory project info
+   basic-memory project info main
    ```
 
 2. **Archive old content** - Move inactive notes to archive folder
@@ -276,9 +241,9 @@ basic-memory status
 
 ### Python Version Error
 
-**Problem:** "Python 3.13+ required" error.
+**Problem:** Unsupported Python version error.
 
-**Solution:** Install Python 3.13 or higher:
+**Solution:** Install Python 3.12 or higher:
 ```bash
 # macOS with Homebrew
 brew install python@3.13
@@ -346,7 +311,7 @@ source ~/.bashrc  # or ~/.zshrc
 **Solution:**
 ```bash
 bm cloud sync-setup research ~/Documents/research
-bm cloud bisync --name research --resync
+bm cloud pull --name research
 ```
 
 ### Moving Notes Between Projects
@@ -397,11 +362,11 @@ Common issues:
    pkill -f "basic-memory"
    ```
 
-3. **Remove lock files** (if they exist):
+3. **Clean up SQLite WAL/shared-memory files** — after closing all clients, the supported path is:
    ```bash
-   rm ~/.basic-memory/memory.db-shm
-   rm ~/.basic-memory/memory.db-wal
+   basic-memory reset --reindex
    ```
+   (It removes `memory.db-shm`/`memory.db-wal` itself — deleting the `-wal` file by hand can silently discard recently indexed changes.)
 
 ### Corrupted Database
 
@@ -409,11 +374,11 @@ Common issues:
 
 **Solution:** Reset and re-index:
 ```bash
-basic-memory reset
+basic-memory reset --reindex
 ```
 
 ::warning
-This rebuilds the database from your markdown files. All files are preserved.
+With `--reindex`, the index is rebuilt from your markdown files. All files are preserved.
 ::
 
 ---
@@ -423,11 +388,11 @@ This rebuilds the database from your markdown files. All files are preserved.
 ### Check Logs
 
 ```bash
-# View log files
-cat ~/.basic-memory/basic-memory-*.log
+# View the log file (Windows uses per-process basic-memory-<pid>.log names)
+cat ~/.basic-memory/basic-memory.log
 
-# Or for Cloud mode
-cat ~/.basic-memory/basic-memory-cloud.json
+# For cloud connection diagnostics
+bm cloud status
 ```
 
 ### Command Help
@@ -437,7 +402,7 @@ cat ~/.basic-memory/basic-memory-cloud.json
 basic-memory --help
 
 # Get help for specific commands
-basic-memory sync --help
+basic-memory status --help
 basic-memory project --help
 bm cloud --help
 ```
@@ -456,7 +421,7 @@ bm cloud --help
 ---
 title: Getting Started
 icon: i-lucide-rocket
-to: /start-here/getting-started
+to: /local/getting-started
 ---
 Installation guide and initial setup.
 ::
diff --git a/content/9.reference/6.configuration.md b/content/10.reference/6.configuration.md
similarity index 85%
rename from content/9.reference/6.configuration.md
rename to content/10.reference/6.configuration.md
index eca9731..682b2df 100644
--- a/content/9.reference/6.configuration.md
+++ b/content/10.reference/6.configuration.md
@@ -31,7 +31,7 @@ When set, Basic Memory stores config and default app DB in that directory.
 
 ---
 
-## Example config (v0.19+)
+## Example config
 
 ```json
 {
@@ -44,15 +44,13 @@ When set, Basic Memory stores config and default app DB in that directory.
     "research": {
       "path": "/Users/you/research-notes",
       "mode": "cloud",
-      "cloud_sync_path": "/Users/you/research-notes",
-      "bisync_initialized": true,
+      "local_sync_path": "/Users/you/research-notes",
       "last_sync": "2026-02-15T18:30:00Z"
     }
   },
   "semantic_search_enabled": true,
   "semantic_min_similarity": 0.55,
-  "permalinks_include_project": true,
-  "cloud_mode": false
+  "permalinks_include_project": true
 }
 ```
 
@@ -68,8 +66,7 @@ Each project entry supports:
 
 - `path`: local filesystem path
 - `mode`: `local` or `cloud`
-- `cloud_sync_path` (optional)
-- `bisync_initialized` (optional)
+- `local_sync_path` (optional; legacy `cloud_sync_path` keys are accepted and migrated on load)
 - `last_sync` (optional)
 
 ### `default_project`
@@ -77,7 +74,7 @@ Each project entry supports:
 Fallback project name used when tools/commands do not pass a project.
 
 - Type: `string | null`
-- Default: `"main"`
+- Default: unset — the first configured project is used (`"main"` on fresh installs, where a `main` project is seeded). Setting it explicitly to `null` disables automatic project resolution.
 
 ::note
 `default_project_mode` is deprecated/removed from active config behavior. Use `default_project` as fallback instead.
@@ -145,7 +142,7 @@ Embedding dimensions override.
 Embedding batch size.
 
 - Type: integer
-- Default: `64`
+- Default: `2`
 - Env: `BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE`
 
 ### `semantic_vector_k`
@@ -260,7 +257,7 @@ Maximum number of files to process concurrently during sync operations.
 
 ### `skip_initialization_sync`
 
-Skip the initial full sync when the MCP server starts. Useful for large projects where you want the server to start faster and rely on the file watcher for incremental updates.
+Skip local initialization — database setup and project reconciliation/seeding — for cloud/stateless deployments where projects are managed in the database. Not a local performance knob; it does not gate the initial file scan.
 
 - Type: boolean
 - Default: `false`
@@ -309,7 +306,7 @@ Timestamp of the last automatic update check. Managed automatically — you don'
 
 ### `format_on_save`
 
-Automatically format notes when they are saved via `write_note` or `edit_note`.
+Automatically format notes when they are saved via `write_note` or `edit_note`. With no `formatter_command` configured, markdown is formatted by the built-in mdformat; setting a command (or the per-extension `formatters` map) overrides it with an external tool.
 
 - Type: boolean
 - Default: `false`
@@ -317,7 +314,7 @@ Automatically format notes when they are saved via `write_note` or `edit_note`.
 
 ### `formatter_command`
 
-External command to use for formatting markdown files. When set and `format_on_save` is enabled, this command is called with the file path as an argument.
+External command to use for formatting markdown files. The file path is substituted via a `{file}` placeholder — for example `npx prettier --write {file}`. A per-extension `formatters` map is also available for different tools per file type.
 
 - Type: string | null
 - Default: `null`
@@ -354,7 +351,7 @@ Connection URL for the database when using the Postgres backend.
 - Default: `null`
 - Env: `BASIC_MEMORY_DATABASE_URL`
 
-Only required when `database_backend` is `postgres`. Example: `postgresql://user:pass@host:5432/dbname`
+Only required when `database_backend` is `postgres`. Example: `postgresql+asyncpg://user:pass@host:5432/dbname`
 
 ---
 
@@ -362,12 +359,13 @@ Only required when `database_backend` is `postgres`. Example: `postgresql://user
 
 ### `cloud_mode`
 
-Global cloud mode toggle.
+Cloud deployment mode (derived, not a config-file setting).
 
-- Type: boolean
-- Default: `false`
+- Type: boolean (read-only property)
 - Env: `BASIC_MEMORY_CLOUD_MODE`
 
+Set by managed cloud deployments via the environment variable. A `cloud_mode` key in `config.json` is ignored and removed on load — don't set it for local installs.
+
 ### `cloud_api_key`
 
 Account-level cloud API key (`bmc_...`) used for cloud-routed projects.
diff --git a/content/10.reference/7.docker.md b/content/10.reference/7.docker.md
new file mode 100644
index 0000000..0a8938b
--- /dev/null
+++ b/content/10.reference/7.docker.md
@@ -0,0 +1,245 @@
+---
+title: Docker
+description: Run Basic Memory in a container for server deployments, CI, and controlled self-hosted MCP experiments.
+---
+
+::warning
+Docker is an advanced deployment path. For most local desktop and coding tools, install Basic Memory with `uv tool install basic-memory` or Homebrew and let the tool launch `uvx basic-memory mcp`.
+::
+
+## What Docker is for
+
+The official Docker image runs the Basic Memory MCP server in a container. It is useful when you want:
+
+- A repeatable server deployment
+- Docker Compose or Kubernetes orchestration
+- A shared test environment
+- CI jobs that need Basic Memory available over HTTP
+- A controlled self-hosted MCP experiment
+
+It is **not** the recommended path for day-one local use. Local MCP clients usually expect a stdio process they can launch themselves. See [Local Install](/local/local-install) for that setup.
+
+## Image
+
+The image is published to GitHub Container Registry:
+
+```bash
+docker pull ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+The image is built from the [Basic Memory repository](https://github.com/basicmachines-co/basic-memory) and runs as a non-root user.
+
+## Run a container
+
+Mount a local knowledge folder and expose the MCP server:
+
+```bash
+docker run -d \
+  --name basic-memory-server \
+  -p 8000:8000 \
+  -v "$PWD/knowledge:/app/data" \
+  -v basic-memory-config:/home/appuser/.basic-memory \
+  ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+The server listens on port `8000`.
+
+::caution
+The container's SSE and HTTP endpoints are not secured by Basic Memory. Do not expose them directly to the public internet. Put authentication, TLS, and network access controls in front of any remote deployment.
+::
+
+## Docker Compose
+
+Use Compose when you want persistent configuration and a repeatable project mount:
+
+```yaml
+services:
+  basic-memory:
+    image: ghcr.io/basicmachines-co/basic-memory:latest
+    container_name: basic-memory-server
+    ports:
+      - "8000:8000"
+    volumes:
+      - basic-memory-config:/home/appuser/.basic-memory:rw
+      - ./knowledge:/app/data:rw
+    environment:
+      - BASIC_MEMORY_DEFAULT_PROJECT=main
+      - BASIC_MEMORY_SYNC_CHANGES=true
+      - BASIC_MEMORY_LOG_LEVEL=INFO
+      - BASIC_MEMORY_SYNC_DELAY=1000
+    command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "basic-memory", "--version"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+volumes:
+  basic-memory-config:
+```
+
+Start it:
+
+```bash
+docker compose up -d
+```
+
+Check logs:
+
+```bash
+docker logs basic-memory-server
+```
+
+## Configuration
+
+Configuration comes from these environment variables — the image itself sets `BASIC_MEMORY_HOME` and `BASIC_MEMORY_PROJECT_ROOT`; the rest are set by the Compose example (shown with their application defaults):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Basic Memory home inside the container |
+| `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for mounted projects |
+| `BASIC_MEMORY_DEFAULT_PROJECT` | `main` in the Compose example | Default project name |
+| `BASIC_MEMORY_SYNC_CHANGES` | `true` in the Compose example | Enable file-change sync behavior |
+| `BASIC_MEMORY_LOG_LEVEL` | `INFO` in the Compose example | Log verbosity |
+| `BASIC_MEMORY_SYNC_DELAY` | `1000` in the Compose example | File sync delay in milliseconds |
+
+Mount two kinds of storage:
+
+- **Knowledge files:** mount your Markdown/project directory at `/app/data`.
+- **Configuration and local index:** mount `/home/appuser/.basic-memory` to a named volume so configuration and database state survive container restarts.
+
+## Connect a client
+
+The Docker image starts Basic Memory with SSE transport by default:
+
+```bash
+basic-memory mcp --transport sse --host 0.0.0.0 --port 8000
+```
+
+Use Docker only with clients or gateways that can reach an HTTP/SSE MCP server. If your client expects local stdio config, use the local install path instead:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": ["basic-memory", "mcp"]
+    }
+  }
+}
+```
+
+## Run CLI commands inside the container
+
+You can inspect the container with normal Basic Memory commands:
+
+```bash
+docker exec basic-memory-server basic-memory --version
+docker exec basic-memory-server bm status
+docker exec basic-memory-server bm project list
+```
+
+Use `docker exec` for diagnostics and scripted maintenance. For everyday local work, use the installed CLI on your host machine.
+
+## PostgreSQL backend
+
+Basic Memory supports **PostgreSQL with `pgvector`** as a database backend — it's the same configuration Basic Memory Cloud runs on. Point your container at a Postgres instance with two environment variables:
+
+```bash
+BASIC_MEMORY_DATABASE_BACKEND=postgres
+BASIC_MEMORY_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname
+```
+
+Connection pooling is tuned via `db_pool_size`, `db_pool_overflow`, and `db_pool_recycle` — see [Configuration](/reference/configuration#database-settings). SQLite remains the default and needs no setup.
+
+## Troubleshooting
+
+### Port 8000 is already in use
+
+Map a different host port:
+
+```bash
+docker run -d \
+  -p 3000:8000 \
+  -v "$PWD/knowledge:/app/data" \
+  -v basic-memory-config:/home/appuser/.basic-memory \
+  ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+The container still listens on `8000`; the host listens on `3000`.
+
+### Permission denied on mounted files
+
+The container runs as a non-root user. If it cannot read or write your mounted directory, fix ownership or run with a matching user:
+
+```bash
+sudo chown -R 1000:1000 ./knowledge
+```
+
+or:
+
+```bash
+docker run --user "$(id -u):$(id -g)" ...
+```
+
+### The client cannot connect
+
+Check three things:
+
+1. The container is running: `docker ps`
+2. The server logs are clean: `docker logs basic-memory-server`
+3. Your client supports the transport you configured
+
+If the client only supports local stdio MCP, Docker is the wrong connection path. Use [Local MCP tools](/local/mcp-tools-local) instead.
+
+## Build from source
+
+Clone the Basic Memory source repository and build the image locally:
+
+```bash
+git clone https://github.com/basicmachines-co/basic-memory.git
+cd basic-memory
+docker build -t basic-memory:local .
+```
+
+You can pass custom UID/GID build arguments if your deployment needs specific file ownership:
+
+```bash
+docker build \
+  --build-arg UID=1001 \
+  --build-arg GID=1001 \
+  -t basic-memory:custom .
+```
+
+## See also
+
+::card-group
+  ::card
+  ---
+  title: Local Install
+  icon: i-lucide-terminal
+  to: /local/local-install
+  ---
+  Install Basic Memory for local desktop and coding tools.
+  ::
+
+  ::card
+  ---
+  title: CLI Reference
+  icon: i-lucide-square-terminal
+  to: /reference/cli-reference
+  ---
+  Look up Basic Memory commands and flags.
+  ::
+
+  ::card
+  ---
+  title: Troubleshooting
+  icon: i-lucide-life-buoy
+  to: /reference/troubleshooting
+  ---
+  Diagnose install, MCP, sync, and routing problems.
+  ::
+::
diff --git a/content/9.reference/8.llms-txt.md b/content/10.reference/8.llms-txt.md
similarity index 91%
rename from content/9.reference/8.llms-txt.md
rename to content/10.reference/8.llms-txt.md
index ef07f1e..7f34e78 100644
--- a/content/9.reference/8.llms-txt.md
+++ b/content/10.reference/8.llms-txt.md
@@ -8,7 +8,7 @@ This documentation is optimized for AI agents. Get clean markdown through multip
 ::tip
 **Want your AI to read the docs?** Just ask it to fetch the documentation:
 
-```bash
+```text
 Fetch https://docs.basicmemory.com/llms.txt and read the Basic Memory documentation
 ```
 
@@ -158,3 +158,27 @@ const markdown = await response.text();
 - **Structured discovery** - llms.txt provides an index
 - **Standard patterns** - Uses [llms.txt specification](https://llmstxt.org/)
 - **Content negotiation** - Same URLs work for humans and AI
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+The tools your AI uses once it's read the docs.
+::
+
+::card
+---
+title: What is Basic Memory
+icon: i-lucide-lightbulb
+to: /start-here/what-is-basic-memory
+---
+The overview, human-readable edition.
+::
+:::
diff --git a/content/2.whats-new/0.teams.md b/content/2.whats-new/0.teams.md
deleted file mode 100644
index 3909315..0000000
--- a/content/2.whats-new/0.teams.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Basic Memory Teams
-description: Share a cloud workspace with your team — invite members, assign roles, and build one knowledge base together.
----
-
-**Basic Memory Teams** brings your whole team into one shared knowledge base. Invite teammates into a shared cloud workspace, work from the same projects, and your AI assistant reaches those shared projects automatically.
-
-Teams adds a **team workspace alongside your personal one** — your own notes and projects stay where they are, and you switch between workspaces in the app whenever you want.
-
-::note{icon="i-lucide-users"}
-Teams is a cloud feature and requires a subscription with one or more seats. Billing is per seat. Your personal cloud workspace (and any local projects) keep working alongside it.
-::
-
-## What you get
-
-- **Three workspaces, side by side** — local, personal cloud, and your team's shared workspace. Switch between them in the app, or target one explicitly from the CLI and MCP.
-- **A shared workspace for the team** — projects everyone on the team can read and write.
-- **Roles** — assign **owner**, **editor**, or **viewer** to control what each member can do.
-- **Email invitations** — invite teammates by email; a seat is only used once they accept.
-- **One source of truth for your AI** — your assistant discovers team projects across every workspace you can access, with no extra setup.
-
-## Invite your team
-
-Owners invite members from **Settings → Teams**. Each member signs in with the invited email, picks up their role, and starts working in the shared projects right away. Promote, demote, deactivate, or hand off ownership at any time.
-
-## Get started
-
-:::card-group
-::card
----
-title: Teams Guide
-icon: i-lucide-users
-to: /teams/about
----
-Roles, invitations, seats, and project sharing — the full walkthrough.
-::
-
-::card
----
-title: Web App
-icon: i-lucide-layout-panel-left
-to: /cloud/web-app
----
-Browse, edit, and collaborate on notes in the browser.
-::
-
-::card
----
-title: What's New in v0.22.0
-icon: i-lucide-megaphone
-to: /whats-new/v0.22.0
----
-Team-safe cloud push and pull.
-::
-:::
diff --git a/content/2.whats-new/1.v0.22.0.md b/content/2.whats-new/1.v0.22.0.md
deleted file mode 100644
index a9e51a6..0000000
--- a/content/2.whats-new/1.v0.22.0.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: v0.22.0
-description: Team-safe cloud push and pull, search improvements, and a large batch of MCP tool and embedding reliability fixes in Basic Memory v0.22.0.
----
-
-v0.22.0 makes cloud sync safe for teams. New **`bm cloud push`** and **`bm cloud pull`** commands transfer changes additively — they never delete files on the destination — so you can collaborate on a shared Team workspace without risking a teammate's work. The release also brings search improvements, more capable `bm tool` and `bm status` commands, and a long list of MCP tool and embedding reliability fixes.
-
----
-
-## v0.22.1 patch
-
-A follow-up patch to v0.22.0 focused on first-run reliability:
-
-- **Fresh installs no longer get stuck** when the projects table is empty — Basic Memory now routes you to project setup and promotes your first project to the default automatically.
-- **Sync skips projects without a valid local path** and ignores stale projects left in the database but missing from your config.
-- **MCP qualified project routes** resolve workspace display names and tenant ids correctly.
-- **`search_notes`** comma-splits `note_types`, `entity_types`, and `categories`, matching how tags already behave.
-- **`write_note`** gains a `workspace` parameter for parity with `edit_note`.
-- **Faster CLI startup** — heavy imports are deferred out of the command path.
-
-Full details in the [changelog](/whats-new/changelog).
-
----
-
-## Team-Safe Push and Pull
-
-`push` and `pull` model `git push` / `git pull`: additive, conflict-aware transfers that work on both Personal and Team workspaces.
-
-```bash
-# Fetch cloud changes into your local directory
-bm cloud pull --name research
-
-# Upload your local changes to the cloud
-bm cloud push --name research
-
-# Preview either direction first
-bm cloud pull --name research --dry-run
-```
-
-If a file differs on both sides, the command aborts and lists the conflicts — like a rejected `git push`. Re-run with `--on-conflict` to choose what survives:
-
-| Value | Behavior |
-|-------|----------|
-| `fail` (default) | Abort and list conflicting files |
-| `keep-cloud` | Take the cloud version |
-| `keep-local` | Keep the local version |
-| `keep-both` | Keep both, renaming one copy |
-
-Each Team workspace gets its own scoped rclone remote, so credentials and sync state stay isolated per workspace.
-
-### Mirror commands are now Personal-only
-
-`bm cloud sync` and `bm cloud bisync` are mirror operations — one side becomes authoritative and missing files get deleted on the other. That's correct for a Personal workspace with a single writer, but unsafe on a shared Team bucket. On Team workspaces these commands now exit early with a clear error and point you at `push`/`pull` instead.
-
-See the [Cloud Sync guide](/cloud/cloud-sync) for details.
-
----
-
-## Search Improvements
-
-- **Observation category filter** — narrow search results to specific observation categories like `[decision]` or `[fact]`.
-- **Comma-separated tags just work** — `tags="alpha,beta"` and the `tag:alpha,beta` shorthand now split and match consistently everywhere.
-- **`note_types` filter is case-insensitive**, so `Task` and `task` find the same notes.
-
----
-
-## CLI Improvements
-
-- **`bm status --wait --timeout 60`** — block until sync completes, handy for scripting.
-- **`bm tool write-note --type`** — set the note type at creation time.
-- **`bm tool delete-note`** — delete notes from the command line.
-- **`bm tool` commands align with MCP behavior** — consistent error exit codes, overwrite handling, and defaults across the CLI wrappers and the MCP tools they mirror.
-
----
-
-## Experimental: LiteLLM Embeddings
-
-Semantic search can now use a [LiteLLM](https://github.com/BerriAI/litellm)-backed embedding provider, opening the door to hosted embedding models beyond the built-in FastEmbed. This is experimental — expect the configuration surface to evolve.
-
-Embedding reliability also improved across the board: FastEmbed vectors are L2-normalized for correct similarity scoring with custom models, corrupt model caches self-heal, and a single embedding provider is reused per process.
-
----
-
-## Reliability Fixes
-
-A large round of MCP tool fixes:
-
-- `build_context` resolves observations by the same permalink the search index uses, and truncated observation permalinks no longer collide.
-- `edit_note` recovers when a file exists on disk but isn't indexed yet.
-- `move_note` resolves `memory://` URLs, no longer falsely rejects same-project moves, and no longer reports false success across project boundaries.
-- `read_note` accepts `page`/`page_size` like its sibling tools.
-- `recent_activity` shows the correct project, and navigation pagination is validated.
-- `bm cloud setup` no longer overwrites an existing rclone remote.
-
----
-
-## Upgrading
-
-No breaking changes. Upgrade as usual:
-
-```bash
-uv tool upgrade basic-memory
-# or
-brew upgrade basic-memory
-```
-
-Full details in the [changelog](/whats-new/changelog).
diff --git a/content/2.whats-new/5.changelog.md b/content/2.whats-new/5.changelog.md
deleted file mode 100644
index 25182ba..0000000
--- a/content/2.whats-new/5.changelog.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Basic Memory
-description: Release notes for Basic Memory.
----
-
-All notable changes to [Basic Memory](https://github.com/basicmachines-co/basic-memory).
-
-::github-releases
----
-repo: basicmachines-co/basic-memory
-limit: 30
----
-::
diff --git a/content/3.cloud/02.web-app.md b/content/3.cloud/02.web-app.md
deleted file mode 100644
index f3e07e3..0000000
--- a/content/3.cloud/02.web-app.md
+++ /dev/null
@@ -1,376 +0,0 @@
----
-title: Web App
-description: Complete guide to the Basic Memory Cloud web app - browse, edit, search, and collaborate on your notes in the browser.
----
-
-The Basic Memory web app at [app.basicmemory.com](https://app.basicmemory.com) is a full-featured interface for working with your knowledge base. Notes open ready to edit, your AI assistant can join you live, and everything is saved as plain Markdown. Anything your AI assistant can do, you can do here too.
-
-::theme-image{light="/screenshots/cloud-app/v2-overview-light.png" dark="/screenshots/cloud-app/v2-overview-dark.png" alt="Web App Overview"}
-::
-
----
-
-## Layout
-
-The app is organized into three panes:
-
-| Pane | Contents |
-|------|----------|
-| **Sidebar** | Project and folder tree, search, your account avatar |
-| **Note list** | Notes in the current folder or project, grouped by date |
-| **Note detail** | The selected note, opened ready to edit |
-
-Click a folder in the sidebar to filter the note list. Select a note to open it in the detail pane.
-
----
-
-## Navigating notes
-
-### Browse by folder
-
-Expand folders in the sidebar to navigate your project structure. Click a folder to filter the note list to that location.
-
-### Filter with tabs
-
-Switch between views above the note list:
-
-| Tab | Shows |
-|-----|-------|
-| **All** | Every note in the current folder/project |
-| **Pinned** | Notes you've pinned for quick access |
-
-### Search notes
-
-Use the search field in the sidebar to filter by title or content. Search is instant and scoped to the current project.
-
-::theme-image{light="/screenshots/cloud-app/v2-search-light.png" dark="/screenshots/cloud-app/v2-search-dark.png" alt="Search notes"}
-::
-
-### Pin important notes
-
-Open a note's `⋮` menu (or use the command palette) and choose **Pin Note**. Pinned notes appear in the Pinned tab.
-
----
-
-## Editing notes
-
-Notes open ready to edit. The app has three modes, switchable from the toolbar or with keyboard shortcuts:
-
-| Mode | Shortcut | Description |
-|------|----------|-------------|
-| **Rich editor** | Cmd/Ctrl + Shift + I | WYSIWYG editing — type and format directly, with tables, code blocks, callouts, and task lists |
-| **Source mode** | Cmd/Ctrl + Shift + R | Plain Markdown editing with full frontmatter visible — for power users |
-| **Preview** | Cmd/Ctrl + Shift + P | Read-only rendered view with clickable `[[wiki links]]` for navigating your knowledge graph |
-
-::theme-image{light="/screenshots/cloud-app/v2-edit-mode-light.png" dark="/screenshots/cloud-app/v2-edit-mode-dark.png" alt="Rich editor mode"}
-::
-
-And here's the same note in **Preview** mode, with clickable wiki links:
-
-::theme-image{light="/screenshots/cloud-app/v2-edit-preview-light.png" dark="/screenshots/cloud-app/v2-edit-preview-dark.png" alt="Preview mode"}
-::
-
-::tip
-Press **Cmd/Ctrl + Option + Z** to toggle Zen mode — a distraction-free full-screen editor. Press **Escape** to drop back to Preview from the editor.
-::
-
-### Markdown formatting
-
-The rich editor supports full Markdown including:
-- Headers, bold, italic, inline code
-- Code blocks with syntax highlighting
-- Tables
-- Links and images
-- Task lists (`- [ ]` and `- [x]`)
-- Basic Memory semantic syntax (observations, relations)
-
-Press **Cmd/Ctrl + /** to see all formatting shortcuts.
-
-### Edit frontmatter
-
-Open the **Frontmatter** panel from the toolbar (or the command palette) to edit a note's YAML metadata separately from its content.
-
-::theme-image{light="/screenshots/cloud-app/v2-frontmatter-light.png" dark="/screenshots/cloud-app/v2-frontmatter-dark.png" alt="Edit Frontmatter"}
-::
-
----
-
-## Drafts
-
-Start typing in an empty editor — or press **Cmd/Ctrl + N** for a new note — to create a **draft**. Drafts let you write before committing a file to a project.
-
-- A draft shows a status dot until it's saved.
-- Click **Save Draft** (or use the command palette) to write it into the current project as a Markdown file.
-- Once saved, the note syncs like any other and is available to your AI assistant.
-
-::note
-Saved notes are written automatically as you edit. Status dots tell you the state: unsaved, saving, or draft — no dot means saved.
-::
-
----
-
-## Working with your AI assistant
-
-The web app treats your AI assistant as a real collaborator — you can watch it write, and steer it, in the same note you're editing.
-
-### Connect an agent
-
-Click **Connect Agent** in the editor to start or resume an agent session for the workspace. When an agent is connected, the button shows its live status (for example, "Claude live").
-
-### Improve a selection
-
-Select text in the editor and choose **Improve** to ask the agent to rewrite, summarize, or extend it. The agent's changes stream into the note as it works — connecting automatically if no agent is attached yet.
-
-### The agent pane
-
-The agent pane shows the session: what the agent is working on, its progress, and a place to steer it ("Ask for a rewrite, summary, or next step…"). Updates flow into the note in real time, so you can follow along while it writes.
-
----
-
-## Creating and managing notes
-
-### Create a note
-
-- Start typing in an empty editor, or
-- Press **Cmd/Ctrl + N**, or
-- Open the command palette (**Cmd/Ctrl + K**) → **New Note**
-
-::theme-image{light="/screenshots/cloud-app/v2-new-note-light.png" dark="/screenshots/cloud-app/v2-new-note-dark.png" alt="New note"}
-::
-
-### Move notes
-
-- Use a note's `⋮` menu → **Move** to relocate it to another folder, or
-- Drag the note card from the list onto the desired folder, or
-- Drag a folder in the tree to move an entire directory.
-
-### Delete notes
-
-Open a note's `⋮` menu → **Delete**.
-
-::warning
-Deletion is permanent. Create a snapshot before bulk deletions if you want the ability to restore.
-::
-
-### Copy permalink and rename
-
-From a note's `⋮` menu or the command palette, you can also **Rename Note** and **Copy Permalink**.
-
-### Share a note
-
-From a note's `⋮` menu, choose **Share note** to create a public, read-only link anyone can open without an account. See [Shared Notes](/cloud/shared-notes).
-
-### See a note's history
-
-Every save creates a new version. Click the **File history** icon (clock) in a note's toolbar to browse the timeline, compare any earlier version against the current one, and merge old content back in. See [File History](/cloud/file-history).
-
----
-
-## Projects
-
-Projects are top-level containers. Each has its own folder tree, notes, and sync configuration.
-
-### Switch projects
-
-Use the project selector in the sidebar to switch between projects.
-
-### Manage projects
-
-Go to **Settings → Projects** to create new projects, upload files, download a project as a ZIP, or delete a project.
-
-::theme-image{light="/screenshots/cloud-app/v2-manage-projects-light.png" dark="/screenshots/cloud-app/v2-manage-projects-dark.png" alt="Manage projects"}
-::
-
-::tip
-Upload entire folders and folder trees via the [command line tools](/cloud/cloud-guide#command-line-tools) — directory structure is preserved.
-::
-
----
-
-## Import data
-
-Import your existing AI conversations from **Settings → Import**.
-
-| Format | File |
-|--------|------|
-| **Claude** | `conversations.json` from a Claude export |
-| **ChatGPT** | Export ZIP or JSON from ChatGPT settings |
-| **Basic Memory JSON** | Memory exports with entities & relations |
-
-1. Go to **Settings → Import**
-2. Select the import type
-3. Choose a target project (or use the default)
-4. Set a destination folder (default: `imports`)
-5. Upload your file and start the import
-
-::theme-image{light="/screenshots/cloud-app/v2-import-light.png" dark="/screenshots/cloud-app/v2-import-dark.png" alt="Import data"}
-::
-
-::note
-Imported conversations are converted to Basic Memory's knowledge format automatically.
-::
-
----
-
-## Snapshots
-
-Create point-in-time backups of your cloud data from **Settings → Snapshots**. Use them before major changes like bulk imports or reorganizations.
-
-::tip
-For complete snapshot management including creating, browsing, and restoring snapshots, see the [Cloud Snapshots Guide](/cloud/cloud-snapshots).
-::
-
----
-
-## Keyboard Shortcuts
-
-The web app is designed for keyboard-first navigation. Press **Cmd/Ctrl + /** to see the full list in the app.
-
-### Command palette
-
-Press **Cmd/Ctrl + K** to open the command palette and search for any action — navigate to notes, settings, the graph, or projects; create a new note; switch view modes; change theme; or run note and editor actions.
-
-::theme-image{light="/screenshots/cloud-app/v2-command-light.png" dark="/screenshots/cloud-app/v2-command-dark.png" alt="Command palette"}
-::
-
-### Formatting
-
-| Shortcut | Action |
-|----------|--------|
-| **Cmd/Ctrl + B** | Bold |
-| **Cmd/Ctrl + I** | Italic |
-| **Cmd/Ctrl + E** | Inline code |
-| **Cmd/Ctrl + Option + 1** | Heading 1 |
-| **Cmd/Ctrl + Option + 2** | Heading 2 |
-| **Cmd/Ctrl + Option + 3** | Heading 3 |
-| **Cmd/Ctrl + D** | Task checkbox |
-
-### Structure
-
-| Shortcut | Action |
-|----------|--------|
-| **Cmd/Ctrl + ]** | Indent list |
-| **Cmd/Ctrl + [** | Outdent list |
-
-### View
-
-| Shortcut | Action |
-|----------|--------|
-| **Cmd/Ctrl + Shift + I** | Rich editor |
-| **Cmd/Ctrl + Shift + P** | Preview |
-| **Cmd/Ctrl + Shift + R** | Source mode |
-| **Escape** | Preview from editor |
-
-### Global
-
-| Shortcut | Action |
-|----------|--------|
-| **Cmd/Ctrl + K** | Commands |
-| **Cmd/Ctrl + N** | New note |
-| **Cmd/Ctrl + Option + E** | Focus editor |
-| **Cmd/Ctrl + Option + Z** | Toggle Zen mode |
-| **Cmd/Ctrl + /** | Keyboard shortcuts |
-
-::theme-image{light="/screenshots/cloud-app/v2-shortcuts-light.png" dark="/screenshots/cloud-app/v2-shortcuts-dark.png" alt="Keyboard shortcuts"}
-::
-
----
-
-## Settings
-
-Access settings from the user menu (top of the sidebar) or the command palette.
-
-::theme-image{light="/screenshots/cloud-app/v2-settings-light.png" dark="/screenshots/cloud-app/v2-settings-dark.png" alt="Settings"}
-::
-
-| Section | What it does |
-|---------|--------------|
-| **General** | Account and profile settings |
-| **Projects** | Create, upload to, download, and delete projects |
-| **Import** | Import Claude, ChatGPT, or JSON exports |
-| **MCP** | Connect AI assistants via MCP |
-| **Teams** | Manage [team members, roles, and invitations](/teams/about) |
-| **Billing** | Manage payment and subscription |
-| **API Keys** | Create and manage [API keys](/cloud/api-keys) for programmatic access |
-| **Snapshots** | Manage [point-in-time backups](/cloud/cloud-snapshots) |
-| **Shared Notes** | Manage public [share links](/cloud/shared-notes) for your notes |
-
-::note
-The **Teams**, **Billing**, and **Audit Logs** sections appear based on your workspace and role. See [Teams](/teams/about) for collaboration features.
-::
-
-You can also customize appearance — see [Themes](/cloud/themes).
-
----
-
-## Tips for Effective Use
-
-### Organize with folders
-
-Create a folder structure that matches how you think:
-
-```bash
-~/basic-memory/
-├── projects/       # Active projects
-├── research/       # Learning and exploration
-├── decisions/      # Decision records
-├── meetings/       # Meeting notes
-└── archive/        # Completed/old content
-```
-
-### Use pinned notes
-
-Pin your most-accessed notes (project overviews, quick references) for one-click access.
-
-### Create snapshots before big changes
-
-Before reorganizing folders, bulk importing, or deleting lots of notes, create a manual snapshot.
-
-### Collaborate with your assistant
-
-The web app and your AI assistant work together:
-1. **AI creates** detailed notes during conversations — or writes alongside you with Connect Agent
-2. **You browse and refine** in the web app
-3. **AI references** your refined notes in future conversations
-
----
-
-## Next Steps
-
-:::card-group
-::card
----
-title: Teams
-icon: i-lucide-users
-to: /teams/about
----
-Share a workspace and collaborate with your team.
-::
-
-::card
----
-title: Cloud Sync
-icon: i-lucide-refresh-cw
-to: /cloud/cloud-sync
----
-Set up bidirectional sync to edit locally and in cloud.
-::
-
-::card
----
-title: CLI Reference
-icon: i-lucide-terminal
-to: /reference/cli-reference
----
-Advanced cloud commands including snapshot CLI.
-::
-
-::card
----
-title: Knowledge Format
-icon: i-lucide-file-text
-to: /concepts/knowledge-format
----
-Learn the semantic structure for observations and relations.
-::
-:::
diff --git a/content/3.cloud/04.user-guide.md b/content/3.cloud/04.user-guide.md
deleted file mode 100644
index 9594514..0000000
--- a/content/3.cloud/04.user-guide.md
+++ /dev/null
@@ -1,480 +0,0 @@
----
-title: User Guide
-description: Learn how to effectively use Basic Memory Cloud in your daily workflow to build rich semantic knowledge.
----
-
-This guide covers everything from creating your first notes to building a comprehensive knowledge graph using Basic Memory Cloud.
-
-::tip
-Using Basic Memory locally? See the [Local User Guide](/local/user-guide) for file-based workflows and CLI commands.
-::
-
----
-
-## Basic Memory Workflow
-
-Using Basic Memory follows a natural cycle:
-
-::mermaid
----
-code: |
-  flowchart LR
-      A[Conversation] --> B[Capture]
-      B --> C[Connect]
-      C --> D[Reference]
-      D --> E[Edit]
-      E --> A
----
-::
-
-1. **Have conversations** with AI assistants like Claude
-2. **Capture knowledge** as notes in your cloud storage
-3. **Build connections** between pieces of knowledge
-4. **Reference your knowledge** in future conversations
-5. **Edit notes** in the web app when needed
-
----
-
-## Creating Knowledge
-
-### Through Conversations
-
-The most natural way to create knowledge is during conversations:
-
-```bash
-You: We've covered several authentication approaches. Could you create a note
-     summarizing what we've discussed?
-
-Claude: I'll create a note summarizing our authentication discussion.
-
-[Uses write_note tool]
-
-Done! I've created "Authentication Approaches.md" with:
-- Overview of options we discussed
-- Observations about JWT vs sessions
-- Relations to your security notes
-```
-
-This creates a Markdown file with semantic markup in your cloud knowledge base.
-
-### Through the Web App
-
-You can also create notes directly in the [web app](https://app.basicmemory.com/notes):
-
-1. Navigate to **Notes** in the web app
-2. Click **New Note** or create in a specific folder
-3. Add frontmatter with title and optional tags
-4. Structure content with observations and relations
-5. Save - changes sync automatically
-
-**Example note structure:**
-```bash
----
-title: API Design Decisions
-tags: [api, architecture, decisions]
----
-
-# API Design Decisions
-
-## Context
-We needed to choose an approach for the new API.
-
-## Observations
-- [decision] Use REST over GraphQL for simplicity #api
-- [requirement] Must support versioning from day one
-- [risk] Rate limiting needed for public endpoints
-
-## Relations
-- implements [[API Specification]]
-- depends_on [[Authentication System]]
-```
-
----
-
-## Using Special Prompts
-
-Basic Memory includes special prompts that help you leverage your knowledge base effectively.
-
-### Continue Conversation
-
-Resume previous topics with full context:
-
-```bash
-"Let's continue our conversation about [topic]"
-```
-
-**What happens:**
-- Searches your knowledge base for relevant content
-- Builds context from related documents
-- Resumes with awareness of previous discussions
-
-### Recent Activity
-
-See what you've been working on:
-
-```bash
-"What have we been discussing recently?"
-```
-
-**What happens:**
-- Retrieves recently modified documents
-- Summarizes main topics and points
-- Offers to continue any discussions
-
-### Search
-
-Find specific information:
-
-```bash
-"Find information about [topic]"
-```
-
-**What happens:**
-- Searches across all your documents
-- Summarizes key findings
-- Offers to explore specific documents
-
----
-
-## Working with Memory URLs
-
-Basic Memory uses special `memory://` URLs to reference knowledge:
-
-### URL Formats
-
-```bash
-memory://title                   # Reference by title
-memory://folder/title            # Reference by folder and title
-memory://permalink               # Reference by permalink
-memory://path/relation_type/*    # Follow all relations of type
-```
-
-### Using Memory URLs
-
-Reference existing knowledge in conversations:
-
-```bash
-You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements"
-```
-
-Claude will load that specific document and any related context.
-
-::tip
-Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same.
-::
-
----
-
-## Building Knowledge Connections
-
-### Creating Relations
-
-Use WikiLink syntax to connect knowledge:
-
-```bash
-## Relations
-- implements [[Authentication System]]
-- requires [[Database Schema]]
-- relates_to [[Security Guidelines]]
-```
-
-### Common Relation Types
-
-| Type | Use for |
-|------|---------|
-| `implements` | One thing implements another |
-| `requires` | Dependencies |
-| `relates_to` | General connections |
-| `part_of` | Hierarchy relationships |
-| `extends` | Extensions or enhancements |
-| `pairs_with` | Things that work together |
-| `inspired_by` | Source of ideas |
-| `replaces` | Supersedes another document |
-
-### Adding Observations
-
-Structure facts with semantic categories:
-
-```bash
-## Observations
-- [decision] We chose JWT tokens for stateless auth
-- [requirement] Must support 2FA for sensitive operations
-- [technique] Use bcrypt for password hashing
-- [issue] Rate limiting needed for login attempts
-- [fact] Average response time is 50ms
-- [question] Should we support OAuth?
-```
-
----
-
-## Multi-Project Workflows
-
-### How Projects Work
-
-Basic Memory Cloud supports multiple projects for organizing different knowledge bases. When you start a conversation, the AI will:
-
-1. Check your available projects
-2. Suggest the most active project based on recent activity
-3. Ask which project to use for this conversation
-4. Remember your choice throughout the session
-
-**Example conversation:**
-```bash
-You: "Let's work on documentation"
-
-Claude: I see you have 3 projects: main, work-notes, personal
-Your most active project is work-notes.
-Should I use work-notes for this task?
-
-You: "Yes, let's use work-notes"
-
-Claude: I'll use the 'work-notes' project for our session.
-```
-
-### Managing Projects in Web App
-
-In the [web app](https://app.basicmemory.com/notes):
-
-1. Use the **Project dropdown** in the upper left to switch projects
-2. Click **Manage Projects** to create, rename, or delete projects
-3. Use the **more menu** (...) on any project to upload files or download archives
-
----
-
-## Organizing Your Knowledge
-
-### Folder Structure
-
-Organize notes in any structure that suits you:
-
-```bash
-main/
-├── projects/          # Active project notes
-│   ├── api-redesign/
-│   └── mobile-app/
-├── decisions/         # Decision records
-├── learning/          # Research and learning notes
-├── meetings/          # Meeting notes
-└── archive/           # Completed/old content
-```
-
-### Best Practices
-
-- Use descriptive filenames
-- Group related content in folders
-- Include dates in time-sensitive notes (e.g., `2024-01-15 Team Standup.md`)
-- Archive old content regularly
-
-### Moving and Organizing
-
-In the web app, you can drag and drop notes between folders. Or ask your AI:
-
-```bash
-You: "Move my old meeting notes to the archive folder"
-
-Claude: [Uses move_note]
-"Done! I've moved 12 meeting notes to the archive folder."
-```
-
----
-
-## Editing Notes
-
-### In the Web App
-
-The web app provides a live Markdown editor:
-
-1. Click any note to open it
-2. Edit directly in the editor pane
-3. Changes save automatically
-4. Preview renders in real-time
-
-### Through AI
-
-Ask your AI to make changes:
-
-```bash
-You: "Add a troubleshooting section to my setup guide"
-
-Claude: [Uses edit_note with append operation]
-"I've added a troubleshooting section to the end of your setup guide."
-```
-
-**Available operations:**
-- `append` - Add content to end
-- `prepend` - Add content to beginning
-- `find_replace` - Replace specific text
-- `replace_section` - Replace entire section by heading
-
-### Directory Operations
-
-Move or delete entire folders:
-
-```bash
-You: "Move the old-projects folder to archive"
-
-Claude: [Uses move_note with is_directory=true]
-"Moved old-projects/ → archive/old-projects/ (15 files)"
-```
-
----
-
-## Importing Data
-
-### From Claude or ChatGPT
-
-Import your conversation history:
-
-1. In the web app, go to **Settings → Import Data**
-2. Select import type (Claude or ChatGPT)
-3. Choose target project and destination folder
-4. Upload your export file
-
-::tip
-Imported conversations are converted to Basic Memory's markdown format with observations and relations extracted automatically.
-::
-
-### From Files
-
-Upload existing markdown files:
-
-1. In the web app, click **Manage Projects**
-2. Click the **more menu** (...) on your project
-3. Select **Upload** and choose files or folders
-
----
-
-## Snapshots and Backup
-
-Basic Memory Cloud automatically creates daily snapshots. You can also create manual snapshots before major changes.
-
-### Creating Snapshots
-
-In the web app or via CLI:
-
-```bash
-bm cloud snapshot create "Before reorganization"
-```
-
-### Restoring from Snapshots
-
-1. List available snapshots
-2. Browse snapshot contents
-3. Download and restore individual files as needed
-
-See the [Cloud Guide](/cloud/cloud-guide#cloud-snapshots) for detailed snapshot management.
-
----
-
-## Best Practices
-
-### Knowledge Creation
-
-1. **Create relations** - Link related concepts with `[[WikiLinks]]`
-2. **Make observations** - Structure facts with `[category]` syntax
-3. **Be descriptive** - Use clear titles and rich content
-4. **Add context** - Include background and reasoning
-5. **Review and refine** - Edit AI-generated content for accuracy
-
-### Workflow
-
-1. **Use special prompts** - "Continue conversation", "Recent activity", "Search"
-2. **Build incrementally** - Add to existing notes rather than creating duplicates
-3. **Organize regularly** - Move old content to archive
-4. **Cross-reference** - Link new content to existing knowledge
-5. **Use projects** - Separate work, personal, research
-
-### Long-term Maintenance
-
-1. **Archive old content** - Keep active knowledge base focused
-2. **Refactor connections** - Update relations as knowledge evolves
-3. **Regular reviews** - Periodically update key documents
-4. **Use snapshots** - Create snapshots before major reorganizations
-
----
-
-## Local Sync (Optional)
-
-Want to edit files locally with Obsidian or VS Code? Set up bidirectional sync:
-
-```bash
-bm cloud login
-bm cloud setup
-bm cloud bisync --name main
-```
-
-This syncs your cloud notes to a local folder. Changes in either location sync automatically.
-
-See the [Cloud Sync Guide](/cloud/cloud-sync) for detailed setup.
-
----
-
-## Troubleshooting
-
-### AI Can't Find Knowledge
-
-1. Confirm you're connected to the correct project
-2. Check that the note exists in the web app
-3. Use `memory://` URLs for direct references
-4. Try searching with different terms
-
-### Web App Issues
-
-1. Refresh the page
-2. Check your subscription status
-3. Clear browser cache if notes aren't updating
-4. Try a different browser
-
-### Sync Issues
-
-If using local sync:
-1. Check sync status: `bm cloud status`
-2. Run manual sync: `bm cloud bisync --name main`
-3. Check for conflicts in the sync log
-
-### Getting Help
-
-- **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #help channel
-- **GitHub**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues)
-
----
-
-## Next Steps
-
-:::card-group
-::card
----
-title: Knowledge Format
-icon: i-lucide-file-text
-to: /concepts/knowledge-format
----
-Learn the semantic patterns for observations and relations.
-::
-
-::card
----
-title: Web App Guide
-icon: i-lucide-layout-panel-left
-to: /cloud/web-app
----
-Detailed guide to the web editor interface.
-::
-
-::card
----
-title: Cloud Sync
-icon: i-lucide-refresh-cw
-to: /cloud/cloud-sync
----
-Set up bidirectional sync with local files.
-::
-
-::card
----
-title: MCP Tools Reference
-icon: i-lucide-wrench
-to: /reference/mcp-tools-reference
----
-All available tools for AI assistants.
-::
-:::
diff --git a/content/3.cloud/06.themes.md b/content/3.cloud/06.themes.md
deleted file mode 100644
index 4057315..0000000
--- a/content/3.cloud/06.themes.md
+++ /dev/null
@@ -1,241 +0,0 @@
----
-title: Themes
-description: Customize the look and feel of Basic Memory Cloud with preset themes or custom CSS.
----
-
-Basic Memory Cloud includes a comprehensive theme system with 40+ preset themes and support for custom CSS. Personalize your workspace with colors, fonts, and styles that work for you.
-
-![Themes](/screenshots/cloud-app/themes.gif)
----
-
-## Color Mode
-
-Switch between light, dark, or system-based color modes:
-
-1. Open **Settings** in the web app
-2. Find the **Theme** section
-3. Click **Light**, **Dark**, or **System**
-
-System mode automatically matches your operating system preference.
-
----
-
-## Preset Themes
-
-Choose from 40+ curated themes, each with coordinated colors for both light and dark modes.
-
-### Selecting a Theme
-
-1. Open **Settings** in the web app
-2. Find the **Theme** section
-3. Click the theme dropdown
-4. Preview themes by hovering - see the color palette
-5. Click to apply
-
-### Available Themes
-
-**Popular presets include:**
-- **Default** - Clean white/dark gray base
-- **Modern Minimal** - Blue-focused minimal design
-- **Violet Bloom** - Purple-focused theme
-- **T3 Chat** - Inspired by T3 Chat interface
-- And 35+ more options
-
-Each theme defines:
-- Background and foreground colors
-- Primary and accent colors
-- Sidebar colors
-- Card and border styles
-- Typography (optional)
-
----
-
-## Custom Themes
-
-Create your own theme with custom CSS variables.
-
-### Adding a Custom Theme
-
-1. Open **Settings** in the web app
-2. Find the **Theme** section
-3. Click **Custom Theme**
-4. Paste your CSS or drag-and-drop a `.css` file
-5. Click **Save**
-
-### CSS Format
-
-Custom themes use CSS variables in TweakCN format:
-
-```css
-:root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --radius: 0.625rem;
-}
-
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  /* ... dark mode overrides */
-}
-```
-
-### Required Variables
-
-Your custom theme must define these variables for both light (`:root`) and dark (`.dark`) modes:
-
-| Variable | Purpose |
-|----------|---------|
-| `--background` | Page background |
-| `--foreground` | Primary text |
-| `--card` | Card backgrounds |
-| `--card-foreground` | Card text |
-| `--popover` | Dropdown/menu backgrounds |
-| `--popover-foreground` | Dropdown/menu text |
-| `--primary` | Primary buttons, links |
-| `--primary-foreground` | Text on primary elements |
-| `--secondary` | Secondary elements |
-| `--secondary-foreground` | Text on secondary elements |
-| `--muted` | Muted backgrounds |
-| `--muted-foreground` | Muted text |
-| `--accent` | Accent highlights |
-| `--accent-foreground` | Text on accents |
-| `--destructive` | Delete/danger actions |
-| `--border` | Borders |
-| `--input` | Input field borders |
-| `--ring` | Focus rings |
-
-### Optional Variables
-
-Customize typography and layout:
-
-```css
-:root {
-  /* Typography */
-  --font-sans: 'Inter', sans-serif;
-  --font-serif: 'Georgia', serif;
-  --font-mono: 'JetBrains Mono', monospace;
-  --letter-spacing: -0.01em;
-
-  /* Layout */
-  --radius: 0.5rem;
-  --spacing: 1rem;
-}
-```
-
-### Sidebar Variables
-
-Customize the sidebar separately:
-
-```css
-:root {
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.205 0 0);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0 0);
-  --sidebar-accent-foreground: oklch(0.205 0 0);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
-}
-```
-
----
-
-## Using TweakCN
-
-[TweakCN](https://tweakcn.com) is a theme generator compatible with Basic Memory Cloud.
-
-### Export from TweakCN
-
-1. Visit [tweakcn.com](https://tweakcn.com)
-2. Customize your theme with the visual editor
-3. Export as CSS
-4. Paste into Basic Memory Cloud's custom theme editor
-
-### Color Format
-
-TweakCN uses OKLCH color format for better perceptual uniformity:
-
-```css
-/* OKLCH format: oklch(lightness chroma hue) */
---primary: oklch(0.6 0.2 250);  /* Blue */
---accent: oklch(0.7 0.15 330);  /* Purple */
-```
-
----
-
-## Theme Persistence
-
-Your theme choice is saved locally in your browser:
-- Persists across sessions
-- Applies immediately on page load
-- Separate settings for each browser/device
-
-::note
-Theme settings are stored in your browser's localStorage, not in your cloud account. If you switch browsers or devices, you'll need to set your theme again.
-::
-
----
-
-## Troubleshooting
-
-### Theme Not Applying
-
-1. Check browser console for CSS errors
-2. Verify all required variables are defined
-3. Ensure both `:root` and `.dark` sections exist
-4. Try refreshing the page
-
-### Colors Look Wrong
-
-1. Verify OKLCH values are valid (lightness 0-1, chroma 0-0.4, hue 0-360)
-2. Check for typos in variable names
-3. Test in both light and dark modes
-
-### Custom Theme Rejected
-
-The editor validates your CSS. Common issues:
-- Missing required variables
-- Invalid CSS syntax
-- CSS too large (size limit applies)
-
----
-
-## Next Steps
-
-:::card-group
-::card
----
-title: Web App Guide
-icon: i-lucide-layout-panel-left
-to: /cloud/web-app
----
-Complete guide to the web editor interface.
-::
-
-::card
----
-title: API Keys
-icon: i-lucide-key
-to: /cloud/api-keys
----
-Create API keys for programmatic access.
-::
-:::
diff --git a/content/3.cloud/10.edit-locally-and-in-the-app.md b/content/3.cloud/10.edit-locally-and-in-the-app.md
deleted file mode 100644
index e28af9b..0000000
--- a/content/3.cloud/10.edit-locally-and-in-the-app.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-title: Edit Locally and in the App
-description: Happy-path setup for hybrid editing — work on the same project in Obsidian or VS Code locally and in the cloud app, with bidirectional sync keeping both sides in step.
----
-
-You want the best of both worlds: edit the same project in your local editor (Obsidian, VS Code, Cursor…) **and** in the [cloud app](/cloud/web-app), with both sides staying in sync. This page is the happy path — get a project sync'd in five steps, then the day-to-day routine.
-
-::note{icon="i-lucide-info"}
-This is a stitched-together how-to. For the deep reference on bidirectional sync — architecture, filters, conflict handling — see [Cloud Sync](/cloud/cloud-sync).
-::
-
----
-
-## What you'll have when you're done
-
-- A cloud project that mirrors a local folder on your machine.
-- Edits in either place propagate to the other with `bm cloud bisync`.
-- Your AI assistant (via MCP) sees the same notes whether you're working locally or remotely.
-
----
-
-## One-time setup
-
-::steps
-### Sign in to cloud
-
-```bash
-bm cloud login
-```
-
-A browser tab walks you through OAuth. After confirming the displayed code, you're authenticated and CLI commands route through cloud by default.
-
-### Install sync tooling
-
-```bash
-bm cloud setup
-```
-
-This installs and configures `rclone`, which Basic Memory uses under the hood for bidirectional sync.
-
-### Add or attach the project
-
-Two starting points — pick the one that matches you:
-
-**You already have local notes** you want to push to cloud:
-
-```bash
-bm project add my-notes --cloud --local-path ~/notes
-```
-
-This creates a cloud project named `my-notes` and points its local mirror at `~/notes`.
-
-**The project already exists in cloud** and you want to clone it locally:
-
-```bash
-bm cloud sync-setup my-notes ~/notes
-```
-
-This wires an existing cloud project to a new local path.
-
-### Establish a baseline (`--resync`)
-
-The first bisync needs a baseline. Preview it first:
-
-```bash
-bm cloud bisync --name my-notes --resync --dry-run
-```
-
-Look at the plan, then run it for real:
-
-```bash
-bm cloud bisync --name my-notes --resync
-```
-
-After this, both sides are aligned and ready for ongoing sync.
-
-### Verify
-
-Open the project in the [web app](https://app.basicmemory.com) and confirm your notes are there. Then check your local folder — you should see the same files.
-::
-
----
-
-## The day-to-day routine
-
-Once the baseline is set, sync is a single command:
-
-```bash
-bm cloud bisync --name my-notes
-```
-
-Run it:
-- After a session of local edits, before switching to the app.
-- After working in the app, before opening your local editor.
-- Whenever you want to be sure both sides agree.
-
-That's it. The rest is editing wherever you like.
-
-::tip
-**Editor of choice.** Once your project syncs to a local folder, any markdown editor works — [Obsidian](/integrations/obsidian) (point a vault at the folder), [VS Code](/integrations/vscode), [Cursor](/integrations/cursor), or just `vim`. Your AI assistant reads the same notes either way.
-::
-
----
-
-## A few habits that help
-
-- **Sync before and after a session.** It's cheap and avoids surprise conflicts.
-- **Don't fight an active sync.** If `bm cloud bisync` is running, let it finish before editing again.
-- **Keep one project per local folder.** Don't nest project folders inside each other — Basic Memory expects each project's local path to be self-contained.
-- **`.bmignore` if you have to.** If a folder contains files you don't want synced (build output, caches), add it to `.bmignore` at the project root — bisync respects it.
-
----
-
-## What if I want some projects local-only and others in cloud?
-
-That's the [routing](/cloud/routing) model. You can keep personal projects entirely local while syncing only a couple of projects to cloud. The hybrid setup on this page is one routing configuration; routing covers the others (all-local, all-cloud, mixed, per-command overrides).
-
----
-
-## When sync needs help
-
-`bm cloud bisync` is conservative by design — if it sees something it can't safely resolve, it stops and tells you. The [Cloud Sync guide](/cloud/cloud-sync) covers the deeper cases: conflict resolution, `bm cloud check` for integrity verification, and `bm cloud bisync-reset` if you ever need to start the baseline over.
-
----
-
-## Related
-
-- [Cloud Sync](/cloud/cloud-sync) — deep reference for bidirectional sync
-- [Local & Cloud Routing](/cloud/routing) — choose where each project lives
-- [Web App](/cloud/web-app) — what the cloud side looks like
-- [Obsidian](/integrations/obsidian) · [VS Code](/integrations/vscode) · [Cursor](/integrations/cursor) — local editor integrations
-- [CLI Reference](/reference/cli-reference) — every `bm cloud` command
diff --git a/content/4.teams/1.about.md b/content/4.teams/1.about.md
deleted file mode 100644
index e4c9707..0000000
--- a/content/4.teams/1.about.md
+++ /dev/null
@@ -1,261 +0,0 @@
----
-title: Basic Memory Teams
-description: Share a cloud workspace with your team — invite members, assign roles, and collaborate on the same projects.
----
-
-Basic Memory Teams gives your team a single, shared cloud workspace. Knowledge isn't confined to one person — anything a teammate writes is immediately available to everyone else and to their AI assistants. Edit a note together in real time, hand work off between humans and agents, and build one connected knowledge base instead of scattered copies.
-
-::note{icon="i-lucide-users"}
-**Teams requires a subscription with one or more seats.** Billing is per seat. Joining or starting a team doesn't change anything about your existing setup — your personal cloud subscription (if you have one) and any local projects keep working exactly as before. Teams adds a team workspace alongside them.
-::
-
----
-
-## Workspaces
-
-Your account can have more than one workspace. Each keeps its own projects, notes, and members.
-
-| Workspace | Who can access it | Notes |
-|-----------|-------------------|-------|
-| **Local** | Just you, on your machine | No team features; runs entirely on your computer |
-| **Personal Cloud** | Just you | Your personal cloud subscription and notes |
-| **Team** | Your team | Shared projects, members, roles, and seats |
-
-Switch between workspaces using the workspace selector in the app. Projects and notes are scoped to the workspace you're in.
-
----
-
-## Roles
-
-Every member of a team has a role that determines what they can do.
-
-| Role | Can do |
-|------|--------|
-| **Viewer** | Read-only access to projects and notes |
-| **Editor** | Read and write notes, and create projects |
-| **User Admin** | Everything an editor can, plus manage members and invitations |
-| **Admin** | Everything a user admin can, plus manage API keys, snapshots, and view audit log |
-| **Owner** | Everything an admin can, plus manage billing, rename team, and transfer ownership. A team can have only one member with the Owner role. |
-
-
-Once a invitation has been extended to a user, members also have a **status**:
-
-- **Pending** — invited, but hasn't finished linking their account yet
-- **Active** — User has accepted the invitation, thus fully claiming the seat and has full access according to their role
-- **Deactivated** — removed from the team; their history is preserved and their seat is released
-
-::theme-image{light="/screenshots/cloud-app/v2-settings-teams-light.png" dark="/screenshots/cloud-app/v2-settings-teams-dark.png" alt="Team members list"}
-::
-
----
-
-## Working together in real time
-
-When two people open the same note, they see each other's edits as they happen. The editor is built on CRDTs (Yjs), so every keystroke syncs instantly across collaborators with no merge conflicts to resolve. A presence avatar appears in the note header for each active collaborator — each one gets a distinct color so you can tell at a glance who's typing where.
-
-### AI agents as collaborators
-
-::note{icon="i-lucide-sparkles"}
-**Coming soon.** AI agents will join as first-class collaborators alongside your team.
-::
-
-Once available, you'll connect an agent to a note and it shows up in the same presence list as your teammates with a live status indicator — _working_, _just updated_, or _waiting for input_. Agents read the shared knowledge graph for context and write structured observations and relations back into it, so the more your team uses Basic Memory, the better your AI gets at answering from your team's actual knowledge.
-
-### Activity feed
-
-The **Activity** view in the app keeps you aware of what's happening across the workspace. It shows operations in progress (imports, indexing, large edits) and recent completed changes — from every team member and agent — with direct links to the affected notes.
-
----
-
-## File history — undo on the file level
-
-Every save creates a new version of a note, automatically. If a teammate overwrites something or an agent edits go sideways, open **File history** on the note to step back through the timeline, compare any version against the current one, and merge content back in. Restored content saves as a _new_ version, so nothing is ever lost.
-
-See [File History](/cloud/file-history) for the full reference, or [Restore Lost Content](/cloud/restore-lost-content) for the broader recovery decision guide (File history for a single note, Snapshots for bigger rollbacks).
-
----
-
-## Inviting members
-
-Owners invite people by email from **Settings → Teams**.
-
-::theme-image{light="/screenshots/cloud-app/v2-team-invite-light.png" dark="/screenshots/cloud-app/v2-team-invite-dark.png" alt="Invite a member"}
-::
-
-To invite a member, click the "Invite Member" button.
-
-::steps
-### Send an invitation
-
-
-Enter the person's email address and choose a role (Editor or Viewer). They'll receive an email with an invitation link.
-
-
-::theme-image{light="/screenshots/cloud-app/v2-team-invitation-light.png" dark="/screenshots/cloud-app/v2-team-invitation-dark.png" alt="Team invitation email"}
-::
-
-### They receive an email
-
-The invitee gets an email invitation.
-
-::theme-image{light="/screenshots/cloud-app/v2-team-accept-invite-email.png" dark="/screenshots/cloud-app/v2-team-accept-invite-email.png" alt="Email invitation"}
-::
-
-Click the accept button. 
-
-### They accept
-
-The link opens an accept page. The invitee signs in (or creates an account) using the email the invitation was sent to. If they're already signed in with a different account, they'll be asked to sign in again with the invited email.
-
-::theme-image{light="/screenshots/cloud-app/v2-team-accept-invite-light.png" dark="/screenshots/cloud-app/v2-team-accept-invite-dark.png" alt="Accept an invitation"}
-::
-
-### Account linking
-
-On first sign-in, their authenticated account is linked to the pending membership, and they become an active member.
-::
-
-::note{icon="i-lucide-credit-card"}
-**Seats are assigned when an invitation is claimed, not when it's sent.** Inviting someone doesn't consume a seat until they accept — so a pending invitation won't be billed until the person joins.
-::
-
-::tip
-**For invitees:** see [Joining a Team Workspace](/teams/join-a-team) for a step-by-step walkthrough of accepting the invite, switching workspaces, and connecting your AI assistant.
-::
-
----
-
-## Managing members
-
-From **Settings → Teams**, an owner can:
-
-- **Change a member's role** — promote a viewer to editor, or vice versa.
-- **Deactivate a member** — removes their access and frees their seat. Their authored history stays intact.
-- **Reactivate a member** — restores access, reassigning a seat if one is available.
-- **Transfer ownership** — hand the workspace (and its subscription) to another member. The new owner takes over billing and management.
-
----
-
-## Seats and billing
-
-Teams billing is **per seat**. The number of seats on your subscription sets how many active members the workspace can have.
-
-- Each active member occupies one seat.
-- Deactivating a member frees their seat for someone else.
-- Reactivating a member requires an available seat.
-- Pending invitations don't consume a seat until they're accepted.
-- If your team grows past your current seat allocation, there's a **14-day grace period** before any restrictions kick in — so a new hire never gets locked out while you're adding seats.
-
-Manage seats and payment from **Settings → Billing**.
-
-::theme-image{light="/screenshots/cloud-app/v2-team-manage-billing-light.png" dark="/screenshots/cloud-app/v2-team-manage-billing-dark.png" alt="Seats and billing"}
-::
-
-Track current seat usage from the same screen:
-
-::theme-image{light="/screenshots/cloud-app/v2-team-usage-light.png" dark="/screenshots/cloud-app/v2-team-usage-dark.png" alt="Team seat usage"}
-::
-
----
-
-## Projects
-
-Team projects come in three visibilities. The right one depends on who needs to see the work:
-
-| Visibility | Who can see it | When to use |
-|------------|----------------|-------------|
-| **Standard** (`team`) — _default_ | Everyone in the team, based on their team role (viewer/editor/owner) | Most team work — the open, shared knowledge base |
-| **Shared** (`shared`) | Only people you grant access to, each at **editor** or **viewer** level | Sensitive topics (hiring, contracts, security audits) where you want a controlled group |
-
-When you create a cloud project, you can set its visibility from the CLI:
-
-```bash
-# Standard — visible to everyone in the team workspace (default)
-bm project add team-wiki --cloud --workspace acme --visibility workspace
-
-# Shared — only people you grant access to
-bm project add hiring-2026 --cloud --workspace acme --visibility shared
-
-# Private — just you
-bm project add my-scratch --cloud --workspace acme --visibility private
-```
-
-See the [CLI Reference](/reference/cli-reference) for full `bm project add` options.
-
----
-
-## Bringing existing notes into a team workspace
-
-When you join (or start) a team, you'll often want to promote work from your personal workspace into the shared one. Cross-workspace transfers are a **copy** workflow — export from the source, import into the target, verify, then optionally delete the original.
-
-See [Copy Content Between Workspaces](/teams/copy-between-workspaces) for the project ZIP, single-note, MCP, and local-sync workflows, along with caveats around wikilinks, permissions, and share links.
-
----
-
-## Working with team projects
-
-Once you're part of a team, projects show up everywhere you work:
-
-- **In the app** — Select the project in the sidebar.
-- **In your AI assistant (MCP)** — your assistant's project list spans every cloud workspace you can access, so it reaches team projects without extra setup. See [v0.21.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.0) for details on cross-workspace discovery.
-- **In the CLI** — `bm project list` shows projects across all your workspaces.
-
-### Workspace commands
-
-```bash
-# List the cloud workspaces available to you
-bm cloud workspace list
-
-# Set the default workspace for CLI and MCP routing
-bm cloud workspace set-default acme
-```
-
-You can also target a specific workspace when creating a project, either from the CLI (`--workspace`) or from MCP (`create_memory_project(workspace="acme")`).
-
----
-
-## Security and isolation
-
-Each team gets its **own** isolated database and file storage in the cloud — there is no shared tenancy at the data layer. Your team's knowledge is physically separated from every other team's. Authentication runs through [WorkOS AuthKit](https://workos.com/authkit) for enterprise-grade identity management.
-
----
-
-## Next Steps
-
-:::card-group
-::card
----
-title: Web App
-icon: i-lucide-layout-dashboard
-to: /cloud/web-app
----
-Browse, edit, and collaborate on notes in the app.
-::
-
-::card
----
-title: Local & Cloud Routing
-icon: i-lucide-route
-to: /cloud/routing
----
-Run some projects locally and others in the cloud.
-::
-
-::card
----
-title: CLI Reference
-icon: i-lucide-terminal
-to: /reference/cli-reference
----
-Full `bm project` and `bm cloud workspace` commands.
-::
-
-::card
----
-title: What's New in v0.22.0
-icon: i-lucide-megaphone
-to: /whats-new/v0.22.0
----
-Team-safe cloud push and pull.
-::
-:::
diff --git a/content/7.integrations/12.claude-research-mode.md b/content/7.integrations/12.claude-research-mode.md
deleted file mode 100644
index 3186898..0000000
--- a/content/7.integrations/12.claude-research-mode.md
+++ /dev/null
@@ -1,82 +0,0 @@
----
-title: Claude Research Mode
-description: Why your MCP connectors (including Basic Memory) aren't available during a Claude advanced-research run — and the recommended flow for combining research with your knowledge base.
----
-
-When you turn on **advanced research**, Claude hands your request to a dedicated research agent that works across the web and Google Drive. That agent runs in its own environment and **does not have access to your connected MCP servers** — including Basic Memory, Gmail, Google Calendar, and any other connectors. This is a limitation of research mode itself, not of any individual connector: every MCP connector is unavailable during a research run, in the same way.
-
-What this means in practice:
-
-- **During a research run,** Claude can't read from or write to Basic Memory (or call any other connector's tools). It will research using web and Drive sources only.
-- **After a research run finishes,** control returns to the normal conversation — which _does_ have your connectors. At that point Claude can save the results to Basic Memory, draft an email, add a calendar event, and so on.
-
-So research and your connectors aren't combined in a single step, but they chain cleanly: **research first, then act on the results with your connectors second.**
-
----
-
-## Recommended flow: research → save to Basic Memory
-
-::steps
-### Turn advanced research on
-
-Toggle **advanced research** in the message composer, then run your query — for example, _"survey how other agent-memory tools expose graph APIs."_
-
-### Wait for the report
-
-Let the research run complete. The report comes back inline in the conversation.
-
-### Turn advanced research off
-
-Use the same toggle to drop back into normal conversation. This is the important step — leaving research on keeps connectors out of reach.
-
-### Ask Claude to save it
-
-Now you're back in the normal tool path. Ask Claude to write up the results — _"Save that as a note in my `research` project"_ — and it can call Basic Memory's [`write_note`](/reference/mcp-tools-reference#write_note) directly.
-::
-
-The same pattern works in reverse for context you already have: if you need Claude to _use_ your Basic Memory notes as input, keep research off and ask normally — Claude can read your notes and reason over them directly. Use research only when you specifically want fresh web/Drive sources.
-
-::tip
-**Which mode do I need?** If the question is "go find out what's out there on the web," use research. If it's "do something with my notes/data," keep research off.
-::
-
----
-
-## Why this happens
-
-Research mode runs a separate agent with its own toolset (web search, Google Drive). MCP connectors live on the main Claude conversation, not inside the research agent's environment. The research agent doesn't know your connectors exist, so it can't call them — and there's no way to "pass through" a connector during a research run.
-
-This is the same for **every** MCP connector, not specific to Basic Memory. If you have a workflow that wants both web research _and_ your private knowledge base in a single step, today the answer is to run them sequentially: research first, then a follow-up turn that uses your connectors on the results.
-
----
-
-## Related
-
-:::card-group
-::card
----
-title: Claude Desktop
-icon: i-lucide-monitor
-to: /integrations/claude-desktop
----
-Connect Basic Memory to Claude Desktop or Claude on the web.
-::
-
-::card
----
-title: MCP Tools Reference
-icon: i-lucide-wrench
-to: /reference/mcp-tools-reference
----
-Every tool Claude can call when research mode is off.
-::
-
-::card
----
-title: Web App
-icon: i-lucide-layout-dashboard
-to: /cloud/web-app
----
-Save and organize research results in the cloud app.
-::
-:::
diff --git a/content/9.reference/3.ai-assistant-guide.md b/content/9.reference/3.ai-assistant-guide.md
deleted file mode 100644
index 6851187..0000000
--- a/content/9.reference/3.ai-assistant-guide.md
+++ /dev/null
@@ -1,974 +0,0 @@
----
-title: AI Assistant Guide
-description: Guide for AI assistants using Basic Memory through the Model Context Protocol (MCP).
----
-
-::note
-This is a technical guide for developers and AI integrations. For an overview of how Basic Memory works, see [What is Basic Memory](/start-here/what-is-basic-memory).
-
-This guide is for AI assistants using Basic Memory tools through MCP. For setup instructions, see [Getting Started](/start-here/getting-started).
-
-Download the [AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) and customize it to your own workflow. A [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md) is available as an MCP Resource in Basic Memory.
-::
-
-::tip
-**AI agents:** This documentation is available as clean markdown. Fetch `https://docs.basicmemory.com/llms.txt` for an index or `https://docs.basicmemory.com/llms-full.txt` for the complete docs. See [AI-Friendly Documentation](/reference/llms-txt) for details.
-::
-
-This guide explains how to use Basic Memory tools effectively when working with users through the Model Context Protocol.
-
----
-
-## Overview
-
-Basic Memory creates a semantic knowledge graph from markdown files stored locally on the user's computer. Knowledge persists across sessions, enabling continuity in conversations and collaborative development.
-
-**Architecture:**
-- **Plain-Text**: Markdown files as source of truth
-- **SQLite Index**: Fast search and navigation
-- **MCP Integration**: Tools for AI interaction
-- **Semantic Graph**: Observations and relations create connections
-
-**Your role:** Help users build structured knowledge that outlasts any particular AI model or session. Focus on creating observations and relations that provide lasting value.
-
----
-
-## Project Management
-
-All tools require explicit project specification. No implicit project context is maintained between calls.
-
-### Discovery and Selection
-
-Start conversations by discovering available projects:
-
-```python
-# List all projects
-projects = await list_memory_projects()
-
-# Response includes:
-# - name
-# - path
-# - is_default
-# - note_count
-# - last_synced
-```
-
-**Recommended workflow:**
-
-1. Call `list_memory_projects()` at conversation start
-2. Identify active project from metadata
-3. Ask user which project to use
-4. Store choice for the session
-5. Pass project parameter to all tool calls
-
-### Cross-Project Operations
-
-Some tools work across all projects when project parameter is omitted:
-
-```python
-# Recent activity across all projects
-activity = await recent_activity(timeframe="7d")
-
-# Recent activity for specific project
-activity = await recent_activity(timeframe="7d", project="main")
-```
-
-Tools supporting cross-project mode:
-- `recent_activity()`
-- `list_memory_projects()`
-
----
-
-## Knowledge Graph Structure
-
-The knowledge graph consists of three core elements: entities, observations, and relations.
-
-### Entities
-
-Each markdown file represents an entity with:
-
-- **Title**: Unique identifier
-- **Permalink**: Auto-generated from title
-- **Frontmatter**: YAML metadata (tags, type, dates)
-- **Observations**: Categorized facts
-- **Relations**: Links to other entities
-
-**Note types** (set via the `type` frontmatter field):
-- `note` - General knowledge (default)
-- `person` - People and contacts
-- `project` - Projects and initiatives
-- `meeting` - Meeting notes
-- `decision` - Documented decisions
-- `spec` - Technical specifications
-
-### Observations
-
-Observations are categorized facts with optional tags.
-
-**Syntax:** `- [category] content #tag1 #tag2`
-
-**Common categories:**
-- `[fact]` - Objective information
-- `[idea]` - Thoughts and concepts
-- `[decision]` - Choices made
-- `[technique]` - Methods and approaches
-- `[requirement]` - Needs and constraints
-- `[problem]` - Issues identified
-- `[solution]` - Resolutions
-- `[insight]` - Key realizations
-
-**Examples:**
-
-```bash
-## Observations
-- [decision] Use JWT tokens for authentication #security
-- [technique] Hash passwords with bcrypt before storage #best-practice
-- [requirement] Support OAuth 2.0 providers #auth
-- [fact] Session timeout set to 24 hours #configuration
-```
-
-### Relations
-
-Relations are directional links between entities.
-
-**Syntax:** `- relation_type [[Target Entity]]`
-
-**Common relation types:**
-- `relates_to` - General connection
-- `implements` - Implementation relationship
-- `requires` - Dependency
-- `extends` - Enhancement
-- `part_of` - Hierarchical membership
-- `contrasts_with` - Alternative approach
-- `leads_to` - Sequential relationship
-- `caused_by` - Causal relationship
-
-**Examples:**
-
-```bash
-## Relations
-- implements [[Authentication Spec v2]]
-- requires [[User Database Schema]]
-- extends [[Base Security Model]]
-- part_of [[API Backend Services]]
-- contrasts_with [[API Key Authentication]]
-```
-
-### Forward References
-
-Reference entities that don't exist yet - relations resolve automatically when targets are created:
-
-```python
-# Create note with forward reference
-await write_note(
-    title="API Implementation",
-    content="## Relations\n- implements [[API Specification]]",
-    directory="api",
-    project="main"
-)
-# Forward reference created
-
-# Later, create referenced entity
-await write_note(
-    title="API Specification",
-    content="# API Specification\n...",
-    directory="specs",
-    project="main"
-)
-# Forward reference automatically resolved
-```
-
----
-
-## Core Tools
-
-### Writing Knowledge
-
-Create new notes:
-
-```python
-await write_note(
-    title="Topic",
-    content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
-    directory="notes",
-    project="main"
-)
-```
-
-**Parameters:**
-- `title` (required) - Note title
-- `content` (required) - Markdown content
-- `directory` (required) - Destination folder
-- `tags` (optional) - List of tags
-- `note_type` (optional) - Note type (default: `note`)
-- `metadata` (optional) - Extra frontmatter fields
-- `overwrite` (optional) - Default `false`. Must be `true` to replace an existing note
-- `project` (optional) - Uses `default_project` fallback when configured
-
-::warning
-**`write_note` is non-destructive by default.** If a note already exists at the target path, the call returns an error instead of silently overwriting. This prevents accidental data loss.
-
-- To update an existing note incrementally, use `edit_note`
-- To fully replace an existing note, pass `overwrite=True`
-- Always search before writing to check whether the note already exists
-::
-
-### Reading Knowledge
-
-Read notes with knowledge graph context:
-
-```python
-# By title
-note = await read_note("Topic", project="main")
-
-# By folder and title
-note = await read_note("specs/Authentication System", project="main")
-
-# By memory:// URL
-note = await read_note("memory://specs/auth", project="main")
-```
-
-**Response includes:**
-- Content
-- Observations (categorized)
-- Relations (typed, with targets)
-- Metadata (dates, tags, type)
-
-### Searching
-
-Find notes across the knowledge base:
-
-```python
-results = await search_notes(
-    query="authentication",
-    project="main",
-    page_size=10
-)
-```
-
-**Filter by note type:**
-
-```python
-# Find all specs about authentication
-specs = await search_notes(
-    query="authentication",
-    note_types=["spec"],
-    project="main"
-)
-
-# Find all meeting notes and decisions
-results = await search_notes(
-    note_types=["meeting", "decision"],
-    project="main"
-)
-```
-
-**Filter by date:**
-
-```python
-recent = await search_notes(
-    query="api",
-    after_date="2025-01-01",
-    project="main"
-)
-```
-
-**Search by tags:**
-
-```python
-# tag: shorthand in the query string
-results = await search_notes(query="tag:security", project="main")
-results = await search_notes(query="tag:coffee AND tag:brewing", project="main")
-
-# tags parameter shorthand
-results = await search_notes(tags=["security"], project="main")
-results = await search_notes(tags=["security", "oauth"], project="main")
-```
-
-**Search by frontmatter metadata:**
-
-The `query` parameter is optional — you can search purely by frontmatter fields. Use `metadata_filters` for structured queries against any frontmatter field, or convenience shorthands for common fields.
-
-```python
-# Find all notes with a specific status
-results = await search_notes(
-    metadata_filters={"status": "in-progress"},
-    project="main"
-)
-
-# Find high-priority items
-results = await search_notes(
-    metadata_filters={"priority": {"$in": ["high", "critical"]}},
-    project="main"
-)
-
-# Filter by team
-results = await search_notes(
-    metadata_filters={"team": "backend"},
-    project="main"
-)
-
-# Combine text search with metadata filters
-results = await search_notes(
-    query="authentication",
-    metadata_filters={"status": "draft"},
-    project="main"
-)
-
-# Convenience shorthands for common fields
-results = await search_notes(status="draft", project="main")
-results = await search_notes(tags=["security"], project="main")
-```
-
-**Supported filter operators:**
-
-| Operator | Example | Meaning |
-|----------|---------|---------|
-| exact match | `{"status": "draft"}` | Field equals value |
-| `$in` | `{"priority": {"$in": ["high", "critical"]}}` | Field is one of the values |
-| `$contains` | `{"tags": {"$contains": "security"}}` | Array field contains value |
-
-**Semantic search:**
-
-Semantic search is enabled by default. `hybrid` mode (combining keyword and meaning-based retrieval) is the default search type — no opt-in needed. You can also use pure semantic search:
-
-```python
-# Pure semantic similarity — finds related concepts even with different wording
-results = await search_notes(
-    query="how to speed up the application",
-    search_type="vector",
-    project="main"
-)
-
-# Hybrid — combines keyword precision with semantic recall (recommended for most queries)
-results = await search_notes(
-    query="authentication security",
-    search_type="hybrid",
-    project="main"
-)
-
-# Adjust similarity threshold for tighter or looser results
-results = await search_notes(
-    query="error handling patterns",
-    search_type="hybrid",
-    min_similarity=0.7,
-    project="main"
-)
-```
-
-**When to use which search mode:**
-- `hybrid` (default) — General-purpose. Start here for most queries.
-- `text` — You know the exact terms. Best for names, identifiers, boolean queries.
-- `vector` — Conceptual discovery. The note may not contain your exact words.
-
-### Building Context
-
-Navigate the knowledge graph. `build_context` defaults to JSON output (unlike other tools which default to text).
-
-```python
-context = await build_context(
-    url="memory://specs/auth",
-    project="main",
-    depth=2,
-    timeframe="1 week"
-)
-```
-
-**Parameters:**
-- `url` (required) - memory:// URL
-- `depth` (optional) - Traversal depth (default: 1)
-- `timeframe` (optional) - Time window (e.g., "7d", "1 week")
-- `output_format` (optional) - Default `"json"`. Pass `"text"` for human-readable output
-- `project` (optional) - Uses `default_project` fallback when configured
-
-**Depth control:**
-- `depth=1` - Immediate connections only
-- `depth=2` - Two levels of relations
-- `depth=3+` - Comprehensive (may be slow)
-
-### Editing Notes
-
-Edit existing notes incrementally:
-
-```python
-# Append content
-await edit_note(
-    identifier="Topic",
-    operation="append",
-    content="\n## New Section\nContent here",
-    project="main"
-)
-
-# Prepend content
-await edit_note(
-    identifier="Topic",
-    operation="prepend",
-    content="## Update\nImportant note\n\n",
-    project="main"
-)
-
-# Find and replace
-await edit_note(
-    identifier="Topic",
-    operation="find_replace",
-    find_text="old text",
-    content="new text",
-    expected_replacements=1,
-    project="main"
-)
-
-# Replace section
-await edit_note(
-    identifier="Topic",
-    operation="replace_section",
-    section="## Status",
-    content="## Status\nUpdated status here",
-    project="main"
-)
-```
-
-**Operations:**
-- `append` - Add to end
-- `prepend` - Add to beginning
-- `find_replace` - Replace specific text
-- `replace_section` - Replace markdown section
-
-### Moving Notes
-
-Organize notes by moving them between folders:
-
-```python
-await move_note(
-    identifier="Note Title",
-    destination_path="archive/note-title.md",
-    project="main"
-)
-```
-
-**Behavior:**
-- Folders created automatically
-- Database updated automatically
-- Relations preserved
-- Both `.md` extension and without work
-
----
-
-## memory:// URL Format
-
-Basic Memory uses special URLs to reference entities. Generated permalinks include the project slug by default, so most URLs you encounter will be project-prefixed.
-
-**By title:**
-```
-memory://title
-```
-
-**By folder and title:**
-```
-memory://folder/title
-```
-
-**Project-prefixed (default format):**
-```
-memory://project-slug/folder/title
-```
-
-**By permalink:**
-```
-memory://permalink
-```
-
-**All in folder:**
-```
-memory://folder/*
-```
-
-Underscores converted to hyphens automatically - `memory://my_note` finds entity with permalink `my-note`.
-
----
-
-## Recording Conversations
-
-Capture conversations to enable long-term context and knowledge accumulation.
-
-### Permission and Transparency
-
-**Always ask before recording:**
-
-```
-AI: "Would you like me to save our discussion about API authentication
-     to Basic Memory? This helps us continue this conversation later."
-
-User: "Yes, please"
-
-AI: [Saves to Basic Memory]
-    "I've saved our discussion as 'API Authentication Discussion'."
-```
-
-**Principles:**
-- Ask permission before saving
-- Confirm after saving
-- Explain what was saved
-- Describe how it helps future conversations
-
-### What to Record
-
-**Good candidates:**
-
-1. **Decisions and Rationales**
-2. **Important Discoveries**
-3. **Action Items and Plans**
-4. **Connected Topics**
-
-### Recording Patterns
-
-**Conversation summary:**
-
-```python
-await write_note(
-    title=f"Conversation: {topic} - {date}",
-    content=f"""# Conversation: {topic}
-
-## Summary
-{brief_summary}
-
-## Key Points
-{key_points}
-
-## Observations
-{categorized_observations}
-
-## Relations
-{relevant_relations}
-""",
-    directory="conversations",
-    tags=["conversation"],
-    project="main"
-)
-```
-
-**Decision record:**
-
-```python
-await write_note(
-    title=f"Decision: {decision_title}",
-    content=f"""# Decision: {decision_title}
-
-## Context
-{why_decision_needed}
-
-## Decision
-{what_was_decided}
-
-## Rationale
-{reasoning}
-
-## Relations
-{related_entities}
-""",
-    directory="decisions",
-    note_type="decision",
-    project="main"
-)
-```
-
----
-
-## Schemas
-
-Schemas define what a "good" note of a particular type should contain. They formalize observation categories and relation types so you can validate notes against a consistent structure. Schemas are optional — you can use Basic Memory without ever defining one — but they help maintain consistency as a knowledge base grows and give you a guide for creating well-structured notes.
-
-A schema is just a regular note with `type: schema` in frontmatter:
-
-```yaml
----
-title: Person
-type: schema
-entity: person
-version: 1
-schema:
-  name: string, full legal name
-  role?: string, current job title
-  works_at?: Organization, primary employer
-  expertise?(array, areas of knowledge): string
-settings:
-  validation: warn
----
-```
-
-Fields without `?` are required. Fields with `?` are optional. Capitalized types like `Organization` indicate entity references (wiki-link relations). Array fields expect multiple observations of the same category.
-
-### Schema tools
-
-Three tools are available for working with schemas:
-
-- **`schema_infer`** — Analyze existing notes of a type and suggest a schema based on common patterns. Use this when the user wants to create a schema from their existing notes.
-- **`schema_validate`** — Check notes against their schema. Pass `note_type` to validate all notes of a type, or `identifier` to validate a single note.
-- **`schema_diff`** — Compare a schema against actual note usage to detect drift. Shows which fields are defined but unused, and which undeclared fields appear in practice.
-
-### Creating notes with schemas
-
-When a schema exists for a note type, use it as a creation guide:
-
-1. **Look up the schema** before creating a note of a known type:
-
-```python
-# Check what fields a "person" note should have
-schema = await schema_infer(note_type="person")
-```
-
-2. **Create the note** following the schema's field definitions:
-
-```python
-await write_note(
-    title="Grace Hopper",
-    content="""# Grace Hopper
-
-## Observations
-- [name] Grace Hopper
-- [role] Computer Scientist and Navy Admiral
-- [expertise] Compiler design
-- [expertise] Programming languages
-
-## Relations
-- works_at [[US Navy]]
-- works_at [[Harvard University]]
-""",
-    directory="people",
-    note_type="person",
-    metadata={"status": "historical"},
-    project="main"
-)
-```
-
-3. **Validate** after creation to confirm conformance:
-
-```python
-result = await schema_validate(identifier="people/grace-hopper", project="main")
-```
-
-### Discovering and evolving schemas
-
-Users may ask you to help create or refine schemas. The typical workflow:
-
-```python
-# 1. Infer a schema from existing notes
-schema = await schema_infer(note_type="meeting", project="main")
-
-# 2. Review the suggested schema with the user, then write it
-await write_note(
-    title="Meeting",
-    content="...",  # schema frontmatter + description
-    directory="schemas",
-    note_type="schema",
-    project="main"
-)
-
-# 3. Validate existing notes against the new schema
-results = await schema_validate(note_type="meeting", project="main")
-
-# 4. Later, check for drift as note patterns evolve
-drift = await schema_diff(note_type="meeting", project="main")
-```
-
-### Using `note_type` and `metadata`
-
-The `note_type` parameter sets the `type` frontmatter field, which controls schema resolution and search filtering. Use it whenever creating notes of a specific type:
-
-```python
-await write_note(
-    title="Sprint Planning 2026-02-15",
-    content="...",
-    directory="meetings",
-    note_type="meeting",
-    metadata={"sprint": 12, "team": "backend"},
-    project="main"
-)
-```
-
-The `metadata` parameter accepts any key-value pairs that get merged into the note's frontmatter. Use it for custom fields like `status`, `priority`, `due_date`, or `team` — these become searchable via `metadata_filters` in `search_notes`.
-
-See the full [Schema System](/concepts/schema-system) guide for syntax details and validation modes.
-
----
-
-## Best Practices
-
-### 1. Project Discovery
-
-Always start with discovery:
-
-```python
-# First action in conversation
-projects = await list_memory_projects()
-
-# Ask user which to use
-# Store for session
-# Use consistently
-```
-
-### 2. Rich Knowledge Graphs
-
-**Every note should have:**
-- Clear, descriptive title
-- 3-5 observations minimum
-- 2-3 relations minimum
-- Appropriate categories and tags
-
-**Good structure:**
-
-```bash
----
-title: Clear Descriptive Title
-tags: [relevant, tags]
-type: note
----
-
-# Title
-
-## Context
-Brief background
-
-## Observations
-- [category] Specific fact #tag1 #tag2
-- [category] Another fact #tag3
-- [category] Third fact #tag4
-
-## Relations
-- relation_type [[Related Entity 1]]
-- relation_type [[Related Entity 2]]
-```
-
-### 3. Search Before Creating
-
-Always search first to avoid duplicates. `write_note` returns an error if a note already exists at the target path, so searching first prevents failed writes and lets you choose the right tool:
-
-```python
-# Before writing new note
-existing = await search_notes(
-    query="topic name",
-    project="main"
-)
-
-if existing["total"] > 0:
-    # Update existing with edit_note
-    await edit_note(
-        identifier=existing["results"][0]["permalink"],
-        operation="append",
-        content=new_information,
-        project="main"
-    )
-else:
-    # Create new
-    await write_note(...)
-```
-
-### 4. Exact Entity Titles in Relations
-
-Use exact titles when creating relations:
-
-```python
-# Search for exact title
-results = await search_notes(query="Authentication System", project="main")
-exact_title = results["results"][0]["title"]
-
-# Use in relation
-content = f"## Relations\n- relates_to [[{exact_title}]]"
-```
-
-### 5. Meaningful Categories and Relations
-
-**Use semantic categories:**
-- `[decision]` for choices made
-- `[fact]` for objective information
-- `[technique]` for methods
-- `[requirement]` for needs
-- `[insight]` for realizations
-
-**Use specific relation types:**
-- `implements` for implementation
-- `requires` for dependencies
-- `part_of` for hierarchy
-- `extends` for enhancement
-- `contrasts_with` for alternatives
-
-**Avoid generic:** Don't overuse `relates_to` - be specific about relationships.
-
-### 6. Progressive Elaboration
-
-Build knowledge over time:
-
-```python
-# Session 1: Create foundation
-await write_note(
-    title="Topic",
-    content="Basic structure with initial observations",
-    directory="notes",
-    project="main"
-)
-
-# Session 2: Add details
-await edit_note(
-    identifier="Topic",
-    operation="append",
-    content="Additional observations",
-    project="main"
-)
-
-# Session 3: Add relations
-await edit_note(
-    identifier="Topic",
-    operation="append",
-    content="Relations to related topics",
-    project="main"
-)
-```
-
-### 7. Consistent Organization
-
-**Folder structure:**
-- `specs/` - Specifications
-- `decisions/` - Decision records
-- `meetings/` - Meeting notes
-- `conversations/` - AI conversations
-- `implementations/` - Code/implementations
-- `docs/` - Documentation
-
-### 8. Confirm Destructive Actions
-
-Always ask before calling `delete_note` or `move_note` on folders.
-
-::note
-When in doubt, create a snapshot (Cloud) or suggest a backup (Local).
-::
-
----
-
-## Error Handling
-
-### Note Already Exists
-
-The most common error. `write_note` returns an error when a note already exists at the target path. This is intentional — it prevents accidental overwrites.
-
-**Solution:**
-```python
-# Option 1: Update the existing note incrementally
-await edit_note(
-    identifier="existing-note-path",
-    operation="append",
-    content="New content to add",
-    project="main"
-)
-
-# Option 2: Explicitly replace the note
-await write_note(
-    title="Topic",
-    content="Completely new content",
-    directory="notes",
-    overwrite=True,
-    project="main"
-)
-```
-
-### Missing Project Parameter
-
-**Solution:**
-```python
-try:
-    results = await search_notes(query="test")
-except:
-    projects = await list_memory_projects()
-    # Ask user which to use
-    results = await search_notes(query="test", project="main")
-```
-
-### Entity Not Found
-
-**Solution:**
-```python
-try:
-    note = await read_note("Nonexistent Note", project="main")
-except:
-    results = await search_notes(query="Note", project="main")
-    # Suggest alternatives to user
-```
-
-### Forward References
-
-**Not an error:** Forward references resolve automatically when targets are created. No action needed.
-
----
-
-## Tool Reference
-
-### Content Management
-
-| Tool | Purpose |
-|------|---------|
-| `write_note` | Create new markdown notes (errors on existing path unless `overwrite=True`) |
-| `read_note` | Read notes with knowledge graph context |
-| `edit_note` | Edit notes incrementally |
-| `move_note` | Move notes to new locations |
-| `delete_note` | Delete notes from knowledge base |
-| `view_note` | View notes as formatted artifacts |
-| `read_content` | Read raw file content |
-
-### Knowledge Graph Navigation
-
-| Tool | Purpose |
-|------|---------|
-| `build_context` | Navigate knowledge graph |
-| `recent_activity` | Get recent changes |
-| `list_directory` | Browse directory contents |
-
-### Search & Discovery
-
-| Tool | Purpose |
-|------|---------|
-| `search_notes` | Search across knowledge base (text, vector, hybrid modes) |
-
-### Schema Tools
-
-| Tool | Purpose |
-|------|---------|
-| `schema_validate` | Validate notes against schema definitions |
-| `schema_infer` | Analyze notes and suggest schema patterns |
-| `schema_diff` | Detect drift between schema and actual usage |
-
-### Project Management
-
-| Tool | Purpose |
-|------|---------|
-| `list_memory_projects` | List all available projects |
-| `create_memory_project` | Create new project |
-| `delete_project` | Delete project from configuration |
-| `list_workspaces` | List available cloud workspaces |
-
-### Visualization
-
-| Tool | Purpose |
-|------|---------|
-| `canvas` | Create Obsidian canvas |
-
----
-
-## Next Steps
-
-:::card-group
-::card
----
-title: MCP Tools Reference
-icon: i-lucide-wrench
-to: /reference/mcp-tools-reference
----
-Complete tool documentation with parameters and examples.
-::
-
-::card
----
-title: Knowledge Format
-icon: i-lucide-file-text
-to: /concepts/knowledge-format
----
-Understanding the note structure and semantic patterns.
-::
-:::
diff --git a/content/9.reference/7.docker.md b/content/9.reference/7.docker.md
deleted file mode 100644
index 1401e79..0000000
--- a/content/9.reference/7.docker.md
+++ /dev/null
@@ -1,247 +0,0 @@
----
-title: Docker
-description: Run Basic Memory in Docker containers for server deployments and SSE transport
----
-::warning
-The Docker image runs Basic Memory as an **SSE server** on port 8000. This is designed for server deployments where clients connect over HTTP, not for local MCP stdio connections with Claude Desktop.
-::
-
-## Overview
-
-Basic Memory provides official Docker images published to GitHub Container Registry. The container runs the MCP server with SSE (Server-Sent Events) transport, suitable for:
-
-- Server deployments where multiple clients connect remotely
-- Kubernetes or Docker Compose orchestration
-- CI/CD environments
-- Development and testing
-
-For local use with Claude Desktop or other MCP clients that use stdio transport, we recommend installing via [Homebrew](/local/local-install) or [pip](/local/local-install).
-
-## Quick Start
-
-### Pull the Image
-
-```bash
-docker pull ghcr.io/basicmachines-co/basic-memory:latest
-```
-
-### Run the Container
-
-```bash
-docker run -d \
---name basic-container \
--p 8000:8000 \
--v ~/basic-memory-data:/app/data \
-ghcr.io/basicmachines-co/basic-memory:latest
-```
-
-The server will be available at `http://localhost:8000/mcp`.
-
-::note
-The `-v` flag mounts a local directory for persistent storage. Without it, your data will be lost when the container stops.
-::
-
-## Image Details
-
-### Registry
-
-Images are published to GitHub Container Registry (GHCR):
-
-```
-ghcr.io/basicmachines-co/basic-memory
-```
-
-### Available Tags
-
-| Tag | Description |
-|-----|-------------|
-| `latest` | Latest stable release |
-| `0.19.0` | Specific version |
-| `0.19` | Latest patch for minor version |
-
-### Architectures
-
-Multi-platform images are available for:
-- `linux/amd64` (Intel/AMD)
-- `linux/arm64` (Apple Silicon, ARM servers)
-
-Docker automatically pulls the correct architecture for your platform.
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Path to Basic Memory data |
-| `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for projects |
-
-### Volume Mounts
-
-Mount a local directory to persist data:
-
-```bash
-docker run -d \
--v /path/to/local/data:/app/data \
--p 8000:8000 \
-ghcr.io/basicmachines-co/basic-memory:latest
-```
-
-### Port Configuration
-
-The container exposes port 8000 by default. Map to a different host port if needed:
-
-```bash
-docker run -d \
--p 3000:8000 \
-ghcr.io/basicmachines-co/basic-memory:latest
-```
-
-## Docker Compose
-
-For more complex setups, use Docker Compose:
-
-```yaml
-version: '3.8'
-
-services:
-basic-container:
-image: ghcr.io/basicmachines-co/basic-memory:latest
-container_name: basic-container
-ports:
-- "8000:8000"
-volumes:
-- ./data:/app/data
-environment:
-- BASIC_MEMORY_HOME=/app/data/basic-memory
-restart: unless-stopped
-healthcheck:
-test: ["CMD", "basic-memory", "--version"]
-interval: 30s
-timeout: 10s
-retries: 3
-```
-
-Run with:
-
-```bash
-docker compose up -d
-```
-
-## Connecting to the Server
-
-### MCP SSE Configuration
-
-Configure your MCP client to connect via SSE transport:
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "transport": {
-      "type": "sse",
-      "url": "http://localhost:8000/mcp"
-      }
-    }
-  }
-}
-```
-
-### Health Check
-
-Verify the server is running:
-
-```bash
-curl http://localhost:8000/health
-```
-
-Or check container health:
-
-```bash
-docker inspect --format='{{.State.Health.Status}}' basic-container
-```
-
-## Running CLI Commands
-
-You can run Basic Memory CLI commands inside the container. Note that the first argument is the container name (`basic-container`) and the second is the CLI command (`basic-memory`):
-
-```bash
-# Check version
-docker exec basic-container basic-memory --version
-
-# Check status
-docker exec basic-container basic-memory status
-
-# List projects
-docker exec basic-container basic-memory project list
-```
-
-## Security
-
-The container runs as a non-root user (`appuser`) for security. Key security features:
-
-- Non-root execution (UID/GID 1000 by default)
-- No unnecessary packages installed
-- Health checks enabled
-- Slim base image (Python 3.12 slim-bookworm)
-
-### Custom UID/GID
-
-Build with custom user IDs for permission compatibility:
-
-```bash
-docker build --build-arg UID=1001 --build-arg GID=1001 -t basic-memory:custom .
-```
-
-## Troubleshooting
-
-### Permission Denied Errors
-
-If you see permission errors with mounted volumes:
-
-```bash
-# Fix ownership on host
-sudo chown -R 1000:1000 /path/to/local/data
-
-# Or run with matching UID
-docker run --user $(id -u):$(id -g) ...
-```
-
-### Container Exits Immediately
-
-Check the logs:
-
-```bash
-docker logs basic-container
-```
-
-Common causes:
-- Port 8000 already in use
-- Volume mount path doesn't exist
-- Insufficient permissions
-
-### SSE vs Stdio Transport
-
-::warning
-The Docker image is configured for SSE transport only. It cannot be used as a stdio MCP server for Claude Desktop directly.
-::
-
-For Claude Desktop integration, either:
-1. Install Basic Memory locally via Homebrew or pip
-2. Use the SSE transport configuration (if your Claude Desktop version supports it)
-
-## Building from Source
-
-Clone the repository and build locally:
-
-```bash
-git clone https://github.com/basicmachines-co/basic-memory.git
-cd basic-memory
-docker build -t basic-memory:local .
-```
-
-## See Also
-
-- [Getting Started](/start-here/getting-started) - Local installation options
-- [CLI Reference](/reference/cli-reference) - Command line interface
-- [MCP Tools Reference](/reference/mcp-tools-reference) - Available MCP tools
diff --git a/content/9.reference/9.v0.19-migration.md b/content/9.reference/9.v0.19-migration.md
deleted file mode 100644
index 28ce8d4..0000000
--- a/content/9.reference/9.v0.19-migration.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: v0.19.0 Migration Guide
-description: Configuration and behavior changes when upgrading from v0.18 to v0.19.
----
-
-This guide covers configuration and behavior changes when upgrading from v0.18 to v0.19. For a user-friendly overview of new features, see [What's New in v0.19.0](/whats-new/v0.19.0).
-
----
-
-## `write_note` is non-destructive by default
-
-`write_note` no longer silently overwrites existing notes. If a note already exists at the target path, the tool returns an error instead of replacing it.
-
-| | Before (v0.18) | After (v0.19) |
-|---|---|---|
-| Writing to an existing path | Silently overwrites | Returns an error |
-| Explicit overwrite | Not needed | Pass `overwrite=True` |
-| Incremental edits | `write_note` or `edit_note` | Use `edit_note` |
-
-This prevents accidental data loss when an AI assistant writes a note without realizing one already exists.
-
-**Restore old behavior:** Set `write_note_overwrite_default: true` in `~/.basic-memory/config.json`.
-
----
-
-## Semantic search enabled by default
-
-Semantic search is now on out of the box. Embeddings are generated automatically on first startup — no opt-in or manual setup required. If `sqlite-vec` fails to load, search gracefully falls back to text-only mode.
-
-| | Before (v0.18) | After (v0.19) |
-|---|---|---|
-| `semantic_search_enabled` | `false` | `true` |
-| Embedding generation | Manual | Automatic on first startup |
-| Install size | Smaller (no embedding deps) | Larger (includes fastembed) |
-
-::note
-After upgrading to v0.19, run `bm reindex --embeddings` to generate vector embeddings for semantic search. This is a one-time operation for local projects. Cloud projects handle embedding generation automatically.
-::
-
-**Restore old behavior:** Set `semantic_search_enabled: false` in config, or set `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false`.
-
----
-
-## Frontmatter added on sync
-
-Files without YAML frontmatter (the metadata block at the top of a note) now get it added automatically during sync. This ensures all notes have proper metadata for search, permalinks, and schema resolution.
-
-| | Before (v0.18) | After (v0.19) |
-|---|---|---|
-| `ensure_frontmatter_on_sync` | `false` | `true` |
-| Files without frontmatter | Left untouched | Frontmatter injected |
-
-**Restore old behavior:** Set `ensure_frontmatter_on_sync: false` in config.
-
----
-
-## Project-prefixed permalinks
-
-Generated permalinks (permanent links to notes) now include the project slug by default, making cross-project references unambiguous.
-
-| | Before (v0.18) | After (v0.19) |
-|---|---|---|
-| `permalinks_include_project` | `false` | `true` |
-| Example permalink | `docs/authentication` | `main/docs/authentication` |
-
-Existing permalinks without a project prefix still resolve correctly — resolution tries project-prefixed first, then falls back to bare path.
-
-**Restore old behavior:** Set `permalinks_include_project: false` in config.
-
----
-
-## `build_context` defaults to JSON output
-
-`build_context` now returns JSON by default instead of text. The JSON response strips redundant fields for smaller, faster responses. All other tools still default to `"text"`.
-
-| | Before (v0.18) | After (v0.19) |
-|---|---|---|
-| `build_context` default format | `"text"` | `"json"` |
-| Other tools default format | `"text"` | `"text"` (unchanged) |
-
-**Get text output:** Pass `output_format="text"` explicitly.
-
----
-
-## `default_project_mode` removed
-
-The `default_project_mode` setting is no longer used. Use `default_project` as the fallback when no project is explicitly passed to a tool or command. Per-project routing (`set-cloud` / `set-local`) replaces the global mode toggle.
-
----
-
-## Project config format changed
-
-Project configuration now uses structured entries with `path`, `mode`, and sync metadata. Legacy config formats (string-valued `projects`, `project_modes`, `cloud_projects`) are migrated automatically when Basic Memory loads your config and re-saved in the new format.
-
-```json
-// Before (v0.18)
-{
-  "projects": {
-    "main": "/Users/you/basic-memory"
-  }
-}
-
-// After (v0.19)
-{
-  "projects": {
-    "main": {
-      "path": "/Users/you/basic-memory",
-      "mode": "local"
-    }
-  }
-}
-```
-
-Legacy configuration keys (`project_modes`, `cloud_projects`, `default_project_mode`) can be safely removed from your config file after migration.
diff --git a/content/index.md b/content/index.md
deleted file mode 100644
index 5535307..0000000
--- a/content/index.md
+++ /dev/null
@@ -1,163 +0,0 @@
----
-seo:
-  title: Basic Memory
-  description: AI and humans working together to build knowledge that gets smarter over time
----
-
-::u-page-hero
----
-orientation: horizontal
-class: py-0
----
-
-#title
-AI memory that grows with you.
-
-#description
-Build persistent knowledge that both you and AI can read, write, and enhance together. 
-Learn how it works.
-See why your AI needs Basic Memory.
-
-#links
-  :::u-button
-  ---
-  color: neutral
-  size: xl
-  to: start-here/what-is-basic-memory
-  trailing-icon: i-lucide-arrow-right
-  ---
-  Get started
-  :::
-
-  :::u-button
-  ---
-  color: neutral
-  icon: simple-icons-github
-  size: xl
-  to: https://github.com/basicmachines-co/basic-memory
-  variant: outline
-  ---
-  Star on GitHub
-  :::
-
-#headline
-  :::u-button
-  ---
-  size: sm
-  to: /whats-new/v0.22.0
-  variant: outline
-  ---
-  v0.22 →
-  :::
-
-#default
-![Basic Memory](/computer.png)
-::
-
-::u-page-section
----
-class: pt-0
----
-  :::u-page-grid
-    ::::u-page-card
-    ---
-    title: See into the black box
-    description: Every piece of AI context is a file you can read and edit. No mystery, no lock-in—just plain Markdown you own forever.
-    class: lg:col-span-1
-    spotlight: true
-    ---
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Knowledge that compounds
-    description: Unlike chat history that disappears, Basic Memory creates a semantic knowledge graph. Every note connects to related ideas, revealing patterns and insights that grow smarter over time.
-    class: lg:col-span-2
-    spotlight: true
-    ---
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Works with your AI assistant
-    description: Connect to Claude, ChatGPT, Gemini, Cursor, VS Code, and more via the Model Context Protocol. Your AI assistant reads your entire knowledge history instantly.
-    class: lg:col-span-2
-    spotlight: true
-    ---
-    ![MCP Integration with Claude](/screenshots/claude/create-first-note.png)
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Your web editor for knowledge
-    description: Write and organize notes from any browser. Search your knowledge, make connections, and watch your ideas grow—no installation required.
-    class: lg:col-span-1
-    spotlight: true
-    ---
-    :::theme-image{light="/screenshots/cloud-app/v2-edit-mode-light.png" dark="/screenshots/cloud-app/v2-edit-mode-dark.png" alt="Web editor"}
-    :::
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Cloud or local
-    description: Start with Basic Memory Cloud for instant access from any browser, or run locally on your machine. Sync between them, or keep everything offline—your choice.
-    class: lg:col-span-1
-    icon: i-lucide-cloud
-    to: /start-here/quickstart-cloud
-    ---
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Plain Markdown
-    description: Human-readable files, not proprietary formats. Your knowledge works in Obsidian, VS Code, or any text editor. Export, backup, or migrate anytime.
-    class: lg:col-span-2
-    icon: i-lucide-file-text
-    ---
-    ```markdown
-    ---
-    title: Project Ideas
-    tags: [ideas, projects]
-    ---
-
-    ## Observations
-    - [insight] AI collaboration improves over time #growth
-
-    ## Relations
-    - relates_to [[AI Tools]]
-    - builds_on [[Past Research]]
-    ```
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Open source
-    description: Basic Memory is fully open source. Run locally, self-host, contribute, or just explore the code. Your knowledge, your rules.
-    class: lg:col-span-1
-    icon: i-simple-icons-github
-    to: https://github.com/basicmachines-co/basic-memory
-    ---
-    ::::
-
-    ::::u-page-card
-    ---
-    title: AI-friendly docs
-    description: This documentation is optimized for AI consumption with llms.txt support and content negotiation. AI assistants can read these docs directly.
-    class: lg:col-span-1
-    icon: i-lucide-bot
-    to: /reference/llms-txt
-    ---
-    ::::
-
-    ::::u-page-card
-    ---
-    title: Ready to start?
-    description: Create your first note in under 2 minutes. Build AI memory that actually remembers.
-    class: lg:col-span-1
-    spotlight: true
-    to: /start-here/quickstart-cloud
-    ---
-    ::::
-  :::
-::
diff --git a/docs/docs-audit.md b/docs/docs-audit.md
new file mode 100644
index 0000000..b90b8ba
--- /dev/null
+++ b/docs/docs-audit.md
@@ -0,0 +1,146 @@
+# Basic Memory Docs Audit
+
+Last updated: 2026-06-09
+
+## Purpose
+
+This file tracks the docs overhaul as a product audit. A page is not "done" because it reads well; it is done when current product behavior, source code, screenshots, and positioning agree.
+
+## Source Of Truth
+
+| Area | Primary source | Verification notes |
+|---|---|---|
+| Messaging | basicmemory.com, product notes, Drew/Paul decisions | Current public website uses "One knowledge base for you, your AI tools, and your team" and emphasizes plain Markdown, MCP, Cloud, open source, and teams. Avoid "just expanding memory" framing. |
+| Cloud app | Live app at app.basicmemory.com | Verify settings, onboarding, workspace switcher, import, sharing, snapshots, file history, themes, and billing in the browser. |
+| Collaboration | Live app invite/member flows, product notes | Verify owner and recipient flows, roles, seats, billing behavior, project access, and shared AI access. |
+| CLI | basic-memory source and command help | Verify commands, flags, defaults, routing, update behavior, imports, schema commands, and local paths. |
+| MCP tools | basic-memory source/tool schemas | Verify tool names, parameters, aliases, output behavior, Cloud/local parity, and ChatGPT compatibility tools. |
+| Integrations | Official client docs plus live Basic Memory behavior | Verify remote MCP/OAuth versus local stdio setup for each client. Remove unsupported clients/workarounds. |
+| Screenshots | Live app/browser captures plus `docs/screenshots.json` | Every screenshot should record source screen, capture date, theme, and owning docs page. |
+| Pricing/limits | Live app checkout, Polar/product config, public website | Treat as high-stale-risk. Do not hard-code pricing or limits without verification. |
+
+## Status Key
+
+| Status | Meaning |
+|---|---|
+| Verified | Checked against current source of truth in this overhaul. |
+| Needs audit | Plausible, but not yet verified deeply enough. |
+| Needs rewrite | Known stale, incomplete, misleading, or too thin. |
+| Needs screenshots | Text may be fine, but UI proof/capture is missing or stale. |
+| Archive candidate | Historical or release-specific; should not sit in current docs nav unless intentionally preserved. |
+
+## Priority Queue
+
+1. **Integrations batch** — verify client-by-client against official current behavior and Basic Memory source.
+2. **Screenshots** — resolve unreferenced screenshot warnings and snapshot-list image transform warning.
+3. **How-to guides** — shorten or rewrite as durable workflows, not old marketing/tutorial sprawl.
+4. **Historical release pages** — keep release material under What's New/changelog/archive, not current reference unless still useful.
+
+## Coverage Checklist
+
+| User job | Current home | Status | Notes |
+|---|---|---|---|
+| Understand what Basic Memory is | `/start-here/what-is-basic-memory` | Needs audit | Messaging mostly aligned; verify examples cover documents, workflows, research, software, and creative projects. |
+| Start with Cloud | `/start-here/quickstart-cloud` | Needs audit | Check live onboarding, pricing/seat language, screenshot, and team invite mention. |
+| Start locally | `/start-here/quickstart-local` | Verified | First pass checked against README/source. |
+| Decide Cloud vs Open Source | Missing dedicated page | Needs rewrite | Add "Cloud or Open Source?" or equivalent; link from homepage and both quickstarts. |
+| Use docs with an AI agent | `/reference/llms-txt`, `/llms.txt`, `/llms-full.txt` | Verified | Endpoints return real content locally. Homepage links to explanation page. |
+| Connect an AI tool | `/integrations/*` | Needs audit | Must distinguish Cloud remote MCP/OAuth from local `uvx basic-memory mcp`. |
+| Invite/collaborate with a team | `/teams/about`, `/teams/join-a-team` | Needs screenshots | Text rewritten, but live invite/recipient flow still needs final verification. |
+| Import existing knowledge | `/cloud/web-app#import-data` | Needs audit | Verify current import UI and supported sources. |
+| Sync local files with Cloud | `/cloud/cloud-sync`, `/cloud/edit-locally-and-in-the-app` | Needs audit | Verify current CLI behavior and local/cloud routing. |
+| Use Cloud from the terminal | `/cloud/cloud-cli` | Verified | Added short command-line guide backed by current CLI source and cross-linked from Cloud onboarding/reference pages. |
+| Recover notes | `/cloud/restore-lost-content`, `/cloud/cloud-snapshots`, `/cloud/file-history` | Needs screenshots | Build logs one Cloud Snapshot image transform warning. |
+| Contact support | `/reference/contact-support` | Verified | Uses public `hello@basicmemory.com` contact path and separates private support from Discord/GitHub. |
+| Use schemas | `/concepts/schema-system`, `/concepts/metadata-search` | Needs audit | Schema page appears substantial; verify examples against current schema commands/tools. |
+| Understand observations/relations | `/concepts/observations-and-relations` | Verified | Rewritten in this audit pass; verify against parser/source during MCP reference audit. |
+| Troubleshoot MCP/install/sync | `/reference/troubleshooting` | Verified | Rewritten around Cloud MCP, Cloud app, local MCP, sync/routing, search/content, config, logs. |
+
+## Page Register
+
+| Area | Page | Status | Action |
+|---|---|---|---|
+| Home | `/` | Verified | New task-first homepage. Add Cloud/Open Source decision page link when created. |
+| Get Started | `/start-here/what-is-basic-memory` | Needs audit | Check examples and remove any narrow "AI memory only" framing. |
+| Get Started | `/start-here/quickstart-cloud` | Needs audit | Verify onboarding, current pricing language, MCP endpoint, and screenshot. |
+| Get Started | `/start-here/quickstart-local` | Verified | Keep concise; revisit after CLI reference audit. |
+| Get Started | `/start-here/getting-started` | Verified | Cloud terminal guidance now points to Cloud CLI; skills framing distinguishes MCP tool access from optional usage patterns. |
+| What's New | `/whats-new/teams` | Needs audit | Verify role/seat copy; keep release-specific framing out of evergreen Teams docs. |
+| What's New | `/whats-new/v0.21.0` | Archive candidate | Confirm patch-release notes belong here, not current nav/reference. |
+| What's New | `/whats-new/hermes-plugin` | Needs audit | Verify install command and feature list. |
+| What's New | `/whats-new/cloud` | Archive candidate | Keep as release/news if still accurate. |
+| What's New | `/whats-new/changelog` | Verified | Simple redirect/explanation. |
+| What's New | `/whats-new/agent-skills` | Needs audit | Verify whether release/news page should mirror current 10-skill list or stay historical. |
+| What's New | `/whats-new/openclaw-plugin` | Needs audit | Verify install command and feature list. |
+| What's New | `/whats-new/ai-friendly-docs` | Verified | Mirrors AI-friendly reference. |
+| Cloud | `/cloud/cloud-guide` | Verified | Cloud CLI and Contact Support are now surfaced; still keep feature claims tied to current Cloud pages. |
+| Cloud | `/cloud/web-app` | Needs screenshots | Verify all settings sections and screenshots. |
+| Cloud | `/cloud/cloud-sync` | Needs audit | Verify commands, routing, and sync statuses. |
+| Cloud | `/cloud/cloud-cli` | Verified | New short guide for terminal workflows; snapshot commands corrected against source. |
+| Cloud | `/cloud/cloud-snapshots` | Needs screenshots | Verify UI/CLI, retention claims, and image warning. |
+| Cloud | `/cloud/web-app#themes` | Verified | Themes folded into Web App settings with current screenshot; `/cloud/themes` redirects here. |
+| Cloud | `/cloud/api-keys` | Verified | Source-backed pass against current CLI API-key behavior; reduced client-specific config, clarified `bmc_` format, bearer usage, OAuth/API-key tradeoffs, and explicit per-project routing. |
+| Cloud | `/cloud/routing` | Verified | Source-backed pass against current `get_client`, routing flags, project mode, workspace default, `set-cloud`, and `set-local` behavior; removed stale global Cloud mode claims. |
+| Cloud | `/cloud/shared-notes` | Verified | Current screenshots present; tightened public-link safety language, removed unverified `/raw` claim, and linked support for accidental private sharing. |
+| Cloud | `/cloud/edit-locally-and-in-the-app` | Needs audit | Verify CLI/sync setup and cross-link with Cloud Sync. |
+| Cloud | `/cloud/restore-lost-content` | Needs audit | Verify recovery decision tree and current UI labels. Visible title is "Recover Notes." |
+| Cloud | `/cloud/file-history` | Needs screenshots | Verify UI, permissions, and retention behavior. |
+| Collaboration | `/teams/about` | Needs screenshots | Verify live owner flow, roles, seats, project visibility. |
+| Collaboration | `/teams/join-a-team` | Needs screenshots | Verify recipient invite flow. |
+| Collaboration | `/teams/copy-between-workspaces` | Needs audit | Verify copy/export/import options and avoid overpromising. |
+| Open Source | `/local/local-install` | Verified | First pass checked. Revisit after CLI reference audit. |
+| Open Source | `/local/cli-basics` | Verified | First pass checked. Revisit after CLI reference audit. |
+| Open Source | `/local/mcp-tools-local` | Verified | First pass checked. Revisit after MCP reference audit. |
+| Concepts | `/concepts/vs-built-in-memory` | Needs audit | Verify current built-in memory claims for Claude/ChatGPT/Cursor. |
+| Concepts | `/concepts/knowledge-format` | Needs audit | Check duplication and align with schema/obs-rel pages. |
+| Concepts | `/concepts/projects-and-folders` | Needs audit | Verify local/cloud project examples and project-prefixed permalinks. |
+| Concepts | `/concepts/observations-and-relations` | Verified | Rewritten from current Knowledge Format/MCP reference behavior. |
+| Concepts | `/concepts/memory-urls` | Needs audit | Verify current URL resolution behavior. |
+| Concepts | `/concepts/schema-system` | Needs audit | Verify picoschema examples and command names. |
+| Concepts | `/concepts/semantic-search` | Needs audit | Verify default embedding provider, config, and OpenAI provider guidance. |
+| Concepts | `/concepts/metadata-search` | Needs audit | Verify filters against current tool schema. |
+| Integrations | `/integrations/claude-desktop` | Needs audit | Verify official Claude connector flow and local deployment variant. |
+| Integrations | `/integrations/claude-code` | Needs audit | Verify CLI commands and Cloud/local variants. |
+| Integrations | `/integrations/chatgpt` | Needs audit | Verify current ChatGPT developer-mode/custom app flow. |
+| Integrations | `/integrations/gemini` | Needs audit | Verify official Gemini CLI MCP config. |
+| Integrations | `/integrations/codex` | Needs audit | Verify Codex app and CLI config, including desktop behavior. |
+| Integrations | `/integrations/cursor` | Needs audit | Verify Cursor MCP config and Cloud/local variants. |
+| Integrations | `/integrations/vscode` | Needs audit | Verify VS Code MCP configuration and direct Markdown editing guidance. |
+| Integrations | `/integrations/obsidian` | Needs audit | Verify Cloud/local wording; likely durable. |
+| Integrations | `/integrations/skills` | Verified | Checked against `basicmachines-co/basic-memory-skills` README; updated to 10 skills including `memory-literary-analysis`. |
+| Integrations | `/integrations/openclaw` | Needs audit | Verify package name and feature list. |
+| Integrations | `/integrations/hermes` | Needs audit | Verify package name and feature list. |
+| Guides | `/how-to/project-documentation` | Needs audit | Keep only if durable and useful; shorten if generic. |
+| Guides | `/how-to/writing-organization` | Needs audit | Good broader-use signal; check for outdated examples. |
+| Guides | `/how-to/research-learning` | Needs audit | Likely durable; tighten if needed. |
+| Guides | `/how-to/note-taking` | Needs audit | Check for old terminology and stale tool behavior. |
+| Guides | `/how-to/personal-knowledge` | Needs audit | Avoid over-indexing docs on personal memory use case. |
+| Reference | `/reference/cli-reference` | Verified | Source-backed pass against current CLI command modules; added status wait/full reindex, Team-safe pull/push guidance, upload flags, and missing `bm tool delete-note`. |
+| Reference | `/reference/mcp-tools-reference` | Verified | Source-backed pass against current MCP tool signatures; added `project_id`, current search aliases/categories, UI tools, and corrected workspace/list-project behavior. |
+| Reference | `/reference/ai-assistant-guide` | Needs audit | Make durable system-prompt guidance; link from quickstarts/getting-started. |
+| Reference | `/reference/technical-information` | Needs audit | Verify architecture, licensing, and source links. |
+| Reference | `/reference/troubleshooting` | Verified | Rewritten in this audit pass; stale `basic-memory sync` and old install assumptions removed. |
+| Reference | `/reference/contact-support` | Verified | New page for private account, billing, workspace, invitation, and Cloud data issues. |
+| Reference | `/reference/configuration` | Needs audit | Verify config keys and environment variables. |
+| Reference | `/reference/docker` | Verified | Rewritten against current Dockerfile, Compose files, default SSE transport, mounted knowledge/config volumes, and security caveats. |
+| Reference | `/reference/llms-txt` | Verified | Endpoints checked locally. |
+| Reference | `/reference/v0.19-migration` | Archive candidate | Keep historical; remove from current-reference prominence if distracting. |
+| Changelog | `/changelog` | Needs audit | Verify release feed/source. |
+
+## Automated Checks To Add Or Extend
+
+- Fail on broken internal links and missing assets.
+- Warn on orphaned screenshots with source metadata missing from `docs/screenshots.json`.
+- Warn on stale version literals outside `whats-new`, changelog, and migration/archive pages.
+- Warn on removed commands such as `basic-memory sync` unless in historical pages.
+- Warn on unsupported clients/features such as Claude Research if reintroduced.
+- Warn when content pages have no title or no body headings.
+
+## Working Rhythm
+
+1. Pick one batch from the priority queue.
+2. Verify source of truth.
+3. Rewrite or delete pages.
+4. Run `npm run check:docs`.
+5. Browser-review the affected routes.
+6. Update this audit status before moving on.
diff --git a/docs/review-findings.md b/docs/review-findings.md
new file mode 100644
index 0000000..747f6c8
--- /dev/null
+++ b/docs/review-findings.md
@@ -0,0 +1,1172 @@
+# Docs review findings — 2026-07-02
+
+Full-site review (66 pages + 4 cross-cutting checks, branch `docs-updates-2026-07`). **287 page findings** (158 incorrect / 34 redundant / 95 confusing; confidence: 135 high / 131 medium / 21 low) plus **32 cross-cutting findings**. Triage: check the box when fixed, strike through to reject.
+
+**Clean pages (2):** `2.writing-organization.md`, `10.contact-support.md`
+
+
+## Welcome
+
+
+### content/0.welcome.md
+
+- [x] **[confusing/medium]** "Pick your path" section — "Getting Started" card (lines 47-54) — The "Getting Started" card gives no hint that it leads to local-install-only content, and its title doesn't distinguish it from the two Quickstart cards next to it.
+  - *Evidence:* The card links to /local/getting-started with the description "Set up projects and choose where your notes are saved." The target page (content/5.local/2.getting-started.md) is entirely local: CLI `basic-memory project add`, editing ~/.basic-memory/config.json, `uv tool upgrade`/`brew upgrade`, restarting Claude Desktop — and it opens by routing readers back to the same two quickstart cards they just passed on the welcome page. A cloud-path reader (who was just told "no install required") clicking this card lands in local CLI configuration with no signpost.
+  - *Fix:* Scope the card so the local path is explicit, e.g. title "Set Up Local Projects" or description "After installing locally: create projects and choose where your notes are saved on disk." Alternatively move it under "Go deeper" so it doesn't compete with the Quickstart cards as an entry point.
+
+## Start Here
+
+
+### content/1.start-here/1.what-is-basic-memory.md
+
+- [x] **[incorrect/high]** MCP Integration > Compatible assistants (line 338: "ChatGPT (Pro/Max)") — "ChatGPT (Pro/Max)" names a nonexistent ChatGPT plan — Max is a Claude tier, and the docs' own ChatGPT integration page says MCP requires Plus or Pro.
+  - *Evidence:* content/7.integrations/3.chatgpt.md:52 — "**ChatGPT Plus or Pro subscription required.** MCP integration is not available on ChatGPT's free tier." ChatGPT has no Max plan.
+  - *Fix:* Change to "ChatGPT (Plus/Pro)" to match the integration page, or drop the parenthetical and let the ChatGPT integration page state the requirement.
+- [x] **[incorrect/high]** Seeing into the black box (line 248: "Audit trail - Every note has a history") — The claim that every note has a history is presented as universal, but per-note version history is a cloud-only feature; local installs have no built-in note history.
+  - *Evidence:* content/3.cloud/12.file-history.md — "File history is a cloud feature. Versions are created automatically on every save." No history feature exists in the local CLI source (src/basic_memory/cli/commands/).
+  - *Fix:* Scope the bullet, e.g. "Audit trail - In the cloud, every note keeps full version history (File History); locally, notes are plain files you can track with git." Or link to /cloud/file-history.
+- [x] **[incorrect/medium]** MCP Integration > Compatible assistants (line 341: "VS Code (with MCP extension)") — VS Code does not need an "MCP extension" — Copilot Chat supports MCP servers natively via VS Code settings, per the docs' own VS Code page.
+  - *Evidence:* content/7.integrations/7.vscode.md:131 — "VS Code's Copilot Chat now supports MCP servers. You can add Basic Memory as an MCP server in your VS Code settings..."
+  - *Fix:* Change to "VS Code (Copilot Chat)" or just "VS Code".
+- [x] **[confusing/medium]** MCP Integration > Available tools (line 332: "`list_memory_projects` - Manage projects") — The gloss "Manage projects" misdescribes the tool — it only lists projects; management (create/delete/switch) is done by other tools, so a reader gets the wrong idea of what this tool does.
+  - *Evidence:* src/basic_memory/mcp/tools/project_management.py:368 — docstring: "List all available projects with their status."
+  - *Fix:* Change the gloss to "List your projects" (or reference the project-management tool family separately).
+
+### content/1.start-here/2.quickstart-cloud.md
+
+- [x] **[incorrect/high]** Section "For ChatGPT", note callout (line 72) — The note says ChatGPT requires a "Pro or Max subscription" — Max is a Claude plan tier, not a ChatGPT one, and the dedicated ChatGPT integration page states the requirement differently.
+  - *Evidence:* content/7.integrations/3.chatgpt.md says "ChatGPT Plus or Pro subscription required. MCP integration is not available on ChatGPT's free tier." ChatGPT's paid tiers are Plus/Pro/Team/Enterprise; "Max" is Anthropic's Claude tier. The same wrong wording also appears in content/3.cloud/01.cloud-guide.md (line ~62), so it looks copy-pasted.
+  - *Fix:* Change to "ChatGPT requires a Plus or Pro subscription to use remote MCP servers" (matching the ChatGPT integration page), and fix the same callout in 3.cloud/01.cloud-guide.md.
+- [x] **[incorrect/high]** Section "For ChatGPT", step "Enable MCP" (line 77) — The setup path "Open Settings → Beta features and enable MCP" contradicts the dedicated ChatGPT integration page and reflects an outdated ChatGPT UI.
+  - *Evidence:* content/7.integrations/3.chatgpt.md documents the current path as "In ChatGPT, go to Settings > Developer > Custom MCP Servers"; there is no "Beta features" MCP toggle in current ChatGPT settings. Two different paths for the same action in the same docs site.
+  - *Fix:* Replace the three inline ChatGPT steps with the path from the integration page (Settings > Developer > Custom MCP Servers) or simply link to /integrations/chatgpt, which the quickstart currently never references.
+- [ ] **[redundant/high]** *(deferred: keeping quickstart + integration page; trim the cloud-guide copy when we reach the Cloud section)* Section "For Claude Desktop" (lines 36-67) — The five-step Claude connector setup (Settings → Claude → Connectors, Add custom connector, Authenticate, Configure Tools, Verify) is duplicated nearly verbatim on two other pages, and the copies have already drifted.
+  - *Evidence:* content/3.cloud/01.cloud-guide.md "Setup with Claude" contains the same 5 steps with the same wording; content/7.integrations/1.claude-desktop.md "Cloud Setup" is a third copy that has drifted (button label "Add connector" vs "Add custom connector", different screenshots, no Configure Tools step). Three maintained copies of one UI flow.
+  - *Fix:* Keep the full walkthrough in one canonical place (the Claude Desktop integration page), have the quickstart keep a minimal 2-3 step version or link out, and reconcile the drifted button label across pages.
+- [x] **[confusing/medium]** "For ChatGPT" section vs "For other assistants" list (lines 69-96) — The quickstart embeds inline ChatGPT setup steps but never links to the dedicated ChatGPT integration guide, while every other assistant gets a link — readers following the inline (outdated) steps never discover the correct, detailed page.
+  - *Evidence:* content/7.integrations/3.chatgpt.md exists with full, current setup instructions, but the "For other assistants" list (lines 92-96) only links Gemini, Cursor, VS Code, and Claude Code; the ChatGPT section links only a YouTube video.
+  - *Fix:* Add a link to /integrations/chatgpt in or after the ChatGPT steps, mirroring how the Claude section is backed by screenshots and the integrations pages.
+- [x] **[confusing/low]** "Example workflow" code block (lines 177-192) — The dialogue labels switch mid-example from "AI:" to "Claude:", which breaks the page's assistant-agnostic framing right after sections covering ChatGPT, Gemini, and others.
+  - *Evidence:* Line 180 uses "AI: [Creates note with observations and tags]" while lines 186 and 191 use "Claude: [Searches knowledge base...]" in the same conversation; the earlier example conversation (lines 134-144) consistently uses "AI:".
+  - *Fix:* Use one label ("AI:") consistently throughout the example workflow.
+
+### content/1.start-here/3.quickstart-local.md
+
+- [x] **[incorrect/high]** Useful CLI commands — line 259, "# Force re-sync all files" / `basic-memory sync` — `basic-memory sync` is not a command; the CLI has no top-level sync command and running it fails.
+  - *Evidence:* No `sync` registration exists in src/basic_memory/cli/ (all @app.command decorators checked: doctor, format, db, orphans, mcp, update, status, reset, reindex, watch, workspace; `sync` exists only under `bm cloud`). status.py:200-202 tells users to run 'bm reindex --project <name>' to index pending changes. Product truth: sync is automatic; index rebuild is `bm reindex`.
+  - *Fix:* Replace with `basic-memory reindex` (comment: "Rebuild the search index") or drop the entry entirely.
+- [x] **[incorrect/high]** Section 1, All platforms (uv) — Requirements note, line 45 — States "Python 3.13 or higher" but the actual floor is Python 3.12.
+  - *Evidence:* basic-memory pyproject.toml: requires-python = ">=3.12" (and pythonVersion = "3.12"). Product truth confirms Python floor 3.12.
+  - *Fix:* Change to "Python 3.12 or higher".
+- [x] **[incorrect/high]** Useful CLI commands — line 250, `basic-memory project info` — `basic-memory project info` is shown without arguments, but the command requires a project name and fails with a missing-argument error as written.
+  - *Evidence:* src/basic_memory/cli/commands/project.py:1360-1362: @project_app.command("info") with `name: str = typer.Argument(..., help="Name of the project")` — a required positional argument (also note the docstring's "current project" is stale; the command always needs a name).
+  - *Fix:* Show `basic-memory project info main` (or `<project-name>`).
+- [x] **[incorrect/medium]** Section 3, Verify the connection — line 91 — Instructs users to click the "tools icon (hammer) in the bottom-right"; current Claude Desktop no longer uses a hammer icon — MCP tools are listed under the "Search and tools" sliders icon in the chat input area.
+  - *Evidence:* The hammer icon was retired from Claude Desktop in 2025; the sibling page content/7.integrations/1.claude-desktop.md (line 31) avoids the hammer wording and just says "click the tools icon". Cannot be verified against product source (third-party UI), hence medium confidence — check the screenshot at /screenshots/claude/tools-menu-local.png against the current UI.
+  - *Fix:* Describe the current UI (e.g., "click the search-and-tools (sliders) icon in the chat input box") and refresh the screenshot if stale.
+- [x] **[confusing/medium]** Sections 1-2 flow: "macOS (Homebrew) - Recommended" then Configure Claude Desktop (uvx config), lines 24-83 — The recommended install path is Homebrew, but step 2's MCP config requires `uvx` — which Homebrew users never installed — and the ENOENT fix ("use the full path to uvx") cannot work for them because `which uvx` returns nothing.
+  - *Evidence:* The Homebrew formula installs the `basic-memory`/`bm` binaries directly (pyproject [project.scripts]); `uvx` only exists if the user separately installed uv (mentioned only under the alternative uv install path). A first-time reader following the recommended path hits ENOENT with no working remedy on the page.
+  - *Fix:* For Homebrew installs, show `"command": "basic-memory", "args": ["mcp"]` (or note that uvx requires uv and give the Homebrew alternative in the ENOENT warning).
+- [x] **[confusing/medium]** Customize your setup — "Skip project selection prompts", lines 228-237 — Tells single-project users to add `"default_project": "main"` to config.json to skip project prompts, but this is a no-op: the config auto-sets default_project to the first project ("main") when unset, and MCP tools already fall back to it — the promised behavior change never materializes.
+  - *Evidence:* src/basic_memory/config.py:778-789: when default_project is not explicitly provided it is set to the first available project; mcp/project_context.py resolve_project_parameter falls back to config.default_project (and then the projects API is_default flag) with no user prompt. The old `default_project_mode` toggle that governed prompting is now a stale key removed from configs (config.py:561-568).
+  - *Fix:* Either drop the section or reframe it for multi-project users ("set which project is used when none is specified"), matching the wording on /local/getting-started.
+- [x] **[redundant/medium]** Customize your setup + Skip project selection prompts, lines 214-237 — The change-notes-location commands (`project add` + `project default` + restart advice) and the `default_project` config.json snippet duplicate content on content/5.local/2.getting-started.md ("Choosing Where Notes Are Saved" and "For users who primarily work in one project") and on content/7.integrations/1.claude-desktop.md ("Project selection").
+  - *Evidence:* 5.local/2.getting-started.md lines 48-60 and 102-112 contain the same commands and an identical `{"default_project": "main"}` snippet with different framing ("default fallback project" vs this page's "skip project selection prompts") — the framings have already drifted.
+  - *Fix:* Keep the two commands here for quickstart completeness but link to /local/getting-started for the default-project config instead of restating it.
+- [x] **[redundant/medium]** Section 1 install commands + brew trust note + Section 2 MCP JSON, lines 26-79 — The Homebrew/uv install commands, the brew trust explanatory note (verbatim), and the claude_desktop_config.json snippet are duplicated word-for-word on content/5.local/1.local-install.md.
+  - *Evidence:* 5.local/1.local-install.md lines 10-41 contain the identical brew tap/trust/install block, the same brew-trust note text ("Recent Homebrew versions warn about untrusted taps, and Homebrew 6 will require..."), and the same uvx MCP config. Verbatim explanatory prose in two places is a drift risk (e.g., when Homebrew 6 ships, both must change).
+  - *Fix:* Make one page canonical: either have local-install link to the quickstart for the note text, or shorten the quickstart note to one line linking to /local/local-install.
+- [x] **[confusing/low]** Verify installation, line 54 — `bm update` — The page uses `basic-memory` everywhere but switches to `bm update` once without ever explaining that `bm` is an alias for `basic-memory`.
+  - *Evidence:* First and only use of `bm` on the page; the alias is only explained on /local/cli-basics ("`bm` is a short alias for `basic-memory`"). A first-time reader may think `bm` is a different tool.
+  - *Fix:* Use `basic-memory update`, or add "(`bm` is a short alias for `basic-memory`)".
+
+## What's New
+
+
+### content/2.whats-new/0.teams.md
+
+- [x] **[incorrect/medium]** "What you get" section, first bullet (line 16): "Three workspaces, side by side — local, personal cloud, and your team's shared workspace. Switch between them in the app..." — The bullet claims you can switch between all three workspaces — including local — "in the app," but the cloud web app is cloud-only and its workspace selector offers only Personal and team workspaces, not a Local entry.
+  - *Evidence:* The Teams guide (content/4.teams/1.about.md) describes the Local workspace as "No team features; runs entirely on your computer," and the web-app page (content/3.cloud/02.web-app.md) and join-a-team page describe only teams/personal cloud content in the app. Product UI labels are "Teams" and "Personal" — there is no Local workspace in the cloud app. Similarly, MCP's workspace parameter targets cloud workspaces only (local projects are reached via per-project routing, not workspace targeting).
+  - *Fix:* Scope the switching claim to the cloud workspaces, e.g.: "Switch between personal and team workspaces in the app; local projects stay on your machine and are reachable from the CLI and MCP alongside them."
+- [x] **[confusing/medium]** "Invite your team" section (line 24): "Promote, demote, deactivate, or hand off ownership at any time." — The sentence's implied subject is the preceding "Owners, admins, and user admins," implying admins and user admins can hand off ownership — but only the Owner can transfer ownership.
+  - *Evidence:* content/4.teams/1.about.md "Managing members": "Only the **owner** can: Transfer ownership... Rename the team." Role changes are also constrained (assignable only at or below your own rank), so lumping "hand off ownership" into the same breezy list misleads a first-time reader about who can do what.
+  - *Fix:* Split the capability: "Promote, demote, or deactivate members at any time — and owners can hand off ownership when needed."
+
+### content/2.whats-new/1.changelog.md
+
+- [x] **[incorrect/high]** v0.21 — Workspace-aware everywhere, '`bm orphan`' bullet (line 38) — The bullet gets the command name, its behavior, and its flags wrong: the command is `bm orphans` (plural), it lists entities that have no relations in the knowledge graph (unlinked notes), not 'entities whose underlying markdown files are gone', and it has no cleanup flag of any kind.
+  - *Evidence:* Source /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/cli/commands/orphans.py: `@app.command()` on `def orphans(...)` with docstring 'Show entities that have no relations in the knowledge graph. Orphan entities have no incoming or outgoing connections.' Its only options are --project, --json, --local, --cloud — no delete/clean flag, and git history of the file shows none ever existed. The docs' own CLI reference (content/9.reference/1.cli-reference.md, '### `bm orphans`', line 123) matches the source and contradicts this changelog bullet. v0.21.0 release notes PR #816 is 'add orphan entity command' for unlinked entities.
+  - *Fix:* Rewrite the bullet: '**`bm orphans`** — lists entities with no incoming or outgoing relations in the knowledge graph, useful for finding notes not yet linked to anything' (and drop the claim about a cleanup flag).
+- [x] **[confusing/medium]** v0.22 — Team-safe cloud push and pull, first paragraph, last sentence (line 14) — 'The mirror-style `sync` command remains personal-only' refers to `bm cloud sync` but names it only as 'sync', which a new reader can conflate with Basic Memory's automatic local file sync and misread as 'sync errors out on team workspaces'.
+  - *Evidence:* Elsewhere the docs stress that local sync is automatic and there is no `basic-memory sync` command; the gated command is specifically `bm cloud sync` (v0.22.0 CHANGELOG: 'The destructive `bm cloud sync` / `bm cloud bisync` mirrors are now gated to Personal workspaces').
+  - *Fix:* Name the command explicitly: 'The mirror-style `bm cloud sync` command remains personal-only and exits with an error on team workspaces.'
+- [x] **[confusing/low]** v0.22 section, v0.22.1 lead-in and bullet list (lines 18-25) — The lead-in says the patch 'focused on first-run reliability', but half the bullets that follow (MCP qualified project routes, search_notes comma-splitting, write_note workspace parameter) are unrelated to first runs, so the list doesn't match its framing.
+  - *Evidence:* The product CHANGELOG describes v0.22.1 more broadly: 'Fixes project and default-project resolution on fresh installs, MCP workspace routing, sync project selection, and CLI startup latency, plus a few MCP parity additions.'
+  - *Fix:* Broaden the lead-in, e.g. 'The v0.22.1 patch fixed first-run reliability and shipped a few MCP fixes and parity additions:'
+
+### content/2.whats-new/3.hermes-plugin.md
+
+- [x] **[confusing/medium]** ::note after Quick Install (line 39): "need a Hermes Agent-side patch on releases through `v0.14.0` / `v2026.5.16`" — The bare dual version "v0.14.0 / v2026.5.16" is unexplained — a first-time reader can't tell these are two version schemes for the same Hermes Agent release, or even whether they refer to Hermes Agent or to the plugin itself (which versions as v0.3.x); the full guide deliberately avoids pinning versions ("current releases"), so this hard-coded pair will also silently go stale once the upstream Hermes fix ships.
+  - *Evidence:* MONKEYPATCH.md in the plugin repo treats "v0.14.0 / v2026.5.16" as one Hermes Agent release row in its compatibility table and explains the dual notation; the guide's warning (content/7.integrations/11.hermes.md line 10) says only "current releases" / "affected Hermes Agent releases" with no version numbers. The what's-new sentence gives the pair with no attribution or gloss.
+  - *Fix:* Either drop the version numbers to match the guide ("...need a Hermes Agent-side patch on current Hermes Agent releases — see the warning in the full guide") or attribute and gloss them ("...on Hermes Agent releases through v0.14.0 (also tagged v2026.5.16)").
+
+### content/2.whats-new/4.cloud.md
+
+- [x] **[confusing/high]** ## A redesigned web app — second bullet (line 13) — The bullet reads "**See all your Projects at once** - see all your projects at once in the **Projects** list" — the bold label and its description are the same phrase repeated, which reads like an unfinished edit.
+  - *Evidence:* Line 13 of content/2.whats-new/4.cloud.md. Every other bullet in the list pairs a bold label with a distinct description (e.g. "**Share notes** — create a public, read-only link..."); this one just repeats itself and also uses a plain hyphen where the others use an em dash. The web-app page (content/3.cloud/02.web-app.md) describes project management under Settings → Projects and a sidebar project selector, so the description should say something concrete about what the Projects list shows.
+  - *Fix:* Rewrite the description so it adds information, e.g. "**Projects at a glance** — browse and manage every project in your workspace from the **Projects** list (create, upload, download as ZIP)."
+- [x] **[redundant/high]** ## File History (line 38) — The entire File History paragraph is a verbatim copy of the intro paragraph of the dedicated File History page, and it never links to that page.
+  - *Evidence:* Line 38 of content/2.whats-new/4.cloud.md is word-for-word identical to line 6 of content/3.cloud/12.file-history.md ("Every saved version of a note is preserved automatically... distinct from Snapshots, which are project-wide point-in-time backups."). A full paragraph duplicated verbatim will drift when either page is edited. Additionally, unlike every other section on this page (Web App, Teams, Shared Notes, Snapshots all end with a "See ..." link), this section links only to /cloud/cloud-snapshots and omits a link to /cloud/file-history, which exists.
+  - *Fix:* Replace the copied paragraph with a one- or two-sentence what's-new summary in the page's own words and add "See [File History](/cloud/file-history)" as the canonical reference, matching the pattern of the other sections.
+
+### content/2.whats-new/6.agent-skills.md
+
+- [x] **[incorrect/high]** ## Available Skills (table, lines 12-22) — The "Available Skills" table lists only 9 skills, omitting 4 of the 13 public skills: memory-capture, memory-continue, memory-curate, and memory-literary-analysis.
+  - *Evidence:* The canonical skills source (/Users/phernandez/dev/basicmachines/basic-memory/skills/) contains 13 public skill directories (14 minus the unlisted CI-internal memory-ci-capture), and skills/README.md documents all 13. The docs' own guide at content/7.integrations/9.skills.md lists all 13 under the identical "Available Skills" heading. A heading claiming availability that shows 9 skills tells readers those are all the skills that exist.
+  - *Fix:* Either add the four missing rows (memory-capture, memory-continue, memory-curate, memory-literary-analysis) or retitle/reframe the section as a highlights subset (e.g., "Skill highlights") with an explicit pointer to the full list on the Agent Skills guide.
+- [x] **[redundant/high]** ## Available Skills, ## Quick Install, ## Using a skill (lines 10-44) — The skills table, install commands (including the --skill variant and the Node.js/npx note), the compatibility sentence ("Works with Claude Desktop, Claude Code, Cursor, Windsurf..."), and the verbatim usage example ("Use the /memory-notes skill to write up what we just discussed.") all duplicate content/7.integrations/9.skills.md — and the duplicated table has already drifted (9 skills here vs 13 there).
+  - *Evidence:* content/7.integrations/9.skills.md contains the same install commands (lines 23-31), the same compatibility tip (line 10), the identical example prompt (line 70), and a fuller "Available Skills" table (lines 80-96). The 9-vs-13 mismatch between the two tables is drift that has already happened, not a hypothetical.
+  - *Fix:* Slim this what's-new page to an announcement: one-paragraph pitch, the single quick-install command, and 3-4 highlighted skills, with the card link to /integrations/skills as the source of truth for the full table, per-agent install options, and usage details. Remove the duplicated full table and the second install variant.
+
+### content/2.whats-new/7.openclaw-plugin.md
+
+- [x] **[incorrect/high]** Key Capabilities, line 21 ("6 bundled skills") — The page claims 6 bundled skills, but the plugin ships 10 — the list omits memory-ingest, memory-lifecycle, memory-literary-analysis, and memory-research.
+  - *Evidence:* Plugin README (v0.2.4, /Users/phernandez/dev/basicmachines/openclaw-basic-memory/README.md) states "Ten skills ship with the plugin — no installation needed" and lists all 10; openclaw.plugin.json "skills" array lists 10 skill directories including memory-ingest, memory-lifecycle, memory-literary-analysis, memory-research.
+  - *Fix:* Replace with the full 10-skill list, or better (per the docs policy against hard-coded skill counts) drop the count and enumerate nothing: "Bundled skills — workflow skills for notes, tasks, schemas, reflection, defrag, and more, no separate install needed" with a link to the guide.
+- [x] **[incorrect/medium]** Key Capabilities, line 20 ("7 slash commands") — The plugin registers more than 7 slash commands: 3 static commands (/bm-setup, /remember, /recall) plus one command per bundled skill, so /ingest, /lifecycle, /notes, /research, /metadata-search (and /literary-analysis) also exist alongside /tasks, /reflect, /defrag, /schema.
+  - *Evidence:* /Users/phernandez/dev/basicmachines/openclaw-basic-memory/commands/skills.ts registerSkillCommands() calls api.registerCommand for every entry in skills/manifest.json (command name = skill dir minus the "memory-" prefix); slash.ts registers bm-setup, remember, recall. With 10 bundled skills that is 13 commands, not 7. (The upstream README's own table also says 7, which is where the drift originated — the integrations/openclaw guide repeats the same table.)
+  - *Fix:* Drop the hard-coded count and list only the headline commands, e.g. "Slash commands — /remember, /recall, /tasks, and more, plus one command per bundled skill", and fix the table on /integrations/openclaw at the same time.
+- [x] **[incorrect/medium]** Quick Install, lines 26-29 — The install snippet omits the plugin-enable step; the plugin README's install sequence is install → `openclaw plugins enable openclaw-basic-memory --slot memory` → gateway restart.
+  - *Evidence:* /Users/phernandez/dev/basicmachines/openclaw-basic-memory/README.md lines 47-49: `openclaw plugins install @basicmemory/openclaw-basic-memory` / `openclaw plugins enable openclaw-basic-memory --slot memory` / `openclaw gateway restart`. The README also lists uv as a prerequisite. The same two-line snippet (missing the enable step) appears on /integrations/openclaw, so both pages need the fix.
+  - *Fix:* Add `openclaw plugins enable openclaw-basic-memory --slot memory` between the install and restart commands (verify against the shipped plugin whether install auto-enables; if it does, the README should change instead).
+- [x] **[incorrect/medium]** Key Capabilities, line 19 ("14 agent tools — Full Basic Memory toolset...") — "Full Basic Memory toolset" overstates what the plugin exposes: it is a curated 14-tool subset, and "project management" is limited to listing projects/workspaces (no create/delete/switch project, no recent_activity, canvas, list_directory, view_note, etc.).
+  - *Evidence:* openclaw.plugin.json contracts.tools lists exactly 14 tools: build_context, delete_note, edit_note, list_memory_projects, list_workspaces, memory_get, memory_search, move_note, read_note, schema_diff, schema_infer, schema_validate, search_notes, write_note — no project create/delete/switch tools and only a subset of Basic Memory's MCP tools.
+  - *Fix:* Reword to something like "Agent tools — search, read, write, edit, schema validation, and project/workspace listing" and drop both the "14" count (docs policy: no hard-coded tool counts) and the "Full ... toolset" claim, or say "the core Basic Memory tools".
+
+### content/2.whats-new/8.ai-friendly-docs.md
+
+- [x] **[redundant/medium]** Access Methods table and Quick Examples (lines 16-36) — The 4-row access-methods table and all three curl examples are near-verbatim copies of the same table and examples on the reference page content/9.reference/8.llms-txt.md, so the two pages will drift if a method or URL changes.
+  - *Evidence:* Reference page 'Quick reference' table (9.reference/8.llms-txt.md lines 20-27) has the identical four rows (Index /llms.txt, Full docs /llms-full.txt, Raw markdown /raw/<path>.md, Content negotiation Accept: text/markdown) with only trivially reworded descriptions; the curl examples for llms.txt, /raw/start-here/what-is-basic-memory.md, and the Accept-header request all appear on both pages. Both pages also share the identical title 'AI-Friendly Documentation' and near-identical frontmatter descriptions, producing two same-titled entries in nav/search.
+  - *Fix:* Keep the What's New page as a short announcement (the one-line 'ask your AI' prompt plus the cross-link cards) and drop or heavily condense the duplicated table and curl examples, deferring details to /reference/llms-txt; also differentiate the page title (e.g., 'New: AI-Friendly Docs') so it doesn't collide with the reference page in search and navigation.
+
+## Cloud
+
+
+### content/3.cloud/01.cloud-guide.md
+
+- [x] **[incorrect/high]** Project Management section, lines 189-193 (`bm project add my-new-project`) — `bm project add my-new-project` (and the `--default` variant) is labeled "Create a new cloud project" but fails in the current CLI: without the `--cloud` flag the command runs in local mode and errors because the positional path is missing.
+  - *Evidence:* src/basic_memory/cli/commands/project.py:764 `effective_cloud_mode = cloud and not local` (changed from config-based cloud mode in commit 0239f4ab, 2026-02-16 "Simplify local/cloud routing"); the local-mode branch errors "path argument is required in local mode" when no path is given (project.py:800-802). Cloud project creation now requires explicit `--cloud`.
+  - *Fix:* Change to `bm project add my-new-project --cloud` and `bm project add my-new-project --cloud --default`.
+- [x] **[incorrect/high]** Migrating to Cloud > Option 2, line 317 (`bm project add main --local-path ~/basic-memory`) — The migration command `bm project add main --local-path ~/basic-memory` fails: `--local-path` without `--cloud` leaves the command in local mode, which requires a positional path and exits with an error.
+  - *Evidence:* Same code path as above: project.py:764 requires the `--cloud` flag for cloud mode; local mode with path=None prints "Error: path argument is required in local mode". The cloud-sync alternative is `bm cloud sync-setup <name> <path>` (project_sync.py:666), which is what `bm cloud setup`'s own next-steps output recommends.
+  - *Fix:* Use `bm project add main --cloud --local-path ~/basic-memory` (or `bm cloud sync-setup main ~/basic-memory` for an existing cloud project).
+- [x] **[incorrect/high]** Per-project Cloud Routing section, line 157 (`bm project set-local research`) — `bm project set-local research` without `--local-path` fails after the preceding `bm project set-cloud research`, because set-cloud blanks the project's stored local path, so set-local has no path to reuse.
+  - *Evidence:* project.py:1168 (`set-cloud`) sets `config.projects[name].path = ""`; project.py:1213-1219 (`set-local`) errors "--local-path is required for '<name>' (no previous local path is recorded)" when both the flag and the stored path are empty. The path-reuse shortcut only applies to configs written by older versions. The Cloud CLI page (content/3.cloud/13.cloud-cli.md) correctly shows `bm project set-local research --local-path ~/Documents/research`.
+  - *Fix:* Change to `bm project set-local research --local-path ~/Documents/research`.
+- [x] **[incorrect/high]** Authentication > Login to Cloud, "After login" output block, lines 136-142 — The example login output includes "Cloud mode enabled" and "CLI commands use cloud routing unless a project is explicitly set to local mode", which `bm cloud login` does not print and which misstates current behavior: routing defaults to local and cloud routing is opt-in per project.
+  - *Evidence:* core_commands.py:75-97 prints "Verifying subscription access...", "Cloud authentication successful", "Cloud host ready: <url>"; auth.py:291 prints "Successfully authenticated with Basic Memory Cloud!" and auth.py:197 "Tokens saved to ...". No "Cloud mode enabled" line exists in the login path (it appears only in mcp/container.py). Routing model: project.py:764 defaults to local unless `--cloud`/`set-cloud`; cloud_mode is env-derived (config.py:1220). The Cloud CLI page states the opposite of this page: "`bm cloud login` authenticates the CLI. It does not automatically move local projects into Cloud or start syncing files."
+  - *Fix:* Replace the output block with the actual messages (Successfully authenticated / Tokens saved / Verifying subscription access / Cloud authentication successful / Cloud host ready) and drop the cloud-routing claim, or state explicitly that login does not change project routing.
+- [x] **[incorrect/high]** Authentication > Check Status, line 176 — The page claims `bm cloud status` shows "last sync time, cloud project count, tenant information, and sync directory configuration", none of which the current command outputs.
+  - *Evidence:* core_commands.py:158-199: status prints Host, API Key configured/not-set, OAuth token validity, and a connectivity check ("Cloud connected" / "Cloud not connected") via GET /proxy/health. No sync time, project count, tenant info, or sync directory appears.
+  - *Fix:* Describe the real output: cloud host, API key status, OAuth token status, and a connection check.
+- [x] **[incorrect/high]** Project Management example output, lines 199-207 — The `bm project list` example shows a stale 3-column table (Name / Path / Default) with a cloud-container path `/app/data/basic-memory`; the current command outputs an 8-column table.
+  - *Evidence:* project.py:457-464 defines columns: Name, Local Path, Cloud Path, Workspace, CLI Route, MCP, Sync, Default. The example predates the workspaces/routing columns and its Path value is the server-side container path, which users never see for their own projects.
+  - *Fix:* Regenerate the example from a real `bm project list` run showing the current columns.
+- [x] **[incorrect/high]** Setup with ChatGPT note, line 64 — The note says ChatGPT requires a "Pro or Max subscription" — ChatGPT has no Max plan (that is Claude's plan name), and the docs' own ChatGPT page says Plus or Pro.
+  - *Evidence:* content/7.integrations/3.chatgpt.md:52: "**ChatGPT Plus or Pro subscription required.**" (repeated at line 65). The same "Pro or Max" error also exists on content/1.start-here/2.quickstart-cloud.md:72.
+  - *Fix:* Change to "Plus or Pro subscription" to match the ChatGPT integration page.
+- [x] **[confusing/high]** Authentication / Per-project Cloud Routing section ordering, lines 144-184 — The "Per-project Cloud Routing" section is wedged into the middle of the Authentication section, stranding the "**If no subscription:**" block (lines 164-168) after the routing tip — where it reads as a routing failure mode instead of a login outcome — and leaving the "Check Status" and "Logout" h4 subsections nested under the routing heading.
+  - *Evidence:* Page structure: '#### Login to Cloud' (h4) → '### Per-project Cloud Routing' (h3) → orphaned '**If no subscription:**' output block → '#### Check Status' / '#### Logout' (h4s that belong to '### Authentication' but now follow the routing h3). The no-subscription output is emitted by `bm cloud login` (core_commands.py SubscriptionRequiredError handler), not by routing commands.
+  - *Fix:* Move the "If no subscription" block directly under "Login to Cloud", and move "Per-project Cloud Routing" after the Authentication section (after Logout).
+- [x] **[redundant/medium]** Setup with Claude section, lines 19-57 — The full Claude connector setup steps (Settings path, Add custom connector, Authenticate, Configure Tools, Verify) are duplicated nearly verbatim from the Cloud Quickstart page, and a third copy lives on the Claude Desktop integration page — three copies that can (and already slightly do) drift.
+  - *Evidence:* content/1.start-here/2.quickstart-cloud.md:36-65 contains the same ::steps sequence with identical wording ("Click **Add custom connector** and enter: Name: Basic Memory..."); content/7.integrations/1.claude-desktop.md:17 repeats the same flow. The Verify step already differs between copies ("search and tools menu" vs "tools menu (+ icon in chat)"), and this page itself links to the Claude Desktop guide for "detailed instructions".
+  - *Fix:* Reduce this section to the connection URL plus links to the Cloud Quickstart and Claude Desktop integration pages, keeping the detailed steps in one canonical place.
+- [x] **[redundant/medium]** Command Line Tools section, lines 89-211 — The CLI walkthrough (login, status, logout, api-key save/create, set-cloud/set-local routing, project list, snapshots) substantially duplicates the dedicated Cloud CLI page in the same section, and the two copies already contradict each other on login/routing behavior and set-local usage.
+  - *Evidence:* content/3.cloud/13.cloud-cli.md covers the identical command set (Sign in to Cloud, api-key save/create, workspace/project inspection, set-cloud/set-local, sync, snapshots). Drift is already visible: cloud-cli.md says login "does not automatically move local projects into Cloud" while this page's login output claims cloud routing becomes the default; cloud-cli.md includes the required `--local-path` on set-local while this page omits it.
+  - *Fix:* Trim this page's CLI section to the quick-start commands plus a link to /cloud/cloud-cli, or reconcile the two and pick one canonical home for the command walkthrough.
+- [x] **[confusing/medium]** Cloud Snapshots section, lines 263-278 — The code comment "# Browse and restore files" precedes `bm cloud snapshot browse`, which only lists snapshot contents; the actual restore command (`bm cloud restore <path> --snapshot <id>`) never appears on the page despite the "Restore individual files or folders" feature bullet.
+  - *Evidence:* snapshot.py:299 `browse` only lists files and itself prints "Use 'bm cloud restore <path> --snapshot <id>' to restore files"; restore is a separate command (restore.py:23). A reader following the snippet has no restore path shown.
+  - *Fix:* Change the comment to "# Browse snapshot contents" and add a `bm cloud restore notes/example.md --snapshot snap_abc123` line.
+- [x] **[confusing/medium]** Authentication > Logout, line 184 — "Removes ~/.basic-memory/basic-memory-cloud.json and clears cached credentials" implies all credentials are revoked, but a saved API key — which the page tells readers to create in the routing section just above — survives logout and continues to route cloud commands.
+  - *Evidence:* core_commands.py logout clears tokens and the cached default workspace, then prints "API key (if configured) remains available for cloud project routing." (core_commands.py:137-157); auth.py:294-300 only unlinks the token file.
+  - *Fix:* Add a sentence: a saved API key is not removed by logout and keeps working for cloud-routed projects; delete it separately if needed.
+
+### content/3.cloud/02.web-app.md
+
+- [x] **[incorrect/high]** ## Working with your AI assistant → ### Improve a selection (lines 120-122) — The section documents an 'Improve' selection action that was removed from the web app.
+  - *Evidence:* In basic-memory-cloud, apps/web-v2/app/components/editor/AgentSelectionPromptPopover.vue (the component with the 'Improve' / 'Improve Selection' labels) was deleted on main by commit 5cdd234f5 'WIP remove selected text agent action' (2026-04-25). A repo-wide grep of origin/main finds no 'Improve' UI control anywhere in apps/web-v2 — only stale descriptive copy in utils/agent-session-presentation.ts. What remains: selecting text in the editor surfaces the selection in the agent pane (NoteAgentSessionPane 'session-current-selection'), where a steering message can include it.
+  - *Fix:* Remove the 'Improve a selection' heading, or rewrite it to describe the current flow: select text in the editor and it appears in the agent pane, where you send a request ('Ask for a rewrite, summary, or next step…') that includes the selection. Also drop the 'connecting automatically if no agent is attached yet' claim, which belonged to the removed action.
+- [x] **[incorrect/high]** ### Search notes (line 44) — The claim 'Search is instant and scoped to the current project' is wrong — search defaults to all projects, with optional scope controls.
+  - *Evidence:* apps/web-v2/app/composables/useSearchDialogState.ts line 35: `const scopeMode = ref<'all' | 'project'>('all')` (same on origin/main); executeSearch() only passes a projectId when the user explicitly picks a project scope, and the dialog offers workspace/project/folder scope options. Also, the sidebar control is a 'Search...' button that opens the search dialog (layouts/default.vue → SearchDialog), not an inline field that filters the note list.
+  - *Fix:* Rewrite to: the sidebar Search button (or Cmd/Ctrl + K) opens the search dialog, which searches across all your projects by default; use the scope controls to narrow to a workspace, project, or folder.
+- [x] **[incorrect/high]** ## Projects → ### Manage projects (line 179) and Settings table 'Projects' row (line 304) — Settings → Projects does not offer file upload; 'upload files' / 'upload to' point users to the wrong place.
+  - *Evidence:* apps/web-v2/app/pages/settings/projects.vue and composables/useProjectsPageState.ts expose only: create (Add Project), Set as Default, Index Project, Download Project (ZIP), Delete Project, and access/members management. The 'Upload Notes' dialog (SettingsUploadNotesDialog) is reachable only from the sidebar project explorer's context menu (components/ProjectExplorer.vue, label 'Upload Notes'); bulk upload is also available via Settings → Import → 'Project ZIP'. Verified identical on origin/main.
+  - *Fix:* In both spots, drop the upload claim and say uploads happen from a project or folder's context menu in the sidebar (Upload Notes) or via Settings → Import → Project ZIP.
+- [x] **[incorrect/high]** ## Import data table, ChatGPT row (line 197) — The ChatGPT row says 'Export ZIP or JSON from ChatGPT settings', but the app only accepts a JSON file for ChatGPT imports.
+  - *Evidence:* apps/web-v2/app/pages/settings/import.vue ChatGPT option: description 'Use a ChatGPT export JSON file.', accept '.json,application/json' — a ZIP is rejected by the file picker. Only the separate 'Project ZIP' import type accepts ZIP archives. Verified on origin/main.
+  - *Fix:* Change to 'conversations JSON from a ChatGPT export' and, if helpful, note that users must extract the JSON from ChatGPT's export ZIP first.
+- [x] **[incorrect/medium]** ## Drafts (lines 100-107) — The section presents drafts as uncommitted until you click Save Draft, but drafts autosave into the target project about 2 seconds after they have meaningful content.
+  - *Evidence:* apps/web-v2/app/components/notes/NoteDetail.vue: debouncedSaveDraft (NOTE_AUTOSAVE_DEBOUNCE_MS = 2000, utils/timing.ts) fires on content and frontmatter changes and calls handleSaveDraft → createNote(targetProjectId, …); new drafts are created with targetProjectId set to the current project (features/notes/note-detail-model.ts line 274). Present on origin/main since 2026-04-23. So 'Drafts let you write before committing a file to a project' and 'Click Save Draft … to write it into the current project' describe superseded behavior; Save Draft (command palette) now just forces an immediate save.
+  - *Fix:* Reframe: a new draft is saved into the current project automatically once it has content (title, tags, or body); use Save Draft in the command palette to save immediately.
+- [x] **[incorrect/medium]** ## Settings intro (line 293) — The user menu is at the bottom of the sidebar, not the top.
+  - *Evidence:* apps/web-v2/app/layouts/default.vue: <UserMenu> is rendered inside the UDashboardSidebar `#footer` slot, in a row with data-testid="sidebar-footer-account-row"; the sidebar header slot contains only the brand plus Add-project/Search buttons.
+  - *Fix:* Change to 'Access settings from the user menu (your avatar at the bottom of the sidebar) or the command palette.' Also update the Layout table's sidebar row if it implies a position.
+- [x] **[incorrect/medium]** ## Import data table, 'Basic Memory JSON' row (line 198) — The import option the docs call 'Basic Memory JSON' is labeled 'memory-json' in the app and is for exports from the memory-json MCP server, not Basic Memory exports.
+  - *Evidence:* apps/web-v2/app/pages/settings/import.vue: label 'memory-json', description 'Use entity and relation JSON exported from the memory-json MCP server.' Calling it 'Basic Memory JSON' suggests it ingests Basic Memory's own export format, and users won't find that name in the Import screen.
+  - *Fix:* Rename the row to 'memory-json' and describe it as entity/relation JSON exported from the memory-json MCP server.
+- [x] **[confusing/medium]** ## Import data (lines 192-204) — The import table omits the 'Project ZIP' option — the first import type in Settings → Import and the page's only real web-based bulk upload path — so a reader never learns how to upload a folder of notes in the browser.
+  - *Evidence:* apps/web-v2/app/pages/settings/import.vue lists four import types, the first being 'Project ZIP' ('Zip the folder you want to import… Basic Memory adds Work/plan.md to the project', destination default 'Project root'). The docs table lists only the three conversation/JSON formats, while the Projects section's upload pointer is wrong (see the Settings → Projects finding) and the tip defers folder uploads to the CLI.
+  - *Fix:* Add a 'Project ZIP' row (ZIP of a folder of Markdown files; directory structure preserved; destination defaults to the project root) and mention it wherever the page discusses uploading files.
+- [x] **[confusing/medium]** ## Tips for Effective Use → ### Organize with folders (lines 326-335) — The folder-structure example is a local filesystem tree rooted at `~/basic-memory/`, which doesn't exist in the web app — folders there live inside cloud projects — and it near-duplicates the tree in the local User Guide.
+  - *Evidence:* In the web app, the sidebar shows project/folder trees inside cloud projects; `~/basic-memory/` is the local default project path (content/5.local/5.user-guide.md line 63), and the same example tree appears in 5.local/5.user-guide.md lines 288-297 ('projects/, decisions/, meetings/, archive/'). A cloud-only reader may look for a home-directory path that doesn't apply.
+  - *Fix:* Show the tree as folders inside a project (drop the `~/basic-memory/` root), or link to the User Guide's organization section instead of repeating the example.
+- [x] **[incorrect/low]** ### Copy permalink and rename (line 157) — 'Copy Permalink' is a command-palette action; the note's ⋮ menu item is labeled 'Copy link for your agent'.
+  - *Evidence:* apps/web-v2/app/composables/useNoteDetailActions.ts line 192: the ⋮ dropdown item invoking handleCopyPermalink is labeled 'Copy link for your agent'; 'Copy Permalink' appears only in useLayoutCommandPalette.ts line 138. A user hunting for 'Copy Permalink' in the ⋮ menu won't find that label. (The menu's rename item is 'Rename note'.)
+  - *Fix:* Say: use 'Copy link for your agent' in the ⋮ menu, or 'Copy Permalink' in the command palette.
+
+### content/3.cloud/03.cloud-sync.md
+
+- [x] **[incorrect/high]** Quick Start > 1. Enable Cloud Mode (also Overview bullet 'Toggle cloud mode' and Architecture state 3 'when cloud mode is disabled') — The page claims `bm cloud login` 'Enables cloud mode - all CLI commands now work against cloud', but there is no global cloud mode toggle anymore — login only authenticates and verifies the subscription; routing is per-project.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/core_commands.py `login` only runs OAuth device auth + subscription check; config.py migration removes `cloud_mode` from config (`data.pop("cloud_mode", None)`) and the `cloud_mode` property reads BASIC_MEMORY_CLOUD_MODE env (server deployments only); routing is per-project via ProjectEntry.mode in mcp/async_client.py get_client(). Sibling page content/3.cloud/13.cloud-cli.md line 56 states the opposite: '`bm cloud login` authenticates the CLI. It does not automatically move local projects into Cloud or start syncing files.'
+  - *Fix:* Rewrite step 1 as 'Sign in to Cloud': login authenticates the CLI and verifies your subscription. Replace the 'Toggle cloud mode' overview bullet and the 'when cloud mode is disabled' parenthetical with the per-project routing model (`bm project set-cloud` / `set-local`, see /cloud/routing).
+- [x] **[incorrect/high]** Quick Start > 3. Add Projects with Sync (also Architecture example, Multiple Projects, Command Reference, Summary step 3) — Every cloud-project-creation example omits the required `--cloud` flag: `bm project add research --local-path ~/Documents/research` and `bm project add temp` fail with 'Error: path argument is required in local mode' because `bm project add` defaults to local mode.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/project.py line 764: `effective_cloud_mode = cloud and not local` (cloud only when --cloud is passed); local branch errors when the positional path is missing. The docs' own CLI reference (content/9.reference/1.cli-reference.md lines 220-229) shows the correct form: `bm project add research --cloud --local-path ~/docs`.
+  - *Fix:* Add `--cloud` to all cloud-project `bm project add` examples on the page (Quick Start, Architecture example, Multiple Projects, Mixed Usage, Command Reference, Summary), e.g. `bm project add research --cloud --local-path ~/Documents/research`.
+- [x] **[incorrect/high]** Quick Start > 6. Verify Setup — Claims `bm cloud status` shows 'Mode: Cloud (enabled)' and 'Cloud instance is healthy' — neither string exists in the command's output.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/core_commands.py status command (lines 158-200) prints 'Cloud Status', '  Host: ...', '  API Key: ...', '  OAuth: token valid/expired/not logged in', then 'Cloud connected' or 'Cloud not connected'.
+  - *Fix:* Replace the expected output with the real strings: `OAuth: token valid` and `Cloud connected`.
+- [x] **[incorrect/high]** Command Reference > Project Management (`bm project rm <name>`) — `bm project rm` is not a command; the command is `bm project remove`.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/project.py line 854: `@project_app.command("remove")`; grep for an "rm" alias across src/basic_memory/cli/ finds nothing. content/9.reference/1.cli-reference.md documents `bm project remove research`.
+  - *Fix:* Change to `bm project remove <name>`.
+- [x] **[incorrect/high]** Quick Start > 5. Daily Workflow > 'What happens on push' (steps 3-4) — Step 4 'Updates last_sync timestamp in config' is false — push/pull never write to config; and step 3 overstates the CLI's role (the push command itself does not reindex; indexing happens automatically on the receiving instance).
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/project_sync.py: `_run_directional_transfer` (used by push/pull) contains no config save and no reindex call; `last_sync` is only set in the bisync command (lines 558-565), which this page correctly no longer documents. grep for last_sync/reindex in rclone_commands.py returns nothing.
+  - *Fix:* Drop step 4 and reword step 3, e.g. '3. The cloud instance detects the new files and reindexes them automatically' — which also matches the ::note directly below.
+- [x] **[incorrect/high]** Architecture: Project-Scoped Sync > 'What happens under the covers' — Claims 'Config stores `cloud_projects` dict mapping project names to local paths' — `cloud_projects` is a legacy format that is migrated away on load; current config stores a unified `projects` dict of ProjectEntry objects with a `local_sync_path` field.
+  - *Evidence:* basic-memory/src/basic_memory/config.py: ProjectEntry (lines 145-176) unifies the old triple 'Replaces the old triple of projects, project_modes, and cloud_projects'; the migrate_legacy_projects validator pops `cloud_projects` from config data (lines 580, 618); CloudProjectConfig is marked 'DEPRECATED: Kept for backward-compatible migration only.'
+  - *Fix:* Say: 'Config stores each project as an entry with a `local_sync_path` in ~/.basic-memory/config.json.'
+- [x] **[incorrect/high]** Architecture 'under the covers' + Quick Start > 2. Set Up Sync ('Configures single rclone remote: basic-memory-cloud') — The 'single rclone remote: basic-memory-cloud' claim is only true for the default Personal workspace — each Team workspace gets its own tenant-scoped remote, and the page (which advertises Team-safe push/pull) never mentions the required `bm cloud setup --workspace <slug>` step for Team workspaces.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/rclone_config.py lines 70-96: default remote 'basic-memory-cloud', non-default workspaces get 'basic-memory-cloud-<slug>' via remote_name_for_workspace; project_sync.py lines 349-359: push/pull abort with 'Workspace X is not set up for sync. Run: bm cloud setup --workspace <slug>' when the workspace remote is missing; core_commands.py setup takes a --workspace option.
+  - *Fix:* Reword to 'Configures a tenant-scoped rclone remote per workspace (basic-memory-cloud for your Personal workspace)' and add a note that Team workspace members must run `bm cloud setup --workspace <slug>` once before push/pull.
+- [x] **[incorrect/high]** Filter Configuration > Understanding .bmignore > 'Default patterns' code block — The listed default patterns do not match the actual generated .bmignore file — the doc shows `memory.db/**`, `.DS_Store/**`, `.env/**` etc., none of which appear in the defaults (and as gitignore-style patterns the `X/**` forms would only match directories, so they would not even ignore those files).
+  - *Evidence:* basic-memory/src/basic_memory/ignore_utils.py create_default_bmignore writes gitignore-style names with no `/**` suffixes: `.*`, `*.db`, `*.db-shm`, `*.db-wal`, `config.json`, `.git`, `.svn`, `__pycache__`, `*.pyc`, `.venv`, `node_modules`, `build`, `dist`, `.DS_Store`, `.obsidian`, `*.tmp`, etc.
+  - *Fix:* Replace the code block with a representative excerpt of the real defaults (`.*`, `*.db`, `*.db-shm`, `*.db-wal`, `config.json`, `.git`, `__pycache__`, `*.pyc`, `.venv`, `node_modules`, `.DS_Store`, `.obsidian`, `*.tmp`).
+- [x] **[incorrect/high]** Disable Cloud Mode section — Claims `bm cloud logout` returns you to 'local mode' where 'All bm commands now work with local projects' — logout only removes OAuth tokens and clears the cached default workspace; cloud-routed projects then fail with a missing-credentials error rather than silently working locally.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/core_commands.py logout: 'Remove stored OAuth tokens and clear cached workspace selection', prints 'API key (if configured) remains available for cloud project routing.'; async_client.py raises "Project 'X' is set to cloud mode but no credentials found" for cloud-mode projects without credentials.
+  - *Fix:* Retitle to 'Sign out' and state that logout removes the stored OAuth tokens; to route a project locally again, use `bm project set-local <name>`.
+- [x] **[incorrect/medium]** Troubleshooting > Project Not Configured for Sync — The quoted error message 'Project has no local_sync_path configured' does not match the actual CLI output.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/project_sync.py line 224: `Error: Project '{name}' has no local sync path configured` (followed by 'Configure sync with: bm cloud sync-setup ...').
+  - *Fix:* Quote the real message: "Error: Project 'research' has no local sync path configured".
+- [x] **[incorrect/high]** Prerequisites > 'Basic Memory CLI: See [Getting Started](/local/getting-started#local-installation)' — The link anchor #local-installation does not exist on the /local/getting-started page; installation instructions live on /local/local-install.
+  - *Evidence:* content/5.local/2.getting-started.md has no 'Local Installation' heading (headings: Choosing Where Notes Are Saved, Multi-Project Setup, Staying Updated, Next Steps); content/5.local/1.local-install.md is the install page, and content/3.cloud/13.cloud-cli.md links to /local/local-install for the same purpose.
+  - *Fix:* Link to [Install Basic Memory locally](/local/local-install).
+- [x] **[redundant/medium]** Command Reference section (Cloud Mode Management / Setup / Project Management / File Synchronization) — This section restates the same commands documented in the CLI Reference page (content/9.reference/1.cli-reference.md, 'Cloud commands' and 'bm project' sections), and the two have already drifted: this page says `bm project rm` and omits `--cloud` on add examples while the CLI reference has `bm project remove` and the correct `--cloud` forms.
+  - *Evidence:* content/9.reference/1.cli-reference.md lines 211-360 cover bm project add/remove/ls, cloud login/status/logout/setup, pull/push/sync/check/sync-setup with the same examples; the drift (rm vs remove, missing --cloud) is visible by diffing the two pages.
+  - *Fix:* Trim the Command Reference to only the sync-specific commands this guide teaches (pull/push/sync/check/sync-setup) and link to /reference/cli-reference for project and auth commands.
+- [x] **[confusing/medium]** Architecture: Project-Scoped Sync > How It Works > Example — The example narrative says 'You have 3 projects on cloud' but the commands shown are `bm project add`, which creates new projects — for projects that already exist on cloud the correct command is `bm cloud sync-setup <name> <path>`, and running `project add` against an existing name errors.
+  - *Evidence:* project.py add_project calls create_project (fails on duplicate names), while project_sync.py sync-setup exists specifically to 'Configure local sync for an existing cloud project'; the page itself introduces sync-setup two sections later for exactly this case.
+  - *Fix:* Either change the narrative to 'You want 3 new projects on cloud' or switch the commands to `bm cloud sync-setup research ~/Documents/research` etc. for the existing-project scenario.
+
+### content/3.cloud/05.cloud-snapshots.md
+
+- [x] **[incorrect/high]** Using the CLI — the three "**Output:**" blocks under Create a Snapshot (line 72), List Snapshots (lines 83-86), and Browse Snapshot Contents (lines 104-108) — The example CLI output blocks are fabricated and do not match what the commands actually print.
+  - *Evidence:* Source: basic-memory/src/basic_memory/cli/commands/cloud/snapshot.py. `create` prints multi-line output ('Snapshot created successfully' + ID/Version/Created/Description lines, lines 68-72), not 'Created snapshot: snap_abc123 (2026-01-27T10:30:00)'. `list` renders a Rich table titled 'Bucket Snapshots (N total)' with columns ID/Description/Auto/Created (lines 130-134) — there is no size column, so the '42 MB' values are invented. `browse` prints a 'Snapshot Contents (N files)' header with per-file sizes in KB and a restore hint (lines 343-353), not bare paths. Snapshot IDs are also UUIDs (cloud service takes snapshot_id: UUID), not 'snap_'-prefixed strings.
+  - *Fix:* Regenerate the three Output blocks from actual command runs (or trim them to just the commands), and use a realistic UUID-style placeholder for snapshot IDs.
+- [x] **[incorrect/high]** Troubleshooting → Restore Didn't Work (steps 1 and 3, lines 190-192) — Step 3 tells users to 'try restoring to a different location first', but neither the CLI nor the web app can restore to a different location, and step 1's 'check file permissions in your project' does not apply to a server-side bucket restore.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/cloud/restore.py: `bm cloud restore` accepts only a path, --snapshot, and --force; the restore API call posts {"path": ...} and always writes files back to their original paths ('The restored files will overwrite any existing files at the same path'). The web-v2 SnapshotRestorePanel likewise restores selected files in place. Restore happens in the cloud bucket, so local file permissions are irrelevant.
+  - *Fix:* Replace these steps with actionable checks, e.g. use `bm cloud snapshot browse <id> --prefix <path>` to confirm the exact path exists in the snapshot, verify the path matches what browse shows (project-prefixed), and re-run with the corrected path.
+- [x] **[incorrect/medium]** Using the Web App → Restore from a Snapshot, step 1 (line 47) — The button that opens the restore flow is labeled 'Restore', not 'Restore Files', and it is a per-snapshot action button rather than something reached by clicking the snapshot itself.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/pages/settings/snapshots.vue line 456: label="Restore" on each snapshot row (alongside 'Download' and 'Delete'); the panel that opens is titled 'Restore from Snapshot' (matches the page's own screenshot restore-files.png). No 'Restore Files' label exists in the current UI source.
+  - *Fix:* Reword step 1 to: 'On the snapshot's row, click **Restore**' (and consider refreshing the screenshots, which show an older actions-menu UI).
+
+### content/3.cloud/06.themes.md
+
+- [x] **[incorrect/high]** ## Custom Themes through ## Using TweakCN (lines 53-180), plus intro line 6 "support for custom CSS" — The entire Custom Themes feature documented here (paste/drag-and-drop CSS, TweakCN format, Required/Optional/Sidebar variables, TweakCN export workflow) does not exist in the current cloud web app.
+  - *Evidence:* In basic-memory-cloud apps/web-v2 (the deployed app), useTheme.ts loads presets exclusively from app/config/themes.json with no custom CSS input; grep for "Custom Theme", "tweakcn", or CSS upload across apps/web-v2 returns nothing; the Settings General page (app/pages/settings/index.vue) offers only preset swatches. The app's theme variables are Nuxt UI --ui-* and --bm-* names (e.g. --ui-bg, --ui-primary, --bm-sidebar-bg), not the documented shadcn/TweakCN set (--background, --card, --popover, --sidebar-*), so even the CSS schema is wrong.
+  - *Fix:* Remove the Custom Themes, CSS Format, Required Variables, Optional Variables, Sidebar Variables, and Using TweakCN sections (and "support for custom CSS" in the intro/description) until a custom-CSS feature ships; keep the page focused on color mode and preset themes.
+- [x] **[incorrect/high]** ### Available Themes (lines 35-49) and "dozens of preset themes" claims (lines 6, 25) — Three of the four named presets (Modern Minimal, Violet Bloom, T3 Chat) do not exist, and "dozens of curated themes" overstates the actual 17 presets.
+  - *Evidence:* apps/web-v2/app/config/themes.json defines exactly 17 presets: Default, shadcn, Midnight, Catppuccin, Nord, Claude, ChatGPT, Mono, Atlas, Monokai, Solarized, Flexoki, Graphite, Ember, Obsidian, Zed, Swiss. Grep for "Modern Minimal", "Violet Bloom", "T3 Chat" across the cloud repo finds no hits.
+  - *Fix:* Name a few real presets (e.g. Default, Catppuccin, Nord, Solarized, Zed) and soften the quantity wording (e.g. "a curated set of themes"), consistent with the no-hard-coded-counts policy.
+- [x] **[incorrect/high]** ### Selecting a Theme (lines 27-33) — The steps describe a theme dropdown with hover color-palette previews, but the actual UI is a row of color swatch circles you click, with only the theme name shown in a tooltip on hover.
+  - *Evidence:* apps/web-v2/app/pages/settings/index.vue lines 246-266: themes render as size-8 rounded-full swatch buttons inside a UTooltip (tooltip text = theme.label), under the "Theme" subsection of the "Look & Feel" card on Settings → General; there is no dropdown component.
+  - *Fix:* Rewrite steps: Open Settings → General, find the Theme row under Look & Feel, hover a swatch to see the theme name, click a swatch to apply.
+- [x] **[incorrect/high]** ## Color Mode (lines 11-19) — Steps say to find the "Theme" section to switch color mode, but the Light/Dark/System toggle is the separate "Mode" control under the "Look & Feel" card on the Settings → General page.
+  - *Evidence:* apps/web-v2/app/pages/settings/index.vue lines 188-210: color mode is a UButtonGroup labeled "Mode" (options System, Light, Dark) in the "Look & Feel" card, distinct from the "Theme" swatch subsection below it. A quick light/dark toggle is also in the user menu (UserMenu.vue).
+  - *Fix:* Update steps to: Open Settings → General, find the Mode control under Look & Feel, click Light, Dark, or System (and optionally mention the user-menu toggle).
+- [x] **[incorrect/high]** ## Troubleshooting (lines 197-217) — All three troubleshooting entries (missing required variables, OKLCH value errors, "Custom Theme Rejected" by the validating editor) troubleshoot the nonexistent custom-CSS theme editor.
+  - *Evidence:* No custom theme editor, CSS validation, or size limit exists in apps/web-v2; theme selection is preset-only via themes.json, so none of these failure modes can occur for users.
+  - *Fix:* Remove the Troubleshooting section along with the custom-theme sections, or replace it with preset-relevant tips (e.g. theme is per-browser via localStorage, so it must be reselected on a new device).
+- [x] **[incorrect/medium]** ### Available Themes → "Each theme defines" list (lines 44-49) — The list of what each theme defines ("Background and foreground colors, Primary and accent colors, Sidebar colors, Card and border styles") uses the shadcn/TweakCN vocabulary rather than what presets actually control, which will mislead readers who inspect or ask about theme internals.
+  - *Evidence:* Presets in themes.json set a Tailwind primary/neutral pair plus --ui-* tokens (bg, text, border, radius) and --bm-* tokens (sidebar, note typography, code blocks, shadows); there are no --card/--accent/--popover style definitions. The general categories loosely overlap, but the framing exists to support the incorrect custom-CSS sections.
+  - *Fix:* Simplify to what users actually experience: each preset coordinates background, text, accent, sidebar colors and (for some themes) typography, in both light and dark modes.
+
+### content/3.cloud/07.api-keys.md
+
+- [x] **[incorrect/medium]** ## Using API Keys → ### With Claude Desktop (lines 53-68) — The claude_desktop_config.json example uses a remote `url` + `headers` server entry, which Claude Desktop's config file does not support (it only spawns stdio servers via command/args); remote MCP with cloud is configured through the Connectors UI.
+  - *Evidence:* The sibling page content/7.integrations/1.claude-desktop.md documents cloud connection exclusively via 'Settings > Claude > Connectors' → 'Add connector' with the URL https://cloud.basicmemory.com/mcp (OAuth flow), not via a url/headers block in claude_desktop_config.json. The url+headers JSON shape is the Cursor/VS Code format, not Claude Desktop's.
+  - *Fix:* Replace the JSON config with the Connectors flow (link to /integrations/claude-desktop), or show a working bearer-token setup via a stdio bridge (e.g. `npx mcp-remote https://cloud.basicmemory.com/mcp --header "Authorization: Bearer bmc_..."`) if API-key auth for Claude Desktop is actually supported.
+- [x] **[incorrect/high]** ## Using API Keys → ### With Codex CLI (lines 70-79) — The Codex config uses TOML array-of-tables syntax `[[mcp_servers]]` with a `name = "basic-memory"` key, but Codex CLI expects a table keyed by server name: `[mcp_servers.basic-memory]`.
+  - *Evidence:* content/7.integrations/5.codex.md (lines 147-151) documents the same setup as `[mcp_servers.basic-memory]` with `url` and `bearer_token_env_var` — no `name` key. Codex CLI parses `mcp_servers` as a map, so the array-of-tables form on this page would not be recognized.
+  - *Fix:* Change the snippet to:
+[mcp_servers.basic-memory]
+url = "https://cloud.basicmemory.com/mcp"
+bearer_token_env_var = "BASIC_MEMORY_API_KEY"
+(matching the Codex integration page).
+- [x] **[incorrect/high]** ## Creating an API Key → ### Set Expiration (Optional) (lines 34-36) — The creation steps include a 'Set Expiration' step, but the web app's create-key dialog has no expiration control — only a 'Key name' field.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/pages/settings/api-keys.vue: the 'Create API key' dialog contains a single UFormField labeled 'Key name' plus Cancel/Create buttons; handleCreateKey sends only the name. expires_at exists in the backend schema (api_key_schemas.py) but is never exposed in the UI.
+  - *Fix:* Remove the 'Set Expiration' step (and soften the 'Set expiration dates' bullet under Security Best Practices, since users cannot set expiration from the web app).
+- [x] **[incorrect/high]** ## Creating an API Key → ### Click Create Key (line 28) — The button label 'Create New API Key' does not match the actual UI, where the button is 'Create Key' (shown per workspace) and the dialog is titled 'Create API key' with a 'Create' confirm button.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/pages/settings/api-keys.vue line ~396: UButton label="Create Key" per workspace group; dialog heading 'Create API key'.
+  - *Fix:* Change to: Click **Create Key** next to the workspace you want the key for, then confirm with **Create**.
+- [x] **[confusing/medium]** Page-wide (Creating an API Key steps and the ::warning at line 45-47) — The page never mentions that API keys are scoped to a workspace — the UI groups keys by workspace and creates keys per workspace, so 'Anyone with the key can access your Basic Memory account' misstates what a key grants for Team users.
+  - *Evidence:* apps/web-v2/app/pages/settings/api-keys.vue: keys are listed in per-workspace groups with a per-workspace 'Create Key' button, and the post-create notice reads 'The full key for {workspaceName} is only shown once'. TenantAPIKey is tenant_id-scoped (models/tenant_api_key.py).
+  - *Fix:* Add a sentence in 'Creating an API Key' noting keys belong to a specific workspace (Personal or a Team), and reword the warning to say the key grants access to that workspace.
+- [x] **[incorrect/low]** ## API Keys vs OAuth table, 'Scopes' row (line 197) — The 'Scopes' row claims API keys are always 'Full access' and OAuth scopes are 'Configurable', but the backend supports project-scoped API keys and nothing supports user-configurable OAuth scopes.
+  - *Evidence:* basic-memory-cloud models/tenant_api_key.py line 55: `project_scope` column with comment 'NULL means admin key (all projects)'; api_key_schemas.py validates project_scope on create. No user-facing OAuth scope configuration exists in the cloud repo or docs.
+  - *Fix:* Drop the Scopes row, or reword to 'Access: full workspace access (project-scoped keys available via API) / full account access'.
+- [x] **[redundant/medium]** ## Using API Keys → ### With Basic Memory CLI (per-project routing) (lines 104-122) — The api-key save/create + set-cloud/set-local command block duplicates the same commands (with the same example names and comments) on the Local & Cloud Routing and Cloud CLI pages, and the three copies can drift.
+  - *Evidence:* content/3.cloud/08.routing.md lines 49-80 and 106-115, and content/3.cloud/13.cloud-cli.md lines 62-69 contain the same `bm cloud api-key save bmc_your_key_here` / `bm cloud api-key create "work-laptop"` / `bm project set-cloud` / `set-local` sequence; the pages already cross-link each other.
+  - *Fix:* Trim this section to the two api-key commands (which are on-topic for this page) plus the existing link to /cloud/routing for the set-cloud/set-local workflow.
+
+### content/3.cloud/08.routing.md
+
+- [x] **[incorrect/high]** Routing Levels table, 'Global' row (line 33) and first example bullet (line 37) — The table claims `bm cloud login` / `logout` sets a global routing default for all projects, but login only stores OAuth credentials and logout only removes them — neither changes routing.
+  - *Evidence:* basic-memory source: cli/commands/cloud/core_commands.py login (lines 75-134) only authenticates and verifies subscription; mcp/async_client.py get_client() (lines 371-459) routes by explicit flags, then per-project mode, then workspace selector, then falls back to LOCAL — no login-derived global mode exists (cloud_mode is the BASIC_MEMORY_CLOUD_MODE server env var, config.py:652-659). The docs' own cloud-cli page (content/3.cloud/13.cloud-cli.md line 56) contradicts this: "`bm cloud login` authenticates the CLI. It does not automatically move local projects into Cloud."
+  - *Fix:* Replace the 'Global' row with the real lowest level: default routing is local (per-project mode decides for registered projects; login/API keys only supply credentials for cloud-routed calls). Rewrite the 'Global cloud mode is active…' example, and remove 'global cloud mode' from the Authentication table's Browser-login row (line 148).
+- [x] **[incorrect/high]** Common Setups > All Cloud (lines 93-100) — Claims running `bm cloud login` makes all projects route through cloud and `bm cloud logout` returns to local-only; login does not change any project's routing and logout does not restore local routing.
+  - *Evidence:* core_commands.py login stores tokens only; per-project modes in config decide routing (async_client.py:412-434, default fallback is local ASGI at lines 456-459). logout even prints "API key (if configured) remains available for cloud project routing" (core_commands.py:155), so cloud-routed projects keep routing to cloud after logout.
+  - *Fix:* Rewrite 'All Cloud' to describe the real options: connect your AI tool directly to cloud.basicmemory.com (as the top note says), or set every project to cloud with `bm project set-cloud <name>`. Drop the login/logout toggle framing.
+- [x] **[incorrect/high]** Setting Up Cloud Routing > Check Routing Status (lines 68-73) — Says `bm cloud status` shows "which projects are cloud-routed"; it only shows the cloud host, whether an API key/OAuth token is configured, and a connectivity check — it never lists projects.
+  - *Evidence:* core_commands.py status (lines 158-200) prints Host, API Key configured/not set, OAuth token state, and a /proxy/health connectivity result. Per-project routing is displayed by `bm project list`, whose table has a 'CLI Route' column (project.py:456-461).
+  - *Fix:* Change the command to `bm project list` (shows a CLI Route column per project); optionally keep `bm cloud status` as the way to verify cloud credentials/connectivity.
+- [x] **[incorrect/high]** Setting Up Cloud Routing > Revert to Local (lines 77-82) — Shows bare `bm project set-local research` reverting immediately, but after the current `set-cloud` (which blanks the stored local path) this command fails with "--local-path is required ... no previous local path is recorded".
+  - *Evidence:* project.py set_cloud clears the path (`config.projects[name].path = ""`, line 1167) and its docstring says "To return to local mode use `bm project set-local <name> --local-path <path>`" (lines 1126-1127); set_local errors when no path is recorded (lines 1213-1219). The bare form only works for projects converted by older versions that didn't blank the path.
+  - *Fix:* Show `bm project set-local research --local-path ~/Documents/research` and note that `--local-path` is required because set-cloud clears the stored local path.
+- [x] **[confusing/high]** Setting Up Cloud Routing > Route a Project to Cloud (lines 59-66) and Common Setups > Hybrid (lines 106-115) — The page implies `bm project set-cloud` puts an existing local project's notes in the cloud, but it only flips routing — it does not upload any files, and it removes the project's local index row and clears its local path, so a reader's notes are not in the cloud (the cloud project may not even exist) until they upload them.
+  - *Evidence:* project.py set_cloud docstring (lines 1122-1127): "This is a one-way cutover: the project's row in the local index DB is removed and the local path in config is cleared... On-disk note files are preserved"; no upload or cloud-project creation happens in set_cloud. The page's own Gradual Migration section uploads first, but Route a Project to Cloud and Hybrid never mention uploading content.
+  - *Fix:* State explicitly that set-cloud changes routing only: upload existing notes first (`bm cloud upload <path> --project <name> --create-project`) or expect the cloud project to be created/populated separately, and note that local files stay on disk but are no longer indexed locally.
+- [x] **[confusing/medium]** Common Setups > Gradual Migration (lines 122-137) — Steps are out of order: step 2's `bm cloud upload` requires cloud credentials, but the API key isn't saved until step 3; the example also never says the project must already be registered locally for step 3's `bm project set-cloud my-notes` to succeed.
+  - *Evidence:* Upload calls the cloud API (upload_command.py:80-106 checks/creates the cloud project via authenticated requests; cloud helpers error with "Run 'bm cloud login' or 'bm cloud api-key save <key>' first" — project_sync.py:98). set_cloud exits with "Project '<name>' not found in config" if the name isn't a registered project (project.py:1139-1141).
+  - *Fix:* Move `bm cloud api-key save` (or `bm cloud login`) to step 1 before the upload, and note the project should already exist locally (`bm project add my-notes ~/my-notes`) before `bm project set-cloud my-notes`.
+
+### content/3.cloud/09.shared-notes.md
+
+- [x] **[incorrect/high]** ## Who can share (line 78) — The page says only "owners and editors" can create, disable, and revoke share links in a team workspace, but the actual permission check blocks only Viewers — Editors, User Admins, Admins, and Owners can all manage share links.
+  - *Evidence:* basic-memory-cloud/apps/cloud/src/basic_memory_cloud/api/public_shares.py `_require_editor_role` raises 403 only when `workspace.user_role.lower() == MemberRole.VIEWER.value.lower()`; MemberRole (models/organization.py) defines 5 roles: OWNER, ADMIN, USER_ADMIN, EDITOR, VIEWER. A User Admin or Admin reading the docs would wrongly conclude they cannot share.
+  - *Fix:* Say everyone except Viewers can manage share links, e.g. "In a team workspace, any member except a Viewer (Editors, User Admins, Admins, and Owners) can create, disable, and revoke share links."
+- [x] **[incorrect/high]** ## Share a note (lines 24-27, dialog blockquote) — The page says clicking Share note immediately creates the link ("Basic Memory creates a public link and shows it in a dialog") and quotes dialog text "A public read-only link for this note was created." — but the dialog actually opens in a confirmation state with a warning plus Cancel/Create Link buttons, and the link is only created after clicking Create Link; the quoted message doesn't exist in the UI.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/components/notes/ShareNoteDialog.vue: description reads "Create a public read-only link for this note."; the pre-share template shows the warning alert with Cancel and "Create Link" buttons, and only after `handleCreateShareLink` does the Share URL + Copy state render. No "was created" text appears anywhere in the dialog.
+  - *Fix:* Describe the two-step flow: Share note opens a dialog warning "Anyone with this link can view the note without signing in." — click Create Link to generate the public link, then Copy to copy it.
+- [x] **[incorrect/medium]** ## Manage your shares (line 59) — "Settings → Shared Notes to see and manage every link you've created" understates the scope: the page lists every share link in the workspace (tenant-scoped), not just the current user's, and in a team workspace any non-Viewer can disable or revoke links created by teammates.
+  - *Evidence:* basic-memory-cloud/apps/cloud/src/basic_memory_cloud/api/public_shares.py `list_shares` calls `public_share_service.list_shares(tenant_id=workspace.tenant_id, ...)` with no created_by filter; repository method is `list_by_tenant`. Update/revoke endpoints also only check tenant + non-Viewer role, not creator.
+  - *Fix:* Change to "see and manage every link in the workspace" (noting that in a team workspace this includes links created by teammates).
+- [x] **[confusing/medium]** ## Manage your shares — actions table (lines 64-70) — The preamble "From a note's ⋮ menu or the settings screen you can:" implies all three actions are available in both places, but the note's ⋮ menu only offers "Sharing link" and "Stop sharing" — Disable/Enable exists only on the Settings → Shared Notes screen, so a reader looking to pause a link from the note menu won't find it.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/composables/useNoteDetailActions.ts builds the menu with only 'Sharing link' and 'Stop sharing' (or 'Share note' when no active share); the Disable/Enable toggle button appears only in apps/web-v2/app/pages/settings/shared-notes.vue (`:label="share.enabled ? 'Disable' : 'Enable'"`).
+  - *Fix:* Add a location column or note which actions live where: Sharing link and Stop sharing are in the note's ⋮ menu; Disable/Enable (and Stop sharing) are on Settings → Shared Notes.
+
+### content/3.cloud/11.restore-lost-content.md
+
+- [x] **[incorrect/high]** What if the snapshot is too old? — second bullet (line 154) — The project ZIP download is attributed to a "Manage Projects → Download" UI path, but that label does not exist in the app or anywhere else in the docs.
+  - *Evidence:* content/3.cloud/02.web-app.md:179 and content/4.teams/3.copy-between-workspaces.md:33 both document the flow as Settings → Projects, then the project's ⋮ menu → Download. Grep for "Manage Projects" across content/ and the basic-memory-cloud web app source returns only this page.
+  - *Fix:* Change "(Manage Projects → Download)" to "(Settings → Projects → the project's ⋮ menu → Download)" to match the rest of the docs.
+- [x] **[incorrect/high]** What if I deleted a whole project? (line 145) — The claim "You may need to re-create the project entry in the workspace before the restored files appear as a live project" is wrong — snapshot restore automatically recreates missing projects.
+  - *Evidence:* basic-memory-cloud/apps/cloud/src/basic_memory_cloud/services/bucket_snapshot_service.py: module docstring lists "Auto-creating projects when restoring to missing projects"; both restore_file and restore_folder call _ensure_project_exists, which creates the Project record (name, path, permalink) when no match is found.
+  - *Fix:* Replace with: restore recreates the project entry automatically — after restoring, open Settings → Projects to confirm the project reappeared.
+- [x] **[incorrect/medium]** 3. Restore — "A single note" and "A folder" examples (lines 95-109) — The single-note and folder restore examples (`notes/important.md`, `research/`) omit the project-name prefix, even though snapshot paths are workspace-relative with the project as the first path segment — so `research/` is actually a project-root restore, not a folder inside a project.
+  - *Evidence:* bucket_snapshot_service.py restore_file: "Extract project name from first path segment (e.g., 'my-project/notes/file.md' -> 'my-project')"; restore_folder derives projects from parts[0] of each key. The page's own "A whole project" example (`bm cloud restore <project-name>/`) confirms the first segment is the project name, so the "A folder" example `research/` has the identical shape as a whole-project restore and would only work for a project literally named research.
+  - *Fix:* Use project-prefixed example paths, e.g. `bm cloud restore my-project/notes/important.md --snapshot <id>` for a note and `bm cloud restore my-project/research/ --snapshot <id>` for a folder, and state that restore paths start with the project name (as shown by `snapshot browse`).
+- [x] **[confusing/high]** Snapshots intro note (line 48) and "What if the snapshot is too old?" (lines 149-151) — The page tells readers the Cloud Snapshots page covers "retention" and warns about content "older than your retention window," but no docs page defines any snapshot retention window — the referenced page instead says there is no limit on snapshots.
+  - *Evidence:* grep for "retention" across content/ finds no snapshot retention documentation; content/3.cloud/05.cloud-snapshots.md says "Create as many snapshots as you need—there's no limit" and has no retention section, so the cross-reference promises information that doesn't exist and the "too old" scenario rests on an undocumented concept.
+  - *Fix:* Either document actual snapshot retention on the Cloud Snapshots page and keep the cross-reference, or reword this section to a concrete condition (e.g., "if no snapshot predates the loss") and drop the retention-window language.
+- [x] **[incorrect/low]** 1. Find a snapshot (line 64) and all CLI examples using snap_abc123 — The example snapshot ID `snap_abc123` implies a snap_-prefixed ID format, but real snapshot IDs are plain UUIDs.
+  - *Evidence:* basic-memory-cloud/apps/cloud/src/basic_memory_cloud/models/bucket_snapshot.py: BucketSnapshot.id is a UUID primary key (gen_random_uuid()), and the CLI prints that id verbatim — there is no snap_ prefix anywhere in the cloud source. The same placeholder is used on content/3.cloud/05.cloud-snapshots.md, so fixing one page should fix both.
+  - *Fix:* Use a UUID-shaped placeholder (or a generic <snapshot-id> as the CLI reference does) on both this page and Cloud Snapshots.
+- [x] **[redundant/low]** 2. Look inside the snapshot and 3. Restore (lines 72-109) — The browse/show and restore command blocks duplicate the Cloud Snapshots reference nearly verbatim, including the same example paths, so the two pages can drift apart.
+  - *Evidence:* content/3.cloud/05.cloud-snapshots.md "Browse Snapshot Contents" and "Restore Files" show the identical commands and examples (`bm cloud snapshot browse snap_abc123 --prefix notes/`, `bm cloud restore notes/important.md --snapshot snap_abc123`, `bm cloud restore research/ --snapshot snap_abc123`). The duplication is arguably deliberate (how-to vs reference, with a cross-link at line 48), but any fix to the path-prefix problem must be applied to both pages or they will contradict each other.
+  - *Fix:* Keep the how-to steps but trim to one canonical example per action and lean on the existing cross-link to Cloud Snapshots for the full command variants — or at minimum keep the examples byte-identical across the two pages when editing.
+
+### content/3.cloud/12.file-history.md
+
+- [x] **[incorrect/medium]** ## Restore (or merge) an old version → ### When Apply is disabled, third bullet ("Current file version changed; refresh before applying.") — The page lists "Current file version changed; refresh before applying" as a state that grays out the Apply button, but in the product this is a server error returned after you click Apply — the button is never disabled for this condition.
+  - *Evidence:* In basic-memory-cloud, the canApply computed (apps/web-v2/app/components/notes/NoteVersionHistoryPanel.vue lines 52-62) gates Apply only on materialization, content loaded, latest-version selection, in-flight requests, and unsaved editor changes — there is no stale-version condition. The message is raised by the apply endpoint as an HTTP error (apps/cloud/src/basic_memory_cloud/services/web_v2_runtime.py line 1300, when the submitted baseVersionId no longer matches the current version) and is rendered in the panel's error alert after a failed Apply (verified by apps/web-v2/tests/NoteVersionHistoryPanel.test.ts lines 178-188, which mock a rejected applyNoteFileVersion call).
+  - *Fix:* Split the third bullet out of the "grays out Apply" list: explain that if someone (or something) writes the note while you're merging, clicking Apply fails with "Current file version changed; refresh before applying" — refresh history and reapply on top of the new current. Keep the first two bullets as the actual disabled states.
+- [x] **[incorrect/medium]** ## Who can see and use it, both bullets — The role parentheticals "(viewers, editors, owners)" and "(editors and owners)" read as exhaustive lists but omit the User Admin and Admin roles, contradicting the five-role model on the Teams page.
+  - *Evidence:* content/4.teams/1.about.md (lines 34-38) documents five roles — Viewer, Editor, User Admin, Admin, Owner — where User Admin and Admin can do "everything an editor can" plus more, so they also have edit access and can apply versions. The underlying rule stated in prose is correct (the cloud service checks read access for listing/reading versions and write access for apply: require_write=False at apps/cloud/src/basic_memory_cloud/services/web_v2_runtime.py lines 1173 and 1225, require_write=True at line 1274), but the parenthetical role enumerations are incomplete.
+  - *Fix:* Drop the parentheticals or rephrase to match the role model: "View history — anyone with read access (Viewer and above). Apply a version — anyone with edit access (Editor and above)."
+- [x] **[redundant/medium]** Intro paragraph (line 6, "Every saved version of a note is preserved automatically…") — The entire opening paragraph is duplicated word-for-word on the What's New cloud page, where it can silently drift from this page.
+  - *Evidence:* content/2.whats-new/4.cloud.md line 38 contains the identical paragraph verbatim ("Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note… distinct from [Snapshots](/cloud/cloud-snapshots), which are project-wide point-in-time backups."), and that copy doesn't even link to /cloud/file-history.
+  - *Fix:* On the What's New cloud page, replace the copied paragraph with a one-line summary plus a link to /cloud/file-history (matching the pattern already used in content/3.cloud/02.web-app.md line 165).
+
+### content/3.cloud/13.cloud-cli.md
+
+- [x] **[confusing/medium]** ## Sync Cloud with local files (code block, lines 122-130) — The example sequence looks copy-paste runnable, but `bm cloud sync-setup research ~/Documents/research` fails with "Project 'research' not found on cloud" unless a Cloud project named 'research' already exists — a prerequisite the page never states.
+  - *Evidence:* src/basic_memory/cli/commands/cloud/project_sync.py setup_project_sync: docstring says "Configure local sync for an existing cloud project" and _verify_project_exists raises ValueError(f"Project '{name}' not found on cloud") before configuring anything. The linked Cloud Sync page (content/3.cloud/03.cloud-sync.md, step 3) covers creating the project first via `bm project add research`, but this page's sequence skips that step without mentioning it.
+  - *Fix:* Add a brief note before the code block, e.g. "These commands assume the Cloud project already exists — create one in the web app or with `bm project add`", or add the create step to the sequence.
+
+## Teams
+
+
+### content/4.teams/1.about.md
+
+- [x] **[incorrect/high]** Roles table, Admin row (line 37) — The Admin row claims admins can manage snapshots, but snapshots on team workspaces are Owner-only.
+  - *Evidence:* All snapshot endpoints in basic-memory-cloud/apps/cloud/src/basic_memory_cloud/api/bucket_snapshots.py use ResolvedWorkspaceForOwnerDep, and resolve_workspace_for_owner (deps.py:2092-2116) raises 403 for any non-owner role in organization workspaces. The web app confirms: apps/web-v2/app/utils/snapshot-workspaces.ts returns true for an org workspace only when `workspace.role === 'owner'`, and the Snapshots settings page shows "No personal or owner-managed team is available for snapshots."
+  - *Fix:* Move snapshot management from the Admin row to the Owner row (e.g., Owner: "...plus manage billing, snapshots, rename team, and transfer ownership").
+- [x] **[incorrect/high]** Roles table, Admin row (line 37) — The table presents audit-log access as an Admin-and-above capability, but User Admins can also view audit logs.
+  - *Evidence:* basic-memory-cloud/apps/cloud/src/basic_memory_cloud/api/audit_logs.py gates access with {OWNER, ADMIN, USER_ADMIN} (line 28) and its docstring says "Owners, admins, and user admins can access audit logs." The web app empty state (apps/web-v2/app/pages/settings/audit-logs.vue:338) says "Audit logs are available to team owners, admins, and user admins."
+  - *Fix:* Move "view audit log" to the User Admin row; keep API keys (owner/admin per api_keys.py require_api_key_workspace_owner) on the Admin row.
+- [x] **[incorrect/medium]** Roles table, Viewer row (line 34) — "Read-only access to projects and notes" overstates the restriction — a Viewer granted edit access on a shared project can write to it.
+  - *Evidence:* resolve_workspace_for_edit in basic-memory-cloud/apps/cloud/src/basic_memory_cloud/deps.py (lines 2004-2007) documents: "Viewer role check (writes only): viewers can only write to their own private project or shared projects with edit access" — and the #1367 fix explicitly exists so "an org viewer who holds an edit-level share on a shared project" is not blocked. This also matters because the page's own Projects section says shared projects grant per-person view or edit access.
+  - *Fix:* Qualify the Viewer row, e.g. "Read-only access to workspace projects (can edit a shared project if granted edit access on it)".
+- [x] **[confusing/high]** Roles section screenshot (line 48, v2-settings-teams) — The screenshot placed under the roles/statuses discussion is captioned "Team members list" but actually shows the Settings → Teams page (Team Details, billing contact, Transfer Ownership, Seat Usage) — no members, roles, or statuses are visible, so it illustrates nothing the surrounding text describes.
+  - *Evidence:* Viewed public/screenshots/cloud-app/v2-settings-teams-light.png: it is the Teams settings page with Team Details and Seat Usage cards. The actual members list with role dropdowns and Active badges is public/screenshots/cloud-app/v2-team-invite-light.png, used later in the Inviting section.
+  - *Fix:* Use a members-list screenshot here (the v2-team-invite image shows roles and statuses) or move this Teams-settings screenshot to the Seats and billing / owner-actions sections it actually depicts.
+- [x] **[redundant/high]** Roles table (lines 32-39) — The full five-role capabilities table is duplicated verbatim on the Joining a Team Workspace page, so corrections must be made twice and the copies will drift.
+  - *Evidence:* content/4.teams/2.join-a-team.md lines 33-39 contain the identical table, row for row — including the same Admin-row errors about snapshots and audit logs, showing the two copies already carry shared mistakes.
+  - *Fix:* Keep the canonical roles table on this page and replace the copy in join-a-team.md with a short summary plus a link to /teams/about#roles.
+- [x] **[redundant/medium]** Inviting members steps 2-4 ("They receive an email" / "They accept" / "Account linking", lines 94-113) — The invitee-side acceptance walkthrough (open email, accept link, sign in with invited email, re-sign-in if on a different account, account linking) duplicates section "1. Accept the invitation" on the Joining a Team page — which this page already defers to via the tip at line 120.
+  - *Evidence:* content/4.teams/2.join-a-team.md lines 14-22 cover the same sequence nearly sentence-for-sentence ("If you're already signed in with a different account, the app will prompt you to sign in again with the invited email" / "On first sign-in, your account is linked to the pending membership, and you become an active team member").
+  - *Fix:* Trim this page's steps to the inviter's side (send invitation, seat claimed on accept) and point invitee details at /teams/join-a-team, which the existing tip already does.
+- [x] **[confusing/medium]** Inviting members steps (lines 82-101) — The invite step sequence is muddled: the standalone sentence "To invite a member, click the 'Invite Member' button" duplicates step 1, the orphan line "Click the accept button." dangles at the end of step 2 ("They receive an email") even though it describes the invitee action that step 3 ("They accept") then restates, and step 1's screenshot alt calls the Invite Member dialog a "Team invitation email".
+  - *Evidence:* Lines 82, 101, and 91 of the page; verified that v2-team-invitation-light.png is the Invite Member modal (email + role + Send Invitation), not an email, while the actual email screenshot is v2-team-accept-invite-email.png in step 2.
+  - *Fix:* Fold line 82 into step 1, move "Click the accept button." into step 3 (or delete it since step 3 already says the link opens an accept page), and correct step 1's screenshot alt to "Invite Member dialog".
+
+### content/4.teams/2.join-a-team.md
+
+- [x] **[incorrect/high]** Section 'Targeting the team workspace explicitly', final paragraph (line 70) — The page tells readers to 'use a project-prefixed permalink' to target a team project and avoid ambiguity with a same-named personal project, but a project-only prefix does not disambiguate workspaces — resolution prefers the default workspace or errors when the project name exists in multiple workspaces.
+  - *Evidence:* basic-memory/src/basic_memory/mcp/project_context.py: ambiguous project-permalink matches prefer the default workspace or raise "Project '{project}' exists in multiple workspaces. Use: {choices}" (~lines 1028-1041); explicit workspace targeting uses the workspace-qualified form `<workspace-slug>/<project>/<path>` / `memory://<workspace>/<project>/<path>` (_split_workspace_identifier_segments, lines 446-467). Additionally, the linked page content/6.concepts/4.memory-urls.md contains zero mentions of 'workspace', so it cannot answer the workspace-targeting question this section poses.
+  - *Fix:* Replace 'use a project-prefixed permalink' with 'use a workspace-qualified memory URL (memory://<workspace-slug>/<project>/<path>)' — and either document that form on the memory-urls page or link to where it is documented.
+- [x] **[redundant/high]** Section '2. Find the projects', roles table (lines 33-39) — The full 5-row roles table is duplicated verbatim from the Teams about page, so any future role change must be made in two places and the copies will drift.
+  - *Evidence:* content/4.teams/1.about.md lines 34-38 contain the identical table text word-for-word, including the Owner row detail 'A team can have only one member with the Owner role.'
+  - *Fix:* Replace the table with a one- or two-line summary (e.g., 'Roles range from read-only Viewer to Owner') plus a link to the roles section on /teams/about as the single source of truth.
+- [x] **[incorrect/medium]** Section '4. Get oriented', third bullet (line 80) — The bullet says to 'Pin the projects or notes you'll come back to', but the web app only supports pinning notes — projects cannot be pinned.
+  - *Evidence:* basic-memory-cloud/apps/web-v2: pin mutations are note-scoped (usePinNoteMutation/useUnpinNoteMutation take projectName + notePath in features/notes/mutations.ts; stores/sidebar-pinned-notes.ts; api listPinnedNotes). No project-pin mutation or API exists in the app source.
+  - *Fix:* Change to 'Pin the notes you'll come back to.'
+- [x] **[confusing/medium]** Section '1. Accept the invitation', bullet list (lines 18-20) — The bullets present 'Sign in with the email the invite was sent to' as the first action on the accept page, but the actual flow is accept first, then WorkOS sign-in — a reader landing on the accept page looking for a sign-in prompt will instead see an Accept button.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/pages/accept-invite.vue UI copy: 'After you accept, Basic Memory will take you through WorkOS sign in so the invitation can be linked to the right account' and 'We're continuing to authentication so the invited email can finish joining the workspace.'
+  - *Fix:* Reorder the step: click Accept on the accept page, then complete the sign-in you're routed through using the invited email (creating an account if you don't have one); keep the note about being asked to re-authenticate if signed in with a different account.
+
+### content/4.teams/3.copy-between-workspaces.md
+
+- [ ] **[incorrect/high]** "What about renaming or restructuring?" (line 117) — Claims that within a single workspace you can rename and move notes and folders freely from the app or with move_note, but both are limited to a single project — moving between projects in the same workspace is not supported by either.
+  - *Evidence:* move_note.py docstring (src/basic_memory/mcp/tools/move_note.py, line 398): "Move a note or directory to a new location within the same project." The web app's MoveNoteDialog.vue (basic-memory-cloud/apps/web-v2) filters the folder picker to `project.projectId !== currentProjectId.value ? continue`, i.e. same-project only. The page itself says earlier (line 84) "MCP doesn't expose an atomic cross-project or cross-workspace move", so this section contradicts its own MCP section.
+  - *Fix:* Change "Within a single workspace" to "Within a single project", and note that moving between projects — even in the same workspace — uses the same copy pattern (read → write → delete) or export/import.
+- [ ] **[incorrect/medium]** "Copy via local sync (power-user)", step 1 (line 106) — Step 1 shows `bm cloud pull` with no `--name` flag, but `--name` is a required option, so the command as written fails; step 3 shows the flag, making step 1 look like a complete command when it isn't.
+  - *Evidence:* src/basic_memory/cli/commands/cloud/project_sync.py line 443: `name: str = typer.Option(..., "--name", "--project", help="Project name to pull")` — Ellipsis default makes the option required, so bare `bm cloud pull` errors with a missing-option message.
+  - *Fix:* Write the command explicitly: "Run `bm cloud pull --name <project>` for each of the two projects so both are up to date locally."
+- [ ] **[confusing/high]** "Copy with MCP", first bullet (line 94) — "workspace-qualified routing" is unexplained jargon and misleading here: of the three tools in the example, only write_note accepts a `workspace` parameter — read_note and delete_note do not, so a reader trying to disambiguate the read or delete call by workspace will fail.
+  - *Evidence:* src/basic_memory/mcp/tools/read_note.py and delete_note.py signatures have `project` and `project_id` but no `workspace` parameter (only write_note, edit_note, create_memory_project, delete_project take `workspace`). The tools' own docstrings recommend `project_id`: "Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces."
+  - *Fix:* Replace "workspace-qualified routing" with the concrete mechanism: pass `project_id` (the project UUID from list_memory_projects), which routes to the exact project even when names collide across workspaces; keep the project-prefixed permalink suggestion.
+- [ ] **[confusing/medium]** "Copy a whole project" → "Import the ZIP" step (line 41) — "Pick the writable target project (or create a new one)" implies you can create a project from within the Import flow, but the Import page only lists existing writable projects — there is no create-project option there.
+  - *Evidence:* basic-memory-cloud/apps/web-v2/app/pages/settings/import.vue has no create-project affordance; project selection is computed from existing `writableProjects` only. Project creation lives under Settings → Projects (per content/3.cloud/02.web-app.md line 179).
+  - *Fix:* Reword to: "Pick the writable target project. If it doesn't exist yet, create it first under Settings → Projects, then return to Import."
+- [ ] **[confusing/low]** Frontmatter description (line 3) — The description says "between personal, team, and local workspaces", but "local workspace" is not a product concept — workspaces are Personal and Teams; local is a sync location/transport — and the page's workflows only cover cloud workspace-to-workspace copies.
+  - *Evidence:* Product UI labels workspaces as "Personal" and "Teams" (Settings → Teams hub); the local-sync section of this page uses local paths only as a transport between two cloud projects, never as a destination "workspace".
+  - *Fix:* Change the description to "Move notes, folders, or whole projects between personal and team workspaces using export/import, MCP, or local sync."
+
+### content/4.teams/4.partners.md
+
+- [x] **[incorrect/high]** Customer SSO and automatic provisioning — final paragraph (line 96) — The page says JIT provisioning is off by default when you add a customer, but new managed customers default to JIT ON.
+  - *Evidence:* basic-memory-cloud/apps/cloud/src/basic_memory_cloud/models/partner.py:333-335 — comment 'New managed customers default to JIT-on for the onboarding happy-path' with `jit_provisioning_enabled ... default=True`; API schema default True (schemas/partner_customers.py:23); Add-customer form defaults the toggle on, citing issue #1228 (apps/web-v2/app/components/partner/PartnerCustomerFormModal.vue:32-36).
+  - *Fix:* Invert the guidance: JIT is on by default for new customers, so users from the verified domain will auto-provision (and consume a seat) as soon as SSO is active — turn JIT off before setting up SSO if you don't want that.
+- [x] **[incorrect/high]** Customer SSO and automatic provisioning — numbered steps 1–2 (lines 88-89) — Steps are in the wrong order: the docs say to click Start SSO setup first and verify the email domain second, but the UI requires domain verification first and hides the SSO setup row until a domain is verified.
+  - *Evidence:* apps/web-v2/app/components/partner/PartnerCustomerSsoPanel.vue:30-33 — 'Domain verification is the operator's entry point ... the panel leads with the verify control and reveals the SSO setup row only once a domain is verified'; template comments label domain verify as Step 1 and the setup-portal row as Step 2, gated by v-if="domainVerified".
+  - *Fix:* Reorder: 1. Verify the customer's email domain. 2. Click Start SSO setup (appears once a domain is verified) to open the WorkOS setup portal. 3. Optionally require SSO.
+- [x] **[incorrect/medium]** Customer SSO and automatic provisioning — warning box about the 5-minute link expiry (lines 92-94) — The warning describes receiving a setup-portal link you could open later or email, but clicking the button opens the WorkOS Admin Portal directly in a new tab — no copyable link is ever handed out.
+  - *Evidence:* apps/web-v2/app/components/partner/PartnerCustomerSsoPanel.vue:84-87 — 'WorkOS Admin Portal links expire ~5 minutes after generation, so the portal opens immediately instead of handing out a copyable link'; the row's own helper text says 'Opens the WorkOS Admin Portal in a new tab ... do it there, or on a screen-share with their IT admin', and the button label is 'Open setup portal'.
+  - *Fix:* Rewrite to match the UI: clicking opens the setup portal directly in a new tab (links expire in ~5 minutes, so there's nothing to copy or email); complete the identity-provider setup yourself or on a screen-share with the customer's IT admin.
+- [x] **[incorrect/medium]** Partner staff roles table — Admin row (line 59) — The Admin row says admins manage 'billing', but Admins cannot purchase seats (Add seats) — the account_capacity.purchase capability is granted only to Owner and Billing roles, and the Add seats button is hidden from Admins.
+  - *Evidence:* apps/cloud/src/basic_memory_cloud/services/partner_authorization_service.py:58-76 — PARTNER_CAP_ACCOUNT_CAPACITY_PURCHASE appears in the OWNER and BILLING capability sets but not ADMIN; apps/web-v2/app/pages/partner/billing.vue:25,113 gates the 'Add seats' button on that capability. The docs' own Billing row lists 'seat purchases' as a billing function, so 'manage billing' for Admin implies a permission Admins lack.
+  - *Fix:* Qualify the Admin row, e.g. 'Manage customers, SSO, team, and billing (except seat purchases — Owner and Billing only)'.
+- [x] **[incorrect/medium]** Managing customers — intro sentence 'Each customer row shows its status, workspace, seat cap, and SSO/JIT state' (line 70) — The Customers list row shows a JIT column but no SSO state — SSO status only appears on the customer's detail page.
+  - *Evidence:* apps/web-v2/app/pages/partner/customers/index.vue:120-195 — table headers are Customer, Status, Workspace, Seat cap, JIT, Billing label; only jit_provisioning_enabled is rendered as an icon, with no SSO column or badge in the row.
+  - *Fix:* Say the row shows status, workspace, seat cap, and JIT state (plus billing label); note that SSO state is on the customer's detail page.
+- [x] **[confusing/medium]** Managing customers — 'Transparency for your customers' note (lines 78-80) — The note implies all actions partner staff take 'inside a customer's workspace' appear in the customer's audit trail, but only a fixed subset of account-level actions is customer-visible (customer created/suspended/reactivated/archived and SSO transitions); billing-metadata updates are deliberately internal-only.
+  - *Evidence:* apps/cloud/src/basic_memory_cloud/models/audit_log.py:79-96 — CUSTOMER_VISIBLE_PARTNER_ACTIONS is limited to lifecycle and SSO actions, with a comment that partner_customer.updated 'stays internal-only because its details carry the MSP's billing metadata'; audit_log_repository.py applies the same visibility subset to customer reads.
+  - *Fix:* Scope the claim: administrative actions your staff take on a customer — lifecycle changes (create, suspend, reactivate, archive) and SSO changes — appear in the customer's audit trail, labeled as performed by their MSP.
+
+## Local
+
+
+### content/5.local/1.local-install.md
+
+- [x] **[redundant/high]** Install the CLI + Start the MCP server sections (lines 10-41) — The install commands, the brew-trust explanatory note (verbatim, word-for-word), and the claude_desktop_config.json snippet are all duplicated from content/1.start-here/3.quickstart-local.md.
+  - *Evidence:* The ::note text "`brew trust` tells Homebrew you accept code from this third-party tap..." is byte-identical in both files (this page line 23, quickstart-local line 33), and the same uv/brew commands and identical mcpServers JSON appear in quickstart-local lines 26-79. Commit history already shows drift risk: #28 had to patch the brew trust step into multiple pages at once.
+  - *Fix:* Keep one canonical copy (quickstart-local is the fuller one) and have this page either link to it or reduce the shared note/config to a cross-reference, so future Homebrew/config changes only need one edit.
+- [x] **[redundant/high]** Choose where notes live (lines 43-50) — The default-location explanation and the project add/default commands are triplicated: the same content appears on the very next page in this section (5.local/2.getting-started.md, "Choosing Where Notes Are Saved") and again in quickstart-local ("Change where notes are saved").
+  - *Evidence:* 2.getting-started.md lines 30-56 open with the same sentence pattern ("By default, Basic Memory saves notes in a project called `main` in `~/basic-memory`") and the same two commands; quickstart-local lines 216-224 repeat them again. The copies have already drifted in form (`bm project add` here vs `basic-memory project add` on the other two pages).
+  - *Fix:* Cover project location once (getting-started or cli-basics) and replace this section with a one-line pointer, or make this page the canonical short version and trim the duplicate from getting-started.
+- [x] **[confusing/medium]** Start the MCP server (lines 26-41) — The page offers Homebrew as an install method but the only MCP config shown uses `uvx`, which a Homebrew-only install does not provide — the reader who followed the Homebrew tab hits a dead end (ENOENT) with no alternative config.
+  - *Evidence:* The Homebrew formula (basicmachines-co/homebrew-basic-memory Formula/basic-memory.rb) declares `depends_on "uv" => :build` (build-time only, not installed for users) and installs the `basic-memory` binary via `bin.install_symlink`; so `"command": "uvx"` fails for Homebrew users. quickstart-local at least carries an ENOENT warning; this page has none.
+  - *Fix:* Add a Homebrew variant of the config (`"command": "basic-memory", "args": ["mcp"]`, noting GUI apps may need the full /opt/homebrew/bin path) or a note directing Homebrew users accordingly.
+- [x] **[confusing/medium]** Start the MCP server (lines 26-41) — The section heading says "Start the MCP server" but the content configures an MCP client; the snippet is Claude Desktop-specific (claude_desktop_config.json) yet the page never says where that file lives or how users of other MCP clients (VS Code, Cursor, etc.) should connect.
+  - *Evidence:* quickstart-local includes the config file locations table (macOS/Windows/Linux paths, lines 62-66) that makes the same snippet actionable; this page shows only the filename label. Neither the prose nor the Next steps cards link to the integrations section for other clients.
+  - *Fix:* Rename the heading to something like "Connect your MCP client", state the config file location (or link to quickstart-local / the Claude Desktop integration page), and add a pointer to /integrations for other clients.
+
+### content/5.local/2.getting-started.md
+
+- [x] **[redundant/high]** ## Multi-Project Setup (lines 70-112) — The entire Multi-Project Setup section is duplicated nearly verbatim in content/5.local/5.user-guide.md under 'Multi-Project Workflows' (lines 215-249): the identical 4-step 'How it works' list, the identical example conversation, and the identical default_project JSON snippet.
+  - *Evidence:* user-guide.md lines 219-224 repeat word-for-word 'When you start a conversation, the AI will: 1. Check your available projects 2. Suggest the most active project based on recent activity 3. Ask which project to use for this conversation 4. Remember your choice throughout the session'; lines 227-237 repeat the same 'Let's work on documentation' dialogue; lines 243-247 repeat the same {"default_project": "main"} snippet. The copies are already drifting (user-guide adds a closing Claude line and punctuation differences).
+  - *Fix:* Keep a two-sentence summary plus the 'Creating projects' commands here, and link to the User Guide's Multi-Project Workflows section (and/or /concepts/projects-and-folders) for the conversation flow and default_project details, so the canonical copy lives in one place.
+- [x] **[confusing/medium]** ### Use Your Existing Notes Folder (lines 38-46) and Multi-Project Setup example (lines 83-91) — Natural-language prompts to the AI assistant ('Create a new project called...', 'Set the default project to...', and the example conversation) are fenced as ```bash code blocks, so they render as shell commands with copy buttons, and a first-time reader may paste them into a terminal.
+  - *Evidence:* Lines 38-40: ```bash\nCreate a new project called "my project" in the "/Users/yourname/Documents/Notes" directory\n``` — this is English prose, not a bash command, and it sits directly above a real bash block (lines 50-56) using the same fence style. The dialogue at lines 83-91 has the same problem.
+  - *Fix:* Use ```text fences (or blockquotes) for AI prompts and conversation transcripts, reserving ```bash for actual shell commands.
+- [x] **[confusing/medium]** **For users who primarily work in one project:** (lines 102-112) — The page tells readers to hand-edit ~/.basic-memory/config.json to set default_project, even though the same page showed the CLI command for exactly this (`basic-memory project default "my project"`, line 55) and the note at line 65 says CLI commands are recommended over editing the file; a new reader can't tell whether these are two different mechanisms.
+  - *Evidence:* Line 65: 'While CLI commands are recommended for configuration, you can edit this file directly.' Then lines 104-110 instruct a direct config.json edit for default_project — verified in source that `basic-memory project default` writes the same config.default_project value (config.py set_default_project, lines 1070-1078).
+  - *Fix:* Show the CLI command (basic-memory project default "main") in the multi-project section instead of the JSON edit, or add a sentence noting it is the same setting the earlier CLI command writes.
+
+### content/5.local/3.cli-basics.md
+
+- [x] **[confusing/medium]** Search notes > "Semantic modes:" code block (lines 31-36) — Presenting --hybrid and --vector as opt-in "Semantic modes" implies the plain search example above is keyword-only, but hybrid semantic search is already the default when semantic search is enabled (which it is in standard installs).
+  - *Evidence:* src/basic_memory/mcp/tools/search.py _default_search_type(): "auto-detect (hybrid if semantic enabled, else text)"; config.py semantic_search_enabled defaults to true when local semantic dependencies exist; docs page 6.concepts/7.semantic-search.md line 146 says semantic search is "included and enabled by default in all standard Basic Memory installs" and line 44 calls hybrid "the default hybrid search". A first-time reader will conclude they must pass --hybrid to get semantic results.
+  - *Fix:* Add one sentence such as: "When semantic search is enabled (the default), plain searches already run in hybrid mode; use these flags to force a specific retrieval mode" — or retitle the block to "Force a retrieval mode".
+- [x] **[confusing/low]** Read and write notes > read-note example (line 41) — The only read-note example on the page uses a .md file path ("docs/api-auth.md") as the identifier, while every other docs page teaches permalinks or titles (CLI reference uses "specs/api-notes"), leaving new readers unsure whether the .md extension is required.
+  - *Evidence:* content/9.reference/1.cli-reference.md line 513 uses `bm tool read-note "specs/api-notes"` (permalink, no extension); read_note's own help describes the identifier as "title or permalink". The .md path does work (services/link_resolver.py resolves by file_path), so this is an inconsistency rather than an error.
+  - *Fix:* Use a permalink-style identifier consistent with the CLI reference, e.g. `bm tool read-note "docs/api-auth"`, or note that titles, permalinks, and file paths are all accepted.
+
+### content/5.local/4.mcp-tools-local.md
+
+- [x] **[incorrect/high]** Line 21, paragraph after 'Common tools' list — The page claims output_format="text" is "the default" for all tools, but build_context — listed on this same page — defaults to "json".
+  - *Evidence:* src/basic_memory/mcp/tools/build_context.py:173: `output_format: Literal["json", "text"] = "json"`. The docs' own reference page (content/9.reference/2.mcp-tools-reference.md:24) also states: "`build_context` defaults to `\"json\"`; most other tools default to `\"text\"`".
+  - *Fix:* Change the sentence to say most tools default to "text" (build_context defaults to "json"), or drop the default claim and defer to the MCP Tools Reference for per-tool defaults.
+- [x] **[confusing/medium]** 'Common tools' list, build_context bullet (line 19) — "memory URL graph traversal" is unexplained jargon on first use, with no link to the concepts page that defines memory URLs.
+  - *Evidence:* A first-time reader in the Local section has no definition of "memory URL" on this page; a dedicated page exists at content/6.concepts/4.memory-urls.md (/concepts/memory-urls) but is not linked here (only Knowledge Format is linked in Next steps).
+  - *Fix:* Link the term, e.g. "`build_context` for graph traversal via [memory:// URLs](/concepts/memory-urls)".
+- [x] **[confusing/low]** 'Use tools in local mode' section (lines 8-10) — The section heading promises usage guidance but contains a single sentence that restates the intro, and "When you run the local MCP server" gives no pointer to how to run or configure that server.
+  - *Evidence:* Lines 6 and 10 say nearly the same thing ("operate on folders on your machine" / "read and write local project folders by default"); the actual server setup (MCP client config running `basic-memory mcp`) lives in content/5.local/1.local-install.md under 'Start the MCP server' and is not linked. "by default" also hints at per-project cloud routing without explanation or link.
+  - *Fix:* Link to the local install page's MCP server setup (e.g. "See [Local install](/local/local-install#start-the-mcp-server) to configure your MCP client") and either explain or drop "by default" (or link per-project cloud routing docs).
+
+### content/5.local/5.user-guide.md
+
+- [x] **[incorrect/high]** Force Re-sync (lines 483-491) and Troubleshooting > Changes Not Syncing step 4 (line 573) — The page says plain `basic-memory reset` will "Reset and rebuild database" and the warning claims it "rebuilds the entire database from your files", but without --reindex the command only deletes and recreates an empty index database.
+  - *Evidence:* src/basic_memory/cli/commands/db.py: reset() takes `reindex: bool = typer.Option(False, "--reindex", help="Rebuild db index from filesystem")` and prints "This only deletes the index database... Use bm reset --reindex to automatically rebuild the index afterward." Rebuild from files only runs inside `if reindex:`. The docs' own CLI reference (content/9.reference/1.cli-reference.md lines 110-116) documents --reindex as the rebuild flag.
+  - *Fix:* Change the command to `basic-memory reset --reindex` (or state that after a plain reset the index stays empty until the next sync/reindex), and reword the warning to attribute the rebuild to --reindex. Apply the same fix to the Troubleshooting step "Reset database: basic-memory reset".
+- [x] **[incorrect/high]** Enhanced Editing > Incremental Editing > "Available operations" (lines 347-352) — The "Available operations" list for edit_note presents four operations as the complete set but omits insert_before_section and insert_after_section.
+  - *Evidence:* src/basic_memory/mcp/tools/edit_note.py line 308: tool description reads "operations like append, prepend, find_replace, replace_section, insert_before_section, or insert_after_section" — six operations, matching the verified product truth.
+  - *Fix:* Add `insert_before_section` and `insert_after_section` to the operations list (e.g., "insert_before_section / insert_after_section - Insert content adjacent to a section heading").
+- [x] **[redundant/high]** Troubleshooting section (lines 566-600) — The Changes Not Syncing, Claude Can't Find Knowledge, Performance Issues, and moving-notes-between-projects guidance duplicates content/9.reference/5.troubleshooting.md almost step-for-step (same four steps for sync issues, same four steps for search issues, same db-size/archive/sync-delay steps, same cross-project workaround).
+  - *Evidence:* content/9.reference/5.troubleshooting.md sections "Changes Not Syncing" (lines 112-133), "Claude Can't Find Knowledge" (lines 176-205), "Slow Operations" (lines 228-254), and "Moving Notes Between Projects" (line 346) contain the identical steps and commands; two copies of concrete command sequences will drift (the reset-vs-reset --reindex discrepancy is already an example).
+  - *Fix:* Trim the user-guide Troubleshooting to the two or three most common symptoms with one-line fixes, and link to /reference/troubleshooting for the full runbook.
+- [x] **[redundant/medium]** Working with Memory URLs > URL Formats (lines 144-169) — The memory:// URL formats block duplicates the dedicated Memory URLs concept page, and the two lists have already drifted — this page omits project-prefixed URLs (memory://project/path) while the concept page omits the relation-traversal form listed here — and this section never links to the concept page.
+  - *Evidence:* content/6.concepts/4.memory-urls.md covers the same ground in depth (title/permalink, path, wildcard, project-prefixed forms) but neither page's format list matches the other's; the user-guide section has no cross-link to /concepts/memory-urls.
+  - *Fix:* Keep the short conversational example and the stability tip, replace the URL-formats code block with one or two examples, and link to /concepts/memory-urls for the full addressing syntax.
+- [x] **[confusing/low]** Working with Memory URLs > tip (line 168) — The tip says the permalink stays the same "(unless you configure otherwise)" without naming the setting or linking anywhere, leaving a new reader unable to find or act on the exception.
+  - *Evidence:* The behavior is controlled by `update_permalinks_on_move` (src/basic_memory/config.py, default False), but the page gives no name or link; a first-time reader has no path from "configure otherwise" to the actual option.
+  - *Fix:* Name the setting, e.g. "(unless you enable `update_permalinks_on_move` — see [Configuration](/reference/configuration))".
+
+## Concepts
+
+
+### content/6.concepts/0.vs-built-in-memory.md
+
+- [x] **[confusing/high]** Getting started — "Integrations" card (line 129, to: /integrations/claude-desktop) — The card titled "Integrations" with the tool-agnostic description "Connect Basic Memory to your AI tool" links to the Claude Desktop guide specifically, not the integrations index, even though the page gives equal weight to Claude, Claude Code, ChatGPT, and Cursor.
+  - *Evidence:* The link is `to: /integrations/claude-desktop`, but a routable integrations index exists at /integrations (content/7.integrations/0.index.md, titled "Connect AI tools") and is what other pages link to for this purpose (e.g., content/0.welcome.md line 64 `to: /integrations`, content/4.teams/2.join-a-team.md line 51). A ChatGPT or Cursor user clicking "Integrations" lands on Claude Desktop setup instead of the picker.
+  - *Fix:* Change the card link to `to: /integrations` so readers land on the tool-picker index page.
+- [x] **[confusing/low]** What each tool offers — Claude Code "Auto memory" bullet (line 19) — `MEMORY.md` appears with no introduction — the bullet says memories are "stored in ~/.claude/projects/ as markdown files" and then jumps to "the first 200 lines of MEMORY.md load into every session" without explaining that MEMORY.md is the index file of that memory directory.
+  - *Evidence:* First-time-reader issue: the sentence "The first 200 lines of `MEMORY.md` load into every session" has no antecedent; a reader who hasn't used Claude Code's auto memory can't tell whether MEMORY.md is one of the auto-written files, a file they must create, or something else.
+  - *Fix:* Add a short clause, e.g. "Stored in ~/.claude/projects/ as markdown files, indexed by a MEMORY.md file whose first 200 lines load into every session."
+
+### content/6.concepts/1.knowledge-format.md
+
+- [x] **[incorrect/high]** Frontmatter section, permalink bullet (line 62) — Claims the permalink is "Generated automatically from the title if you don't set one" — it is actually generated from the file path (folder + filename) and, by default, prefixed with the project slug.
+  - *Evidence:* generate_permalink() in basic-memory src/basic_memory/utils.py derives from the file path (docstring: generate_permalink("docs/My Feature.md") -> 'docs/my-feature'); resolve_permalink() in src/basic_memory/services/entity_service.py (lines 198-224) calls build_canonical_permalink(project_permalink, file_path_str, ...) for new files, with permalinks_include_project defaulting to True in config.py. The sibling page content/6.concepts/2.projects-and-folders.md confirms with examples like memory://work/architecture/auth-system.
+  - *Fix:* Change to: "Generated automatically from the file's path (and prefixed with the project name by default) if you don't set one. Stays the same even if you later move the file."
+- [x] **[incorrect/high]** Permalinks section (line 131) — States a permalink is "a stable identifier derived from its title" — permalinks are derived from the file path with an optional project prefix, not the title.
+  - *Evidence:* Same source evidence as above: generate_permalink()/build_canonical_permalink() in src/basic_memory/utils.py and resolve_permalink() in src/basic_memory/services/entity_service.py operate on file paths; permalinks_include_project defaults to True. The bare memory://authentication-design example only matches because the page's sample note sets permalink explicitly in frontmatter — a generated permalink would look like project/folder/authentication-design, as shown on the projects-and-folders page.
+  - *Fix:* Change to "derived from its file path (project-prefixed by default)" and note that the stability guarantee (permalink unchanged on rename/move) is the default behavior, which the source confirms (update_permalinks_on_move defaults to False).
+- [x] **[incorrect/high]** Tip after intro (line 11) — Link [Web Editor](/cloud/cloud-guide#web-editor) points to an anchor that does not exist, and "Web Editor" is not a label used anywhere else in the docs.
+  - *Evidence:* grep of content/3.cloud/01.cloud-guide.md shows no "Web Editor" heading (its sections are Setup with Claude, Web App, Command Line Tools, etc.); "Web Editor"/#web-editor appears nowhere in content/ except this line. Cloud note editing is documented on content/3.cloud/02.web-app.md under "Editing notes" (rich editor).
+  - *Fix:* Link to the web app page instead, e.g. "...or edit them directly in the [web app](/cloud/web-app#editing-notes)."
+- [x] **[redundant/medium]** File Organization section (lines 141-156) — The "organize files however you want; the graph ignores folder structure" message plus example folder tree duplicates the "Folders within a project" section on the Projects and Folders page.
+  - *Evidence:* content/6.concepts/2.projects-and-folders.md lines 63-77 make the identical claim ("Inside a project, organize however you like... The knowledge graph does not care about folder structure") with a near-identical example tree and the same "flat folder works too" conclusion.
+  - *Fix:* Trim this section to one or two sentences and cross-link to /concepts/projects-and-folders for the full discussion of folders and organization.
+- [x] **[redundant/low]** Relations section, relation-type quoting rule (line 106) — The full quoting rule (single-token types, quote multi-word types, unquoted prose/bare wikilinks fall back to generic links_to) is restated verbatim on the Observations and Relations deep-dive page that this page already defers to.
+  - *Evidence:* content/6.concepts/3.observations-and-relations.md line 69 states the same rule with the same example pattern ("A relation type is a single token... quote it — \"depends on\" [[Caching Layer]]... indexed as a generic links_to connection"), including the v0.21.0 change note. This is a versioned parser behavior spec duplicated in two places and could drift; the rule itself is verified correct against parse_relation_type() in src/basic_memory/markdown/plugins.py.
+  - *Fix:* Keep only "The word before the link becomes the relationship type" here and defer the quoting/links_to edge cases to the existing cross-link to /concepts/observations-and-relations.
+
+### content/6.concepts/2.projects-and-folders.md
+
+- [x] **[incorrect/high]** Creating and managing projects — line 43 ("The AI will call `switch_project` behind the scenes.") — There is no `switch_project` MCP tool; the AI targets a different project by passing the `project` (or `project_id`) parameter on each tool call.
+  - *Evidence:* grep for switch_project across /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory returns zero hits; src/basic_memory/mcp/tools/project_management.py defines only list_memory_projects, create_memory_project, and delete_project, and tools like write_note/build_context take a per-call project/project_id parameter (build_context.py:183-192).
+  - *Fix:* Replace with: the AI will simply pass `project="personal"` on subsequent tool calls (discoverable via `list_memory_projects`); there is no switch tool to invoke.
+- [x] **[incorrect/high]** Creating and managing projects — line 46 (`bm project switch "personal"`) — `bm project switch` is not a real CLI command.
+  - *Evidence:* src/basic_memory/cli/commands/project.py registers only: list, add, remove, default, move, set-cloud, set-local, ls, info. The docs' own CLI reference (content/9.reference/1.cli-reference.md) also has no `bm project switch` entry.
+  - *Fix:* Drop the CLI sentence and code block, or replace with `bm project default "personal"` (changing the fallback project for commands that don't specify one).
+- [x] **[incorrect/high]** What is a project? — line 14 ("it targets whichever project is currently active. You can switch projects at any time") — Describes a session-level "active project" that gets switched, but no such state exists — each MCP tool call resolves its project independently (explicit project parameter, else the default project).
+  - *Evidence:* build_context.py:183-185: "Server resolves projects using a unified priority chain... Single Project Mode → project parameter → default project. Uses default project automatically." write_note.py likewise takes project/project_id per call. No switch mechanism exists anywhere in the source.
+  - *Fix:* Reword to: each command or tool call targets the project you name (via a project parameter or CLI argument); if you don't specify one, it goes to the default project. You can target a different project at any time, including mid-conversation.
+- [x] **[incorrect/medium]** Project-prefixed permalinks — lines 89-96 — Prefixing is not triggered by "when you have multiple projects" and is not applied to existing permalinks at index time — it is the `permalinks_include_project` setting (default on) applied when permalinks are generated, regardless of project count, and existing permalinks are left unchanged.
+  - *Evidence:* config.py:451-453: permalinks_include_project default True, "generated permalinks are prefixed with the project slug... Existing permalinks remain unchanged unless explicitly updated." The sibling page content/6.concepts/4.memory-urls.md states it correctly ("With project-prefixed permalink behavior enabled (default)"), so this page contradicts it.
+  - *Fix:* Say: by default, Basic Memory prefixes newly generated permalinks with the project name so notes with the same title in different projects stay distinct; existing permalinks are not rewritten. Keep the cross-link to Memory URLs for details.
+- [x] **[confusing/medium]** When to use multiple projects — lines 60-61 ("If you're unsure, start with one project...") — The closing advice line has no blank line separating it from the bullet list, so it renders as a continuation of the "A writing project" bullet instead of a standalone paragraph.
+  - *Evidence:* Line 61 immediately follows the last list item on line 60 with no blank line; Markdown lazy continuation folds it into the bullet, attaching general advice to the writing-project example.
+  - *Fix:* Insert a blank line between line 60 and line 61.
+- [x] **[confusing/medium]** Mixing local and cloud projects — line 81 ("Starting in v0.19, ...") — Version-floor framing ("Starting in v0.19") conflicts with the docs policy of no version floors and reads as stale now that the feature is standard (current release v0.22.1); the linked routing guide is version-agnostic.
+  - *Evidence:* Docs policy for this repo avoids hard-coded version floors; content/3.cloud/08.routing.md contains no version framing, making this page the outlier and a drift risk.
+  - *Fix:* Drop the version clause: "You can keep some projects local and route others to Basic Memory Cloud."
+
+### content/6.concepts/3.observations-and-relations.md
+
+- [x] **[incorrect/high]** Enforcing structure with schemas — line 107 ("The schema validates notes when they're written and flags anything that's missing.") — Schema validation does not run automatically at write time; it is on-demand via the schema_validate MCP tool, the /schema/validate API endpoint, or `bm schema validate`.
+  - *Evidence:* In the product source, validate_note() (src/basic_memory/schema/validator.py) is called only from the on-demand endpoint src/basic_memory/api/v2/routers/schema_router.py (lines 170, 206); grep shows no schema-validation call in write_note.py, entity_service.py, or the sync path. The docs' own schema-system page (content/6.concepts/6.schema-system.md) likewise describes validation as an explicit action (`bm schema validate ...`, "AI: [Validates all person notes]") with a warn mode that "reports what's missing but doesn't block anything" — not a write-time check.
+  - *Fix:* Reword to match actual behavior, e.g.: "You can then validate notes on demand — ask your AI to check them (the schema_validate tool) or run `bm schema validate` — and the report flags anything that's missing. Validation warns by default rather than blocking writes."
+
+### content/6.concepts/4.memory-urls.md
+
+- [x] **[incorrect/high]** Resolution behavior > 1. Project constraints (line 81: "all URLs are resolved within the `research` project regardless of any prefix in the URL") — The claim that a BASIC_MEMORY_MCP_PROJECT constraint resolves all URLs in the constrained project "regardless of any prefix" is wrong — a URL prefixed with a different known project is rejected with an error, not resolved in the constrained project.
+  - *Evidence:* src/basic_memory/mcp/project_context.py resolve_project_and_path (lines 1349-1390): when the URL's first segment resolves to a known project that differs from the constrained project, the code raises ValueError(f"Project is constrained to '{resolved_project}', cannot use '{project_prefix}'."). Only prefix-free URLs (or URLs prefixed with the constrained project itself) resolve in the constrained project.
+  - *Fix:* Reword to: URLs without a project prefix (and URLs prefixed with the constrained project) resolve in the constrained project; URLs prefixed with a different project return an error ("Project is constrained to 'research', cannot use 'main'").
+- [x] **[incorrect/high]** Resolution behavior > Project-prefix extraction (line 106: "When `permalinks_include_project` is enabled (the default), Basic Memory checks whether the first path segment of a URL matches a known project name") — Project-prefix detection in memory URLs is not conditioned on the `permalinks_include_project` setting — it runs unconditionally; that setting only controls whether generated permalinks include the project slug.
+  - *Evidence:* src/basic_memory/mcp/project_context.py: _split_project_prefix and the project-resolve attempt in resolve_project_and_path (lines 1344-1349) run regardless of config; detect_project_from_url_prefix (lines 1438-1464) never reads permalinks_include_project. config.py:451-454 describes the flag as controlling generated permalink prefixes only. The same conflation appears in the intro at line 38 ("With project-prefixed permalink behavior enabled (default), memory URLs can include project scope").
+  - *Fix:* Drop the config-conditional phrasing: state that Basic Memory always checks whether the first path segment matches a known project name, and (if the setting is worth mentioning) note that `permalinks_include_project` governs permalink generation, linking to the configuration reference.
+- [x] **[confusing/medium]** Resolution behavior > Project-prefix extraction (lines 104-114) — This unnumbered subsection follows the numbered steps 1-3 and reads like a fourth resolution step, but it restates step 2 ("Explicit project prefix") with different framing, leaving readers unsure whether it is a separate stage or an elaboration of step 2.
+  - *Evidence:* Step 2 (lines 87-94) says "The first path segment is compared against known project names" unconditionally; the extraction section (line 106) re-describes the same mechanism but adds a config condition, so the two passages describe one mechanism with contradictory conditions.
+  - *Fix:* Merge the extraction detail (segment stripping diagram, fallback when no project matches) into step 2 and remove the standalone subsection.
+- [x] **[confusing/medium]** Cross-project references in links (lines 49-63) — The section shows bare `project::note-path` and `project/note-path` code blocks with no example of where this syntax is actually written (e.g., inside a `[[wiki-link]]` relation or a memory:// URL), so a first-time reader cannot tell how or where to use it.
+  - *Evidence:* The prose says only "Within notes, project namespace syntax is normalized" without a concrete note example; the source shows the syntax is used in wiki-links (src/basic_memory/services/link_resolver.py lines 134-156 resolves `project::note` links) and in memory URL paths (project_context.py:1300 applies normalize_project_reference to memory URL paths).
+  - *Fix:* Add a concrete usage example, e.g. a relation line `- relates_to [[research::specs/api]]` in a note, and mention the syntax also works inside memory:// URLs.
+- [x] **[confusing/low]** Basic forms > By title/permalink (lines 14-18) — The heading promises addressing "by title" but the single example is permalink-shaped (`auth-approaches-2024`), leaving readers unsure whether a human-readable title (with spaces/capitals) works in a memory URL.
+  - *Evidence:* Title resolution does work (link_resolver.py falls back to exact title match, and normalize_memory_url in schemas/memory.py permits spaces), but the page never shows a title-form example, so the "title" half of the heading is unillustrated.
+  - *Fix:* Either add a title example (e.g. `memory://Auth Approaches 2024`) or retitle the subsection "By permalink" and note that titles also resolve.
+
+### content/6.concepts/5.canvas.md
+
+- [x] **[confusing/high]** Creating Canvas Visualizations — line 13 ("Example Requests" bullet) — Three example requests are collapsed into a single run-on bullet with inline hyphens, rendering as one garbled line instead of a list.
+  - *Evidence:* Source reads: `- **Example Requests** — - "Create a canvas visualization of my project components and their relationships." - "Make a concept map showing the main themes from our discussion about climate change." - "Can you make a canvas diagram of the perfect pour over method?"` — in Markdown this is one list item, so the inner `- "..."` markers render as literal dashes mid-sentence. Looks like a migration artifact where sub-bullets were flattened.
+  - *Fix:* Restore the sub-list: put "Example Requests" as a lead-in line (or bold label) with each of the three quoted requests as its own bullet on its own line.
+- [x] **[confusing/medium]** Types of Visualizations — "### Relationship Networks" subsection (lines 26-28) — "Relationship Networks" is clearly a fifth visualization type, but it appears as a lone subheading with a one-line body while the other four types are bullets in a list, breaking the section's structure and reading as an orphaned fragment.
+  - *Evidence:* Lines 19-24 introduce "several types of visual maps" as a 4-item bullet list (Document Maps, Concept Maps, Process Diagrams, Thematic Analysis); line 26 then switches to an `###` heading for Relationship Networks with the same em-dash-description pattern as the bullets, suggesting it was meant to be a fifth bullet.
+  - *Fix:* Convert "### Relationship Networks" into a fifth bullet in the list above: `- **Relationship Networks** — Show how different entities relate to each other in your knowledge base`.
+
+### content/6.concepts/6.schema-system.md
+
+- [x] **[incorrect/high]** CLI reference section, line 508-509 ("Save the inferred schema as a note" / `bm schema infer person --save`) — The docs present `bm schema infer person --save` as saving the inferred schema as a note, but the --save flag is not implemented — it prints a notice telling the user to copy the schema manually.
+  - *Evidence:* src/basic_memory/cli/commands/schema.py lines 320-324: `if save: console.print(f"\n[yellow]--save not yet implemented. Copy the schema above into schema/{note_type}.md[/yellow]")` — the flag exists but performs no save.
+  - *Fix:* Remove the `--save` example (and its comment) from the CLI reference block, or replace it with guidance to copy the suggested schema output into a schema note until --save ships.
+- [x] **[incorrect/high]** Validation section, mode table line 107 ("Off | No checking | Temporarily disable while restructuring") — The docs claim `validation: off` disables checking, but no code path implements an "off" mode — the validator only branches on "strict" versus everything else, so "off" behaves identically to warn (warnings are still produced).
+  - *Evidence:* src/basic_memory/schema/validator.py lines 102-143: every diagnostic uses `if schema.validation_mode == "strict": errors else: warnings` with no off/skip branch; grep for '"off"' across src finds it only in a parser docstring comment (parser.py:54, 287). Additionally, bare YAML `off` parses as boolean False, which also falls into the warn branch.
+  - *Fix:* Remove the Off row from the mode table (and the "Temporarily disable while restructuring" advice) until an off mode actually skips validation, or reword to say only warn and strict are honored today.
+- [x] **[incorrect/high]** Validating frontmatter fields section (lines 463-494) and Complete example (lines 582-591), the `$ bm schema validate ...` transcripts — The shown terminal output (`✓ grace-hopper: valid (0 warnings)`, `⚠ iris-west: frontmatter field 'status' enum mismatch (got 'archived', expected one of: draft, published)`, `⚠ hank-pym: missing required frontmatter field: status`, `⚠ ada-lovelace: missing required field: name`) does not match what the CLI actually prints — real output is a Rich table with Note/Status/Warnings/Errors columns plus a summary line, and the warning message text is only visible via --json with different wording.
+  - *Evidence:* src/basic_memory/cli/commands/schema.py `_render_validate_table` (lines 49-83) renders a table titled "Schema Validation: ..." with warning/error counts only, never per-note check-mark lines. Actual message strings in src/basic_memory/schema/validator.py: "Frontmatter key 'status' has invalid value: archived (allowed: ...)" (line 289), "Missing required frontmatter key: status" (line 128), "Missing required field: name (expected [name] observation)" (line 343).
+  - *Fix:* Replace the fabricated transcripts with the real table-plus-summary output (or trim to just the command and a prose description of the result), and align quoted warning texts with the actual validator messages.
+- [x] **[confusing/high]** Validating frontmatter fields section, lines 468-481 (Iris West enum-mismatch example) — The "value outside the allowed enum" example uses `status: archived` with the comment "# not in [draft, published]" and an error saying "expected one of: draft, published", but the schema defined two code blocks earlier declares `status?(enum): [draft, published, archived]` — so per the page's own schema, `archived` is a valid value and would not fail.
+  - *Evidence:* Line 435 of the page: `status?(enum): [draft, published, archived]`; line 474: `status: archived   # not in [draft, published]`. The example silently drops `archived` from the enum, contradicting the surrounding prose and confusing readers about how enums work.
+  - *Fix:* Use a value genuinely outside the declared enum (e.g., `status: retired`) or change the example schema's enum to `[draft, published]` consistently across the section.
+- [x] **[incorrect/medium]** "Writing with schema guidance" (line 81) and "Roll your own" (line 221): "your AI uses it as a creation guide automatically... without you having to ask" / "The AI reads your schemas automatically when creating notes of that type" — The page states as fact that the AI automatically consults schemas when creating notes, but no product mechanism does this — write_note performs no schema lookup and the MCP server injects no schema context at creation time; the behavior depends entirely on the assistant's setup (e.g., the memory-schema skill being installed and invoked).
+  - *Evidence:* src/basic_memory/mcp/tools/write_note.py contains no schema resolution or guidance logic (schema mentions are only a custom-frontmatter example); schema-guided creation is instructed only by the optional memory-schema skill (basic-memory monorepo skills/memory-schema/SKILL.md).
+  - *Fix:* Soften both claims to conditional/instructional language, e.g., "AI assistants can read your schema notes and use them as a creation guide — ask your assistant to check the schema, or install the memory-schema skill to make this automatic."
+
+### content/6.concepts/7.semantic-search.md
+
+- [x] **[incorrect/medium]** Intel Mac workaround > Option 2: Pin ONNX Runtime (lines 299-304) — The command `uv pip install 'onnxruntime<1.24'` will not affect the environments created by the install methods this page assumes (Homebrew and `uv tool install`/`uvx`), so the workaround as written likely does nothing for those users.
+  - *Evidence:* This same page (line 146) says standard installs are Homebrew and uv. `uv pip install` targets an active virtualenv, not a uv tool's isolated environment (that requires `uv tool install basic-memory --with 'onnxruntime<1.24'` or `uvx --with 'onnxruntime<1.24' basic-memory mcp`) and cannot modify Homebrew's bundled Python env. The product repo doc (basic-memory/docs/semantic-search.md line 40) pins it at install time in a single pip environment: `pip install basic-memory 'onnxruntime<1.24'`.
+  - *Fix:* Give per-install-method commands: `uv tool install basic-memory --with 'onnxruntime<1.24'` for uv installs (and `uvx --with 'onnxruntime<1.24' basic-memory mcp` for MCP configs), and tell Homebrew users to use the OpenAI option or switch to a uv install.
+- [x] **[incorrect/medium]** Configuration table (line 231), Embedding providers section (lines 252-265), and FAQ 'Can I use a different embedding model?' (lines 360-362) — The page presents `"fastembed"` and `"openai"` as the only embedding providers, but the shipped release also supports a `litellm` provider for custom embedding models.
+  - *Evidence:* basic-memory/src/basic_memory/repository/embedding_provider_factory.py dispatches `provider_name == "litellm"` (litellm_provider.py, added in v0.22.0 via #809 and contained in the v0.22.0/v0.22.1 tags), with related config fields (semantic_embedding_forward_dimensions, document/query input types) described in config.py. No docs page mentions litellm, so the FAQ's 'You can switch between FastEmbed (local, free) and OpenAI (API, paid)' understates the shipped options. May be an intentional docs omission, hence medium confidence.
+  - *Fix:* Either add a short LiteLLM subsection under Embedding providers, or soften the table wording to 'common values: fastembed, openai' (as the reference/configuration page already does) so the list isn't presented as exhaustive.
+- [x] **[confusing/medium]** Under the Hood > How results are ranked (lines 196-198) — The one-sentence 'Search results return whole notes ranked by relevance' directly contradicts the preceding Chunking section, which says a search 'can surface the specific fact ... rather than returning the entire Coffee Brewing Methods note', and it oversimplifies: results are search items that can also be individual observations and relations, not only whole notes.
+  - *Evidence:* Chunking section (line 194) vs line 198 on the same page. Source: the CLI exposes `--entity-type` with values 'entity, observation, relation' (basic-memory/src/basic_memory/cli/commands/tool.py lines 542-548), and hybrid fusion is keyed on (type, id) across those row types (search_repository_base.py ~line 2260).
+  - *Fix:* Reword to reconcile both statements, e.g.: 'Results are returned as note-level items (plus individual observations and relations) ranked by their best-matching chunks; the matched chunk text shows which part of the note was most relevant.'
+- [x] **[confusing/medium]** Reindexing section (lines 308-329) — The section labels plain `bm reindex` as 'Rebuild both search index and embeddings' and recommends reindexing for 'Troubleshooting', but the default run is an incremental scan that skips unchanged content — a true fresh rebuild requires `--full`, which the page never mentions, so the troubleshooting advice may do nothing.
+  - *Evidence:* basic-memory/src/basic_memory/cli/commands/db.py reindex help: 'By default runs incremental search + embeddings... Use --full to bypass incremental scan optimization, rebuild all file-backed search rows, and re-embed all eligible notes'; reindex_vectors only clears vectors when force_full=True (search_service.py lines 640-685). The page's own Deduplication section says unchanged chunks skip re-indexing, compounding the contradiction.
+  - *Fix:* Add `bm reindex --full` to the command list ('Force a full rebuild, re-embedding everything') and point the Troubleshooting bullet at `bm reindex --full`.
+- [x] **[redundant/medium]** Configuration section table (lines 226-236) — The seven-row semantic settings table (fields, defaults, env vars) fully duplicates the 'Semantic search settings' section of the Configuration reference page, which this page already links to — two complete copies that can drift.
+  - *Evidence:* content/9.reference/6.configuration.md lines 103-168 documents the identical seven settings (semantic_search_enabled through semantic_min_similarity) with the same defaults and env var names; the concepts page even ends the section with 'See Configuration for the full config reference.'
+  - *Fix:* Trim the concepts-page table to the settings a user actually tunes here (semantic_embedding_provider, semantic_min_similarity, semantic_search_enabled) and defer the rest to the Configuration reference.
+
+### content/6.concepts/8.metadata-search.md
+
+- [x] **[incorrect/high]** Convenience shortcuts — 'Multiple tags in the shorthand' code block (lines 131-135) — The example claims `search_notes("tag:tier1 alpha")` (space-separated) requires BOTH tags to be present, but the tool-level parser only captures the token attached to `tag:`, so this call filters on tag `tier1` and treats `alpha` as a leftover text query.
+  - *Evidence:* src/basic_memory/mcp/tools/search.py lines 941-951: `raw_values = re.findall(r"tag:(\S+)", query, ...)` captures only "tier1" from "tag:tier1 alpha"; the remainder "alpha" is kept as the text query (`remainder = re.sub(r"tag:\S+", "", query...)`; `query = remainder or None`). Multiple tags require comma-separation (`tag:tier1,alpha`, split on comma at line 944) or repeated tokens (`tag:tier1 tag:brewing`, per the source comment at line 938). The service-layer space-splitting parser (search_service.py line 166) never sees the raw query because the MCP tool strips it first.
+  - *Fix:* Replace the space-separated example with the repeated-token form: `search_notes("tag:tier1 tag:alpha")   # repeated tag: tokens`, and keep the comma form. Optionally note that a bare word after a tag: token is treated as ordinary query text, not a tag.
+- [x] **[incorrect/medium]** Filter syntax → Operator reference table (line 101, `$gt`/`$gte`/`$lt`/`$lte` row) — The table says comparison operators take a "number", but the implementation also accepts strings and performs lexicographic comparison (e.g., ISO date strings for date ranges), and the page's own prose two lines above says "Numeric or lexicographic comparison".
+  - *Evidence:* src/basic_memory/repository/metadata_filters.py lines 102-117: non-numeric comparison values are normalized with comparison="text" and compared lexicographically (no cast in sqlite_search_repository.py lines 925-930). The same applies to `$between` (lines 119-128 support text pairs). The page's own prose under "Comparison" (line 73) says "Numeric or lexicographic comparison", contradicting the table.
+  - *Fix:* Change the Value column for the comparison row to "number or string (lexicographic; dates as ISO strings)" — and consider the same clarification for `$between`.
+- [x] **[confusing/low]** Intro paragraph (line 6) — The intro promises the reader can ask "find decisions made in the last quarter with priority high or critical", but the page never shows a date-based filter example (e.g., `{"date": {"$gte": "2026-04-01"}}`) or mentions `after_date`, and the operator table implies comparisons are number-only, leaving a first-time reader unable to reproduce the teased query.
+  - *Evidence:* No worked example or syntax example on the page uses a date value; the only hint is one line in "Type handling" ("Dates and datetimes are normalized to ISO strings"). Combined with the operator table's "number" constraint, the date-range use case advertised in the opening sentence is undemonstrated.
+  - *Fix:* Add one date-range row to the worked-examples table, e.g. "Decisions since April → {\"type\": \"decision\", \"date\": {\"$gte\": \"2026-04-01\"}}", noting dates compare as ISO strings.
+
+## Integrations
+
+
+### content/7.integrations/0.index.md
+
+- [x] **[incorrect/high]** Codex card in 'Recommended Cloud Connections' (line 49) — The card says 'Use Basic Memory from the Codex app, CLI, and IDE extension', but the linked page documents only two Codex surfaces and never mentions an IDE extension.
+  - *Evidence:* content/7.integrations/5.codex.md states 'Codex comes in two forms, and both connect to Basic Memory: Codex app ... Codex CLI' and contains no IDE-extension content; grep across all of content/ shows 'IDE extension' appears only on this index card.
+  - *Fix:* Change the card text to 'Use Basic Memory from the Codex app and CLI.' (or add IDE-extension coverage to the Codex page before advertising it).
+- [x] **[confusing/medium]** Claude card in 'Recommended Cloud Connections' (line 31) — The card promises setup for 'Claude on the web, Claude Desktop, and Claude mobile apps', but the linked page (titled 'Claude Desktop') documents only Claude Desktop — a reader looking for web or mobile connection steps finds nothing.
+  - *Evidence:* content/7.integrations/1.claude-desktop.md (146 lines) has zero mentions of mobile, claude.ai, or web-surface setup; its instructions are 'In Claude Desktop, go to Settings > Claude > Connectors'.
+  - *Fix:* Either narrow the card text to Claude Desktop, or add a short note on the target page that a custom connector added to your Claude account is also available on claude.ai and the mobile apps.
+- [x] **[confusing/medium]** Opening tip block (lines 8-16) — The tip points readers to 'the web app's Connect your agent flow' without saying where it lives (the onboarding guide and the Help sheet), and the Web App docs page separately documents a similarly named 'Connect Agent' editor button that is a different feature (starting a live in-app agent session), so first-time readers can conflate the two or fail to find the flow.
+  - *Evidence:* In the cloud repo, the 'Connect your agent' walkthrough is rendered by OnboardingSheet.vue and the Help sheet (ConnectAgent.vue: 'shared by the Help sheet and onboarding'); meanwhile content/3.cloud/02.web-app.md line 118 documents 'Click **Connect Agent** in the editor to start or resume an agent session' — a distinct feature.
+  - *Fix:* Say where the flow is found, e.g. 'the Connect your agent walkthrough in the web app's onboarding guide and Help sheet (replay via Settings → General → Show onboarding)'.
+
+### content/7.integrations/1.claude-desktop.md
+
+- [x] **[incorrect/high]** Troubleshooting > Changes not showing up (line 95) — The page tells users to "run the watcher manually: `basic-memory watch`", but no `watch` command exists in the CLI.
+  - *Evidence:* Grep of /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/cli/ shows "watch" only inside the skip_init_commands set in app.py:99; no watch command is registered in main.py or commands/__init__.py. Source comment in commands/status.py explains indexing only runs inside a live server (bm mcp / hosted API) and directs users to `bm reindex` instead. This page is the only docs page referencing `basic-memory watch`.
+  - *Fix:* Replace the line with the actual recovery path, e.g. "If the index is stale, rebuild it with `bm reindex`" (and note that file watching runs automatically inside the MCP server).
+- [x] **[incorrect/medium]** Cloud Setup > Add Remote MCP Connector (line 19) — The button label is given as "Add connector", but the Claude Desktop UI button (and every other docs page describing it) is "Add custom connector".
+  - *Evidence:* content/1.start-here/2.quickstart-cloud.md line 45 and content/3.cloud/01.cloud-guide.md both say "Click **Add custom connector**" for the identical step; this page alone says "Click \"Add connector\"".
+  - *Fix:* Change to "Click **Add custom connector**" to match the UI and the other pages.
+- [x] **[redundant/high]** Cloud Setup section (lines 10-41) — The four connector-setup steps (settings path, add connector with name/URL, OAuth authenticate, verify tools) duplicate the same walkthrough on two other pages, and the copies have already drifted.
+  - *Evidence:* content/1.start-here/2.quickstart-cloud.md ("For Claude Desktop" steps, lines 36-67) and content/3.cloud/01.cloud-guide.md ("Setup with Claude" steps) contain the same procedure with more detail (Configure Tools step, different screenshots) and a different button label ("Add custom connector" vs this page's "Add connector"). Ironically, cloud-guide's tip points readers to this page "for detailed Claude setup instructions" even though this page's copy is the least detailed of the three.
+  - *Fix:* Pick one canonical location for the Claude Desktop connector walkthrough (this integration page is the natural home), align the step wording and screenshots, and have quickstart-cloud and cloud-guide link here instead of carrying their own copies.
+- [x] **[confusing/medium]** Troubleshooting > Tools appear but return errors / Changes not showing up / Project selection (lines 87-104) — After the first troubleshooting item explicitly splits Cloud vs Local, the remaining three subsections give exclusively local-install advice (basic-memory CLI commands, ~/basic-memory file permissions, editing ~/.basic-memory/config.json) without saying they only apply to local setups, so a cloud-connector user hitting tool errors is misdirected to check a local installation they don't have.
+  - *Evidence:* The page's primary setup path is the Cloud connector, yet "Tools appear but return errors" starts with "Check Basic Memory is installed: `basic-memory --version`" and "Project selection" tells all readers to edit `~/.basic-memory/config.json` — none of which exists for a cloud-only user.
+  - *Fix:* Label the local-only subsections (e.g. "(local setup)") or add a cloud branch to each, e.g. pointing cloud users at the web app Activity view / reconnecting the connector / the Cloud Guide troubleshooting section.
+
+### content/7.integrations/2.claude-code.md
+
+- [x] **[incorrect/high]** Troubleshooting > "Notes not syncing?" (line 91) — The page tells readers to look for errors in `~/.basic-memory/logs/`, but no such directory exists — Basic Memory writes a single log file at `~/.basic-memory/basic-memory.log`.
+  - *Evidence:* basic-memory source /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/utils.py lines 442-447: `log_filename = "basic-memory-{pid}.log" if os.name == "nt" else "basic-memory.log"` and `log_path = resolve_data_dir() / log_filename`, where resolve_data_dir() (config.py:68-84) returns `~/.basic-memory`. A grep of the entire src tree finds no `logs/` subdirectory. (The gemini integration page has the same wrong path.)
+  - *Fix:* Change to: Look for errors in `~/.basic-memory/basic-memory.log`.
+- [x] **[confusing/medium]** Cloud Setup steps 3-4 ("Authenticate" / "Verify", lines 23-27) — Step 3 says "Follow the OAuth flow in Claude Code" but never says how to trigger it — after `claude mcp add` nothing happens until the user opens Claude Code and runs `/mcp` to authenticate the server, which the page only introduces in step 4 as a verification step.
+  - *Evidence:* In Claude Code, HTTP MCP servers added via `claude mcp add -t http` require the user to run `/mcp`, select the server, and choose Authenticate to start the browser OAuth flow. A first-time reader at step 3 has no OAuth flow to follow, and at step 4 an unauthenticated server shows a needs-authentication state rather than a tool list.
+  - *Fix:* Merge or reorder: "In Claude Code, run `/mcp`, select basic-memory-cloud, and choose Authenticate to complete the OAuth flow in your browser. Then re-run `/mcp` to confirm the Basic Memory tools are listed."
+- [x] **[confusing/medium]** ::tip after Cloud Setup (line 31) — The tip points to the Cloud Guide "for detailed instructions and troubleshooting," but the Cloud Guide contains no Claude Code setup section (its Claude section covers the Claude Web/Desktop custom connector UI) and no troubleshooting section at all.
+  - *Evidence:* content/3.cloud/01.cloud-guide.md headings: "Setup with Claude" (Settings → Claude → Connectors, i.e. Claude Web/Desktop), "Setup with ChatGPT", "Web App", "Command Line Tools", "Upload Files to Cloud", "Cloud Snapshots", "Migrating to Cloud", "Next Steps" — no Claude Code instructions and no troubleshooting heading. A reader clicking through for Claude Code OAuth troubleshooting finds neither.
+  - *Fix:* Reword the tip to say what the Cloud Guide actually offers (web app, CLI, snapshots, migration), or point troubleshooting readers at /reference/troubleshooting instead.
+- [x] **[redundant/medium]** FAQ > "How does Basic Memory work alongside CLAUDE.md?" (lines 100-101) — This FAQ answer restates the "CLAUDE.md and Basic Memory" section from the same page nearly verbatim (both say CLAUDE.md holds instructions while Basic Memory holds "decisions, architecture notes, research, ... context"), and the first FAQ entry already covers the same ground with a link to the dedicated comparison page.
+  - *Evidence:* Line 73: "`CLAUDE.md` tells Claude Code *how* to work in a project, while Basic Memory stores the *knowledge* -- decisions, architecture notes, research, context"; line 101: "`CLAUDE.md` holds project instructions and coding standards. Basic Memory holds evolving knowledge — decisions, architecture notes, research, meeting notes, and context". The full comparison lives on content/6.concepts/0.vs-built-in-memory.md (/concepts/vs-built-in-memory), which FAQ entry 1 (line 98) already links. Three restatements on one page are likely to drift.
+  - *Fix:* Drop the second FAQ entry (or fold any unique phrase into the first FAQ entry), keeping the section at line 71 and the single cross-link to /concepts/vs-built-in-memory.
+
+### content/7.integrations/3.chatgpt.md
+
+- [x] **[incorrect/high]** Cloud Setup > Configure ChatGPT (line 21) — The UI path "Settings > Developer > Custom MCP Servers" does not exist in ChatGPT; custom MCP connectors are added via Settings → Apps & Connectors → Advanced settings → enable Developer mode, then a Create button appears to add a connector (Connector name / Description / Connector URL).
+  - *Evidence:* OpenAI Apps SDK docs (developers.openai.com/apps-sdk/deploy/connect-chatgpt): "Navigate to Settings → Apps & Connectors → Advanced settings... Toggle developer mode on... you'll see a Create button under Settings → Apps & Connectors." No "Custom MCP Servers" menu exists. The docs' own quickstart (content/1.start-here/2.quickstart-cloud.md line 77) gives yet another, also-outdated path ("Settings → Beta features and enable MCP").
+  - *Fix:* Rewrite the step to match ChatGPT's current flow: enable Developer mode under Settings → Apps & Connectors → Advanced settings, then click Create and enter the connector name and Connector URL (https://cloud.basicmemory.com/mcp).
+- [x] **[confusing/high]** Important Notes > "Default vs full MCP access" note (lines 55-61) — The note tells readers to "explicitly enable the Basic Memory MCP server in ChatGPT's developer settings" to unlock the full tool set, but the setup steps above already added the server through developer settings — a first-time reader can't tell what extra action distinguishes "default" (search/fetch only) from "full" access.
+  - *Evidence:* Setup step 3 (line 21) already routes through developer settings. Per OpenAI docs, the search/fetch-only limitation applies to standard connector contexts (e.g., deep research/chat search), while custom connectors added via Developer mode expose all tools in conversations — the note never explains this distinction, so the instruction reads as circular.
+  - *Fix:* Explain when each mode applies: connectors used in ChatGPT's standard search/deep-research contexts only call search and fetch; conversations with the Developer-mode connector enabled get the full tool set (write_note, edit_note, project management, etc.). Remove the circular "enable in developer settings" instruction.
+- [x] **[incorrect/medium]** Try It > Semantic search bullet (line 45) — The claim that semantic/conceptual search "requires full MCP access" is wrong: the default ChatGPT `search` tool delegates to search_notes with no search_type, which defaults to hybrid (semantic + text fusion) whenever semantic search is enabled on the server.
+  - *Evidence:* src/basic_memory/mcp/tools/chatgpt_tools.py lines 131-137 call search_notes(query=..., page=1, page_size=10, output_format="json") with no search_type; src/basic_memory/mcp/tools/search.py _default_search_type() returns "hybrid" when semantic search is enabled (config.py enables it by default when dependencies exist). Full MCP access is only needed to choose a mode explicitly.
+  - *Fix:* Drop the "(requires full MCP access)" parenthetical, or reword to say full access is needed only to pick a specific search mode (text/vector/hybrid) explicitly.
+- [x] **[incorrect/medium]** Important Notes warning + Troubleshooting (lines 52, 65) — "ChatGPT Plus or Pro subscription required" is over-restrictive: Developer mode / custom MCP connectors are also available on Business/Team, Enterprise, and Edu plans (only the free tier lacks them).
+  - *Evidence:* OpenAI Help Center (Developer mode and MCP apps in ChatGPT): Developer Mode is available on Plus, Pro, Team, Enterprise, and Edu plans; free ChatGPT does not support custom connectors. Related drift: content/1.start-here/2.quickstart-cloud.md line 72 and content/3.cloud/01.cloud-guide.md line 64 claim "Pro or Max subscription" — "Max" is not a ChatGPT plan, so the three pages contradict each other.
+  - *Fix:* Say a paid ChatGPT plan is required (Plus, Pro, Business/Team, Enterprise, or Edu) and that the free tier is not supported; align quickstart-cloud.md and cloud-guide.md with the same wording.
+- [x] **[redundant/medium]** Cloud Setup steps (lines 10-33) and tip (lines 35-37) — The ChatGPT cloud setup steps duplicate the "For ChatGPT" section of the Cloud Quickstart, and the two have already drifted — they give contradictory UI paths for the same procedure.
+  - *Evidence:* content/1.start-here/2.quickstart-cloud.md lines 69-88 contain a parallel ChatGPT setup (subscription note, enable MCP, add endpoint, OAuth) but instruct "Settings → Beta features and enable MCP" while this page says "Settings > Developer > Custom MCP Servers". content/3.cloud/01.cloud-guide.md line 67 already treats this page as the canonical ChatGPT guide.
+  - *Fix:* Make this page the single detailed ChatGPT setup; reduce the quickstart's ChatGPT section to a short summary plus a link here, so UI instructions live in one place.
+- [x] **[confusing/medium]** Tip after Cloud Setup (line 36) — The tip sends readers to the Cloud Setup Guide "for detailed instructions", but that guide's ChatGPT section points straight back to this page as the detailed guide, so a reader seeking more ChatGPT detail is bounced in a circle.
+  - *Evidence:* content/3.cloud/01.cloud-guide.md line 67: "For detailed ChatGPT setup instructions, see the [ChatGPT Integration](/integrations/chatgpt) guide."
+  - *Fix:* Scope the tip to what the cloud guide actually adds (account setup, web app, sync options), e.g. "See the Cloud Setup Guide for account and sync details" rather than "detailed instructions".
+
+### content/7.integrations/4.gemini.md
+
+- [x] **[incorrect/high]** Troubleshooting → "Notes not updating" (line 123) — Points readers to a nonexistent `~/.basic-memory/logs` directory; logs are written to the single rotated file `~/.basic-memory/basic-memory.log`.
+  - *Evidence:* src/basic_memory/utils.py setup_logging(): log_filename = "basic-memory.log" (per-PID files only on Windows) and log_path = resolve_data_dir() / log_filename; resolve_data_dir() in src/basic_memory/config.py:68 defaults to ~/.basic-memory. No logs/ subdirectory is ever created. (Same error exists in content/7.integrations/2.claude-code.md:91.)
+  - *Fix:* Change to "look for errors in `~/.basic-memory/basic-memory.log`".
+- [x] **[confusing/medium]** Troubleshooting → "Gemini can't find Basic Memory" (line 115) — Tells readers to verify installation with `basic-memory --version`, but the page's setup uses `uvx basic-memory mcp`, which never installs basic-memory globally — a reader who followed the page exactly gets "command not found" and is misled into thinking something is broken.
+  - *Evidence:* The install command on lines 63/78/83/118 runs basic-memory via uvx (ephemeral, not on PATH); the page never links to a local install step (contrast content/7.integrations/2.claude-code.md, which links Quickstart: Local before the add command). `basic-memory --version` only works after a real install.
+  - *Fix:* Use `uvx basic-memory --version` for the check, or add a note/link to the local Quickstart for installing basic-memory before the troubleshooting step assumes it.
+- [x] **[confusing/medium]** Cloud Setup → Authenticate step (lines 22-23) — The Authenticate step says "Follow the OAuth flow" but nothing the reader has done starts one — after `gemini mcp add`, no OAuth prompt appears until Gemini actually connects to the server, so a literal reader stalls at this step.
+  - *Evidence:* Verified with gemini CLI 0.44.0: `gemini mcp add -t http ...` only writes the server entry to settings.json and exits; no browser flow is triggered. Authentication happens when Gemini connects (launching `gemini` / running `/mcp auth basic-memory-cloud`), which the step never mentions.
+  - *Fix:* State the trigger, e.g. "Start `gemini` — your browser opens to authorize Basic Memory Cloud (or run `/mcp auth basic-memory-cloud` inside Gemini)".
+
+### content/7.integrations/5.codex.md
+
+- [x] **[redundant/high]** Remote MCP (Basic Memory Cloud) section — API key + ~/.codex/config.toml steps (lines 124-154) — The Codex CLI remote-MCP setup (create API key, export BASIC_MEMORY_API_KEY, config.toml snippet) is duplicated on content/3.cloud/07.api-keys.md ('With Codex CLI' section), and the two copies have already drifted: api-keys.md uses `[[mcp_servers]]` array-of-tables with a `name` field, while this page uses `[mcp_servers.basic-memory]`.
+  - *Evidence:* content/3.cloud/07.api-keys.md lines 71-84 show `[[mcp_servers]]` + `name = "basic-memory"`; this page shows `[mcp_servers.basic-memory]`. The codex page's form matches the basic-memory README (line 294) and Codex's actual config format (verified via installed codex CLI: `codex mcp add --url --bearer-token-env-var` writes `[mcp_servers.<name>]` tables), so the api-keys copy is the wrong one — but the duplication is what lets them disagree.
+  - *Fix:* Keep the full walkthrough on one page (this one is the correct, canonical version) and have api-keys.md link here instead of carrying its own drifted config.toml snippet; at minimum fix api-keys.md to the `[mcp_servers.basic-memory]` table form.
+- [x] **[confusing/medium]** Troubleshooting — 'Codex CLI can't find Basic Memory' bullet (line 186) — The first troubleshooting step says to verify Basic Memory is installed with `basic-memory --version`, but the CLI setup this page teaches uses `uvx basic-memory mcp`, which never installs `basic-memory` on PATH — a user who followed the guide exactly gets 'command not found' from this check even when their setup is working, and will chase a non-problem.
+  - *Evidence:* Setup command on lines 91 and 190 is `codex mcp add basic-memory bash -c "uvx basic-memory mcp"`; uvx fetches and runs the package ephemerally without putting `basic-memory` on PATH. Contrast with content/7.integrations/2.claude-code.md, where the same `basic-memory --version` check is paired with a setup that does require a local install.
+  - *Fix:* Replace the check with something valid for the uvx path, e.g. `uvx basic-memory --version`, or drop the install check and lead with `codex mcp list` plus re-adding the server.
+- [x] **[confusing/medium]** Connect to a local Basic Memory (local MCP) — 'Start a local server' step (lines 54-65) — The Codex-app local path tells readers to run `basic-memory mcp --transport streamable-http --port 8000` with no installation prerequisite or link anywhere on the page — a first-time reader who hasn't installed Basic Memory (the CLI section's uvx path doesn't install it) hits 'command not found' with no pointer to fix it.
+  - *Evidence:* The page never links local installation docs; the parallel page content/7.integrations/2.claude-code.md line 38 explicitly says 'Install Basic Memory locally ([Quickstart: Local](/start-here/quickstart-local))' before its first local command.
+  - *Fix:* Add an install prerequisite link (e.g. 'Install Basic Memory first — see [Quickstart: Local](/start-here/quickstart-local)') before the command, or show the no-install variant `uvx basic-memory mcp --transport streamable-http --port 8000`.
+
+### content/7.integrations/6.cursor.md
+
+- [x] **[incorrect/high]** Cloud Setup > step 'Configure Remote MCP in Cursor' (line 17) — The UI path 'Settings > Developer > Edit Config, select MCP Tools, click Add Custom MCP' is not Cursor's UI — it appears to graft Claude Desktop's menu path (Settings > Developer > Edit Config) onto Cursor, and the step sequence is incoherent (opening a config editor, then selecting a panel and clicking a button).
+  - *Evidence:* Cursor's current MCP docs (cursor.com/docs/context/mcp, fetched 2026-07-02) say custom servers are configured via a JSON file — project-level .cursor/mcp.json or global ~/.cursor/mcp.json — or installed one-click from the 'Customize' sidebar / Cursor Marketplace; no 'Settings > Developer > Edit Config' path exists in Cursor. That exact path is Claude Desktop's config flow.
+  - *Fix:* Replace with Cursor's actual mechanism, e.g.: 'Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root:' followed by the same JSON block, optionally noting it can also be added from Cursor Settings > MCP.
+- [x] **[incorrect/high]** Local Setup > step 'Configure MCP' (line 46) — The link https://docs.cursor.com/context/model-context-protocol is stale — it 308-permanent-redirects to the generic docs homepage (cursor.com/docs), not the MCP page, so readers lose the instructions the step depends on.
+  - *Evidence:* Fetched 2026-07-02: the URL returns '308 Permanent Redirect' to https://cursor.com/docs (docs root). The MCP documentation now lives at https://cursor.com/docs/context/mcp.
+  - *Fix:* Update the link to https://cursor.com/docs/context/mcp.
+- [x] **[confusing/medium]** Troubleshooting > 'MCP tools not appearing' / 'Tools appear but don't work' (lines 99-101) — Troubleshooting tells readers to verify installation with `basic-memory --version` and that `which basic-memory` resolves, but the Local Setup step just above marks installing Basic Memory as optional (uvx fetches and runs it without putting `basic-memory` on PATH) — so a user who followed the page exactly fails both checks even when their setup is fine.
+  - *Evidence:* Line 59: '### Install Basic Memory (optional)'; config uses `uvx basic-memory mcp`, which runs from uvx's isolated environment without a PATH install. (The commands themselves are real: `status` is registered in src/basic_memory/cli/app.py:92 and --version/-v in src/basic_memory/cli/main.py.)
+  - *Fix:* Reword the checks for the uvx path, e.g. 'verify uvx can run it: `uvx basic-memory --version`' and note that `which basic-memory` only applies if you installed it with uv tool/pip.
+- [x] **[confusing/medium]** Cloud Setup and Local Setup config steps (lines 17-27, 45-57) — Neither setup section tells the reader which file the JSON block goes into (~/.cursor/mcp.json or .cursor/mcp.json); the only pointer is the external Cursor docs link, which currently redirects to the wrong page, leaving a first-time reader with no working instruction.
+  - *Evidence:* The page shows two mcpServers JSON blocks with no file path anywhere; Cursor's docs (cursor.com/docs/context/mcp) specify project-level .cursor/mcp.json or global ~/.cursor/mcp.json as the configuration locations.
+  - *Fix:* Name the config file explicitly in both steps (global ~/.cursor/mcp.json, or project .cursor/mcp.json), keeping the external link as supplementary.
+
+### content/7.integrations/7.vscode.md
+
+- [x] **[incorrect/high]** Terminal CLI section, 'Write a quick note' example (line 118) — The example `bm tool write-note --title "API Design Decision" --folder "decisions"` fails when run in an interactive terminal because no content is supplied.
+  - *Evidence:* src/basic_memory/cli/commands/tool.py lines 121-130: when --content is omitted and stdin is a TTY, the command prints 'No content provided. Please provide content via --content or by piping to stdin.' and exits 1. In VS Code's integrated terminal (the exact context this section describes), stdin is a TTY, so a copy-paste of this example errors out.
+  - *Fix:* Add --content to the example (e.g. `bm tool write-note --title "API Design Decision" --folder "decisions" --content "..."`) or show the stdin form (`echo "..." | bm tool write-note --title ... --folder ...`).
+- [x] **[redundant/medium]** Cloud Sync Workflow section (lines 10-77) — The full seven-step cloud sync workflow (login, setup, project add --local-path, pull --dry-run, pull, edit, pull/push) duplicates the Quick Start on the Cloud Sync Guide and is repeated nearly verbatim on the Obsidian integration page.
+  - *Evidence:* content/3.cloud/03.cloud-sync.md 'Quick Start' covers the identical sequence (Enable Cloud Mode, Set Up Sync, Add Projects with Sync, Pull the Project Down, Daily Workflow); content/7.integrations/8.obsidian.md lines 14-72 contain the same ::steps block with only project names changed. Three copies of the same command sequence is exactly the kind of duplication that drifted when bisync was removed.
+  - *Fix:* Keep only the VS Code-specific parts (open the synced folder in VS Code, daily pull/push habit) and link to the Cloud Sync Guide for the full setup steps, or extract the shared workflow into a reusable snippet/component.
+- [x] **[confusing/medium]** Copilot Chat with MCP section (lines 129-131) — The section says to 'add Basic Memory as an MCP server in your VS Code settings' but never gives the Basic Memory server command or endpoint, so a first-time reader following the external VS Code link still doesn't know what to configure.
+  - *Evidence:* content/7.integrations/6.cursor.md provides both concrete configs (local: command `uvx` with args `["basic-memory", "mcp"]`; cloud: url `https://cloud.basicmemory.com/mcp`), while this page offers only a link to VS Code's generic MCP docs. The Basic Memory-specific half of the setup is missing.
+  - *Fix:* Include the local stdio config (`uvx basic-memory mcp`) and the cloud endpoint (https://cloud.basicmemory.com/mcp), or link to a Basic Memory docs page that contains them.
+- [x] **[confusing/medium]** Cloud Sync Workflow, note under 'Set Up Sync' (lines 34-36) — The prerequisite note 'Sync requires the Basic Memory CLI. See Local Installation' appears at step 3, but step 2 already has the reader running `bm cloud login` — a reader without the CLI installed hits 'command not found' before reaching the install pointer.
+  - *Evidence:* Steps out of order: 'Enable Cloud Mode' (line 18-23, runs `bm cloud login`) precedes the CLI installation note at lines 34-36.
+  - *Fix:* Move the CLI-installation note above the 'Enable Cloud Mode' step, or add an explicit 'Install the CLI' first step linking to /local/local-install.
+
+### content/7.integrations/8.obsidian.md
+
+- [x] **[incorrect/high]** Cloud Sync Workflow → step 'Create Project with Local Sync' (lines 42-51) — Both example commands (`bm project add my-vault --local-path ~/path/to/obsidian-vault` and `bm project add notes --local-path ~/Documents/notes`) fail as written because cloud project creation requires the explicit --cloud flag.
+  - *Evidence:* In basic-memory v0.22.1 (src/basic_memory/cli/commands/project.py, add_project): `effective_cloud_mode = cloud and not local` — cloud mode is flag-only. Without --cloud the command runs in local mode, where the positional path is required, and exits with "Error: path argument is required in local mode". This behavior dates to v0.19.0 (commit 0239f4ab, 'Simplify local/cloud routing').
+  - *Fix:* Add --cloud to both commands: `bm project add my-vault --cloud --local-path ~/path/to/obsidian-vault` and `bm project add notes --cloud --local-path ~/Documents/notes`. (The same fix is needed on the Cloud Sync Guide and VS Code pages, which share this command.)
+- [x] **[incorrect/high]** Cloud Sync Workflow → step 'Enable Cloud Mode' (lines 26-31) — The step claims `bm cloud login` enables cloud mode ("Authenticate and enable cloud mode"), but login only authenticates and verifies the subscription — there is no cloud-mode switch it flips.
+  - *Evidence:* src/basic_memory/cli/commands/cloud/core_commands.py login() runs the WorkOS OAuth device flow and a subscription health check only. src/basic_memory/config.py: cloud_mode is derived solely from the BASIC_MEMORY_CLOUD_MODE env var, and stale `cloud_mode` keys are actively removed from config files on load (`data.pop("cloud_mode", None)`). Routing is per-project (`bm project set-cloud`/`set-local`), not a global mode toggled by login.
+  - *Fix:* Retitle the step 'Log In to Basic Memory Cloud' and change the text to 'Authenticate with your Basic Memory Cloud account:' — drop the 'enable cloud mode' claim.
+- [x] **[confusing/medium]** Cloud Sync Workflow → step 'Pull Your Vault Down' (lines 53-62) — For the page's primary scenario — an existing Obsidian vault registered in the previous step — the freshly created cloud project is empty, so the "initial pull" transfers nothing and the vault's notes don't reach the cloud until a push; the flow never tells existing-vault users to push first.
+  - *Evidence:* Step 4 offers 'If you have an existing vault' as the first example, then step 5 says 'fetch the cloud files' from a project that was just created and contains no files. `bm cloud pull` is additive cloud→local (project_sync.py), so it cannot upload the vault. The upload only happens implicitly in step 7's `bm cloud push`.
+  - *Fix:* Split the step by scenario: existing vault → run `bm cloud push --name my-vault --dry-run` then `bm cloud push --name my-vault` to seed the cloud copy; notes already in cloud → run the pull commands as shown.
+- [x] **[redundant/medium]** Cloud Sync Workflow section (lines 14-79) — The entire 7-step setup sequence (login, setup, project add --local-path, dry-run pull, pull, push) duplicates the Cloud Sync Guide's Quick Start and is repeated nearly verbatim on the VS Code integration page, creating three copies that drift together.
+  - *Evidence:* content/3.cloud/03.cloud-sync.md 'Quick Start' covers the identical steps 1-5; content/7.integrations/7.vscode.md lines 18-68 contain the same headings ('Enable Cloud Mode', 'Set Up Sync') and the identical sentence 'This installs rclone automatically and configures your cloud credentials.' All three copies currently share the same broken `bm project add --local-path` command (missing --cloud), demonstrating the drift risk.
+  - *Fix:* Keep only the Obsidian-specific steps (point --local-path at the vault, open the folder as an Obsidian vault, when to pull/push) and link to the Cloud Sync Guide Quick Start for the login/setup mechanics — or extract the shared sequence into one reusable snippet/page.
+
+### content/7.integrations/9.skills.md
+
+- [x] **[redundant/high]** Available Skills table + Installation section — The skills table, both npx install commands, the agent-compatibility sentence, the Node.js note, and the slash-command usage example are all duplicated on content/2.whats-new/6.agent-skills.md, and the two copies have already drifted.
+  - *Evidence:* content/2.whats-new/6.agent-skills.md carries its own 'Available Skills' table listing only 9 skills (missing memory-capture, memory-continue, memory-curate, memory-literary-analysis), plus the same `npx skills add basicmachines-co/basic-memory/skills` and `--skill memory-tasks` commands, the same Claude Desktop/Claude Code/Cursor/Windsurf compatibility line, and the same '/memory-notes' usage example. This page lists 13 skills, so the duplicate table is already out of sync.
+  - *Fix:* Make this page the single canonical skill list. On the whats-new announcement page, replace the full table with a short highlights list (or drop it) and lean on its existing 'Agent Skills Guide' card that already links here; at minimum, sync the whats-new table to the current 13 skills.
+- [x] **[confusing/medium]** Core Skills / Knowledge Maintenance / Advanced Workflows sections — The categorized detail sections read like a complete taxonomy but silently cover only 9 of the 13 skills in the table above — memory-capture, memory-continue, memory-curate, and memory-literary-analysis get no detail paragraph anywhere.
+  - *Evidence:* The table (lines 82–96) lists 13 skills, but the three headed sections below describe only memory-notes, memory-tasks, memory-schema, memory-reflect, memory-defrag, memory-lifecycle, memory-metadata-search, memory-ingest, and memory-research. memory-continue is even used as the activation example in 'Using skills' ('where did we leave off?' pulls in memory-continue), yet a reader scrolling down for more on it finds nothing; same for memory-capture, arguably half of the flagship capture/resume loop.
+  - *Fix:* Add short paragraphs for the four missing skills in the appropriate sections (memory-capture and memory-continue under Core Skills, memory-curate under Knowledge Maintenance, memory-literary-analysis under Advanced Workflows), or retitle/introduce the sections as selected highlights rather than an exhaustive breakdown.
+
+### content/7.integrations/10.openclaw.md
+
+- [x] **[incorrect/high]** Tip block after intro (line 10) — The stated prerequisite is wrong and self-contradictory: it says the plugin "Requires ... a local Basic Memory installation" and then says the plugin auto-installs the bm CLI; the actual prerequisite is uv, without which the auto-install silently skips.
+  - *Evidence:* Plugin README.md: "Prerequisite: uv (Python package manager) — used to install the Basic Memory CLI." index.ts auto-install runs `command -v uv` first and aborts if missing; scripts/setup-bm.sh: "Fails gracefully when uv is absent" and prints "uv not found — skipping basic-memory install."
+  - *Fix:* Change the tip to: requires OpenClaw and uv; the plugin auto-installs the bm CLI via uv on first startup if it's not already on your PATH (with brew/curl install commands for uv, matching the plugin README).
+- [x] **[incorrect/medium]** Installation (lines 17-22) — The install steps omit `openclaw plugins enable openclaw-basic-memory --slot memory`, which the plugin's canonical install instructions include between install and gateway restart.
+  - *Evidence:* openclaw-basic-memory README.md install section: `openclaw plugins install @basicmemory/openclaw-basic-memory` → `openclaw plugins enable openclaw-basic-memory --slot memory` → `openclaw gateway restart`; DEVELOPMENT.md line 13 has the same enable step, and both README config examples include `slots: { memory: "openclaw-basic-memory" }`.
+  - *Fix:* Add the `openclaw plugins enable openclaw-basic-memory --slot memory` line between the install and restart commands.
+- [x] **[incorrect/high]** Configuration table (lines 34-35) — The `project` and `projectPath` rows show no default ("—"), but both have meaningful defaults that make zero-config work: `openclaw-{hostname}` and `.` (workspace root).
+  - *Evidence:* config.ts parseConfig: project defaults to `openclaw-${hostname()}` via defaultProject(), projectPath defaults to "."; plugin README table documents defaults `"openclaw-{hostname}"` and `"."`.
+  - *Fix:* Fill in the defaults: project = `openclaw-{hostname}`, projectPath = `.` (workspace root).
+- [x] **[incorrect/high]** Bundled Skills note (lines 121-125) — The claim that the bundled skills are "the same pre-built skills as the standalone skills collection" and "identical to the standalone collection — no separate install needed" is false: the plugin bundles a subset (9 skills), omitting memory-capture, memory-continue, memory-curate, and memory-literary-analysis that the standalone collection includes.
+  - *Evidence:* openclaw-basic-memory/skills/manifest.json lists 9 skills (defrag, ingest, lifecycle, metadata-search, notes, reflect, research, schema, tasks); the standalone collection on content/7.integrations/9.skills.md lists 13 including memory-capture, memory-continue, memory-curate, memory-literary-analysis.
+  - *Fix:* Say the plugin bundles a core subset of the skills collection (drawn from the same source, no separate install needed for those), and link to /integrations/skills for the full collection plus install instructions for skills not bundled.
+- [x] **[incorrect/medium]** Slash Commands table (lines 107-115) — The table is presented as the plugin's slash-command list but omits five commands the plugin registers: /notes, /ingest, /lifecycle, /metadata-search, and /research (one command per bundled skill).
+  - *Evidence:* commands/skills.ts registerSkillCommands registers a command for every entry in skills/manifest.json using the dir name minus the `memory-` prefix; the manifest contains 9 skills, so /defrag, /ingest, /lifecycle, /metadata-search, /notes, /reflect, /research, /schema, /tasks all exist alongside /bm-setup, /remember, /recall from commands/slash.ts.
+  - *Fix:* Either list all skill-backed commands or state that every bundled skill is also exposed as a slash command (skill name minus the memory- prefix) and show the built-ins plus a few examples.
+- [x] **[incorrect/high]** Slash Commands table, /bm-setup row (line 109) — `/bm-setup` is described as "Initialize Basic Memory configuration" but it actually installs or updates the Basic Memory CLI.
+  - *Evidence:* commands/slash.ts line 16: description: "Install or update the Basic Memory CLI (requires uv)"; the handler runs scripts/setup-bm.sh, which does `uv tool install basic-memory @ git+...`. This also collides with the docs' Claude Code plugin skill of the same name that does configure a project, compounding the confusion.
+  - *Fix:* Change the description to "Install or update the Basic Memory CLI (requires uv)".
+- [x] **[incorrect/medium]** Agent Tools table, edit_note row (line 93) — edit_note's operations are listed as "append, prepend, find/replace", omitting replace_section which the plugin's tool supports.
+  - *Evidence:* tools/edit-note.ts operation union: append, prepend, find_replace, replace_section; its description reads "Supports append, prepend, find/replace, and section replacement". Note the plugin exposes 4 operations, not the 6 of the core MCP edit_note (no insert_before/after_section), so the parenthetical should match the plugin exactly.
+  - *Fix:* Change to "Incremental edits (append, prepend, find/replace, replace section)".
+- [x] **[confusing/medium]** Multi-Project & Cloud Access (line 70) — "Use `list_memory_projects` to browse projects and switch between them on the fly" implies a project-switching tool, but the plugin has none — cross-project access works by passing an optional `project` parameter on each tool call.
+  - *Evidence:* Plugin README Agent tools section: "All tools accept an optional `project` parameter for cross-project operations"; no switch tool is registered in index.ts. A reader will look for a switch command that doesn't exist.
+  - *Fix:* Reword to: use `list_memory_projects` to browse projects, then pass the optional `project` parameter on any tool call to operate on a different project.
+
+### content/7.integrations/11.hermes.md
+
+- [x] **[incorrect/high]** ## Installation, line 24 (install command) — The install command `hermes plugins install basicmachines-co/hermes-basic-memory` points at the deprecated standalone repo; the plugin moved into the basic-memory monorepo and the canonical install is `hermes plugins install basicmachines-co/basic-memory --path integrations/hermes`.
+  - *Evidence:* github.com/basicmachines-co/hermes-basic-memory is archived (archived: true, last push 2026-05-31) and its README opens with 'WE'VE MOVED ... https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes'. The canonical README (basic-memory/integrations/hermes/README.md, present locally at /Users/phernandez/dev/basicmachines/basic-memory/integrations/hermes/README.md) documents `hermes plugins install basicmachines-co/basic-memory --path integrations/hermes` and describes the old slug as 'the final deprecated basicmachines-co/hermes-basic-memory pointer release' for Hermes builds without --path support.
+  - *Fix:* Change the install command to `hermes plugins install basicmachines-co/basic-memory --path integrations/hermes`, optionally noting the deprecated pointer-release slug as a fallback for Hermes builds that don't support --path.
+- [x] **[incorrect/high]** Intro (lines 6-7), top warning MONKEYPATCH link (line 10), Slash Commands note (line 138), Next Steps GitHub card (lines 201-208) — Five links (plugin repo twice in the intro, MONKEYPATCH.md twice, and the GitHub Repository card promising 'Source code, issues, and contributing guide') all point at the archived standalone repo instead of the canonical monorepo location.
+  - *Evidence:* The old repo is archived (issues read-only, no ongoing development) and redirects readers via a 'WE'VE MOVED' banner. Canonical source: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes; MONKEYPATCH.md exists there (https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md). This matches the established skills precedent where docs point at the monorepo and the old repo is a distribution target only.
+  - *Fix:* Repoint all five links to basic-memory/tree/main/integrations/hermes (and blob/main/integrations/hermes/MONKEYPATCH.md for the patch links); reword the GitHub card since the archived repo no longer accepts issues or contributions.
+- [x] **[confusing/medium]** Top ::warning block (line 10) — The warning gives a first-time reader no way to tell whether their Hermes build is affected, and 'The plugin ships a best-effort workaround, but it isn't sufficient for gateway startup discovery' references a workaround that is never identified — while 'gateway sessions' jargon appears before the gateway is introduced (Installation later says 'If you run the gateway').
+  - *Evidence:* The plugin README handles this by listing concrete symptoms (tools work, `hermes memory status` shows available, but /bm-* commands are missing from the Discord/native picker) and linking the upstream tracking issue NousResearch/hermes-agent#23603, plus a second workaround (use the bm_* agent tools directly). The docs page omits all three, leaving 'affected releases'/'affected builds' undeterminable.
+  - *Fix:* Add the symptom test (agent tools work and `hermes memory status` shows available, but /bm-* commands don't appear in the command picker), link the upstream tracking issue, and either name the plugin-side workaround or drop the sentence about it.
+- [x] **[redundant/medium]** ## Installation (lines 19-50) — The install quick-start (install command, config.yaml activation snippet, gateway restart, `hermes memory status` verify) is duplicated nearly verbatim on the What's New announcement page, and both copies now carry the same outdated install command — the drift risk has already materialized.
+  - *Evidence:* content/2.whats-new/3.hermes-plugin.md 'Quick Install' section (lines 23-36) repeats the identical `hermes plugins install basicmachines-co/hermes-basic-memory` command, the `memory: provider: basic-memory` YAML, restart, and verify steps.
+  - *Fix:* Keep full install steps only on this integration guide and reduce the What's New page's Quick Install to a link — or at minimum fix the repo-move command in both places together.
+- [x] **[confusing/medium]** ## Bundled Skill (line 158) — 'a longer reference doc on top of the always-on guidance' has no antecedent — the page never mentions any always-on guidance, and 'It's opt-in via `skill:view basic-memory:basic-memory`' doesn't say where or how that invocation is issued.
+  - *Evidence:* The phrase paraphrases the plugin README's 'on top of the always-on system_prompt_block' — context the docs page dropped, leaving a dangling reference. A first-time reader can't tell what the skill adds to, nor whether `skill:view ...` is typed in a Hermes session, a CLI, or something the agent calls.
+  - *Fix:* Reword to e.g. 'on top of the guidance the plugin always injects into the agent's system prompt' and note that `skill:view basic-memory:basic-memory` is run in a Hermes session.
+- [x] **[incorrect/low]** Frontmatter description (line 3) and ## Agent Tools intro (line 114) — Hard-coded tool count ('10 agent tools' / 'exposes 10 tools') conflicts with the stated docs policy of no hard-coded tool counts and will silently drift when the plugin's curated surface changes.
+  - *Evidence:* Docs policy (authoritative for this review) says 'no hard-coded tool/skill/theme counts'. The count is accurate today (the table enumerates exactly 10 and the plugin README says 'ten tools'), so this is a drift-risk/policy-consistency flag rather than a present factual error.
+  - *Fix:* Drop the numerals: 'a curated set of bm_* agent tools' in the description and 'The plugin exposes a curated subset of Basic Memory's MCP surface:' in the body.
+
+## How-To
+
+
+### content/8.how-to/1.project-documentation.md
+
+- [x] **[confusing/high]** Architecture Decision Records — schema example (lines 49-68) — The example prompt asks for ADRs that "should always have a status, context, decision, and consequences section," but the AI-generated schema shown marks consequences as optional (`consequences?(array, ...)`), contradicting the request it supposedly fulfills.
+  - *Evidence:* Line 49 quote: "They should always have a status, context, decision, and consequences section." Line 63 schema field: `consequences?(array, outcomes of the decision): string` — per the Picoschema parser (basic-memory/src/basic_memory/schema/parser.py), the trailing `?` means optional. A first-time reader learning schema syntax from this example sees output that contradicts the prompt, right where the `?` marker is being implicitly taught.
+  - *Fix:* Either drop the `?` so consequences is required (matching the prompt), or soften the prompt to "status, context, and decision, and usually consequences."
+- [x] **[confusing/medium]** Finding and Reviewing Documentation (lines 104-112) — "Show me all accepted ADRs" is presented as metadata search "filtering by type, status, tags, and other frontmatter fields," but per the page's own ADR schema, `status` is a schema field that maps to an observation category (`- [status] accepted`), not a frontmatter field — so frontmatter metadata search would not find accepted ADRs written to that schema.
+  - *Evidence:* The metadata-search concepts page (content/6.concepts/8.metadata-search.md, line 15) explicitly warns: "Observation categories such as [decision] ... are not frontmatter fields. Filter them with search_notes(categories=[...], entity_types=[\"observation\"]) instead of metadata_filters." The schema-system page (content/6.concepts/6.schema-system.md) confirms schema fields validate observations, e.g. `name: string` → `- [name] Ada Lovelace`. The two examples on this page contradict each other.
+  - *Fix:* Either replace the ADR example with one that genuinely uses frontmatter (e.g. "Find notes tagged with api"), or reword to say the AI filters by observation categories for schema fields like status, or show the ADR schema declaring status under settings.frontmatter.
+- [x] **[confusing/medium]** Architecture Decision Records — schema prompt and follow-up prose (lines 47-70) — The prompt's "section" language ("should always have a status, context, decision, and consequences section") suggests the schema enforces markdown headings, but schema fields actually validate observation categories and relations — a reader who writes `## Context` sections and runs `bm schema validate adr` would fail validation and not understand why.
+  - *Evidence:* The Picoschema parser docstring (basic-memory/src/basic_memory/schema/parser.py): schema fields "Map to either an observation category or a relation type in Basic Memory notes." The validator (basic-memory/src/basic_memory/schema/validator.py) checks observations and relations only. The linked schema-system page frames fields the same way (`status: string` requires `- [status] ...`), but this page never says so, and "section" points readers at markdown headings instead.
+  - *Fix:* Reword the prompt to avoid "section" (e.g. "They should always record a status, context, decision, and consequences"), or add one sentence after the example noting fields are satisfied by observations like `- [status] accepted`, with the existing Schema System link for details.
+
+### content/8.how-to/3.research-learning.md
+
+- [x] **[incorrect/high]** ## Keeping Research Organized > ### Schemas for Consistency (lines 113-122; also the schema prompt at lines 30-36) — The page describes schemas as requiring named markdown sections ("A 'Key Findings' section", "A 'Sources' section", "An 'Open Questions' section", "A 'Relations' section") and says you can validate notes against such a schema, but the schema system validates observation categories, relation types, and frontmatter fields — not document sections or headings.
+  - *Evidence:* src/basic_memory/schema/validator.py validates observations (categories), relations, and frontmatter only — no section/heading concept exists anywhere in src/basic_memory/schema/. The docs' own schema page (content/6.concepts/6.schema-system.md) maps every picoschema field to observations, relations, or frontmatter (e.g. "`name: string` | Required observation") and its fix advice is "Add the observation or relation expected by the schema" — sections are never a schema construct.
+  - *Fix:* Rephrase the schema requirements in terms the system actually enforces, e.g. "required `key-finding` observations, `source` observations for references, `open-question` observations, and relations linking to related topics", and adjust the earlier prompt example (line 31-33) to ask for observation categories rather than sections.
+- [x] **[confusing/medium]** ## Finding and Exploring Your Research > ### Exploring Connections (line 89) — "Use `build_context` to follow the links between notes" drops a raw MCP tool name, unexplained and unlinked, on a page otherwise written entirely as natural-language prompts — and it's the AI that calls build_context, not the reader, as the very next example (a plain conversational prompt) shows.
+  - *Evidence:* Every other instruction on the page is phrased as "tell your AI" / a quoted prompt; no other MCP tool name appears. The sibling page content/8.how-to/2.writing-organization.md handles the identical workflow in plain language ("Build context around Sarah Chen — show me everything connected to her character") without naming the tool.
+  - *Fix:* Rephrase to plain language (e.g. "Ask your AI to build context around a note to follow its links") or, if keeping the tool name, add a link to /reference/mcp-tools-reference on first use.
+- [x] **[confusing/medium]** ### Tag and Metadata Search (line 85) vs ### Note Types (line 104) — `literature-review` is used as a tag in one section ("find all notes tagged `literature-review`") and as a note type in the next ("**literature-review** -- Summaries and analysis of papers or books"), conflating two distinct mechanisms and leaving a new reader unsure whether to tag notes or type them.
+  - *Evidence:* Tags (frontmatter tags, searched via `tag:` shorthand) and note types (frontmatter `type`, set via write_note's `note_type` param) are separate mechanisms in the product (src/basic_memory/mcp/tools/write_note.py, src/basic_memory/mcp/tools/search.py); the page uses the same token for both without acknowledging the difference.
+  - *Fix:* Use a distinct example tag at line 85 (e.g. `lit-review-queue` or reuse the page's earlier `battery-technology`), or add a sentence noting that tags and note types are separate ways to categorize.
+
+### content/8.how-to/4.note-taking.md
+
+- [x] **[incorrect/high]** Progressive Note Building, line 187 ("Basic Memory tracks who made each update") — The page claims Basic Memory tracks who made each update to a note, but no per-update authorship or edit-history tracking exists in the product.
+  - *Evidence:* Searched /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory for author/attribution/actor/history tracking: edit_note.py and the knowledge write path record no editor identity, and notes are plain markdown files with no history mechanism. The only author fields in source are in CI project-update ingestion and the ChatGPT importer, unrelated to note edits.
+  - *Fix:* Drop the clause, e.g. "The note grows through contributions from both you and the AI." If attribution matters, scope it correctly to Cloud (the activity feed shows agent/MCP writes) rather than claiming it as core behavior.
+- [x] **[incorrect/medium]** Keeping Notes Consistent with Schemas, line 169 ("The AI validates notes against schemas as it creates them") — Schema validation is not performed automatically at note creation; it is an on-demand action via the schema_validate tool or `bm schema validate`.
+  - *Evidence:* In /Users/phernandez/dev/basicmachines/basic-memory, schema/validator.py's validate_note is called only from api/v2/routers/schema_router.py (backing the schema_validate MCP tool). write_note.py, edit_note.py, and knowledge_router.py never invoke the validator. The docs' own schema-system concepts page also frames validation as an explicit step (`bm schema validate ...`).
+  - *Fix:* Rephrase to match actual behavior: the AI follows the schema's structure when creating typed notes, and you can validate anytime ("Validate my meeting notes against the schema") — with warn mode as the gentle default.
+- [x] **[confusing/medium]** Finding Your Notes Later > Semantic Search, line 141 — The cross-vocabulary example ("if you wrote about 'conversion rates declining' and search for 'budget concerns'") is contradicted by the page's own sample notes, which literally contain the words "Budget concerns raised by finance" and "[request] $50k additional advertising budget" — so the illustrated match is a plain keyword hit, not a semantic one.
+  - *Evidence:* Lines 21 and 75 of the same page contain the literal terms "Budget concerns" and "budget", making the semantic-search illustration a keyword match.
+  - *Fix:* Use query vocabulary genuinely absent from the sample notes (e.g., searching "spending pushback" or "cost worries" surfaces the meeting notes about the $50k ad request).
+- [x] **[confusing/medium]** Finding Your Notes Later > Metadata Search, line 150 ("Find notes with action items assigned to Sarah") — This example doesn't illustrate metadata search: action items are body content (markdown checkboxes), not note properties/frontmatter, so under a section defined as "search by note properties" it misleads readers about what metadata filtering does.
+  - *Evidence:* Metadata filters in search_notes operate on frontmatter fields with equality/$in/range/$between operators (src/basic_memory/mcp/tools/search.py); the action items in the page's own example (lines 79-82) are plain checkbox list items with no frontmatter representation.
+  - *Fix:* Replace with a frontmatter-based example, e.g. "Find all notes of type meeting with status open" or "Show notes where priority is high", and keep the action-items example under text/semantic search.
+- [x] **[confusing/low]** Meeting Notes, line 92 ("Also notice that the AI used edit_note...") — The text asks the reader to "notice" that the AI used edit_note, but the example output is just a finished note with no visible indication of which tool was used, leaving a first-time reader looking for something that isn't shown.
+  - *Evidence:* The preceding code block (lines 58-88) shows only the enhanced markdown note; no tool call or transcript is displayed.
+  - *Fix:* State it directly instead: "Behind the scenes, the AI enhances your existing note with edit_note rather than creating a new one — Basic Memory's write protection blocks accidental overwrites of existing notes."
+
+### content/8.how-to/5.personal-knowledge.md
+
+- [x] **[incorrect/high]** Privacy and Boundaries → "Per-project routing" bullet (line 150) — The sentence "your team documentation syncs to Basic Memory Cloud" misstates what `bm project set-cloud` does — it routes requests to the cloud instance; it does not sync or upload existing local content.
+  - *Evidence:* Source docstring in /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/cli/commands/project.py (set_cloud, line 1114+): "Set a project to cloud mode (route through cloud API)... This is a one-way cutover: the project's row in the local index DB is removed and the local path in config is cleared... On-disk note files are preserved." No upload happens. The docs' own routing page (content/3.cloud/08.routing.md) says only "all MCP tool calls for the `research` project go through your cloud instance." A reader following this page could run `bm project set-cloud work` expecting their existing work notes to appear in cloud; instead the local project is detached and the cloud project starts from whatever is already in cloud.
+  - *Fix:* Reword to routing language, e.g. "your work projects route through Basic Memory Cloud" and link to /cloud/routing; if migration of existing notes matters here, mention pushing them with `bm cloud push` before or after the cutover.
+- [x] **[confusing/medium]** Privacy and Boundaries → bash code block (lines 152-158) — The only code block on the page mixes the two CLI aliases (`basic-memory project add ...` then `bm project set-cloud work`) and runs `set-cloud` against a `work` project that is never created in the example, so a first-time reader may think these are two different tools and wonder where `work` came from.
+  - *Evidence:* Lines 154 and 157 of the page: `basic-memory project add personal ~/notes/personal` followed by `bm project set-cloud work`. Nothing on this page states that `bm` is an alias for `basic-memory`, and the `work` project appears only in the set-cloud line. This how-to targets personal-knowledge users who are the least CLI-savvy audience in the docs.
+  - *Fix:* Use `bm` consistently for both commands and either add a `bm project add work ~/notes/work` line before the set-cloud line or a comment noting `work` is an existing project.
+
+## Reference
+
+
+### content/9.reference/1.cli-reference.md
+
+- [x] **[incorrect/high]** Cloud commands → Sync (code block, `bm cloud sync` and `bm cloud check` examples) — The examples `bm cloud sync` and `bm cloud check` omit the required `--name` option, so both commands fail as shown ('Missing option --name').
+  - *Evidence:* src/basic_memory/cli/commands/cloud/project_sync.py lines 242 and 580: `name: str = typer.Option(..., "--name", "--project", ...)` — the Ellipsis default makes --name mandatory for both `sync` and `check`. The command's own docstring examples use `bm cloud sync --name research` / `bm cloud check --name research`.
+  - *Fix:* Change the examples to `bm cloud sync --name research` and `bm cloud check --name research`.
+- [x] **[incorrect/high]** ### `bm tool read-note` (example and flag table) — Documents `--page` and `--page-size` flags (with example `bm tool read-note my-note --page 2 --page-size 5`), but the command has no pagination options — the example errors with 'No such option: --page'.
+  - *Evidence:* src/basic_memory/cli/commands/tool.py lines 175-195: read_note's only parameters are identifier, --include-frontmatter, --project, --project-id, --local, --cloud.
+  - *Fix:* Remove the pagination example and the --page / --page-size rows; optionally add the real --project-id flag.
+- [x] **[incorrect/high]** ### `bm tool recent-activity` flag table (--page-size row) — States the `--page-size` default is 50; the actual default is 10.
+  - *Evidence:* src/basic_memory/cli/commands/tool.py line 461: `page_size: int = typer.Option(10, "--page-size", ...)` with a comment noting it deliberately matches the MCP recent_activity default of 10.
+  - *Fix:* Change the default to `10`.
+- [x] **[incorrect/high]** ## Notes on defaults (second bullet) — Claims 'All `bm tool` subcommands support `--workspace` for cloud workspace targeting' — no `bm tool` subcommand has a `--workspace` option.
+  - *Evidence:* grep of src/basic_memory/cli/commands/tool.py finds no workspace option on any subcommand; cross-workspace disambiguation is done via `--project-id` ("Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces").
+  - *Fix:* Replace the bullet with: most `bm tool` subcommands accept `--project-id` (project external UUID) to disambiguate same-named projects across cloud workspaces.
+- [x] **[incorrect/high]** ### `bm schema infer` (--save example and flag-table row) — Documents `--save` as saving the inferred schema 'directly as a schema note in the `schemas/` directory', but the flag is not implemented — it prints a notice telling the user to copy the schema manually (and the conventional directory is `schema/`, not `schemas/`).
+  - *Evidence:* src/basic_memory/cli/commands/schema.py lines 320-324: `if save: console.print("--save not yet implemented. Copy the schema above into schema/{note_type}.md")`.
+  - *Fix:* Remove the --save example and row, or document it as accepted-but-not-yet-implemented (prints instructions to save manually to `schema/<type>.md`).
+- [x] **[incorrect/high]** ### `bm schema validate` (--strict example comment and flag-table row) — Describes `--strict` as 'Treat validation warnings as errors (exit code 1 on any issue)' — strict only exits 1 when there are validation errors; warnings never affect the exit code.
+  - *Evidence:* src/basic_memory/cli/commands/schema.py line 234: `if strict and result.get("error_count", 0) > 0: raise typer.Exit(1)`; the option help is 'Exit with error on validation failures'.
+  - *Fix:* Reword to: '--strict — exit with code 1 if any validation errors are found' and fix the example comment.
+- [x] **[incorrect/high]** ### Schema tool commands (first example line) — Example `bm tool schema-validate --entity-type person` uses a nonexistent `--entity-type` option; the target is a positional argument.
+  - *Evidence:* src/basic_memory/cli/commands/tool.py lines 761-766: schema_validate takes `target` as a typer.Argument; its docstring example is `bm tool schema-validate person`.
+  - *Fix:* Change to `bm tool schema-validate person`.
+- [x] **[incorrect/high]** ### `bm update` (intro paragraph) — Claims background update checks run for `uvx` installs; the auto-updater explicitly skips uvx environments entirely.
+  - *Evidence:* src/basic_memory/cli/auto_update.py lines 207-215: `if source == InstallSource.UVX: return AutoUpdateResult(status=SKIPPED, ..., message="uvx runtime detected; updates are managed by uvx cache resolution.")`.
+  - *Fix:* Limit the background-check claim to Homebrew and `uv tool` installs, and note that uvx installs are skipped because uvx manages its own cache resolution.
+- [x] **[confusing/high]** ### `bm project move` — 'Move a local project to a new filesystem location' implies files are relocated, but the command only updates the configured path — the CLI itself warns that the user must manually move the files afterward.
+  - *Evidence:* src/basic_memory/cli/commands/project.py lines 1016-1027 print a panel: 'You must manually move your project files from the old location... Basic Memory has only updated the configuration - your files remain in their original location.'
+  - *Fix:* Add a sentence: 'This updates configuration only — move the files to the new path yourself (Basic Memory does not move them).'
+- [x] **[incorrect/medium]** ### `bm tool write-note` flag table — The flag table omits `--overwrite`, so the reference gives no way past the write_note overwrite guard — a scripted write to an existing title fails with NOTE_ALREADY_EXISTS and exit 1 with no documented resolution.
+  - *Evidence:* src/basic_memory/cli/commands/tool.py lines 95-99: `overwrite: bool = typer.Option(False, "--overwrite", help="Replace an existing note on conflict (matches MCP write_note overwrite=True)")`. The command also supports the undocumented `--project-id`.
+  - *Fix:* Add an `--overwrite` row (replace an existing note on conflict) and optionally `--project-id`.
+- [x] **[incorrect/medium]** ### `bm reindex` (flag table and first example comment) — The flag table omits `--full`, and the page implies bare `bm reindex` rebuilds everything when the default is an incremental scan — `--full` is what forces a complete rebuild/re-embed.
+  - *Evidence:* src/basic_memory/cli/commands/db.py lines 283-287 and docstring: '--full — Force a full filesystem scan and file reindex instead of the default incremental scan'; 'By default runs incremental search + embeddings'.
+  - *Fix:* Add a `--full` row and note that the default is incremental; `bm reindex --full` forces a complete rebuild.
+- [x] **[incorrect/medium]** ### `bm tool search-notes` flag table — The flag table omits `--category`, the repeatable observation-category filter (pairs with `--entity-type observation`).
+  - *Evidence:* src/basic_memory/cli/commands/tool.py lines 549-558: `--category` option, help 'Filter observation results to exact categories (repeatable); pair with --entity-type observation'; the command's own docstring includes the example `bm tool search-notes "auth" --entity-type observation --category requirement`.
+  - *Fix:* Add a `--category` row (repeatable; filters observation results to exact categories, pair with `--entity-type observation`).
+- [x] **[incorrect/medium]** ### `bm tool edit-note` flag table (--operation row) — Lists only four operations for `--operation`, but the CLI forwards the value to MCP edit_note, which also accepts `insert_before_section` and `insert_after_section` — and this site's own MCP Tools Reference lists all six, creating an internal inconsistency.
+  - *Evidence:* src/basic_memory/mcp/tools/edit_note.py line 515+ validates six operations; the CLI (tool.py lines 307-368) passes `operation` straight through. content/9.reference/2.mcp-tools-reference.md line 69 documents all six.
+  - *Fix:* List all six operations and note `--section` is also required for the two insert operations.
+- [x] **[incorrect/medium]** ## Import commands — The import list omits `bm import claude projects` (Claude.ai project import), which exists alongside `claude conversations`.
+  - *Evidence:* src/basic_memory/cli/commands/import_claude_projects.py line 40: `@claude_app.command(name="projects", help="Import projects from Claude.ai.")`.
+  - *Fix:* Add `bm import claude projects` to the example block.
+
+### content/9.reference/2.mcp-tools-reference.md
+
+- [x] **[incorrect/high]** ## UI tools (sections `search_notes_ui` and `read_note_ui`) — The page documents search_notes_ui and read_note_ui as available MCP tools, but both are disabled in the current release — their registration is commented out, so the MCP server does not expose them.
+  - *Evidence:* In basic-memory src/basic_memory/mcp/tools/__init__.py (both on main and at tag v0.22.1): '# TODO: re-enable once MCP client rendering is working' followed by '# from basic_memory.mcp.tools.ui_sdk import read_note_ui, search_notes_ui', and both names are commented out of __all__. Tool registration happens only on module import, and nothing else imports ui_sdk. Documenting them also conflicts with the docs policy of not documenting unshipped features.
+  - *Fix:* Remove the entire 'UI tools' section (intro paragraph plus both tool subsections) until the tools are re-enabled in a shipped release.
+- [x] **[incorrect/high]** ## Discovery tools — `cloud_info()` bullet — cloud_info is described as returning 'cloud connection information including authentication status, subscription details, and tenant info', but it returns a static bundled markdown blurb about Basic Memory Cloud with no connection/auth/tenant data.
+  - *Evidence:* src/basic_memory/mcp/tools/cloud_info.py: `return load_discovery_resource("cloud_info.md")` — a static file (src/basic_memory/mcp/resources/cloud_info.md) containing a feature list, an OSS discount code, and 'bm cloud login' setup guidance. Docstring: 'Return optional Basic Memory Cloud information and setup guidance.'
+  - *Fix:* Describe it as: returns an overview of Basic Memory Cloud (features, discount code, and setup guidance via `bm cloud login`). No parameters.
+- [x] **[incorrect/high]** ### `recent_activity` — intro sentence — The claim 'When called without a `project` parameter, returns activity across all projects' is wrong for typical setups — without a project parameter the tool falls back to the default project; cross-project discovery mode only triggers when no project can be resolved at all.
+  - *Evidence:* src/basic_memory/mcp/project_context.py resolve_project_parameter: resolution order is env constraint → explicit parameter → default_project → discovery, and recent_activity.py calls it with allow_discovery=True; its docstring says discovery applies 'When no specific project can be resolved'. Config auto-sets default_project to the first project when unset (config.py model validator), so a default almost always exists. The sentence also contradicts the page's own project-resolution tip at the top.
+  - *Fix:* Change to: 'When no project can be resolved (no parameter, no default project), returns activity across all projects (discovery mode); otherwise it uses the resolved project.'
+- [x] **[incorrect/medium]** ## Discovery tools — `release_notes()` bullet — release_notes is described as returning 'the latest Basic Memory release notes and changelog', but it returns a short static markdown resource bundled with the package — not the changelog.
+  - *Evidence:* src/basic_memory/mcp/tools/release_notes.py: `return load_discovery_resource("release_notes.md")` — a bundled static file (src/basic_memory/mcp/resources/release_notes.md) containing a brief dated note and a cloud promo/discount blurb. Docstring: 'Return the latest product release notes for optional user review.'
+  - *Fix:* Drop 'and changelog' and describe it as returning bundled release-notes highlights for the installed version.
+- [x] **[incorrect/medium]** ### `read_content` — description — 'Returns the file's raw bytes' misstates the behavior: text files are returned as plain text, images are automatically resized/optimized (not raw), and other binaries are returned base64-encoded only when below size limits.
+  - *Evidence:* src/basic_memory/mcp/tools/read_content.py docstring: 'Text files (markdown, code, etc.) are returned as plain text; Images are automatically resized/optimized for display; Other binary files are returned as base64 if below size limits.'
+  - *Fix:* Reword to: 'Read a file's raw content by path or permalink. Text files return as plain text; images are resized/optimized for display; other binary files return base64-encoded (subject to size limits).'
+- [x] **[confusing/low]** ## Discovery tools — 'Cloud discovery tools' subheading — Grouping release_notes under 'Cloud discovery tools' implies both tools are cloud-only, but both are registered unconditionally and work in local mode; release_notes is about the product release, not the cloud.
+  - *Evidence:* src/basic_memory/mcp/tools/__init__.py imports cloud_info and release_notes unconditionally alongside the standard tools; release_notes.md content is product release notes plus an optional cloud promo.
+  - *Fix:* Rename the subheading to 'Discovery tools' content directly (drop the 'Cloud' qualifier) or split release_notes out from the cloud-specific grouping.
+
+### content/9.reference/3.ai-assistant-guide.md
+
+- [x] **[confusing/medium]** ## 1. Install Agent Skills (recommended) — line 20 — The prose says "Start with memory-notes ... and add others as you need them," but the command shown right above (npx skills add basicmachines-co/basic-memory/skills) installs all skills at once, so the incremental-adoption advice contradicts the example.
+  - *Evidence:* The skills page (content/7.integrations/9.skills.md, Installation section) documents that the bare command "Install[s] all skills at once" and that single-skill installs require --skill (e.g. `npx skills add basicmachines-co/basic-memory/skills --skill memory-tasks`).
+  - *Fix:* Either show the single-skill form for the recommended starting point (`npx skills add basicmachines-co/basic-memory/skills --skill memory-notes`) before mentioning adding others, or reword to clarify the command installs the full set and memory-notes is simply the skill to lean on first.
+
+### content/9.reference/4.technical-information.md
+
+- [x] **[incorrect/medium]** Resulting JSON Entity Structure (entity_metadata.tags, ~line 141) — The example shows entity_metadata.tags as a stringified Python list ("['#coffee', '#brewing', '#methods', '#demo']") but the current parser preserves frontmatter lists as lists, so the API returns a JSON array.
+  - *Evidence:* normalize_frontmatter_value in /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/markdown/entity_parser.py explicitly preserves lists: 'if isinstance(value, list): return [normalize_frontmatter_value(item) for item in value]'. entity_metadata is a Dict field (schemas/response.py line 202), so tags serialize as a JSON array, not a str()-ed Python list. The example output (timestamped 2025-03-06) appears generated by an older version.
+  - *Fix:* Change the value to a JSON array: "tags": ["#coffee", "#brewing", "#methods", "#demo"] (or regenerate the example against a current build).
+- [x] **[confusing/high]** Implementation Details (steps, lines 73-83) vs Entity Model (lines 188-197) — The page defines the same entity model twice: the 'Implementation Details' steps define Entities/Observations/Relations, then the 'Entity Model' section immediately after the JSON example re-defines the identical three concepts (plus Tags), breaking the narrative flow.
+  - *Evidence:* Lines 73-83: 'Entities — Distinct concepts represented by Markdown documents / Observations — Categorized facts... / Relations — Connections between entities...'; lines 190-195 repeat: 'Entities — Documents in your knowledge base / Observations — Facts or statements about entities / Relations — Connections between entities'. A first-time reader encounters near-identical definitions a screen apart with the long JSON example in between.
+  - *Fix:* Merge the two into one definition list (keeping Tags), placed once before the Example Markdown Input, and drop the duplicate 'Entity Model' bullets.
+- [x] **[confusing/medium]** Resulting JSON Entity Structure (created_at/updated_at, lines 179-180) — In the example JSON, created_at (2025-03-06T14:01:23) is later than updated_at (2025-03-06T13:34:48), an impossible ordering that makes careful readers doubt the example's accuracy.
+  - *Evidence:* "created_at": "2025-03-06T14:01:23.445071" vs "updated_at": "2025-03-06T13:34:48.563606" — a record cannot be updated before it was created.
+  - *Fix:* Swap or adjust the timestamps so updated_at >= created_at.
+- [x] **[confusing/low]** Resulting JSON Entity Structure (file_path, line 135) — The output's file_path 'Coffee Notes/Coffee Brewing Methods.md' is never established by the 'Example Markdown Input' it supposedly derives from, and its folder doesn't match the permalink prefix 'coffee/', leaving readers unable to tell how file paths and permalinks relate.
+  - *Evidence:* The markdown input block (lines 89-126) shows only file content with an explicit 'permalink: coffee/coffee-brewing-methods'; the JSON output introduces a 'Coffee Notes/' folder out of nowhere. Since permalinks are normally derived from file paths unless overridden, the mismatch invites the wrong mental model for the input->output example pair.
+  - *Fix:* Either state the file's location above the input example (e.g., 'saved as Coffee Notes/Coffee Brewing Methods.md') and note that the frontmatter permalink overrides the path-derived one, or align file_path with the permalink (coffee/Coffee Brewing Methods.md).
+
+### content/9.reference/5.troubleshooting.md
+
+- [x] **[incorrect/high]** Database Issues → Corrupted Database — The fix is labeled "Reset and re-index" and the warning claims `basic-memory reset` "rebuilds the database from your markdown files", but plain `reset` only drops and recreates an empty index database — it does not re-index files.
+  - *Evidence:* src/basic_memory/cli/commands/db.py:196-219 — reset prints "This only deletes the index database... Use bm reset --reindex to automatically rebuild the index afterward"; re-indexing only runs when the --reindex flag is passed (db.py:265).
+  - *Fix:* Change the command to `basic-memory reset --reindex` (or `basic-memory reset` followed by `basic-memory reindex`) and reword the warning to say the index is rebuilt from markdown files when --reindex is used.
+- [x] **[incorrect/high]** Sync Issues → Changes Not Syncing, step 4 "Reset the database" — The warning under `basic-memory reset` says "This re-indexes all files", but reset alone never re-indexes — without `--reindex` the user is left with an empty index and their "changes not syncing" problem seemingly worse.
+  - *Evidence:* src/basic_memory/cli/commands/db.py:196-219 — reset help/output: "Reset database (drop all tables and recreate)" and "Use bm reset --reindex to automatically rebuild the index afterward."
+  - *Fix:* Use `basic-memory reset --reindex` in the code block, or recommend `basic-memory reindex` first (lighter fix) before a full reset.
+- [x] **[incorrect/high]** Performance Issues → Slow Operations, step 1 "Check database size" — `basic-memory project info` as written fails — the command requires a project name argument — and it reports knowledge-graph/embedding statistics, not database size.
+  - *Evidence:* src/basic_memory/cli/commands/project.py:1360-1363 — `@project_app.command("info")` with `name: str = typer.Argument(..., help="Name of the project")` (required); output shows Entities/Observations/Relations counts and embedding status.
+  - *Fix:* Change to `basic-memory project info <project-name>` and relabel the step "Check knowledge base statistics".
+- [x] **[incorrect/high]** Getting Help → Check Logs (first code block) — `cat ~/.basic-memory/basic-memory-*.log` matches nothing on macOS/Linux — the log file there is `basic-memory.log`; the hyphen-pid form (`basic-memory-<pid>.log`) is Windows-only.
+  - *Evidence:* src/basic_memory/utils.py:442 — `log_filename = f"basic-memory-{os.getpid()}.log" if os.name == "nt" else "basic-memory.log"`.
+  - *Fix:* Use `cat ~/.basic-memory/basic-memory.log` (and optionally note the per-process `basic-memory-<pid>.log` naming on Windows).
+- [x] **[incorrect/high]** Getting Help → Check Logs ("Or for Cloud mode" line) — `~/.basic-memory/basic-memory-cloud.json` is not a cloud-mode log file — it is the OAuth token cache, so catting it shows (and encourages exposing) credentials, not logs.
+  - *Evidence:* src/basic_memory/cli/auth.py:35 — `self.token_file = app_config.data_dir_path / "basic-memory-cloud.json"`.
+  - *Fix:* Remove the "Or for Cloud mode" line, or replace it with a real diagnostic such as `bm cloud status`.
+- [x] **[incorrect/medium]** MCP Connection Issues → MCP Endpoint Connection Fails (Cloud), step 3 — Step 3 labels `bm cloud status` as "Check subscription status", but the command reports authentication and connection status (host, API key, OAuth token validity, health-check reachability), not subscription state.
+  - *Evidence:* src/basic_memory/cli/commands/cloud/core_commands.py:158-200 — docstring "Check cloud authentication and connection status"; output covers Host, API Key, OAuth token validity, and a /proxy/health connectivity check only.
+  - *Fix:* Relabel the step "Check authentication and connection status"; the separate "Subscription Required Error" section already covers subscription problems.
+- [x] **[incorrect/medium]** Sync Issues → Sync In Progress — The section troubleshoots operations failing with a "sync in progress" message, but no such message exists anywhere in the current codebase — this appears to be stale guidance from an earlier release.
+  - *Evidence:* grep for "sync in progress"/"in progress" (case-insensitive) across /Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory returns no user-facing message; neither CLI, API, nor MCP tools emit it.
+  - *Fix:* Remove the section, or rewrite it around what users actually see today (e.g., `basic-memory status` showing files still being indexed after startup).
+- [x] **[redundant/high]** Sync Issues → Cloud Sync Issues; Cloud Issues → Authentication Failed or Invalid Token; Project Issues → Project Not Configured for Sync (Cloud) — These three cloud troubleshooting entries duplicate, nearly verbatim, the Troubleshooting section of the Cloud Sync page (same error strings, same command sequences), and "Project Not Configured for Sync (Cloud)" additionally repeats step 4 of "Cloud Sync Issues" on this same page.
+  - *Evidence:* content/3.cloud/03.cloud-sync.md lines 355-385 contain identical "Authentication failed or Invalid token" (bm cloud logout/login), "Push or Pull Reports Conflicts" (--dry-run, --on-conflict keep-both), and "Project has no local_sync_path configured" (bm cloud sync-setup research ~/Documents/research) entries.
+  - *Fix:* Keep one-line symptoms here and link to /cloud/cloud-sync#troubleshooting for the fixes, or make the cloud-sync page link here — pick a single owner so the two copies cannot drift.
+- [x] **[confusing/medium]** Search and Content Issues → Entity Not Found, steps 1 and 3 — Natural-language AI prompts ("Find notes about [topic]", "List files in [folder]") appear in bare code blocks on a page otherwise full of shell commands, so a first-time reader may try to run them in a terminal.
+  - *Evidence:* Every other code block on the page is a bash command or JSON config; nothing signals these two blocks are things to say to the AI assistant rather than type into a shell.
+  - *Fix:* Prefix each with a sentence like "Ask your AI assistant:" or label the fences (e.g., a 'prompt' caption) to distinguish them from shell commands.
+- [x] **[confusing/medium]** Database Issues → Database Locked, step 3 "Remove lock files" — The step calls memory.db-shm/-wal "lock files" — they are SQLite WAL/shared-memory files — and deleting the -wal file by hand can silently discard recently indexed changes, when the supported cleanup path is `basic-memory reset --reindex` (which removes these files itself).
+  - *Evidence:* src/basic_memory/cli/commands/db.py:236-242 deletes the "", "-shm", "-wal" suffixed files as part of the guarded reset flow (which first refuses to run while MCP processes hold the DB open); the doc's manual `rm` has no such guard and mislabels the files.
+  - *Fix:* Reword to "Remove SQLite WAL/shared-memory files" and point users at `basic-memory reset --reindex` after closing clients, instead of manual rm commands.
+
+### content/9.reference/6.configuration.md
+
+- [x] **[incorrect/high]** Project and routing settings > `projects` bullet list (line 69) — The project entry field is listed as `cloud_sync_path`, but the actual config field is `local_sync_path`; `cloud_sync_path` is only a legacy read-time alias.
+  - *Evidence:* basic-memory src/basic_memory/config.py line 163: `local_sync_path: Optional[str] = Field(... validation_alias=AliasChoices("local_sync_path", "cloud_sync_path"))`. Re-saved configs serialize `local_sync_path`. The page's own example config (line 47) correctly uses `local_sync_path`, contradicting this bullet.
+  - *Fix:* Change the bullet to `local_sync_path` (optional), optionally noting that legacy `cloud_sync_path` keys are accepted and migrated on load.
+- [x] **[incorrect/high]** Sync and watch settings > `skip_initialization_sync` (lines 258-264) — The description says it skips the initial full sync at MCP server start and recommends it for large local projects, but the setting actually skips database initialization and project reconciliation/seeding (cloud/stateless deployments) and does not gate the initial file scan at all.
+  - *Evidence:* config.py line 458: description 'Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.' It feeds skip_local_initialization (config.py line 673), which makes initialize_app return before DB init and project reconciliation (services/initialization.py line 202) and skips default-project seeding (config.py lines 767-776). The initial file sync is gated only by sync_changes/test/cloud mode (mcp/container.py line 57); grep shows no file-sync path checks skip_initialization_sync.
+  - *Fix:* Rewrite as: skips local initialization (database setup and project reconciliation) for cloud/stateless deployments where projects are managed in the database; do not recommend it as a local large-project performance knob.
+- [x] **[incorrect/high]** Formatter settings > `formatter_command` (lines 315-321) — The page says the command 'is called with the file path as an argument', but the file path is only substituted via a `{file}` placeholder in the command string — nothing is appended if the placeholder is absent.
+  - *Evidence:* file_utils.py line 240: `cmd = formatter.replace("{file}", str(path))` followed by shlex.split and subprocess exec — no path is appended. config.py line 469 description: 'External formatter command. Use {file} as placeholder for file path... Set to 'npx prettier --write {file}' for Prettier.' A user setting `"prettier --write"` per the docs would run the command without any file.
+  - *Fix:* Document the `{file}` placeholder with an example like `npx prettier --write {file}`.
+- [x] **[confusing/medium]** Formatter settings > `format_on_save` / `formatter_command` (lines 307-321) — The section implies formatting only happens when `formatter_command` is set, but with `format_on_save: true` and no command configured, markdown files are formatted by the built-in mdformat formatter; the per-extension `formatters` map is also undocumented.
+  - *Evidence:* file_utils.py lines 228-236: when no formatter is configured, markdown files fall through to `format_markdown_builtin` (mdformat with GFM/frontmatter). config.py line 469: 'If not set, uses built-in mdformat (Python, no Node.js required).' config.py line 472 also defines a `formatters` per-extension dict not mentioned on the page.
+  - *Fix:* State that enabling format_on_save alone formats markdown with built-in mdformat, and that formatter_command (or the per-extension `formatters` map) overrides it with an external tool.
+- [x] **[confusing/low]** Project and routing settings > `default_project` (lines 72-77) — 'Default: "main"' is not the field default — the field defaults to null and, when omitted, Basic Memory falls back to the first configured project ('main' only on fresh installs because a 'main' project is seeded); explicit null disables automatic project resolution, which the page does not mention.
+  - *Evidence:* config.py lines 200-203 (default=None, 'Set to null to disable automatic project resolution') and lines 783-789 (when not explicitly set, default_project becomes the first project in the config; corrected to first project if it references a missing project).
+  - *Fix:* Say: default is unset, in which case the first configured project is used ('main' on fresh installs); explicit null disables automatic project resolution.
+- [x] **[redundant/medium]** Semantic search settings section (lines 103-168) — The seven semantic settings with their defaults and env var names are fully duplicated in the settings table on the Semantic Search concepts page, creating drift risk if a default changes.
+  - *Evidence:* content/6.concepts/7.semantic-search.md lines 230-236 list semantic_search_enabled, semantic_embedding_provider, semantic_embedding_model, semantic_embedding_dimensions, semantic_embedding_batch_size, semantic_vector_k, and semantic_min_similarity with identical defaults and BASIC_MEMORY_* env vars; line 240 also repeats the min-similarity tuning guidance.
+  - *Fix:* Keep the full reference here and have the concepts page link to /reference/configuration#semantic-search-settings instead of maintaining its own defaults table (or vice versa).
+- [x] **[confusing/medium]** ## Example config (v0.19+) heading (line 34) — The heading hard-codes a version floor ('v0.19+'), which contradicts the docs policy of not embedding version floors and reads dated now that the current release is v0.22.x.
+  - *Evidence:* Docs policy: no version floors; latest-release info lives on the Changelog page. Nothing in the example is v0.19-specific relative to the current format, so the qualifier adds no information for a first-time reader.
+  - *Fix:* Rename the heading to 'Example config'.
+
+### content/9.reference/7.docker.md
+
+- [x] **[confusing/medium]** ## Configuration — intro sentence and defaults table — The table is introduced with "The image sets these defaults," but four of the six rows (BASIC_MEMORY_DEFAULT_PROJECT, BASIC_MEMORY_SYNC_CHANGES, BASIC_MEMORY_LOG_LEVEL, BASIC_MEMORY_SYNC_DELAY) are not set by the image at all — their Default cells say "in the Compose example," contradicting the intro.
+  - *Evidence:* The Dockerfile in the basic-memory repo only sets BASIC_MEMORY_HOME and BASIC_MEMORY_PROJECT_ROOT (ENV block); the other four variables appear only in the Compose example's environment section. A reader using plain `docker run` (the page's first example) could skim the intro and assume those four are baked into the image.
+  - *Fix:* Split into two parts: "The image sets BASIC_MEMORY_HOME=/app/data/basic-memory and BASIC_MEMORY_PROJECT_ROOT=/app/data" plus a second list/table of "variables the Compose example sets (and their application defaults)" — or reword the intro to "Configuration comes from these environment variables" and give each row a clear Source column (image vs. Compose example vs. application default).
+
+### content/9.reference/8.llms-txt.md
+
+- [x] **[redundant/medium]** Quick reference table and Content negotiation / llms.txt / Raw markdown sections — The 4-row access-methods table and the same three curl examples (llms.txt index, /raw/ page fetch, Accept: text/markdown negotiation) are duplicated nearly verbatim on content/2.whats-new/8.ai-friendly-docs.md.
+  - *Evidence:* content/2.whats-new/8.ai-friendly-docs.md lines 18-36 contain an identical Method/URL table (Index /llms.txt, Full docs /llms-full.txt, Raw markdown /raw/<path>.md, Content negotiation Accept: text/markdown) plus the same curl commands; that page already cross-links here twice ('See the full reference at Reference → AI-Friendly Documentation'), so the duplicated table/examples could drift if an endpoint changes.
+  - *Fix:* Trim the What's New page to the announcement prompt plus the cross-link card, keeping the reference table and curl examples only on this reference page.
+- [x] **[confusing/low]** Opening ::tip block (lines 8-16) — The natural-language AI prompt ('Fetch https://docs.basicmemory.com/llms.txt and read the Basic Memory documentation') is fenced as a bash code block, so a first-time reader may paste it into a terminal where it fails; the equivalent block on the What's New page uses a plain fence.
+  - *Evidence:* Line 11 opens the fence with ```bash but the content is a prompt for an AI assistant, not a shell command; the surrounding prose says 'ask it to fetch the documentation'. content/2.whats-new/8.ai-friendly-docs.md line 12 renders the same prompt with a language-less fence.
+  - *Fix:* Change the fence language from bash to plain text (```text or no language) for the prompt block.
+
+## Cross-cutting
+
+
+### terminology (3)
+
+- [x] **[high]** content/3.cloud/11.restore-lost-content.md:45 vs content/3.cloud/11.restore-lost-content.md:151, content/3.cloud/05.cloud-snapshots.md:33, content/3.cloud/02.web-app.md:217 and 02.web-app.md:309 — Snapshot scope is described inconsistently: restore-lost-content.md:45 says "Snapshots are project-wide point-in-time backups", implying each project has its own snapshots, while the same page (line 151: "Snapshots cover the recent history of your cloud workspace"), the Cloud Snapshots guide ("Go to Settings → Snapshots and select a workspace to see its snapshots"), and the Web App settings table ("Manage point-in-time backups per workspace") all describe snapshots as workspace-scoped. A reader following the cross-links between the recovery guide and the snapshots guide gets two different answers about what a snapshot contains.
+  - *Fix:* Change restore-lost-content.md:45 to "Snapshots are workspace-wide point-in-time backups" (or "cover your whole cloud workspace, every project in it"), matching the rest of the snapshot docs.
+- [x] **[medium]** content/4.teams/1.about.md:18-24 and content/2.whats-new/0.teams.md:16 vs content/9.reference/1.cli-reference.md:192 and 1.cli-reference.md:374-375, content/9.reference/2.mcp-tools-reference.md:235 — "Workspace" sometimes includes Local and sometimes means cloud-only. The Teams pages present a three-workspace model (Local / Personal Cloud / Team) and say you "switch between workspaces using the workspace selector in the app" / "switch between them in the app, or target one explicitly from the CLI and MCP" — but the CLI and MCP references define workspaces as cloud-only (`--workspace`: "Cloud workspace name, slug, type, or tenant ID"; `bm cloud workspace list` lists cloud workspaces; `list_workspaces` "List available cloud workspaces"). A reader who follows the about page's pointer to the CLI reference will find that the "Local" workspace from the table never appears in `bm cloud workspace list` or accepts `--workspace` targeting, and the web app cannot switch to it.
+  - *Fix:* In 4.teams/1.about.md and 2.whats-new/0.teams.md, either footnote the Local row (e.g., "Local projects live outside the cloud workspace model — they aren't listed by `bm cloud workspace list` or shown in the app's workspace selector") or reframe the table as "where your knowledge can live" rather than three workspaces, reserving "workspace" for cloud.
+- [x] **[medium]** content/4.teams/2.join-a-team.md:29 vs content/3.cloud/02.web-app.md:19, content/4.teams/1.about.md:24, content/4.teams/3.copy-between-workspaces.md:37 — The workspace-switching UI is named three different ways across linked pages: join-a-team.md:29 says "The sidebar shows the teams and projects you have access to" (and its page description promises a "switch workspaces" step that the body never ties to a named control), about.md:24 and copy-between-workspaces.md:37 call it "the workspace selector", and the Web App guide — the page join-a-team links to for the UI — describes the sidebar as only "Project and folder tree, search, your account avatar" with no mention of a workspace selector or teams at all. A new team member following join-a-team → Web App won't find where "teams" or workspaces appear in the interface.
+  - *Fix:* Pick one UI label ("workspace selector") and use it in join-a-team step 2 (e.g., "switch to the team workspace using the workspace selector, then the sidebar shows its projects"), and add the workspace selector to the Web App guide's Layout/sidebar description.
+
+### commands (12)
+
+- [x] **[high]** content/3.cloud/03.cloud-sync.md:82-84, content/3.cloud/03.cloud-sync.md:135-138, content/3.cloud/03.cloud-sync.md:280-282, content/3.cloud/03.cloud-sync.md:300-305, content/3.cloud/03.cloud-sync.md:467, content/3.cloud/01.cloud-guide.md:190, content/3.cloud/01.cloud-guide.md:193, content/3.cloud/01.cloud-guide.md:317, content/7.integrations/7.vscode.md:43, content/7.integrations/7.vscode.md:46, content/7.integrations/8.obsidian.md:47, content/7.integrations/8.obsidian.md:50 — Cloud project creation shown without the required --cloud flag, e.g. `bm project add research --local-path ~/Documents/research` and `bm project add temp`. Source (basic-memory/src/basic_memory/cli/commands/project.py:716-806) sets `effective_cloud_mode = cloud and not local` — cloud mode only when --cloud is passed; otherwise local mode requires the positional path argument, so every one of these commands exits with 'Error: path argument is required in local mode' even when global cloud mode is enabled. Contradicts the same operation shown correctly with --cloud on content/4.teams/1.about.md:176-182 and content/9.reference/1.cli-reference.md:220-229.
+  - *Fix:* Add `--cloud` to every cloud-mode `bm project add` example (e.g. `bm project add research --cloud --local-path ~/Documents/research`, `bm project add temp --cloud`).
+- [x] **[high]** content/9.reference/1.cli-reference.md:668 — Claims 'All `bm tool` subcommands support `--workspace` for cloud workspace targeting.' No `bm tool` subcommand defines a --workspace option (basic-memory/src/basic_memory/cli/commands/tool.py — only --project and --project-id exist; --project-id is the documented way to disambiguate same-named projects across workspaces). Only `bm cloud pull/push` and `bm project add/list/set-cloud` take --workspace.
+  - *Fix:* Replace the bullet with: `bm tool` subcommands support `--project-id` (project external_id) to disambiguate same-named projects across cloud workspaces; --workspace belongs to `bm project` and `bm cloud pull/push` commands.
+- [x] **[high]** content/1.start-here/3.quickstart-local.md:259 — Documents `basic-memory sync` ('Force re-sync all files') but no top-level `sync` command exists in the CLI (basic-memory/src/basic_memory/cli/commands/__init__.py registers no sync module; only `bm cloud sync` exists). Running it fails with 'No such command'.
+  - *Fix:* Replace with the current equivalents: `basic-memory reindex` (rebuild indexes) or `basic-memory reset --reindex`, matching content/5.local/5.user-guide.md:483-486.
+- [x] **[high]** content/7.integrations/1.claude-desktop.md:95 — Suggests 'run the watcher manually: `basic-memory watch`' but no `watch` command exists in the CLI (not registered in basic-memory/src/basic_memory/cli/commands/__init__.py; 'watch' only appears in a legacy skip-init list in cli/app.py:99). The command fails with 'No such command'.
+  - *Fix:* Remove the `basic-memory watch` suggestion; sync runs inside the MCP server process, so point users at `basic-memory status` / restarting the MCP client instead.
+- [x] **[high]** content/1.start-here/3.quickstart-local.md:250, content/5.local/5.user-guide.md:474, content/5.local/5.user-guide.md:584, content/9.reference/5.troubleshooting.md:236 — `basic-memory project info` shown with no project name, but the name argument is required (basic-memory/src/basic_memory/cli/commands/project.py:1360-1363: `name: str = typer.Argument(...)`). Bare invocation errors with 'Missing argument'. cli-reference.md:201 correctly shows `bm project info main`.
+  - *Fix:* Add a project name to each example, e.g. `basic-memory project info main`.
+- [x] **[high]** content/9.reference/1.cli-reference.md:515 — `bm tool read-note my-note --page 2 --page-size 5` — read-note has no --page/--page-size options (basic-memory/src/basic_memory/cli/commands/tool.py:175-196: only --include-frontmatter, --project, --project-id, --local, --cloud). The command fails with 'No such option: --page'.
+  - *Fix:* Remove the pagination example from the read-note section (pagination flags exist on search-notes, build-context, and recent-activity only).
+- [x] **[high]** content/9.reference/1.cli-reference.md:646 — `bm tool schema-validate --entity-type person` — schema-validate takes a positional TARGET argument, not an --entity-type option (basic-memory/src/basic_memory/cli/commands/tool.py:761-766). --entity-type is a search-notes filter flag, not a schema-validate flag. The documented command fails with 'No such option'.
+  - *Fix:* Change to `bm tool schema-validate person`, matching the schema-infer/schema-diff examples on the following lines and `bm schema validate person` elsewhere.
+- [x] **[high]** content/3.cloud/03.cloud-sync.md:435 — Command cheat-sheet lists `bm project rm <name>` but the subcommand is `remove` with no `rm` alias (basic-memory/src/basic_memory/cli/commands/project.py:854: `@project_app.command("remove")`). cli-reference.md:249 correctly documents `bm project remove`.
+  - *Fix:* Change to `bm project remove <name>`.
+- [x] **[high]** content/9.reference/1.cli-reference.md:344, content/9.reference/1.cli-reference.md:347 — `bm cloud sync` and `bm cloud check` shown bare, but --name is a required option on both (basic-memory/src/basic_memory/cli/commands/cloud/project_sync.py:240-243 and 578-581: `typer.Option(..., "--name", "--project")`). Bare invocation fails with 'Missing option --name'. Every other page (03.cloud-sync.md:250, 267, 449-453) shows `--name <project>`.
+  - *Fix:* Change to `bm cloud sync --name research` and `bm cloud check --name research`.
+- [x] **[high]** content/2.whats-new/1.changelog.md:38 — Changelog names the command `bm orphan` (singular); the actual command is `bm orphans` (basic-memory/src/basic_memory/cli/commands/orphans.py:32-33), and cli-reference.md:123-130 documents `bm orphans`. Also 'a flag to clean them out' — orphans has no cleanup flag (only --project, --json, --local, --cloud); it is read-only reporting.
+  - *Fix:* Rename to `bm orphans` and drop or correct the cleanup-flag claim to match the actual flags (--json, --project).
+- [x] **[medium]** content/9.reference/6.configuration.md:69, content/9.reference/6.configuration.md:413 — Project entry key documented as `cloud_sync_path`, but the current config field is `local_sync_path` — `cloud_sync_path` is only a legacy read alias (basic-memory/src/basic_memory/config.py:163-167: `validation_alias=AliasChoices("local_sync_path", "cloud_sync_path")`); new configs are written with `local_sync_path`.
+  - *Fix:* Document the key as `local_sync_path` (optionally noting `cloud_sync_path` is accepted as a legacy alias).
+- [x] **[medium]** content/3.cloud/03.cloud-sync.md:93 — 'Config stores `cloud_projects` dict mapping project names to local paths' — `cloud_projects` is a removed legacy key; per configuration.md:407-410 (and config.py:145-151) it was migrated into structured `projects` entries with `local_sync_path`. The two docs pages contradict each other about the same config surface.
+  - *Fix:* Update to say local sync paths are stored per-project in the `projects` entries (`local_sync_path` field) of config.json.
+
+### redundancy (9)
+
+- [x] **[high]** content/1.start-here/2.quickstart-cloud.md:69-88, content/3.cloud/01.cloud-guide.md:61-67, content/7.integrations/3.chatgpt.md:8-37,49-53 — ChatGPT cloud setup is maintained in two full copies and has already drifted. quickstart-cloud says enable MCP under 'Settings → Beta features' and requires a 'Pro or Max subscription' (Max is a Claude tier, not a ChatGPT tier); the ChatGPT integration page says 'Settings > Developer > Custom MCP Servers' and 'ChatGPT Plus or Pro subscription required'. cloud-guide repeats the 'Pro or Max' claim in its note even though it otherwise defers to the integration page. Users following the quickstart get a wrong settings path and wrong tier names.
+  - *Fix:* Make integrations/chatgpt.md canonical for the steps and the subscription requirement. In quickstart-cloud, replace the ChatGPT ::steps block with a one-line pointer (endpoint URL + link), and fix/remove the 'Pro or Max' note in both quickstart-cloud and cloud-guide to match the integration page's 'Plus or Pro'.
+- [x] **[high]** content/1.start-here/2.quickstart-cloud.md:36-67, content/3.cloud/01.cloud-guide.md:27-57, content/7.integrations/1.claude-desktop.md:10-41 — The Claude Desktop remote-connector setup (Open Settings → Add Custom Connector → Authenticate → Configure Tools → Verify) is maintained as three separate full ::steps blocks. They already diverge in small ways: quickstart uses /screenshots/claude/* images, claude-desktop uses /claude-settings-*.png images, cloud-guide has no images; wording differs ('Add custom connector' vs 'Add connector'). cloud-guide even ends its copy with a tip pointing at the claude-desktop guide 'for detailed instructions' while carrying the same detail itself.
+  - *Fix:* Pick one canonical walkthrough. Given quickstart-cloud is the primary onboarding page with the best screenshots, make it (or integrations/claude-desktop) canonical, reduce cloud-guide's 'Setup with Claude' to the endpoint URL plus a link, and have integrations/claude-desktop either host the canonical steps or link to the quickstart the way its own Local Setup section already links to quickstart-local.
+- [x] **[high]** content/3.cloud/01.cloud-guide.md:89-211,286-335, content/3.cloud/13.cloud-cli.md (whole page), content/3.cloud/03.cloud-sync.md:99-192 — cloud-guide's 'Command Line Tools' section is a second, older treatment of exactly what the newer Cloud CLI page (13.cloud-cli) owns: bm cloud login flow, api-key save/create, per-project routing commands, project management, and sync setup. cloud-guide never links to cloud-cli. Its 'Migrating to Cloud → Option 2' also restates the cloud-sync Quick Start command sequence (login, setup, project add --local-path, pull --dry-run, pull, push). Two pages in the same Cloud section both claim CLI onboarding, so any command change (as with v0.22's push/pull semantics) must be applied in both places.
+  - *Fix:* Make 13.cloud-cli canonical for CLI-on-cloud material (it is already the well-structured pointer hub). Compress cloud-guide's 'Command Line Tools' to a short paragraph plus a card linking to /cloud/cloud-cli, and reduce 'Option 2: Local File Sync' to a pointer at the cloud-sync Quick Start.
+- [x] **[high]** content/5.local/5.user-guide.md:144-169, content/6.concepts/4.memory-urls.md:12-64 — Memory URL formats are documented twice and have drifted in both directions: the user-guide lists memory://folder/title and the relation-follow wildcard memory://path/relation_type/* (absent from the concepts page) but omits project-prefixed URLs and project::note-path syntax (v0.19+, present only in the concepts page). The user-guide section has no link to the concepts page.
+  - *Fix:* Make concepts/memory-urls canonical. Add the relation-follow wildcard form there if it is still supported, then shrink the user-guide section to one example plus a link to /concepts/memory-urls.
+- [x] **[high]** content/5.local/5.user-guide.md:173-211, content/6.concepts/3.observations-and-relations.md:10-81 — Observation and relation syntax is taught in full in both the local user-guide ('Building Knowledge Connections', including a fixed 'Common Relation Types' table) and the concepts page (which explicitly frames relation types as open-ended, 'no fixed list'). The two framings can mislead: the user-guide table reads like an enumerated vocabulary. The user-guide section does not link to the concepts page, so the v0.21 relation-parsing change (quoted multi-word types, links_to fallback) documented in concepts is invisible from the user-guide's copy.
+  - *Fix:* Make concepts/observations-and-relations canonical. Replace the user-guide's syntax subsections with a short example and a link, moving the 'Common Relation Types' table into the concepts page (labeled as examples, not a fixed list) if it is worth keeping.
+- [x] **[high]** content/5.local/5.user-guide.md:215-249,566-600, content/5.local/2.getting-started.md:70-113, content/9.reference/5.troubleshooting.md:112-133,176-204,228-246,346-350 — Two more user-guide sections are near-verbatim duplicates maintained elsewhere: (1) 'Multi-Project Workflows / How Projects Work' repeats getting-started's 'Multi-Project Setup' word-for-word (same 4-step list, same example conversation, same default_project config snippet), and both overlap concepts/projects-and-folders; (2) the user-guide 'Troubleshooting' section repeats reference/troubleshooting's 'Changes Not Syncing', 'Claude Can't Find Knowledge', and performance fixes, and the 'Moving Notes Between Projects' not-supported claim exists in both user-guide and troubleshooting — if cross-project move ships, three pages must change in lockstep.
+  - *Fix:* Decide the split: getting-started owns local setup (keep Multi-Project Setup there), concepts/projects-and-folders owns the mental model, reference/troubleshooting owns fixes. Cut the user-guide's duplicated blocks down to pointers; the user-guide should orchestrate workflows, not restate setup and troubleshooting content.
+- [x] **[medium]** content/1.start-here/3.quickstart-local.md:20-85, content/5.local/1.local-install.md:8-41 — Install commands (brew tap/trust/install, uv tool install) and the claude_desktop_config.json snippet are maintained in two copies, including a verbatim-identical ::note paragraph about `brew trust` and Homebrew 6. They are in sync today only because one was copy-pasted from the other; the Homebrew-6 transition (and any change to the recommended MCP config, e.g. uvx vs installed binary) will require editing both, and nothing links them to each other.
+  - *Fix:* Keep quickstart-local as the self-contained onboarding walkthrough (quickstarts benefit from inlined steps) and turn 5.local/1.local-install into a pointer page ('follow Quickstart: Local, then...'), or extract the install block into a shared MDC component/partial so the brew-trust note lives once.
+- [x] **[medium]** content/7.integrations/8.obsidian.md:14-79, content/7.integrations/7.vscode.md:10-78, content/3.cloud/03.cloud-sync.md:99-192, content/3.cloud/01.cloud-guide.md:307-326 — The cloud-sync onboarding sequence (bm cloud login → bm cloud setup → bm project add --local-path → pull --dry-run → pull → push) is maintained as full step-by-step blocks in at least four places: the canonical cloud-sync Quick Start, the Obsidian integration, the VS Code integration, and cloud-guide's migration Option 2. The v0.22 push/pull semantics change means every future change to these commands or their conflict behavior fans out to four pages; the integration copies each re-explain additive sync in their own words.
+  - *Fix:* Keep cloud-sync's Quick Start canonical. In the Obsidian/VS Code pages keep only the tool-specific steps (which folder to use as the vault/workspace, what to open) and link to /cloud/cloud-sync#quick-start for the command sequence, or factor the shared steps into one reusable MDC partial.
+- [x] **[medium]** content/3.cloud/08.routing.md:43-83, content/3.cloud/07.api-keys.md:104-125, content/3.cloud/01.cloud-guide.md:144-163, content/3.cloud/13.cloud-cli.md:97-114, content/9.reference/1.cli-reference.md:292-323 — The per-project routing command block (bm cloud api-key save/create, bm project set-cloud, bm project set-local) is repeated in five places. routing.md is clearly intended as canonical and most copies link to it, but api-keys and cloud-guide both carry the full command sequence rather than a pointer, so a flag rename (e.g. the --workspace option that only cloud-cli's copy shows) drifts silently.
+  - *Fix:* Treat /cloud/routing as the single canonical setup for these commands. In api-keys, keep only the api-key save/create commands (its actual topic) plus a link to routing for set-cloud/set-local; in cloud-guide, replace the block with the existing tip link. cli-reference legitimately keeps its terse command listing.
+
+### journey (8)
+
+- [x] **[high]** content/0.welcome.md:47-54, content/5.local/2.getting-started.md:6-26 — Circular path from the Welcome page: the fourth 'Pick your path' card sends new users to /local/getting-started, whose first content block is 'Ready to set up Basic Memory? Start with the quickstart guides' with cards pointing back to the two quickstarts that sit directly beside it on Welcome. A new reader following the promised path loops back to where they started. The card is also presented as path-neutral ('Set up projects and choose where your notes are saved') but the page content is local/CLI-centric (basic-memory CLI, Claude Desktop restarts, ~/.basic-memory/config.json), so a cloud-path user lands on local-only instructions.
+  - *Fix:* Either point the Welcome card at /local/local-install (or drop it, since both quickstarts are already on Welcome), or rewrite the getting-started intro so it doesn't bounce readers back to Start Here.
+- [x] **[high]** content/3.cloud/01.cloud-guide.md:93 — Misdirected installation link: the Cloud Guide's CLI section says 'See [Getting Started](/local/getting-started) for installation', but that page contains no installation instructions (only project configuration and an update command). Install steps actually live at /local/local-install, /start-here/quickstart-local, and /cloud/cloud-cli. A cloud-first reader trying to install the CLI hits a page about default projects and gets bounced back to quickstarts.
+  - *Fix:* Link to /local/local-install or /cloud/cloud-cli (which has an 'Install and check the CLI' section aimed at exactly this reader).
+- [x] **[high]** content/6.concepts/5.canvas.md (whole page), content/9.reference/8.llms-txt.md (whole page), content/9.reference/4.technical-information.md:311-325 — Dead-end pages with no onward navigation: /concepts/canvas has zero internal links and no Next Steps (it also never links the Obsidian integration guide it depends on); /reference/llms-txt has no internal links despite being promoted directly from the Welcome page's 'AI-friendly docs' card, so a Welcome reader who clicks it has no path back into the docs; /reference/technical-information has a single internal link in its intro and ends flat on a 'Development Philosophy' note. Nearly every other page in the site has a Next Steps card group.
+  - *Fix:* Add Next Steps card groups: canvas → /integrations/obsidian and /concepts/knowledge-format; llms-txt → /reference/mcp-tools-reference and /start-here/what-is-basic-memory; technical-information → /reference/configuration and /concepts/knowledge-format.
+- [x] **[high]** content/2.whats-new/0.teams.md:2, content/4.teams/1.about.md:2, content/2.whats-new/4.cloud.md:2, content/3.cloud/01.cloud-guide.md:2 — Duplicate left-nav titles across sections: 'Basic Memory Teams' is the frontmatter title of both the What's New announcement (2.whats-new/0.teams.md) and the Teams section landing page (4.teams/1.about.md); 'Basic Memory Cloud' titles both the What's New cloud announcement (2.whats-new/4.cloud.md) and the Cloud section landing page (3.cloud/01.cloud-guide.md). A reader walking the nav sees the same label twice with different content, and the announcement pages summarize/overlap the canonical guides they link to.
+  - *Fix:* Retitle the What's New pages as announcements (e.g. 'Teams launch', 'Cloud app updates') so nav labels are distinct and the canonical section pages own the product names.
+- [x] **[medium]** content/5.local/1.local-install.md:1-50, content/1.start-here/3.quickstart-local.md:20-90 and 214-237, content/5.local/2.getting-started.md:30-56 — Walking the nav in order, the Local section re-runs the reader through content they just completed in Start Here with no acknowledgment: 5.local/1.local-install.md repeats the exact install commands, Claude Desktop JSON config, and project add/default steps from Quickstart: Local, and 'choose where notes live' is covered a third time in 5.local/2.getting-started.md. The Local section's first page never says 'already done the quickstart? skip ahead' — a sequential reader can't tell whether this is new material.
+  - *Fix:* Open local-install with a pointer for quickstart graduates (e.g. 'If you followed Quickstart: Local you've done this — continue to CLI Basics'), or consolidate the three overlapping 'where notes are saved' treatments.
+- [x] **[medium]** content/6.concepts/0.vs-built-in-memory.md:1-6 and 93-133 — The Concepts section opens with a positioning/comparison page ('Using Basic Memory with Built-in AI Memory') rather than anything that orients the section, and its closing 'Getting started' cards point back to the Start Here quickstarts — top-of-funnel navigation for a reader who is five sections deep. The section's real foundation (Knowledge Format → Observations and Relations → Memory URLs) starts at page 2 with no page introducing that arc.
+  - *Fix:* Move vs-built-in-memory later in the section (or into Start Here) so Knowledge Format leads Concepts, and/or swap its quickstart cards for forward links into the concept sequence.
+- [x] **[medium]** content/2.whats-new/0.teams.md:1, content/2.whats-new/1.changelog.md:1, content/0.welcome.md:13-15 — Clicking the What's New section in the nav lands on the Teams announcement (0.teams.md sorts first), not the Changelog that the Welcome callout ('New in v0.22... See the Changelog') treats as the section's canonical page. The section reads as a mix of one changelog plus four undated feature announcements in no evident order (numbering 0,1,3,4,6,7,8), so a reader can't tell what's current versus historical.
+  - *Fix:* Make the Changelog the first page of What's New (renumber to 0/1), and order announcement pages by recency.
+- [x] **[medium]** content/3.cloud/08.routing.md:150-161 — The routing page ends abruptly on 'How It Works Under the Hood' with no Next Steps card group, unlike every sibling Cloud page; its only onward links are two inline references to /cloud/api-keys. Multiple pages (cloud-guide, cloud-cli, teams/about, projects-and-folders) funnel readers here, then leave them without an onward path to Cloud Sync or the CLI reference.
+  - *Fix:* Add a Next Steps card group (Cloud Sync, Cloud CLI, API Keys, CLI Reference) consistent with the rest of the Cloud section.
diff --git a/docs/screenshots.json b/docs/screenshots.json
new file mode 100644
index 0000000..3622e53
--- /dev/null
+++ b/docs/screenshots.json
@@ -0,0 +1,26 @@
+{
+  "description": "Screenshots deliberately reviewed during the 2026 documentation overhaul. Add new UI captures here when they become part of the maintained documentation.",
+  "screenshots": [
+    {
+      "path": "screenshots/cloud-app/snapshots-list.png",
+      "page": "/cloud/cloud-snapshots",
+      "source": "Settings > Snapshots",
+      "captured": "2026-06-07",
+      "theme": "light"
+    },
+    {
+      "path": "screenshots/cloud-app/create-snapshot.png",
+      "page": "/cloud/cloud-snapshots",
+      "source": "Create Snapshot dialog",
+      "captured": "2026-06-07",
+      "theme": "light"
+    },
+    {
+      "path": "screenshots/cloud-app/restore-files.png",
+      "page": "/cloud/cloud-snapshots",
+      "source": "Snapshot restore browser",
+      "captured": "2026-06-07",
+      "theme": "light"
+    }
+  ]
+}
diff --git a/docs/todo.md b/docs/todo.md
new file mode 100644
index 0000000..a9629f8
--- /dev/null
+++ b/docs/todo.md
@@ -0,0 +1,41 @@
+# Docs TODO
+
+Last updated: 2026-07-02 (docs-updates-2026-07 branch). Items found during the July 2026 audit that need screenshots, product verification, or a human decision. Working checks: `npm run check:docs` (broken links/assets fail; version literals and orphaned screenshots warn).
+
+## Screenshots — verified 2026-07-03
+
+Audit result: every image referenced by content exists on disk (checker enforces this); current shots are the May–June v2 capture set and accepted as current. Stale unreferenced files deleted (old Claude walkthrough spares, pre-v2 signup/first-note/themes.gif, superseded accept-invite pair).
+
+Remaining, only if desired:
+- [ ] Optional new captures: onboarding popup / Activity view / Explore graph / partner portal — pages describe these in prose today and don't require images
+- [ ] When capturing anything new, record source screen, date, theme, and owning page in `docs/screenshots.json` (the checker validates manifest entries)
+
+## Verify against production — done 2026-07-03
+
+Verified live at app.basicmemory.com (logged-in session):
+- [x] July-1 onboarding batch deployed: seeded Getting Started project (all workspaces), Help Center at /help with Connect Your AI Tool (endpoint + copy, Claude/ChatGPT guides, test prompt), Activity feed (sidebar popover + View all), Explore Graph (Graph → Project/Structured/Explore tabs, 2D/3D)
+- [x] `/notes` route confirmed canonical
+- [x] Settings nav matches docs (General…Version); Look & Feel = Mode + Note list + Theme swatches (saved per-browser — docs updated)
+- [x] `bm project ls --name` — source-verified (project.py:1240)
+- [x] `api/v2/projects` — source-verified (gateway path test + v2 project router)
+- Corrections applied to docs: "Show onboarding" control doesn't exist (Help Center is the replay surface); workspaces are sidebar *sections*, not a selector dropdown; graph entry is **Graph** with Explore as a tab
+
+## Verify against external products (fast-moving UIs)
+
+- [ ] **ChatGPT MCP setup path** — docs now say Settings → Apps & Connectors → Advanced settings → enable Developer mode → Create (per review-agent verification); double-check against current ChatGPT UI, and check the YouTube walkthrough link still matches. Paid-plan wording is now "Plus, Pro, Business/Team, Enterprise, or Edu".
+- [ ] **Cursor MCP setup** — review-agent correction applied (config via `~/.cursor/mcp.json` / `.cursor/mcp.json`, or Cursor Settings → MCP); verify against current Cursor UI
+- [ ] **Claude Desktop connector flow** — "Settings → Claude → Connectors" wording + the screenshot sets above
+- [ ] **Claude advanced research** — the research-mode page was deleted; a troubleshooting bullet in `integrations/1.claude-desktop.md` still claims research runs without MCP access. Verify current Claude behavior.
+- [ ] **Hermes slash-command patch** — version pin removed from `integrations/11.hermes.md`; check whether current Hermes Agent releases still need MONKEYPATCH.md and update or drop the warning
+- [ ] **Codex `bearer_token_env_var` config** in `cloud/07.api-keys.md` — verify against current Codex config schema
+- [ ] Explainer video embed on `what-is-basic-memory` (basicmemory.com/videos/explainer-video.mp4) — still current?
+
+## Open decisions / structural
+
+- [ ] **Quickstart duplication** — cloud and local quickstarts share near-identical structure ("what you can do now" tables, example workflows); fine for now, but they must be edited in pairs
+- [ ] **What's New numbering** — nav order is Teams(0), Changelog(1), Hermes(3), Cloud(4), Skills(6), OpenClaw(7), AI-docs(8) with gaps; consider renumbering and whether the Cloud announcement should outrank plugin announcements
+- [x] **Teams page "Personal Cloud" label** — fixed in the teams-section split (table now says "Personal")
+- [ ] `web-app.md` → "Organize with folders" shows a local `~/basic-memory/` tree in a web-app context
+- [ ] `cloud-guide.md` "search and tools menu" Claude wording is vague
+- [ ] Keep pricing out of docs (none present today; the only safe reference is the marketing site)
+- [ ] `docs/docs-audit.md` register predates this branch's changes — treat this file as current; update the register when doing the next structured audit
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 4d9eab6..424f8ab 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -2,6 +2,19 @@ export default defineNuxtConfig({
   extends: ['docus'],
   modules: ['@nuxtjs/sitemap'],
   compatibilityDate: '2025-07-15',
+  routeRules: {
+    '/': { redirect: { to: '/welcome', statusCode: 301 } },
+    '/start-here/getting-started': { redirect: { to: '/local/getting-started', statusCode: 301 } },
+    '/start-here/why-basic-memory': { redirect: { to: '/start-here/what-is-basic-memory', statusCode: 301 } },
+    '/changelog': { redirect: { to: '/whats-new/changelog', statusCode: 301 } },
+    '/whats-new/v0.22.0': { redirect: { to: '/whats-new/changelog', statusCode: 301 } },
+    '/reference/v0.19-migration': { redirect: { to: '/whats-new/changelog', statusCode: 301 } },
+    '/cloud/edit-locally-and-in-the-app': { redirect: { to: '/cloud/cloud-sync', statusCode: 301 } },
+    '/cloud/user-guide': { redirect: { to: '/cloud/cloud-guide', statusCode: 301 } },
+    '/teams/partners': { redirect: { to: '/partners/about', statusCode: 301 } },
+    '/concepts/canvas': { redirect: { to: '/local/canvas', statusCode: 301 } },
+    '/integrations/claude-research-mode': { redirect: { to: '/integrations/claude-desktop', statusCode: 301 } },
+  },
   app: {
     head: {
       meta: [
diff --git a/package.json b/package.json
index a123901..6a8622e 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,8 @@
   "scripts": {
     "dev": "nuxt dev",
     "build": "nuxt build",
+    "check:docs": "node scripts/check-docs.mjs",
+    "check": "npm run check:docs && npm run build",
     "generate": "nuxt generate",
     "preview": "nuxt preview",
     "start": "node .output/server/index.mjs"
diff --git a/public/claude-settings-add-connector.png b/public/claude-settings-add-connector.png
deleted file mode 100644
index d81f161..0000000
Binary files a/public/claude-settings-add-connector.png and /dev/null differ
diff --git a/public/claude-settings-configure.png b/public/claude-settings-configure.png
deleted file mode 100644
index aa33908..0000000
Binary files a/public/claude-settings-configure.png and /dev/null differ
diff --git a/public/claude-settings-tools.png b/public/claude-settings-tools.png
deleted file mode 100644
index 548e428..0000000
Binary files a/public/claude-settings-tools.png and /dev/null differ
diff --git a/public/screenshots/claude/create-first-note.png b/public/screenshots/claude/create-first-note.png
deleted file mode 100644
index 891fcd8..0000000
Binary files a/public/screenshots/claude/create-first-note.png and /dev/null differ
diff --git a/public/screenshots/claude/oauth-authorize.png b/public/screenshots/claude/oauth-authorize.png
deleted file mode 100644
index 3c68790..0000000
Binary files a/public/screenshots/claude/oauth-authorize.png and /dev/null differ
diff --git a/public/screenshots/claude/project-list-response.png b/public/screenshots/claude/project-list-response.png
deleted file mode 100644
index 8e146e1..0000000
Binary files a/public/screenshots/claude/project-list-response.png and /dev/null differ
diff --git a/public/screenshots/cloud-app/first-note.png b/public/screenshots/cloud-app/first-note.png
deleted file mode 100644
index 677c757..0000000
Binary files a/public/screenshots/cloud-app/first-note.png and /dev/null differ
diff --git a/public/screenshots/cloud-app/themes.gif b/public/screenshots/cloud-app/themes.gif
deleted file mode 100644
index de5c320..0000000
Binary files a/public/screenshots/cloud-app/themes.gif and /dev/null differ
diff --git a/public/screenshots/cloud-app/v2-team-accept-invite-dark.png b/public/screenshots/cloud-app/v2-team-accept-invite-dark.png
deleted file mode 100644
index 450c98b..0000000
Binary files a/public/screenshots/cloud-app/v2-team-accept-invite-dark.png and /dev/null differ
diff --git a/public/screenshots/cloud-app/v2-team-accept-invite-light.png b/public/screenshots/cloud-app/v2-team-accept-invite-light.png
deleted file mode 100644
index 7a5c5cf..0000000
Binary files a/public/screenshots/cloud-app/v2-team-accept-invite-light.png and /dev/null differ
diff --git a/public/screenshots/cloud/signup.png b/public/screenshots/cloud/signup.png
deleted file mode 100644
index e9f3118..0000000
Binary files a/public/screenshots/cloud/signup.png and /dev/null differ
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
new file mode 100644
index 0000000..d297ff4
--- /dev/null
+++ b/scripts/check-docs.mjs
@@ -0,0 +1,135 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { extname, join, relative, resolve, sep } from 'node:path'
+
+const root = resolve(import.meta.dirname, '..')
+const contentRoot = join(root, 'content')
+const publicRoot = join(root, 'public')
+const errors = []
+const warnings = []
+const retryableCodes = new Set(['ETIMEDOUT', 'EAGAIN', 'EBUSY'])
+
+function retry(operation) {
+  let lastError
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    try {
+      return operation()
+    } catch (error) {
+      lastError = error
+      if (!retryableCodes.has(error.code) || attempt === 3) throw error
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150 * (attempt + 1))
+    }
+  }
+  throw lastError
+}
+
+const readText = path => retry(() => readFileSync(path, 'utf8'))
+const listDirectory = path => retry(() => readdirSync(path))
+const getStat = path => retry(() => statSync(path))
+
+function walk(directory, extensions) {
+  const files = []
+  for (const name of listDirectory(directory)) {
+    const path = join(directory, name)
+    const stat = getStat(path)
+    if (stat.isDirectory()) files.push(...walk(path, extensions))
+    else if (!extensions || extensions.has(extname(path))) files.push(path)
+  }
+  return files
+}
+
+function slug(value) {
+  return value
+    .replace(/^\d+\./, '')
+    .replace(/\.md$/, '')
+}
+
+function routeFor(file) {
+  const parts = relative(contentRoot, file).split(sep).map(slug)
+  if (parts.at(-1) === 'index') parts.pop()
+  return `/${parts.join('/')}`.replace(/\/$/, '') || '/'
+}
+
+const markdownFiles = walk(contentRoot, new Set(['.md']))
+const routes = new Set(markdownFiles.map(routeFor))
+routes.add('/')
+routes.add('/changelog')
+
+const nuxtConfig = readText(join(root, 'nuxt.config.ts'))
+for (const match of nuxtConfig.matchAll(/['"]([^'"]+)['"]\s*:\s*\{\s*redirect:/g)) {
+  routes.add(match[1])
+}
+
+const referencedScreenshots = new Set()
+const linkPattern = /\[[^\]\n]*]\(([^)\s]+)\)|\bto:\s*([^\s]+)|(?:light|dark)="([^"]+)"/g
+
+for (const file of markdownFiles) {
+  const source = readText(file)
+  const display = relative(root, file)
+
+  if (!display.includes(`${sep}02.whats-new${sep}`)
+    && !display.endsWith(`${sep}changelog.md`)) {
+    const versions = [...source.matchAll(/(?<![-\w])v\d+\.\d+(?:\.\d+)?\b/g)]
+    for (const match of versions) {
+      warnings.push(`${display}: current documentation contains release literal ${match[0]}`)
+    }
+  }
+
+  for (const match of source.matchAll(linkPattern)) {
+    let target = match[1] || match[2] || match[3]
+    if (!target || target.startsWith('#') || /^[a-z]+:/i.test(target)) continue
+    target = target.replace(/^<|>$/g, '').split('#')[0].split('?')[0]
+    if (!target.startsWith('/')) continue
+
+    if (target.startsWith('/screenshots/')) referencedScreenshots.add(target)
+
+    if (target.startsWith('/raw/')
+      || target === '/llms.txt'
+      || target === '/llms-full.txt') continue
+
+    if (routes.has(target.replace(/\/$/, '') || '/')) continue
+
+    if (extname(target)) {
+      if (!existsSync(join(publicRoot, target))) {
+        errors.push(`${display}: missing public asset ${target}`)
+      }
+      continue
+    }
+
+    errors.push(`${display}: broken internal route ${target}`)
+  }
+}
+
+const screenshotRoot = join(publicRoot, 'screenshots')
+if (existsSync(screenshotRoot)) {
+  for (const file of walk(screenshotRoot)) {
+    const publicPath = `/${relative(publicRoot, file).split(sep).join('/')}`
+    if (!referencedScreenshots.has(publicPath)) {
+      warnings.push(`unreferenced screenshot: ${publicPath}`)
+    }
+  }
+}
+
+const manifestPath = join(root, 'docs', 'screenshots.json')
+if (!existsSync(manifestPath)) {
+  errors.push('docs/screenshots.json is missing')
+} else {
+  const manifest = JSON.parse(readText(manifestPath))
+  for (const item of manifest.screenshots || []) {
+    if (!existsSync(join(publicRoot, item.path))) {
+      errors.push(`screenshot manifest references missing file: ${item.path}`)
+    }
+    if (!item.captured || !item.page || !item.source) {
+      errors.push(`incomplete screenshot manifest entry: ${item.path}`)
+    }
+  }
+}
+
+for (const warning of warnings) console.warn(`WARN ${warning}`)
+for (const error of errors) console.error(`ERROR ${error}`)
+
+if (errors.length) {
+  console.error(`\nDocs checks failed with ${errors.length} error(s).`)
+  process.exit(1)
+}
+
+console.log(`Docs checks passed. ${warnings.length} warning(s).`)