feat: load docs space from remote Git with bundled fallback

Add docs-loader module that clones github.com/nsheaps/cept scoped to
docs/content/ using the existing cloneRemoteRepo infrastructure.
Cloned content is cached in .cept/docs-cache/ for instant subsequent loads.
When cloning fails (offline, CORS errors), falls back to the bundled
DOCS_PAGES/DOCS_CONTENT constants.

- New docs-loader.ts with loadDocs() and getRemoteDocsSourceUrl()
- App.tsx uses loader on first docs space open
- Sidebar reflects actual repository layout when loaded from remote
- View on GitHub links work with both remote file paths and bundled IDs
- Loading state shown while clone is in progress
- Banner indicates content source (remote, cached, or bundled fallback)

Closes #68

https://claude.ai/code/session_01TF6rYpGkqBWjzNQHgqrVmD

Author: claude

packages/ui/src/components/App.tsx

@@ -12,7 +12,9 @@ import type { SearchResult } from './search/SearchPanel.js';
 import { PageHeader } from './page-header/PageHeader.js';
 import { SettingsModal, DEFAULT_SETTINGS } from './settings/SettingsModal.js';
 import type { CeptSettings, SpaceInfo } from './settings/SettingsModal.js';
-import { DOCS_PAGES, DOCS_CONTENT, DOCS_SPACE_INFO, getDocsSourceUrl, resolveDocsContent } from './docs/docs-content.js';
+import { DOCS_PAGES, DOCS_CONTENT, DOCS_SPACE_INFO, resolveDocsContent } from './docs/docs-content.js';
+import { loadDocs, getRemoteDocsSourceUrl } from './docs/docs-loader.js';
+import type { DocsLoadResult } from './docs/docs-loader.js';
 import {
   useStorage,
   useWorkspacePersistence,
@@ -111,6 +113,10 @@ export function App() {
   const [activeSpace, setActiveSpace] = useState<'user' | 'docs'>('user');
   const [docsSelectedPageId, setDocsSelectedPageId] = useState<string | undefined>('docs-index');
   const [docsPages, setDocsPages] = useState<PageTreeNode[]>(DOCS_PAGES);
+  const [docsContents, setDocsContents] = useState<Record<string, string>>(DOCS_CONTENT);
+  const [docsSource, setDocsSource] = useState<DocsLoadResult['source']>('bundled');
+  const [docsLoading, setDocsLoading] = useState(false);
+  const docsLoadedRef = useRef(false);
   const [importDialogOpen, setImportDialogOpen] = useState(false);
   const [importSource, setImportSource] = useState<ImportSource>('notion');
   const [exportDialogOpen, setExportDialogOpen] = useState(false);
@@ -952,10 +958,32 @@ export function App() {
 
   const handleOpenDocs = useCallback(() => {
     setActiveSpace('docs');
-    setDocsSelectedPageId('docs-index');
-    setDocsPages(DOCS_PAGES);
-    pushRoute({ space: 'docs', pageId: 'docs-index' });
-  }, []);
+    // Select the first page — remote pages use file-path IDs, bundled use 'docs-index'
+    const firstPageId = docsPages.length > 0 ? docsPages[0].id : 'docs-index';
+    setDocsSelectedPageId(firstPageId);
+    pushRoute({ space: 'docs', pageId: firstPageId });
+
+    // Trigger remote load if not loaded yet
+    if (!docsLoadedRef.current && backend instanceof BrowserFsBackend) {
+      docsLoadedRef.current = true;
+      setDocsLoading(true);
+      loadDocs(backend as BrowserFsBackend, false, (msg) => {
+        addToast(msg, 'info');
+      }).then((result) => {
+        setDocsPages(result.pages);
+        setDocsContents(result.pageContents);
+        setDocsSource(result.source);
+        // Select the first page of the loaded docs
+        if (result.pages.length > 0) {
+          setDocsSelectedPageId(result.pages[0].id);
+        }
+      }).catch(() => {
+        // Already falls back to bundled inside loadDocs
+      }).finally(() => {
+        setDocsLoading(false);
+      });
+    }
+  }, [backend, docsPages, addToast]);
 
   /** Handle "Add Space" from the remote repo form in the wizard. */
   const handleAddRemoteRepo = useCallback(async (config: RemoteSpaceConfig) => {
@@ -1208,16 +1236,20 @@ export function App() {
         contentSize,
       });
     }
-    list.push(DOCS_SPACE_INFO);
+    list.push({
+      ...DOCS_SPACE_INFO,
+      pageCount: Object.keys(docsContents).length,
+      contentSize: Object.values(docsContents).reduce((sum, c) => sum + c.length, 0),
+    });
     return list;
-  }, [hasStarted, pages, pageContents, spaceName, spacesManifest, userSpaceId, backend.type, inactiveSpaceStats]);
+  }, [hasStarted, pages, pageContents, spaceName, spacesManifest, userSpaceId, backend.type, inactiveSpaceStats, docsContents]);
 
   /** Known Git hosting domains — only these produce "View on GitHub" links. */
   const KNOWN_GIT_HOSTS = ['github.com', 'gitlab.com', 'bitbucket.org'];
 
   const currentGithubUrl = useMemo((): string | undefined => {
     if (activeSpace === 'docs' && docsSelectedPageId) {
-      return getDocsSourceUrl(docsSelectedPageId) ?? undefined;
+      return getRemoteDocsSourceUrl(docsSelectedPageId, docsSource);
     }
     if (activeSpace !== 'user' || !selectedPageId || !isRemoteSpaceId(userSpaceId)) return undefined;
     const parsed = parseRemoteSpaceId(userSpaceId);
@@ -1227,7 +1259,7 @@ export function App() {
     if (!KNOWN_GIT_HOSTS.includes(host)) return undefined;
     const subPath = parsed.subPath ? `${parsed.subPath}/` : '';
     return `https://${parsed.repo}/blob/${parsed.branch}/${subPath}${selectedPageId}`;
-  }, [activeSpace, docsSelectedPageId, selectedPageId, userSpaceId]);
+  }, [activeSpace, docsSelectedPageId, docsSource, selectedPageId, userSpaceId]);
 
   const commandItems: CommandItem[] = useMemo(() => [
     { id: 'new-page', title: 'New Page', icon: '\u{1F4C4}', category: 'Pages', action: () => handlePageAdd() },
@@ -1363,18 +1395,28 @@ export function App() {
         )}
         <section className="flex-1 min-w-0 p-4 md:p-8 overflow-y-auto">
           {isDocsActive ? (
-            docsSelectedPageId && DOCS_CONTENT[docsSelectedPageId] ? (
+            docsLoading ? (
+              <div className="text-center text-gray-400 mt-20" data-testid="docs-loading">
+                <p>Loading documentation...</p>
+              </div>
+            ) : docsSelectedPageId && docsContents[docsSelectedPageId] ? (
               <>
                 <div className="cept-docs-banner" data-testid="docs-banner">
                   <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5">
                     <rect x="2" y="1" width="12" height="14" rx="1" />
                     <path d="M5 5h6M5 8h6M5 11h3" />
                   </svg>
-                  <span>Read-only &mdash; sourced from docs/ in the Git repository</span>
+                  <span>
+                    Read-only &mdash; {docsSource === 'bundled'
+                      ? 'sourced from bundled docs (offline fallback)'
+                      : docsSource === 'cache'
+                        ? 'sourced from cached Git clone'
+                        : 'sourced from docs/ in the Git repository'}
+                  </span>
                 </div>
                 <CeptEditor
                   key={`docs-${docsSelectedPageId}`}
-                  content={resolveDocsContent(DOCS_CONTENT[docsSelectedPageId])}
+                  content={docsSource === 'bundled' ? resolveDocsContent(docsContents[docsSelectedPageId]) : docsContents[docsSelectedPageId]}
                   placeholder=""
                   onUpdate={() => {/* read-only */}}
                   editable={false}

packages/ui/src/components/docs/docs-loader.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getRemoteDocsSourceUrl } from './docs-loader.js';
+
+// Mock the docs-content module to avoid importing the full bundled content
+vi.mock('./docs-content.js', () => ({
+  DOCS_PAGES: [{ id: 'docs-index', title: 'Test', children: [] }],
+  DOCS_CONTENT: { 'docs-index': '# Test' },
+  resolveDocsContent: (c: string) => c.replace(/\{\{base\}\}/g, '/'),
+  getDocsSourceUrl: (id: string) => {
+    const paths: Record<string, string> = {
+      'docs-index': 'docs/content/index.md',
+      'docs-introduction': 'docs/content/getting-started/introduction.md',
+    };
+    return paths[id] ? `https://github.com/nsheaps/cept/blob/main/${paths[id]}` : undefined;
+  },
+}));
+
+describe('getRemoteDocsSourceUrl', () => {
+  it('returns GitHub URL for bundled page IDs using source path lookup', () => {
+    const url = getRemoteDocsSourceUrl('docs-index', 'bundled');
+    expect(url).toBe('https://github.com/nsheaps/cept/blob/main/docs/content/index.md');
+  });
+
+  it('returns undefined for unknown bundled page IDs', () => {
+    const url = getRemoteDocsSourceUrl('unknown-page', 'bundled');
+    expect(url).toBeUndefined();
+  });
+
+  it('returns GitHub URL for remote page IDs using file path', () => {
+    const url = getRemoteDocsSourceUrl('getting-started/introduction.md', 'remote');
+    expect(url).toBe('https://github.com/nsheaps/cept/blob/main/docs/content/getting-started/introduction.md');
+  });
+
+  it('returns GitHub URL for cached page IDs using file path', () => {
+    const url = getRemoteDocsSourceUrl('reference/roadmap.md', 'cache');
+    expect(url).toBe('https://github.com/nsheaps/cept/blob/main/docs/content/reference/roadmap.md');
+  });
+
+  it('uses custom branch when provided', () => {
+    const url = getRemoteDocsSourceUrl('index.md', 'remote', 'develop');
+    expect(url).toBe('https://github.com/nsheaps/cept/blob/develop/docs/content/index.md');
+  });
+});
+
+describe('loadDocs', () => {
+  it('returns bundled content when backend is null', async () => {
+    // Dynamic import to get loadDocs after mocks are set up
+    const { loadDocs } = await import('./docs-loader.js');
+    const result = await loadDocs(null);
+    expect(result.source).toBe('bundled');
+    expect(result.pages).toHaveLength(1);
+    expect(result.pages[0].id).toBe('docs-index');
+    expect(result.pageContents['docs-index']).toBe('# Test');
+  });
+});

packages/ui/src/components/docs/docs-loader.ts

@@ -0,0 +1,188 @@
+/**
+ * docs-loader — Load documentation from the remote Git repository with
+ * bundled fallback.
+ *
+ * On first load (no cache), attempts to clone `github.com/nsheaps/cept`
+ * scoped to the `docs/content` subdirectory.  Cloned pages and content are
+ * cached in the StorageBackend so subsequent loads are instant.
+ *
+ * When cloning fails (offline, CORS, network issues) the bundled constants
+ * from `docs-content.ts` are used as a fallback.
+ */
+
+import type { PageTreeNode } from '../sidebar/PageTreeItem.js';
+import { BrowserFsBackend } from '@cept/core';
+import type { GitHttp } from '@cept/core';
+import { cloneRemoteRepo } from '../storage/git-space.js';
+import { DOCS_PAGES, DOCS_CONTENT, resolveDocsContent, getDocsSourceUrl } from './docs-content.js';
+
+/** Result of loading docs (from remote or fallback). */
+export interface DocsLoadResult {
+  pages: PageTreeNode[];
+  pageContents: Record<string, string>;
+  /** Where the content came from */
+  source: 'remote' | 'cache' | 'bundled';
+}
+
+const DOCS_REPO_URL = 'github.com/nsheaps/cept';
+const DOCS_BRANCH = 'main';
+const DOCS_SUB_PATH = 'docs/content';
+const CORS_PROXY = 'https://cors.isomorphic-git.org';
+
+/** Storage paths for cached remote docs */
+const CACHE_DIR = '.cept/docs-cache';
+const CACHE_PAGES_FILE = `${CACHE_DIR}/pages.json`;
+const CACHE_CONTENTS_FILE = `${CACHE_DIR}/contents.json`;
+const CACHE_META_FILE = `${CACHE_DIR}/meta.json`;
+
+function encode(value: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(value));
+}
+
+function decode<T>(data: Uint8Array | null): T | null {
+  if (!data) return null;
+  try {
+    return JSON.parse(new TextDecoder().decode(data)) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Read cached docs from the backend, if they exist. */
+async function readCache(backend: BrowserFsBackend): Promise<DocsLoadResult | null> {
+  try {
+    const [pagesData, contentsData, metaData] = await Promise.all([
+      backend.readFile(CACHE_PAGES_FILE),
+      backend.readFile(CACHE_CONTENTS_FILE),
+      backend.readFile(CACHE_META_FILE),
+    ]);
+    if (!pagesData || !contentsData || !metaData) return null;
+    const pages = decode<PageTreeNode[]>(pagesData);
+    const pageContents = decode<Record<string, string>>(contentsData);
+    if (!pages || !pageContents) return null;
+    return { pages, pageContents, source: 'cache' };
+  } catch {
+    return null;
+  }
+}
+
+/** Write cloned docs to the cache. */
+async function writeCache(
+  backend: BrowserFsBackend,
+  pages: PageTreeNode[],
+  pageContents: Record<string, string>,
+): Promise<void> {
+  try {
+    // Ensure cache directory exists
+    const exists = await backend.exists(CACHE_DIR);
+    if (!exists) {
+      await backend.writeFile(`${CACHE_DIR}/.gitkeep`, new Uint8Array(0));
+    }
+    await Promise.all([
+      backend.writeFile(CACHE_PAGES_FILE, encode(pages)),
+      backend.writeFile(CACHE_CONTENTS_FILE, encode(pageContents)),
+      backend.writeFile(CACHE_META_FILE, encode({
+        clonedAt: new Date().toISOString(),
+        repo: DOCS_REPO_URL,
+        branch: DOCS_BRANCH,
+        subPath: DOCS_SUB_PATH,
+      })),
+    ]);
+  } catch {
+    // Cache write failures are non-fatal
+  }
+}
+
+/**
+ * Resolve `{{base}}` placeholders in all page contents.
+ * Remote-cloned docs won't have these, but bundled fallback content does.
+ */
+function resolveAllContent(contents: Record<string, string>): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [id, content] of Object.entries(contents)) {
+    resolved[id] = resolveDocsContent(content);
+  }
+  return resolved;
+}
+
+/**
+ * Load docs: try cache → try remote clone → fall back to bundled.
+ *
+ * @param backend - The BrowserFsBackend (needed for cache and clone)
+ * @param forceRefresh - Skip cache and re-clone from remote
+ * @param onStatus - Optional callback for status messages
+ */
+export async function loadDocs(
+  backend: BrowserFsBackend | null,
+  forceRefresh: boolean = false,
+  onStatus?: (message: string) => void,
+): Promise<DocsLoadResult> {
+  // If no BrowserFsBackend, go straight to bundled fallback
+  if (!backend) {
+    return {
+      pages: DOCS_PAGES,
+      pageContents: resolveAllContent(DOCS_CONTENT),
+      source: 'bundled',
+    };
+  }
+
+  // 1. Try cache (unless force-refreshing)
+  if (!forceRefresh) {
+    const cached = await readCache(backend);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  // 2. Try remote clone
+  onStatus?.('Cloning documentation from GitHub...');
+  try {
+    const httpModule = await import('isomorphic-git/http/web');
+    const gitHttp: GitHttp = httpModule.default as GitHttp;
+
+    const { pages, pageContents } = await cloneRemoteRepo(
+      backend,
+      gitHttp,
+      DOCS_REPO_URL,
+      DOCS_BRANCH,
+      DOCS_SUB_PATH,
+      CORS_PROXY,
+    );
+
+    // Cache the result for next time
+    await writeCache(backend, pages, pageContents);
+
+    onStatus?.('Documentation loaded from GitHub');
+    return { pages, pageContents, source: 'remote' };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    onStatus?.(`Could not load remote docs (${message}), using bundled content`);
+  }
+
+  // 3. Fall back to bundled content
+  return {
+    pages: DOCS_PAGES,
+    pageContents: resolveAllContent(DOCS_CONTENT),
+    source: 'bundled',
+  };
+}
+
+/**
+ * Build a GitHub source URL for a page loaded from the remote clone.
+ *
+ * For remote/cached pages the pageId IS the file path relative to docs/content/
+ * (e.g. "getting-started/introduction.md").
+ *
+ * For bundled pages we fall back to the DOCS_SOURCE_PATHS lookup.
+ */
+export function getRemoteDocsSourceUrl(
+  pageId: string,
+  source: 'remote' | 'cache' | 'bundled',
+  branch: string = DOCS_BRANCH,
+): string | undefined {
+  if (source === 'bundled') {
+    return getDocsSourceUrl(pageId) ?? undefined;
+  }
+  // Remote/cached: pageId is the relative file path within docs/content/
+  return `https://github.com/nsheaps/cept/blob/${branch}/${DOCS_SUB_PATH}/${pageId}`;
+}