create-feltdb 0.4.4 → 0.4.9

package/dist/create.js

@@ -53,15 +53,12 @@ export async function createProject(options) {
             '@feltdb/core': feltdbPackageRange,
         },
         devDependencies: {
-            '@feltdb/cli': feltdbPackageRange,
-            '@feltdb/studio': feltdbPackageRange,
             typescript: '^5.0.0',
             '@types/node': '^20.0.0',
             vite: '^8.2.1',
         },
     };
     if (framework === 'react') {
-        packageJson.dependencies['@feltdb/react'] = feltdbPackageRange;
         packageJson.dependencies['react'] = '^18.0.0';
         packageJson.dependencies['react-dom'] = '^18.0.0';
         packageJson.devDependencies['@types/react'] = '^18.0.0';
@@ -75,7 +72,7 @@ export async function createProject(options) {
     const feltdbConfig = {
         namespace: applicationName,
         runtime,
-        storage: runtime === 'browser' ? 'opfs' : 'durable',
+        storage: runtime === 'browser' ? 'indexeddb' : runtime === 'managed' ? 'managed' : 'durable',
         distributed,
         agents: {
             enabled: hasAgents,
@@ -159,16 +156,165 @@ export async function createProject(options) {
     // Create main application files
     const runtimeOptions = runtime === 'browser'
         ? "{ namespace: '" + applicationName + "', browser: true }"
-        : runtime === 'self-hosted'
-            ? "{ namespace: '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
-            : "{ namespace: '" + applicationName + "', memory: true }";
+        : runtime === 'managed'
+            ? "{ namespace: import.meta.env.VITE_FELTDB_MANAGED_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_MANAGED_URL || import.meta.env.VITE_FELTDB_URL || '', token: import.meta.env.VITE_FELTDB_MANAGED_API_KEY || import.meta.env.VITE_FELTDB_API_KEY || '' } }"
+            : runtime === 'self-hosted'
+                ? "{ namespace: '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
+                : "{ namespace: '" + applicationName + "', memory: true }";
     const feltdbTs = `import { createFeltDB } from '@feltdb/core';
 
 export const db = createFeltDB(${runtimeOptions});
 
 // Collections
-export const documents = db.collection('documents');
-export const reports = db.collection('reports');
+export const projects = db.collection('projects');
+export const tasks = db.collection('tasks');
+export const activity = db.collection('activity');
+
+// Types
+export interface Project {
+  id: string;
+  name: string;
+  description: string;
+  status: 'active' | 'archived' | 'completed';
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, any>;
+}
+
+export interface Task {
+  id: string;
+  projectId: string;
+  title: string;
+  description: string;
+  status: 'todo' | 'in-progress' | 'completed';
+  priority: 'low' | 'medium' | 'high';
+  assignee?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ActivityEvent {
+  id: string;
+  timestamp: string;
+  type: string;
+  entityType: 'project' | 'task';
+  entityId: string;
+  entityName: string;
+  changes?: Record<string, any>;
+  userId?: string;
+}
+
+// Indexes
+projects.createIndex('status');
+tasks.createIndex('projectId');
+tasks.createIndex('status');
+tasks.createIndex('priority');
+activity.createIndex('timestamp');
+
+// Operations
+export async function createProject(data: Omit<Project, 'id' | 'createdAt' | 'updatedAt'>): Promise<Project> {
+  const project: Project = {
+    id: 'proj_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
+    ...data,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  await projects.insert(project);
+  await logActivity({
+    type: 'project_created',
+    entityType: 'project',
+    entityId: project.id,
+    entityName: project.name,
+  });
+  return project;
+}
+
+export async function createTask(data: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>): Promise<Task> {
+  const task: Task = {
+    id: 'task_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
+    ...data,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  await tasks.insert(task);
+  await logActivity({
+    type: 'task_created',
+    entityType: 'task',
+    entityId: task.id,
+    entityName: task.title,
+  });
+  return task;
+}
+
+export async function updateTask(id: string, updates: Partial<Task>): Promise<void> {
+  const task = await tasks.findOne({ id });
+  if (!task) throw new Error('Task not found');
+  
+  const updated = {
+    ...task,
+    ...updates,
+    updatedAt: new Date().toISOString(),
+  };
+  await tasks.update({ id }, updated);
+  await logActivity({
+    type: 'task_updated',
+    entityType: 'task',
+    entityId: id,
+    entityName: updated.title,
+    changes: updates,
+  });
+}
+
+export async function updateProject(id: string, updates: Partial<Project>): Promise<void> {
+  const project = await projects.findOne({ id });
+  if (!project) throw new Error('Project not found');
+  
+  const updated = {
+    ...project,
+    ...updates,
+    updatedAt: new Date().toISOString(),
+  };
+  await projects.update({ id }, updated);
+  await logActivity({
+    type: 'project_updated',
+    entityType: 'project',
+    entityId: id,
+    entityName: updated.name,
+    changes: updates,
+  });
+}
+
+export async function getTasksByProject(projectId: string): Promise<Task[]> {
+  return tasks.find({ projectId }) as Promise<Task[]>;
+}
+
+export async function getRecentActivity(limit = 50): Promise<ActivityEvent[]> {
+  const events = await activity.find({});
+  return (events as ActivityEvent[]).sort((a, b) => 
+    new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+  ).slice(0, limit);
+}
+
+export async function getDashboardStats(): Promise<any> {
+  const allTasks = await tasks.find({});
+  const allProjects = await projects.find({});
+  return {
+    totalProjects: allProjects.length,
+    totalTasks: allTasks.length,
+    completedTasks: (allTasks as Task[]).filter(t => t.status === 'completed').length,
+    inProgressTasks: (allTasks as Task[]).filter(t => t.status === 'in-progress').length,
+    activeTasks: (allTasks as Task[]).filter(t => t.status === 'todo').length,
+  };
+}
+
+async function logActivity(event: Omit<ActivityEvent, 'id' | 'timestamp'>): Promise<void> {
+  const activityEvent: ActivityEvent = {
+    id: 'evt_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
+    timestamp: new Date().toISOString(),
+    ...event,
+  };
+  await activity.insert(activityEvent);
+}
 `;
     fs.writeFileSync(path.join(srcDir, 'feltdb.ts'), feltdbTs);
     // Create a real local-inference agent for browser projects.
@@ -183,12 +329,16 @@ import { db, reports } from '../../src/feltdb';
 export const researcher = db.defineAgent({
   name: 'researcher',
   version: 1,
-  description: 'Analyze documents with private, on-device inference',
+  description: 'Private, on-device AI assistant for document enhancement and analysis',
   capabilities: [
     'document-read',
     'report-write'
   ],
-  goals: ['Summarize documents without sending prompts off-device'],
+  goals: [
+    'Analyze documents privately without sending data off-device',
+    'Generate insights and enhancements locally',
+    'Support document summarization, expansion, and improvement'
+  ],
   constraints: { maxIterations: 1 },
 });
 
@@ -198,20 +348,138 @@ export async function runResearcher(
   prompt: string,
   onProgress?: (message: string) => void,
 ) {
-  provider ??= new WebLLMProvider({
-    onProgress: ({ progress, text }) =>
-      onProgress?.(\`${'${Math.round(progress * 100)}'}% ${'${text}'}\`),
-  });
-  const content = await provider.generate([
-    { role: 'system', content: 'You are a concise research assistant. Keep all reasoning local.' },
-    { role: 'user', content: prompt },
-  ]);
-  await reports.insert({
-    title: prompt.slice(0, 80) || 'Local research',
-    content,
-    createdAt: new Date(),
-  });
-  return content;
+  if (!provider) {
+    provider = new WebLLMProvider({
+      onProgress: ({ progress, text }) => {
+        const pct = Math.round(progress * 100);
+        onProgress?.(\`\${pct}% - \${text}\`);
+      },
+    });
+  }
+
+  try {
+    const systemPrompt = \`You are a helpful AI assistant that operates entirely in the browser.
+You help users:
+- Summarize documents concisely
+- Expand and enhance text with more details
+- Generate ideas and suggestions
+- Improve writing clarity and structure
+- Answer questions about document content
+
+Always be concise and practical. Respect the user's intent.\`;
+
+    const content = await provider.generate([
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: prompt },
+    ]);
+
+    await reports.insert({
+      id: 'report_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
+      title: prompt.slice(0, 80) || 'AI Research Result',
+      content,
+      createdAt: new Date().toISOString(),
+    });
+
+    return content;
+  } catch (error) {
+    throw new Error(error instanceof Error ? error.message : 'Failed to generate response');
+  }
+}
+
+export async function summarizeDocument(
+  title: string,
+  content: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const prompt = \`Summarize this document in 2-3 concise sentences:
+
+Title: \${title}
+
+Content: \${content.substring(0, 2000)}\`;
+
+  return runResearcher(prompt, onProgress);
+}
+
+export async function enhanceDocument(
+  title: string,
+  content: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const prompt = \`Enhance and improve this document by making it more detailed and clearer:
+
+Title: \${title}
+
+Content: \${content}
+
+Provide the enhanced version:\`;
+
+  return runResearcher(prompt, onProgress);
+}
+
+export async function generateIdeas(
+  topic: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const prompt = \`Generate 5 creative ideas related to: \${topic}
+
+Format as a numbered list with brief explanations.\`;
+
+  return runResearcher(prompt, onProgress);
+}
+
+export async function generateFeltDBFeature(
+  featureDescription: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const prompt = \`Generate FeltDB flow syntax for: \${featureDescription}
+
+Include:
+1. Collection definitions with proper types
+2. Capability definitions
+3. Workflow definitions if needed
+4. Policy rules for access control
+
+Format the output as valid FeltDB flow language.\`;
+
+  return runResearcher(prompt, onProgress);
+}
+
+export async function generateReactComponent(
+  componentDescription: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const prompt = \`Generate a React component for: \${componentDescription}
+
+Include:
+1. TypeScript types/interfaces
+2. useState and useEffect hooks
+3. Error handling
+4. Loading states
+5. Proper styling with CSS classes
+
+Export a functional component that can be imported and used.\`;
+
+  return runResearcher(prompt, onProgress);
+}
+
+export async function generateCapability(
+  capabilityName: string,
+  description: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const prompt = \`Generate a FeltDB capability definition for: \${capabilityName}
+
+Description: \${description}
+
+Include:
+1. TypeScript interface definitions
+2. Implementation with proper types
+3. Error handling
+4. Documentation comments
+
+Make it production-ready.\`;
+
+  return runResearcher(prompt, onProgress);
 }
 `;
         fs.writeFileSync(path.join(feltdbDir, 'agents', 'researcher.ts'), agentTs);
@@ -243,24 +511,44 @@ export const capabilities = {
     // Create main application file based on framework
     if (framework === 'react') {
         const agentImport = hasAgents
-            ? "import { runResearcher } from '../feltdb/agents/researcher';"
+            ? "import { runResearcher, summarizeDocument, enhanceDocument, generateIdeas, generateFeltDBFeature, generateReactComponent, generateCapability } from '../feltdb/agents/researcher';"
             : '';
         const agentState = hasAgents
-            ? `  const [prompt, setPrompt] = useState('Summarize why local-first applications are useful.');
+            ? `  const [prompt, setPrompt] = useState('');
   const [answer, setAnswer] = useState('');
   const [modelStatus, setModelStatus] = useState('Model not loaded');
-  const [generating, setGenerating] = useState(false);`
+  const [generating, setGenerating] = useState(false);
+  const [selectedDoc, setSelectedDoc] = useState<any | null>(null);
+  const [aiMode, setAiMode] = useState<'custom' | 'summarize' | 'enhance' | 'ideas' | 'feltdb' | 'react' | 'capability'>('custom');`
             : '';
         const agentHandler = hasAgents
             ? `
-  const handleResearch = async () => {
+  const handleRunAI = async (mode: 'custom' | 'summarize' | 'enhance' | 'ideas' | 'feltdb' | 'react' | 'capability') => {
     setGenerating(true);
     setAnswer('');
+    setModelStatus('Running inference...');
+
     try {
-      setAnswer(await runResearcher(prompt, setModelStatus));
-      setModelStatus('Ready — inference stayed in this browser');
+      let result = '';
+      if (mode === 'custom') {
+        result = await runResearcher(prompt, setModelStatus);
+      } else if (mode === 'summarize' && selectedDoc) {
+        result = await summarizeDocument(selectedDoc.title, selectedDoc.content, setModelStatus);
+      } else if (mode === 'enhance' && selectedDoc) {
+        result = await enhanceDocument(selectedDoc.title, selectedDoc.content, setModelStatus);
+      } else if (mode === 'ideas') {
+        result = await generateIdeas(prompt, setModelStatus);
+      } else if (mode === 'feltdb') {
+        result = await generateFeltDBFeature(prompt, setModelStatus);
+      } else if (mode === 'react') {
+        result = await generateReactComponent(prompt, setModelStatus);
+      } else if (mode === 'capability') {
+        result = await generateCapability('Feature', prompt, setModelStatus);
+      }
+      setAnswer(result);
+      setModelStatus('✓ Ready — all processing done locally');
     } catch (error) {
-      setModelStatus(error instanceof Error ? error.message : String(error));
+      setModelStatus('✗ Error: ' + (error instanceof Error ? error.message : String(error)));
     } finally {
       setGenerating(false);
     }
@@ -270,228 +558,551 @@ export const capabilities = {
         const agentMarkup = hasAgents
             ? `
         <section className="researcher">
-          <h2>Private WebLLM Researcher</h2>
-          <p>{modelStatus}</p>
-          <textarea value={prompt} onChange={event => setPrompt(event.target.value)} rows={4} />
-          <button onClick={handleResearch} disabled={generating || !prompt.trim()}>
-            {generating ? 'Running locally…' : 'Run researcher'}
+          <h2>🤖 AI Assistant (Private, Local)</h2>
+          <div className="status-badge">{modelStatus}</div>
+
+          <div className="ai-modes">
+            <div className="mode-group">
+              <span className="mode-group-label">📝 Content</span>
+              <button
+                className={\`mode-btn \${aiMode === 'custom' ? 'active' : ''}\`}
+                onClick={() => setAiMode('custom')}
+              >
+                ✍️ Custom
+              </button>
+              <button
+                className={\`mode-btn \${aiMode === 'summarize' ? 'active' : ''}\`}
+                onClick={() => setAiMode('summarize')}
+                disabled={!selectedDoc}
+              >
+                📄 Summarize
+              </button>
+              <button
+                className={\`mode-btn \${aiMode === 'enhance' ? 'active' : ''}\`}
+                onClick={() => setAiMode('enhance')}
+                disabled={!selectedDoc}
+              >
+                ✨ Enhance
+              </button>
+              <button
+                className={\`mode-btn \${aiMode === 'ideas' ? 'active' : ''}\`}
+                onClick={() => setAiMode('ideas')}
+              >
+                💡 Ideas
+              </button>
+            </div>
+
+            <div className="mode-group">
+              <span className="mode-group-label">💻 Code Gen</span>
+              <button
+                className={\`mode-btn code-mode \${aiMode === 'feltdb' ? 'active' : ''}\`}
+                onClick={() => setAiMode('feltdb')}
+              >
+                ⚙️ FeltDB Flow
+              </button>
+              <button
+                className={\`mode-btn code-mode \${aiMode === 'react' ? 'active' : ''}\`}
+                onClick={() => setAiMode('react')}
+              >
+                ⚛️ React
+              </button>
+              <button
+                className={\`mode-btn code-mode \${aiMode === 'capability' ? 'active' : ''}\`}
+                onClick={() => setAiMode('capability')}
+              >
+                🔧 Capability
+              </button>
+            </div>
+          </div>
+
+          {aiMode === 'summarize' || aiMode === 'enhance' ? (
+            <div className="doc-selector">
+              <label>Select a document:</label>
+              <select
+                value={selectedDoc?.id || ''}
+                onChange={(e) => {
+                  const doc = docs.find((d: any) => d.id === e.target.value);
+                  setSelectedDoc(doc || null);
+                }}
+              >
+                <option value="">Choose a document...</option>
+                {docs.map((doc: any) => (
+                  <option key={doc.id} value={doc.id}>
+                    {doc.title}
+                  </option>
+                ))}
+              </select>
+            </div>
+          ) : (
+            <textarea
+              value={prompt}
+              onChange={(event) => setPrompt(event.target.value)}
+              placeholder={
+                aiMode === 'ideas' ? 'What topic do you want ideas for?' :
+                aiMode === 'feltdb' ? 'Describe the FeltDB feature you want to create...' :
+                aiMode === 'react' ? 'Describe the React component you need...' :
+                aiMode === 'capability' ? 'Describe the capability implementation...' :
+                'Enter your prompt...'
+              }
+              rows={5}
+            />
+          )}
+
+          <button
+            onClick={() => handleRunAI(aiMode)}
+            disabled={
+              generating ||
+              (aiMode === 'custom' && !prompt.trim()) ||
+              ((aiMode === 'summarize' || aiMode === 'enhance') && !selectedDoc) ||
+              ((aiMode === 'ideas' || aiMode === 'feltdb' || aiMode === 'react' || aiMode === 'capability') && !prompt.trim())
+            }
+            className="research-btn"
+          >
+            {generating ? '⏳ Running locally…' : '🚀 Generate'}
           </button>
-          {answer && <article><h3>Result</h3><p>{answer}</p></article>}
+
+          {answer && (
+            <article className="research-result">
+              <h3>Generated Output</h3>
+              <div className="result-content">{answer}</div>
+              <div className="result-actions">
+                {aiMode === 'custom' || aiMode === 'enhance' || aiMode === 'ideas' ? (
+                  <button
+                    onClick={() => {
+                      const title = aiMode === 'ideas' ? prompt : (selectedDoc?.title || 'AI Generated');
+                      documents.insert({
+                        id: 'doc_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
+                        title: title + ' (AI Enhanced)',
+                        content: answer,
+                        createdAt: new Date().toISOString(),
+                      });
+                      loadDocs();
+                      setAnswer('');
+                    }}
+                    className="save-result-btn"
+                  >
+                    💾 Save to Documents
+                  </button>
+                ) : (
+                  <>
+                    <button
+                      onClick={() => {
+                        const filename = aiMode === 'feltdb' ? 'feature.flow' :
+                                       aiMode === 'react' ? 'Component.tsx' :
+                                       'capability.ts';
+                        const blob = new Blob([answer], { type: 'text/plain' });
+                        const url = URL.createObjectURL(blob);
+                        const a = document.createElement('a');
+                        a.href = url;
+                        a.download = filename;
+                        a.click();
+                        URL.revokeObjectURL(url);
+                      }}
+                      className="save-result-btn"
+                    >
+                      📥 Download Code
+                    </button>
+                    <button
+                      onClick={() => {
+                        navigator.clipboard.writeText(answer);
+                        alert('Code copied to clipboard!');
+                      }}
+                      className="copy-result-btn"
+                    >
+                      📋 Copy Code
+                    </button>
+                  </>
+                )}
+              </div>
+              <p className="code-note">
+                💡 Tip: Generated code can be downloaded, copied, or saved to documents for later reference.
+              </p>
+            </article>
+          )}
         </section>`
             : '';
         const appTsx = `import React, { useState, useEffect } from 'react';
-import { db, documents } from './feltdb';
-${agentImport}
+import { useCollection } from '@feltdb/core/react';
+import {
+  projects,
+  tasks,
+  activity,
+  createProject,
+  createTask,
+  updateTask,
+  getDashboardStats,
+} from './feltdb';
+
+type View = 'dashboard' | 'projects' | 'tasks' | 'activity' | 'inspector';
 
 export function App() {
-  const [docs, setDocs] = useState<any[]>([]);
-  const [loading, setLoading] = useState(true);
-${agentState}
+  const [currentView, setCurrentView] = useState<View>('dashboard');
+  const [selectedProjectId, setSelectedProjectId] = useState<string>('');
+  const [dashboardStats, setDashboardStats] = useState<any>(null);
+  const [newProjectName, setNewProjectName] = useState('');
+  const [newTaskTitle, setNewTaskTitle] = useState('');
+  const [newTaskProject, setNewTaskProject] = useState('');
+
+  const { data: projectsList } = useCollection(projects);
+  const { data: tasksList } = useCollection(tasks);
+  const { data: activityList } = useCollection(activity);
 
   useEffect(() => {
-    const loadDocs = async () => {
-      try {
-        const allDocs = await documents.find({});
-        setDocs(allDocs);
-      } catch (err) {
-        console.error('Error loading documents:', err);
-      } finally {
-        setLoading(false);
-      }
-    };
+    getDashboardStats().then(setDashboardStats);
+  }, [projectsList, tasksList]);
 
-    loadDocs();
-  }, []);
+  const handleCreateProject = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!newProjectName.trim()) return;
+    await createProject({
+      name: newProjectName,
+      description: 'Created via Workspace',
+      status: 'active',
+      metadata: {},
+    });
+    setNewProjectName('');
+  };
 
-  const handleAddDocument = async () => {
-    try {
-      await documents.insert({
-        title: 'New Document',
-        content: 'Enter content here',
-        createdAt: new Date(),
-      });
-      // Reload documents
-      const allDocs = await documents.find({});
-      setDocs(allDocs);
-    } catch (err) {
-      console.error('Error adding document:', err);
-    }
+  const handleCreateTask = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!newTaskTitle.trim() || !newTaskProject) return;
+    await createTask({
+      projectId: newTaskProject,
+      title: newTaskTitle,
+      description: '',
+      status: 'todo',
+      priority: 'medium',
+    });
+    setNewTaskTitle('');
+  };
+
+  const containerStyle: React.CSSProperties = {
+    display: 'flex',
+    minHeight: '100vh',
+    fontFamily: 'system-ui, sans-serif',
+    backgroundColor: '#f5f7fa',
+  };
+
+  const sidebarStyle: React.CSSProperties = {
+    width: '240px',
+    backgroundColor: '#1e293b',
+    color: '#e2e8f0',
+    padding: '20px',
+    borderRight: '1px solid #334155',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '20px',
+  };
+
+  const mainStyle: React.CSSProperties = {
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+  };
+
+  const headerStyle: React.CSSProperties = {
+    backgroundColor: '#fff',
+    borderBottom: '1px solid #e2e8f0',
+    padding: '20px',
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  };
+
+  const contentStyle: React.CSSProperties = {
+    flex: 1,
+    padding: '20px',
+    overflowY: 'auto',
+  };
+
+  const titleStyle: React.CSSProperties = {
+    fontSize: '24px',
+    fontWeight: 'bold',
+    color: '#1e293b',
+  };
+
+  const navItemStyle = (active: boolean): React.CSSProperties => ({
+    padding: '10px 12px',
+    borderRadius: '6px',
+    cursor: 'pointer',
+    backgroundColor: active ? '#334155' : 'transparent',
+    color: active ? '#fff' : '#cbd5e1',
+    border: 'none',
+    textAlign: 'left',
+    width: '100%',
+    fontSize: '14px',
+  });
+
+  const statsStyle: React.CSSProperties = {
+    display: 'grid',
+    gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
+    gap: '16px',
+    marginBottom: '24px',
+  };
+
+  const statCardStyle: React.CSSProperties = {
+    backgroundColor: '#fff',
+    padding: '16px',
+    borderRadius: '8px',
+    border: '1px solid #e2e8f0',
+  };
+
+  const formStyle: React.CSSProperties = {
+    display: 'flex',
+    gap: '8px',
+    marginBottom: '20px',
+  };
+
+  const inputStyle: React.CSSProperties = {
+    flex: 1,
+    padding: '8px 12px',
+    border: '1px solid #cbd5e1',
+    borderRadius: '6px',
+    fontSize: '14px',
+  };
+
+  const buttonStyle: React.CSSProperties = {
+    padding: '8px 16px',
+    backgroundColor: '#0284c7',
+    color: '#fff',
+    border: 'none',
+    borderRadius: '6px',
+    cursor: 'pointer',
+    fontSize: '14px',
+  };
+
+  const itemStyle: React.CSSProperties = {
+    backgroundColor: '#fff',
+    padding: '12px',
+    borderRadius: '6px',
+    marginBottom: '8px',
+    border: '1px solid #e2e8f0',
   };
-${agentHandler}
 
   return (
-    <div className="app">
-      <header>
-        <h1>🌊 FeltDB Research App</h1>
-        <p>Distributed document management with agents and capabilities</p>
-      </header>
-
-      <main>
-        <section className="stats">
-          <div className="stat">
-            <span className="label">Documents:</span>
-            <span className="value">{docs.length}</span>
-          </div>
-          <div className="stat">
-            <span className="label">Runtime:</span>
-            <span className="value">${runtime}</span>
-          </div>
-          <div className="stat">
-            <span className="label">Distributed:</span>
-            <span className="value">${distributed ? '✓' : '✗'}</span>
+    <div style={containerStyle}>
+      <div style={sidebarStyle}>
+        <div style={{ fontSize: '16px', fontWeight: 'bold' }}>⚡ FeltDB Workspace</div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
+          <button
+            style={navItemStyle(currentView === 'dashboard')}
+            onClick={() => setCurrentView('dashboard')}
+          >
+            📊 Dashboard
+          </button>
+          <button
+            style={navItemStyle(currentView === 'projects')}
+            onClick={() => setCurrentView('projects')}
+          >
+            📁 Projects
+          </button>
+          <button
+            style={navItemStyle(currentView === 'tasks')}
+            onClick={() => setCurrentView('tasks')}
+          >
+            ✅ Tasks
+          </button>
+          <button
+            style={navItemStyle(currentView === 'activity')}
+            onClick={() => setCurrentView('activity')}
+          >
+            📝 Activity
+          </button>
+          <button
+            style={navItemStyle(currentView === 'inspector')}
+            onClick={() => setCurrentView('inspector')}
+          >
+            🔍 Inspector
+          </button>
+        </div>
+        <div style={{ marginTop: 'auto', fontSize: '12px', color: '#64748b' }}>
+          {projectsList.length} projects • {tasksList.length} tasks
+        </div>
+      </div>
+
+      <div style={mainStyle}>
+        <div style={headerStyle}>
+          <div style={titleStyle}>
+            {currentView === 'dashboard' && '📊 Dashboard'}
+            {currentView === 'projects' && '📁 Projects'}
+            {currentView === 'tasks' && '✅ Tasks'}
+            {currentView === 'activity' && '📝 Activity'}
+            {currentView === 'inspector' && '🔍 Data Inspector'}
           </div>
-        </section>
-
-        <section className="documents">
-          <h2>Documents</h2>
-          {loading ? (
-            <p>Loading...</p>
-          ) : docs.length === 0 ? (
-            <p>No documents yet</p>
-          ) : (
-            <ul>
-              {docs.map((doc: any) => (
-                <li key={doc.id}>
-                  <h3>{doc.title}</h3>
-                  <p>{doc.content}</p>
-                </li>
-              ))}
-            </ul>
+        </div>
+
+        <div style={contentStyle}>
+          {currentView === 'dashboard' && (
+            <div>
+              <div style={statsStyle}>
+                <div style={statCardStyle}>
+                  <div style={{ fontSize: '12px', color: '#64748b' }}>Projects</div>
+                  <div style={{ fontSize: '28px', fontWeight: 'bold' }}>{projectsList.length}</div>
+                </div>
+                <div style={statCardStyle}>
+                  <div style={{ fontSize: '12px', color: '#64748b' }}>Tasks</div>
+                  <div style={{ fontSize: '28px', fontWeight: 'bold' }}>{tasksList.length}</div>
+                </div>
+                <div style={statCardStyle}>
+                  <div style={{ fontSize: '12px', color: '#64748b' }}>Activity Events</div>
+                  <div style={{ fontSize: '28px', fontWeight: 'bold' }}>{activityList.length}</div>
+                </div>
+              </div>
+              <h3>Welcome to FeltDB Workspace!</h3>
+              <p style={{ color: '#64748b', lineHeight: '1.6' }}>
+                This application demonstrates core FeltDB capabilities:<br/>
+                ✅ Collections and relationships (Projects → Tasks)<br/>
+                ✅ Indexed querying for efficient lookups<br/>
+                ✅ Activity logs for audit trails<br/>
+                ✅ Local-first persistence with IndexedDB<br/>
+                ✅ Reactive updates using React hooks<br/>
+                <br/>
+                Create a project to get started! 👇
+              </p>
+            </div>
           )}
-          <button onClick={handleAddDocument}>Add Document</button>
-        </section>
-${agentMarkup}
-      </main>
-
-      <style>{\`
-        body {
-          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
-          margin: 0;
-          padding: 0;
-          background: #f5f5f5;
-        }
-
-        .app {
-          max-width: 1200px;
-          margin: 0 auto;
-          padding: 20px;
-        }
-
-        header {
-          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-          color: white;
-          padding: 30px;
-          border-radius: 8px;
-          margin-bottom: 30px;
-        }
-
-        header h1 {
-          margin: 0 0 10px 0;
-          font-size: 28px;
-        }
-
-        header p {
-          margin: 0;
-          opacity: 0.9;
-        }
-
-        main {
-          background: white;
-          padding: 20px;
-          border-radius: 8px;
-          box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-        }
-
-        .stats {
-          display: grid;
-          grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-          gap: 20px;
-          margin-bottom: 30px;
-        }
-
-        .stat {
-          padding: 15px;
-          background: #f9f9f9;
-          border-radius: 4px;
-          border-left: 3px solid #667eea;
-        }
-
-        .stat .label {
-          display: block;
-          color: #666;
-          font-size: 12px;
-          text-transform: uppercase;
-          margin-bottom: 5px;
-        }
-
-        .stat .value {
-          display: block;
-          font-size: 24px;
-          font-weight: bold;
-          color: #333;
-        }
-
-        .documents h2 {
-          margin-top: 0;
-        }
-
-        .documents ul {
-          list-style: none;
-          padding: 0;
-          margin: 0 0 20px 0;
-        }
-
-        .documents li {
-          padding: 15px;
-          background: #f9f9f9;
-          border-radius: 4px;
-          margin-bottom: 10px;
-        }
-
-        .documents h3 {
-          margin: 0 0 10px 0;
-          color: #333;
-        }
-
-        .documents p {
-          margin: 0;
-          color: #666;
-          font-size: 14px;
-        }
-
-        button {
-          background: #667eea;
-          color: white;
-          border: none;
-          padding: 10px 20px;
-          border-radius: 4px;
-          cursor: pointer;
-          font-size: 14px;
-          font-weight: 500;
-        }
-
-        button:hover {
-          background: #5568d3;
-        }
-
-        textarea {
-          box-sizing: border-box;
-          display: block;
-          margin: 12px 0;
-          padding: 10px;
-          width: 100%;
-        }
-
-        .researcher {
-          border-top: 1px solid #eee;
-          margin-top: 30px;
-          padding-top: 20px;
-        }
-      \`}</style>
+
+          {currentView === 'projects' && (
+            <div>
+              <form style={formStyle} onSubmit={handleCreateProject}>
+                <input
+                  style={inputStyle}
+                  type="text"
+                  placeholder="New project name..."
+                  value={newProjectName}
+                  onChange={(e) => setNewProjectName(e.target.value)}
+                />
+                <button style={buttonStyle} type="submit">Create</button>
+              </form>
+              <div>
+                {projectsList.map((p: any) => (
+                  <div key={p.id} style={itemStyle}>
+                    <div style={{ fontWeight: 'bold' }}>{p.name}</div>
+                    {p.description && (
+                      <div style={{ fontSize: '14px', color: '#64748b', margin: '4px 0' }}>
+                        {p.description}
+                      </div>
+                    )}
+                    <div style={{ fontSize: '12px', color: '#0284c7', marginTop: '4px' }}>
+                      Status: {p.status}
+                    </div>
+                  </div>
+                ))}
+                {projectsList.length === 0 && (
+                  <p style={{ color: '#64748b' }}>No projects yet. Create one above!</p>
+                )}
+              </div>
+            </div>
+          )}
+
+          {currentView === 'tasks' && (
+            <div>
+              <form style={formStyle} onSubmit={handleCreateTask}>
+                <select
+                  style={inputStyle}
+                  value={newTaskProject}
+                  onChange={(e) => setNewTaskProject(e.target.value)}
+                >
+                  <option value="">Select a project...</option>
+                  {projectsList.map((p: any) => (
+                    <option key={p.id} value={p.id}>{p.name}</option>
+                  ))}
+                </select>
+                <input
+                  style={inputStyle}
+                  type="text"
+                  placeholder="Task title..."
+                  value={newTaskTitle}
+                  onChange={(e) => setNewTaskTitle(e.target.value)}
+                />
+                <button style={buttonStyle} type="submit">Create</button>
+              </form>
+              <div>
+                {tasksList.map((t: any) => (
+                  <div key={t.id} style={itemStyle}>
+                    <div style={{ fontWeight: 'bold' }}>{t.title}</div>
+                    {t.description && (
+                      <div style={{ fontSize: '14px', color: '#64748b', margin: '4px 0' }}>
+                        {t.description}
+                      </div>
+                    )}
+                    <div style={{ fontSize: '12px', color: '#64748b', marginTop: '4px' }}>
+                      Priority: <strong>{t.priority}</strong> | Status: <strong>{t.status}</strong>
+                    </div>
+                  </div>
+                ))}
+                {tasksList.length === 0 && (
+                  <p style={{ color: '#64748b' }}>No tasks yet. Create one above!</p>
+                )}
+              </div>
+            </div>
+          )}
+
+          {currentView === 'activity' && (
+            <div>
+              {activityList.length === 0 ? (
+                <p style={{ color: '#64748b' }}>No activity yet</p>
+              ) : (
+                <div>
+                  {activityList.slice(-30).map((event: any, idx: number) => (
+                    <div key={idx} style={itemStyle}>
+                      <div style={{ fontSize: '12px', color: '#64748b' }}>
+                        {new Date(event.timestamp).toLocaleString()}
+                      </div>
+                      <div style={{ fontWeight: 'bold' }}>{event.type}</div>
+                      {event.entityName && (
+                        <div style={{ fontSize: '14px', marginTop: '4px' }}>
+                          {event.entityName}
+                        </div>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+
+          {currentView === 'inspector' && (
+            <div>
+              <h3>Data Inspector</h3>
+              <p style={{ color: '#64748b', marginBottom: '16px' }}>
+                Developer panel showing FeltDB internals
+              </p>
+              <div style={statCardStyle}>
+                <div style={{ fontWeight: 'bold', marginBottom: '8px' }}>Collections</div>
+                <div style={{ fontSize: '14px', color: '#64748b', lineHeight: '1.6' }}>
+                  📦 projects: {projectsList.length} records<br/>
+                  📦 tasks: {tasksList.length} records<br/>
+                  📦 activity: {activityList.length} events<br/>
+                </div>
+              </div>
+              <div style={statCardStyle}>
+                <div style={{ fontWeight: 'bold', marginBottom: '8px' }}>Storage</div>
+                <div style={{ fontSize: '14px', color: '#64748b', lineHeight: '1.6' }}>
+                  💾 Type: IndexedDB<br/>
+                  🔑 Namespace: FeltDB<br/>
+                  🔄 Sync: Automatic
+                </div>
+              </div>
+              <div style={statCardStyle}>
+                <div style={{ fontWeight: 'bold', marginBottom: '8px' }}>Indexes</div>
+                <div style={{ fontSize: '14px', color: '#64748b', lineHeight: '1.6' }}>
+                  📌 projects.status<br/>
+                  📌 tasks.projectId<br/>
+                  📌 tasks.status<br/>
+                  📌 tasks.priority<br/>
+                  📌 activity.timestamp
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
     </div>
   );
 }
 `;
+        ;
         fs.writeFileSync(path.join(srcDir, 'App.tsx'), appTsx);
         const indexTsx = `import React from 'react';
 import ReactDOM from 'react-dom/client';
@@ -537,13 +1148,282 @@ main().catch(console.error);
     fs.writeFileSync(path.join(projectDir, 'index.html'), indexHtml);
     // Create .env.example
     const envExample = `# FeltDB Configuration
+# Copy this file to .env.local and update the values
+
+# API Key for authenticating with FeltDB servers
+# Leave empty for browser runtime; required for authenticated self-hosted and managed runtimes
 VITE_FELTDB_API_KEY=
+
+# FeltDB Server URL (self-hosted or managed runtime)
 VITE_FELTDB_URL=http://localhost:7700
-# Override the versioned self-hosted container when needed:
+
+# Managed example: https://runtime.your-app.feltdb.com
+VITE_FELTDB_MANAGED_URL=
+VITE_FELTDB_MANAGED_API_KEY=
+VITE_FELTDB_MANAGED_TENANT_ID=
+VITE_FELTDB_MANAGED_APPLICATION_ID=
+VITE_FELTDB_MANAGED_NAMESPACE=
+VITE_FELTDB_MANAGED_ENVIRONMENT=production
+
+# Override the default self-hosted container image
+# Example: ghcr.io/rkendel1/feltdb:latest
 FELTDB_IMAGE=
+
+# Node environment
 NODE_ENV=development
 `;
     fs.writeFileSync(path.join(projectDir, '.env.example'), envExample);
+    // Create RUNTIME_GUIDE.md
+    const runtimeGuide = `# Runtime Configuration Guide
+
+This guide explains the differences between FeltDB runtime options and how to choose the right one for your use case.
+
+## Browser Runtime
+
+\`\`\`json
+{
+  "runtime": "browser",
+  "storage": "opfs"
+}
+\`\`\`
+
+### What it does
+- Runs FeltDB entirely in the browser using JavaScript
+- Stores data in the browser's Origin Private File System (OPFS)
+- No backend server required
+
+### When to use
+- Building offline-first applications
+- Client-side only projects
+- Prototyping and development
+- Privacy-focused applications where data never leaves the user's device
+
+### Limitations
+- Data is isolated per browser/device
+- Single-user only
+- Limited by browser disk space (usually 50GB+)
+- Cannot be accessed from other devices/browsers
+
+### Setup
+No special setup required. Just run \`npm run dev\`.
+
+## Node.js Runtime
+
+\`\`\`json
+{
+  "runtime": "node",
+  "storage": "durable"
+}
+\`\`\`
+
+### What it does
+- Runs FeltDB as a Node.js server
+- Uses file-based or database storage
+- Accessible via HTTP/API
+
+### When to use
+- Building backend APIs
+- Server-side applications
+- REST API backends
+- Integration with other services
+
+### Limitations
+- Requires Node.js environment
+- Single server by default (no automatic distribution)
+- Data persistence depends on storage backend
+
+### Setup
+\`\`\`bash
+npm run dev
+# or
+npm run feltdb:server
+\`\`\`
+
+## Self-Hosted Runtime
+
+\`\`\`json
+{
+  "runtime": "self-hosted",
+  "storage": "durable"
+}
+\`\`\`
+
+### What it does
+- Runs a dedicated FeltDB server in Docker
+- Provides distributed capabilities
+- Enables multi-user, multi-device access
+- Includes API management and authentication
+
+### When to use
+- Production deployments
+- Multi-user applications
+- Synchronization across devices
+- Team collaboration features
+- Advanced distributed scenarios
+
+### Requirements
+- Docker installed and running
+- Internet access (first run downloads image)
+
+### Setup
+\`\`\`bash
+npm run dev
+# Docker will be started automatically
+\`\`\`
+
+The self-hosted instance runs on \`http://localhost:7700\` by default.
+
+## Managed Runtime
+
+\`\`\`json
+{
+  "runtime": "managed",
+  "storage": "managed"
+}
+\`\`\`
+
+Managed mode uses the same application API with a FeltDB-hosted endpoint. The CLI creates \`.env.local\` with \`VITE_FELTDB_MANAGED_URL\` and \`VITE_FELTDB_MANAGED_API_KEY\` after account setup. Studio uses that same connection for state, health, operations, and API-key administration.
+
+## Vector Search Status
+
+### Current Status
+Vector search support in FeltDB is available through integrations with vector databases:
+- Milvus
+- Pinecone
+- Weaviate
+- Local vector storage (development)
+
+### Enabling Vector Search
+To enable vector search capabilities:
+
+1. Update \`feltdb.config.json\`:
+\`\`\`json
+{
+  "capabilities": {
+    "search": true,
+    "vector-search": true
+  }
+}
+\`\`\`
+
+2. Configure your vector database in your environment variables or code
+
+3. Implement vector embedding logic in your capabilities:
+\`\`\`typescript
+// feeldb/capabilities/index.ts
+export const capabilities = {
+  'vector-search': {
+    enabled: true,
+    scope: ['documents:read', 'capabilities:execute'],
+  },
+};
+\`\`\`
+
+### Vector Storage Options
+
+#### Local Development
+For development, FeltDB includes a local vector store:
+- In-memory embeddings
+- No external dependencies
+- Perfect for prototyping
+
+#### Production
+For production deployments:
+
+**Milvus** (Open source)
+- Self-hosted vector database
+- Scalable to millions of vectors
+- Full-text + vector search combined
+
+**Pinecone** (Managed service)
+- Serverless vector database
+- Easy to set up
+- No infrastructure to manage
+
+**Weaviate** (Open source + Cloud)
+- GraphQL interface
+- Hybrid search (text + vectors)
+- Multiple deployment options
+
+## Migration Between Runtimes
+
+You can migrate between runtimes by:
+
+1. Export data from current runtime
+2. Update \`feltdb.config.json\` with new runtime
+3. Import data to new runtime
+
+Example:
+\`\`\`bash
+# Export from browser
+npm run feltdb:export
+
+# Update config
+# nano feltdb.config.json
+
+# Start new runtime
+npm run dev
+
+# Import data
+npm run feltdb:import
+\`\`\`
+
+## Environment Variables by Runtime
+
+### Browser
+- No special variables needed
+- Optional: \`VITE_DEBUG=1\` for debugging
+
+### Node.js
+- \`DATABASE_URL\`: Connection string for persistent database
+- \`PORT\`: Server port (default: 3000)
+- \`NODE_ENV\`: development|production
+
+### Self-Hosted
+- \`VITE_FELTDB_URL\`: Docker container URL (default: http://localhost:7700)
+- \`VITE_FELTDB_API_KEY\`: API token for authentication
+- \`FELTDB_IMAGE\`: Docker image to use (optional override)
+- \`DOCKER_NETWORK\`: Custom Docker network (optional)
+
+## Troubleshooting
+
+### "Runtime not configured" Error
+Update \`feltdb.config.json\` with a valid runtime selection.
+
+### "Cannot connect to self-hosted server"
+Check that Docker is running:
+\`\`\`bash
+docker ps | grep feltdb
+\`\`\`
+
+If not running, restart:
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### Browser Storage Full
+OPFS limit reached. Clear unused data or migrate to self-hosted.
+
+### Vector Search Not Working
+Verify vector database connection and that embeddings are enabled in capabilities.
+
+## Performance Considerations
+
+| Metric | Browser | Node.js | Self-Hosted |
+|--------|---------|---------|-------------|
+| Latency | Immediate | Low | Low |
+| Throughput | ~1000 ops/sec | ~10K ops/sec | ~100K ops/sec |
+| Data Limit | 50GB+ | Disk dependent | Unlimited |
+| Users | 1 | Few | Many |
+| Cost | Free | Hosting cost | Hosting cost |
+
+## Next Steps
+
+- Read the [FeltDB Documentation](https://github.com/rkendel1/feltdb)
+- Check out example projects in the templates
+- Join the community Discord for support
+`;
+    fs.writeFileSync(path.join(projectDir, 'RUNTIME_GUIDE.md'), runtimeGuide);
     // Create .gitignore
     const gitignore = `node_modules/
 dist/
@@ -560,7 +1440,14 @@ build/
     // Create README
     const readme = `# ${applicationName}
 
-A FeltDB distributed application with agents and capabilities.
+A FeltDB Workspace application demonstrating local-first database capabilities.
+
+**Deployment Target:** \`${runtime}\`
+- **Runtime:** ${runtime === 'browser' ? 'Browser (IndexedDB)' : runtime === 'node' ? 'Node.js Server' : runtime === 'managed' ? 'Managed FeltDB' : 'Self-hosted Docker'}
+- **Framework:** ${framework}
+- **Distributed:** ${distributed ? 'Yes' : 'No'}
+- **Agents:** ${hasAgents ? 'Yes' : 'No'}
+- **Capabilities:** ${capabilities}
 
 ## Quick Start
 
@@ -569,37 +1456,123 @@ npm install
 npm run dev
 \`\`\`
 
+The application will be available at http://localhost:5173 (or your configured port).
+
+## FeltDB Workspace Showcase
+
+This application demonstrates core FeltDB capabilities:
+
+✅ **Collections & Relationships** - Projects, Tasks, and Activity collections with foreign key relationships
+✅ **Indexed Querying** - Efficient queries by projectId, status, priority, and timestamp
+✅ **Activity/Audit Logs** - Append-only event collection demonstrating immutable history
+✅ **Persistent Storage** - Data persists through page reloads (IndexedDB)
+✅ **Reactive State** - Real-time updates using React hooks
+✅ **Local-first** - Works offline with no server required
+✅ **Data Inspector** - Built-in developer panel to inspect collections and indexes
+
+### Application Features
+
+- **Dashboard** - Overview of projects, tasks, and runtime status
+- **Projects** - Create and manage projects with descriptions
+- **Tasks** - Create tasks within projects with priority and status
+- **Activity Log** - Append-only event history of all changes
+- **Search** - Indexed searching across task titles and descriptions
+- **Data Inspector** - Developer panel showing collections, indexes, and storage info
+
 ## Project Structure
 
 \`\`\`
 ${applicationName}/
-├── feltdb/
+├── feltdb/                 # FeltDB configuration
 │   ├── agents/            # Agent definitions
 │   ├── capabilities/      # Capability implementations
 │   ├── workflows/         # Workflow definitions
 │   └── schema/            # Data schemas
-├── src/
-│   ├── App.${framework === 'react' ? 'tsx' : 'js'}
-│   ├── feltdb.ts
-│   └── index.${framework === 'react' ? 'tsx' : 'js'}
-├── public/
+├── src/                   # Application source code
+│   ├── App.${framework === 'react' ? 'tsx' : 'js'}         # Main workspace UI
+│   ├── feltdb.ts          # FeltDB collections and operations
+│   └── index.${framework === 'react' ? 'tsx' : 'js'}       # Entry point
+├── public/                # Static assets
 ├── index.html
 ├── .feltdb/               # Local FeltDB configuration
-├── feltdb.config.json
-├── .env.example
+├── feltdb.config.json     # FeltDB configuration
+├── .env.example           # Environment variables template
 ├── package.json
 ├── tsconfig.json
 └── README.md
 \`\`\`
 
+## FeltDB Runtime
+
+This project was created with the **${runtime === 'browser' ? 'Browser' : runtime === 'node' ? 'Node.js Server' : runtime === 'managed' ? 'Managed' : 'Self-hosted'}** runtime.
+
+### Browser Runtime
+
+FeltDB runs locally in the browser and persists through IndexedDB.
+
+- ✅ Zero server/database infrastructure
+- ✅ Works completely offline
+- ✅ Data stays on your device (privacy-first)
+- ✅ Best for: Client-side apps, offline-first experiences, prototypes
+
+**Data Persistence:** IndexedDB (OPFS fallback)
+
+### Node.js Runtime
+
+FeltDB runs as a Node.js server with server-side authority.
+
+- ✅ Server-side FeltDB authority
+- ✅ Persistent file-based storage
+- ✅ Multi-client capable
+- ✅ Best for: Server-side applications, APIs, backend services
+
+**Data Persistence:** File-based storage
+
+### Self-hosted Runtime
+
+FeltDB runs through a dedicated server with Docker Compose and persistent data volume.
+
+- ✅ Production-ready deployment
+- ✅ Multi-node replication
+- ✅ Health checks and orchestration
+- ✅ Best for: Production deployments, multi-user systems
+
+**Data Persistence:** Docker volume (persistent /data)
+
+### Managed Runtime
+
+FeltDB provides the runtime endpoint, durable storage, synchronization, and background workload infrastructure. The CLI configures \`VITE_FELTDB_MANAGED_URL\` and \`VITE_FELTDB_MANAGED_API_KEY\` in \`.env.local\`.
+
 ## Configuration
 
 Configuration is in \`feltdb.config.json\`:
-- \`runtime\`: ${runtime} (browser|node|self-hosted)
-- \`storage\`: ${runtime === 'browser' ? 'opfs' : 'durable'}
-- \`distributed\`: ${distributed}
-- \`agents.enabled\`: ${hasAgents}
-- \`capabilities\`: ${capabilities}
+
+\`\`\`json
+{
+  "namespace": "${applicationName}",
+  "runtime": "${runtime}",
+  "storage": "${runtime === 'browser' ? 'indexeddb' : runtime === 'managed' ? 'managed' : 'durable'}",
+  "distributed": ${distributed},
+  "agents": {
+    "enabled": ${hasAgents}
+  },
+  "capabilities": ["${capabilities}"]
+}
+\`\`\`
+
+### Environment Variables
+
+Create a \`.env.local\` file (copy from \`.env.example\`):
+
+\`\`\`
+VITE_FELTDB_API_KEY=your_api_key_here
+VITE_FELTDB_URL=http://localhost:7700
+VITE_FELTDB_MANAGED_API_KEY=your_managed_api_key_here
+VITE_FELTDB_MANAGED_URL=https://api.feltdb.com
+VITE_FELTDB_WEBSOCKET_URL=ws://localhost:7700
+\`\`\`
+
+These are required when connecting to an authenticated self-hosted or managed FeltDB instance.
 
 ## Development
 
@@ -613,29 +1586,105 @@ npm run dev
 npm run build
 \`\`\`
 
-### Connect to Remote Server
+### Validate FeltDB Configuration
 \`\`\`bash
-feltdb connect http://localhost:7700
+npm run feltdb:validate
 \`\`\`
 
-### Create API Key
+### View FeltDB Status
 \`\`\`bash
-feltdb keys create --name development --scope '*'
+npm run feltdb:status
 \`\`\`
 
+### Open FeltDB Studio
+\`\`\`bash
+npm run feltdb:studio
+\`\`\`
+
+## Database Schema
+
+### Collections
+
+#### projects
+- **id** (string): Unique project identifier
+- **name** (string): Project name
+- **description** (string): Project description
+- **status** (string): 'active' | 'archived' | 'completed'
+- **createdAt** (string): ISO timestamp
+- **updatedAt** (string): ISO timestamp
+- **metadata** (object, optional): Custom metadata
+
+**Indexes:** status
+
+#### tasks
+- **id** (string): Unique task identifier
+- **projectId** (string): Foreign key to projects
+- **title** (string): Task title
+- **description** (string): Task description
+- **status** (string): 'todo' | 'in-progress' | 'completed'
+- **priority** (string): 'low' | 'medium' | 'high'
+- **assignee** (string, optional): Assigned team member
+- **createdAt** (string): ISO timestamp
+- **updatedAt** (string): ISO timestamp
+
+**Indexes:** projectId, status, priority
+
+#### activity
+- **id** (string): Unique event identifier
+- **timestamp** (string): ISO timestamp
+- **type** (string): Event type
+- **entityType** (string): 'project' | 'task'
+- **entityId** (string): Reference to entity
+- **entityName** (string): Name of entity
+- **changes** (object, optional): Changed fields
+- **userId** (string, optional): User who made change
+
+**Indexes:** timestamp, (entityType, entityId)
+
 ## Agents
 
-${hasAgents ? `The \`researcher\` agent runs real private inference with
-\`@feltdb/webllm\`. The model downloads on first use, runs in a Web Worker, and
-caches its artifacts in the browser. Generated reports are stored in FeltDB.` : 'No agents configured'}
+${hasAgents ? `### Available Agents
+The application includes autonomous agents powered by \`@feltdb/webllm\`:
+- Runs entirely in the browser (private, no external APIs)
+- Model downloads on first use
+- Inference runs in a Web Worker
+- Learn more: https://github.com/mlc-ai/web-llm` : 'No agents configured. To enable agents, re-run create-feltdb or add them to feltdb.config.json.'}
+
+## Troubleshooting
 
-## Capabilities
+### Data not persisting
+1. Check browser console for errors
+2. Verify IndexedDB is enabled (not in private mode)
+3. Check browser storage quota
+4. Clear browser cache and try again
 
-${capabilities}
+### Slow performance
+1. Check browser DevTools Performance tab
+2. Verify indexes are being used (check Data Inspector)
+3. Consider optimizing queries or collection size
+
+### Self-Hosted Connection Issues
+If using self-hosted mode and connection fails:
+1. Ensure Docker is installed and running
+2. Check VITE_FELTDB_URL and API key in .env.local
+3. Run \`npm run feltdb:status\` to check server health
+4. View Docker logs: \`docker logs feltdb\`
+
+### Port conflicts
+If port 5173 is in use:
+1. Change the port in \`vite.config.ts\`
+2. Or: \`npm run dev -- --port 3000\`
 
 ## Learn More
 
-Visit [FeltDB Documentation](https://github.com/rkendel1/feltdb) to learn more.
+- [FeltDB Documentation](https://github.com/rkendel1/feltdb)
+- [FeltDB Architecture](https://github.com/rkendel1/feltdb/blob/main/ARCHITECTURE.md)
+- [WebLLM (In-browser LLM)](https://github.com/mlc-ai/web-llm)
+- [Getting Started Guide](https://github.com/rkendel1/feltdb/blob/main/GETTING_STARTED.md)
+
+## License
+
+MIT
 `;
     fs.writeFileSync(path.join(projectDir, 'README.md'), readme);
 }