@feltdb/core 0.4.6 → 0.4.8

package/dist/create/create.js

@@ -180,12 +180,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 },
 });
 
@@ -195,20 +199,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);
@@ -240,24 +362,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);
     }
@@ -267,13 +409,167 @@ 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';
@@ -283,35 +579,109 @@ ${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}
 
-  useEffect(() => {
-    const loadDocs = async () => {
-      try {
-        const allDocs = await documents.find({});
-        setDocs(allDocs);
-      } catch (err) {
-        console.error('Error loading documents:', err);
-      } finally {
-        setLoading(false);
-      }
-    };
+  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 {
-      await documents.insert({
+      const newDoc = {
+        id: 'doc_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
         title: 'New Document',
-        content: 'Enter content here',
-        createdAt: new Date(),
-      });
-      // Reload documents
-      const allDocs = await documents.find({});
-      setDocs(allDocs);
+        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}
@@ -339,37 +709,123 @@ ${agentHandler}
           </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">
-          <h2>Documents</h2>
+          <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 ? (
-            <p>Loading...</p>
+            <div className="loading">
+              <div className="spinner"></div>
+              <p>Loading documents...</p>
+            </div>
           ) : docs.length === 0 ? (
-            <p>No documents yet</p>
+            <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>
           ) : (
-            <ul>
-              {docs.map((doc: any) => (
-                <li key={doc.id}>
-                  <h3>{doc.title}</h3>
-                  <p>{doc.content}</p>
-                </li>
+            <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>
               ))}
-            </ul>
+            </div>
           )}
-          <button onClick={handleAddDocument}>Add Document</button>
         </section>
 ${agentMarkup}
       </main>
 
       <style>{\`
+        * { box-sizing: border-box; }
+
         body {
           font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
           margin: 0;
           padding: 0;
-          background: #f5f5f5;
+          background: #f5f7fa;
+          color: #333;
         }
 
         .app {
-          max-width: 1200px;
+          max-width: 1400px;
           margin: 0 auto;
           padding: 20px;
         }
@@ -377,112 +833,549 @@ ${agentMarkup}
         header {
           background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
           color: white;
-          padding: 30px;
-          border-radius: 8px;
+          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: 28px;
+          font-size: 32px;
+          font-weight: 700;
         }
 
         header p {
           margin: 0;
-          opacity: 0.9;
+          opacity: 0.95;
+          font-size: 16px;
         }
 
         main {
           background: white;
-          padding: 20px;
-          border-radius: 8px;
-          box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+          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(200px, 1fr));
+          grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
           gap: 20px;
           margin-bottom: 30px;
         }
 
         .stat {
-          padding: 15px;
-          background: #f9f9f9;
-          border-radius: 4px;
-          border-left: 3px solid #667eea;
+          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: #666;
-          font-size: 12px;
+          color: #999;
+          font-size: 10px;
           text-transform: uppercase;
-          margin-bottom: 5px;
+          letter-spacing: 1px;
+          margin-bottom: 8px;
+          font-weight: 700;
         }
 
         .stat .value {
           display: block;
-          font-size: 24px;
-          font-weight: bold;
-          color: #333;
+          font-size: 32px;
+          font-weight: 700;
+          color: #667eea;
         }
 
-        .documents h2 {
-          margin-top: 0;
+        .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;
         }
 
-        .documents ul {
-          list-style: none;
-          padding: 0;
-          margin: 0 0 20px 0;
-        }
+        .error-message strong { font-weight: 600; }
 
-        .documents li {
-          padding: 15px;
-          background: #f9f9f9;
+        .retry-btn {
+          background: #f56565;
+          padding: 8px 16px;
+          font-size: 12px;
+          margin-left: 15px;
           border-radius: 4px;
-          margin-bottom: 10px;
         }
 
-        .documents h3 {
-          margin: 0 0 10px 0;
-          color: #333;
+        .retry-btn:hover { background: #e53e3e; }
+
+        .docs-header {
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+          margin-bottom: 24px;
+          gap: 20px;
         }
 
-        .documents p {
+        .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;
         }
 
-        button {
+        .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;
-          border-radius: 4px;
-          cursor: pointer;
+          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;
-          font-weight: 500;
+          border: 1px solid #ddd;
+          border-radius: 6px;
+          resize: vertical;
         }
 
-        button:hover {
-          background: #5568d3;
+        textarea:focus, input:focus {
+          outline: none;
+          border-color: #667eea;
+          box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
         }
 
-        textarea {
-          box-sizing: border-box;
+        .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;
-          margin: 12px 0;
-          padding: 10px;
+          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;
         }
 
-        .researcher {
-          border-top: 1px solid #eee;
-          margin-top: 30px;
-          padding-top: 20px;
+        .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>
@@ -534,13 +1427,263 @@ 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 self-hosted
 VITE_FELTDB_API_KEY=
+
+# FeltDB Server URL (for self-hosted runtime)
 VITE_FELTDB_URL=http://localhost:7700
-# Override the versioned self-hosted container when needed:
+
+# 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/
@@ -558,6 +1701,11 @@ build/
     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
 
@@ -566,38 +1714,74 @@ npm install
 npm run dev
 \`\`\`
 
+The application will be available at http://localhost:5173.
+
 ## Project Structure
 
 \`\`\`
 ${applicationName}/
-├── feltdb/
+├── feltdb/                 # FeltDB configuration and logic
 │   ├── agents/            # Agent definitions
 │   ├── capabilities/      # Capability implementations
 │   ├── workflows/         # Workflow definitions
 │   └── schema/            # Data schemas
-├── src/
+├── src/                   # Application source code
 │   ├── App.${framework === 'react' ? 'tsx' : 'js'}
-│   ├── feltdb.ts
+│   ├── feltdb.ts          # FeltDB client initialization
 │   └── index.${framework === 'react' ? 'tsx' : 'js'}
-├── public/
+├── 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
 \`\`\`
 
+## 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} (browser|node|self-hosted)
+- \`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
@@ -610,29 +1794,69 @@ 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
 \`\`\`
 
+## 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 ? `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 ? `### 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
 
-## Capabilities
+### 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\`
 
-${capabilities}
+### 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
 
-Visit [FeltDB Documentation](https://github.com/rkendel1/feltdb) to 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);
 }