From a0d9f4ab1e734f3271d06aeaad137b2d8684af1d Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Tue, 23 Jun 2026 22:39:54 +0200
Subject: [PATCH 1/2] docs: add standalone Relayfile and Relayloop
 documentation sections
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add two self-contained documentation sections alongside the Agent Relay
docs, each with its own sidebar, multi-group nav, scoped search, and
markdown mirrors:

- /docs/file  → Relayfile  (17 pages)
- /docs/loop  → Relayloop  (13 pages)

Infrastructure:
- lib/product-docs-nav.ts: pure, client-safe section + nav definitions
- lib/product-docs.ts: server-only content loaders, markdown mirrors,
  per-section search index
- DocsNav renders a distinct product sidebar (header, tagline, back-link,
  own nav groups/icons) when under a product path
- DocsSearch scopes to the active product's index and routes within it
- routes under app/docs/{file,loop}/* (index redirect, [slug] page via a
  shared ProductDocPage, markdown/[slug] endpoint)
- extracted the shared MDX component map to components/docs/mdx-components

Content is grounded in the relayfile/relayfile-cloud and
relayhistory/relayhistory-cloud repos.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 web/app/docs/[slug]/page.tsx                  |  46 +----
 web/app/docs/file/[slug]/page.tsx             |  43 +++++
 web/app/docs/file/markdown/[slug]/route.ts    |  30 ++++
 web/app/docs/file/page.tsx                    |   5 +
 web/app/docs/layout.tsx                       |   9 +-
 web/app/docs/loop/[slug]/page.tsx             |  43 +++++
 web/app/docs/loop/markdown/[slug]/route.ts    |  30 ++++
 web/app/docs/loop/page.tsx                    |   5 +
 web/components/docs/DocsNav.tsx               |  77 +++++++-
 web/components/docs/DocsSearch.tsx            |  29 ++-
 web/components/docs/ProductDocPage.tsx        |  58 ++++++
 web/components/docs/docs.module.css           |  53 ++++++
 web/components/docs/mdx-components.tsx        |  45 +++++
 web/content/docs/file/acls.mdx                |  58 ++++++
 .../docs/file/adapters-and-providers.mdx      |  81 +++++++++
 web/content/docs/file/agents.mdx              | 103 +++++++++++
 web/content/docs/file/api-reference.mdx       | 167 ++++++++++++++++++
 web/content/docs/file/cli.mdx                 | 163 +++++++++++++++++
 web/content/docs/file/cloud.mdx               |  69 ++++++++
 web/content/docs/file/comparison.mdx          |  53 ++++++
 web/content/docs/file/introduction.mdx        |  64 +++++++
 web/content/docs/file/local-development.mdx   |  84 +++++++++
 web/content/docs/file/mount-layout.mdx        |  85 +++++++++
 web/content/docs/file/mounting.mdx            | 113 ++++++++++++
 web/content/docs/file/quickstart.mdx          | 111 ++++++++++++
 web/content/docs/file/reads-and-writes.mdx    |  89 ++++++++++
 web/content/docs/file/realtime-sync.mdx       |  68 +++++++
 web/content/docs/file/run-locally.mdx         |  97 ++++++++++
 web/content/docs/file/sdk.mdx                 | 135 ++++++++++++++
 web/content/docs/file/why-files.mdx           |  53 ++++++
 web/content/docs/loop/cli.mdx                 | 149 ++++++++++++++++
 web/content/docs/loop/cloud-architecture.mdx  |  61 +++++++
 web/content/docs/loop/cloud.mdx               |  80 +++++++++
 web/content/docs/loop/install.mdx             |  93 ++++++++++
 web/content/docs/loop/introduction.mdx        |  60 +++++++
 web/content/docs/loop/privacy.mdx             |  75 ++++++++
 web/content/docs/loop/quickstart.mdx          |  86 +++++++++
 web/content/docs/loop/search.mdx              |  69 ++++++++
 web/content/docs/loop/sessions.mdx            |  63 +++++++
 web/content/docs/loop/sources.mdx             |  69 ++++++++
 web/content/docs/loop/stats.mdx               |  67 +++++++
 web/content/docs/loop/sync.mdx                |  69 ++++++++
 web/content/docs/loop/teams.mdx               |  62 +++++++
 web/lib/docs-markdown.ts                      |   2 +-
 web/lib/product-docs-nav.ts                   | 150 ++++++++++++++++
 web/lib/product-docs.ts                       |  92 ++++++++++
 46 files changed, 3255 insertions(+), 58 deletions(-)
 create mode 100644 web/app/docs/file/[slug]/page.tsx
 create mode 100644 web/app/docs/file/markdown/[slug]/route.ts
 create mode 100644 web/app/docs/file/page.tsx
 create mode 100644 web/app/docs/loop/[slug]/page.tsx
 create mode 100644 web/app/docs/loop/markdown/[slug]/route.ts
 create mode 100644 web/app/docs/loop/page.tsx
 create mode 100644 web/components/docs/ProductDocPage.tsx
 create mode 100644 web/components/docs/mdx-components.tsx
 create mode 100644 web/content/docs/file/acls.mdx
 create mode 100644 web/content/docs/file/adapters-and-providers.mdx
 create mode 100644 web/content/docs/file/agents.mdx
 create mode 100644 web/content/docs/file/api-reference.mdx
 create mode 100644 web/content/docs/file/cli.mdx
 create mode 100644 web/content/docs/file/cloud.mdx
 create mode 100644 web/content/docs/file/comparison.mdx
 create mode 100644 web/content/docs/file/introduction.mdx
 create mode 100644 web/content/docs/file/local-development.mdx
 create mode 100644 web/content/docs/file/mount-layout.mdx
 create mode 100644 web/content/docs/file/mounting.mdx
 create mode 100644 web/content/docs/file/quickstart.mdx
 create mode 100644 web/content/docs/file/reads-and-writes.mdx
 create mode 100644 web/content/docs/file/realtime-sync.mdx
 create mode 100644 web/content/docs/file/run-locally.mdx
 create mode 100644 web/content/docs/file/sdk.mdx
 create mode 100644 web/content/docs/file/why-files.mdx
 create mode 100644 web/content/docs/loop/cli.mdx
 create mode 100644 web/content/docs/loop/cloud-architecture.mdx
 create mode 100644 web/content/docs/loop/cloud.mdx
 create mode 100644 web/content/docs/loop/install.mdx
 create mode 100644 web/content/docs/loop/introduction.mdx
 create mode 100644 web/content/docs/loop/privacy.mdx
 create mode 100644 web/content/docs/loop/quickstart.mdx
 create mode 100644 web/content/docs/loop/search.mdx
 create mode 100644 web/content/docs/loop/sessions.mdx
 create mode 100644 web/content/docs/loop/sources.mdx
 create mode 100644 web/content/docs/loop/stats.mdx
 create mode 100644 web/content/docs/loop/sync.mdx
 create mode 100644 web/content/docs/loop/teams.mdx
 create mode 100644 web/lib/product-docs-nav.ts
 create mode 100644 web/lib/product-docs.ts

diff --git a/web/app/docs/[slug]/page.tsx b/web/app/docs/[slug]/page.tsx
index a5ee7fc4..44f2046f 100644
--- a/web/app/docs/[slug]/page.tsx
+++ b/web/app/docs/[slug]/page.tsx
@@ -1,20 +1,12 @@
 import type { Metadata } from 'next';
-import type React from 'react';
 import { notFound, redirect } from 'next/navigation';
 import { evaluate } from '@mdx-js/mdx';
 import { Fragment } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import remarkGfm from 'remark-gfm';
 
-import { Card } from '../../../components/docs/Card';
-import { CardGroup } from '../../../components/docs/CardGroup';
-import { BannerLink } from '../../../components/docs/BannerLink';
-import { CodeGroup } from '../../../components/docs/CodeGroup';
 import { DocsPageActions } from '../../../components/docs/DocsPageActions';
-import { HighlightedPre } from '../../../components/docs/HighlightedCode';
-import { LegacySpawnOptionsTable } from '../../../components/docs/LegacySpawnOptionsTable';
-import { Note } from '../../../components/docs/Note';
-import { Warning } from '../../../components/docs/Warning';
+import { mdxComponents } from '../../../components/docs/mdx-components';
 import { TableOfContents } from '../../../components/docs/TableOfContents';
 import styles from '../../../components/docs/docs.module.css';
 import { getDoc } from '../../../lib/docs';
@@ -24,40 +16,6 @@ import { getDefaultDocsVersionForSlug } from '../../../lib/docs-versions';
 import { ogImage } from '../../../lib/og-meta';
 import { absoluteUrl } from '../../../lib/site';
 
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/`([^`]+)`/g, '$1')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '');
-}
-
-function HeadingWithId(level: 2 | 3) {
-  return function Heading({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
-    const text = typeof children === 'string' ? children : String(children);
-    const id = slugify(text);
-    const Tag = `h${level}` as const;
-    return (
-      <Tag id={id} {...props}>
-        {children}
-      </Tag>
-    );
-  };
-}
-
-const components = {
-  CodeGroup,
-  Card,
-  CardGroup,
-  BannerLink,
-  Note,
-  Warning,
-  SpawnOptionsTable: LegacySpawnOptionsTable,
-  pre: HighlightedPre,
-  h2: HeadingWithId(2),
-  h3: HeadingWithId(3),
-};
-
 type PageProps = {
   params: Promise<{ slug: string }>;
 };
@@ -152,7 +110,7 @@ export default async function DocsPage({ params }: PageProps) {
           <p className={styles.articleDescription}>{doc.frontmatter.description}</p>
         )}
         <div className={styles.articleBody}>
-          <MDXContent components={components} />
+          <MDXContent components={mdxComponents} />
         </div>
       </article>
       <aside className={styles.tocSidebar}>
diff --git a/web/app/docs/file/[slug]/page.tsx b/web/app/docs/file/[slug]/page.tsx
new file mode 100644
index 00000000..fa325e94
--- /dev/null
+++ b/web/app/docs/file/[slug]/page.tsx
@@ -0,0 +1,43 @@
+import type { Metadata } from 'next';
+
+import { ProductDocPage } from '../../../../components/docs/ProductDocPage';
+import {
+  fileSection,
+  getProductDoc,
+  getProductDocMarkdownUrl,
+  getProductDocSlugs,
+} from '../../../../lib/product-docs';
+import { absoluteUrl } from '../../../../lib/site';
+
+const SECTION_ID = fileSection.id;
+
+type PageProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export function generateStaticParams() {
+  return getProductDocSlugs(fileSection).map((slug) => ({ slug }));
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const doc = getProductDoc(SECTION_ID, slug);
+
+  if (!doc) {
+    return { title: 'Not Found' };
+  }
+
+  return {
+    title: `${doc.frontmatter.title} — Relayfile`,
+    description: doc.frontmatter.description,
+    alternates: {
+      canonical: absoluteUrl(`/docs/${SECTION_ID}/${slug}`),
+      types: { 'text/markdown': getProductDocMarkdownUrl(SECTION_ID, slug) },
+    },
+  };
+}
+
+export default async function RelayfileDocPage({ params }: PageProps) {
+  const { slug } = await params;
+  return <ProductDocPage sectionId={SECTION_ID} slug={slug} />;
+}
diff --git a/web/app/docs/file/markdown/[slug]/route.ts b/web/app/docs/file/markdown/[slug]/route.ts
new file mode 100644
index 00000000..64ac1b75
--- /dev/null
+++ b/web/app/docs/file/markdown/[slug]/route.ts
@@ -0,0 +1,30 @@
+import { fileSection, getProductDocMarkdown, getProductDocSlugs } from '../../../../../lib/product-docs';
+
+export const revalidate = 86400;
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return getProductDocSlugs(fileSection).map((slug) => ({ slug: `${slug}.md` }));
+}
+
+type RouteProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export async function GET(_request: Request, { params }: RouteProps) {
+  const { slug: rawSlug } = await params;
+  const slug = rawSlug.replace(/\.md$/, '');
+
+  const doc = getProductDocMarkdown(fileSection.id, slug);
+
+  if (!doc) {
+    return new Response('Not found', { status: 404 });
+  }
+
+  return new Response(doc.markdown, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'public, max-age=86400',
+    },
+  });
+}
diff --git a/web/app/docs/file/page.tsx b/web/app/docs/file/page.tsx
new file mode 100644
index 00000000..11c85de5
--- /dev/null
+++ b/web/app/docs/file/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function RelayfileDocsIndexPage() {
+  redirect('/docs/file/introduction');
+}
diff --git a/web/app/docs/layout.tsx b/web/app/docs/layout.tsx
index ea02b517..b79cdc5f 100644
--- a/web/app/docs/layout.tsx
+++ b/web/app/docs/layout.tsx
@@ -8,15 +8,22 @@ import { SiteFooter } from '../../components/SiteFooter';
 import { SiteNav } from '../../components/SiteNav';
 import styles from '../../components/docs/docs.module.css';
 import { getSearchIndex } from '../../lib/docs';
+import { productBasePath, productSections, getProductSearchIndex } from '../../lib/product-docs';
 
 const searchIndex = getSearchIndex();
+const productScopes = productSections.map((section) => ({
+  id: section.id,
+  label: section.label,
+  basePath: productBasePath(section),
+  index: getProductSearchIndex(section),
+}));
 
 export default function DocsLayout({ children }: { children: ReactNode }) {
   return (
     <DocsLanguageProvider>
       <div className={styles.docsPage}>
         <SiteNav
-          center={<DocsSearch index={searchIndex} />}
+          center={<DocsSearch index={searchIndex} productScopes={productScopes} />}
           actions={<GitHubStarsBadge />}
           mobileMenuContent={<DocsNav variant="mobileMenu" />}
           hideMobileDocsLink
diff --git a/web/app/docs/loop/[slug]/page.tsx b/web/app/docs/loop/[slug]/page.tsx
new file mode 100644
index 00000000..224e9cf0
--- /dev/null
+++ b/web/app/docs/loop/[slug]/page.tsx
@@ -0,0 +1,43 @@
+import type { Metadata } from 'next';
+
+import { ProductDocPage } from '../../../../components/docs/ProductDocPage';
+import {
+  getProductDoc,
+  getProductDocMarkdownUrl,
+  getProductDocSlugs,
+  loopSection,
+} from '../../../../lib/product-docs';
+import { absoluteUrl } from '../../../../lib/site';
+
+const SECTION_ID = loopSection.id;
+
+type PageProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export function generateStaticParams() {
+  return getProductDocSlugs(loopSection).map((slug) => ({ slug }));
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const doc = getProductDoc(SECTION_ID, slug);
+
+  if (!doc) {
+    return { title: 'Not Found' };
+  }
+
+  return {
+    title: `${doc.frontmatter.title} — Relayloop`,
+    description: doc.frontmatter.description,
+    alternates: {
+      canonical: absoluteUrl(`/docs/${SECTION_ID}/${slug}`),
+      types: { 'text/markdown': getProductDocMarkdownUrl(SECTION_ID, slug) },
+    },
+  };
+}
+
+export default async function RelayloopDocPage({ params }: PageProps) {
+  const { slug } = await params;
+  return <ProductDocPage sectionId={SECTION_ID} slug={slug} />;
+}
diff --git a/web/app/docs/loop/markdown/[slug]/route.ts b/web/app/docs/loop/markdown/[slug]/route.ts
new file mode 100644
index 00000000..20ec803a
--- /dev/null
+++ b/web/app/docs/loop/markdown/[slug]/route.ts
@@ -0,0 +1,30 @@
+import { getProductDocMarkdown, getProductDocSlugs, loopSection } from '../../../../../lib/product-docs';
+
+export const revalidate = 86400;
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return getProductDocSlugs(loopSection).map((slug) => ({ slug: `${slug}.md` }));
+}
+
+type RouteProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export async function GET(_request: Request, { params }: RouteProps) {
+  const { slug: rawSlug } = await params;
+  const slug = rawSlug.replace(/\.md$/, '');
+
+  const doc = getProductDocMarkdown(loopSection.id, slug);
+
+  if (!doc) {
+    return new Response('Not found', { status: 404 });
+  }
+
+  return new Response(doc.markdown, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'public, max-age=86400',
+    },
+  });
+}
diff --git a/web/app/docs/loop/page.tsx b/web/app/docs/loop/page.tsx
new file mode 100644
index 00000000..599b7099
--- /dev/null
+++ b/web/app/docs/loop/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function RelayloopDocsIndexPage() {
+  redirect('/docs/loop/introduction');
+}
diff --git a/web/components/docs/DocsNav.tsx b/web/components/docs/DocsNav.tsx
index 6113ea18..c631257f 100644
--- a/web/components/docs/DocsNav.tsx
+++ b/web/components/docs/DocsNav.tsx
@@ -35,11 +35,47 @@ import { SiClaude, SiPython, SiTypescript } from 'react-icons/si';
 
 import { docsNav, legacyDocsNav } from '../../lib/docs-nav';
 import { getDocsVersionForPath, legacyDocsBasePath, v8DocsBasePath } from '../../lib/docs-versions';
+import { getProductSectionForPath, productBasePath } from '../../lib/product-docs-nav';
 import { DocsVersionSelect } from './DocsVersionSelect';
+import { FolderOpen as FolderOpenIcon, Repeat } from 'lucide-react';
 import styles from './docs.module.css';
 
 type NavIcon = ComponentType<{ className?: string; 'aria-hidden'?: boolean | 'true' | 'false' }>;
 
+const productSectionIcons: Record<string, NavIcon> = {
+  file: FolderOpenIcon,
+  loop: Repeat,
+};
+
+const productNavIcons: Record<string, NavIcon> = {
+  introduction: Compass,
+  quickstart: Rocket,
+  install: Rocket,
+  'why-files': BookOpen,
+  'mount-layout': FolderOpen,
+  'reads-and-writes': Send,
+  acls: Shield,
+  'realtime-sync': Activity,
+  'run-locally': Terminal,
+  'local-development': Terminal,
+  mounting: FolderOpen,
+  sdk: SiTypescript,
+  agents: Bot,
+  'adapters-and-providers': Plug,
+  comparison: BookOpen,
+  cloud: Cloud,
+  'api-reference': Network,
+  cli: Terminal,
+  sync: Activity,
+  search: Compass,
+  sessions: BsChatRightText,
+  sources: Network,
+  stats: Zap,
+  'cloud-architecture': Network,
+  privacy: PiLockKeyDuotone,
+  teams: Users,
+};
+
 const navIcons: Record<string, NavIcon> = {
   introduction: Compass,
   quickstart: Rocket,
@@ -89,9 +125,18 @@ export function DocsNav({ variant = 'sidebar' }: { variant?: 'sidebar' | 'mobile
   const pathname = usePathname();
   const navRef = useRef<HTMLElement | null>(null);
   const isSidebar = variant === 'sidebar';
+  const productSection = getProductSectionForPath(pathname ?? '/docs');
   const docsVersion = getDocsVersionForPath(pathname ?? '/docs');
-  const navGroups = docsVersion === 'v7.1.1' ? legacyDocsNav : docsNav;
-  const docsBasePath = docsVersion === 'v8' ? v8DocsBasePath : legacyDocsBasePath;
+  const navGroups = productSection
+    ? productSection.nav
+    : docsVersion === 'v7.1.1'
+      ? legacyDocsNav
+      : docsNav;
+  const docsBasePath = productSection
+    ? productBasePath(productSection)
+    : docsVersion === 'v8'
+      ? v8DocsBasePath
+      : legacyDocsBasePath;
 
   useEffect(() => {
     if (!isSidebar) return;
@@ -140,7 +185,23 @@ export function DocsNav({ variant = 'sidebar' }: { variant?: 'sidebar' | 'mobile
       className={`${styles.sidebar} ${!isSidebar ? styles.mobileSidebar : ''}`}
       aria-label="Documentation"
     >
-      {!isSidebar && <DocsVersionSelect />}
+      {!isSidebar && !productSection && <DocsVersionSelect />}
+      {productSection &&
+        (() => {
+          const ProductIcon = productSectionIcons[productSection.id] ?? BookOpen;
+          return (
+            <div className={styles.productHeader}>
+              <Link href="/docs/introduction" className={styles.productBackLink}>
+                ← Agent Relay docs
+              </Link>
+              <Link href={docsBasePath} className={styles.productHeaderName}>
+                <ProductIcon className={styles.productHeaderIcon} aria-hidden="true" />
+                <span>{productSection.label}</span>
+              </Link>
+              <p className={styles.productHeaderTagline}>{productSection.tagline}</p>
+            </div>
+          );
+        })()}
       {navGroups.map((group) => (
         <div key={group.title} className={styles.navGroup}>
           <h4 className={styles.navGroupTitle}>{group.title}</h4>
@@ -150,8 +211,14 @@ export function DocsNav({ variant = 'sidebar' }: { variant?: 'sidebar' | 'mobile
               const isActive =
                 pathname === href ||
                 (item.slug === 'introduction' &&
-                  (pathname === '/docs' || pathname === legacyDocsBasePath || pathname === v8DocsBasePath));
-              const Icon = navIcons[item.slug] ?? BookOpen;
+                  (productSection
+                    ? pathname === docsBasePath
+                    : pathname === '/docs' ||
+                      pathname === legacyDocsBasePath ||
+                      pathname === v8DocsBasePath));
+              const Icon = productSection
+                ? (productNavIcons[item.slug] ?? BookOpen)
+                : (navIcons[item.slug] ?? BookOpen);
               return (
                 <li key={item.slug}>
                   <Link href={href} className={`${styles.navLink} ${isActive ? styles.navLinkActive : ''}`}>
diff --git a/web/components/docs/DocsSearch.tsx b/web/components/docs/DocsSearch.tsx
index 9dbb385c..9ee108b4 100644
--- a/web/components/docs/DocsSearch.tsx
+++ b/web/components/docs/DocsSearch.tsx
@@ -3,13 +3,21 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import Link from 'next/link';
-import { useRouter } from 'next/navigation';
+import { usePathname, useRouter } from 'next/navigation';
 
 import type { SearchEntry } from '../../lib/docs';
 import s from './docs-search.module.css';
 
+export interface ProductSearchScope {
+  id: string;
+  label: string;
+  basePath: string;
+  index: SearchEntry[];
+}
+
 interface DocsSearchProps {
   index: SearchEntry[];
+  productScopes?: ProductSearchScope[];
 }
 
 function search(query: string, index: SearchEntry[]): SearchEntry[] {
@@ -36,13 +44,20 @@ function search(query: string, index: SearchEntry[]): SearchEntry[] {
     .map((r) => r.entry);
 }
 
-export function DocsSearch({ index }: DocsSearchProps) {
+export function DocsSearch({ index, productScopes = [] }: DocsSearchProps) {
   const [open, setOpen] = useState(false);
   const [query, setQuery] = useState('');
   const [activeIdx, setActiveIdx] = useState(0);
   const inputRef = useRef<HTMLInputElement>(null);
   const router = useRouter();
-  const results = search(query, index);
+  const pathname = usePathname();
+
+  const activeScope = productScopes.find(
+    (scope) => pathname === scope.basePath || pathname?.startsWith(`${scope.basePath}/`)
+  );
+  const activeIndex = activeScope?.index ?? index;
+  const basePath = activeScope?.basePath ?? '/docs';
+  const results = search(query, activeIndex);
 
   const close = useCallback(() => {
     setOpen(false);
@@ -53,9 +68,9 @@ export function DocsSearch({ index }: DocsSearchProps) {
   const navigate = useCallback(
     (slug: string) => {
       close();
-      router.push(`/docs/${slug}`);
+      router.push(`${basePath}/${slug}`);
     },
-    [close, router]
+    [basePath, close, router]
   );
 
   // Reset active index when results change
@@ -135,7 +150,7 @@ export function DocsSearch({ index }: DocsSearchProps) {
                 <input
                   ref={inputRef}
                   className={s.input}
-                  placeholder="Search documentation..."
+                  placeholder={activeScope ? `Search ${activeScope.label} docs...` : 'Search documentation...'}
                   value={query}
                   onChange={(e) => setQuery(e.target.value)}
                 />
@@ -152,7 +167,7 @@ export function DocsSearch({ index }: DocsSearchProps) {
                     results.map((entry, i) => (
                       <Link
                         key={entry.slug}
-                        href={`/docs/${entry.slug}`}
+                        href={`${basePath}/${entry.slug}`}
                         className={`${s.result} ${i === activeIdx ? s.resultActive : ''}`}
                         onClick={() => close()}
                         onMouseEnter={() => setActiveIdx(i)}
diff --git a/web/components/docs/ProductDocPage.tsx b/web/components/docs/ProductDocPage.tsx
new file mode 100644
index 00000000..756ff8f8
--- /dev/null
+++ b/web/components/docs/ProductDocPage.tsx
@@ -0,0 +1,58 @@
+import { notFound } from 'next/navigation';
+import { evaluate } from '@mdx-js/mdx';
+import { Fragment } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import remarkGfm from 'remark-gfm';
+
+import { getProductDoc, getProductDocMarkdownUrl } from '../../lib/product-docs';
+import { absoluteUrl } from '../../lib/site';
+import { DocsPageActions } from './DocsPageActions';
+import { mdxComponents } from './mdx-components';
+import { TableOfContents } from './TableOfContents';
+import styles from './docs.module.css';
+
+export async function ProductDocPage({ sectionId, slug }: { sectionId: string; slug: string }) {
+  const doc = getProductDoc(sectionId, slug);
+
+  if (!doc) {
+    notFound();
+  }
+
+  const { default: MDXContent } = await evaluate(doc.content, {
+    Fragment,
+    jsx,
+    jsxs,
+    remarkPlugins: [remarkGfm],
+  } as Parameters<typeof evaluate>[1]);
+
+  const pageUrl = absoluteUrl(`/docs/${sectionId}/${slug}`);
+  const markdownPath = `/docs/${sectionId}/markdown/${slug}.md`;
+  const markdownUrl = getProductDocMarkdownUrl(sectionId, slug);
+
+  return (
+    <div className={styles.articleWrapper}>
+      <article className={styles.article}>
+        <div className={styles.articleHeader}>
+          <div className={styles.articleHeading}>
+            <h1>{doc.frontmatter.title}</h1>
+          </div>
+          <DocsPageActions
+            title={doc.frontmatter.title}
+            pageUrl={pageUrl}
+            markdownPath={markdownPath}
+            markdownUrl={markdownUrl}
+          />
+        </div>
+        {doc.frontmatter.description && (
+          <p className={styles.articleDescription}>{doc.frontmatter.description}</p>
+        )}
+        <div className={styles.articleBody}>
+          <MDXContent components={mdxComponents} />
+        </div>
+      </article>
+      <aside className={styles.tocSidebar}>
+        <TableOfContents items={doc.toc} />
+      </aside>
+    </div>
+  );
+}
diff --git a/web/components/docs/docs.module.css b/web/components/docs/docs.module.css
index cd237eab..56cbf8be 100644
--- a/web/components/docs/docs.module.css
+++ b/web/components/docs/docs.module.css
@@ -273,6 +273,59 @@
   transform: translateY(-50%);
 }
 
+/* ── Product section sidebar header (Relayfile / Relayloop) ── */
+
+.productHeader {
+  margin-bottom: 1.4rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--line);
+}
+
+.productBackLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  font-size: 0.74rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--fg-faint);
+  text-decoration: none;
+  margin-bottom: 0.75rem;
+  transition: color 0.15s;
+}
+
+.productBackLink:hover {
+  color: var(--primary);
+}
+
+.productHeaderName {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 1.05rem;
+  font-weight: 700;
+  color: var(--fg);
+  text-decoration: none;
+}
+
+.productHeaderName:hover {
+  color: var(--primary);
+}
+
+.productHeaderIcon {
+  width: 1.1rem;
+  height: 1.1rem;
+  color: var(--primary);
+}
+
+.productHeaderTagline {
+  margin: 0.4rem 0 0;
+  font-size: 0.8rem;
+  line-height: 1.4;
+  color: var(--fg-muted);
+}
+
 .navGroup {
   margin-bottom: 1.25rem;
 }
diff --git a/web/components/docs/mdx-components.tsx b/web/components/docs/mdx-components.tsx
new file mode 100644
index 00000000..1f21dde2
--- /dev/null
+++ b/web/components/docs/mdx-components.tsx
@@ -0,0 +1,45 @@
+import type React from 'react';
+
+import { BannerLink } from './BannerLink';
+import { Card } from './Card';
+import { CardGroup } from './CardGroup';
+import { CodeGroup } from './CodeGroup';
+import { HighlightedPre } from './HighlightedCode';
+import { LegacySpawnOptionsTable } from './LegacySpawnOptionsTable';
+import { Note } from './Note';
+import { Warning } from './Warning';
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function HeadingWithId(level: 2 | 3) {
+  return function Heading({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+    const text = typeof children === 'string' ? children : String(children);
+    const id = slugify(text);
+    const Tag = `h${level}` as const;
+    return (
+      <Tag id={id} {...props}>
+        {children}
+      </Tag>
+    );
+  };
+}
+
+/** Component map shared by every MDX docs renderer (Agent Relay + product sections). */
+export const mdxComponents = {
+  CodeGroup,
+  Card,
+  CardGroup,
+  BannerLink,
+  Note,
+  Warning,
+  SpawnOptionsTable: LegacySpawnOptionsTable,
+  pre: HighlightedPre,
+  h2: HeadingWithId(2),
+  h3: HeadingWithId(3),
+};
diff --git a/web/content/docs/file/acls.mdx b/web/content/docs/file/acls.mdx
new file mode 100644
index 00000000..401aa576
--- /dev/null
+++ b/web/content/docs/file/acls.mdx
@@ -0,0 +1,58 @@
+---
+title: 'ACLs'
+description: 'Scope each agent to exactly the paths it should read and write with per-agent ACLs, so multi-agent fleets run least-privilege by default.'
+---
+
+In a multi-agent fleet you rarely want every agent to see and mutate the whole tree. Relayfile scopes each agent's read and write surface with per-agent ACLs, so an agent sees only the paths it should — readonly on the rest of the tree, fully invisible where you want it invisible. Least-privilege becomes a property of the substrate rather than something each app re-implements.
+
+## Scoping an agent
+
+ACLs are expressed via `.relayfile.acl` and map an agent to the paths it may read and write. The model is path-scoped: an agent's grant is a set of read and write globs, and any operation outside them is denied.
+
+A common pattern is a reviewer agent that can read everything under `/notion` but only write Linear follow-ups:
+
+```text
+# agent: reviewer
+read   /notion/**
+read   /linear/**
+write  /linear/issues/**
+```
+
+An implementer agent might have the inverse — write to a narrow slice and read broadly:
+
+```text
+# agent: label-bot
+read   /linear/**
+write  /linear/labels/**
+```
+
+Anything not listed is denied. The rest of the tree is readonly (or invisible) to that agent depending on how you scope its reads.
+
+## Readonly by default
+
+The safe default is readonly: an agent can `ls`, `cat`, and `grep` its readable paths but cannot write back unless a write grant explicitly covers the path. This means handing a new agent a workspace token is non-destructive by default — it can observe and synthesize without any risk of mutating provider state until you grant writes.
+
+<Note>
+  When you scope tokens through the SDK or Cloud, request the path-scoped form (`relayfile:fs:read:/notion/**`, `relayfile:fs:write:/linear/labels/**`) for true least-privilege. Requesting a bare `fs:read` / `fs:write` scope can fall back to a broad grant. See [The SDK](/docs/file/sdk) and [Relayfile Cloud](/docs/file/cloud).
+</Note>
+
+## Multi-agent least privilege
+
+ACLs are what make a fleet of agents safe to run against the same workspace. Each agent gets a narrow, scoped surface:
+
+- Agent A — `read /notion/**` only. A pure summarizer; can never mutate anything.
+- Agent B — `read /linear/**`, `write /linear/labels/**`. Can triage labels and nothing else.
+- Agent C — `read /github/**`, `write /github/repos/acme/api/pulls/**`. Reviews PRs in one repo.
+
+Because the agents coordinate through the same filesystem (see [Real-time sync](/docs/file/realtime-sync)), they can observe each other's writes in real time while remaining unable to step outside their own grant. A denied write is rejected, not silently dropped, so misconfiguration surfaces immediately rather than corrupting state.
+
+This is the per-agent equivalent of giving each microservice its own credentials: the blast radius of any single agent is bounded by its ACL, not by the size of the workspace.
+
+<CardGroup cols={2}>
+  <Card title="Reads and writes" href="/docs/file/reads-and-writes">
+    What read and write operations the ACL grants apply to.
+  </Card>
+  <Card title="The SDK" href="/docs/file/sdk">
+    Mint downscoped tokens per agent with `agentInviteScoped`.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/adapters-and-providers.mdx b/web/content/docs/file/adapters-and-providers.mdx
new file mode 100644
index 00000000..1ec1db02
--- /dev/null
+++ b/web/content/docs/file/adapters-and-providers.mdx
@@ -0,0 +1,81 @@
+---
+title: 'Adapters and providers'
+description: 'Relayfile is a core file server plus pluggable adapters (webhook-to-path mapping, writeback) and providers (auth and proxy via Nango, Composio, Pipedream).'
+---
+
+Relayfile's architecture is deliberately split into three layers: a core file server, a set of **adapters** that map provider data into paths, and a set of **providers** that handle auth and API access. This is what lets one provider integration unlock tens of apps, and what lets you self-host only the pieces you need.
+
+## The three layers
+
+- **Core file server** ([relayfile](https://github.com/AgentWorkforce/relayfile)). The VFS API, scoped tokens, generic event ingest, the writeback queue, the operation log, and the mount layer. This is what every deployment runs.
+- **Adapters** ([relayfile-adapters](https://github.com/AgentWorkforce/relayfile-adapters)). Per-integration logic: how a provider's webhooks and objects map into Relayfile paths, how events are normalized into a consistent shape, and how writeback behaves for each resource type.
+- **Providers** ([relayfile-providers](https://github.com/AgentWorkforce/relayfile-providers)). Provider auth, token lookup, API proxying, webhook subscriptions, and connection health — backed by Nango, Composio, or Pipedream.
+
+The core server never stores third-party OAuth credentials. It receives normalized files, webhook envelopes, writeback operations, and a `connectionId` that identifies the provider connection. Credentials stay in the provider layer.
+
+## What adapters do
+
+An adapter is the integration's brain. For a given provider it defines:
+
+- **Webhook-to-path mapping.** A Linear `Issue.create` event becomes `/linear/issues/AGE-12__fix-login-bug.json`. The adapter decides the directory structure and the canonical naming.
+- **Event normalization.** Different providers fire wildly different payloads; the adapter turns each into a consistent file event so agents never see provider-specific webhook shapes.
+- **Writeback behavior.** When an agent writes a canonical path, the adapter knows how to translate that into the right provider API call (PATCH, create, delete) and what the resource schema is.
+
+An adapter alone gives you path mapping plus writeback. It does **not** by itself backfill historical data — that requires a sync definition.
+
+<Note>
+  Sync coverage matters. A provider with both an adapter and a shipped sync definition does an initial backfill plus live events. A provider with only an adapter has no backfill — you ingest just what you push. Picking a path-mapping-only provider and getting an empty tree is the common trap. The sync definitions themselves are a scoped engagement; the ingest scaffolding is OSS.
+</Note>
+
+## What providers do
+
+A provider handles getting data in and out of the SaaS tool itself:
+
+- **Auth and token lookup** — resolving the OAuth connection identified by `connectionId`.
+- **API proxying** — making the actual provider API calls for reads and writeback.
+- **Webhook subscriptions** — registering for the events the adapter maps.
+- **Connection health** — reporting whether a connection is live.
+
+Because providers are backed by aggregators (Nango, Composio, Pipedream), one provider integration unlocks the many apps that aggregator supports — you don't write a bespoke OAuth dance per SaaS tool.
+
+## Bring existing connections
+
+Relayfile tracks provider identity as `connectionId` metadata. The core server can ingest events and queue writebacks against a `connectionId`, but the provider layer must be able to use that ID. If you already have connections in an aggregator, you can bring them:
+
+<CodeGroup>
+```text Nango
+# self-hosted: point the Nango provider at your host/secret and
+# link the workspace to the existing connection before sync
+workspace_id         relayfile workspace id
+provider             e.g. notion or github
+connection_id        existing Nango connection id
+provider_config_key  Nango provider config key
+```
+
+```text Composio
+# use your Composio API key and the existing connected-account ID
+# as the Relayfile connectionId; verify with getConnectedAccount /
+# healthCheck, then proxy reads/writeback through that account
+```
+
+```text Pipedream
+# use your Pipedream Connect project credentials and the existing
+# account ID as the connectionId; proxy calls also need the external
+# user id via x-pd-external-user-id, query, or a resolver callback
+```
+</CodeGroup>
+
+Hosted `agentrelay.com` currently exposes a connect-session flow through the CLI, not a public import command for arbitrary existing Nango connections. If a connection lives in a different Nango project, re-connect through the hosted flow or run your own provider-backed stack.
+
+## Self-host vs hosted
+
+Fully self-hosting provider-backed files means running the core server, a scoped JWT issuer (relayauth or compatible), the adapters and providers for the systems you expose, and Nango for OAuth. [Relayfile Cloud](/docs/file/cloud) runs all of these for you. The OSS surface deliberately ships the VFS, scoped tokens, generic ingest, writeback queue, and mount; the polished OAuth connect flow and the provider sync definitions are either hosted or part of your self-host provider stack.
+
+<CardGroup cols={2}>
+  <Card title="Reads and writes" href="/docs/file/reads-and-writes">
+    The PATCH / CREATE / DELETE model adapters implement.
+  </Card>
+  <Card title="Relayfile Cloud" href="/docs/file/cloud">
+    The managed path that runs adapters and providers for you.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/agents.mdx b/web/content/docs/file/agents.mdx
new file mode 100644
index 00000000..764dd5ac
--- /dev/null
+++ b/web/content/docs/file/agents.mdx
@@ -0,0 +1,103 @@
+---
+title: 'Agents'
+description: 'One connect() call gives your agent path-scoped read tools, a writeback lifecycle, and reactive onEvent webhooks — identically across Vercel AI SDK, OpenAI Agents SDK, and LangChain.'
+---
+
+`@relayfile/agents` is a thin framework adapter over [the SDK](/docs/file/sdk). One `connect()` call gives your agent path-scoped read tools, a proven writeback lifecycle, and `onEvent` reactive webhooks — working identically against the Vercel AI SDK, OpenAI Agents SDK, and LangChain. Examples never reach into `@relayfile/sdk` directly; the package re-exports the type surface and the error classes you need.
+
+```bash
+npm install @relayfile/agents
+```
+
+## One connect, three frameworks
+
+`connect()` runs the canonical Cloud bootstrap and returns a handle. `tools.*` adapt that handle into each framework's native tool shape:
+
+```ts
+import { connect, tools } from "@relayfile/agents"
+
+const rf = await connect({ scopes: ["relayfile:fs:read:/notion/**"] })
+
+// Vercel AI SDK
+const { text } = await generateText({
+  model: anthropic("claude-sonnet-4-6"),
+  tools: tools.vercel(rf, { readPaths: ["/notion"] }),
+  prompt: "Summarise the Notion workspace.",
+})
+
+// OpenAI Agents SDK
+const agent = new Agent({ name: "x", tools: tools.openai(rf, { readPaths: ["/notion"] }) })
+
+// LangChain
+const graph = createReactAgent({ tools: tools.langchain(rf, { readPaths: ["/notion"] }) })
+```
+
+The interface is **O(1)** in the number of providers: `listTree` / `readFile` / writeback work identically across every integration, so adding `/linear` or `/github` doesn't add tool schemas the model must learn.
+
+## The connect handle
+
+```ts
+const rf = await connect({ workspaceId?, scopes?, agentName? })
+// → { client, workspaceId, cloudWorkspaceId, credSource, writeback }
+```
+
+- `rf.client` — the raw `RelayFileClient` escape hatch for anything the helpers don't cover.
+- `rf.workspaceId` — the `rw_` id from join; use it for any direct SDK calls.
+- `rf.writeback.*` — the writeback lifecycle helpers below.
+
+## Writeback lifecycle
+
+The `writeback` helpers wrap the create / read / update / delete cycle with the right `baseRevision` and conflict handling:
+
+```ts
+rf.writeback.create(root, payload, opts?)              // CREATE a record under a root
+rf.writeback.readCanonical(canonicalPath, opts?)        // read the canonical entity
+rf.writeback.update(canonicalPath, baseRevision, patch) // PATCH with optimistic concurrency
+rf.writeback.delete(canonicalPath, baseRevision, opts?) // DELETE the record
+rf.writeback.deleteDraft(draftPath)                     // local-only Relayfile cleanup
+```
+
+Concurrency safety comes from `baseRevision` plus `RevisionConflictError` — two agents writing the same record don't silently clobber. See [Reads and writes](/docs/file/reads-and-writes) for the underlying model.
+
+## Reactive onEvent
+
+The biggest structural difference from per-provider MCPs is that Relayfile is event-driven, not request/response. Every provider webhook becomes a workspace file event any number of agents can subscribe to:
+
+```
+Linear webhook → Cloud sync → /linear/issues/X.json revision++ → WebSocket event
+                                                                      ↓
+                                                  agent A reacts, writes a comment
+                                                  agent B reacts, files a Slack ping
+                                                  agent C reacts, opens a PR
+```
+
+The SDK exposes `connectWebSocket({ onEvent })` and a glob-based `subscribe()` for filtering. This is the substrate for **proactive agents** — agents reacting to provider state changes rather than waiting for a prompt. See [Real-time sync](/docs/file/realtime-sync).
+
+## Works with
+
+Anything that can read and write files works with Relayfile — that's the point. Confirmed integration recipes ship for:
+
+| Framework | Recipe |
+|---|---|
+| Claude Code | the `setting-up-relayfile` skill |
+| Vercel AI SDK | `@relayfile/agents` · Notion read · Linear writeback · reactive `onEvent` |
+| OpenAI Agents SDK | `@relayfile/agents` · Notion read · Linear writeback |
+| LangChain | `@relayfile/agents` · Notion read · Linear writeback |
+| Anything that runs `bash` | works out of the box (it's a real OS mount) |
+
+## When to use this vs a provider MCP
+
+Honest answer: for **1 provider × 1 agent × one-shot action**, a dedicated provider MCP is simpler and can model provider-specific operations richer than a generic schema-validate-and-write. For **N providers and/or N agents**, Relayfile is the substrate and the gap widens with each one added — a shared, ACL'd, versioned filesystem rather than a per-provider client. The two compose: Relayfile for the stateful multi-provider substrate, an MCP for typed one-shot writes. See [Comparison](/docs/file/comparison).
+
+## Credentials
+
+Two sources, in order: env overrides for CI (`CLOUD_API_URL`, `CLOUD_API_ACCESS_TOKEN`, `CLOUD_WORKSPACE_ID`), then `~/.agentworkforce/relay/cloud-auth.json` written by `agent-relay cloud login`. One login per machine; per-app permissions live in Cloud.
+
+<CardGroup cols={2}>
+  <Card title="The SDK" href="/docs/file/sdk">
+    The `RelayFileClient` and `RelayfileSetup` this package wraps.
+  </Card>
+  <Card title="Real-time sync" href="/docs/file/realtime-sync">
+    The change stream that powers `onEvent`.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/api-reference.mdx b/web/content/docs/file/api-reference.mdx
new file mode 100644
index 00000000..9457aee0
--- /dev/null
+++ b/web/content/docs/file/api-reference.mdx
@@ -0,0 +1,167 @@
+---
+title: 'API reference'
+description: 'The Relayfile v1 HTTP API: Bearer auth, the workspace filesystem endpoints (tree, file, bulk, events), and the sync and writeback surfaces.'
+---
+
+The Relayfile data plane is a plain HTTP API. Every workspace operation — reading the tree, reading and writing files, ingesting webhooks, checking sync status — is a request against `/v1/workspaces/{workspaceId}/...`. The full machine-readable contract is the OpenAPI spec in the repo at [`openapi/relayfile-v1.openapi.yaml`](https://github.com/AgentWorkforce/relayfile/blob/main/openapi/relayfile-v1.openapi.yaml); this page is the runnable summary.
+
+## Authentication
+
+Authenticated requests carry a Bearer token and a correlation ID:
+
+```bash
+export RELAYFILE_BASE_URL=http://127.0.0.1:8080
+export RELAYFILE_WORKSPACE=ws_live
+export RELAYFILE_TOKEN="$(./scripts/generate-dev-token.sh ${RELAYFILE_WORKSPACE})"
+export RELAYFILE_CORRELATION_ID="corr_$(date +%s)"
+```
+
+Every authenticated call includes:
+
+```bash
+-H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+-H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}"
+```
+
+`X-Correlation-Id` is **required** on authenticated HTTP requests — it's used for traceability and auditability across requests. Tokens are scope-aware: the OpenAPI contract defines `fs:read` and `fs:write` scopes, and the data plane enforces them. Do **not** send `X-Workspace-Id`; the routing layer sets it internally.
+
+<Warning>
+  Use the `rw_…` workspace ID returned by `mount-session` / join for every data-plane call — never the request-side app UUID. Passing an app UUID returns `404 workspace_not_found`. The [SDK](/docs/file/sdk) resolves this for you; raw-HTTP callers must resolve it first.
+</Warning>
+
+## Health
+
+`GET /health` returns a liveness response and requires no auth:
+
+```bash
+curl -sS "${RELAYFILE_BASE_URL}/health" | jq .
+```
+
+## Filesystem
+
+The filesystem endpoints are the core surface. All are scoped to a workspace.
+
+### List a tree
+
+`GET /v1/workspaces/{workspaceId}/fs/tree` lists files and directories under a path.
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/fs/tree?path=/&depth=2" | jq .
+```
+
+### Read a file
+
+`GET /v1/workspaces/{workspaceId}/fs/file` reads one file.
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/fs/file?path=/README.md" | jq .
+```
+
+### Write a file
+
+`PUT /v1/workspaces/{workspaceId}/fs/file` creates or updates one file.
+
+```bash
+curl -sS -X PUT \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}" \
+  -H "Content-Type: application/json" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/fs/file" \
+  -d '{ "path": "/docs/guide.md", "content": "# agent guide", "contentType": "text/markdown" }' | jq .
+```
+
+### Delete a file
+
+`DELETE /v1/workspaces/{workspaceId}/fs/file` deletes one file.
+
+```bash
+curl -sS -X DELETE \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/fs/file?path=/docs/guide.md" | jq .
+```
+
+### Bulk write
+
+`POST /v1/workspaces/{workspaceId}/fs/bulk` writes many files in one request.
+
+```bash
+curl -sS -X POST \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}" \
+  -H "Content-Type: application/json" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/fs/bulk" \
+  -d '{ "files": [ { "path": "/src/app.js", "content": "console.log(1);", "contentType": "application/javascript" } ] }' | jq .
+```
+
+### Other filesystem endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET .../fs/events?path=/&limit=20` | Read the filesystem event feed |
+| `GET .../fs/query?path=/documents&...` | Structured metadata query (filters synced metadata, not path) |
+| `GET .../fs/export?format=json\|tar\|patch` | Export visible files, optionally scoped with `path=` |
+| `GET .../fs/ws?token=...` | Upgrade to a WebSocket stream of real-time changes |
+
+<Note>
+  `fs/query` matches against each file's synced `provider`/`semantics` metadata, not the path prefix — a provider's content is only queryable if its sync tags that metadata. For reads over un-tagged providers, prefer `fs/tree` + `fs/file`. The [SDK](/docs/file/sdk) wraps all of these as `listTree`, `readFile`, `writeFile`, `bulkWrite`, `deleteFile`, `queryFiles`, and `subscribe`.
+</Note>
+
+## Sync
+
+Inspect and drive provider sync for a workspace:
+
+| Endpoint | Purpose |
+|---|---|
+| `GET .../sync/status` | Workspace sync status (per-provider readiness) |
+| `GET .../sync/ingress` | Ingress queue and reliability counters |
+| `GET .../sync/dead-letter` | List dead-letter envelopes |
+| `POST .../sync/dead-letter/{id}/replay` | Replay one dead-letter envelope |
+| `POST .../sync/dead-letter/{id}/ack` | Acknowledge a dead-letter envelope |
+| `POST .../sync/refresh` | Trigger a sync refresh |
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: ${RELAYFILE_CORRELATION_ID}" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/sync/status" | jq .
+```
+
+## Webhooks and writeback
+
+Push normalized provider events in, and drive outbound writeback work:
+
+| Endpoint | Purpose |
+|---|---|
+| `POST .../webhooks/ingest` | Submit a provider-agnostic webhook into a workspace |
+| `POST /v1/internal/webhook-envelopes` | Internal envelope ingest (trusted callers; may require HMAC in prod) |
+| `GET .../writeback/pending` | List outbound writeback items awaiting a provider |
+| `POST .../writeback/{itemId}/ack` | Acknowledge a processed writeback item |
+
+```bash
+curl -sS -X POST \
+  -H "Authorization: Bearer ${RELAYFILE_TOKEN}" \
+  -H "X-Correlation-Id: webhook_test_1" \
+  -H "Content-Type: application/json" \
+  "${RELAYFILE_BASE_URL}/v1/workspaces/${RELAYFILE_WORKSPACE}/webhooks/ingest" \
+  -d '{ "provider": "salesforce", "event_type": "file.updated", "path": "/salesforce/Account_123", "data": { "content": "Account details", "contentType": "text/plain" }, "delivery_id": "sf_evt_123" }' | jq .
+```
+
+## Operations and admin
+
+`GET .../ops`, `GET .../ops/{opId}`, and `POST .../ops/{opId}/replay` list, fetch, and replay workspace operations. The admin plane (`/v1/admin/...`) exposes backend config, cross-workspace ingress and sync health, and envelope/op replay. Most workspace and admin endpoints use Bearer auth; internal ingress may use service-to-service signing in production.
+
+<CardGroup cols={2}>
+  <Card title="The SDK" href="/docs/file/sdk">
+    The typed client over this HTTP surface.
+  </Card>
+  <Card title="OpenAPI spec" href="https://github.com/AgentWorkforce/relayfile/blob/main/openapi/relayfile-v1.openapi.yaml">
+    The full machine-readable v1 contract.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/cli.mdx b/web/content/docs/file/cli.mdx
new file mode 100644
index 00000000..6104b5bf
--- /dev/null
+++ b/web/content/docs/file/cli.mdx
@@ -0,0 +1,163 @@
+---
+title: 'CLI reference'
+description: 'The relayfile CLI: setup, login, seed, tree, mount, and the relayfile-mount daemon flags, with auth and token resolution rules.'
+---
+
+The `relayfile` CLI is the primary interface for humans and CI to work with Relayfile workspaces. It wraps the HTTP API and the mount sync engine into one tool: minimal flags, sensible defaults, composable with pipes (`--json` everywhere), and no implicit destructive actions (deletes require `--yes`).
+
+## Authentication
+
+The CLI resolves a token in priority order, first match wins:
+
+1. `--token` flag (one-off override)
+2. `RELAYFILE_TOKEN` env var (CI/CD)
+3. the canonical relay cloud session (cloud-hosted interactive use)
+4. `~/.relayfile/credentials.json` (self-hosted / API-key compatibility)
+
+For the cloud-hosted path, login is owned by the `agent-relay` CLI: `agent-relay login`, then `agent-relay workspace switch <name>`, then any `relayfile` command. For self-hosted servers, use the API-key path:
+
+```bash
+relayfile login --api-key --server https://api.relayfile.dev
+```
+
+If no token is found, the CLI prints: `Error: not authenticated. Run 'agent-relay login' for Cloud or set RELAYFILE_TOKEN.`
+
+## `relayfile setup`
+
+The low-friction Cloud setup path for humans and agent-guided onboarding. It ensures you're logged in, creates or joins a Cloud workspace, requests a hosted connect session for the chosen provider, waits until it reports ready, and starts the mount loop.
+
+```bash
+relayfile setup --provider notion --workspace my-project --local-dir ./relayfile-mount
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--provider` | prompted (`github`) | Integration to connect; `none` to skip |
+| `--workspace` | prompted | Workspace name to create or join |
+| `--local-dir` | prompted (`./relayfile-mount`) | Local mount directory |
+| `--cloud-api-url` | `https://agentrelay.com/cloud` | Cloud API URL |
+| `--cloud-token` | `RELAYFILE_CLOUD_TOKEN` | Cloud token for headless setup; skips browser login |
+| `--no-open` | `false` | Print login/connect URLs instead of opening a browser |
+| `--skip-mount` | `false` | Complete setup without starting the mount loop |
+| `--once` | `false` | Run one mount sync cycle and exit |
+
+Re-running with the same workspace name reuses the workspace, refreshes the session, and only opens a new connect flow when the provider isn't already connected. See [Relayfile Cloud](/docs/file/cloud).
+
+## `relayfile login`
+
+Authenticate through the canonical relay session, or the self-hosted API-key path.
+
+```bash
+relayfile login [--no-open]
+relayfile login --api-key --server https://api.relayfile.dev
+```
+
+The default path delegates to `agent-relay login`. `--api-key` keeps the self-hosted compatibility path and writes `~/.relayfile/credentials.json` with `0600` permissions.
+
+## `relayfile seed`
+
+Bulk-upload a local directory into a workspace, respecting `.gitignore` and `--exclude` patterns.
+
+```bash
+relayfile seed my-workspace ./src
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--exclude` | (none) | Glob patterns to exclude (repeatable) |
+| `--dry-run` | `false` | List files that would upload, without uploading |
+| `--batch-size` | `50` | Files per bulk API request |
+
+It walks the directory and posts batches to the bulk write endpoint, printing progress.
+
+## `relayfile tree`
+
+List a remote workspace path without mounting.
+
+```bash
+relayfile tree my-workspace / --depth 2
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--depth` | `1` | Maximum tree depth |
+| `--json` | `false` | Print the raw API response |
+
+Prints a compact human-readable tree by default; `--json` is for scripts. `relayfile read <workspace> <path>` (alias `relayfile cat`) reads a single file the same way.
+
+## `relayfile mount`
+
+Mount a workspace to a local directory, syncing changes in real time. This replaces the standalone daemon for end users.
+
+```bash
+relayfile mount my-workspace ./local-mirror
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--interval` | `30s` | Polling interval between sync cycles |
+| `--once` | `false` | Run a single sync cycle and exit (CI) |
+| `--mode` | `poll` | `poll` (synced mirror, recommended) or `fuse` (opt-in, POSIX) |
+| `--background` | `false` | Detach; write PID to `.relay/mount.pid`, logs to `.relay/mount.log` |
+| `--no-websocket` | `false` | Disable WebSocket streaming, poll only |
+
+In `poll` mode the daemon maintains a synced mirror accelerated by a WebSocket invalidation channel. `fuse` mode is gated by build tags and unavailable in the OSS build (the CLI exits cleanly with a clear message rather than falling back silently). Stop a background mount with `relayfile stop` and tail its log with `relayfile logs`.
+
+## The `relayfile-mount` daemon
+
+`cmd/relayfile-mount` is the minimal single-purpose daemon, kept for backwards compatibility and deployments that want it directly. It's configured by flags or environment variables:
+
+```bash
+RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
+  --base-url http://localhost:9090 \
+  --workspace ws_demo \
+  --local-dir ./relayfile-mount \
+  --remote-path /github \
+  --fuse-content-ttl 10s
+```
+
+| Flag / env | Default | Description |
+|---|---|---|
+| `--base-url` / `RELAYFILE_BASE_URL` | `http://127.0.0.1:8080` | Relayfile API base URL |
+| `--workspace` / `RELAYFILE_WORKSPACE` | — (required) | Workspace ID to mount |
+| `--local-dir` / `RELAYFILE_LOCAL_DIR` | — (required) | Local mirror directory |
+| `RELAYFILE_TOKEN` | — (required) | Bearer token |
+| `--remote-path` / `RELAYFILE_REMOTE_PATH` | `/` | Remote subtree to mirror (repeatable) |
+| `--paths-file` | — | JSON array or newline list of remote roots |
+| `--fuse-content-ttl` / `RELAYFILE_MOUNT_FUSE_CONTENT_TTL` | `30s` | FUSE content cache TTL |
+| `RELAYFILE_MOUNT_INTERVAL` | `2s` | Polling interval |
+| `RELAYFILE_MOUNT_TIMEOUT` | `15s` | Per-sync timeout |
+
+See [Run locally](/docs/file/run-locally) for the daemon in context and [Local development](/docs/file/local-development) for the no-Docker loop.
+
+## Other commands
+
+| Command | Purpose |
+|---|---|
+| `relayfile workspace create / list / delete` | Manage workspaces |
+| `relayfile export` | Download a snapshot (`--format tar\|json\|patch`) |
+| `relayfile status` | Per-provider sync state, lag, conflicts, denials |
+| `relayfile integration connect / list / disconnect` | Manage provider integrations after setup |
+| `relayfile pull` | Force a reconcile of a path or the whole workspace |
+| `relayfile permissions` | Show writable paths and expected schema for a path |
+| `relayfile ops list / replay` | Inspect and replay dead-lettered writeback ops |
+| `relayfile stop` / `relayfile logs` | Control and read a background mount daemon |
+
+## Global flags
+
+| Flag | Env var | Description |
+|---|---|---|
+| `--server` | `RELAYFILE_SERVER` | Server base URL |
+| `--token` | `RELAYFILE_TOKEN` | Bearer token |
+| `--workspace` | `RELAYFILE_WORKSPACE` | Workspace name or ID |
+| `--json` | — | Emit JSON instead of tables |
+| `--verbose` | — | Debug logging to stderr |
+
+<CardGroup cols={2}>
+  <Card title="Run locally" href="/docs/file/run-locally">
+    The Docker stack and the mount daemon in context.
+  </Card>
+  <Card title="Relayfile Cloud" href="/docs/file/cloud">
+    What `relayfile setup` connects to.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/cloud.mdx b/web/content/docs/file/cloud.mdx
new file mode 100644
index 00000000..50dff851
--- /dev/null
+++ b/web/content/docs/file/cloud.mdx
@@ -0,0 +1,69 @@
+---
+title: 'Relayfile Cloud'
+description: 'Hosted Agent Relay runs the workspace, scoped auth, Nango OAuth, sync workers, and writeback workers — connect provider-backed files with one token.'
+---
+
+If you want Notion, Slack, Linear, GitHub, or other provider-backed files without running any infrastructure, use Hosted Agent Relay. Agent Relay Cloud runs the workspace, the Relayfile API, scoped auth, Nango OAuth, provider sync workers, and writeback workers for you. Your agents connect with a single token; there's no integration runtime on your machine.
+
+## The setup flow
+
+`relayfile setup` is the human and agent-guided entry point. It connects to `agentrelay.com`, creates or joins a cloud workspace, completes provider auth, waits for sync, and mounts the resulting files:
+
+```bash
+relayfile setup \
+  --provider notion \
+  --workspace my-agent \
+  --local-dir ./relayfile-mount \
+  --no-open
+```
+
+`--no-open` prints the hosted login and connect URLs instead of opening a browser, which is what you want inside agents and headless environments. The local directory is just the agent's file interface — the integration stack is hosted. Re-running with the same workspace name reuses the workspace, refreshes the session, and only opens a new connect flow when the requested provider isn't already connected.
+
+After setup, hand the agent the mount path and it reads and writes under `$RELAYFILE_LOCAL_DIR/<provider>/...` instead of calling provider APIs directly:
+
+```bash
+export RELAYFILE_LOCAL_DIR="$PWD/relayfile-mount"
+```
+
+For the programmatic equivalent from inside an authorized sandbox, see [Mounting from a sandbox](/docs/file/mounting).
+
+## What Cloud manages
+
+Cloud runs the whole integration path so you don't operate the stack:
+
+- **Managed OAuth (Nango).** The polished connect-session flow and provider credentials.
+- **Provider sync workers.** Initial backfill plus live webhook ingestion, normalized into the file tree.
+- **Writeback workers.** Your agents' file writes turned into provider API calls, with retry and dead-letter handling.
+- **Scoped auth.** Short-lived, path-scoped Relayfile tokens minted per workspace and per agent.
+
+## Local OSS vs Hosted
+
+Use local OSS for development, tests, or fully self-hosted deployments. Use Hosted Agent Relay when you want provider-backed files to work without operating the stack.
+
+| Need | Local OSS | Hosted Agent Relay |
+|---|---|---|
+| Run the Relayfile API | you run it | managed |
+| Mount files for an agent | yes | yes |
+| Issue scoped tokens | run relayauth or equivalent | managed |
+| Provider OAuth | self-host provider auth | managed |
+| Provider sync / writeback | self-host workers | managed |
+| Nango | self-host for end-to-end OAuth | managed |
+
+For end-to-end self-hosting, run relayfile, relayauth, the relevant [adapters and providers](/docs/file/adapters-and-providers), and Nango. The split is deliberate: Relayfile's OSS surface handles the VFS, scoped tokens, generic ingest, writeback queue, and mount; the polished OAuth connect flow and provider sync definitions are hosted by Cloud or implemented in your self-host provider stack.
+
+<Note>
+  Relayfile itself never stores third-party OAuth credentials. Whether hosted or self-hosted, credentials live in the provider layer (Nango, Composio, Pipedream) — Relayfile receives normalized files, events, writeback operations, and a `connectionId`.
+</Note>
+
+## file.agentrelay.com
+
+`relayfile-cloud` is the standalone Cloudflare service for the hosted Relayfile data plane, currently being extracted from the internal SST monorepo and moved onto the **`file.agentrelay.com`** domain. It's a rebuild in progress: the previous standalone implementation has been archived (not deleted) under the git tag `archive/standalone-impl-pre-migration`, and the source of truth being ported from is the internal cloud monorepo's `packages/relayfile` and `infra/relayfile.ts`. The control plane today resolves through `agentrelay.com/cloud`; the data plane is being consolidated onto its own domain as part of that migration.
+
+<CardGroup cols={2}>
+  <Card title="CLI reference" href="/docs/file/cli">
+    Every flag of `relayfile setup` and the integration commands.
+  </Card>
+  <Card title="Mounting from a sandbox" href="/docs/file/mounting">
+    The SDK equivalent of `relayfile setup` for runtimes.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/comparison.mdx b/web/content/docs/file/comparison.mdx
new file mode 100644
index 00000000..e29171fc
--- /dev/null
+++ b/web/content/docs/file/comparison.mdx
@@ -0,0 +1,53 @@
+---
+title: 'How Relayfile compares'
+description: 'Relayfile next to MCP servers, virtual-filesystem-for-agents projects, and rolling your own — what each is good at and where they compose.'
+---
+
+"Give agents a filesystem" is a healthy direction, and Relayfile isn't the only project pointing at it. Here's an honest read of where it sits relative to the alternatives, and where they compose rather than compete.
+
+## vs MCP servers
+
+MCP gives the agent a typed tool surface per integration — a Linear server, a Notion server, a GitHub server. That's strong for single, well-defined writes: `linear.create_issue(title, priority, …)` enforces the shape at call time and can model provider-specific operations richer than a generic schema-validate-and-write.
+
+The costs show up as you scale out:
+
+| Dimension | Per-provider MCPs | Relayfile |
+|---|---|---|
+| Tool surface as providers grow | O(N) tool schemas in context | O(1) — `ls` / `cat` / write work identically everywhere |
+| Context cost | 100+ schemas loaded before any work | nothing until the agent reads a file |
+| Enumeration | API search results, paginated | exhaustive — `ls` returns what's there |
+| Cross-provider composition | bespoke glue per pair | free: `grep -r`, `cat`, `cp` across providers |
+| Multi-agent coordination | point-to-point, pull-only | shared, ACL'd, real-time filesystem |
+| Event-driven loops | request/response only | webhook → file event → many subscribers |
+
+An LLM is also more reliable reading a directory than juggling N typed APIs. **The two compose well:** Relayfile for reads, synthesis, and the stateful multi-provider substrate; MCP for typed one-shot writes that need server-side validation. A real harness can use both. The honest rule of thumb: **1 provider × 1 agent × one-shot action → use the provider MCP**; **N providers and/or N agents → Relayfile is the substrate** and the gap widens with each one. See [Agents](/docs/file/agents) for the full breakdown.
+
+## vs Mirage and other virtual-FS projects
+
+Mirage and similar virtual-filesystem-for-agents projects are doing thoughtful work in this space. The clearest distinction is the layer they operate at:
+
+- **Mirage is a pull layer.** Agents query data from S3, GDrive, Postgres, Redis, and other infrastructure backends on demand.
+- **Relayfile is an event layer.** Provider webhooks normalize into file events that wake agents, which then read, react, and write back.
+
+They're complementary: use a pull layer when your agents need to query infrastructure data; use Relayfile when your agents need to react to SaaS events. Relayfile also adds file-native writeback (PATCH / CREATE / DELETE through file ops), per-agent [ACLs](/docs/file/acls), [real-time multi-agent sync](/docs/file/realtime-sync), and centralized OAuth, retry, and rate-limit handling across providers — the last of which is an open issue in some of these projects today.
+
+## vs rolling your own
+
+A single agent against a single backend can do fine with FUSE, Mountpoint, or direct SDK calls. You don't need Relayfile for that.
+
+Relayfile becomes worth it when you need:
+
+- **Multi-agent coordination** — agents seeing each other's writes in real time, without a coordination protocol on top.
+- **Scoped capabilities** — least-privilege per agent via ACLs, not a shared all-or-nothing credential.
+- **A consistent read/write contract across many SaaS surfaces** — one interface instead of N bespoke integrations, with centralized auth, retry, dead-letter, and rate-limit handling.
+
+Below those thresholds, rolling your own is reasonable. Above them, you'd be re-implementing the [adapter and provider](/docs/file/adapters-and-providers) layers, the writeback queue, and the sync substrate that Relayfile already ships.
+
+<CardGroup cols={2}>
+  <Card title="Why files" href="/docs/file/why-files">
+    The reactive-invocation, coordination, and context arguments in depth.
+  </Card>
+  <Card title="Adapters and providers" href="/docs/file/adapters-and-providers">
+    The pluggable architecture that makes one provider unlock many apps.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/introduction.mdx b/web/content/docs/file/introduction.mdx
new file mode 100644
index 00000000..ac07b3c5
--- /dev/null
+++ b/web/content/docs/file/introduction.mdx
@@ -0,0 +1,64 @@
+---
+title: 'Relayfile'
+description: 'The event layer for AI agents — normalize SaaS webhooks into a consistent, ACL-scoped file tree your agents read and write with ls, cat, and grep.'
+---
+
+Your SaaS tools are always firing events. A Linear issue is created, a Notion page edited, a GitHub PR opened — and something should react. But every provider fires webhooks differently: different payload shapes, different auth schemes, different retry semantics. Building that normalization for each provider is the plumbing nobody wants to write.
+
+Relayfile normalizes webhooks from Linear, Notion, GitHub, Slack, HubSpot, Salesforce, and the rest of your SaaS stack into a consistent, ACL'd file tree, then delivers them to your agents. Agents wake up to a ready filesystem, read what changed, and write back — using `cat`, `grep`, and file-write operations they already know. One integration point. Zero webhook parsing.
+
+LLMs are far better at reading files than calling typed tools — the filesystem is the most-trained-on API in existence. Relayfile leans on that instead of fighting it.
+
+## The entire interface
+
+There is no new SDK to learn and no MCP schemas eating your context window — just the bash and file IO an agent already knows.
+
+```bash
+$ ls mount/
+github  linear  notion  slack
+
+$ cat mount/linear/issues/AGE-12.json
+{ "identifier": "AGE-12", "title": "Fix login bug", "state": "Todo", ... }
+
+$ echo '{"description":"Updated by reviewer agent"}' \
+    > mount/linear/issues/AGE-12.json   # PATCH back to Linear
+
+$ grep -l '"state":"Todo"' mount/linear/issues/*.json
+```
+
+`ls` lists what's there. `cat` reads a record. Writing a JSON file patches it back to the provider. Removing a file deletes the record. The filesystem is the protocol.
+
+## Why files beat tool schemas
+
+A typical MCP setup loads 100+ tool schemas into every agent session before any work happens. Files load nothing — context cost is exactly what the agent opens. An LLM is also more reliable reading a directory than juggling N typed APIs, and `ls` gives you exhaustive enumeration where a tool call returns paginated search results.
+
+There are three reasons the file interface wins, covered in depth on [Why files](/docs/file/why-files):
+
+- **Reactive invocation.** Provider webhooks normalize into file events. Your agent wakes up to the changed file, not a raw payload it has to parse.
+- **Coordination.** Multiple agents working through the same filesystem see each other's writes immediately, scoped by ACL.
+- **Context efficiency.** Files load nothing into context until an agent reads them.
+
+<Note>
+  Relayfile is the file layer of the Agent Relay platform. Where Agent Relay gives agents a [communication layer](/docs/introduction) — messaging, delivery, and actions — Relayfile gives them the integration layer: every connected SaaS tool exposed as files.
+</Note>
+
+## Where to go next
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" href="/docs/file/quickstart">
+    Get a working mount in minutes — hosted with `relayfile setup`, or local with Docker.
+  </Card>
+  <Card title="Mount layout" href="/docs/file/mount-layout">
+    Self-describing mounts: `LAYOUT.md`, `_index.json`, canonical naming, and the alias views.
+  </Card>
+  <Card title="The SDK" href="/docs/file/sdk">
+    `@relayfile/sdk` — `RelayFileClient` reads and writes, plus `RelayfileSetup` for mounting.
+  </Card>
+  <Card title="Relayfile Cloud" href="/docs/file/cloud">
+    Hosted Agent Relay runs the daemon, OAuth, and sync workers — connect with one token.
+  </Card>
+</CardGroup>
+
+<BannerLink href="/docs/file/quickstart" icon="rocket">
+  Mount your first provider-backed workspace.
+</BannerLink>
diff --git a/web/content/docs/file/local-development.mdx b/web/content/docs/file/local-development.mdx
new file mode 100644
index 00000000..812a57d0
--- /dev/null
+++ b/web/content/docs/file/local-development.mdx
@@ -0,0 +1,84 @@
+---
+title: 'Local development'
+description: 'Run Relayfile without Docker: start relayauth, run the server with the durable-local backend, generate a dev token, and use the CLI.'
+---
+
+When you're working on Relayfile itself or want a no-container loop, you can run the pieces directly from source. This path uses the durable-local backend so state survives restarts, a local token issuer, and the `relayfile-cli` binary for login, seed, tree, and mount.
+
+## Start the token issuer
+
+`relayauth` is the local dev JWT issuer. Start it first:
+
+```bash
+node docker/relayauth/server.js
+```
+
+## Run the server
+
+In another terminal, start the file server with the durable-local backend profile so workspace state persists between runs, pointed at the local issuer's JWKS:
+
+```bash
+RELAYFILE_BACKEND_PROFILE=durable-local \
+RELAYFILE_DATA_DIR=.data \
+RELAYAUTH_JWKS_URL=http://127.0.0.1:9091/.well-known/jwks.json \
+go run ./cmd/relayfile
+```
+
+`RELAYFILE_BACKEND_PROFILE=durable-local` selects a durable on-disk profile (other values include `memory` for ephemeral test runs and `production`/`prod` for a Postgres-backed deployment). `RELAYFILE_DATA_DIR` is where the durable profile writes state; it defaults to `.relayfile`.
+
+## Generate a dev token and use the CLI
+
+In a third terminal, generate a workspace-scoped dev token and drive the CLI:
+
+```bash
+export RELAYFILE_WORKSPACE=ws_demo
+export RELAYFILE_TOKEN="$(./scripts/generate-dev-token.sh "$RELAYFILE_WORKSPACE")"
+
+go run ./cmd/relayfile-cli login \
+  --server http://127.0.0.1:8080 \
+  --token "$RELAYFILE_TOKEN"
+
+go run ./cmd/relayfile-cli seed "$RELAYFILE_WORKSPACE" ./examples
+go run ./cmd/relayfile-cli tree "$RELAYFILE_WORKSPACE" /
+go run ./cmd/relayfile-cli mount "$RELAYFILE_WORKSPACE" ./relayfile-mount --once
+```
+
+`generate-dev-token.sh` emits a JWT with `workspace_id`, `agent_name`, and `aud: ["relayfile"]`, signed with the dev secret (`RELAYFILE_JWT_SECRET`, default `dev-secret`).
+
+<Note>
+  The default server address is `:8080`, so the CLI's `--server http://127.0.0.1:8080` matches the server you started above. This differs from the Docker stack, which publishes relayfile on port 9090.
+</Note>
+
+## Common local commands
+
+```bash
+# read remote tree and files without mounting
+go run ./cmd/relayfile-cli tree ws_demo /
+go run ./cmd/relayfile-cli read ws_demo /docs/welcome.md
+
+# one-shot sync for CI
+go run ./cmd/relayfile-cli mount ws_demo ./relayfile-mount --once
+
+# export a workspace
+go run ./cmd/relayfile-cli export ws_demo --format tar --output ws_demo.tar
+```
+
+`mount --once` runs a single sync cycle and exits, which is the right shape for CI and tests. Drop `--once` for a long-running mirror. See the [CLI reference](/docs/file/cli) for the full command and flag set.
+
+## Where state lives
+
+The CLI keeps local config under `~/.relayfile/`:
+
+- `credentials.json` — self-hosted/API-key credentials only, mode `0600`.
+- `workspaces.json` — local workspace metadata (names, IDs, default).
+
+The mount directory keeps sync state under `<local-dir>/.relay/` (`state.json`, conflicts, dead-letter, denial log). For the full set of environment variables the server, mount, and CLI read, this all maps to the source-backed env reference in the Relayfile repo.
+
+<CardGroup cols={2}>
+  <Card title="Run locally" href="/docs/file/run-locally">
+    The Docker path and `relayfile-mount` daemon flags.
+  </Card>
+  <Card title="CLI reference" href="/docs/file/cli">
+    Every `relayfile` subcommand and global flag.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/mount-layout.mdx b/web/content/docs/file/mount-layout.mdx
new file mode 100644
index 00000000..6264e713
--- /dev/null
+++ b/web/content/docs/file/mount-layout.mdx
@@ -0,0 +1,85 @@
+---
+title: 'Mount layout'
+description: 'Every Relayfile mount is self-describing: LAYOUT.md, per-integration layout files, _index.json, canonical naming, and four alias views.'
+---
+
+Every mount is self-describing. The agent never needs to learn paths from external documentation — `cat mount/LAYOUT.md` lists everything, and per-integration `.layout.md` files document the tree shape for each provider. This is deliberate: an agent oriented by reading the tree itself doesn't carry path knowledge in its prompt or schema.
+
+## The tree
+
+```
+mount/
+├── LAYOUT.md                              # virtual, read-only — top-level guide
+├── _index.json                            # root listing
+├── linear/
+│   ├── .layout.md                         # linear-specific tree shape
+│   ├── issues/
+│   │   ├── _index.json
+│   │   ├── AGE-12__fix-login-bug.json     # canonical: <slug>__<id>
+│   │   ├── by-title/AGE-12-fix-login-bug.json
+│   │   ├── by-id/AGE-12.json
+│   │   └── by-state/in-progress/AGE-12__fix-login-bug.json
+│   └── users/by-name/dana.json
+└── github/
+    └── repos/
+        ├── _index.json
+        ├── acme/api/
+        │   └── pulls/42__bump-deps/meta.json
+        └── by-name/acme__api.json
+```
+
+## Self-describing files
+
+Three kinds of metadata files make the tree navigable without prior knowledge:
+
+- **`LAYOUT.md`** at the root is a virtual, read-only guide to the top-level structure. It's the first thing an agent should `cat` after mounting.
+- **`<integration>/.layout.md`** documents the tree shape for a single provider — what directories exist under `linear/`, what each holds.
+- **`_index.json`** in every directory lists the rows that directory contains, so an agent can read one file to understand a directory rather than walking every entry.
+
+## Canonical naming
+
+Entity files follow a `<sanitized-name>__<id>` convention so identifiers are recoverable from any filename. The ID is always the **last** `__`-separated segment:
+
+```text
+inbox/threads/Re_Welcome__01HXYZ.json
+inbox/threads/01HXYZ.json
+```
+
+The first path is the canonical human-readable form. The second is a legacy fallback that remains readable during the naming transition — consumers should accept both the new-style filename and the bare `<id>` basename while producers are updated.
+
+<Note>
+  Because the ID is recoverable from the filename, an agent can read `AGE-12__fix-login-bug.json`, derive the identifier `AGE-12`, and write back to the canonical path without a separate lookup.
+</Note>
+
+## The four alias views
+
+Each resource type ships four alias views out of the box, so an agent can navigate the same records by whichever key it has in hand:
+
+- **`by-title/`** — slug lookups (`AGE-12-fix-login-bug.json`).
+- **`by-id/`** — identifier lookups (`AGE-12.json`).
+- **`by-name/`** — human-readable name lookups (`dana.json`, `acme__api.json`).
+- **`by-state/`** — grouped by issue or PR state (`by-state/in-progress/...`).
+
+These are views over the same canonical entities, not copies you have to keep in sync. An agent that knows only a state can `ls by-state/in-progress/`; one that knows only a name can read `by-name/dana.json`.
+
+## Lazy repo materialization
+
+For huge-org workspaces, GitHub repo subtrees can be materialized lazily rather than exported up front. Opt in with `--lazy-repos`:
+
+```bash
+RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
+  --workspace ws_demo \
+  --local-dir ./relayfile-mount \
+  --lazy-repos
+```
+
+This avoids pulling every repo tree on mount; subtrees populate on demand as they're accessed. Combine it with `--remote-path` (see [Run locally](/docs/file/run-locally)) to scope the mount to specific subtrees from the start.
+
+<CardGroup cols={2}>
+  <Card title="Reads and writes" href="/docs/file/reads-and-writes">
+    How ls/cat/grep map to reads and how writing canonical paths maps to writeback.
+  </Card>
+  <Card title="ACLs" href="/docs/file/acls">
+    Scope which parts of this tree each agent can see and write.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/mounting.mdx b/web/content/docs/file/mounting.mdx
new file mode 100644
index 00000000..192e15f9
--- /dev/null
+++ b/web/content/docs/file/mounting.mdx
@@ -0,0 +1,113 @@
+---
+title: 'Mounting from a sandbox'
+description: 'Attach an authorized Relayfile workspace as local files from inside a sandbox with mountWorkspace and ensureMountedWorkspace.'
+---
+
+Once a user has signed in and connected their providers in Agent Relay Cloud, a sandbox — Daytona, E2B, an ephemeral container, or your own runtime — can attach the workspace as local files in a single SDK call. This is the programmatic sibling of the [`relayfile setup` CLI](/docs/file/cli): same outcome, different entry point. Use the CLI for human-driven setup; use the SDK from inside an already-authorized sandbox or agent runtime.
+
+## `mountWorkspace`
+
+`RelayfileSetup.mountWorkspace` mounts a workspace you already know is ready. It mints a fresh mount-session token, launches and supervises the `relayfile-mount` process, and resolves once the mount is reachable.
+
+```ts
+import { RelayfileSetup } from "@relayfile/sdk"
+
+const setup = new RelayfileSetup({ accessToken })
+
+const handle = await setup.mountWorkspace({
+  workspaceId: "rw_…",
+  localDir: "/workspace",
+})
+
+// /workspace is now a live mount of the workspace
+console.log(handle.expiresAt)
+await handle.stop()
+```
+
+You can pass either a `workspaceId` (the SDK joins internally) or a `WorkspaceHandle` you already hold. `remotePath` (default `/`) scopes the mount to a subtree, and `mode` defaults to `poll`.
+
+## `ensureMountedWorkspace`
+
+Use `ensureMountedWorkspace` when you also want provider-readiness gating in the same call. It checks the provider before issuing any mount-session request, so no token is minted if the provider isn't ready.
+
+```ts
+const handle = await setup.ensureMountedWorkspace({
+  workspaceId: "rw_…",
+  provider: "notion",
+  verifyProvider: true,
+  localDir: "/workspace",
+})
+```
+
+This is the standard entry point for sandbox integrators — it removes the race where an agent mounts before the provider has finished its first sync.
+
+## Provider readiness errors
+
+`ensureMountedWorkspace` surfaces two typed errors so callers can give meaningful diagnostics without an extra round-trip:
+
+- **`ProviderNotConnectedError`** — thrown when the provider isn't connected to the workspace at all. Carries `.provider`.
+- **`ProviderNotReadyError`** — thrown when the connection exists but isn't ready within `providerReadyTimeoutMs`. Carries `{ provider, state, initialSyncState }`.
+
+```ts
+import { ProviderNotConnectedError, ProviderNotReadyError } from "@relayfile/sdk"
+
+try {
+  const handle = await setup.ensureMountedWorkspace({
+    workspaceId: "rw_…",
+    provider: "notion",
+    verifyProvider: true,
+    providerReadyTimeoutMs: 30_000,
+    localDir: "/workspace",
+  })
+} catch (err) {
+  if (err instanceof ProviderNotConnectedError) {
+    console.error(`Provider ${err.provider} is not connected to this workspace.`)
+  } else if (err instanceof ProviderNotReadyError) {
+    console.error(`Provider ${err.provider} connected but not ready. State: ${err.state}`)
+  }
+  throw err
+}
+```
+
+Pass `verifyProvider: false` to skip the probe entirely (equivalent to calling `mountWorkspace`).
+
+## The mounted handle
+
+Both methods resolve to a `MountedWorkspaceHandle`. The SDK supervises the local `relayfile-mount` process for you and only resolves once the mount is reachable. The handle exposes:
+
+- **`ready`** — `true` once the first sync completes.
+- **`expiresAt`** — ISO timestamp from the token mint.
+- **`suggestedRefreshAt`** — when to refresh before expiry.
+- **`env()`** — the environment block for child processes (`RELAYFILE_BASE_URL`, `RELAYFILE_TOKEN`, `RELAYFILE_WORKSPACE`, `RELAYFILE_LOCAL_DIR`, and the Relaycast keys). Spread it into a sandbox process's env.
+- **`status()`** — a fresh readiness snapshot; reads `${localDir}/.relay/state.json` and falls back to an HTTP probe.
+- **`stop()`** — idempotent shutdown that drains in-flight syncs and never deletes the local directory.
+
+```ts
+const env = handle.env()
+await sandbox.process.executeCommand("ls /workspace", { env })
+await handle.stop()
+```
+
+<Note>
+  The sandbox receives only a workspace-scoped Relayfile JWT, the server URL, and a Relaycast key — never the user's Cloud access token or PII. The minted token's scopes are a subset of the caller's grant, so passing `scopes: ["fs:read"]` yields a read-only mount even if the caller can write. Pair this with [ACLs](/docs/file/acls) for least-privilege fleets.
+</Note>
+
+## Contrast with the CLI
+
+`relayfile setup` and `mountWorkspace`/`ensureMountedWorkspace` reach the same end state — a workspace mounted at a local directory:
+
+| | `relayfile setup` (CLI) | `mountWorkspace` / `ensureMountedWorkspace` (SDK) |
+|---|---|---|
+| Entry point | human or agent at a shell | code inside an authorized sandbox |
+| Login | runs the cloud login flow | uses an access token you already hold |
+| Provider connect | opens the OAuth flow | assumes connected; `ensure*` gates on readiness |
+| Process management | starts the mount loop in the foreground | SDK launches and supervises the process |
+
+<CardGroup cols={2}>
+  <Card title="The SDK" href="/docs/file/sdk">
+    `RelayFileClient` reads and writes once you're mounted.
+  </Card>
+  <Card title="CLI reference" href="/docs/file/cli">
+    The `relayfile setup` human-driven path.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/quickstart.mdx b/web/content/docs/file/quickstart.mdx
new file mode 100644
index 00000000..b0feb4fa
--- /dev/null
+++ b/web/content/docs/file/quickstart.mdx
@@ -0,0 +1,111 @@
+---
+title: 'Quickstart'
+description: 'The fastest path to a working Relayfile mount — hosted with one command, or local with Docker — then read and write provider files.'
+---
+
+There are two ways to get a working mount. The **hosted** path runs the integration stack for you — OAuth, sync workers, writeback — so you only run a local mount. The **local OSS** path runs the file server yourself with Docker. Pick whichever fits; both end with provider-backed files in an ordinary directory.
+
+## Hosted: one command
+
+If you want Notion, Slack, Linear, GitHub, or other provider-backed files without running infrastructure, use Hosted Agent Relay. The CLI logs you in, creates or joins a cloud workspace, completes provider auth, waits for sync, and mounts the result.
+
+```bash
+relayfile setup \
+  --provider notion \
+  --workspace my-agent \
+  --local-dir ./relayfile-mount \
+  --no-open
+```
+
+`--no-open` prints the hosted login and connect URLs instead of opening a browser — useful inside agents and headless environments. The command connects to `agentrelay.com`, completes the Nango connect flow, blocks until the provider reports ready, and starts the mount sync loop.
+
+When it returns, `./relayfile-mount` is a live mirror of your workspace:
+
+```bash
+ls ./relayfile-mount/notion
+cat ./relayfile-mount/LAYOUT.md
+```
+
+See [Relayfile Cloud](/docs/file/cloud) for what the hosted plane manages, and [Mounting](/docs/file/mounting) to do the same thing programmatically from a sandbox.
+
+## Local: Docker stack
+
+The local path runs the file server, the dev token issuer, and a seed step that creates a sample `ws_demo` workspace.
+
+```bash
+cd docker
+docker compose up --build
+```
+
+This starts three services:
+
+| Service | URL | Purpose |
+|---|---|---|
+| relayfile | `http://localhost:9090` | VFS API |
+| relayauth | `http://localhost:9091` | local dev token issuer |
+| seed | exits after setup | creates `ws_demo` sample files |
+
+### Get a token and call the API
+
+The seed step prints a dev token to its logs. Grab it, then hit the tree and file endpoints:
+
+```bash
+TOKEN="$(docker compose logs seed | awk '/token/ {print $NF}' | tail -1)"
+
+curl -H "Authorization: Bearer $TOKEN" \
+  -H "X-Correlation-Id: quickstart-tree" \
+  "http://localhost:9090/v1/workspaces/ws_demo/fs/tree?path=/"
+
+curl -H "Authorization: Bearer $TOKEN" \
+  -H "X-Correlation-Id: quickstart-read" \
+  "http://localhost:9090/v1/workspaces/ws_demo/fs/file?path=/docs/welcome.md"
+```
+
+`X-Correlation-Id` is required on authenticated requests for traceability. The full endpoint surface is in the [API reference](/docs/file/api-reference).
+
+### Mount it as local files
+
+```bash
+cd ..
+RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
+  --base-url http://localhost:9090 \
+  --workspace ws_demo \
+  --local-dir ./relayfile-mount
+```
+
+Now any local tool or agent can use `./relayfile-mount` like a normal directory. See [Run locally](/docs/file/run-locally) for the full daemon flag set, including `--remote-path` to mirror a subtree and `--fuse-content-ttl` to tune the content cache.
+
+## Read and write
+
+Once mounted, the interface is the filesystem you already know:
+
+```bash
+# read
+cat ./relayfile-mount/linear/issues/AGE-12__fix-login-bug.json
+
+# patch back to the provider by writing the canonical path
+echo '{"state":"In Review"}' \
+  > ./relayfile-mount/linear/issues/AGE-12__fix-login-bug.json
+
+# find across providers
+grep -rl '"state":"Todo"' ./relayfile-mount/linear/issues/
+```
+
+See [Reads and writes](/docs/file/reads-and-writes) for the full PATCH / CREATE / DELETE model.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Mount layout" href="/docs/file/mount-layout">
+    Learn the tree shape: `LAYOUT.md`, `_index.json`, canonical naming, and alias views.
+  </Card>
+  <Card title="Reads and writes" href="/docs/file/reads-and-writes">
+    How file ops map to PATCH, CREATE, and DELETE — and where schemas live.
+  </Card>
+  <Card title="The SDK" href="/docs/file/sdk">
+    Use `RelayFileClient` from any agent runtime, with the built-in read cache.
+  </Card>
+  <Card title="Agents" href="/docs/file/agents">
+    One `connect()` call for Vercel AI SDK, OpenAI Agents SDK, and LangChain.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/reads-and-writes.mdx b/web/content/docs/file/reads-and-writes.mdx
new file mode 100644
index 00000000..147d8ac6
--- /dev/null
+++ b/web/content/docs/file/reads-and-writes.mdx
@@ -0,0 +1,89 @@
+---
+title: 'Reads and writes'
+description: 'File-native reads with ls/cat/grep/find and writes that map to PATCH, CREATE, and DELETE — with per-resource schemas discoverable in-tree.'
+---
+
+Relayfile maps the agent's native filesystem vocabulary directly onto provider operations. Reads are ordinary file reads; writes are ordinary file writes that queue a provider writeback. There are no tool schemas in context — the agent uses `ls`, `cat`, `grep`, `find`, and file writes exactly as it would on a local disk.
+
+## File-native reads
+
+Every read operation is something an agent already knows how to do:
+
+```bash
+# enumerate
+ls mount/linear/issues/
+
+# read one record
+cat mount/linear/issues/AGE-12__fix-login-bug.json
+
+# search across records — exhaustive, no API pagination
+grep -rl '"state":"Todo"' mount/linear/issues/
+
+# find by name
+find mount/linear/users/by-name -name 'dana.json'
+```
+
+This is the whole read interface. `ls` returns what's there (exhaustive enumeration, not a paginated search result), `cat` reads a record, and `grep`/`find` work because everything is a real file. There are no schemas to load before any of this works — context cost is exactly what the agent opens.
+
+When using the SDK or HTTP API directly, the equivalents are `listTree` and `readFile`; see [The SDK](/docs/file/sdk) and the [API reference](/docs/file/api-reference).
+
+## File-native writes
+
+Writes follow three intuitive rules:
+
+- **PATCH** a record by writing to its canonical path. The new content is queued as a writeback to the provider.
+- **CREATE** by saving a draft filename. Writing a new file under the right directory creates the corresponding provider record.
+- **DELETE** by removing the file. Deleting the file queues a delete on the provider.
+
+```bash
+# PATCH: update an existing Linear issue
+echo '{"state":"In Review","description":"PR #42"}' \
+  > mount/linear/issues/AGE-12__fix-login-bug.json
+
+# CREATE: save a draft to create a new record
+echo '{"title":"Investigate flaky test","priority":2}' \
+  > mount/linear/issues/draft-flaky-test.json
+
+# DELETE: remove the file to delete the record
+rm mount/linear/labels/stale.json
+```
+
+Writes are durable: they're recorded in Relayfile's writeback queue and processed by provider workers with retry and dead-letter handling, so an agent doesn't race the provider's rate limits directly.
+
+<Note>
+  Through the SDK, `writeFile` takes a `baseRevision` for optimistic concurrency (`baseRevision: "*"` means create-or-overwrite). When two agents write the same path, a conflicting write surfaces a `RevisionConflictError` instead of silently clobbering. Bulk writes are unconditional create-or-overwrite. See [The SDK](/docs/file/sdk).
+</Note>
+
+## Discovering schemas in-tree
+
+You don't need an out-of-band schema registry. Per-resource schemas are discoverable in the tree itself at `<resource>/.schema.json`:
+
+```bash
+cat mount/linear/issues/.schema.json
+```
+
+An agent that wants to create or patch a record reads the adjacent schema file to learn the expected shape, then writes a conforming JSON file. This keeps the contract co-located with the data — the same self-describing principle as [`LAYOUT.md` and `.layout.md`](/docs/file/mount-layout).
+
+The exact write semantics and field mapping per provider are defined by the [adapters](/docs/file/adapters-and-providers), which own webhook-to-path mapping and writeback behavior.
+
+## Reads and writes across providers
+
+Because every provider is just paths, cross-provider workflows need no special glue:
+
+```bash
+# read a Notion page, then file a Linear follow-up
+cat mount/notion/pages/roadmap__abc.json
+echo '{"title":"Follow up on roadmap","priority":3}' \
+  > mount/linear/issues/draft-roadmap-followup.json
+```
+
+Scope which providers and paths a given agent can read versus write with [ACLs](/docs/file/acls) — for example, read Notion and write Linear follow-ups, nothing else.
+
+<CardGroup cols={2}>
+  <Card title="ACLs" href="/docs/file/acls">
+    Restrict each agent's read and write surface.
+  </Card>
+  <Card title="Adapters and providers" href="/docs/file/adapters-and-providers">
+    Where webhook-to-path mapping and writeback behavior are defined.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/realtime-sync.mdx b/web/content/docs/file/realtime-sync.mdx
new file mode 100644
index 00000000..77432d48
--- /dev/null
+++ b/web/content/docs/file/realtime-sync.mdx
@@ -0,0 +1,68 @@
+---
+title: 'Real-time multi-agent sync'
+description: 'Write-through invalidation makes a Relayfile workspace a real coordination substrate: one agent writes, others see it on the next read.'
+---
+
+Most "filesystem for agents" projects assume one agent at a time. Relayfile assumes many. When agent A writes a file, agent B sees the new contents on the next read — within a second, no commit, no push, no merge. That's not polish; it's the difference between agents that *use* a filesystem and agents that *coordinate through* one.
+
+## The reviewer / implementer loop
+
+The clearest demonstration is two agents watching the same record:
+
+```bash
+# terminal 1: reviewer agent watching the ticket
+$ tail -F mount/linear/issues/AGE-12.json
+{ "title": "Fix login bug", "state": "Todo", ... }
+
+# terminal 2: implementer agent (writes after pushing the fix)
+$ echo '{"state":"In Review","description":"PR #42"}' \
+    > mount/linear/issues/AGE-12.json
+
+# terminal 1, ~half a second later — same file, new contents
+$ tail -F mount/linear/issues/AGE-12.json
+{ "title": "Fix login bug", "state": "In Review", ..., "description": "PR #42" }
+```
+
+The reviewer didn't poll an API or subscribe to a custom event bus. It tailed a file. A persona-orchestrator agent can watch all its workers' progress the same way — by reading the files they write. None of that requires a coordination protocol on top of Relayfile. **The filesystem is the protocol.**
+
+## Write-through invalidation
+
+Without write-through invalidation, this falls apart. Two agents on the same data either hit stale-read bugs (B reads a cached version after A wrote) or step on each other (last-write-wins, no notification). Some virtual-filesystem-for-agents projects have this as an open issue today; Relayfile shipped it.
+
+The mechanism: a write doesn't just persist, it invalidates. When a change stream delivers a mutation event for a path, any cached copy of that path is evicted, so the next read fetches fresh content. This is what turns multi-agent collaboration into a property of the substrate instead of something every app has to reinvent.
+
+## The client-side read cache
+
+The TypeScript SDK ships a client-side read cache (enabled by default, `v0.10.1+`) that makes this efficient without sacrificing freshness. `RelayFileClient.readFile` caches responses with:
+
+- **A short TTL** — 5 seconds by default, 500 entries by default.
+- **In-flight deduplication** — concurrent reads for the same path resolve from a single in-flight request.
+- **LRU eviction** — the cache stays bounded.
+- **Automatic write-through invalidation** — the cache auto-evicts when a change stream delivers a mutation event, and immediately on `writeFile` / `bulkWrite` / `deleteFile` from the same client.
+
+```ts
+// custom TTL for fast-changing workspaces (default: 5000ms, 500 entries)
+const files = new RelayFileClient({ token, readCache: { ttlMs: 2000 } })
+
+// disable caching entirely
+const files = new RelayFileClient({ token, readCache: false })
+```
+
+The default settings are deliberately conservative: a 5-second TTL plus event-driven invalidation means a reader almost never serves data older than the most recent write it could have heard about. Tune `ttlMs` down for workspaces with very fast churn, or disable the cache when you need every read to hit the server.
+
+<Note>
+  The FUSE/poll mount layer has its own kernel content and attribute caches, tuned separately with `--fuse-content-ttl`. The SDK read cache and the mount caches are independent — see [Run locally](/docs/file/run-locally).
+</Note>
+
+## The protocol is the filesystem
+
+Putting it together: provider webhooks become file events, file writes invalidate caches, and any agent can subscribe to a path. A new Linear issue mutates `/linear/issues/X.json`, which raises a change event, which wakes every subscribed agent — one comments, one pings Slack, one opens a PR. See [Why files](/docs/file/why-files) for the reactive-invocation argument and [Agents](/docs/file/agents) for the `onEvent` webhook helper that turns these events into agent invocations.
+
+<CardGroup cols={2}>
+  <Card title="The SDK" href="/docs/file/sdk">
+    Configure the read cache and subscribe to change streams.
+  </Card>
+  <Card title="ACLs" href="/docs/file/acls">
+    Coordinate many agents safely with per-agent path scopes.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/run-locally.mdx b/web/content/docs/file/run-locally.mdx
new file mode 100644
index 00000000..0860adaf
--- /dev/null
+++ b/web/content/docs/file/run-locally.mdx
@@ -0,0 +1,97 @@
+---
+title: 'Run locally'
+description: 'Run the Relayfile daemon with Docker, hit the VFS over curl, and mount a workspace with relayfile-mount and its FUSE cache flags.'
+---
+
+Relayfile runs as a lightweight background daemon. That's where OAuth tokens stay warm, provider rate limits are absorbed, webhook deliveries are deduplicated, and events fan out to all subscribed agents. It's an integration runtime — the same reason you run a database process rather than re-implementing storage per request. If you'd rather not run it, [Relayfile Cloud](/docs/file/cloud) runs the daemon for you.
+
+## Start the Docker stack
+
+The fastest local path brings up the file server, the dev token issuer, and a seed step that creates a sample workspace:
+
+```bash
+cd docker
+docker compose up --build
+```
+
+This starts three services:
+
+| Service | URL | Purpose |
+|---|---|---|
+| relayfile | `http://localhost:9090` | VFS API |
+| relayauth | `http://localhost:9091` | local dev token issuer |
+| seed | exits after setup | creates `ws_demo` sample files |
+
+## Call the API over curl
+
+The seed step prints a dev token to its logs. Pull it out, then read the tree and a file:
+
+```bash
+TOKEN="$(docker compose logs seed | awk '/token/ {print $NF}' | tail -1)"
+
+curl -H "Authorization: Bearer $TOKEN" \
+  -H "X-Correlation-Id: quickstart-tree" \
+  "http://localhost:9090/v1/workspaces/ws_demo/fs/tree?path=/"
+
+curl -H "Authorization: Bearer $TOKEN" \
+  -H "X-Correlation-Id: quickstart-read" \
+  "http://localhost:9090/v1/workspaces/ws_demo/fs/file?path=/docs/welcome.md"
+```
+
+`X-Correlation-Id` is required on authenticated requests. The full endpoint set is in the [API reference](/docs/file/api-reference).
+
+## Mount the workspace
+
+Mount `ws_demo` as ordinary local files with the `relayfile-mount` daemon:
+
+```bash
+cd ..
+RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
+  --base-url http://localhost:9090 \
+  --workspace ws_demo \
+  --local-dir ./relayfile-mount
+```
+
+Now any local tool or agent can use `./relayfile-mount` like a normal directory.
+
+## Scope the mount to subtrees
+
+On large workspaces you don't want to pull the whole tree. Limit the daemon to one or more remote subtrees by repeating `--remote-path`. Each subtree is mirrored under the matching path inside `--local-dir`, which avoids full-workspace export pulls:
+
+```bash
+RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
+  --base-url http://localhost:9090 \
+  --workspace ws_demo \
+  --local-dir ./relayfile-mount \
+  --remote-path /github \
+  --remote-path /slack/channels/proj-cloud
+```
+
+For long path lists, pass `--paths-file ./paths.json`. The file may be a JSON array of remote roots or a newline-separated list. Combine with `--lazy-repos` (see [Mount layout](/docs/file/mount-layout)) for huge-org GitHub workspaces.
+
+## Tune the FUSE caches
+
+The FUSE layer caches file content in kernel memory independently of its attribute TTL. By default content is held for 30 seconds and attributes for 2 seconds. Tune content caching with `--fuse-content-ttl` (or the `RELAYFILE_MOUNT_FUSE_CONTENT_TTL` env var) when your workload needs fresher reads or can tolerate a longer cache window:
+
+```bash
+# 10-second content cache — reduces kernel re-reads for stable workspaces
+RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
+  --workspace ws_demo \
+  --local-dir ./relayfile-mount \
+  --fuse-content-ttl 10s
+```
+
+<Note>
+  The mount daemon reads its config from the environment: `RELAYFILE_BASE_URL` (default `http://127.0.0.1:8080`), `RELAYFILE_TOKEN`, `RELAYFILE_WORKSPACE`, `RELAYFILE_REMOTE_PATH`, `RELAYFILE_LOCAL_DIR`, `RELAYFILE_MOUNT_INTERVAL` (default `2s`), and `RELAYFILE_MOUNT_TIMEOUT` (default `15s`). The flags above override the corresponding variables.
+</Note>
+
+This kernel content cache is independent of the SDK's [client-side read cache](/docs/file/realtime-sync) — they operate at different layers and are tuned separately.
+
+<CardGroup cols={2}>
+  <Card title="Local development" href="/docs/file/local-development">
+    Run the daemon without Docker, with the durable-local backend profile.
+  </Card>
+  <Card title="API reference" href="/docs/file/api-reference">
+    The full HTTP surface the daemon talks to.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/sdk.mdx b/web/content/docs/file/sdk.mdx
new file mode 100644
index 00000000..23a75fc1
--- /dev/null
+++ b/web/content/docs/file/sdk.mdx
@@ -0,0 +1,135 @@
+---
+title: 'The SDK'
+description: 'Use @relayfile/sdk: RelayFileClient for reads, writes, and bulk operations with a built-in read cache, plus RelayfileSetup for joining and mounting.'
+---
+
+`@relayfile/sdk` is the TypeScript surface for talking to a Relayfile workspace. It has two halves: `RelayFileClient` for file operations against the data plane, and `RelayfileSetup` for the control-plane flow of logging in, joining a workspace, and mounting it. You can wrap a `RelayFileClient` call in any agent runtime — a Vercel AI SDK tool, a Claude SDK MCP tool, an OpenAI Agents SDK tool, or your own callback.
+
+```bash
+npm install @relayfile/sdk
+```
+
+## RelayFileClient
+
+Construct a client with a token (a string or a function that returns one, for auto-refresh):
+
+```ts
+import { RelayFileClient } from "@relayfile/sdk"
+
+const files = new RelayFileClient({ token: process.env.RELAYFILE_TOKEN! })
+
+// Use this as the body of any agent tool / runtime callback.
+export async function readRelayfile(path: string) {
+  return files.readFile("rw_123", path)
+}
+```
+
+### Reads
+
+```ts
+// list a subtree
+const tree = await files.listTree("rw_123", { path: "/notion", depth: 2 })
+
+// read one file (positional or options-object form both work)
+const page = await files.readFile("rw_123", "/notion/pages/roadmap__abc.json")
+```
+
+### Writes
+
+`writeFile` requires a `baseRevision` for optimistic concurrency — `If-Match` semantics. Use `baseRevision: "*"` for create-or-overwrite, or pass the last revision you read to detect conflicts:
+
+```ts
+await files.writeFile({
+  workspaceId: "rw_123",
+  path: "/linear/issues/AGE-12__fix-login-bug.json",
+  baseRevision: "*",
+  content: JSON.stringify({ state: "In Review" }),
+  contentType: "application/json",
+})
+```
+
+When a conflicting write loses the optimistic-concurrency check, the client throws `RevisionConflictError` instead of silently clobbering — catch it to re-read and retry.
+
+`bulkWrite` writes many files in one request. Bulk writes are unconditional create-or-overwrite (no per-file `baseRevision`):
+
+```ts
+await files.bulkWrite({
+  workspaceId: "rw_123",
+  files: [
+    { path: "/linear/labels/p0.json", content: "{...}", contentType: "application/json" },
+    { path: "/linear/labels/p1.json", content: "{...}", contentType: "application/json" },
+  ],
+})
+```
+
+`deleteFile` removes a file (and queues the provider delete), also taking a `baseRevision`:
+
+```ts
+await files.deleteFile({
+  workspaceId: "rw_123",
+  path: "/linear/labels/stale.json",
+  baseRevision: "*",
+})
+```
+
+For real-time work, `subscribe(globs, onChange)` and `connectWebSocket(workspaceId)` deliver change events; see [Real-time sync](/docs/file/realtime-sync).
+
+## The read cache
+
+`RelayFileClient` caches `readFile` responses by default (`v0.10.1+`): a 5-second TTL, 500-entry LRU, in-flight deduplication of concurrent reads for the same path, and automatic write-through invalidation on remote mutation events and on local `writeFile` / `bulkWrite` / `deleteFile`. Tune or disable it with the `readCache` option:
+
+```ts
+// custom TTL for fast-changing workspaces
+const files = new RelayFileClient({ token, readCache: { ttlMs: 2000 } })
+
+// disable caching entirely
+const files = new RelayFileClient({ token, readCache: false })
+```
+
+The defaults are conservative — short TTL plus event eviction — so readers rarely serve stale data. See [Real-time sync](/docs/file/realtime-sync) for how invalidation ties into multi-agent coordination.
+
+## RelayfileSetup
+
+`RelayfileSetup` drives the control plane: it mints a short-lived data-plane token from your Cloud credentials, joins a workspace, and hands you a `RelayFileClient` bound to it.
+
+```ts
+import { RelayfileSetup } from "@relayfile/sdk"
+
+// fromCloudTokens auto-refreshes within the refresh window
+const setup = RelayfileSetup.fromCloudTokens(
+  { accessToken, refreshToken, accessTokenExpiresAt },
+  { cloudApiUrl: "https://agentrelay.com/cloud" },
+)
+
+const workspace = await setup.joinWorkspace("rw_…")
+const client = workspace.client() // bound, auto-refreshing token
+
+const tree = await client.listTree(workspace.workspaceId, { path: "/notion", depth: 2 })
+```
+
+<Warning>
+  Always use the workspace ID returned by `joinWorkspace` / mount-session (the `rw_…` shard id) for every data-plane call — never the request-side app UUID. The SDK resolves this for you; raw-HTTP callers must resolve it first.
+</Warning>
+
+`RelayfileSetup` also handles mounting (`mountWorkspace`, `ensureMountedWorkspace` — see [Mounting from a sandbox](/docs/file/mounting)), connecting integrations (`connectIntegration`, `connectNotion`, `waitForConnection`), and minting per-agent scoped tokens. For least-privilege, mint a downscoped JWT with `agentInviteScoped({ scopes: ["relayfile:fs:read:/notion/**"] })` rather than the broad sync `agentInvite()`.
+
+<Note>
+  Request the path-scoped form (`relayfile:fs:read:/notion/**`) when scoping tokens. A bare `fs:read` / `fs:write` request can fall back to a broad grant. See [ACLs](/docs/file/acls).
+</Note>
+
+## Where to go next
+
+<CardGroup cols={2}>
+  <Card title="Agents" href="/docs/file/agents">
+    `@relayfile/agents` wraps this client into one-call framework tools.
+  </Card>
+  <Card title="Mounting from a sandbox" href="/docs/file/mounting">
+    `RelayfileSetup` mount methods for sandboxes and runtimes.
+  </Card>
+  <Card title="API reference" href="/docs/file/api-reference">
+    The HTTP surface the client calls.
+  </Card>
+  <Card title="Reads and writes" href="/docs/file/reads-and-writes">
+    How write operations map to provider PATCH / CREATE / DELETE.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/why-files.mdx b/web/content/docs/file/why-files.mdx
new file mode 100644
index 00000000..9d43bef9
--- /dev/null
+++ b/web/content/docs/file/why-files.mdx
@@ -0,0 +1,53 @@
+---
+title: 'Why files'
+description: 'The case for a file interface over typed tool schemas: reactive invocation, multi-agent coordination, and context efficiency.'
+---
+
+The "give agents a filesystem" idea is a healthy direction, and Relayfile makes a specific bet: the filesystem is the most-trained-on API in existence, and an LLM is more reliable reading a directory than juggling a dozen typed APIs. Three concrete reasons make files the right substrate for SaaS integrations.
+
+## Reactive invocation
+
+Provider webhooks normalize into file events. When a Linear issue is created or a Notion page edited, your agent wakes up to the changed file — no webhook parsing, no provider-specific payload handling, no bespoke adapter per integration. The event is already in a shape the agent can read.
+
+This is the structural difference from request/response tool surfaces. A typed tool can only be called; it has no notion of *being woken up* by external state changing. Relayfile inverts that:
+
+```
+Linear webhook → Cloud sync → /linear/issues/X.json revision++ → change event
+                                                                     ↓
+                                                  agent A reacts, writes a comment
+                                                  agent B reacts, files a Slack ping
+                                                  agent C reacts, opens a PR
+```
+
+The same event fans out to every agent subscribed to that path. This is the substrate that makes **proactive agents** possible — agents reacting to provider state instead of waiting for a user prompt. See [Real-time sync](/docs/file/realtime-sync) for how that fan-out works, and [Agents](/docs/file/agents) for the `onEvent` helper.
+
+## Coordination
+
+Multiple agents working through the same filesystem can see each other's writes immediately, scoped by ACL. Multi-agent collaboration becomes a property of the substrate, not something each app re-implements.
+
+When agent A writes a file, agent B sees the new contents on the next read — within a second, no commit, no push, no merge. A reviewer agent can `tail -F` an issue a worker is updating and watch progress live. A persona-orchestrator can watch its workers' writes without a coordination protocol layered on top.
+
+None of that requires anything beyond the filesystem. **The filesystem is the protocol.** Per-agent surfaces are scoped with [ACLs](/docs/file/acls) so each worker sees only the paths it should.
+
+## Context efficiency
+
+A typical MCP setup loads 100+ tool schemas into every agent session before any work happens. Files load nothing — context cost is what the agent actually opens.
+
+- `ls` returns what's there. Exhaustive enumeration beats query-by-query API retrieval, where a tool call returns paginated search results and the agent has to guess at filters.
+- The tool surface is **O(1)** in the number of providers. `listTree` / `readFile` / write operations work identically across `/linear`, `/notion`, `/github`, and every other integration — there is no per-provider schema for the model to learn.
+- Cross-provider composition is free: `grep -r`, `cp`, and `cat` semantics work across providers because they're all just files.
+
+Contrast that with N typed tool servers, where each connected provider adds another batch of schemas to the context window and cross-provider work needs bespoke glue per pair.
+
+## When a typed tool still wins
+
+Files are not always the answer. For a single provider, a single agent, and a one-shot action that needs server-side validation — `linear.create_issue(title, priority, …)` enforcing the shape at call time — a dedicated MCP is simpler and richer. The two compose well: Relayfile for reads, synthesis, and the stateful multi-provider substrate; an MCP for typed one-shot writes. See [Comparison](/docs/file/comparison) for the full breakdown.
+
+<CardGroup cols={2}>
+  <Card title="Real-time sync" href="/docs/file/realtime-sync">
+    How write-through invalidation makes multi-agent coordination reliable.
+  </Card>
+  <Card title="Comparison" href="/docs/file/comparison">
+    Relayfile vs MCP servers, virtual-FS projects, and rolling your own.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/cli.mdx b/web/content/docs/loop/cli.mdx
new file mode 100644
index 00000000..f4711ce7
--- /dev/null
+++ b/web/content/docs/loop/cli.mdx
@@ -0,0 +1,149 @@
+---
+title: 'CLI Reference'
+description: 'The full ai-hist command surface: sync, search, recent, show, context, session, stats, watch, and the cloud command group, with flags.'
+---
+
+This is the complete `ai-hist` command reference. The CLI is Rust-default — the public `ai-hist` command routes the whole surface through the Rust engine, with the legacy Python CLI available only as an explicit escape hatch (see [Install](/docs/loop/install)). Everything below runs locally against the SQLite database at `~/.local/share/ai-hist/ai-history.db` (override with `AI_HIST_DB`).
+
+## `sync`
+
+Import all history into the local database. Incremental — only reads new bytes on re-run.
+
+```bash
+ai-hist sync
+```
+
+Covers Claude Code, Codex, Cursor, OpenCode, Agent Relay (when configured), and trajectories. See [Sync](/docs/loop/sync) and [Sources](/docs/loop/sources).
+
+## `search`
+
+Full-text search across all sources.
+
+```bash
+ai-hist search "authentication bug"
+ai-hist search "refactor" --source claude --limit 10
+ai-hist search "deploy" --project relay
+```
+
+| Flag | Effect |
+|------|--------|
+| `--source <name>` | Restrict to one source: `claude`, `codex`, `cursor`, `relay`, `trajectory`, `opencode` |
+| `--project <path>` | Restrict to a project |
+| `--limit <n>` | Cap the number of results |
+
+Results include entry IDs (`#NNN`) used to drill in. See [Search](/docs/loop/search).
+
+## `recent`
+
+Show the most recent prompts, no query needed.
+
+```bash
+ai-hist recent                 # last 20
+ai-hist recent 50              # last 50
+ai-hist recent --source claude --project my-app
+```
+
+Takes an optional count argument and the same `--source` / `--project` filters as `search`.
+
+## `show`
+
+Drill into a specific entry by ID. Prints the full prompt, metadata, session info, and the exact resume command.
+
+```bash
+ai-hist show 4521
+```
+
+## `context`
+
+Show an entry's surrounding context: same-session entries plus nearby entries in a time window.
+
+```bash
+ai-hist context 4521
+ai-hist context 4521 --window 15   # ±15 min window (default: 5)
+```
+
+| Flag | Effect |
+|------|--------|
+| `--window <minutes>` | Width of the nearby-entry time window (default: 5) |
+
+## `session`
+
+View all prompts in a session by session ID.
+
+```bash
+ai-hist session abc-1234-def
+ai-hist session abc-1234-def --full   # no truncation
+```
+
+| Flag | Effect |
+|------|--------|
+| `--full` | Show full prompts without truncation |
+
+See [Sessions](/docs/loop/sessions) for `show`, `context`, `session`, and resume commands together.
+
+## `stats`
+
+Print a database overview: total entries, breakdown by source, date range, and top projects.
+
+```bash
+ai-hist stats
+```
+
+See [Stats](/docs/loop/stats) for the Burn lens.
+
+## `watch`
+
+Run sync repeatedly on an interval — continuous local sync.
+
+```bash
+ai-hist watch                  # sync every 60s
+ai-hist watch --interval 30    # sync every 30s
+```
+
+| Flag | Effect |
+|------|--------|
+| `--interval <seconds>` | Seconds between syncs (default: 60) |
+
+## `cloud`
+
+The opt-in [Relayloop Cloud](/docs/loop/cloud) command group. Local commands keep working unchanged; these add durable backup and cross-device access.
+
+```bash
+ai-hist cloud login            # authenticate and set up your encryption key
+ai-hist cloud sync             # encrypt + push new entries since last push
+ai-hist cloud pull             # fetch + decrypt remote entries into the local DB
+ai-hist cloud watch            # continuous push loop
+ai-hist cloud status           # show sync state, entry count, last push
+ai-hist cloud export --output my-history.jsonl.gz   # export all data
+ai-hist cloud delete <id>      # hard-delete a single entry from the cloud
+ai-hist cloud delete-account   # full account deletion
+```
+
+## Resume commands
+
+`ai-hist show <id>` prints the resume command for the recording tool. The forms are:
+
+```bash
+cd /path/to/project && claude --resume <session_id>          # Claude Code
+codex resume <session_id>                                     # Codex
+cd /path/to/project && cursor-agent --resume=<session_id>     # Cursor
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `AI_HIST_DB` | Override the database path |
+| `AI_HIST_CLI` | Dispatch mode: `auto` (default), `rust`, `python` |
+| `AI_HIST_RUST_BIN` | Use an explicit Rust binary instead of the default |
+| `RELAYCAST_API_KEY` / `RELAYCAST_WORKSPACE_ID` | Configure Agent Relay sync |
+| `TRAJECTORY_ROOT` | Explicit root for trajectory sync |
+
+<CardGroup cols={2}>
+  <Card title="Install" href="/docs/loop/install">
+    Dispatch modes and escape hatches in detail.
+  </Card>
+  <Card title="Quickstart" href="/docs/loop/quickstart">
+    The core commands in a five-minute walkthrough.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/cloud-architecture.mdx b/web/content/docs/loop/cloud-architecture.mdx
new file mode 100644
index 00000000..4d384a01
--- /dev/null
+++ b/web/content/docs/loop/cloud-architecture.mdx
@@ -0,0 +1,61 @@
+---
+title: 'Cloud Architecture'
+description: 'How Relayloop Cloud works end to end: local sync reads files, encrypts them, and POSTs ciphertext over HTTPS to ingestion, storage, and query APIs.'
+---
+
+Relayloop Cloud is deliberately thin where it matters. The client does the work — reading, encrypting, and deciding — and the server stores what it is handed. This page traces the path a history entry takes from a local file to the cloud and back, and names the components it passes through. It is grounded in the [relayhistory-cloud architecture](https://github.com/AgentWorkforce/relayhistory-cloud).
+
+## The path of an entry
+
+The flow is the same shape as local [sync](/docs/loop/sync), with two steps added before the data leaves your machine:
+
+1. **Read** — `ai-hist cloud sync` reads new entries from your local sources, exactly as local sync does.
+2. **Encrypt** — each entry is encrypted on the client. The key never leaves your machine. See [Privacy](/docs/loop/privacy) for the cryptographic detail.
+3. **POST** — the client sends the ciphertext payload to the cloud over HTTPS. Only ciphertext crosses the wire.
+4. **Store** — the cloud ingestion API checks for duplicates and stores the encrypted blobs.
+5. **Query and decrypt** — to read history back, the client (CLI or browser) fetches ciphertext from the query API and decrypts it locally.
+
+The server stores ciphertext blobs plus a small amount of operational metadata. It cannot reconstruct your content.
+
+## Components
+
+### Ingestion API
+
+Receives sync payloads from the CLI. It is stateless — the business logic lives in the client. A sync request carries a batch of entries, each with its ciphertext, nonce, authentication tag, and operational metadata. The server checks each entry's content hash against what it has already stored and skips duplicates, then stores the rest. It also exposes a sync-state endpoint that returns only operational metadata — last sync time and entry count, never content.
+
+### Storage layer
+
+Per-row encryption: every stored row is an encrypted blob keyed by a one-way content hash used for deduplication, alongside the nonce, authentication tag, and schema version. No plaintext content is stored anywhere in the database. The server cannot reconstruct user data even with full database access.
+
+### Auth service
+
+Handles identity and tenant scoping. Authentication establishes *who you are* and which organization you belong to — it grants no decryption access. Identity and encryption-key custody are deliberately separate concerns: logging in does not unlock content. The auth service also handles team membership and seat counting for billing.
+
+### Query API
+
+Returns the ciphertext blobs the server stored, scoped to the authenticated user and org. The client decrypts locally. It also exposes hard-delete endpoints (for a single entry or a full account) and a streaming export endpoint that hands back all your ciphertext for the client to decrypt and write to a local file.
+
+### Hosted MCP endpoint
+
+Lets you point Claude and other MCP clients at a hosted URL instead of running a local MCP server. This is the one place data is transiently decrypted server-side to fulfill tool calls; it is opt-in and clearly disclosed, and the local MCP server remains the zero-trust default. See [Privacy](/docs/loop/privacy) for the trade-off.
+
+### Web dashboard
+
+A single-page app that does all decryption in the browser. On login it pulls your encrypted entries, unlocks your key locally, decrypts into an in-memory index, and runs search client-side. No decrypted content — not even a search query — is sent back to the server.
+
+## What the server can see
+
+The server holds your encrypted blobs plus a thin layer of metadata it needs to operate: your identity and org, your entry count (for billing), each entry's creation timestamp (for sync ordering), and a content hash (for deduplication). The prompt text, project path, session ID, source, and trajectory decisions are all encrypted. The content hash is one-way and reveals only that two entries are duplicates.
+
+## Where the CLI fits
+
+The cloud commands are additive. `ai-hist cloud login` sets up auth and stores your key in the OS keychain; `ai-hist cloud sync` and `ai-hist cloud watch` push encrypted entries; `ai-hist cloud pull` fetches and decrypts them onto a new machine; `ai-hist cloud export` and `ai-hist cloud delete` give you data portability and deletion. Your local-only commands are untouched.
+
+<CardGroup cols={2}>
+  <Card title="Privacy" href="/docs/loop/privacy">
+    The encryption model and its honest limits.
+  </Card>
+  <Card title="Cloud" href="/docs/loop/cloud">
+    What cloud adds and how to opt in.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/cloud.mdx b/web/content/docs/loop/cloud.mdx
new file mode 100644
index 00000000..a272be63
--- /dev/null
+++ b/web/content/docs/loop/cloud.mdx
@@ -0,0 +1,80 @@
+---
+title: 'Relayloop Cloud'
+description: 'An opt-in sync target that adds durable backup, cross-device access, unified search, team recall, a web UI, and a hosted MCP endpoint.'
+---
+
+Relayloop Cloud is a hosted layer on top of the local-first `ai-hist` CLI. The CLI stays exactly as it is — fully functional with no account, working offline. Cloud is an opt-in sync target that adds the things a local SQLite file on one laptop cannot: durable backup, access from every machine, search across your whole team, a web UI, and a hosted MCP endpoint.
+
+The core promise is simple, and architectural rather than just policy: your data is yours to store and yours to remove at any time. See [Privacy](/docs/loop/privacy) for the full data-handling model.
+
+## Why opt in
+
+A local database is fast and private, but it lives on one disk. The moment you work across two machines, replace a laptop, or want a teammate to benefit from a session you ran, you hit its limits. Cloud closes those gaps.
+
+<CardGroup cols={2}>
+  <Card title="Durable backup">
+    Local files get corrupted or deleted. Cloud history is durable — your record survives a wiped disk or a new machine.
+  </Card>
+  <Card title="Cross-device access">
+    Sync history to a new machine instantly and never lose a conversation between devices.
+  </Card>
+  <Card title="Unified search">
+    One place to search across every AI tool you use, from any device.
+  </Card>
+  <Card title="Team recall">
+    Search your teammates' shared sessions so the team never solves the same problem twice.
+  </Card>
+  <Card title="Web UI">
+    A dashboard to search, browse sessions, and view stats in the browser — no terminal required.
+  </Card>
+  <Card title="Hosted MCP">
+    Point your Claude config at a URL instead of running a local MCP server.
+  </Card>
+</CardGroup>
+
+## Opt in from the CLI
+
+Cloud lives under the `ai-hist cloud` command group. Log in once, then push:
+
+```bash
+ai-hist cloud login    # authenticate and set up your encryption key
+ai-hist cloud sync     # encrypt + push new entries since last push
+ai-hist cloud pull     # fetch + decrypt remote entries into the local DB
+ai-hist cloud watch    # continuous push loop, like local watch
+ai-hist cloud status   # show sync state, entry count, last push
+```
+
+Your local commands — `sync`, `search`, `show`, `session`, `stats` — do not change. Cloud sync layers on top of them.
+
+## Local vs. cloud at a glance
+
+| Capability | Local CLI | Relayloop Cloud |
+|------------|-----------|-----------------|
+| Sync, search, show, stats | Yes | Yes |
+| Works offline | Yes | Local CLI still works offline |
+| No account required | Yes | Account required |
+| Durable backup | No (single disk) | Yes |
+| Cross-device access | No | Yes |
+| Web UI | No | Yes |
+| Hosted MCP endpoint | Local MCP server | Hosted endpoint (opt-in) |
+| Team recall / shared sessions | No | Yes ([Teams](/docs/loop/teams)) |
+
+## The local CLI never breaks
+
+This is the deal: nothing about going to cloud takes anything away locally. The CLI remains MIT-licensed and fully functional with zero cloud dependency. You can run entirely local forever, turn on cloud sync when you need backup or a second device, and turn on team features when your team is ready.
+
+<CardGroup cols={2}>
+  <Card title="Cloud architecture" href="/docs/loop/cloud-architecture">
+    How sync reads, encrypts, and pushes to the cloud.
+  </Card>
+  <Card title="Privacy" href="/docs/loop/privacy">
+    Encryption, scrubbing, and your data rights.
+  </Card>
+  <Card title="Teams" href="/docs/loop/teams">
+    Shared memory, onboarding, and pricing.
+  </Card>
+</CardGroup>
+
+<BannerLink href="/docs/loop/teams" icon="rocket">
+  Start free and local. Turn on team sync — and the network — when you are ready.
+</BannerLink>
diff --git a/web/content/docs/loop/install.mdx b/web/content/docs/loop/install.mdx
new file mode 100644
index 00000000..94dfe23b
--- /dev/null
+++ b/web/content/docs/loop/install.mdx
@@ -0,0 +1,93 @@
+---
+title: 'Install'
+description: 'Install the ai-hist CLI in one command, set up your PATH, and understand the Rust-default dispatch and its escape hatches.'
+---
+
+Relayloop ships as a single CLI named `ai-hist`. One install script builds the Rust engine, drops launchers into your local bin directory, and leaves you ready to run `ai-hist sync`. No account is required — installing the CLI gives you the full local-first product.
+
+## Install
+
+Run the install script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relayhistory/main/install.sh | sh
+```
+
+The installer owns the Rust build. It compiles the engine, places the binary under the `ai-hist` install directory, and writes deterministic launchers for `ai-hist`, `ai-hist-rust`, and `ai-hist-python`.
+
+## PATH setup
+
+The launchers install to `~/.local/bin`. Make sure that directory is on your `PATH`:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"   # add to .zshrc / .bashrc
+```
+
+Open a new shell (or `source` your profile) and confirm:
+
+```bash
+ai-hist stats
+```
+
+If the command is found, you are installed. A fresh database reports zero entries until you run your first [sync](/docs/loop/sync).
+
+## Requirements
+
+The install script requires:
+
+- **`cargo`** — to build the Rust engine. If Rust is missing, install it from [rustup.rs](https://rustup.rs/) and rerun the script.
+- **`python3`** — used by the legacy compatibility launcher.
+
+Normal use does not require you to run any Cargo commands yourself. The script handles the build and points the wrapper at the exact binary it produced.
+
+## Rust-default dispatch
+
+`ai-hist` is a Rust-default CLI. The public `ai-hist` command routes the entire user-facing command surface — `sync`, `search`, `recent`, `show`, `context`, `session`, `stats`, `watch` — through the Rust engine. The legacy Python CLI remains installed only as an explicit compatibility escape hatch; auto mode never routes normal commands to Python.
+
+See the [DISPATCH_MATRIX](https://github.com/AgentWorkforce/relayhistory/blob/main/DISPATCH_MATRIX.md) for the tested parity table.
+
+## Escape hatches
+
+You can override dispatch when you need to:
+
+```bash
+# Force the Rust CLI explicitly
+AI_HIST_CLI=rust ai-hist search deploy
+
+# Use the legacy Python compatibility path
+AI_HIST_CLI=python ai-hist sync
+
+# Point the wrapper at a specific Rust binary
+AI_HIST_RUST_BIN=/absolute/path/to/ai-hist-rust-bin ai-hist search deploy
+
+# Call the launchers directly
+ai-hist-rust search deploy
+ai-hist-python sync
+```
+
+The dispatch modes are:
+
+- `AI_HIST_CLI=auto` (default) — Rust for the user-facing surface.
+- `AI_HIST_CLI=rust` — force Rust.
+- `AI_HIST_CLI=python` — force the legacy Python CLI.
+
+<Note>
+  The Rust default honors `XDG_DATA_HOME` before falling back to `~/.local/share/ai-hist/ai-history.db`, matching the legacy Python default. Existing databases stay compatible.
+</Note>
+
+## Database location
+
+By default the database lives at `~/.local/share/ai-hist/ai-history.db`. Override it with the `AI_HIST_DB` environment variable — for example, to keep it in a synced folder:
+
+```bash
+export AI_HIST_DB="$HOME/Dropbox/ai-history/ai-history.db"
+```
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" href="/docs/loop/quickstart">
+    Sync, search, and resume a conversation.
+  </Card>
+  <Card title="Sources" href="/docs/loop/sources">
+    What gets imported and where it reads from on disk.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/introduction.mdx b/web/content/docs/loop/introduction.mdx
new file mode 100644
index 00000000..a71f980c
--- /dev/null
+++ b/web/content/docs/loop/introduction.mdx
@@ -0,0 +1,60 @@
+---
+title: 'Introduction'
+description: 'Relayloop is the system of record for how your team works with AI agents — searchable history, token spend, and patterns that compound.'
+---
+
+Relayloop captures every conversation you and your team have with AI coding agents — Claude Code, Codex, Cursor, Agent Relay, and more — into one searchable record, and turns that record into leverage. It is local-first: a single Rust-backed CLI (`ai-hist`) syncs your agent history into a local SQLite database with full-text search, on your machine, with no account required. The hosted layer, **Relayloop Cloud**, is opt-in.
+
+The local engine binary is `ai-hist`. Wherever you see that command in these docs, it is the real CLI you install and run.
+
+## The problem
+
+Three things go wrong once a team starts leaning on AI agents, and they get worse with scale.
+
+- **AI leverage is bimodal.** Your strongest engineers pull 5–10× out of coding agents; most of the team gets 1×. The gap is prompting skill — tribal, undocumented, and gone the day someone leaves.
+- **Spend is invisible.** Real money flows to tokens every month with almost no visibility into where it goes, which model burned it, or which loop ran away.
+- **Nothing compounds.** Every session — the prompts that worked, the dead ends, the decisions — evaporates when the terminal closes. There is no shared playbook and no improvement loop.
+
+## The three lenses
+
+Relayloop looks at your agent history through three lenses.
+
+<CardGroup cols={3}>
+  <Card title="Recall">
+    A searchable history of how your team prompts. Your best engineers' patterns become a living playbook everyone can draw from — find the prompt, the session, and the resume command in seconds.
+  </Card>
+  <Card title="Burn">
+    Token spend by model, tool, project, and engineer. Find the waste, forecast the cost, and kill runaway loops before they bill you twice.
+  </Card>
+  <Card title="Insights">
+    Patterns become proactive guidance and repo rules, so your baseline rises every week and your codebase gets steadily more agent-ready.
+  </Card>
+</CardGroup>
+
+## Local-first, cloud opt-in
+
+The CLI works completely offline. `ai-hist sync` reads your local agent files, dedupes, and indexes everything into a SQLite database at `~/.local/share/ai-hist/ai-history.db`. Nothing leaves your machine unless you choose to turn on cloud sync.
+
+When you want durable backup, cross-device access, a web UI, and team recall, you opt into [Relayloop Cloud](/docs/loop/cloud). The local CLI does not change and keeps working offline either way.
+
+<Note>
+  Relayloop indexes Agent Relay history as one of its sources. If you coordinate agents with [Agent Relay](/docs/introduction), those conversations land in the same searchable corpus as your Claude Code and Codex sessions.
+</Note>
+
+## Start here
+
+<CardGroup cols={3}>
+  <Card title="Install" href="/docs/loop/install">
+    Install the `ai-hist` CLI in one command and set up your PATH.
+  </Card>
+  <Card title="Search" href="/docs/loop/search">
+    Full-text search across every agent session you have ever run.
+  </Card>
+  <Card title="Cloud" href="/docs/loop/cloud">
+    Opt into durable backup, cross-device sync, and team recall.
+  </Card>
+</CardGroup>
+
+<BannerLink href="/docs/loop/quickstart" icon="rocket">
+  Go from zero to a searchable agent history in five minutes.
+</BannerLink>
diff --git a/web/content/docs/loop/privacy.mdx b/web/content/docs/loop/privacy.mdx
new file mode 100644
index 00000000..518bf29a
--- /dev/null
+++ b/web/content/docs/loop/privacy.mdx
@@ -0,0 +1,75 @@
+---
+title: 'Privacy'
+description: 'How Relayloop Cloud handles your data: encrypted in transit and at rest, secrets scrubbed on ingest, end-to-end encryption available, and full data rights.'
+---
+
+Relayloop is local-first, so the most private option is always to run the CLI and sync nothing. When you do opt into [Relayloop Cloud](/docs/loop/cloud), the data-handling model is built to be honest about what we can and cannot see — and to give you concrete controls, not just promises. This page describes how data is protected, what is scrubbed, the end-to-end-encrypted option and its real limits, and your rights to export and delete.
+
+## Encrypted in transit and at rest
+
+All cloud sync travels over HTTPS, and stored data is encrypted at rest, access-controlled, and audited. Secrets and PII — API keys, tokens, credentials — are scrubbed on ingest, before content is stored.
+
+Your data is never used to train models without your explicit opt-in. Any cross-team learning that powers [Insights](/docs/loop/teams) is always aggregated and anonymized — one customer never sees another's content.
+
+## Two trust tiers
+
+There are two distinct trust models, and it matters which one you are on.
+
+### Team tier (default)
+
+The default tier is vendor-readable: data is encrypted in transit and at rest, secret-scrubbed, and consent-gated, with no training without opt-in. It is readable by the platform so that it can power features like the cross-team learning flywheel. This is the standard SaaS trust model with privacy controls layered on.
+
+### Enterprise / Private tier (end-to-end encrypted)
+
+For teams whose IP or compliance rules mean content cannot leave at all, the Enterprise tier runs end-to-end encrypted, or self-hosted in your own VPC or on-prem. This tier trades the cross-team flywheel for total privacy.
+
+<Note>
+  Choose the tier that matches your constraints. The Team tier is more capable because the platform can read content to help; the Enterprise tier is more private because it cannot. See [Teams](/docs/loop/teams) for how the tiers map to pricing.
+</Note>
+
+## How end-to-end encryption works
+
+On the Enterprise / Private tier, the design principle is that the server stores ciphertext and holds no decryption keys. Even with full database access, neither an attacker nor the platform can read your content.
+
+- **Content encryption** uses AES-256-GCM, with each entry encrypted independently under a fresh nonce. The whole entry — prompt, project path, session ID, source — is encrypted.
+- **Key custody is separate from login.** Authentication establishes who you are; it grants no decryption access. The encryption key is a client-held master key, generated on your first device and never sent to the server.
+- **The master key is wrapped by a separate secret** — an encryption passphrase (or a passkey via WebAuthn-PRF). The server stores only the wrapped key and its salt: ciphertext that is useless without the passphrase. A printed recovery kit is issued at setup, because a lost passphrase means data is unrecoverable by design.
+
+### Browser decryption
+
+The web dashboard decrypts entirely in the browser. You sign in for identity, enter your passphrase (or tap a passkey), the browser unwraps the key locally and decrypts entries in memory, and search runs against that in-memory index. The key is held only for the tab's lifetime and discarded when the tab closes — never persisted, never sent to the server. This is the same model used by Bitwarden, ProtonMail, and 1Password web clients.
+
+### Honest limits
+
+End-to-end encryption is not magic, and the limits deserve to be stated plainly:
+
+- **JavaScript delivery.** With a web app, the browser executes JavaScript served by the server on every page load. This shifts one trust assumption that the CLI does not have: you trust that the server is delivering the same JS that is in the open source repo. This is mitigated — not eliminated — by Subresource Integrity (the browser refuses JS that does not match a published hash), a strict Content Security Policy, an open-source web client whose build hashes are published, and holding the key only in tab-scoped session storage. For maximum security, use the CLI, where the key lives in the OS keychain and never touches a browser.
+- **Compromised client device.** If your device is compromised, the local key can be extracted. Encryption protects data on our servers, not on a machine an attacker already controls.
+- **Weak passphrase.** A memory-hard KDF slows brute-force of the wrapped key but cannot save a very weak passphrase; minimum entropy is enforced, and the passkey path is preferred where available.
+- **Hosted MCP endpoint.** The [hosted MCP endpoint](/docs/loop/cloud-architecture) is the one place data is transiently decrypted server-side, which requires trusting the server. It is opt-in and clearly disclosed; the local MCP server stays the zero-trust default.
+
+## What the server can see
+
+On the end-to-end tier the server holds your ciphertext plus a thin operational layer: your identity and org, the wrapped key and its salt (ciphertext only), entry count for billing, per-entry creation timestamp for ordering, and a one-way content hash for deduplication. Prompt text, project paths, session IDs, sources, and trajectory decisions are encrypted. The content hash reveals only that two entries are duplicates.
+
+## Your data rights
+
+These are commitments backed by mechanics, not just policy. They map to GDPR Articles 15, 17, and 20 and CCPA rights.
+
+- **Delete, immediately and permanently.** Delete a single entry with `ai-hist cloud delete <id>`, or your whole account with `ai-hist cloud delete-account`. Deletes are hard deletes — rows are removed, not flagged — completing synchronously. Nightly backups are retained for 7 days for disaster recovery and disclosed explicitly; after 7 days no copy exists on our infrastructure.
+- **Export, any time, always free.** `ai-hist cloud export --output my-history.jsonl.gz` streams your ciphertext, decrypts it locally, and writes NDJSON in the same format as local `ai-hist export`. It imports straight into a local database with `ai-hist import` — no cloud dependency.
+- **No training use.** Your data is never used to train any model, ours or anyone's. This is written into the Terms of Service and is not waivable.
+- **No third-party analytics SDKs** in the sync client.
+
+## Compliance posture
+
+The end-to-end architecture is a structural compliance asset: it makes several controls provable rather than procedural. The roadmap targets SOC 2 (Security, Confidentiality, Privacy), then ISO 27001 and ISO 27701, with an EU–U.S. Data Privacy Framework self-certification and a CSA STAR self-assessment along the way. Data Processing Agreements are available for enterprise customers. Before any of those certifications land, the strongest assurance is the open-source client itself — a skeptical security team can read the encryption code and verify the claim.
+
+<CardGroup cols={2}>
+  <Card title="Cloud architecture" href="/docs/loop/cloud-architecture">
+    Where encryption sits in the data flow.
+  </Card>
+  <Card title="Teams" href="/docs/loop/teams">
+    How the trust tiers map to pricing.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/quickstart.mdx b/web/content/docs/loop/quickstart.mdx
new file mode 100644
index 00000000..3694a417
--- /dev/null
+++ b/web/content/docs/loop/quickstart.mdx
@@ -0,0 +1,86 @@
+---
+title: 'Quickstart'
+description: 'From zero to a searchable agent history: sync your sessions, find a past prompt, and resume the conversation.'
+---
+
+This walks you from a fresh install to real value in a few commands: pull your agent history into a local database, search it, drill into a session, and jump back into the exact conversation. Everything here runs locally and needs no account. If you have not installed yet, start with [Install](/docs/loop/install).
+
+## 1. Sync your history
+
+Pull every supported source into the local database. The first run reads everything; later runs are incremental and only read new bytes.
+
+```bash
+ai-hist sync
+```
+
+This imports Claude Code, Codex CLI, Cursor, OpenCode, Agent Relay (when configured), and compacted trajectory runs. See [Sources](/docs/loop/sources) for exactly what is read and from where.
+
+## 2. Search across everything
+
+Full-text search runs over all sources at once:
+
+```bash
+ai-hist search "authentication bug"
+```
+
+Results come back with entry IDs in the form `#NNN`. Those IDs are your handle for drilling deeper. Narrow the search with filters when you need to:
+
+```bash
+ai-hist search "refactor" --source claude --limit 10
+ai-hist search "deploy" --project relay
+```
+
+See [Search](/docs/loop/search) for the full filter set.
+
+## 3. Drill into an entry
+
+Take an entry ID from your search results and look at the full prompt, its session, and the exact command to resume it:
+
+```bash
+ai-hist show 4521
+```
+
+To see what else was happening around that moment — the same session plus nearby entries — use `context`:
+
+```bash
+ai-hist context 4521
+ai-hist context 4521 --window 15   # widen to a 15-minute window
+```
+
+To browse an entire conversation, use `session` with the session ID:
+
+```bash
+ai-hist session abc-1234-def
+ai-hist session abc-1234-def --full   # no truncation
+```
+
+## 4. Resume the conversation
+
+`ai-hist show <id>` prints the exact resume command for the tool that recorded the session. Run it to pick the conversation back up where it left off:
+
+```bash
+cd /path/to/project && claude --resume <session_id>          # Claude Code
+codex resume <session_id>                                     # Codex
+cd /path/to/project && cursor-agent --resume=<session_id>     # Cursor
+```
+
+<Note>
+  Copy the resume command straight from `ai-hist show <id>` rather than hand-building it — it already has the right project directory and session ID filled in.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Sync" href="/docs/loop/sync">
+    Keep your history current with continuous watch mode.
+  </Card>
+  <Card title="Sessions" href="/docs/loop/sessions">
+    Drill into sessions and resume across every tool.
+  </Card>
+  <Card title="Stats" href="/docs/loop/stats">
+    The Burn lens: see where your token spend goes.
+  </Card>
+  <Card title="Cloud" href="/docs/loop/cloud">
+    Add durable backup and team recall when you are ready.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/search.mdx b/web/content/docs/loop/search.mdx
new file mode 100644
index 00000000..e91e7f2d
--- /dev/null
+++ b/web/content/docs/loop/search.mdx
@@ -0,0 +1,69 @@
+---
+title: 'Search'
+description: 'Full-text search across every agent session with ai-hist search and recent, using entry IDs as the handle to drill deeper.'
+---
+
+Search is the Recall lens. Once you have [synced](/docs/loop/sync), every prompt you and your team have ever sent to an AI agent is one query away — across Claude Code, Codex, Cursor, OpenCode, Agent Relay, and trajectories at the same time. Search is powered by SQLite FTS5, so it is fast even over tens of thousands of entries.
+
+## Full-text search
+
+Search across all sources with a query string:
+
+```bash
+ai-hist search "authentication bug"
+```
+
+Results come back ranked, each with an entry ID in the form `#NNN`. That ID is your handle to drill in further.
+
+## Filters
+
+Narrow a search by source, project, or result count:
+
+```bash
+ai-hist search "refactor" --source claude --limit 10
+ai-hist search "deploy" --source relay
+ai-hist search "retry policy" --source trajectory
+ai-hist search "deploy" --project relay
+```
+
+- `--source` — restrict to one source. Valid values are `claude`, `codex`, `cursor`, `relay`, `trajectory`, and `opencode`. See [Sources](/docs/loop/sources).
+- `--project` — restrict to a project (matched against the recorded project path).
+- `--limit` — cap the number of results returned.
+
+## Recent prompts
+
+To see what you have been working on most recently without a query, use `recent`:
+
+```bash
+ai-hist recent                              # last 20
+ai-hist recent 50                           # last 50
+ai-hist recent --source claude --project my-app
+```
+
+`recent` accepts the same `--source` and `--project` filters as search.
+
+## Entry IDs are the drill-in handle
+
+Search and recent both surface entry IDs (`#NNN`). Use them to move from a hit to the full picture:
+
+```bash
+ai-hist search "deploy"   # find #4521 in the results
+ai-hist show 4521         # full prompt, session info, resume command
+ai-hist context 4521      # what else was happening in that session, plus nearby entries
+ai-hist session <id>      # browse the full conversation
+```
+
+This is the core Recall loop: search broad, find the entry, then [drill into the session](/docs/loop/sessions) and resume it.
+
+<Note>
+  Searching for a problem you have hit before is the fastest way to recover a working approach — find the prompt that solved it last time, then reuse or resume it.
+</Note>
+
+<CardGroup cols={2}>
+  <Card title="Sessions" href="/docs/loop/sessions">
+    Show, context, session, and per-tool resume commands.
+  </Card>
+  <Card title="Sources" href="/docs/loop/sources">
+    The full list of sources and `--source` filter values.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/sessions.mdx b/web/content/docs/loop/sessions.mdx
new file mode 100644
index 00000000..70a0e3fb
--- /dev/null
+++ b/web/content/docs/loop/sessions.mdx
@@ -0,0 +1,63 @@
+---
+title: 'Sessions'
+description: 'Drill into a single entry, see its surrounding context, browse a whole session, and resume the conversation in any tool.'
+---
+
+Search gets you to an entry; sessions get you the whole story behind it. Once you have an entry ID from [search](/docs/loop/search), three commands let you zoom from a single prompt out to the full conversation — and then jump back into it in the original tool.
+
+## Show a single entry
+
+`show` takes an entry ID and prints the full prompt, its metadata, the session it belongs to, and — crucially — the exact command to resume it:
+
+```bash
+ai-hist show 4521
+```
+
+This is the command to reach for first. The resume command it prints is built for the tool that recorded the session, with the right project directory and session ID already filled in.
+
+## See surrounding context
+
+`context` shows what else was happening around an entry: other entries from the same session, plus nearby entries within a time window.
+
+```bash
+ai-hist context 4521
+ai-hist context 4521 --window 15   # widen to a 15-minute window (default: 5)
+```
+
+This is useful when one prompt only makes sense alongside the steps before and after it — the failed attempt, the fix, the follow-up.
+
+## Browse a whole session
+
+When you want the full conversation, pass a session ID to `session`:
+
+```bash
+ai-hist session abc-1234-def
+ai-hist session abc-1234-def --full   # no truncation
+```
+
+By default long prompts are truncated for readability. Add `--full` to see every prompt in full.
+
+## Resume in any tool
+
+The fastest path back into a conversation is to copy the resume command printed by `ai-hist show <id>`. The shape depends on the recording tool:
+
+```bash
+cd /path/to/project && claude --resume <session_id>          # Claude Code
+codex resume <session_id>                                     # Codex
+cd /path/to/project && cursor-agent --resume=<session_id>     # Cursor
+```
+
+Note that Claude Code and Cursor expect you to be in the project directory first, which is why the printed command includes the `cd`. The placeholder `<session_id>` is filled in for you by `ai-hist show`.
+
+<Note>
+  Don't hand-build resume commands. `ai-hist show <id>` already knows the source, the project path, and the session ID, and prints the exact command for that tool.
+</Note>
+
+<CardGroup cols={2}>
+  <Card title="Search" href="/docs/loop/search">
+    Find the entry ID to start from.
+  </Card>
+  <Card title="CLI reference" href="/docs/loop/cli">
+    Every command and flag in one place.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/sources.mdx b/web/content/docs/loop/sources.mdx
new file mode 100644
index 00000000..fd0ffe7e
--- /dev/null
+++ b/web/content/docs/loop/sources.mdx
@@ -0,0 +1,69 @@
+---
+title: 'Sources'
+description: 'The agent tools Relayloop indexes, where each reads from on disk, and the --source filter values you use to scope queries.'
+---
+
+Relayloop's value comes from aggregating history that is otherwise scattered across a half-dozen tools and file formats. A single [`ai-hist sync`](/docs/loop/sync) pulls all of them into one indexed corpus. This page lists every supported source, where it reads from, and the `--source` value you use to filter [search](/docs/loop/search) and [recent](/docs/loop/search).
+
+## Supported sources
+
+| Source | `--source` value | Where it reads from |
+|--------|------------------|---------------------|
+| Claude Code | `claude` | `~/.claude/history.jsonl` |
+| Codex CLI | `codex` | `~/.codex/history.jsonl` |
+| Cursor | `cursor` | Per-session JSONL under `~/.cursor/projects/...` |
+| Agent Relay | `relay` | Relaycast API (`https://api.relaycast.dev/v1`) |
+| Trajectories | `trajectory` | Compacted per-run JSON files |
+| OpenCode | `opencode` | Local SQLite (`~/.local/share/opencode/opencode.db`) |
+
+Pass any of these to `--source` to scope a query:
+
+```bash
+ai-hist search "deploy" --source claude
+ai-hist recent --source codex
+ai-hist search "retry policy" --source trajectory
+```
+
+## File-based sources
+
+**Claude Code, Codex, and Cursor** are synced incrementally from local files using byte-offset tracking, so re-syncing only reads what is new.
+
+- **Claude Code** reads `~/.claude/history.jsonl`, using its `display`, `timestamp`, `project`, and `sessionId` fields.
+- **Codex CLI** reads `~/.codex/history.jsonl`, using its `text`, `ts`, and `session_id` fields.
+- **Cursor** reads per-session transcripts at `~/.cursor/projects/<encoded-path>/agent-transcripts/<uuid>/<uuid>.jsonl`. User prompts are extracted from the message content. Because Cursor lines carry no per-line timestamp, the file modification time at sync time is used instead.
+
+**OpenCode** is read from a local SQLite database (`$OPENCODE_DB` or `~/.local/share/opencode/opencode.db`), joining user text parts to their sessions. Reads are WAL-safe so an active OpenCode session is not disrupted.
+
+## Agent Relay
+
+[Agent Relay](/docs/introduction) history is pulled from the Relaycast API with cursor-based pagination, indexing each message's `sender`, `content`, `channel`, and `timestamp`. Configure it with environment variables:
+
+```bash
+export RELAYCAST_API_KEY="rk_live_..."
+export RELAYCAST_WORKSPACE_ID="ws_abc123"
+```
+
+## Trajectories
+
+Trajectories are compacted per-run JSON files that capture the *why* behind an agent run — the task, the decisions made, the alternatives considered, and a retrospective. They round out the searchable history with structured reasoning, not just prompts.
+
+By default, sync discovers `~/Projects/**/.trajectories/**/compacted/*.json`. Point it at an explicit root with:
+
+```bash
+export TRAJECTORY_ROOT="/path/to/repo/.trajectories"
+```
+
+Sync then scans `$TRAJECTORY_ROOT/**/compacted/*.json`. Each file is one completed run, with fields like `personaId`, `projectId`, `task`, `decisions`, and `retrospective`. A searchable `trajectory` row is inserted into the history index, and the structured decisions and retrospectives are also retained for richer queries.
+
+<Note>
+  Trajectory sync indexes the runtime-emitted per-run contract files, not aggregate compaction artifacts.
+</Note>
+
+<CardGroup cols={2}>
+  <Card title="Sync" href="/docs/loop/sync">
+    How sync reads and dedupes these sources.
+  </Card>
+  <Card title="Search" href="/docs/loop/search">
+    Use `--source` to scope queries.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/stats.mdx b/web/content/docs/loop/stats.mdx
new file mode 100644
index 00000000..f875f21b
--- /dev/null
+++ b/web/content/docs/loop/stats.mdx
@@ -0,0 +1,67 @@
+---
+title: 'Stats'
+description: 'The Burn lens: see your agent history at a glance, attribute token spend by model, tool, project, and engineer, and kill runaway loops.'
+---
+
+`ai-hist stats` is your dashboard for the corpus you have built — and the entry point to the Burn lens. At its simplest it tells you how much history you have and where it came from. As your record grows, it becomes the place to see where token spend actually goes and which sessions are burning money for nothing.
+
+## Overview
+
+Run `stats` for a snapshot of the whole database:
+
+```bash
+ai-hist stats
+```
+
+Example output:
+
+```
+Total entries: 47,665
+
+By source:
+  claude: 37,406
+  codex: 10,259
+
+Date range:
+  2025-10-05 to 2026-03-08
+
+Top 10 projects:
+   8,701  /Users/you/Projects/my-app
+   4,586  /Users/you/Projects/api-server
+   ...
+```
+
+You get total entries, a breakdown by source, the date range covered, and your busiest projects — a fast read on where your AI work is concentrated.
+
+## The Burn lens
+
+Recall tells you *how* your team prompts. Burn tells you what it costs. The same history that makes sessions searchable also makes spend attributable: every entry is tagged with its source (tool), its project, and — once you sync as a team via [Relayloop Cloud](/docs/loop/cloud) — the engineer behind it.
+
+That attribution turns an opaque monthly token bill into answers:
+
+- **By model and tool** — which agents and models account for the spend.
+- **By project** — which codebases are the expensive ones to work in.
+- **By engineer** — where leverage is high and where sessions churn.
+
+## Finding waste and runaway loops
+
+The patterns Burn surfaces are the ones worth acting on:
+
+- **Repeated dead ends** — the same prompt retried over and over in a session is a signal that an approach is not landing. Drill in with [`ai-hist context <id>`](/docs/loop/sessions) to see the loop.
+- **Runaway loops** — a session that keeps regenerating without converging burns tokens fast. Catching these early, before they bill you twice, is direct savings.
+- **Expensive habits** — a project that consistently costs more per task is a candidate for better repo rules, which the [Insights](/docs/loop/teams) lens turns into proactive guidance.
+
+The goal of Burn is lower, more predictable token spend — not by rationing, but by seeing the waste clearly enough to cut it.
+
+<Note>
+  Burn is most useful with continuous [sync](/docs/loop/sync) running so the numbers reflect today's work, not last week's snapshot. Pair it with [Insights](/docs/loop/teams) to turn the waste you find into rules that prevent it.
+</Note>
+
+<CardGroup cols={2}>
+  <Card title="Cloud" href="/docs/loop/cloud">
+    Per-engineer attribution across the team.
+  </Card>
+  <Card title="Teams" href="/docs/loop/teams">
+    Turn Burn patterns into Insights and repo rules.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/sync.mdx b/web/content/docs/loop/sync.mdx
new file mode 100644
index 00000000..be4c55fa
--- /dev/null
+++ b/web/content/docs/loop/sync.mdx
@@ -0,0 +1,69 @@
+---
+title: 'Sync'
+description: 'How ai-hist sync imports your agent history incrementally, what gets indexed, and how to keep it current with watch mode.'
+---
+
+`ai-hist sync` is the command that builds your history. It reads your local agent files, dedupes, and indexes everything into a SQLite database with full-text search. The first run imports everything; every run after that is incremental — it tracks byte offsets per file and only reads what is new.
+
+```bash
+ai-hist sync
+```
+
+## What gets imported
+
+A single `sync` covers every supported source in one pass:
+
+- **Claude Code** — local JSONL history
+- **Codex CLI** — local JSONL history
+- **Cursor** — per-session JSONL transcripts
+- **OpenCode** — local SQLite database
+- **Agent Relay** — workspace messages via the Relaycast API (when configured)
+- **Trajectories** — compacted per-run JSON files capturing decisions and retrospectives
+
+See [Sources](/docs/loop/sources) for exactly where each reads from on disk and how to configure the API-backed ones.
+
+## Incremental by design
+
+Sync is cheap to run often. For the file-based sources (Claude Code, Codex, Cursor), it tracks a byte offset per file in a `.sync-state.json` state file and only reads the bytes appended since last time. Re-running `ai-hist sync` after a long coding session reads just the new lines, not the whole file.
+
+Deduplication is enforced at the database level — entries are unique on the combination of source, timestamp, and prompt — so syncing the same data twice never creates duplicates.
+
+<Note>
+  Cursor transcript lines carry no per-line timestamp, so sync uses the file's modification time at sync time. Running sync regularly keeps those timestamps close to reality.
+</Note>
+
+## Continuous sync with watch
+
+To keep history current without thinking about it, run watch mode. It runs the same sync on a loop:
+
+```bash
+ai-hist watch                  # sync every 60s
+ai-hist watch --interval 30    # sync every 30s
+```
+
+For a fully managed background loop, schedule `ai-hist sync` with your OS scheduler — a launchd agent on macOS or a cron entry on Linux. The [relayhistory README](https://github.com/AgentWorkforce/relayhistory) includes ready-to-copy launchd and cron snippets.
+
+```bash
+# Linux: sync every minute via cron
+echo "* * * * * ~/.local/bin/ai-hist sync >> /tmp/ai-hist-sync.log 2>&1" | crontab -
+```
+
+## Cloud sync
+
+Everything above is local. When you want your history backed up durably and available on every machine, opt into Relayloop Cloud and push with the cloud sync loop:
+
+```bash
+ai-hist cloud sync     # encrypt + push new entries since last push
+ai-hist cloud watch    # continuous push loop, like local watch
+```
+
+Local sync and cloud sync are independent. The local CLI keeps working offline, and cloud sync layers durable backup and cross-device access on top.
+
+<CardGroup cols={2}>
+  <Card title="Cloud" href="/docs/loop/cloud">
+    What cloud sync adds and how to opt in.
+  </Card>
+  <Card title="Cloud architecture" href="/docs/loop/cloud-architecture">
+    How local sync reads, encrypts, and pushes to the cloud.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/loop/teams.mdx b/web/content/docs/loop/teams.mdx
new file mode 100644
index 00000000..ccf861c4
--- /dev/null
+++ b/web/content/docs/loop/teams.mdx
@@ -0,0 +1,62 @@
+---
+title: 'Teams'
+description: 'Shared organizational memory, faster onboarding, knowledge retention, the Insights flywheel that learns across teams, and pricing tiers.'
+---
+
+For an individual, Relayloop is a searchable memory. For a team, it becomes shared organizational memory — and an improvement loop that raises everyone's baseline. The thesis behind [Relayloop](/docs/loop/introduction) is that AI leverage is bimodal: your best engineers get 5–10× from coding agents while most of the team gets 1×, and the difference is prompting skill that today is tribal and undocumented. Team features close that gap and make sure nothing evaporates when people leave.
+
+## Shared organizational memory
+
+When teammates opt into [cloud](/docs/loop/cloud) sync and share sessions, the team's prompts become a common corpus. Anyone can search how a colleague approached a problem instead of solving it from scratch. Your best engineers' patterns become a living playbook the whole team draws from — the Recall lens, but team-wide.
+
+## Onboarding acceleration
+
+New hires inherit the team's accumulated AI history on day one. Instead of learning the codebase and the team's prompting style by osmosis, they can search how the team has approached similar work and start from a known-good pattern. The ramp gets shorter and first-try acceptance goes up.
+
+## Knowledge retention
+
+When someone leaves, their AI-assisted work history stays with the organization. The sessions, the decisions, and — through trajectory records — the *why* behind them, all remain searchable. Institutional knowledge that used to walk out the door now stays.
+
+## The network that learns
+
+The Insights flywheel is what a single-team tool cannot match. Relayloop does not only learn from your team — it learns what works across every team on the platform and feeds the generalized, anonymized lessons back to you.
+
+> The more teams on Relayloop, the smarter your engineers' agents get.
+
+Your engineers get the benefit of patterns proven across thousands of others, automatically, without you running the experiments. Cross-team learning is always aggregated and anonymized — one customer never sees another's content — and your data is never used to train models without your explicit opt-in. Patterns turn into proactive guidance and repo rules, so your baseline rises every week and your codebase gets steadily more agent-ready. Teams that need full isolation can run the Enterprise tier end-to-end encrypted or in their own VPC, trading the flywheel for total privacy. See [Privacy](/docs/loop/privacy) for the trust model.
+
+## What to expect
+
+- Faster ramp for new and junior engineers.
+- Higher first-try acceptance and less agent rework.
+- Lower, more predictable token spend ([Burn](/docs/loop/stats)).
+- A prompting playbook that improves on its own — and gets better as the network grows.
+
+## Pricing
+
+<CardGroup cols={3}>
+  <Card title="Free">
+    Local-first, single engineer, up and running in five minutes. The full `ai-hist` CLI with no account.
+  </Card>
+  <Card title="Team">
+    From $49/mo for 5 seats. Org dashboard, shared sessions, and team plus network Insights.
+  </Card>
+  <Card title="Enterprise">
+    Custom. SSO/SAML, end-to-end encryption or self-host/VPC, audit log, and data residency.
+  </Card>
+</CardGroup>
+
+Start free and local. Turn on team sync — and the network — when you are ready.
+
+<CardGroup cols={2}>
+  <Card title="Cloud" href="/docs/loop/cloud">
+    Opt into sync, shared sessions, and the web UI.
+  </Card>
+  <Card title="Privacy" href="/docs/loop/privacy">
+    How team data is handled and the trust tiers.
+  </Card>
+</CardGroup>
+
+<BannerLink href="/docs/loop/install" icon="rocket">
+  Install the CLI and start building your team's shared memory.
+</BannerLink>
diff --git a/web/lib/docs-markdown.ts b/web/lib/docs-markdown.ts
index 4b710729..a1ba7b80 100644
--- a/web/lib/docs-markdown.ts
+++ b/web/lib/docs-markdown.ts
@@ -85,7 +85,7 @@ function renderBannerLink(attrs: string, body: string): string {
   return href ? `[${label}](${href})` : label;
 }
 
-function renderMarkdownBody(content: string): string {
+export function renderMarkdownBody(content: string): string {
   let output = content;
 
   output = output.replace(/<CodeGroup>\s*/g, '');
diff --git a/web/lib/product-docs-nav.ts b/web/lib/product-docs-nav.ts
new file mode 100644
index 00000000..484a3627
--- /dev/null
+++ b/web/lib/product-docs-nav.ts
@@ -0,0 +1,150 @@
+// Pure, dependency-free section + nav definitions for the standalone product
+// docs (Relayfile, Relayloop). This module is safe to import from client
+// components — it must NOT import anything that touches `node:fs` (e.g.
+// content-store), so the sidebar can use it without dragging server-only code
+// into the browser bundle. Content loaders live in `./product-docs`.
+
+export interface NavItem {
+  title: string;
+  slug: string;
+}
+
+export interface NavGroup {
+  title: string;
+  items: NavItem[];
+}
+
+/**
+ * A standalone documentation section that lives alongside the Agent Relay docs
+ * but has its own sidebar, content tree, and routing under `/docs/<id>`.
+ */
+export interface ProductDocSection {
+  /** Route + content-folder id, e.g. `file` → `/docs/file`, `content/docs/file`. */
+  id: string;
+  /** Product name shown at the top of the sidebar. */
+  label: string;
+  /** One-line tagline for the sidebar / metadata. */
+  tagline: string;
+  /** GitHub org/repo, used for the sidebar source link. */
+  repo: string;
+  nav: NavGroup[];
+}
+
+export const fileSection: ProductDocSection = {
+  id: 'file',
+  label: 'Relayfile',
+  tagline: 'The event layer for AI agents.',
+  repo: 'AgentWorkforce/relayfile',
+  nav: [
+    {
+      title: 'Start',
+      items: [
+        { title: 'Introduction', slug: 'introduction' },
+        { title: 'Quickstart', slug: 'quickstart' },
+        { title: 'Why files', slug: 'why-files' },
+      ],
+    },
+    {
+      title: 'Concepts',
+      items: [
+        { title: 'Mount layout', slug: 'mount-layout' },
+        { title: 'Reads and writes', slug: 'reads-and-writes' },
+        { title: 'Per-agent ACLs', slug: 'acls' },
+        { title: 'Real-time sync', slug: 'realtime-sync' },
+      ],
+    },
+    {
+      title: 'Running Relayfile',
+      items: [
+        { title: 'Run locally', slug: 'run-locally' },
+        { title: 'Local development', slug: 'local-development' },
+        { title: 'Mounting a workspace', slug: 'mounting' },
+      ],
+    },
+    {
+      title: 'SDK & agents',
+      items: [
+        { title: 'TypeScript SDK', slug: 'sdk' },
+        { title: 'Agent frameworks', slug: 'agents' },
+      ],
+    },
+    {
+      title: 'Architecture',
+      items: [
+        { title: 'Adapters & providers', slug: 'adapters-and-providers' },
+        { title: 'How Relayfile compares', slug: 'comparison' },
+      ],
+    },
+    {
+      title: 'Cloud',
+      items: [{ title: 'Hosted Relayfile', slug: 'cloud' }],
+    },
+    {
+      title: 'Reference',
+      items: [
+        { title: 'API reference', slug: 'api-reference' },
+        { title: 'CLI reference', slug: 'cli' },
+      ],
+    },
+  ],
+};
+
+export const loopSection: ProductDocSection = {
+  id: 'loop',
+  label: 'Relayloop',
+  tagline: 'The system of record for how your team works with AI agents.',
+  repo: 'AgentWorkforce/relayhistory',
+  nav: [
+    {
+      title: 'Start',
+      items: [
+        { title: 'Introduction', slug: 'introduction' },
+        { title: 'Install', slug: 'install' },
+        { title: 'Quickstart', slug: 'quickstart' },
+      ],
+    },
+    {
+      title: 'Using Relayloop',
+      items: [
+        { title: 'Sync', slug: 'sync' },
+        { title: 'Search', slug: 'search' },
+        { title: 'Sessions & resume', slug: 'sessions' },
+        { title: 'Sources', slug: 'sources' },
+        { title: 'Stats & burn', slug: 'stats' },
+      ],
+    },
+    {
+      title: 'Cloud',
+      items: [
+        { title: 'Relayloop Cloud', slug: 'cloud' },
+        { title: 'Architecture', slug: 'cloud-architecture' },
+        { title: 'Privacy & encryption', slug: 'privacy' },
+        { title: 'Teams', slug: 'teams' },
+      ],
+    },
+    {
+      title: 'Reference',
+      items: [{ title: 'CLI reference', slug: 'cli' }],
+    },
+  ],
+};
+
+export const productSections: ProductDocSection[] = [fileSection, loopSection];
+
+export function getProductSection(id: string): ProductDocSection | null {
+  return productSections.find((section) => section.id === id) ?? null;
+}
+
+/** Resolve a section from a pathname like `/docs/file/quickstart`. */
+export function getProductSectionForPath(pathname: string): ProductDocSection | null {
+  const normalized = pathname.split('?')[0].split('#')[0].replace(/\/+$/, '') || '/docs';
+  const match = normalized.match(/^\/docs\/([^/]+)/);
+  if (!match) return null;
+  return getProductSection(match[1]);
+}
+
+export function getProductDocSlugs(section: ProductDocSection): string[] {
+  return [...new Set(section.nav.flatMap((group) => group.items.map((item) => item.slug)))];
+}
+
+export const productBasePath = (section: ProductDocSection): string => `/docs/${section.id}`;
diff --git a/web/lib/product-docs.ts b/web/lib/product-docs.ts
new file mode 100644
index 00000000..90770eb4
--- /dev/null
+++ b/web/lib/product-docs.ts
@@ -0,0 +1,92 @@
+import matter from 'gray-matter';
+
+import { readContentFile } from './content-store';
+import type { DocContent, SearchEntry } from './docs';
+import { getDoc } from './docs';
+import { renderMarkdownBody } from './docs-markdown';
+import type { ProductDocSection } from './product-docs-nav';
+import { getProductDocSlugs } from './product-docs-nav';
+import { absoluteUrl } from './site';
+
+// Re-export the pure nav surface so server code can import everything from one
+// place. Client components must import from `./product-docs-nav` directly to
+// avoid pulling the server-only loaders below into the browser bundle.
+export type { NavItem, NavGroup, ProductDocSection } from './product-docs-nav';
+export {
+  fileSection,
+  loopSection,
+  productSections,
+  getProductSection,
+  getProductSectionForPath,
+  getProductDocSlugs,
+  productBasePath,
+} from './product-docs-nav';
+
+/** Load a product doc; content lives at `content/docs/<sectionId>/<slug>.mdx`. */
+export function getProductDoc(sectionId: string, slug: string): DocContent | null {
+  return getDoc(`${sectionId}/${slug}`);
+}
+
+export function getProductDocMarkdownUrl(sectionId: string, slug: string): string {
+  return absoluteUrl(`/docs/${sectionId}/markdown/${slug}.md`);
+}
+
+/** Markdown mirror of a product doc, for the `.md` endpoints and copy actions. */
+export function getProductDocMarkdown(
+  sectionId: string,
+  slug: string
+): { title: string; description: string; markdown: string } | null {
+  const raw = readContentFile(`docs/${sectionId}/${slug}.mdx`);
+  if (raw === null) return null;
+
+  const { data, content } = matter(raw);
+  const title = (data.title as string) || slug;
+  const description = (data.description as string) || '';
+  const canonicalUrl = absoluteUrl(`/docs/${sectionId}/${slug}`);
+  const markdownUrl = getProductDocMarkdownUrl(sectionId, slug);
+
+  const header = [
+    `# ${title}`,
+    description ? `\n${description}` : '',
+    `\nRendered page: ${canonicalUrl}`,
+    `Markdown endpoint: ${markdownUrl}`,
+    '\n---\n',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  return { title, description, markdown: `${header}\n${renderMarkdownBody(content)}\n` };
+}
+
+/** Per-section search index, scoped to that product's pages. */
+export function getProductSearchIndex(section: ProductDocSection): SearchEntry[] {
+  return getProductDocSlugs(section).flatMap((slug) => {
+    const raw = readContentFile(`docs/${section.id}/${slug}.mdx`);
+    if (raw === null) return [];
+
+    const { data, content } = matter(raw);
+    const headings: string[] = [];
+    const hRegex = /^#{2,3}\s+(.+)$/gm;
+    let m;
+    while ((m = hRegex.exec(content)) !== null) {
+      headings.push(m[1].replace(/`([^`]+)`/g, '$1').trim());
+    }
+
+    const body = content
+      .split(/\r?\n/)
+      .filter((line) => line.trim() && !line.trim().startsWith('<') && !line.trim().startsWith('```'))
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .slice(0, 500);
+
+    return [
+      {
+        slug,
+        title: (data.title as string) || slug,
+        description: (data.description as string) || '',
+        headings,
+        body,
+      },
+    ];
+  });
+}

From cd571f275536b7aae262ad78dbc34eeeade15a8b Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 24 Jun 2026 14:46:50 +0200
Subject: [PATCH 2/2] docs: rework Relayfile intro/why-files and correct
 Relayloop to real CLI

Relayfile:
- Rewrite introduction around event materialization; CLI/SDK CodeGroup
- Add events (webhook normalization) and self-hosting concept pages
- why-files mirrors the "Just Give the Agent Files" blog, trimmed
- quickstart shows hosted path only, links self-host + GitHub

Relayloop: ground the docs in relayhistory/relayhistory-cloud
- Remove the fabricated `ai-hist cloud` command group; real flow is
  `ai-hist login` + `ai-hist push`, plus pair check and learn distill
- Rebuild CLI reference (pack/resume/export/import/tags, real env vars)
- Add Grok source; correct cloud architecture to Workers + Neon/pgvector
- Default tier is vendor-readable (scrubbed); E2E is Enterprise tier
- Mark unbuilt cloud/team features (cross-device pull, web UI, hosted
  MCP, Insights, teams, pricing) as coming soon

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 web/content/docs/file/events.mdx             |  78 ++++++++++
 web/content/docs/file/introduction.mdx       |  59 +++++---
 web/content/docs/file/quickstart.mdx         |  57 +-------
 web/content/docs/file/self-hosting.mdx       |  47 ++++++
 web/content/docs/file/why-files.mdx          |  48 +++----
 web/content/docs/loop/cli.mdx                | 143 ++++++++++++++-----
 web/content/docs/loop/cloud-architecture.mdx |  53 +++----
 web/content/docs/loop/cloud.mdx              |  50 +++----
 web/content/docs/loop/introduction.mdx       |   8 +-
 web/content/docs/loop/privacy.mdx            |  12 +-
 web/content/docs/loop/quickstart.mdx         |   2 +-
 web/content/docs/loop/search.mdx             |   4 +-
 web/content/docs/loop/sources.mdx            |   4 +-
 web/content/docs/loop/stats.mdx              |   8 +-
 web/content/docs/loop/sync.mdx               |  14 +-
 web/content/docs/loop/teams.mdx              |  49 +++----
 web/lib/product-docs-nav.ts                  |   2 +
 17 files changed, 394 insertions(+), 244 deletions(-)
 create mode 100644 web/content/docs/file/events.mdx
 create mode 100644 web/content/docs/file/self-hosting.mdx

diff --git a/web/content/docs/file/events.mdx b/web/content/docs/file/events.mdx
new file mode 100644
index 00000000..0ae2bd4c
--- /dev/null
+++ b/web/content/docs/file/events.mdx
@@ -0,0 +1,78 @@
+---
+title: 'Events and webhooks'
+description: 'How Relayfile turns per-provider webhooks into one normalized, filesystem-shaped event stream — so your agent reacts to a changed file instead of parsing a raw payload.'
+---
+
+A raw webhook is a diff without context, and every provider fires one differently: different payload shapes, different signature schemes, different retry semantics. Relayfile collapses all of that into a single event model. A provider webhook becomes a **normalized file event** pointing at a canonical path — the same shape whether it came from Linear, GitHub, Notion, or Slack.
+
+## The pipeline
+
+```text
+provider webhook
+  → provider layer verifies + receives        (Nango / Composio / Pipedream)
+  → adapter normalizes payload → canonical path
+  → core server materializes the file, revision++
+  → normalized file event emitted to subscribers
+```
+
+The load-bearing word is **materializes**. Relayfile doesn't forward the webhook — it applies it. By the time the event reaches your agent, the file at `path` already holds current state, and the surrounding context (`by-state/`, related records, the provider's `LAYOUT.md`) is already on disk. The event creates urgency; the materialized tree is what makes acting on it possible without an API call. See [Adapters and providers](/docs/file/adapters-and-providers) for how normalization is implemented per integration.
+
+## The normalized event
+
+Every change — webhook, sync, or another agent's write — surfaces as the same object:
+
+```json
+{
+  "eventId": "evt_01HQ8K7M2YV3R0XW9F4ZB6T2QA",
+  "type": "file.updated",
+  "path": "/linear/issues/AGE-16__87389837-62b1-4e1a-a237-59218bab2974.json",
+  "revision": "rev_42",
+  "provider": "linear",
+  "origin": "provider_sync",
+  "timestamp": "2026-05-13T14:32:01Z"
+}
+```
+
+- **`type`** is one of `file.created`, `file.updated`, `file.deleted`.
+- **`path`** is the canonical file that changed. The path itself carries context — you know which provider and which record without parsing a payload.
+- **`revision`** monotonically increases per file. Use it to order events and to fetch the prior state for a diff.
+- **`origin`** distinguishes `provider_sync` (a webhook or sync from the provider), `agent_write` (another agent wrote the file), and `api` (a direct API write). This is how an agent avoids reacting to its own writes.
+
+## Consuming events
+
+Filter by path glob and event type so an agent only wakes for what it cares about. From the CLI:
+
+```bash
+relayfile listen \
+  --path "/linear/issues/by-state/triage/**" \
+  --event file.created \
+  --run "claude --print 'Triage this: {{path}}'"
+```
+
+Or from the SDK with `onWrite`, which subscribes over the same WebSocket stream and dispatches by pattern:
+
+```typescript
+import { onWrite } from '@relayfile/sdk';
+
+onWrite('/linear/issues/**', async (event) => {
+  if (event.source === 'agent') return; // ignore our own writes
+  await agent.handle(event);
+}, { client, workspaceId, operations: ['create', 'update'] });
+```
+
+See [Agents](/docs/file/agents) for the framework helpers built on this.
+
+## Delivery semantics
+
+- **At-least-once.** Events can repeat. Deduplicate on `eventId`; treat handlers as idempotent.
+- **Ordering.** Per file, `revision` is the source of truth — wall-clock `timestamp` can be close together under bursty traffic.
+- **Catch-up.** A subscriber that connects with a cursor receives the events it missed while disconnected, so a restart doesn't drop changes. If the WebSocket can't open, the SDK degrades to HTTP polling rather than going silent.
+
+<CardGroup cols={2}>
+  <Card title="Real-time sync" href="/docs/file/realtime-sync">
+    How those events fan out to every subscribed agent in sub-second time.
+  </Card>
+  <Card title="Adapters and providers" href="/docs/file/adapters-and-providers">
+    The layer that maps each provider's webhooks and objects into paths.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/introduction.mdx b/web/content/docs/file/introduction.mdx
index ac07b3c5..4a6332d7 100644
--- a/web/content/docs/file/introduction.mdx
+++ b/web/content/docs/file/introduction.mdx
@@ -1,19 +1,55 @@
 ---
 title: 'Relayfile'
-description: 'The event layer for AI agents — normalize SaaS webhooks into a consistent, ACL-scoped file tree your agents read and write with ls, cat, and grep.'
+description: 'When a SaaS event fires, your agent wakes up with the full context already on disk. No API calls, no webhook parsing, no ingestion code.'
 ---
 
-Your SaaS tools are always firing events. A Linear issue is created, a Notion page edited, a GitHub PR opened — and something should react. But every provider fires webhooks differently: different payload shapes, different auth schemes, different retry semantics. Building that normalization for each provider is the plumbing nobody wants to write.
+A page is updated in Notion, a Linear issue changes state, a Hubspot deal is closed and you want your AI agent to react to it in real time proactively. 
 
-Relayfile normalizes webhooks from Linear, Notion, GitHub, Slack, HubSpot, Salesforce, and the rest of your SaaS stack into a consistent, ACL'd file tree, then delivers them to your agents. Agents wake up to a ready filesystem, read what changed, and write back — using `cat`, `grep`, and file-write operations they already know. One integration point. Zero webhook parsing.
 
-LLMs are far better at reading files than calling typed tools — the filesystem is the most-trained-on API in existence. Relayfile leans on that instead of fighting it.
+How do you do that today? In each system you configure webhook notifications and a target address, then wire up provider-specific logic to invoke your agent and react to the payload. Often you also have to call the API for additional data so the agent has everything it needs.
+
+
+What if you could do this with just a few lines of code and your agent wakes with all the context it needs in its filesystem?
+
+Relayfile materializes your full provider state as a file tree and keeps it current with webhooks. When an event fires, `/linear/issues/ENG-123.json` is already there. `/linear/issues/by-state/triage/` is already there. No API calls needed.
+
+
+```bash
+relayfile listen \
+  --path "/linear/issues/by-state/triage/**" \
+  --event file.created \
+  --run "claude --print 'Triage this: {{path}}'"
+```
+
+
+## Connect a provider
+
+<CodeGroup>
+```bash CLI
+relayfile setup --provider linear
+```
+```typescript SDK
+import { RelayfileSetup } from '@relayfile/sdk/cli'
+import { onWrite } from '@relayfile/sdk'
+
+const setup = await RelayfileSetup.login()
+const workspace = await setup.createWorkspace({ name: 'my-workspace' })
+
+const { connectLink } = await workspace.connectIntegration('linear')
+if (connectLink) {
+  console.log('Authorize Linear:', connectLink)
+  await workspace.waitForConnection('linear')
+}
+```
+</CodeGroup>
 
 ## The entire interface
 
-There is no new SDK to learn and no MCP schemas eating your context window — just the bash and file IO an agent already knows.
+The agent can simply read and write back to files to make changes:
 
 ```bash
+$ relayfile mount --local-dir ./mount   # mirror the workspace to disk
+
 $ ls mount/
 github  linear  notion  slack
 
@@ -28,19 +64,6 @@ $ grep -l '"state":"Todo"' mount/linear/issues/*.json
 
 `ls` lists what's there. `cat` reads a record. Writing a JSON file patches it back to the provider. Removing a file deletes the record. The filesystem is the protocol.
 
-## Why files beat tool schemas
-
-A typical MCP setup loads 100+ tool schemas into every agent session before any work happens. Files load nothing — context cost is exactly what the agent opens. An LLM is also more reliable reading a directory than juggling N typed APIs, and `ls` gives you exhaustive enumeration where a tool call returns paginated search results.
-
-There are three reasons the file interface wins, covered in depth on [Why files](/docs/file/why-files):
-
-- **Reactive invocation.** Provider webhooks normalize into file events. Your agent wakes up to the changed file, not a raw payload it has to parse.
-- **Coordination.** Multiple agents working through the same filesystem see each other's writes immediately, scoped by ACL.
-- **Context efficiency.** Files load nothing into context until an agent reads them.
-
-<Note>
-  Relayfile is the file layer of the Agent Relay platform. Where Agent Relay gives agents a [communication layer](/docs/introduction) — messaging, delivery, and actions — Relayfile gives them the integration layer: every connected SaaS tool exposed as files.
-</Note>
 
 ## Where to go next
 
diff --git a/web/content/docs/file/quickstart.mdx b/web/content/docs/file/quickstart.mdx
index b0feb4fa..f5606e1e 100644
--- a/web/content/docs/file/quickstart.mdx
+++ b/web/content/docs/file/quickstart.mdx
@@ -1,11 +1,15 @@
 ---
 title: 'Quickstart'
-description: 'The fastest path to a working Relayfile mount — hosted with one command, or local with Docker — then read and write provider files.'
+description: 'The fastest path to a working Relayfile mount: hosted with one command, then read and write provider files.'
 ---
 
-There are two ways to get a working mount. The **hosted** path runs the integration stack for you — OAuth, sync workers, writeback — so you only run a local mount. The **local OSS** path runs the file server yourself with Docker. Pick whichever fits; both end with provider-backed files in an ordinary directory.
+The fastest path is **hosted**: Agent Relay runs the integration stack for you — OAuth, sync workers, writeback — so you only run a local mount. One command and you have provider-backed files in an ordinary directory.
 
-## Hosted: one command
+<Note>
+  Want to run the whole stack yourself instead? See [Run locally](/docs/file/run-locally) for the self-hosted Docker path. The source lives at [github.com/AgentWorkforce/relayfile](https://github.com/AgentWorkforce/relayfile) — clone it first.
+</Note>
+
+## One command
 
 If you want Notion, Slack, Linear, GitHub, or other provider-backed files without running infrastructure, use Hosted Agent Relay. The CLI logs you in, creates or joins a cloud workspace, completes provider auth, waits for sync, and mounts the result.
 
@@ -28,53 +32,6 @@ cat ./relayfile-mount/LAYOUT.md
 
 See [Relayfile Cloud](/docs/file/cloud) for what the hosted plane manages, and [Mounting](/docs/file/mounting) to do the same thing programmatically from a sandbox.
 
-## Local: Docker stack
-
-The local path runs the file server, the dev token issuer, and a seed step that creates a sample `ws_demo` workspace.
-
-```bash
-cd docker
-docker compose up --build
-```
-
-This starts three services:
-
-| Service | URL | Purpose |
-|---|---|---|
-| relayfile | `http://localhost:9090` | VFS API |
-| relayauth | `http://localhost:9091` | local dev token issuer |
-| seed | exits after setup | creates `ws_demo` sample files |
-
-### Get a token and call the API
-
-The seed step prints a dev token to its logs. Grab it, then hit the tree and file endpoints:
-
-```bash
-TOKEN="$(docker compose logs seed | awk '/token/ {print $NF}' | tail -1)"
-
-curl -H "Authorization: Bearer $TOKEN" \
-  -H "X-Correlation-Id: quickstart-tree" \
-  "http://localhost:9090/v1/workspaces/ws_demo/fs/tree?path=/"
-
-curl -H "Authorization: Bearer $TOKEN" \
-  -H "X-Correlation-Id: quickstart-read" \
-  "http://localhost:9090/v1/workspaces/ws_demo/fs/file?path=/docs/welcome.md"
-```
-
-`X-Correlation-Id` is required on authenticated requests for traceability. The full endpoint surface is in the [API reference](/docs/file/api-reference).
-
-### Mount it as local files
-
-```bash
-cd ..
-RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
-  --base-url http://localhost:9090 \
-  --workspace ws_demo \
-  --local-dir ./relayfile-mount
-```
-
-Now any local tool or agent can use `./relayfile-mount` like a normal directory. See [Run locally](/docs/file/run-locally) for the full daemon flag set, including `--remote-path` to mirror a subtree and `--fuse-content-ttl` to tune the content cache.
-
 ## Read and write
 
 Once mounted, the interface is the filesystem you already know:
diff --git a/web/content/docs/file/self-hosting.mdx b/web/content/docs/file/self-hosting.mdx
new file mode 100644
index 00000000..e749fad9
--- /dev/null
+++ b/web/content/docs/file/self-hosting.mdx
@@ -0,0 +1,47 @@
+---
+title: 'Self-hosting'
+description: 'Run the entire Relayfile stack yourself — core server, adapters, and the provider auth layer — so provider data and OAuth tokens never leave your infrastructure.'
+---
+
+Relayfile is open source end to end. [Relayfile Cloud](/docs/file/cloud) runs it for you, but every layer can run inside your own infrastructure. For teams with data-residency or compliance constraints, this is the path where no provider data and no OAuth token ever leaves your network.
+
+## The stack you run
+
+Self-hosting means running all three layers yourself (see [Adapters and providers](/docs/file/adapters-and-providers) for what each does):
+
+- **Core file server** ([relayfile](https://github.com/AgentWorkforce/relayfile)) — the VFS API, scoped tokens, event ingest, writeback queue, and mount layer.
+- **Adapters** ([relayfile-adapters](https://github.com/AgentWorkforce/relayfile-adapters)) — per-provider webhook-to-path normalization and writeback.
+- **Provider layer** ([relayfile-providers](https://github.com/AgentWorkforce/relayfile-providers)) — auth, token refresh, API proxy, and webhook subscriptions.
+
+Start with [Run locally](/docs/file/run-locally) for the Docker stack, or [Local development](/docs/file/local-development) to run from source. Clone the repo first: [github.com/AgentWorkforce/relayfile](https://github.com/AgentWorkforce/relayfile).
+
+## Self-host the provider layer too
+
+The provider layer is backed by an aggregator — Nango, Composio, or Pipedream — which handles OAuth, token storage, and API proxying. **Nango is itself open source and self-hostable**, so you can run it inside your own network and point the Relayfile provider layer at it. With self-hosted Nango, the OAuth flow, the stored refresh tokens, and every proxied provider API call stay on your infrastructure — there is no third-party hop in the data path.
+
+Point the provider config at your Nango host and secret, and link the workspace to the connection before sync. The connection fields are documented in [Adapters and providers › Bring existing connections](/docs/file/adapters-and-providers).
+
+<Note>
+  Already running Nango, Composio, or Pipedream? You don't need to re-do OAuth. Relayfile can adopt an existing `connectionId` — bring the connection you already have and Relayfile starts routing sync and writeback against it.
+</Note>
+
+## The fully-private deployment
+
+Put together, the self-hosted stack keeps the entire integration path inside your boundary:
+
+```text
+provider webhook → your Nango → your provider layer
+  → your adapters → your relayfile core → your mount
+  → your agent
+```
+
+Nothing in that chain calls out to Agent Relay. This pairs well with self-hosted workflow tools (n8n, your own queue) for teams that want every part of the agent's integration surface under their own control.
+
+<CardGroup cols={2}>
+  <Card title="Run locally" href="/docs/file/run-locally">
+    The Docker stack: file server, dev token issuer, and a seeded sample workspace.
+  </Card>
+  <Card title="Local development" href="/docs/file/local-development">
+    Run the pieces from source with the durable-local backend — no containers.
+  </Card>
+</CardGroup>
diff --git a/web/content/docs/file/why-files.mdx b/web/content/docs/file/why-files.mdx
index 9d43bef9..a4063386 100644
--- a/web/content/docs/file/why-files.mdx
+++ b/web/content/docs/file/why-files.mdx
@@ -1,47 +1,33 @@
 ---
 title: 'Why files'
-description: 'The case for a file interface over typed tool schemas: reactive invocation, multi-agent coordination, and context efficiency.'
+description: 'Most agents are reactive: you call them, they answer, they go dormant. Relayfile makes them proactive by turning provider state into files an agent can watch, read, and write.'
 ---
 
-The "give agents a filesystem" idea is a healthy direction, and Relayfile makes a specific bet: the filesystem is the most-trained-on API in existence, and an LLM is more reliable reading a directory than juggling a dozen typed APIs. Three concrete reasons make files the right substrate for SaaS integrations.
+The full argument lives in the blog post [Just Give the Agent Files](/blog/just-give-the-agent-files). The short version:
 
-## Reactive invocation
+- **MCP lets the agent pull. It is not how the world pushes a signal to the agent.** For push you need webhooks, and making a single agent proactive against Linear means a public endpoint, HMAC verification, a queue, deduplication, and retries. Then repeat per provider. Relayfile does that once and hands the agent a normalized file event instead.
+- **Stacked MCP tools bloat context.** Tool definitions can consume tens of thousands of tokens before any work begins. Files load nothing — context cost is exactly what the agent opens.
+- **The workspace is just files.** Every provider mounts at a well-known path. The agent explores with `ls`, reads with `cat`, searches with `grep` — no per-provider schema to learn.
+- **Writebacks are files too.** The agent writes a file; Relayfile handles provider auth, validation, retries, and the audit trail. No API call from the agent.
+- **Agents coordinate through the filesystem.** Writes propagate to every other agent in sub-second time, scoped by [ACL](/docs/file/acls). When agent A writes, agent B sees it on the next read. No message bus.
 
-Provider webhooks normalize into file events. When a Linear issue is created or a Notion page edited, your agent wakes up to the changed file — no webhook parsing, no provider-specific payload handling, no bespoke adapter per integration. The event is already in a shape the agent can read.
+## The benchmark
 
-This is the structural difference from request/response tool surfaces. A typed tool can only be called; it has no notion of *being woken up* by external state changing. Relayfile inverts that:
+We ran "what did I work on yesterday across GitHub, Linear, and Notion?" head-to-head against MCP, same prompt and accounts, across three Claude models. After adding `by-*` index directories and a pre-computed `digests/yesterday.md`, the filesystem won decisively:
 
-```
-Linear webhook → Cloud sync → /linear/issues/X.json revision++ → change event
-                                                                     ↓
-                                                  agent A reacts, writes a comment
-                                                  agent B reacts, files a Slack ping
-                                                  agent C reacts, opens a PR
-```
+| Model  | MCP cost | Relayfile cost | MCP turns | RF turns |
+| ------ | -------- | -------------- | --------- | -------- |
+| Opus   | $0.44    | $0.25          | 9         | 4        |
+| Sonnet | $0.27    | $0.07          | 18        | 4        |
+| Haiku  | failed¹  | $0.06          | —         | 4        |
 
-The same event fans out to every agent subscribed to that path. This is the substrate that makes **proactive agents** possible — agents reacting to provider state instead of waiting for a user prompt. See [Real-time sync](/docs/file/realtime-sync) for how that fan-out works, and [Agents](/docs/file/agents) for the `onEvent` helper.
+¹ MCP Haiku asked for clarification instead of acting. Relayfile Haiku completed the task.
 
-## Coordination
-
-Multiple agents working through the same filesystem can see each other's writes immediately, scoped by ACL. Multi-agent collaboration becomes a property of the substrate, not something each app re-implements.
-
-When agent A writes a file, agent B sees the new contents on the next read — within a second, no commit, no push, no merge. A reviewer agent can `tail -F` an issue a worker is updating and watch progress live. A persona-orchestrator can watch its workers' writes without a coordination protocol layered on top.
-
-None of that requires anything beyond the filesystem. **The filesystem is the protocol.** Per-agent surfaces are scoped with [ACLs](/docs/file/acls) so each worker sees only the paths it should.
-
-## Context efficiency
-
-A typical MCP setup loads 100+ tool schemas into every agent session before any work happens. Files load nothing — context cost is what the agent actually opens.
-
-- `ls` returns what's there. Exhaustive enumeration beats query-by-query API retrieval, where a tool call returns paginated search results and the agent has to guess at filters.
-- The tool surface is **O(1)** in the number of providers. `listTree` / `readFile` / write operations work identically across `/linear`, `/notion`, `/github`, and every other integration — there is no per-provider schema for the model to learn.
-- Cross-provider composition is free: `grep -r`, `cp`, and `cat` semantics work across providers because they're all just files.
-
-Contrast that with N typed tool servers, where each connected provider adds another batch of schemas to the context window and cross-provider work needs bespoke glue per pair.
+The digest is one file read that replaces 25 individual provider queries. Every structural improvement to the mount makes every future run cheaper — with MCP you are stuck at whatever the API returns. The [full write-up](/blog/just-give-the-agent-files) shows all three rounds, including the naive first pass where files lost.
 
 ## When a typed tool still wins
 
-Files are not always the answer. For a single provider, a single agent, and a one-shot action that needs server-side validation — `linear.create_issue(title, priority, …)` enforcing the shape at call time — a dedicated MCP is simpler and richer. The two compose well: Relayfile for reads, synthesis, and the stateful multi-provider substrate; an MCP for typed one-shot writes. See [Comparison](/docs/file/comparison) for the full breakdown.
+Files are not always the answer. For a single provider, a single agent, and a one-shot action that needs server-side validation, a dedicated MCP that enforces the shape at call time is simpler. The two compose: Relayfile for reads, synthesis, and the multi-provider substrate; an MCP for typed one-shot writes. See [Comparison](/docs/file/comparison).
 
 <CardGroup cols={2}>
   <Card title="Real-time sync" href="/docs/file/realtime-sync">
diff --git a/web/content/docs/loop/cli.mdx b/web/content/docs/loop/cli.mdx
index f4711ce7..369c9539 100644
--- a/web/content/docs/loop/cli.mdx
+++ b/web/content/docs/loop/cli.mdx
@@ -1,11 +1,13 @@
 ---
 title: 'CLI Reference'
-description: 'The full ai-hist command surface: sync, search, recent, show, context, session, stats, watch, and the cloud command group, with flags.'
+description: 'The full ai-hist command surface: sync, search, recent, show, context, session, stats, pack, watch, export/import, tags, and the cloud commands (login, push), with flags.'
 ---
 
-This is the complete `ai-hist` command reference. The CLI is Rust-default — the public `ai-hist` command routes the whole surface through the Rust engine, with the legacy Python CLI available only as an explicit escape hatch (see [Install](/docs/loop/install)). Everything below runs locally against the SQLite database at `~/.local/share/ai-hist/ai-history.db` (override with `AI_HIST_DB`).
+This is the complete `ai-hist` command reference. The CLI is Rust-default — the public `ai-hist` command routes the whole surface through the Rust engine, with the legacy Python CLI available only as an explicit escape hatch (see [Install](/docs/loop/install)). Local commands run against the SQLite database at `~/.local/share/ai-hist/ai-history.db` (override with `AI_HIST_DB`); cloud commands talk to Relayloop Cloud.
 
-## `sync`
+## Local: capture and query
+
+### `sync`
 
 Import all history into the local database. Incremental — only reads new bytes on re-run.
 
@@ -13,27 +15,43 @@ Import all history into the local database. Incremental — only reads new bytes
 ai-hist sync
 ```
 
-Covers Claude Code, Codex, Cursor, OpenCode, Agent Relay (when configured), and trajectories. See [Sync](/docs/loop/sync) and [Sources](/docs/loop/sources).
+Covers Claude Code, Codex, Cursor, Grok, OpenCode, Agent Relay (when configured), and trajectories. See [Sync](/docs/loop/sync) and [Sources](/docs/loop/sources).
+
+### `watch`
+
+Run sync repeatedly on an interval — continuous local sync.
+
+```bash
+ai-hist watch                  # sync every 60s
+ai-hist watch --interval 30    # sync every 30s
+```
+
+| Flag | Effect |
+|------|--------|
+| `--interval <seconds>` | Seconds between syncs (default: 60) |
 
-## `search`
+### `search`
 
 Full-text search across all sources.
 
 ```bash
 ai-hist search "authentication bug"
 ai-hist search "refactor" --source claude --limit 10
-ai-hist search "deploy" --project relay
+ai-hist search --tag relayfile-migration
 ```
 
 | Flag | Effect |
 |------|--------|
-| `--source <name>` | Restrict to one source: `claude`, `codex`, `cursor`, `relay`, `trajectory`, `opencode` |
+| `--source <name>` | Restrict to one source: `claude`, `codex`, `cursor`, `grok`, `relay`, `trajectory`, `opencode` |
 | `--project <path>` | Restrict to a project |
-| `--limit <n>` | Cap the number of results |
+| `--tag <name>` | Restrict to a tagged session |
+| `--limit <n>` | Cap the number of results (default: 20) |
+| `--fts` | Force the FTS index path |
+| `--json` | JSON output |
 
-Results include entry IDs (`#NNN`) used to drill in. See [Search](/docs/loop/search).
+Results include entry IDs used to drill in. See [Search](/docs/loop/search).
 
-## `recent`
+### `recent`
 
 Show the most recent prompts, no query needed.
 
@@ -43,17 +61,18 @@ ai-hist recent 50              # last 50
 ai-hist recent --source claude --project my-app
 ```
 
-Takes an optional count argument and the same `--source` / `--project` filters as `search`.
+Takes an optional count and the same `--source` / `--project` / `--tag` / `--json` filters as `search`.
 
-## `show`
+### `show`
 
 Drill into a specific entry by ID. Prints the full prompt, metadata, session info, and the exact resume command.
 
 ```bash
 ai-hist show 4521
+ai-hist show 4521 --json
 ```
 
-## `context`
+### `context`
 
 Show an entry's surrounding context: same-session entries plus nearby entries in a time window.
 
@@ -62,11 +81,7 @@ ai-hist context 4521
 ai-hist context 4521 --window 15   # ±15 min window (default: 5)
 ```
 
-| Flag | Effect |
-|------|--------|
-| `--window <minutes>` | Width of the nearby-entry time window (default: 5) |
-
-## `session`
+### `session`
 
 View all prompts in a session by session ID.
 
@@ -75,13 +90,9 @@ ai-hist session abc-1234-def
 ai-hist session abc-1234-def --full   # no truncation
 ```
 
-| Flag | Effect |
-|------|--------|
-| `--full` | Show full prompts without truncation |
-
 See [Sessions](/docs/loop/sessions) for `show`, `context`, `session`, and resume commands together.
 
-## `stats`
+### `stats`
 
 Print a database overview: total entries, breakdown by source, date range, and top projects.
 
@@ -89,34 +100,85 @@ Print a database overview: total entries, breakdown by source, date range, and t
 ai-hist stats
 ```
 
-See [Stats](/docs/loop/stats) for the Burn lens.
+See [Stats](/docs/loop/stats).
 
-## `watch`
+### `pack`
 
-Run sync repeatedly on an interval — continuous local sync.
+Build a compact evidence bundle for a query — matching entries plus their resume commands, optionally token-budgeted.
 
 ```bash
-ai-hist watch                  # sync every 60s
-ai-hist watch --interval 30    # sync every 30s
+ai-hist pack "deploy" --limit 10
+ai-hist pack "auth" --tokens 4000 --json
 ```
 
 | Flag | Effect |
 |------|--------|
-| `--interval <seconds>` | Seconds between syncs (default: 60) |
+| `--source` / `--project` / `--tag` | Same scoping as `search` |
+| `--limit <n>` | Max entries (default: 10) |
+| `--tokens <n>` | Truncate prompts to fit a token budget (default: 0 = no limit) |
+| `--json` | JSON output |
+
+### `resume`
+
+Print the resume command for the best-matching session in one step.
+
+```bash
+ai-hist resume "auth middleware refactor"
+```
+
+## Tagging
+
+Tags group sessions for later retrieval. `--tag` then scopes `search`, `recent`, `stats`, and `pack`.
+
+```bash
+ai-hist tag abc-1234-def release-prep        # tag a session (creates the tag if new)
+ai-hist tag abc-1234-def release-prep --color "#ff8800"
+ai-hist untag abc-1234-def release-prep      # remove a tag
+ai-hist tags                                 # list all tags
+ai-hist tags --tag release-prep --sessions   # list sessions under a tag
+```
+
+## Data portability
+
+Local export/import — no cloud required.
+
+```bash
+ai-hist export backup.jsonl                  # JSONL (also .jsonl.gz)
+ai-hist export backup.sqlite --format sqlite
+ai-hist export --since 2026-01-01 --source claude
+ai-hist import backup.jsonl                  # JSONL, .jsonl.gz, or SQLite
+ai-hist import backup.jsonl --dry-run        # preview without writing
+```
+
+## Cloud: login and push
+
+There is no `ai-hist cloud` subcommand group. Cloud is two top-level commands: authenticate once, then push. See [Relayloop Cloud](/docs/loop/cloud).
+
+```bash
+ai-hist login                  # authenticate via Agent Relay Cloud; stores a token in $RELAYHISTORY_HOME
+ai-hist push                   # send new local history to the cloud (incremental, idempotent)
+ai-hist push --json
+ai-hist push --incognito abc-1234-def   # exclude specific sessions from the push (repeatable)
+```
+
+`push` is cursor-based and idempotent — it only sends rows past the last accepted cursor, and the server deduplicates. Your local commands are unaffected.
+
+### `pair check`
+
+Ask your team's shared history for advisory warnings before a risky change. Requires a prior `ai-hist push`.
+
+```bash
+ai-hist pair check --task "refactor auth" --file src/auth/middleware.ts
+ai-hist pair check --file src/db/schema.ts --limit 5 --json
+```
 
-## `cloud`
+### `learn distill`
 
-The opt-in [Relayloop Cloud](/docs/loop/cloud) command group. Local commands keep working unchanged; these add durable backup and cross-device access.
+Distill local session history into structured decision / finding / reflection events.
 
 ```bash
-ai-hist cloud login            # authenticate and set up your encryption key
-ai-hist cloud sync             # encrypt + push new entries since last push
-ai-hist cloud pull             # fetch + decrypt remote entries into the local DB
-ai-hist cloud watch            # continuous push loop
-ai-hist cloud status           # show sync state, entry count, last push
-ai-hist cloud export --output my-history.jsonl.gz   # export all data
-ai-hist cloud delete <id>      # hard-delete a single entry from the cloud
-ai-hist cloud delete-account   # full account deletion
+ai-hist learn distill --source claude --limit 5
+ai-hist learn distill --session_id abc-1234-def --dry_run
 ```
 
 ## Resume commands
@@ -134,9 +196,12 @@ cd /path/to/project && cursor-agent --resume=<session_id>     # Cursor
 | Variable | Purpose |
 |----------|---------|
 | `AI_HIST_DB` | Override the database path |
+| `XDG_DATA_HOME` | Honored before falling back to `~/.local/share/ai-hist/ai-history.db` |
 | `AI_HIST_CLI` | Dispatch mode: `auto` (default), `rust`, `python` |
 | `AI_HIST_RUST_BIN` | Use an explicit Rust binary instead of the default |
+| `RELAYHISTORY_HOME` | Cloud auth + sync-cursor directory (default `~/.agentworkforce/relayhistory-prod`) |
 | `RELAYCAST_API_KEY` / `RELAYCAST_WORKSPACE_ID` | Configure Agent Relay sync |
+| `OPENCODE_DB` | Override the OpenCode SQLite path |
 | `TRAJECTORY_ROOT` | Explicit root for trajectory sync |
 
 <CardGroup cols={2}>
diff --git a/web/content/docs/loop/cloud-architecture.mdx b/web/content/docs/loop/cloud-architecture.mdx
index 4d384a01..93c1df3c 100644
--- a/web/content/docs/loop/cloud-architecture.mdx
+++ b/web/content/docs/loop/cloud-architecture.mdx
@@ -1,61 +1,46 @@
 ---
 title: 'Cloud Architecture'
-description: 'How Relayloop Cloud works end to end: local sync reads files, encrypts them, and POSTs ciphertext over HTTPS to ingestion, storage, and query APIs.'
+description: 'How Relayloop Cloud works: the CLI pushes scrubbed history to a Cloudflare Workers API backed by Neon and pgvector, with an end-to-end-encrypted Enterprise tier.'
 ---
 
-Relayloop Cloud is deliberately thin where it matters. The client does the work — reading, encrypting, and deciding — and the server stores what it is handed. This page traces the path a history entry takes from a local file to the cloud and back, and names the components it passes through. It is grounded in the [relayhistory-cloud architecture](https://github.com/AgentWorkforce/relayhistory-cloud).
+Relayloop Cloud is the hosted convergence store that local history pushes into. The CLI captures and normalizes; the cloud ingests, scrubs, indexes, and serves. This page traces the path an entry takes from a local file to the cloud and names the components it passes through. It is grounded in the [relayhistory-cloud](https://github.com/AgentWorkforce/relayhistory-cloud) source.
 
 ## The path of an entry
 
-The flow is the same shape as local [sync](/docs/loop/sync), with two steps added before the data leaves your machine:
-
-1. **Read** — `ai-hist cloud sync` reads new entries from your local sources, exactly as local sync does.
-2. **Encrypt** — each entry is encrypted on the client. The key never leaves your machine. See [Privacy](/docs/loop/privacy) for the cryptographic detail.
-3. **POST** — the client sends the ciphertext payload to the cloud over HTTPS. Only ciphertext crosses the wire.
-4. **Store** — the cloud ingestion API checks for duplicates and stores the encrypted blobs.
-5. **Query and decrypt** — to read history back, the client (CLI or browser) fetches ciphertext from the query API and decrypts it locally.
-
-The server stores ciphertext blobs plus a small amount of operational metadata. It cannot reconstruct your content.
+1. **Authenticate** — `ai-hist login` exchanges an Agent Relay Cloud session for a scoped token (`rth_at_…`), stored in `$RELAYHISTORY_HOME/auth.json`.
+2. **Push** — `ai-hist push` reads new local rows past the last cursor and `POST`s them to `/v1/ingest` as a batch.
+3. **Scrub** — on the default tier the server scrubs secrets and PII at ingest: API keys and tokens are redacted, home paths are normalized (`/Users/you/…` → `/Users/~/…`), and the stored record is reduced to an allowlist.
+4. **Store and embed** — accepted rows land in the `convergence_events` table with a vector embedding for semantic search. The server deduplicates on batch and event id and advances the cursor only after it accepts the batch.
+5. **Serve** — team features (`pair check`, `learn distill`) and queries read back from that store, scoped to your org and workspace.
 
 ## Components
 
-### Ingestion API
+### API (Cloudflare Workers)
 
-Receives sync payloads from the CLI. It is stateless — the business logic lives in the client. A sync request carries a batch of entries, each with its ciphertext, nonce, authentication tag, and operational metadata. The server checks each entry's content hash against what it has already stored and skips duplicates, then stores the rest. It also exposes a sync-state endpoint that returns only operational metadata — last sync time and entry count, never content.
+The API is a Cloudflare Worker built with the Hono framework and deployed via SST, served at `history.agentrelay.com`. It is stateless request-handling in front of the database. The main route is `POST /v1/ingest`, which takes a batch of records plus the machine identity and sync cursors and returns `{ batchId, received, accepted, cursors }`.
 
-### Storage layer
+### Storage (Neon + pgvector)
 
-Per-row encryption: every stored row is an encrypted blob keyed by a one-way content hash used for deduplication, alongside the nonce, authentication tag, and schema version. No plaintext content is stored anywhere in the database. The server cannot reconstruct user data even with full database access.
+The default tier stores history in **Neon** (managed Postgres) through Drizzle ORM, with the **pgvector** extension providing an HNSW index over 1536-dimension embeddings for semantic search. A `convergence_events` row holds the scrubbed content, task metadata, token/cost fields (`inputTokens`, `outputTokens`, `costUsdMicros`, `model`, `provider`), and the embedding. A `machines` table tracks per-machine sync cursors.
 
 ### Auth service
 
-Handles identity and tenant scoping. Authentication establishes *who you are* and which organization you belong to — it grants no decryption access. Identity and encryption-key custody are deliberately separate concerns: logging in does not unlock content. The auth service also handles team membership and seat counting for billing.
-
-### Query API
-
-Returns the ciphertext blobs the server stored, scoped to the authenticated user and org. The client decrypts locally. It also exposes hard-delete endpoints (for a single entry or a full account) and a streaming export endpoint that hands back all your ciphertext for the client to decrypt and write to a local file.
-
-### Hosted MCP endpoint
-
-Lets you point Claude and other MCP clients at a hosted URL instead of running a local MCP server. This is the one place data is transiently decrypted server-side to fulfill tool calls; it is opt-in and clearly disclosed, and the local MCP server remains the zero-trust default. See [Privacy](/docs/loop/privacy) for the trade-off.
-
-### Web dashboard
-
-A single-page app that does all decryption in the browser. On login it pulls your encrypted entries, unlocks your key locally, decrypts into an in-memory index, and runs search client-side. No decrypted content — not even a search query — is sent back to the server.
+`ai-hist login` rides Agent Relay Cloud's device flow; the cloud verifies the token and derives `{ userId, orgId, workspaceId }`. Sessions are stored as token *hashes* (never plaintext) in `auth_sessions`, with short-lived access tokens and longer-lived refresh tokens. Every query hard-filters by `(orgId, workspaceId, userId, machineId)`, so there is no cross-tenant access.
 
-## What the server can see
+## Trust tiers
 
-The server holds your encrypted blobs plus a thin layer of metadata it needs to operate: your identity and org, your entry count (for billing), each entry's creation timestamp (for sync ordering), and a content hash (for deduplication). The prompt text, project path, session ID, source, and trajectory decisions are all encrypted. The content hash is one-way and reveals only that two entries are duplicates.
+The stack differs by tier. This is the single most important thing to understand about the cloud:
 
-## Where the CLI fits
+- **Default tier — vendor-readable.** Content is stored readable in Neon (after secret/PII scrubbing) so it can power semantic search and the cross-team learning features. It is encrypted in transit and at rest at the infrastructure level, access-controlled, and never used to train models without explicit opt-in.
+- **Enterprise tier — end-to-end encrypted.** For teams whose content cannot leave their boundary, the Enterprise tier stores opaque ciphertext in Cloudflare **D1** (metadata) and **R2** (encrypted blobs), or self-hosts in your own VPC. This tier trades the cross-team flywheel for total privacy.
 
-The cloud commands are additive. `ai-hist cloud login` sets up auth and stores your key in the OS keychain; `ai-hist cloud sync` and `ai-hist cloud watch` push encrypted entries; `ai-hist cloud pull` fetches and decrypts them onto a new machine; `ai-hist cloud export` and `ai-hist cloud delete` give you data portability and deletion. Your local-only commands are untouched.
+See [Privacy](/docs/loop/privacy) for the data-handling model of each tier.
 
 <CardGroup cols={2}>
   <Card title="Privacy" href="/docs/loop/privacy">
-    The encryption model and its honest limits.
+    What is scrubbed, what is readable, and the two trust tiers.
   </Card>
   <Card title="Cloud" href="/docs/loop/cloud">
-    What cloud adds and how to opt in.
+    What pushing to the cloud adds and how to opt in.
   </Card>
 </CardGroup>
diff --git a/web/content/docs/loop/cloud.mdx b/web/content/docs/loop/cloud.mdx
index a272be63..87846426 100644
--- a/web/content/docs/loop/cloud.mdx
+++ b/web/content/docs/loop/cloud.mdx
@@ -1,9 +1,9 @@
 ---
 title: 'Relayloop Cloud'
-description: 'An opt-in sync target that adds durable backup, cross-device access, unified search, team recall, a web UI, and a hosted MCP endpoint.'
+description: 'An opt-in push target that adds durable off-machine backup and team features like pair check, with a web UI and cross-device pull on the roadmap.'
 ---
 
-Relayloop Cloud is a hosted layer on top of the local-first `ai-hist` CLI. The CLI stays exactly as it is — fully functional with no account, working offline. Cloud is an opt-in sync target that adds the things a local SQLite file on one laptop cannot: durable backup, access from every machine, search across your whole team, a web UI, and a hosted MCP endpoint.
+Relayloop Cloud is a hosted layer on top of the local-first `ai-hist` CLI. The CLI stays exactly as it is — fully functional with no account, working offline. Cloud is an opt-in push target that adds what a local SQLite file on one laptop cannot: a durable off-machine copy of your history and team features built on a shared org corpus (today, `pair check`). A web UI, cross-device pull, a hosted MCP endpoint, and the Insights flywheel are on the roadmap.
 
 The core promise is simple, and architectural rather than just policy: your data is yours to store and yours to remove at any time. See [Privacy](/docs/loop/privacy) for the full data-handling model.
 
@@ -13,38 +13,37 @@ A local database is fast and private, but it lives on one disk. The moment you w
 
 <CardGroup cols={2}>
   <Card title="Durable backup">
-    Local files get corrupted or deleted. Cloud history is durable — your record survives a wiped disk or a new machine.
+    Local files get corrupted or deleted. Pushing to the cloud keeps a durable copy of your record off your laptop.
   </Card>
-  <Card title="Cross-device access">
-    Sync history to a new machine instantly and never lose a conversation between devices.
+  <Card title="Team recall">
+    Once your team pushes to the same org, your collective history powers `pair check` — advisory warnings from past work before a risky change.
   </Card>
-  <Card title="Unified search">
-    One place to search across every AI tool you use, from any device.
+  <Card title="Cross-device access (coming soon)">
+    Hydrate a new machine from your cloud history. Today push is one-way (local → cloud); pull is on the roadmap.
   </Card>
-  <Card title="Team recall">
-    Search your teammates' shared sessions so the team never solves the same problem twice.
+  <Card title="Web UI (coming soon)">
+    A dashboard to search, browse sessions, and view Burn stats in the browser — no terminal required.
   </Card>
-  <Card title="Web UI">
-    A dashboard to search, browse sessions, and view stats in the browser — no terminal required.
+  <Card title="Hosted MCP (coming soon)">
+    Point your Claude config at a hosted URL instead of running the local `npx ai-hist-mcp` server.
   </Card>
-  <Card title="Hosted MCP">
-    Point your Claude config at a URL instead of running a local MCP server.
+  <Card title="Insights (coming soon)">
+    Cross-team patterns turned into proactive guidance and repo rules.
   </Card>
 </CardGroup>
 
 ## Opt in from the CLI
 
-Cloud lives under the `ai-hist cloud` command group. Log in once, then push:
+There is no `ai-hist cloud` subcommand. Cloud is two top-level commands: authenticate once, then push.
 
 ```bash
-ai-hist cloud login    # authenticate and set up your encryption key
-ai-hist cloud sync     # encrypt + push new entries since last push
-ai-hist cloud pull     # fetch + decrypt remote entries into the local DB
-ai-hist cloud watch    # continuous push loop, like local watch
-ai-hist cloud status   # show sync state, entry count, last push
+ai-hist login          # authenticate via Agent Relay Cloud; stores a token in $RELAYHISTORY_HOME
+ai-hist push           # send new local history to the cloud (incremental, idempotent)
 ```
 
-Your local commands — `sync`, `search`, `show`, `session`, `stats` — do not change. Cloud sync layers on top of them.
+`push` is cursor-based — it only sends rows past the last accepted cursor, and the server deduplicates, so it is safe to run often (or on a loop alongside `ai-hist watch`). Exclude specific sessions with `--incognito <session_id>`. Your local commands — `sync`, `search`, `show`, `session`, `stats` — do not change.
+
+Once your history is in the cloud, two team features build on it: `ai-hist pair check` surfaces advisory warnings from your team's past work before a risky change, and `ai-hist learn distill` turns sessions into structured decisions and findings. See the [CLI reference](/docs/loop/cli).
 
 ## Local vs. cloud at a glance
 
@@ -53,11 +52,12 @@ Your local commands — `sync`, `search`, `show`, `session`, `stats` — do not
 | Sync, search, show, stats | Yes | Yes |
 | Works offline | Yes | Local CLI still works offline |
 | No account required | Yes | Account required |
-| Durable backup | No (single disk) | Yes |
-| Cross-device access | No | Yes |
-| Web UI | No | Yes |
-| Hosted MCP endpoint | Local MCP server | Hosted endpoint (opt-in) |
-| Team recall / shared sessions | No | Yes ([Teams](/docs/loop/teams)) |
+| Durable off-machine backup | No (single disk) | Yes (via `push`) |
+| Team recall (`pair check`) | No | Yes |
+| Cross-device pull | No | Coming soon |
+| Web UI / Burn dashboard | No | Coming soon |
+| Hosted MCP endpoint | Local (`npx ai-hist-mcp`) | Coming soon |
+| Shared session management / Insights | No | Coming soon ([Teams](/docs/loop/teams)) |
 
 ## The local CLI never breaks
 
diff --git a/web/content/docs/loop/introduction.mdx b/web/content/docs/loop/introduction.mdx
index a71f980c..b61031dc 100644
--- a/web/content/docs/loop/introduction.mdx
+++ b/web/content/docs/loop/introduction.mdx
@@ -24,9 +24,9 @@ Relayloop looks at your agent history through three lenses.
     A searchable history of how your team prompts. Your best engineers' patterns become a living playbook everyone can draw from — find the prompt, the session, and the resume command in seconds.
   </Card>
   <Card title="Burn">
-    Token spend by model, tool, project, and engineer. Find the waste, forecast the cost, and kill runaway loops before they bill you twice.
+    Token spend by model, tool, project, and engineer. Find the waste, forecast the cost, and kill runaway loops before they bill you twice. Cost attribution is captured in [Relayloop Cloud](/docs/loop/cloud).
   </Card>
-  <Card title="Insights">
+  <Card title="Insights (coming soon)">
     Patterns become proactive guidance and repo rules, so your baseline rises every week and your codebase gets steadily more agent-ready.
   </Card>
 </CardGroup>
@@ -35,7 +35,7 @@ Relayloop looks at your agent history through three lenses.
 
 The CLI works completely offline. `ai-hist sync` reads your local agent files, dedupes, and indexes everything into a SQLite database at `~/.local/share/ai-hist/ai-history.db`. Nothing leaves your machine unless you choose to turn on cloud sync.
 
-When you want durable backup, cross-device access, a web UI, and team recall, you opt into [Relayloop Cloud](/docs/loop/cloud). The local CLI does not change and keeps working offline either way.
+When you want a durable off-machine backup and team features, you opt into [Relayloop Cloud](/docs/loop/cloud) with `ai-hist login` and `ai-hist push`. The local CLI does not change and keeps working offline either way.
 
 <Note>
   Relayloop indexes Agent Relay history as one of its sources. If you coordinate agents with [Agent Relay](/docs/introduction), those conversations land in the same searchable corpus as your Claude Code and Codex sessions.
@@ -51,7 +51,7 @@ When you want durable backup, cross-device access, a web UI, and team recall, yo
     Full-text search across every agent session you have ever run.
   </Card>
   <Card title="Cloud" href="/docs/loop/cloud">
-    Opt into durable backup, cross-device sync, and team recall.
+    Push for a durable off-machine backup and team features like `pair check`.
   </Card>
 </CardGroup>
 
diff --git a/web/content/docs/loop/privacy.mdx b/web/content/docs/loop/privacy.mdx
index 518bf29a..b7adf758 100644
--- a/web/content/docs/loop/privacy.mdx
+++ b/web/content/docs/loop/privacy.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Privacy'
-description: 'How Relayloop Cloud handles your data: encrypted in transit and at rest, secrets scrubbed on ingest, end-to-end encryption available, and full data rights.'
+description: 'How Relayloop Cloud handles your data across two trust tiers: a vendor-readable default with secrets scrubbed on ingest, and an end-to-end-encrypted Enterprise tier — plus full export and deletion rights.'
 ---
 
 Relayloop is local-first, so the most private option is always to run the CLI and sync nothing. When you do opt into [Relayloop Cloud](/docs/loop/cloud), the data-handling model is built to be honest about what we can and cannot see — and to give you concrete controls, not just promises. This page describes how data is protected, what is scrubbed, the end-to-end-encrypted option and its real limits, and your rights to export and delete.
@@ -29,6 +29,10 @@ For teams whose IP or compliance rules mean content cannot leave at all, the Ent
 
 ## How end-to-end encryption works
 
+<Note>
+  The end-to-end-encrypted Enterprise tier is in development and offered through enterprise contracts. The design below describes how it is built; the default Team tier is vendor-readable as described above.
+</Note>
+
 On the Enterprise / Private tier, the design principle is that the server stores ciphertext and holds no decryption keys. Even with full database access, neither an attacker nor the platform can read your content.
 
 - **Content encryption** uses AES-256-GCM, with each entry encrypted independently under a fresh nonce. The whole entry — prompt, project path, session ID, source — is encrypted.
@@ -46,7 +50,7 @@ End-to-end encryption is not magic, and the limits deserve to be stated plainly:
 - **JavaScript delivery.** With a web app, the browser executes JavaScript served by the server on every page load. This shifts one trust assumption that the CLI does not have: you trust that the server is delivering the same JS that is in the open source repo. This is mitigated — not eliminated — by Subresource Integrity (the browser refuses JS that does not match a published hash), a strict Content Security Policy, an open-source web client whose build hashes are published, and holding the key only in tab-scoped session storage. For maximum security, use the CLI, where the key lives in the OS keychain and never touches a browser.
 - **Compromised client device.** If your device is compromised, the local key can be extracted. Encryption protects data on our servers, not on a machine an attacker already controls.
 - **Weak passphrase.** A memory-hard KDF slows brute-force of the wrapped key but cannot save a very weak passphrase; minimum entropy is enforced, and the passkey path is preferred where available.
-- **Hosted MCP endpoint.** The [hosted MCP endpoint](/docs/loop/cloud-architecture) is the one place data is transiently decrypted server-side, which requires trusting the server. It is opt-in and clearly disclosed; the local MCP server stays the zero-trust default.
+- **Hosted MCP endpoint (planned).** A hosted MCP endpoint is on the roadmap. It would be the one place data is transiently decrypted server-side, which requires trusting the server — so it will be opt-in and clearly disclosed. The local MCP server (`npx ai-hist-mcp`) stays the zero-trust default.
 
 ## What the server can see
 
@@ -56,8 +60,8 @@ On the end-to-end tier the server holds your ciphertext plus a thin operational
 
 These are commitments backed by mechanics, not just policy. They map to GDPR Articles 15, 17, and 20 and CCPA rights.
 
-- **Delete, immediately and permanently.** Delete a single entry with `ai-hist cloud delete <id>`, or your whole account with `ai-hist cloud delete-account`. Deletes are hard deletes — rows are removed, not flagged — completing synchronously. Nightly backups are retained for 7 days for disaster recovery and disclosed explicitly; after 7 days no copy exists on our infrastructure.
-- **Export, any time, always free.** `ai-hist cloud export --output my-history.jsonl.gz` streams your ciphertext, decrypts it locally, and writes NDJSON in the same format as local `ai-hist export`. It imports straight into a local database with `ai-hist import` — no cloud dependency.
+- **Delete, immediately and permanently.** The cloud API exposes hard deletes — a single entry (`DELETE /v1/entries/<id>`) or your whole account (`DELETE /v1/user`). Rows are removed, not flagged.
+- **Export, any time, always free.** Your local database is always exportable with `ai-hist export` (JSONL, `.jsonl.gz`, or SQLite), and re-importable with `ai-hist import` — no cloud dependency. The cloud also streams your stored records back via `GET /v1/export`.
 - **No training use.** Your data is never used to train any model, ours or anyone's. This is written into the Terms of Service and is not waivable.
 - **No third-party analytics SDKs** in the sync client.
 
diff --git a/web/content/docs/loop/quickstart.mdx b/web/content/docs/loop/quickstart.mdx
index 3694a417..a8865b90 100644
--- a/web/content/docs/loop/quickstart.mdx
+++ b/web/content/docs/loop/quickstart.mdx
@@ -81,6 +81,6 @@ cd /path/to/project && cursor-agent --resume=<session_id>     # Cursor
     The Burn lens: see where your token spend goes.
   </Card>
   <Card title="Cloud" href="/docs/loop/cloud">
-    Add durable backup and team recall when you are ready.
+    Push for a durable backup and team features when you are ready.
   </Card>
 </CardGroup>
diff --git a/web/content/docs/loop/search.mdx b/web/content/docs/loop/search.mdx
index e91e7f2d..f71fabc3 100644
--- a/web/content/docs/loop/search.mdx
+++ b/web/content/docs/loop/search.mdx
@@ -3,7 +3,7 @@ title: 'Search'
 description: 'Full-text search across every agent session with ai-hist search and recent, using entry IDs as the handle to drill deeper.'
 ---
 
-Search is the Recall lens. Once you have [synced](/docs/loop/sync), every prompt you and your team have ever sent to an AI agent is one query away — across Claude Code, Codex, Cursor, OpenCode, Agent Relay, and trajectories at the same time. Search is powered by SQLite FTS5, so it is fast even over tens of thousands of entries.
+Search is the Recall lens. Once you have [synced](/docs/loop/sync), every prompt you and your team have ever sent to an AI agent is one query away — across Claude Code, Codex, Cursor, Grok, OpenCode, Agent Relay, and trajectories at the same time. Search is powered by SQLite FTS5, so it is fast even over tens of thousands of entries.
 
 ## Full-text search
 
@@ -26,7 +26,7 @@ ai-hist search "retry policy" --source trajectory
 ai-hist search "deploy" --project relay
 ```
 
-- `--source` — restrict to one source. Valid values are `claude`, `codex`, `cursor`, `relay`, `trajectory`, and `opencode`. See [Sources](/docs/loop/sources).
+- `--source` — restrict to one source. Valid values are `claude`, `codex`, `cursor`, `grok`, `relay`, `trajectory`, and `opencode`. See [Sources](/docs/loop/sources).
 - `--project` — restrict to a project (matched against the recorded project path).
 - `--limit` — cap the number of results returned.
 
diff --git a/web/content/docs/loop/sources.mdx b/web/content/docs/loop/sources.mdx
index fd0ffe7e..bc96f1de 100644
--- a/web/content/docs/loop/sources.mdx
+++ b/web/content/docs/loop/sources.mdx
@@ -12,6 +12,7 @@ Relayloop's value comes from aggregating history that is otherwise scattered acr
 | Claude Code | `claude` | `~/.claude/history.jsonl` |
 | Codex CLI | `codex` | `~/.codex/history.jsonl` |
 | Cursor | `cursor` | Per-session JSONL under `~/.cursor/projects/...` |
+| Grok | `grok` | Per-session JSONL under `~/.grok/sessions/...` |
 | Agent Relay | `relay` | Relaycast API (`https://api.relaycast.dev/v1`) |
 | Trajectories | `trajectory` | Compacted per-run JSON files |
 | OpenCode | `opencode` | Local SQLite (`~/.local/share/opencode/opencode.db`) |
@@ -26,11 +27,12 @@ ai-hist search "retry policy" --source trajectory
 
 ## File-based sources
 
-**Claude Code, Codex, and Cursor** are synced incrementally from local files using byte-offset tracking, so re-syncing only reads what is new.
+**Claude Code, Codex, Cursor, and Grok** are synced incrementally from local files using byte-offset tracking, so re-syncing only reads what is new.
 
 - **Claude Code** reads `~/.claude/history.jsonl`, using its `display`, `timestamp`, `project`, and `sessionId` fields.
 - **Codex CLI** reads `~/.codex/history.jsonl`, using its `text`, `ts`, and `session_id` fields.
 - **Cursor** reads per-session transcripts at `~/.cursor/projects/<encoded-path>/agent-transcripts/<uuid>/<uuid>.jsonl`. User prompts are extracted from the message content. Because Cursor lines carry no per-line timestamp, the file modification time at sync time is used instead.
+- **Grok** reads per-session chat history at `~/.grok/sessions/<encoded-path>/<session-id>/chat_history.jsonl` alongside its `summary.json`.
 
 **OpenCode** is read from a local SQLite database (`$OPENCODE_DB` or `~/.local/share/opencode/opencode.db`), joining user text parts to their sessions. Reads are WAL-safe so an active OpenCode session is not disrupted.
 
diff --git a/web/content/docs/loop/stats.mdx b/web/content/docs/loop/stats.mdx
index f875f21b..28f37b85 100644
--- a/web/content/docs/loop/stats.mdx
+++ b/web/content/docs/loop/stats.mdx
@@ -35,7 +35,13 @@ You get total entries, a breakdown by source, the date range covered, and your b
 
 ## The Burn lens
 
-Recall tells you *how* your team prompts. Burn tells you what it costs. The same history that makes sessions searchable also makes spend attributable: every entry is tagged with its source (tool), its project, and — once you sync as a team via [Relayloop Cloud](/docs/loop/cloud) — the engineer behind it.
+Recall tells you *how* your team prompts. Burn tells you what it costs.
+
+<Note>
+  Local `ai-hist stats` reports entry counts, sources, date range, and top projects. Cost and token attribution — the Burn lens below — is built on the per-event token and cost fields (`inputTokens`, `outputTokens`, `costUsdMicros`, `model`, `provider`) captured in [Relayloop Cloud](/docs/loop/cloud), not in the local overview.
+</Note>
+
+Once your history is in the cloud, the same record that makes sessions searchable also makes spend attributable: each event carries its source (tool), project, model, and — across a team — the engineer behind it.
 
 That attribution turns an opaque monthly token bill into answers:
 
diff --git a/web/content/docs/loop/sync.mdx b/web/content/docs/loop/sync.mdx
index be4c55fa..d67fe2d1 100644
--- a/web/content/docs/loop/sync.mdx
+++ b/web/content/docs/loop/sync.mdx
@@ -48,22 +48,22 @@ For a fully managed background loop, schedule `ai-hist sync` with your OS schedu
 echo "* * * * * ~/.local/bin/ai-hist sync >> /tmp/ai-hist-sync.log 2>&1" | crontab -
 ```
 
-## Cloud sync
+## Pushing to the cloud
 
-Everything above is local. When you want your history backed up durably and available on every machine, opt into Relayloop Cloud and push with the cloud sync loop:
+Everything above is local. When you want your history in [Relayloop Cloud](/docs/loop/cloud) — for durable backup and team features — authenticate once, then push:
 
 ```bash
-ai-hist cloud sync     # encrypt + push new entries since last push
-ai-hist cloud watch    # continuous push loop, like local watch
+ai-hist login    # authenticate via Agent Relay Cloud
+ai-hist push     # send new local history to the cloud (incremental, idempotent)
 ```
 
-Local sync and cloud sync are independent. The local CLI keeps working offline, and cloud sync layers durable backup and cross-device access on top.
+There is no `ai-hist cloud` subcommand — `push` is the cloud counterpart to local `sync`. It is cursor-based and idempotent, so you can run it as often as you like. Local `sync` and cloud `push` are independent: the local CLI keeps working offline either way.
 
 <CardGroup cols={2}>
   <Card title="Cloud" href="/docs/loop/cloud">
-    What cloud sync adds and how to opt in.
+    What pushing to the cloud adds and how to opt in.
   </Card>
   <Card title="Cloud architecture" href="/docs/loop/cloud-architecture">
-    How local sync reads, encrypts, and pushes to the cloud.
+    The cloud stack and how a pushed entry is stored.
   </Card>
 </CardGroup>
diff --git a/web/content/docs/loop/teams.mdx b/web/content/docs/loop/teams.mdx
index ccf861c4..2857eeee 100644
--- a/web/content/docs/loop/teams.mdx
+++ b/web/content/docs/loop/teams.mdx
@@ -1,59 +1,54 @@
 ---
 title: 'Teams'
-description: 'Shared organizational memory, faster onboarding, knowledge retention, the Insights flywheel that learns across teams, and pricing tiers.'
+description: 'Where Relayloop is headed for teams: shared organizational memory, faster onboarding, the Insights flywheel — and what works today.'
 ---
 
-For an individual, Relayloop is a searchable memory. For a team, it becomes shared organizational memory — and an improvement loop that raises everyone's baseline. The thesis behind [Relayloop](/docs/loop/introduction) is that AI leverage is bimodal: your best engineers get 5–10× from coding agents while most of the team gets 1×, and the difference is prompting skill that today is tribal and undocumented. Team features close that gap and make sure nothing evaporates when people leave.
+For an individual, Relayloop is a searchable memory. For a team, it becomes shared organizational memory — and an improvement loop that raises everyone's baseline. The thesis behind [Relayloop](/docs/loop/introduction) is that AI leverage is bimodal: your best engineers get 5–10× from coding agents while most of the team gets 1×, and the difference is prompting skill that today is tribal and undocumented. Team features close that gap.
 
-## Shared organizational memory
-
-When teammates opt into [cloud](/docs/loop/cloud) sync and share sessions, the team's prompts become a common corpus. Anyone can search how a colleague approached a problem instead of solving it from scratch. Your best engineers' patterns become a living playbook the whole team draws from — the Recall lens, but team-wide.
-
-## Onboarding acceleration
+<Note>
+  **What works today.** Once teammates [push](/docs/loop/cloud) to the same org, history is scoped and visible at the org level, and any session can be excluded from a push with `--incognito`. The richer team features below — shared session management, onboarding flows, roles, and the Insights flywheel — are on the roadmap, not yet shipped.
+</Note>
 
-New hires inherit the team's accumulated AI history on day one. Instead of learning the codebase and the team's prompting style by osmosis, they can search how the team has approached similar work and start from a known-good pattern. The ramp gets shorter and first-try acceptance goes up.
-
-## Knowledge retention
+## Shared organizational memory
 
-When someone leaves, their AI-assisted work history stays with the organization. The sessions, the decisions, and — through trajectory records — the *why* behind them, all remain searchable. Institutional knowledge that used to walk out the door now stays.
+When teammates push their history to the same organization, the team's prompts become a common corpus scoped to your org. The direction is that anyone can search how a colleague approached a problem instead of solving it from scratch — your best engineers' patterns as a living playbook, the Recall lens team-wide.
 
-## The network that learns
+## Onboarding acceleration <span>(coming soon)</span>
 
-The Insights flywheel is what a single-team tool cannot match. Relayloop does not only learn from your team — it learns what works across every team on the platform and feeds the generalized, anonymized lessons back to you.
+New hires inherit the team's accumulated AI history on day one. Instead of learning the codebase and the team's prompting style by osmosis, they search how the team approached similar work and start from a known-good pattern.
 
-> The more teams on Relayloop, the smarter your engineers' agents get.
+## Knowledge retention <span>(coming soon)</span>
 
-Your engineers get the benefit of patterns proven across thousands of others, automatically, without you running the experiments. Cross-team learning is always aggregated and anonymized — one customer never sees another's content — and your data is never used to train models without your explicit opt-in. Patterns turn into proactive guidance and repo rules, so your baseline rises every week and your codebase gets steadily more agent-ready. Teams that need full isolation can run the Enterprise tier end-to-end encrypted or in their own VPC, trading the flywheel for total privacy. See [Privacy](/docs/loop/privacy) for the trust model.
+When someone leaves, their AI-assisted work history stays with the organization. The sessions, the decisions, and — through trajectory records — the *why* behind them remain searchable.
 
-## What to expect
+## The network that learns <span>(coming soon)</span>
 
-- Faster ramp for new and junior engineers.
-- Higher first-try acceptance and less agent rework.
-- Lower, more predictable token spend ([Burn](/docs/loop/stats)).
-- A prompting playbook that improves on its own — and gets better as the network grows.
+The Insights flywheel is the longer-term bet: Relayloop learns what works across every team on the platform and feeds generalized, anonymized lessons back to you. Cross-team learning is always aggregated and anonymized — one customer never sees another's content — and data is never used to train models without explicit opt-in. Teams that need full isolation can run the [Enterprise tier](/docs/loop/privacy) end-to-end encrypted or in their own VPC, trading the flywheel for total privacy.
 
 ## Pricing
 
+Pricing is being finalized. The intended shape:
+
 <CardGroup cols={3}>
   <Card title="Free">
     Local-first, single engineer, up and running in five minutes. The full `ai-hist` CLI with no account.
   </Card>
-  <Card title="Team">
-    From $49/mo for 5 seats. Org dashboard, shared sessions, and team plus network Insights.
+  <Card title="Team (planned)">
+    Org dashboard, shared sessions, and team plus network Insights. Per-seat, pricing TBD.
   </Card>
-  <Card title="Enterprise">
-    Custom. SSO/SAML, end-to-end encryption or self-host/VPC, audit log, and data residency.
+  <Card title="Enterprise (planned)">
+    SSO/SAML, end-to-end encryption or self-host/VPC, audit log, and data residency.
   </Card>
 </CardGroup>
 
-Start free and local. Turn on team sync — and the network — when you are ready.
+Start free and local. Turn on cloud push — and team features as they ship — when you are ready.
 
 <CardGroup cols={2}>
   <Card title="Cloud" href="/docs/loop/cloud">
-    Opt into sync, shared sessions, and the web UI.
+    Opt into push and the team features built on it.
   </Card>
   <Card title="Privacy" href="/docs/loop/privacy">
-    How team data is handled and the trust tiers.
+    How team data is handled and the two trust tiers.
   </Card>
 </CardGroup>
 
diff --git a/web/lib/product-docs-nav.ts b/web/lib/product-docs-nav.ts
index 484a3627..8c1113d2 100644
--- a/web/lib/product-docs-nav.ts
+++ b/web/lib/product-docs-nav.ts
@@ -47,6 +47,7 @@ export const fileSection: ProductDocSection = {
     {
       title: 'Concepts',
       items: [
+        { title: 'Events and webhooks', slug: 'events' },
         { title: 'Mount layout', slug: 'mount-layout' },
         { title: 'Reads and writes', slug: 'reads-and-writes' },
         { title: 'Per-agent ACLs', slug: 'acls' },
@@ -56,6 +57,7 @@ export const fileSection: ProductDocSection = {
     {
       title: 'Running Relayfile',
       items: [
+        { title: 'Self-hosting', slug: 'self-hosting' },
         { title: 'Run locally', slug: 'run-locally' },
         { title: 'Local development', slug: 'local-development' },
         { title: 'Mounting a workspace', slug: 'mounting' },