@feltdb/core 0.4.5 → 0.4.7

package/dist/create/create.js

@@ -0,0 +1,1862 @@
+/**
+ * Project creation logic
+ */
+import fs from 'fs';
+import path from 'path';
+import { feltdbPackageRange } from './package-versions.js';
+export async function createProject(options) {
+    const { projectName, templatesDir } = options;
+    const projectDir = path.resolve(process.cwd(), projectName);
+    const applicationName = path.basename(projectDir);
+    // Create project directory
+    if (!fs.existsSync(projectDir)) {
+        fs.mkdirSync(projectDir, { recursive: true });
+    }
+    // Create feltdb directory structure
+    const feltdbDir = path.join(projectDir, 'feltdb');
+    const srcDir = path.join(projectDir, 'src');
+    const publicDir = path.join(projectDir, 'public');
+    const feltdbConfigDir = path.join(projectDir, '.feltdb');
+    fs.mkdirSync(path.join(feltdbDir, 'capabilities'), { recursive: true });
+    fs.mkdirSync(path.join(feltdbDir, 'workflows'), { recursive: true });
+    fs.mkdirSync(path.join(feltdbDir, 'agents'), { recursive: true });
+    fs.mkdirSync(path.join(feltdbDir, 'schema'), { recursive: true });
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(publicDir, { recursive: true });
+    fs.mkdirSync(feltdbConfigDir, { recursive: true });
+    const runtime = options.runtime || 'browser';
+    const framework = options.framework || 'react';
+    const distributed = options.distributed !== false;
+    const hasAgents = options.agents !== false;
+    const capabilities = options.capabilities || 'search';
+    // Create package.json
+    const packageJson = {
+        name: applicationName,
+        version: '0.1.0',
+        description: `A FeltDB application`,
+        main: 'src/index.ts',
+        type: 'module',
+        scripts: {
+            dev: 'feltdb dev',
+            build: 'feltdb build',
+            test: 'node --test',
+            feltdb: 'feltdb',
+            'feltdb:server': 'feltdb server',
+            'feltdb:connect': 'feltdb connect http://localhost:7700',
+            'feltdb:status': 'feltdb status',
+            'feltdb:studio': 'feltdb studio',
+            'feltdb:validate': 'feltdb validate',
+            'feltdb:diff': 'feltdb diff',
+            'feltdb:deploy': 'feltdb deploy',
+        },
+        dependencies: {
+            '@feltdb/core': feltdbPackageRange,
+        },
+        devDependencies: {
+            typescript: '^5.0.0',
+            '@types/node': '^20.0.0',
+            vite: '^8.2.1',
+        },
+    };
+    if (framework === 'react') {
+        packageJson.dependencies['react'] = '^18.0.0';
+        packageJson.dependencies['react-dom'] = '^18.0.0';
+        packageJson.devDependencies['@types/react'] = '^18.0.0';
+        packageJson.devDependencies['@types/react-dom'] = '^18.0.0';
+    }
+    if (hasAgents) {
+        packageJson.dependencies['@feltdb/webllm'] = feltdbPackageRange;
+    }
+    fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+    // Create feltdb.config.json
+    const feltdbConfig = {
+        namespace: applicationName,
+        runtime,
+        storage: runtime === 'browser' ? 'opfs' : 'durable',
+        distributed,
+        agents: {
+            enabled: hasAgents,
+        },
+        capabilities: {},
+    };
+    if (capabilities.includes('search')) {
+        feltdbConfig.capabilities.search = true;
+    }
+    if (capabilities.includes('vector')) {
+        feltdbConfig.capabilities['vector-search'] = true;
+    }
+    fs.writeFileSync(path.join(projectDir, 'feltdb.config.json'), JSON.stringify(feltdbConfig, null, 2));
+    const appName = applicationName.replace(/[^A-Za-z0-9_]/g, '_').replace(/^[^A-Za-z_]/, 'App_');
+    const flowSpec = `app ${appName} {
+  collection Document {
+    title: text
+    content: text
+    createdAt: datetime
+    index search using fulltext(content)
+  }
+
+  collection Report {
+    title: text
+    content: text
+    document: ref Document
+  }
+
+  capability Research {
+    read Document
+    write Report
+  }
+
+  agent Researcher {
+    capability Research
+    workflow ResearchDocument
+  }
+
+  workflow ResearchDocument(document: Document) {
+    step search {
+      input document.content
+    }
+    step identity {
+      input search.output
+    }
+  }
+
+  trigger on Document.created {
+    workflow ResearchDocument(document)
+  }
+
+  policy Document {
+    read: authenticated
+    write: authenticated
+  }
+}
+`;
+    fs.writeFileSync(path.join(projectDir, 'feltdb.flow'), flowSpec);
+    // Create tsconfig.json
+    const tsconfig = {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'ESNext',
+            lib: ['ES2020', 'DOM'],
+            declaration: true,
+            outDir: './dist',
+            rootDir: './src',
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+            moduleResolution: 'node',
+        },
+        include: ['src/**/*'],
+        exclude: ['node_modules'],
+    };
+    if (framework === 'react') {
+        tsconfig.compilerOptions.jsx = 'react-jsx';
+    }
+    fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
+    // 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 }";
+    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');
+`;
+    fs.writeFileSync(path.join(srcDir, 'feltdb.ts'), feltdbTs);
+    // Create a real local-inference agent for browser projects.
+    if (hasAgents) {
+        const agentTs = `import { WebLLMProvider } from '@feltdb/webllm';
+import { db, reports } from '../../src/feltdb';
+
+/**
+ * Researcher metadata is registered in FeltDB; inference runs privately in
+ * the browser through WebLLM and its worker.
+ */
+export const researcher = db.defineAgent({
+  name: 'researcher',
+  version: 1,
+  description: 'Private, on-device AI assistant for document enhancement and analysis',
+  capabilities: [
+    'document-read',
+    'report-write'
+  ],
+  goals: [
+    'Analyze documents privately without sending data off-device',
+    'Generate insights and enhancements locally',
+    'Support document summarization, expansion, and improvement'
+  ],
+  constraints: { maxIterations: 1 },
+});
+
+let provider: WebLLMProvider | undefined;
+
+export async function runResearcher(
+  prompt: string,
+  onProgress?: (message: string) => void,
+) {
+  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);
+    }
+    // Create capabilities index
+    const capabilitiesTs = `/**
+ * Capabilities
+ *
+ * Define capabilities that can be executed by agents
+ * across distributed peers
+ */
+
+export const capabilities = {
+  'document-read': {
+    enabled: true,
+    scope: ['documents:read'],
+  },
+  'vector-search': {
+    enabled: ${capabilities.includes('vector')},
+    scope: ['documents:read', 'capabilities:execute'],
+  },
+  'report-write': {
+    enabled: true,
+    scope: ['reports:write'],
+  },
+};
+`;
+    fs.writeFileSync(path.join(feltdbDir, 'capabilities', 'index.ts'), capabilitiesTs);
+    // Create main application file based on framework
+    if (framework === 'react') {
+        const agentImport = hasAgents
+            ? "import { runResearcher, summarizeDocument, enhanceDocument, generateIdeas, generateFeltDBFeature, generateReactComponent, generateCapability } from '../feltdb/agents/researcher';"
+            : '';
+        const agentState = hasAgents
+            ? `  const [prompt, setPrompt] = useState('');
+  const [answer, setAnswer] = useState('');
+  const [modelStatus, setModelStatus] = useState('Model not loaded');
+  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 handleRunAI = async (mode: 'custom' | 'summarize' | 'enhance' | 'ideas' | 'feltdb' | 'react' | 'capability') => {
+    setGenerating(true);
+    setAnswer('');
+    setModelStatus('Running inference...');
+
+    try {
+      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: ' + (error instanceof Error ? error.message : String(error)));
+    } finally {
+      setGenerating(false);
+    }
+  };
+`
+            : '';
+        const agentMarkup = hasAgents
+            ? `
+        <section className="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 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}
+
+export function App() {
+  const [docs, setDocs] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [addingDoc, setAddingDoc] = useState(false);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [editTitle, setEditTitle] = useState('');
+  const [editContent, setEditContent] = useState('');
+  const [deletingId, setDeletingId] = useState<string | null>(null);
+${agentState}
+
+  const loadDocs = async () => {
+    try {
+      setError(null);
+      const allDocs = await documents.find({});
+      setDocs(allDocs.sort((a: any, b: any) =>
+        new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+      ));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to load documents';
+      console.error('Error loading documents:', err);
+      setError(msg);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    loadDocs();
+  }, []);
+
+  const filteredDocs = docs.filter((doc: any) =>
+    doc.title.toLowerCase().includes(searchTerm.toLowerCase()) ||
+    doc.content.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+
+  const handleAddDocument = async () => {
+    if (addingDoc) return;
+    setAddingDoc(true);
+    setError(null);
+
+    try {
+      const newDoc = {
+        id: 'doc_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
+        title: 'New Document',
+        content: 'Enter your content here...',
+        createdAt: new Date().toISOString(),
+      };
+      await documents.insert(newDoc);
+      await loadDocs();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to add document';
+      console.error('Error adding document:', err);
+      setError(msg);
+    } finally {
+      setAddingDoc(false);
+    }
+  };
+
+  const handleEditStart = (doc: any) => {
+    setEditingId(doc.id);
+    setEditTitle(doc.title);
+    setEditContent(doc.content);
+  };
+
+  const handleEditSave = async () => {
+    if (!editingId) return;
+    setError(null);
+
+    try {
+      const doc = docs.find((d: any) => d.id === editingId);
+      if (doc) {
+        const updatedDoc = {
+          ...doc,
+          title: editTitle,
+          content: editContent,
+          updatedAt: new Date().toISOString(),
+        };
+        await documents.insert(updatedDoc);
+        setEditingId(null);
+        await loadDocs();
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to save document';
+      console.error('Error saving document:', err);
+      setError(msg);
+    }
+  };
+
+  const handleDelete = async (docId: string) => {
+    if (deletingId) return;
+    setDeletingId(docId);
+    setError(null);
+
+    try {
+      const doc = docs.find((d: any) => d.id === docId);
+      if (doc) {
+        await documents.delete(doc);
+        await loadDocs();
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to delete document';
+      setError(msg);
+    } finally {
+      setDeletingId(null);
+    }
+  };
+${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>
+        </section>
+
+        {error && (
+          <section className="error-message">
+            <strong>⚠ Error:</strong> {error}
+            <button onClick={() => window.location.reload()} className="retry-btn">
+              Retry
+            </button>
+          </section>
+        )}
+
+        <section className="documents">
+          <div className="docs-header">
+            <h2>📚 Documents</h2>
+            <div className="docs-controls">
+              <input
+                type="text"
+                placeholder="🔍 Search documents..."
+                value={searchTerm}
+                onChange={(e) => setSearchTerm(e.target.value)}
+                className="search-input"
+              />
+              <button
+                onClick={handleAddDocument}
+                disabled={addingDoc || loading}
+                className="primary-btn"
+              >
+                {addingDoc ? '⏳ Adding...' : '➕ New Document'}
+              </button>
+            </div>
+          </div>
+
+          {loading ? (
+            <div className="loading">
+              <div className="spinner"></div>
+              <p>Loading documents...</p>
+            </div>
+          ) : docs.length === 0 ? (
+            <div className="empty-state">
+              <p>📭 No documents yet.</p>
+              <p className="hint">Create one to get started!</p>
+            </div>
+          ) : filteredDocs.length === 0 ? (
+            <div className="empty-state">
+              <p>🔍 No documents match "{searchTerm}"</p>
+            </div>
+          ) : (
+            <div className="docs-grid">
+              {filteredDocs.map((doc: any) => (
+                <div key={doc.id} className="doc-card">
+                  {editingId === doc.id ? (
+                    <div className="edit-mode">
+                      <input
+                        type="text"
+                        value={editTitle}
+                        onChange={(e) => setEditTitle(e.target.value)}
+                        className="edit-title"
+                      />
+                      <textarea
+                        value={editContent}
+                        onChange={(e) => setEditContent(e.target.value)}
+                        className="edit-content"
+                        rows={6}
+                      />
+                      <div className="edit-actions">
+                        <button onClick={handleEditSave} className="save-btn">
+                          ✓ Save
+                        </button>
+                        <button onClick={() => setEditingId(null)} className="cancel-btn">
+                          ✕ Cancel
+                        </button>
+                      </div>
+                    </div>
+                  ) : (
+                    <>
+                      <h3>{doc.title}</h3>
+                      <p className="doc-preview">{doc.content.substring(0, 150)}...</p>
+                      <div className="doc-meta">
+                        <small>{new Date(doc.createdAt).toLocaleDateString()}</small>
+                        <span className="doc-size">{doc.content.length} chars</span>
+                      </div>
+                      <div className="doc-actions">
+                        <button
+                          onClick={() => handleEditStart(doc)}
+                          className="edit-btn"
+                        >
+                          ✎ Edit
+                        </button>
+                        <button
+                          onClick={() => handleDelete(doc.id)}
+                          disabled={deletingId === doc.id}
+                          className="delete-btn"
+                        >
+                          {deletingId === doc.id ? '⏳ Deleting...' : '🗑 Delete'}
+                        </button>
+                      </div>
+                    </>
+                  )}
+                </div>
+              ))}
+            </div>
+          )}
+        </section>
+${agentMarkup}
+      </main>
+
+      <style>{\`
+        * { box-sizing: border-box; }
+
+        body {
+          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
+          margin: 0;
+          padding: 0;
+          background: #f5f7fa;
+          color: #333;
+        }
+
+        .app {
+          max-width: 1400px;
+          margin: 0 auto;
+          padding: 20px;
+        }
+
+        header {
+          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+          color: white;
+          padding: 40px 30px;
+          border-radius: 12px;
+          margin-bottom: 30px;
+          box-shadow: 0 8px 24px rgba(102, 126, 234, 0.3);
+        }
+
+        header h1 {
+          margin: 0 0 10px 0;
+          font-size: 32px;
+          font-weight: 700;
+        }
+
+        header p {
+          margin: 0;
+          opacity: 0.95;
+          font-size: 16px;
+        }
+
+        main {
+          background: white;
+          padding: 30px;
+          border-radius: 12px;
+          box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+        }
+
+        .stats {
+          display: grid;
+          grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+          gap: 20px;
+          margin-bottom: 30px;
+        }
+
+        .stat {
+          padding: 24px;
+          background: linear-gradient(135deg, #f5f7fa 0%, #f9f9f9 100%);
+          border-radius: 8px;
+          border-left: 4px solid #667eea;
+          box-shadow: 0 1px 3px rgba(0,0,0,0.05);
+        }
+
+        .stat .label {
+          display: block;
+          color: #999;
+          font-size: 10px;
+          text-transform: uppercase;
+          letter-spacing: 1px;
+          margin-bottom: 8px;
+          font-weight: 700;
+        }
+
+        .stat .value {
+          display: block;
+          font-size: 32px;
+          font-weight: 700;
+          color: #667eea;
+        }
+
+        .error-message {
+          padding: 16px 20px;
+          background: #fff5f5;
+          border: 1px solid #fca5a5;
+          border-left: 4px solid #f56565;
+          border-radius: 8px;
+          margin-bottom: 20px;
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+          color: #c53030;
+        }
+
+        .error-message strong { font-weight: 600; }
+
+        .retry-btn {
+          background: #f56565;
+          padding: 8px 16px;
+          font-size: 12px;
+          margin-left: 15px;
+          border-radius: 4px;
+        }
+
+        .retry-btn:hover { background: #e53e3e; }
+
+        .docs-header {
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+          margin-bottom: 24px;
+          gap: 20px;
+        }
+
+        .docs-header h2 {
+          margin: 0;
+          color: #1a202c;
+          font-size: 26px;
+          flex: 1;
+        }
+
+        .docs-controls {
+          display: flex;
+          gap: 12px;
+          flex: 1;
+          max-width: 600px;
+        }
+
+        .search-input {
+          flex: 1;
+          padding: 10px 16px;
+          border: 1px solid #e2e8f0;
+          border-radius: 6px;
+          font-size: 14px;
+          transition: all 0.2s ease;
+        }
+
+        .search-input:focus {
+          outline: none;
+          border-color: #667eea;
+          box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+        }
+
+        .loading {
+          text-align: center;
+          padding: 60px 20px;
+          color: #999;
+        }
+
+        .spinner {
+          display: inline-block;
+          width: 48px;
+          height: 48px;
+          border: 4px solid #e2e8f0;
+          border-top-color: #667eea;
+          border-radius: 50%;
+          animation: spin 0.8s linear infinite;
+          margin-bottom: 20px;
+        }
+
+        @keyframes spin { to { transform: rotate(360deg); } }
+
+        .empty-state {
+          text-align: center;
+          padding: 60px 20px;
+          color: #999;
+        }
+
+        .empty-state p { margin: 8px 0; font-size: 16px; }
+        .empty-state .hint { font-size: 14px; opacity: 0.8; }
+
+        .docs-grid {
+          display: grid;
+          grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
+          gap: 20px;
+        }
+
+        .doc-card {
+          background: #f9f9f9;
+          border: 1px solid #e2e8f0;
+          border-radius: 8px;
+          padding: 20px;
+          transition: all 0.3s ease;
+          display: flex;
+          flex-direction: column;
+        }
+
+        .doc-card:hover {
+          border-color: #667eea;
+          box-shadow: 0 4px 12px rgba(102, 126, 234, 0.15);
+          transform: translateY(-2px);
+        }
+
+        .doc-card h3 {
+          margin: 0 0 12px 0;
+          color: #1a202c;
+          font-size: 18px;
+          font-weight: 600;
+          word-break: break-word;
+        }
+
+        .doc-preview {
+          flex: 1;
+          margin: 0 0 12px 0;
+          color: #666;
+          font-size: 14px;
+          line-height: 1.6;
+          display: -webkit-box;
+          -webkit-line-clamp: 3;
+          -webkit-box-orient: vertical;
+          overflow: hidden;
+        }
+
+        .doc-meta {
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+          padding: 12px 0;
+          border-top: 1px solid #e2e8f0;
+          border-bottom: 1px solid #e2e8f0;
+          margin-bottom: 12px;
+          font-size: 12px;
+          color: #999;
+        }
+
+        .doc-size {
+          background: #f0f4ff;
+          padding: 2px 8px;
+          border-radius: 4px;
+          color: #667eea;
+          font-weight: 600;
+        }
+
+        .doc-actions {
+          display: flex;
+          gap: 8px;
+        }
+
+        .edit-btn, .delete-btn, .save-btn, .cancel-btn {
+          flex: 1;
+          padding: 8px 12px;
+          font-size: 13px;
+          border: 1px solid;
+          border-radius: 6px;
+          cursor: pointer;
+          font-weight: 600;
+          transition: all 0.2s ease;
+        }
+
+        .edit-btn {
+          background: #eef2ff;
+          border-color: #667eea;
+          color: #667eea;
+        }
+
+        .edit-btn:hover { background: #e0e7ff; }
+
+        .delete-btn {
+          background: #fee;
+          border-color: #fca5a5;
+          color: #c53030;
+        }
+
+        .delete-btn:hover:not(:disabled) { background: #fdd; }
+        .delete-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+
+        .edit-mode {
+          display: flex;
+          flex-direction: column;
+          gap: 12px;
+        }
+
+        .edit-title, .edit-content {
+          padding: 10px 12px;
+          border: 1px solid #ddd;
+          border-radius: 6px;
+          font-family: inherit;
+          font-size: 14px;
+        }
+
+        .edit-title {
+          font-size: 16px;
+          font-weight: 600;
+        }
+
+        .edit-title:focus, .edit-content:focus {
+          outline: none;
+          border-color: #667eea;
+          box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+        }
+
+        .edit-actions {
+          display: flex;
+          gap: 8px;
+        }
+
+        .save-btn {
+          background: #667eea;
+          color: white;
+          border: none;
+          flex: 1;
+        }
+
+        .save-btn:hover { background: #5568d3; }
+
+        .cancel-btn {
+          background: #f0f0f0;
+          color: #666;
+          border: none;
+          flex: 1;
+        }
+
+        .cancel-btn:hover { background: #e0e0e0; }
+
+        .primary-btn {
+          background: #667eea;
+          color: white;
+          border: none;
+          padding: 10px 20px;
+          white-space: nowrap;
+        }
+
+        .primary-btn:hover:not(:disabled) { background: #5568d3; }
+        .primary-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+
+        textarea, input {
+          display: block;
+          width: 100%;
+          margin: 12px 0;
+          padding: 12px;
+          font-family: inherit;
+          font-size: 14px;
+          border: 1px solid #ddd;
+          border-radius: 6px;
+          resize: vertical;
+        }
+
+        textarea:focus, input:focus {
+          outline: none;
+          border-color: #667eea;
+          box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+        }
+
+        .status-badge {
+          display: inline-block;
+          padding: 8px 12px;
+          background: #f0f4ff;
+          color: #667eea;
+          border-radius: 6px;
+          font-size: 12px;
+          font-weight: 600;
+          margin-bottom: 16px;
+        }
+
+        .researcher {
+          border-top: 2px solid #e2e8f0;
+          margin-top: 40px;
+          padding-top: 30px;
+        }
+
+        .researcher h2 {
+          margin-top: 0;
+          color: #1a202c;
+          font-size: 20px;
+        }
+
+        .research-btn {
+          background: #667eea;
+          color: white;
+          border: none;
+          padding: 12px 24px;
+          margin: 16px 0;
+          border-radius: 6px;
+          cursor: pointer;
+          font-weight: 600;
+          transition: all 0.2s ease;
+        }
+
+        .research-btn:hover:not(:disabled) { background: #5568d3; }
+        .research-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+
+        .research-result {
+          background: #f5f8ff;
+          border: 1px solid #d4e0ff;
+          border-radius: 8px;
+          padding: 16px;
+          margin-top: 20px;
+        }
+
+        .ai-modes {
+          display: flex;
+          gap: 16px;
+          margin-bottom: 16px;
+          flex-wrap: wrap;
+        }
+
+        .mode-group {
+          display: flex;
+          flex-direction: column;
+          gap: 6px;
+        }
+
+        .mode-group-label {
+          font-size: 11px;
+          font-weight: 700;
+          text-transform: uppercase;
+          color: #999;
+          letter-spacing: 0.5px;
+        }
+
+        .mode-group {
+          display: flex;
+          gap: 6px;
+          flex-wrap: wrap;
+        }
+
+        .mode-btn {
+          background: #f0f4ff;
+          color: #667eea;
+          border: 1px solid #d4e0ff;
+          padding: 8px 14px;
+          border-radius: 6px;
+          cursor: pointer;
+          font-size: 12px;
+          font-weight: 600;
+          transition: all 0.2s ease;
+        }
+
+        .mode-btn:hover:not(:disabled) {
+          background: #e0e7ff;
+          border-color: #667eea;
+          transform: translateY(-1px);
+        }
+
+        .mode-btn.active {
+          background: #667eea;
+          color: white;
+          border-color: #667eea;
+        }
+
+        .mode-btn.code-mode {
+          background: #fef5e7;
+          color: #c87832;
+          border-color: #f4d29d;
+        }
+
+        .mode-btn.code-mode:hover:not(:disabled) {
+          background: #fdebd0;
+          border-color: #c87832;
+        }
+
+        .mode-btn.code-mode.active {
+          background: #c87832;
+          color: white;
+          border-color: #c87832;
+        }
+
+        .mode-btn:disabled {
+          opacity: 0.5;
+          cursor: not-allowed;
+        }
+
+        .doc-selector {
+          margin-bottom: 16px;
+        }
+
+        .doc-selector label {
+          display: block;
+          font-size: 13px;
+          font-weight: 600;
+          color: #666;
+          margin-bottom: 8px;
+          text-transform: uppercase;
+          letter-spacing: 0.5px;
+        }
+
+        .doc-selector select {
+          width: 100%;
+          padding: 10px 12px;
+          border: 1px solid #ddd;
+          border-radius: 6px;
+          font-family: inherit;
+          font-size: 14px;
+          background: white;
+        }
+
+        .doc-selector select:focus {
+          outline: none;
+          border-color: #667eea;
+          box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+        }
+
+        .research-result h3 {
+          margin: 0 0 12px 0;
+          color: #667eea;
+          font-size: 16px;
+        }
+
+        .result-content {
+          color: #555;
+          line-height: 1.6;
+          font-size: 14px;
+          margin-bottom: 16px;
+          max-height: 400px;
+          overflow-y: auto;
+          padding: 12px;
+          background: white;
+          border-radius: 4px;
+        }
+
+        .result-actions {
+          display: flex;
+          gap: 8px;
+          flex-wrap: wrap;
+        }
+
+        .save-result-btn, .copy-result-btn {
+          flex: 1;
+          min-width: 140px;
+          background: #48bb78;
+          color: white;
+          border: none;
+          padding: 10px 16px;
+          border-radius: 6px;
+          cursor: pointer;
+          font-weight: 600;
+          font-size: 13px;
+          transition: all 0.2s ease;
+        }
+
+        .save-result-btn:hover {
+          background: #38a169;
+          transform: translateY(-1px);
+        }
+
+        .copy-result-btn {
+          background: #4299e1;
+        }
+
+        .copy-result-btn:hover {
+          background: #3182ce;
+          transform: translateY(-1px);
+        }
+
+        .code-note {
+          font-size: 12px;
+          color: #999;
+          margin-top: 12px;
+          font-style: italic;
+          border-top: 1px solid #e2e8f0;
+          padding-top: 12px;
+        }
+
+        @media (max-width: 768px) {
+          .docs-header {
+            flex-direction: column;
+            align-items: stretch;
+          }
+          .docs-controls {
+            flex-direction: column;
+            max-width: 100%;
+          }
+          .docs-grid {
+            grid-template-columns: 1fr;
+          }
+          header { padding: 24px 20px; }
+          main { padding: 20px; }
+        }
+      \`}</style>
+    </div>
+  );
+}
+`;
+        fs.writeFileSync(path.join(srcDir, 'App.tsx'), appTsx);
+        const indexTsx = `import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { App } from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root')!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+`;
+        fs.writeFileSync(path.join(srcDir, 'index.tsx'), indexTsx);
+    }
+    else {
+        // Create vanilla JS app
+        const indexJs = `import { db, documents } from './feltdb';
+
+async function main() {
+  console.log('🌊 FeltDB Research App');
+  console.log('Runtime: ${runtime}');
+  console.log('Distributed: ${distributed}');
+}
+
+main().catch(console.error);
+`;
+        fs.writeFileSync(path.join(srcDir, 'index.js'), indexJs);
+    }
+    // Create index.html
+    const indexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${applicationName}</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/index${framework === 'react' ? '.tsx' : '.js'}"></script>
+</body>
+</html>
+`;
+    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 self-hosted
+VITE_FELTDB_API_KEY=
+
+# FeltDB Server URL (for self-hosted runtime)
+VITE_FELTDB_URL=http://localhost:7700
+
+# 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.
+
+## 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/
+build/
+.env
+.env.local
+.env.*.local
+*.log
+.DS_Store
+.feltdb/keys.json
+.feltdb/connection.json
+`;
+    fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignore);
+    // Create README
+    const readme = `# ${applicationName}
+
+A FeltDB distributed application with agents and capabilities.
+- **Runtime:** ${runtime}
+- **Framework:** ${framework}
+- **Distributed:** ${distributed ? 'Yes' : 'No'}
+- **Agents:** ${hasAgents ? 'Yes' : 'No'}
+- **Capabilities:** ${capabilities}
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+The application will be available at http://localhost:5173.
+
+## Project Structure
+
+\`\`\`
+${applicationName}/
+├── feltdb/                 # FeltDB configuration and logic
+│   ├── agents/            # Agent definitions
+│   ├── capabilities/      # Capability implementations
+│   ├── workflows/         # Workflow definitions
+│   └── schema/            # Data schemas
+├── src/                   # Application source code
+│   ├── App.${framework === 'react' ? 'tsx' : 'js'}
+│   ├── feltdb.ts          # FeltDB client initialization
+│   └── index.${framework === 'react' ? 'tsx' : 'js'}
+├── public/                # Static assets
+├── index.html
+├── .feltdb/               # Local FeltDB configuration
+├── feltdb.config.json     # FeltDB configuration
+├── .env.example           # Environment variables template
+├── package.json
+├── tsconfig.json
+└── README.md
+\`\`\`
+
+## Runtime Options
+
+### Browser (\`browser\`)
+- Local-first, client-side only
+- Uses browser OPFS (Origin Private File System) for storage
+- No server required
+- Best for: Offline-first apps, privacy-focused applications
+- Limitations: Single device scope (data stays local)
+
+### Node.js (\`node\`)
+- Server-side Node.js runtime
+- In-memory or file-based storage
+- Suitable for APIs and backend services
+- Best for: Server-side applications, REST APIs
+- Limitations: Memory-based by default
+
+### Self-Hosted (\`self-hosted\`)
+- Dedicated FeltDB server instance
+- Durable storage with distributed capabilities
+- Requires Docker (image: ghcr.io/rkendel1/feltdb)
+- Best for: Production deployments, multi-user systems
+- Setup: \`npm run dev\` starts the Docker container automatically
+
+## Configuration
+
+Configuration is in \`feltdb.config.json\`:
+- \`runtime\`: ${runtime}
+- \`storage\`: ${runtime === 'browser' ? 'opfs' : '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
+\`\`\`
+
+These are used when connecting to a self-hosted FeltDB instance.
+
+## Development
+
+### Start Development Server
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### Build for Production
+\`\`\`bash
+npm run build
+\`\`\`
+
+### Validate FeltDB Configuration
+\`\`\`bash
+npm run feltdb:validate
+\`\`\`
+
+### View FeltDB Status
+\`\`\`bash
+npm run feltdb:status
+\`\`\`
+
+## Database Operations
+
+### Collections
+
+The application includes pre-configured collections:
+- \`documents\`: Stores research documents
+- \`reports\`: Stores generated reports
+
+### Schema
+
+Review \`feltdb.flow\` for the complete schema and workflow definitions.
+
+## Agents
+
+${hasAgents ? `### Researcher Agent
+The \`researcher\` agent runs real private inference using \`@feltdb/webllm\`:
+- Runs entirely in the browser (no data sent to servers)
+- Model downloads on first use
+- Inference runs in a Web Worker
+- Generated reports are stored in FeltDB
+- Learn more: https://github.com/mlc-ai/web-llm` : 'No agents configured. Add agents by re-running create-feltdb.'}
+
+## Vector Search
+
+${capabilities.includes('vector') ? `Vector search is enabled. Configure your vector storage backend in \`feltdb.config.json\`.` : `Vector search is not enabled. To add it, update \`feltdb.config.json\` to include \`"vector-search": true\` in capabilities.`}
+
+## Troubleshooting
+
+### "Model not loaded" in Researcher
+If the WebLLM Researcher shows "Model not loaded":
+1. Check browser console for errors
+2. Ensure sufficient disk space (models are ~2-3GB)
+3. Try in a private/incognito window if localStorage is full
+4. Clear browser cache and try again
+
+### Self-Hosted Connection Issues
+If using self-hosted mode and connection fails:
+1. Ensure Docker is installed and running
+2. Check FELTDB_URL and API key in .env.local
+3. Run \`npm run feltdb:status\` to check server health
+4. View logs: \`docker logs feltdb\`
+
+### API Key Errors
+If API key management fails in Studio:
+1. Verify VITE_FELTDB_URL is set correctly
+2. Ensure token has proper scopes
+3. Check CORS settings on self-hosted server
+
+## Learn More
+
+- [FeltDB Documentation](https://github.com/rkendel1/feltdb)
+- [WebLLM Documentation](https://github.com/mlc-ai/web-llm)
+- [Distribution & Capabilities](https://github.com/rkendel1/feltdb/docs/capabilities.md)
+`;
+    fs.writeFileSync(path.join(projectDir, 'README.md'), readme);
+}