synthos 0.8.0 → 0.10.0

package/src/service/useApiRoutes.ts

@@ -1,8 +1,7 @@
 import path from "path";
-import fs from "fs/promises";
 import AdmZip from "adm-zip";
-import { listPages, loadPageMetadata, PageMetadata, savePageMetadata, REQUIRED_PAGES, deletePage, copyPage, loadPageState, savePageState, PAGE_VERSION } from "../pages";
-import { checkIfExists, copyFile, copyFolderRecursive, deleteFile, ensureFolderExists, loadFile } from "../files";
+import { listPages, loadPageMetadata, PageMetadata, savePageMetadata, deletePage, copyPage, savePageState, clearVersions, PAGE_VERSION } from "../pages";
+import { checkIfExists, findFileInFolders, listFiles, listFolders, loadFile } from "../files";
 import {getModelEntry, loadSettings, saveSettings, ServicesConfig } from "../settings";
 import { Application } from 'express';
 import express from 'express';
@@ -12,9 +11,10 @@ import { generateDefaultImage, generateImage } from "./generateImage";
 import { chainOfThought } from "../models";
 import { requiresSettings } from "./requiresSettings";
 import { executeScript } from "../scripts";
-import { listThemes, loadTheme, loadThemeInfo } from "../themes";
+import { listThemes, loadTheme, loadThemeInfo, loadThemeVersion } from "../themes";
 import { migratePage } from "../migrations";
 import { loadPageWithFallback } from "./usePageRoutes";
+import { Customizer } from "../customizer";
 
 // ---------------------------------------------------------------------------
 // Service registry
@@ -48,10 +48,12 @@ const SERVICE_REGISTRY: ServiceDefinition[] = [
     }
 ];
 
-export function useApiRoutes(config: SynthOSConfig, app: Application): void {
+export function useApiRoutes(config: SynthOSConfig, app: Application, customizer?: Customizer): void {
+    const sp = config.storageProvider;
+
     // List pages
     app.get('/api/pages', async (req, res) => {
-        const pages = await listPages(config.pagesFolder, config.requiredPagesFolder);
+        const pages = await listPages(config, config.requiredPagesFolders);
         res.json(pages);
     });
 
@@ -97,13 +99,13 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             // Auto-append _1, _2, etc. on name conflicts
             let finalName = pageName;
             let suffix = 0;
-            while (await checkIfExists(path.join(config.pagesFolder, 'pages', finalName))) {
+            while (await sp.checkIfExists(path.join(config.pagesFolder, 'pages', finalName))) {
                 suffix++;
                 finalName = `${pageName}_${suffix}`;
             }
 
             const targetDir = path.join(config.pagesFolder, 'pages', finalName);
-            await ensureFolderExists(targetDir);
+            await sp.ensureFolderExists(targetDir);
 
             // Extract entries with path traversal protection
             for (const entry of entries) {
@@ -119,13 +121,13 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
                     continue;
                 }
 
-                await ensureFolderExists(path.dirname(resolvedPath));
-                await fs.writeFile(resolvedPath, entry.getData());
+                await sp.ensureFolderExists(path.dirname(resolvedPath));
+                await sp.saveBuffer(resolvedPath, entry.getData());
             }
 
             // Update metadata: set createdDate and lastModified to now
             const now = new Date().toISOString();
-            const existingMeta = await loadPageMetadata(config.pagesFolder, finalName);
+            const existingMeta = await loadPageMetadata(config, finalName);
             const metadata: PageMetadata = {
                 title: existingMeta?.title ?? '',
                 categories: existingMeta?.categories ?? [],
@@ -136,7 +138,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
                 pageVersion: existingMeta?.pageVersion ?? PAGE_VERSION,
                 mode: existingMeta?.mode ?? 'unlocked',
             };
-            await savePageMetadata(config.pagesFolder, finalName, metadata);
+            await savePageMetadata(config, finalName, metadata);
 
             res.status(201).json({ name: finalName, title: metadata.title });
         } catch (err: unknown) {
@@ -149,7 +151,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
     app.get('/api/pages/:name', async (req, res) => {
         try {
             const { name } = req.params;
-            const metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            const metadata = await loadPageMetadata(config, name, config.requiredPagesFolders);
             if (metadata) {
                 res.json(metadata);
             } else {
@@ -200,7 +202,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             }
 
             // Load existing metadata (or defaults)
-            const existing = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            const existing = await loadPageMetadata(config, name, config.requiredPagesFolders);
             const metadata: PageMetadata = {
                 title: existing?.title ?? '',
                 categories: existing?.categories ?? [],
@@ -225,15 +227,23 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             // Promote required page to user folder if being unlocked/designed
             if (metadata.mode !== 'locked') {
                 const userPagePath = path.join(config.pagesFolder, 'pages', name, 'page.html');
-                if (!(await checkIfExists(userPagePath))) {
-                    const html = await loadPageState(config.requiredPagesFolder, name, false);
+                if (!(await sp.checkIfExists(userPagePath))) {
+                    // Read from required pages (package content, always local fs)
+                    let html: string | undefined;
+                    for (const folder of config.requiredPagesFolders) {
+                        const candidate = path.join(folder, name, 'page.html');
+                        if (await checkIfExists(candidate)) {
+                            html = await loadFile(candidate);
+                            break;
+                        }
+                    }
                     if (html) {
-                        await savePageState(config.pagesFolder, name, html);
+                        await savePageState(config, name, html);
                     }
                 }
             }
 
-            await savePageMetadata(config.pagesFolder, name, metadata);
+            await savePageMetadata(config, name, metadata);
             res.json(metadata);
         } catch (err: unknown) {
             console.error(err);
@@ -252,7 +262,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             }
 
             // Load existing metadata (user override → fallback .json → defaults)
-            let metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            let metadata = await loadPageMetadata(config, name, config.requiredPagesFolders);
             if (!metadata) {
                 metadata = {
                     title: '',
@@ -267,7 +277,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             }
 
             metadata.pinned = pinned;
-            await savePageMetadata(config.pagesFolder, name, metadata);
+            await savePageMetadata(config, name, metadata);
             res.json(metadata);
         } catch (err: unknown) {
             console.error(err);
@@ -281,7 +291,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             const { name } = req.params;
 
             // Cannot delete required pages
-            if (REQUIRED_PAGES.includes(name)) {
+            if (config.requiredPages.includes(name)) {
                 res.status(400).json({ error: `Cannot delete required page "${name}"` });
                 return;
             }
@@ -289,13 +299,13 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             // Check if page exists (folder-based or legacy flat file)
             const folderPath = path.join(config.pagesFolder, 'pages', name, 'page.html');
             const flatPath = path.join(config.pagesFolder, `${name}.html`);
-            const exists = await checkIfExists(folderPath) || await checkIfExists(flatPath);
+            const exists = await sp.checkIfExists(folderPath) || await sp.checkIfExists(flatPath);
             if (!exists) {
                 res.status(404).json({ error: `Page "${name}" not found` });
                 return;
             }
 
-            await deletePage(config.pagesFolder, name);
+            await deletePage(config, name);
             res.json({ deleted: true });
         } catch (err: unknown) {
             console.error(err);
@@ -303,11 +313,65 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
         }
     });
 
+    // Discover what a page contains (tables + files)
+    app.get('/api/pages/:name/contents', async (req, res) => {
+        try {
+            const { name } = req.params;
+
+            // Resolve page folder: user pages first, then required pages
+            let pageFolder: string | undefined;
+            const userFolder = path.join(config.pagesFolder, 'pages', name);
+            if (await sp.checkIfExists(path.join(userFolder, 'page.html'))) {
+                pageFolder = userFolder;
+            } else {
+                for (const folder of config.requiredPagesFolders) {
+                    const candidate = path.join(folder, name);
+                    if (await checkIfExists(path.join(candidate, 'page.html'))) {
+                        pageFolder = candidate;
+                        break;
+                    }
+                }
+            }
+
+            if (!pageFolder) {
+                res.status(404).json({ error: `Page "${name}" not found` });
+                return;
+            }
+
+            // List subdirectories, filtering out non-table entries
+            const EXCLUDED = new Set(['files']);
+            // Use provider for user folder, local fs for required pages
+            const isUserFolder = pageFolder === userFolder;
+            const subdirs = isUserFolder
+                ? await sp.listFolders(pageFolder)
+                : await listFolders(pageFolder);
+            const tables = subdirs.filter(d => !EXCLUDED.has(d));
+
+            // Check if files/ exists and has entries
+            const filesDir = path.join(pageFolder, 'files');
+            let hasFiles = false;
+            const filesDirExists = isUserFolder
+                ? await sp.checkIfExists(filesDir)
+                : await checkIfExists(filesDir);
+            if (filesDirExists) {
+                const entries = isUserFolder
+                    ? await sp.listFiles(filesDir)
+                    : await listFiles(filesDir);
+                hasFiles = entries.length > 0;
+            }
+
+            res.json({ tables, hasFiles });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
     // Copy a page to a new name
     app.post('/api/pages/:name/copy', async (req, res) => {
         try {
             const sourceName = req.params.name;
-            const { name: targetName, title, categories } = req.body;
+            const { name: targetName, title, categories, copyTables, copyFiles } = req.body;
 
             // Validate target name
             if (!targetName || typeof targetName !== 'string') {
@@ -329,10 +393,14 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             // Check source exists (user pages → required pages)
             const sourceFolderPath = path.join(config.pagesFolder, 'pages', sourceName, 'page.html');
             const sourceFlatPath = path.join(config.pagesFolder, `${sourceName}.html`);
-            const sourceRequiredPath = path.join(config.requiredPagesFolder, `${sourceName}.html`);
-            const sourceExists = await checkIfExists(sourceFolderPath)
-                || await checkIfExists(sourceFlatPath)
-                || await checkIfExists(sourceRequiredPath);
+            let sourceRequiredPath: string | undefined;
+            for (const folder of config.requiredPagesFolders) {
+                const candidate = path.join(folder, sourceName, 'page.html');
+                if (await checkIfExists(candidate)) { sourceRequiredPath = candidate; break; }
+            }
+            const sourceExists = await sp.checkIfExists(sourceFolderPath)
+                || await sp.checkIfExists(sourceFlatPath)
+                || !!sourceRequiredPath;
             if (!sourceExists) {
                 res.status(404).json({ error: `Source page "${sourceName}" not found` });
                 return;
@@ -341,22 +409,26 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             // Check target doesn't already exist
             const targetFolderPath = path.join(config.pagesFolder, 'pages', targetName, 'page.html');
             const targetFlatPath = path.join(config.pagesFolder, `${targetName}.html`);
-            if (await checkIfExists(targetFolderPath) || await checkIfExists(targetFlatPath)) {
+            if (await sp.checkIfExists(targetFolderPath) || await sp.checkIfExists(targetFlatPath)) {
                 res.status(409).json({ error: `Page "${targetName}" already exists` });
                 return;
             }
 
             await copyPage(
-                config.pagesFolder,
+                config,
                 sourceName,
                 targetName,
                 typeof title === 'string' ? title : '',
                 Array.isArray(categories) ? categories : [],
-                config.requiredPagesFolder
+                config.requiredPagesFolders,
+                {
+                    copyTables: copyTables === true,
+                    copyFiles: copyFiles !== false, // default true
+                }
             );
 
             // Return the new page metadata
-            const metadata = await loadPageMetadata(config.pagesFolder, targetName);
+            const metadata = await loadPageMetadata(config, targetName);
             res.status(201).json({ name: targetName, ...metadata });
         } catch (err: unknown) {
             console.error(err);
@@ -366,7 +438,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
 
     // Define a route to return settings
     app.get('/api/settings', async (req, res) => {
-        const settings = await loadSettings(config.pagesFolder);
+        const settings = await loadSettings(config);
         const providers = PROVIDERS.map(p => ({ name: p.name, builderModels: p.builderModels, chatModels: p.chatModels }));
         res.json({...settings, providers});
     });
@@ -387,7 +459,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             }
 
             // Save settings
-            await saveSettings(config.pagesFolder, settings);
+            await saveSettings(config, settings);
             res.redirect('/builder');
         } catch (err: unknown) {
             console.error(err);
@@ -397,7 +469,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
 
     // Define a route to generate an image
     app.post('/api/generate/image', async (req, res) => {
-        await requiresSettings(res, config.pagesFolder, async (settings) => {
+        await requiresSettings(res, config, async (settings) => {
             const { prompt, shape, style } = req.body;
             const builder = getModelEntry(settings, 'builder');
             const { configuration, imageQuality, provider } = builder;
@@ -414,9 +486,9 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
 
     // Define a route to generate a completion using chain-of-thought
     app.post('/api/generate/completion', async (req, res) => {
-        await requiresSettings(res, config.pagesFolder, async (settings) => {
+        await requiresSettings(res, config, async (settings) => {
             const { prompt, temperature } = req.body;
-            const completePrompt = await createCompletePrompt(config.pagesFolder, 'chat', req.body.model);
+            const completePrompt = await createCompletePrompt(config, 'chat', req.body.model);
             const response = await chainOfThought({ question: prompt, temperature, completePrompt });
             if (response.completed) {
                 res.json(response.value ?? {});
@@ -428,16 +500,18 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
     });
 
     // Brainstorm endpoint
+    if (!customizer || customizer.isEnabled('brainstorm'))
     app.post('/api/brainstorm', async (req, res) => {
-        await requiresSettings(res, config.pagesFolder, async (settings) => {
+        await requiresSettings(res, config, async (settings) => {
             const { context, messages } = req.body;
-            const completePrompt = await createCompletePrompt(config.pagesFolder, 'chat');
+            const completePrompt = await createCompletePrompt(config, 'chat');
 
+            const productName = customizer?.productName ?? 'SynthOS';
             const system: { role: 'system'; content: string } = {
                 role: 'system',
-                content: `You are a creative brainstorming assistant for SynthOS, a tool that builds pages through conversation.
-SynthOS is like a WIKI for vibe coding. Each page has a chat panel and a viewer panel. They are vibe coding what's displayed in that viewer panel. They can then save that as a page.
-The user is brainstorming — exploring ideas before building. Be concise, creative, and collaborative. 
+                content: `You are a creative brainstorming assistant for ${productName}, a tool that builds pages through conversation.
+${productName} is like a WIKI for vibe coding. Each page has a chat panel and a viewer panel. They are vibe coding what's displayed in that viewer panel. They can then save that as a page.
+The user is brainstorming — exploring ideas before building. Be concise, creative, and collaborative.
 They may say that they want to build an app or page that does XYZ but they're talking about what they expect to see in the viewer panel.
 The goal is to help them generate a prompt for the builder that captures their vision, along with suggestions for next steps.
 Suggest concrete approaches when you can, not complex visions for some ellaborate app.
@@ -448,14 +522,14 @@ ${context}
 
 <INSTRUCTIONS>
 Look at the <CHAT_HISTORY> and if it's empty it's the start of a new idea. Simply greet them and ask them what they're thinking of building. Suggestions could be help me decide, etc.
-If you see a conversation between SynthOS and the User. Asses what they're building and ask them what they'd like help with. Maybe offer a few good next steps.
+If you see a conversation between ${productName} and the User. Asses what they're building and ask them what they'd like help with. Maybe offer a few good next steps.
 
-SynthOS exposes table storage and chat completion api's that every page can use. If the user wants to store something or use AI, your prompt should suggest using table storage or make llm calls.
+${productName} exposes table storage and chat completion api's that every page can use. If the user wants to store something or use AI, your prompt should suggest using table storage or make llm calls.
 
 You MUST return your response as a JSON object with exactly these fields:
 {
   "response": "Your conversational reply — explanations, options, suggestions. Markdown OK.",
-  "prompt": "A clean, actionable instruction ready to paste into SynthOS chat to build what was discussed. Update this each exchange to reflect the latest brainstorm state.",
+  "prompt": "A clean, actionable instruction ready to paste into ${productName} chat to build what was discussed. Update this each exchange to reflect the latest brainstorm state.",
   "suggestions": ["Short clickable option A", "Short clickable option B", "Short clickable option C"]
 }
 
@@ -495,12 +569,12 @@ Return ONLY the JSON object.`};
     });
 
     // Define a route for running configured scripts
+    if (!customizer || customizer.isEnabled('scripts'))
     app.post('/api/scripts/:id', async (req, res) => {
-        await requiresSettings(res, config.pagesFolder, async (settings) => {
+        await requiresSettings(res, config, async (settings) => {
             const { id } = req.params;
-            const pagesFolder = config.pagesFolder;
             const scriptId = id;
-            const response = await executeScript({ pagesFolder, scriptId, variables: req.body });
+            const response = await executeScript({ pagesFolder: config.pagesFolder, scriptId, variables: req.body });
             if (response.completed) {
                 // Return the response as text
                 const value = (response.value?.output ?? (response.value?.errors ?? []).join('\n')).trim();
@@ -516,14 +590,20 @@ Return ONLY the JSON object.`};
     // Return theme info as a self-executing JS script
     app.get('/api/theme-info.js', async (req, res) => {
         try {
-            const settings = await loadSettings(config.pagesFolder);
+            const settings = await loadSettings(config);
             const themeName = settings.theme ?? 'nebula-dusk';
             const info = await loadThemeInfo(themeName, config);
             if (!info) {
                 res.status(404).send(`// Theme info for "${themeName}" not found`);
                 return;
             }
-            const js = `window.themeInfo=${JSON.stringify(info)};document.documentElement.classList.add(window.themeInfo.mode+"-mode");`;
+            const themeVersion = await loadThemeVersion(themeName, config);
+            const payload = { ...info, name: themeName, version: themeVersion };
+            let js = `window.themeInfo=${JSON.stringify(payload)};document.documentElement.classList.add(window.themeInfo.mode+"-mode");`;
+            if (themeVersion >= 3) {
+                js += `document.documentElement.classList.add(${JSON.stringify(themeName)});`;
+            }
+            js += `document.documentElement.setAttribute("data-toolbar",${JSON.stringify(settings.toolbarPosition || 'left')});`;
             res.set('Content-Type', 'application/javascript');
             res.send(js);
         } catch (err: unknown) {
@@ -540,21 +620,18 @@ Return ONLY the JSON object.`};
                 res.status(400).send('// Missing page query parameter');
                 return;
             }
-            const metadata = await loadPageMetadata(config.pagesFolder, page, config.requiredPagesFolder);
+            const metadata = await loadPageMetadata(config, page, config.requiredPagesFolders);
             const mode = metadata?.mode ?? 'unlocked';
             const title = metadata?.title ?? '';
             const categories = metadata?.categories ?? [];
-            const info = JSON.stringify({ name: page, mode, latestPageVersion: PAGE_VERSION, title, categories });
+            const isRequiredPage = config.requiredPages.includes(page);
+            const productName = customizer?.productName ?? 'SynthOS';
+            const info = JSON.stringify({ name: page, mode, latestPageVersion: PAGE_VERSION, title, categories, isRequiredPage, productName });
             const js = [
                 `window.pageInfo=${info};`,
                 `if(window.pageInfo.mode==="locked"){`,
                 `document.addEventListener("DOMContentLoaded",function(){`,
                 `var f=document.getElementById("chatForm");if(f)f.style.display="none";`,
-                `var s=document.getElementById("saveLink");if(s)s.textContent="Copy";`,
-                `var r=document.getElementById("resetLink");if(r){`,
-                `var c=r.cloneNode(true);c.textContent="Reload";`,
-                `c.addEventListener("click",function(e){e.preventDefault();window.location.href=window.location.pathname;});`,
-                `r.parentNode.replaceChild(c,r);}`,
                 `});`,
                 `}`,
             ].join('');
@@ -570,7 +647,7 @@ Return ONLY the JSON object.`};
     // Return the current theme as CSS
     app.get('/api/theme.css', async (req, res) => {
         try {
-            const settings = await loadSettings(config.pagesFolder);
+            const settings = await loadSettings(config);
             const themeName = settings.theme ?? 'nebula-dusk';
             const css = await loadTheme(themeName, config);
             if (!css) {
@@ -604,8 +681,8 @@ Return ONLY the JSON object.`};
                 res.status(400).send('// Invalid version parameter');
                 return;
             }
-            const scriptPath = path.join(config.pageScriptsFolder, `page-v${v}.js`);
-            if (!(await checkIfExists(scriptPath))) {
+            const scriptPath = await findFileInFolders(config.staticFilesFolders, `page.v${v}.js`);
+            if (!scriptPath) {
                 res.status(404).send(`// page-v${v}.js not found`);
                 return;
             }
@@ -627,8 +704,8 @@ Return ONLY the JSON object.`};
                 res.status(400).send('// Invalid version parameter');
                 return;
             }
-            const scriptPath = path.join(config.pageScriptsFolder, `helpers-v${v}.js`);
-            if (!(await checkIfExists(scriptPath))) {
+            const scriptPath = await findFileInFolders(config.staticFilesFolders, `helpers.v${v}.js`);
+            if (!scriptPath) {
                 res.status(404).send(`// helpers-v${v}.js not found`);
                 return;
             }
@@ -654,7 +731,7 @@ Return ONLY the JSON object.`};
     // Return user's configured services (API keys masked)
     app.get('/api/services', async (_req, res) => {
         try {
-            const settings = await loadSettings(config.pagesFolder);
+            const settings = await loadSettings(config);
             const services = settings.services ?? {};
             const masked: Record<string, { enabled: boolean; hasKey: boolean }> = {};
             for (const [id, cfg] of Object.entries(services)) {
@@ -674,7 +751,7 @@ Return ONLY the JSON object.`};
     app.post('/api/services', async (req, res) => {
         try {
             const incoming = req.body as ServicesConfig;
-            const settings = await loadSettings(config.pagesFolder);
+            const settings = await loadSettings(config);
             const existing = settings.services ?? {};
 
             // Build merged config — empty apiKey means "keep existing"
@@ -695,7 +772,7 @@ Return ONLY the JSON object.`};
                 }
             }
 
-            await saveSettings(config.pagesFolder, { services: merged });
+            await saveSettings(config, { services: merged });
             res.json({ saved: true });
         } catch (err: unknown) {
             console.error(err);
@@ -707,6 +784,7 @@ Return ONLY the JSON object.`};
     // Web Search (Brave Search API)
     // -----------------------------------------------------------------------
 
+    if (!customizer || customizer.isEnabled('search'))
     app.post('/api/search/web', async (req, res) => {
         try {
             const { query, count, country, freshness } = req.body;
@@ -715,7 +793,7 @@ Return ONLY the JSON object.`};
                 return;
             }
 
-            const settings = await loadSettings(config.pagesFolder);
+            const settings = await loadSettings(config);
             const braveConfig = settings.connectors?.['brave-search'] ?? settings.services?.['brave-search'];
             if (!braveConfig || !braveConfig.enabled || !braveConfig.apiKey) {
                 res.status(400).json({ error: 'Brave Search is not configured or not enabled. Add your API key in Settings > Services.' });
@@ -761,7 +839,7 @@ Return ONLY the JSON object.`};
             const { name } = req.params;
 
             // Load current metadata
-            const metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            const metadata = await loadPageMetadata(config, name, config.requiredPagesFolders);
             if (!metadata) {
                 res.status(404).json({ error: `Page "${name}" not found` });
                 return;
@@ -781,32 +859,37 @@ Return ONLY the JSON object.`};
             }
 
             // Run LLM-based migration
-            const completePrompt = await createCompletePrompt(config.pagesFolder, 'builder');
+            const completePrompt = await createCompletePrompt(config, 'builder');
             const migratedHtml = await migratePage(html, currentVersion, PAGE_VERSION, completePrompt);
 
             // Save upgraded HTML to v2 folder structure
-            await savePageState(config.pagesFolder, name, migratedHtml);
+            await savePageState(config, name, migratedHtml);
 
             // Backup original page to .migrated/ before overwriting
             const migratedFolder = path.join(config.pagesFolder, '.migrated');
 
-            // Handle legacy flat file (.synthos/pagename.html)
+            // Handle legacy flat file (<localFolder>/pagename.html)
             const flatPath = path.join(config.pagesFolder, `${name}.html`);
-            if (await checkIfExists(flatPath)) {
-                await copyFile(flatPath, migratedFolder);
-                await deleteFile(flatPath);
+            if (await sp.checkIfExists(flatPath)) {
+                await sp.ensureFolderExists(migratedFolder);
+                const flatData = await sp.loadBuffer(flatPath);
+                await sp.saveBuffer(path.join(migratedFolder, `${name}.html`), flatData);
+                await sp.deleteFile(flatPath);
             }
 
-            // Handle folder-based page (.synthos/pages/name/)
+            // Handle folder-based page (<localFolder>/pages/name/)
             const folderPath = path.join(config.pagesFolder, 'pages', name);
-            if (await checkIfExists(folderPath)) {
-                await copyFolderRecursive(folderPath, path.join(migratedFolder, name));
+            if (await sp.checkIfExists(folderPath)) {
+                await sp.copyFolderRecursive(folderPath, path.join(migratedFolder, name));
             }
 
+            // Clear stale version files (undo snapshots from the old page version)
+            await clearVersions(config, name);
+
             // Update metadata
             metadata.pageVersion = PAGE_VERSION;
             metadata.lastModified = new Date().toISOString();
-            await savePageMetadata(config.pagesFolder, name, metadata);
+            await savePageMetadata(config, name, metadata);
 
             res.json({ upgraded: true, fromVersion: currentVersion, toVersion: PAGE_VERSION });
         } catch (err: unknown) {
@@ -822,21 +905,27 @@ Return ONLY the JSON object.`};
 
             // Try user pages folder first, then required pages
             const userPageDir = path.join(config.pagesFolder, 'pages', name);
-            const requiredPageFile = path.join(config.requiredPagesFolder, `${name}.html`);
+            let requiredPageDir: string | undefined;
+            for (const folder of config.requiredPagesFolders) {
+                if (await checkIfExists(path.join(folder, name, 'page.html'))) {  // package content, local fs
+                    requiredPageDir = path.join(folder, name);
+                    break;
+                }
+            }
             let sourceDir: string | null = null;
 
-            if (await checkIfExists(path.join(userPageDir, 'page.html'))) {
+            if (await sp.checkIfExists(path.join(userPageDir, 'page.html'))) {
                 sourceDir = userPageDir;
-            } else if (await checkIfExists(requiredPageFile)) {
+            } else if (requiredPageDir) {
                 // For required pages, create a temp-like zip with just the HTML
                 const zip = new AdmZip();
-                const html = await loadFile(requiredPageFile);
+                const html = await loadFile(path.join(requiredPageDir, 'page.html'));
                 zip.addFile(`${name}/page.html`, Buffer.from(html, 'utf-8'));
 
                 // Include page.json if it exists
-                const requiredMetaFile = path.join(config.requiredPagesFolder, `${name}.json`);
-                if (await checkIfExists(requiredMetaFile)) {
-                    const meta = await loadFile(requiredMetaFile);
+                const metaPath = path.join(requiredPageDir, 'page.json');
+                if (await checkIfExists(metaPath)) {
+                    const meta = await loadFile(metaPath);
                     zip.addFile(`${name}/page.json`, Buffer.from(meta, 'utf-8'));
                 }
 
@@ -863,4 +952,39 @@ Return ONLY the JSON object.`};
             res.status(500).json({ error: (err as Error).message });
         }
     });
+
+    // Ask a question about a page (with full page HTML context)
+    app.post('/api/pages/:name/ask', async (req, res) => {
+        await requiresSettings(res, config, async (settings) => {
+            const { name } = req.params;
+            const { question } = req.body;
+            if (typeof question !== 'string' || !question.trim()) {
+                res.status(400).json({ error: 'question is required' });
+                return;
+            }
+
+            // Load the page HTML
+            const html = await loadPageWithFallback(name, config, false);
+            if (!html) {
+                res.status(404).json({ error: `Page "${name}" not found` });
+                return;
+            }
+
+            // Create completion (uses 'chat' model, not 'builder')
+            const complete = await createCompletePrompt(config, 'chat', req.body.model);
+
+            const system = {
+                role: 'system' as const,
+                content: `You are a helpful assistant. The user will ask questions about a web page. Answer based on the page content provided.\n\n<PAGE_HTML>\n${html}`
+            };
+            const prompt = { role: 'user' as const, content: question };
+
+            const result = await complete({ system, prompt });
+            if (result.completed) {
+                res.json({ answer: result.value });
+            } else {
+                res.status(500).json({ error: result.error?.message || 'Completion failed' });
+            }
+        });
+    });
 }