synthos 0.8.0 → 0.10.0

package/src/service/transformPage.ts

@@ -1,29 +1,24 @@
-import { AgentArgs, AgentCompletion, SystemMessage, UserMessage } from "../models";
-import { listScripts } from "../scripts";
+import { AgentCompletion } from "../models";
 import * as cheerio from "cheerio";
-import { ThemeInfo } from "../themes";
-import { CONNECTOR_REGISTRY, ConnectorsConfig, ConnectorOAuthConfig } from "../connectors";
-import { AgentConfig } from "../agents";
+import { Customizer } from "../customizer";
+import { Attachment, Builder, ContextSection } from "../builders/types";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export interface TransformPageArgs extends AgentArgs {
-    pagesFolder: string;
+export interface TransformPageArgs {
     pageState: string;
     message: string;
     instructions?: string;
-    /** Provider-specific formatting instructions injected into the prompt. */
-    modelInstructions?: string;
-    /** Active theme metadata for theme-aware page generation. */
-    themeInfo?: ThemeInfo;
-    /** Page mode. */
-    mode?: 'unlocked' | 'locked';
-    /** User's configured connectors (from settings). */
-    configuredConnectors?: ConnectorsConfig;
-    /** User's configured A2A agents (from settings). */
-    configuredAgents?: AgentConfig[];
+    builder: Builder;
+    additionalSections: ContextSection[];
+    /** True when this is the builder page (has chat panel). */
+    isBuilder?: boolean;
+    /** Product name for branding in prompts (defaults to 'SynthOS'). */
+    productName?: string;
+    /** Optional image attachments sent alongside the user message. */
+    attachments?: Attachment[];
 }
 
 export type ChangeOp =
@@ -31,20 +26,12 @@ export type ChangeOp =
     | { op: "replace"; nodeId: string; html: string }
     | { op: "delete"; nodeId: string }
     | { op: "insert"; parentId: string; position: "prepend" | "append" | "before" | "after"; html: string }
-    | { op: "style-element"; nodeId: string; style: string };
+    | { op: "style-element"; nodeId: string; style: string }
+    | { op: "search-replace"; nodeId: string; search: string; replace: string }
+    | { op: "search-insert"; nodeId: string; after: string; content: string };
 
 export type ChangeList = ChangeOp[];
 
-interface FailedOp {
-    op: ChangeOp;
-    reason: string;
-}
-
-interface ApplyResult {
-    html: string;
-    failedOps: FailedOp[];
-}
-
 // ---------------------------------------------------------------------------
 // Public entry point
 // ---------------------------------------------------------------------------
@@ -55,167 +42,179 @@ export interface TransformPageResult {
 }
 
 export async function transformPage(args: TransformPageArgs): Promise<AgentCompletion<TransformPageResult>> {
-    const { pagesFolder, pageState, message, completePrompt } = args;
+    const { message, builder, additionalSections } = args;
+
+    // 0. Strip the early error-capture script so the LLM never sees it
+    const pageState = stripErrorCapture(args.pageState);
 
     // 1. Assign data-node-id to every element
     const { html: annotatedHtml } = assignNodeIds(pageState);
 
     try {
-        // 2. Build prompt
-        const scripts = await listScripts(pagesFolder);
-        const serverScripts = `<SERVER_SCRIPTS>\n${scripts || ''}`;
-        const currentPage = `<CURRENT_PAGE>\n${annotatedHtml}`;
-
-        // Build theme context block
-        let themeBlock = '<THEME>\n';
-        if (args.themeInfo) {
-            const { mode, colors } = args.themeInfo;
-            const colorList = Object.entries(colors)
-                .map(([name, value]) => `  --${name}: ${value}`)
-                .join('\n');
-            themeBlock += `Mode: ${mode}\nCSS custom properties (use instead of hardcoded values):\n${colorList}\n\nShared shell classes (pre-styled by theme, do not redefine):\n  .chat-panel — Left sidebar container (30% width)\n  .chat-header — Chat panel title bar\n  .chat-messages — Scrollable message container\n  .chat-message — Individual message wrapper\n  .link-group — Navigation links row (Save, Pages, Reset)\n  .chat-input — Message text input\n  .chat-submit — Send button\n  .viewer-panel — Right content area (70% width)\n  .loading-overlay — Full-screen loading overlay\n  .spinner — Animated loading spinner\n  .modal-overlay — Full-screen modal backdrop (position:fixed, z-index:2000, backdrop-filter:blur). Add class "show" to display.\n  .modal-content — Centered modal container\n  .modal-header — Gradient header bar\n  .modal-body — Modal content area\n  .modal-footer — Bottom action bar (flex, space-between)\n  .modal-footer-right — Right-aligned button group\n\nModals and popups: ALWAYS use the theme\'s .modal-overlay class for any modal or popup overlay. Do NOT create custom overlay classes with position:fixed and z-index. Structure:\n  <div class="modal-overlay" id="myModal">\n    <div class="modal-content">\n      <div class="modal-header">Title</div>\n      <div class="modal-body">Content</div>\n      <div class="modal-footer"><div class="modal-footer-right"><button>OK</button></div></div>\n    </div>\n  </div>\nShow/hide by toggling the "show" class: el.classList.add(\'show\') / el.classList.remove(\'show\'). This ensures correct z-index layering above the chat toggle and other UI elements.\n\nPage title bars: To align with the chat header, apply these styles:\n  min-height: var(--header-min-height);\n  padding: var(--header-padding-vertical) var(--header-padding-horizontal);\n  line-height: var(--header-line-height);\n  display: flex; align-items: center; justify-content: center; box-sizing: border-box;\n\nFull-viewer mode: For games, animations, or full-screen content, add class "full-viewer" to the viewer-panel element to remove its padding.\n\nChat panel behaviours (auto-injected via page script — do NOT recreate in page code):\n  The server injects page-v2.js after transformation. It provides:\n  - Form submit handler: sets action to window.location.pathname, shows #loadingOverlay, disables inputs\n  - Save/Reset link handlers (#saveLink, #resetLink)\n  - Chat scroll to bottom (#chatMessages)\n  - Chat toggle button (.chat-toggle) — created dynamically if not in markup\n  - .chat-input-wrapper — wraps #chatInput with a brainstorm icon button\n  - Brainstorm modal (#brainstormModal) — LLM-powered brainstorm UI, created dynamically\n  - Focus management — keeps keyboard input directed to #chatInput\n\n  Do NOT:\n  - Create your own form submit handler, toggle button, or input wrapper\n  - Modify or replace .chat-panel, .chat-header, .link-group, #chatForm, or .chat-toggle\n  - INSERT new <script> blocks that duplicate existing ones — when fixing JavaScript, UPDATE or REPLACE the existing script's nodeId instead. Always give inline scripts a unique id attribute.\n  - Set the form action attribute (page-v2.js sets it dynamically)\n  - Include these CSS rules (in the theme): #loadingOverlay position, .chat-submit:disabled, .chat-input:disabled\n\n  To add chat messages: use insert with parentId of #chatMessages and position "append".\n  #chatMessages is the only unlocked element inside .chat-panel.\n\nThe <html> element has class "${mode}-mode". Always add .light-mode CSS overrides for any page-specific styles so the page works in both light and dark themes, unless the user has explicitly requested a very specific color scheme.`;
+        // 2. Build CURRENT_PAGE section
+        const currentPage: ContextSection = {
+            title: '<CURRENT_PAGE>',
+            content: annotatedHtml,
+            instructions: '',
+        };
+
+        // 3. Determine newBuild: if isBuilder, count .chat-message in annotated HTML
+        let newBuild = false;
+        if (args.isBuilder) {
+            const $ = cheerio.load(annotatedHtml, { decodeEntities: false });
+            const messageCount = $('#chatMessages .chat-message').length;
+            newBuild = messageCount <= 1;
         }
 
-        // Build configured-connectors block
-        let connectorsBlock = '';
-        if (args.configuredConnectors) {
-            const entries = Object.entries(args.configuredConnectors)
-                .filter(([, cfg]) => cfg.enabled && cfg.apiKey);
-            if (entries.length > 0) {
-                const blocks = entries.map(([id, cfg]) => {
-                    const def = CONNECTOR_REGISTRY.find(d => d.id === id);
-                    if (!def) return `- ${id}`;
-                    let block = `- ${def.name} (id: "${id}", category: ${def.category})\n  Base URL: ${def.baseUrl}`;
-                    if (def.hints) {
-                        block += `\n  Usage:\n${def.hints.split('\n').map(l => '    ' + l).join('\n')}`;
-                    }
-                    // Append dynamic OAuth context
-                    if (def.authStrategy === 'oauth2') {
-                        const oauthCfg = cfg as ConnectorOAuthConfig;
-                        block += '\n  Auth: The proxy attaches the access token automatically. Do NOT pass access_token in body or query params.';
-                        if (oauthCfg.userId) {
-                            block += `\n  User ID: ${oauthCfg.userId} — use this directly in API paths (e.g. /${oauthCfg.userId}/media).`;
-                        } else {
-                            block += '\n  User ID: Not yet resolved. Call GET /me/accounts to discover it, then GET /{page-id}?fields=instagram_business_account to get the IG user ID.';
-                        }
-                    }
-                    return block;
-                });
-                connectorsBlock = `<CONFIGURED_CONNECTORS>\nThe user has configured and enabled these connectors:\n${blocks.join('\n\n')}\n\nYou may use synthos.connectors.call(connector, method, path, opts) to call them.\nIMPORTANT: Before making any connector call, ALWAYS check that the connector is configured first using synthos.connectors.list(). If the connector is not configured, show the user a friendly message with a link to the Settings > Connectors page (/settings?tab=connectors) so they can set it up.\nDo NOT hardcode API keys. The connector proxy attaches authentication automatically.`;
+        // 4. Call builder
+        const result = await builder.run(currentPage, additionalSections, message, newBuild, args.attachments);
+
+        // 5. Switch on result kind
+        switch (result.kind) {
+            case 'transforms': {
+                const applied = applyChangeList(annotatedHtml, result.changes);
+                const clean = stripNodeIds(applied);
+                const deduped = deduplicateInlineScripts(clean);
+                const safe = ensureScriptsBeforeBodyClose(deduped);
+                return { completed: true, value: { html: safe, changeCount: result.changes.length } };
+            }
+            case 'reply': {
+                const productName = args.productName ?? 'SynthOS';
+                const withReply = appendChatReply(annotatedHtml, message, result.text, productName);
+                const clean = stripNodeIds(withReply);
+                const deduped = deduplicateInlineScripts(clean);
+                const safe = ensureScriptsBeforeBodyClose(deduped);
+                return { completed: true, value: { html: safe, changeCount: -1 } };
+            }
+            case 'error': {
+                const productName = args.productName ?? 'SynthOS';
+                const errorHtml = appendChatError(annotatedHtml, message, result.error.message, productName);
+                const clean = stripNodeIds(errorHtml);
+                return { completed: true, value: { html: clean, changeCount: -1 } };
             }
         }
+    } catch (err: unknown) {
+        // On any error: append error message to chat
+        const productName = args.productName ?? 'SynthOS';
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const errorHtml = appendChatError(annotatedHtml, message, errorMessage, productName);
+        const clean = stripNodeIds(errorHtml);
+        return { completed: true, value: { html: clean, changeCount: -1 } };
+    }
+}
 
-        // Build configured-agents block (only enabled agents)
-        let agentsBlock = '';
-        const enabledAgents = (args.configuredAgents ?? []).filter(a => a.enabled);
-        if (enabledAgents.length > 0) {
-            const agentBlocks = enabledAgents.map(a => {
-                let block = `- ${a.name} (id: "${a.id}", provider: ${a.provider})`;
-                block += `\n  Description: ${a.description}`;
-                if (a.capabilities?.streaming) {
-                    block += `\n  Supports streaming: yes`;
-                }
-                if (a.skills && a.skills.length > 0) {
-                    const skillList = a.skills.map(s => `    - ${s.name}: ${s.description}`).join('\n');
-                    block += `\n  Skills:\n${skillList}`;
-                }
-                return block;
-            });
-            agentsBlock = `<CONFIGURED_AGENTS>\nThe user has configured these agents:\n\n${agentBlocks.join('\n\n')}\n\n${AGENT_API_REFERENCE}`;
-        }
+// ---------------------------------------------------------------------------
+// Chat reply helper
+// ---------------------------------------------------------------------------
 
-        const systemMessage = [currentPage, serverAPIs, serverScripts, connectorsBlock, agentsBlock, themeBlock, messageFormat].filter(s => s).join('\n\n');
-        const system: SystemMessage = {
-            role: 'system',
-            content: systemMessage
-        };
+/**
+ * Append a user message and a reply to #chatMessages using cheerio.
+ */
+function appendChatReply(annotatedHtml: string, userMessage: string, replyText: string, productName: string): string {
+    const $ = cheerio.load(annotatedHtml, { decodeEntities: false });
+    const chatMessages = $('#chatMessages');
+    if (chatMessages.length > 0) {
+        chatMessages.append(`<div class="chat-message"><p><strong>User:</strong> ${escapeHtml(userMessage)}</p></div>`);
+        const replyHtml = simpleMarkdown(replyText);
+        chatMessages.append(`<div class="chat-message"><p><strong>${escapeHtml(productName)}:</strong> ${replyHtml}</p></div>`);
+    }
+    return $.html();
+}
 
-        const userInstr = args.instructions || '';
-        const modelInstr = args.modelInstructions || '';
-        const instructions = [userInstr, modelInstr, transformInstr].filter(s => s.trim() !== '').join('\n');
-        const prompt: UserMessage = {
-            role: 'user',
-            content: `<USER_MESSAGE>\n${message}\n\n<INSTRUCTIONS>\n${instructions}`
-        };
+function escapeHtml(text: string): string {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+
+/**
+ * Lightweight markdown-to-HTML converter for chat reply text.
+ * Handles: code blocks, inline code, bold, italic, links, unordered/ordered lists, paragraphs.
+ */
+export function simpleMarkdown(text: string): string {
+    // Extract fenced code blocks first to protect their contents
+    const codeBlocks: string[] = [];
+    let processed = text.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang, code) => {
+        const idx = codeBlocks.length;
+        const escaped = escapeHtml(code.replace(/\n$/, ''));
+        const langAttr = lang ? ` class="language-${escapeHtml(lang)}"` : '';
+        codeBlocks.push(`<pre><code${langAttr}>${escaped}</code></pre>`);
+        return `\x00CODEBLOCK${idx}\x00`;
+    });
 
-        // 3. Call model
-        const result = await completePrompt({ prompt, system });
-        if (!result.completed) {
-            return { completed: false, error: result.error };
+    // Split into paragraphs by blank lines
+    const blocks = processed.split(/\n{2,}/);
+    const htmlBlocks: string[] = [];
+
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed) continue;
+
+        // Code block placeholder
+        if (/^\x00CODEBLOCK\d+\x00$/.test(trimmed)) {
+            htmlBlocks.push(trimmed);
+            continue;
         }
 
-        // 4. Parse JSON change list from response
-        const changes = parseChangeList(result.value);
-
-        // 5. Apply changes (first pass — with failure reporting)
-        const firstPass = applyChangeListWithReport(annotatedHtml, changes);
-        let finalHtml = firstPass.html;
-        let successCount = changes.length - firstPass.failedOps.length;
-
-        // 6. Repair pass — if any ops failed, make one follow-up LLM call
-        if (firstPass.failedOps.length > 0) {
-            console.warn(`transformPage: ${firstPass.failedOps.length} op(s) failed — attempting repair pass`);
-            try {
-                // Re-assign fresh node IDs on the partially-updated HTML
-                const { html: reAnnotatedHtml } = assignNodeIds(stripNodeIds(firstPass.html));
-
-                // Build compact repair prompt
-                const failedSummary = firstPass.failedOps
-                    .map((f, i) => `${i + 1}. op="${f.op.op}" — ${f.reason}\n   original: ${JSON.stringify(f.op)}`)
-                    .join('\n');
-
-                const repairSystem: SystemMessage = {
-                    role: 'system',
-                    content: `<CURRENT_PAGE>\n${reAnnotatedHtml}\n\n<FAILED_OPERATIONS>\n${failedSummary}`
-                };
-
-                const repairPrompt: UserMessage = {
-                    role: 'user',
-                    content: repairUSER_MESSAGE
-                };
-
-                const repairResult = await completePrompt({ prompt: repairPrompt, system: repairSystem });
-
-                if (repairResult.completed) {
-                    const repairChanges = parseChangeList(repairResult.value);
-                    if (repairChanges.length > 0) {
-                        const repairPass = applyChangeListWithReport(reAnnotatedHtml, repairChanges);
-                        const repairSuccessCount = repairChanges.length - repairPass.failedOps.length;
-                        if (repairPass.failedOps.length > 0) {
-                            console.warn(`transformPage: repair pass had ${repairPass.failedOps.length} remaining failure(s) — keeping partial result`);
-                        }
-                        finalHtml = repairPass.html;
-                        successCount += repairSuccessCount;
-                        console.log(`transformPage: repair pass applied ${repairSuccessCount} fix(es)`);
-                    } else {
-                        console.log('transformPage: repair pass returned no changes (model deemed repairs unnecessary)');
-                    }
-                } else {
-                    console.warn('transformPage: repair LLM call failed — keeping partial result from first pass');
-                }
-            } catch (repairErr: unknown) {
-                const msg = repairErr instanceof Error ? repairErr.message : String(repairErr);
-                console.warn(`transformPage: repair pass error — ${msg} — keeping partial result from first pass`);
-            }
+        // Unordered list (lines starting with - or *)
+        if (/^[\-\*] /m.test(trimmed) && trimmed.split('\n').every(l => /^[\-\*] /.test(l.trim()) || l.trim() === '')) {
+            const items = trimmed.split('\n')
+                .map(l => l.trim())
+                .filter(l => l)
+                .map(l => `<li>${inlineMarkdown(l.replace(/^[\-\*] /, ''))}</li>`)
+                .join('');
+            htmlBlocks.push(`<ul>${items}</ul>`);
+            continue;
         }
 
-        // 7. Strip data-node-id attributes
-        const cleanHtml = stripNodeIds(finalHtml);
+        // Ordered list (lines starting with 1. 2. etc.)
+        if (/^\d+\. /m.test(trimmed) && trimmed.split('\n').every(l => /^\d+\. /.test(l.trim()) || l.trim() === '')) {
+            const items = trimmed.split('\n')
+                .map(l => l.trim())
+                .filter(l => l)
+                .map(l => `<li>${inlineMarkdown(l.replace(/^\d+\. /, ''))}</li>`)
+                .join('');
+            htmlBlocks.push(`<ol>${items}</ol>`);
+            continue;
+        }
 
-        // 8. Remove duplicate inline scripts (LLM may insert instead of update)
-        const dedupedHtml = deduplicateInlineScripts(cleanHtml);
+        // Regular paragraph
+        htmlBlocks.push(`<p>${inlineMarkdown(trimmed.replace(/\n/g, '<br>'))}</p>`);
+    }
 
-        // 9. Ensure page-helpers and page-script are last in <body>
-        const safeHtml = ensureScriptsBeforeBodyClose(dedupedHtml);
+    // Restore code blocks
+    let result = htmlBlocks.join('');
+    result = result.replace(/\x00CODEBLOCK(\d+)\x00/g, (_m, idx) => codeBlocks[parseInt(idx)]);
+    return result;
+}
 
-        return { completed: true, value: { html: safeHtml, changeCount: successCount } };
-    } catch (err: unknown) {
-        // On any error: return original page with error block injected
-        const cleanOriginal = stripNodeIds(annotatedHtml);
-        const errorMessage = err instanceof Error ? err.message : String(err);
-        const errorHtml = injectError(cleanOriginal, 'Something went wrong try again', errorMessage);
-        return { completed: true, value: { html: errorHtml, changeCount: 0 } };
-    }
+/** Apply inline markdown formatting: bold, italic, inline code, links. */
+function inlineMarkdown(text: string): string {
+    // Inline code (protect from further processing)
+    const codes: string[] = [];
+    let result = text.replace(/`([^`]+)`/g, (_m, code) => {
+        const idx = codes.length;
+        codes.push(`<code>${escapeHtml(code)}</code>`);
+        return `\x00CODE${idx}\x00`;
+    });
+
+    // Bold (**text** or __text__)
+    result = result.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+    result = result.replace(/__(.+?)__/g, '<strong>$1</strong>');
+
+    // Italic (*text* or _text_)
+    result = result.replace(/\*(.+?)\*/g, '<em>$1</em>');
+    result = result.replace(/(?<!\w)_(.+?)_(?!\w)/g, '<em>$1</em>');
+
+    // Links [text](url)
+    result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+    // Restore inline code
+    result = result.replace(/\x00CODE(\d+)\x00/g, (_m, idx) => codes[parseInt(idx)]);
+
+    return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -247,6 +246,69 @@ export function stripNodeIds(html: string): string {
     return $.html();
 }
 
+/**
+ * Remove the early error-capture script injected into <head> so the LLM
+ * never sees it during page transformation.
+ */
+function stripErrorCapture(html: string): string {
+    const id = 'synthos-error-capture';
+    if (!html.includes(id)) return html;
+    const $ = cheerio.load(html, { decodeEntities: false });
+    $(`#${id}`).remove();
+    return $.html();
+}
+
+/**
+ * Find `needle` in `haystack` using whitespace-normalized comparison.
+ * Collapses runs of whitespace (spaces, tabs, newlines) into a single space
+ * for comparison purposes but returns the position in the original string.
+ * Returns -1 if no match found.
+ */
+export function normalizedIndexOf(haystack: string, needle: string): { start: number; end: number } | null {
+    // Build a mapping from normalized-string positions to original-string positions
+    const normChars: string[] = [];
+    const origPositions: number[] = []; // origPositions[i] = original index of normChars[i]
+    let inWhitespace = false;
+
+    for (let i = 0; i < haystack.length; i++) {
+        const ch = haystack[i];
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+            if (!inWhitespace) {
+                normChars.push(' ');
+                origPositions.push(i);
+                inWhitespace = true;
+            }
+        } else {
+            normChars.push(ch);
+            origPositions.push(i);
+            inWhitespace = false;
+        }
+    }
+
+    const normHaystack = normChars.join('');
+
+    // Normalize the needle the same way
+    const normNeedle = needle.replace(/\s+/g, ' ');
+
+    const idx = normHaystack.indexOf(normNeedle);
+    if (idx === -1) return null;
+
+    const start = origPositions[idx];
+    // The end position: find the original position of the last matched char, then go one past
+    const lastNormIdx = idx + normNeedle.length - 1;
+    const lastOrigPos = origPositions[lastNormIdx];
+    // Advance past any trailing whitespace that was collapsed in the original
+    let end = lastOrigPos + 1;
+    if (haystack[lastOrigPos] === ' ' || haystack[lastOrigPos] === '\t' || haystack[lastOrigPos] === '\n' || haystack[lastOrigPos] === '\r') {
+        // The last matched normalized char was a whitespace collapse — extend to include all original whitespace
+        while (end < haystack.length && (haystack[end] === ' ' || haystack[end] === '\t' || haystack[end] === '\n' || haystack[end] === '\r')) {
+            end++;
+        }
+    }
+
+    return { start, end };
+}
+
 /**
  * Remove duplicate inline `<script>` blocks using a two-pass approach.
  *
@@ -385,6 +447,29 @@ function isElementLocked(el: cheerio.Cheerio, $: cheerio.Root): boolean {
     return el.attr('data-locked') !== undefined;
 }
 
+/**
+ * If the target element is a <script> or <style> and the html is wrapped in a
+ * redundant matching tag, strip the outer tag to avoid nesting (e.g.
+ * `<script>` inside `<script>`). Returns the inner content when unwrapped.
+ */
+function unwrapRedundantTag(tagName: string | undefined, html: string): string {
+    if (tagName !== 'script' && tagName !== 'style') return html;
+    const re = new RegExp(`^\\s*<${tagName}[^>]*>([\\s\\S]*)</${tagName}>\\s*$`, 'i');
+    const match = html.match(re);
+    return match ? match[1] : html;
+}
+
+/**
+ * Strip any `<script>` or `<style>` tags from text that will be injected
+ * inside an existing script/style block (search-replace, search-insert).
+ */
+function stripNestedBlockTags(tagName: string | undefined, text: string): string {
+    if (tagName !== 'script' && tagName !== 'style') return text;
+    return text
+        .replace(new RegExp(`<${tagName}[^>]*>`, 'gi'), '')
+        .replace(new RegExp(`</${tagName}>`, 'gi'), '');
+}
+
 /**
  * Apply a list of CRUD operations to annotated HTML (elements must have `data-node-id`).
  */
@@ -399,7 +484,8 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                     console.warn(`applyChangeList: skipping update — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
-                el.html(change.html);
+                const tag = el.prop('tagName')?.toLowerCase();
+                el.html(unwrapRedundantTag(tag, change.html));
                 break;
             }
             case 'replace': {
@@ -412,7 +498,16 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                     console.warn(`applyChangeList: skipping replace — node ${change.nodeId} is data-locked`);
                     break;
                 }
-                el.replaceWith(change.html);
+                // If the target is a <script> or <style> and the html doesn't
+                // include the outer tag (or wraps it redundantly), treat as an
+                // update (set inner content) instead of replacing the element.
+                const tagName = el.prop('tagName')?.toLowerCase();
+                const cleaned = unwrapRedundantTag(tagName, change.html);
+                if ((tagName === 'script' || tagName === 'style') && !cleaned.trimStart().startsWith('<')) {
+                    el.html(cleaned);
+                } else {
+                    el.replaceWith(change.html);
+                }
                 break;
             }
             case 'delete': {
@@ -430,13 +525,20 @@ export function applyChangeList(html: string, changes: ChangeList): string {
             }
             case 'insert': {
                 const parent = $(`[data-node-id="${change.parentId}"]`);
-                if (parent.length === 0) throw new Error(`insert: parent node ${change.parentId} not found`);
+                if (parent.length === 0) {
+                    console.warn(`applyChangeList: skipping insert — parent node ${change.parentId} not found`);
+                    break;
+                }
+                // Unwrap redundant tags when inserting into script/style
+                const parentTag = parent.prop('tagName')?.toLowerCase();
+                const insertHtml = unwrapRedundantTag(parentTag, change.html);
                 switch (change.position) {
-                    case 'prepend': parent.prepend(change.html); break;
-                    case 'append': parent.append(change.html); break;
-                    case 'before': parent.before(change.html); break;
-                    case 'after': parent.after(change.html); break;
-                    default: throw new Error(`insert: unknown position "${(change as any).position}"`);
+                    case 'prepend': parent.prepend(insertHtml); break;
+                    case 'append': parent.append(insertHtml); break;
+                    case 'before': parent.before(insertHtml); break;
+                    case 'after': parent.after(insertHtml); break;
+                    default:
+                        console.warn(`applyChangeList: skipping insert — unknown position "${(change as any).position}"`);
                 }
                 break;
             }
@@ -453,101 +555,49 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                 el.attr('style', change.style);
                 break;
             }
-            default:
-                throw new Error(`Unknown change op: "${(change as any).op}"`);
-        }
-    }
-
-    return $.html();
-}
-
-/**
- * Apply a list of CRUD operations and report any ops that failed due to
- * missing nodes (instead of throwing). Unknown op types still throw.
- */
-function applyChangeListWithReport(html: string, changes: ChangeList): ApplyResult {
-    const $ = cheerio.load(html, { decodeEntities: false });
-    const failedOps: FailedOp[] = [];
-
-    for (const change of changes) {
-        switch (change.op) {
-            case 'update': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
-                if (el.length === 0) {
-                    const reason = `node ${change.nodeId} not found (already removed?)`;
-                    console.warn(`applyChangeListWithReport: skipping update — ${reason}`);
-                    failedOps.push({ op: change, reason });
-                    break;
-                }
-                el.html(change.html);
-                break;
-            }
-            case 'replace': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
-                if (el.length === 0) {
-                    const reason = `node ${change.nodeId} not found (already removed?)`;
-                    console.warn(`applyChangeListWithReport: skipping replace — ${reason}`);
-                    failedOps.push({ op: change, reason });
-                    break;
-                }
-                if (isElementLocked(el, $)) {
-                    const reason = `node ${change.nodeId} is data-locked`;
-                    console.warn(`applyChangeListWithReport: skipping replace — ${reason}`);
-                    failedOps.push({ op: change, reason });
-                    break;
-                }
-                el.replaceWith(change.html);
-                break;
-            }
-            case 'delete': {
+            case 'search-replace': {
                 const el = $(`[data-node-id="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    const reason = `node ${change.nodeId} not found (already removed?)`;
-                    console.warn(`applyChangeListWithReport: skipping delete — ${reason}`);
-                    failedOps.push({ op: change, reason });
-                    break;
-                }
-                if (isElementLocked(el, $)) {
-                    const reason = `node ${change.nodeId} is data-locked`;
-                    console.warn(`applyChangeListWithReport: skipping delete — ${reason}`);
-                    failedOps.push({ op: change, reason });
-                    break;
-                }
-                el.remove();
-                break;
-            }
-            case 'insert': {
-                const parent = $(`[data-node-id="${change.parentId}"]`);
-                if (parent.length === 0) {
-                    const reason = `parent node ${change.parentId} not found`;
-                    console.warn(`applyChangeListWithReport: skipping insert — ${reason}`);
-                    failedOps.push({ op: change, reason });
+                    console.warn(`applyChangeList: skipping search-replace — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
-                switch (change.position) {
-                    case 'prepend': parent.prepend(change.html); break;
-                    case 'append': parent.append(change.html); break;
-                    case 'before': parent.before(change.html); break;
-                    case 'after': parent.after(change.html); break;
-                    default: throw new Error(`insert: unknown position "${(change as any).position}"`);
+                const srTag = el.prop('tagName')?.toLowerCase();
+                const replaceText = stripNestedBlockTags(srTag, change.replace);
+                const content = el.html() ?? '';
+                const exactIdx = content.indexOf(change.search);
+                if (exactIdx !== -1) {
+                    el.html(content.slice(0, exactIdx) + replaceText + content.slice(exactIdx + change.search.length));
+                } else {
+                    const norm = normalizedIndexOf(content, change.search);
+                    if (norm) {
+                        el.html(content.slice(0, norm.start) + replaceText + content.slice(norm.end));
+                    } else {
+                        console.warn(`applyChangeList: skipping search-replace — search text not found in node ${change.nodeId}`);
+                    }
                 }
                 break;
             }
-            case 'style-element': {
+            case 'search-insert': {
                 const el = $(`[data-node-id="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    const reason = `node ${change.nodeId} not found (already removed?)`;
-                    console.warn(`applyChangeListWithReport: skipping style-element — ${reason}`);
-                    failedOps.push({ op: change, reason });
+                    console.warn(`applyChangeList: skipping search-insert — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
-                if (isElementLocked(el, $)) {
-                    const reason = `node ${change.nodeId} is data-locked`;
-                    console.warn(`applyChangeListWithReport: skipping style-element — ${reason}`);
-                    failedOps.push({ op: change, reason });
-                    break;
+                const siTag = el.prop('tagName')?.toLowerCase();
+                const insertContent = stripNestedBlockTags(siTag, change.content);
+                const content = el.html() ?? '';
+                const exactIdx = content.indexOf(change.after);
+                if (exactIdx !== -1) {
+                    const insertPos = exactIdx + change.after.length;
+                    el.html(content.slice(0, insertPos) + insertContent + content.slice(insertPos));
+                } else {
+                    const norm = normalizedIndexOf(content, change.after);
+                    if (norm) {
+                        el.html(content.slice(0, norm.end) + insertContent + content.slice(norm.end));
+                    } else {
+                        console.warn(`applyChangeList: skipping search-insert — after text not found in node ${change.nodeId}`);
+                    }
                 }
-                el.attr('style', change.style);
                 break;
             }
             default:
@@ -555,27 +605,24 @@ function applyChangeListWithReport(html: string, changes: ChangeList): ApplyResu
         }
     }
 
-    return { html: $.html(), failedOps };
+    return $.html();
 }
 
 /**
- * Inject an error script block into the page HTML.
+ * Append a user message and a styled error message to #chatMessages.
  */
-export function injectError(html: string, message: string, details: string): string {
+function appendChatError(html: string, userMessage: string, errorDetails: string, productName: string): string {
     const $ = cheerio.load(html, { decodeEntities: false });
-    const errorPayload = JSON.stringify({ message, details });
-    const scriptTag = `<script id="error" type="application/json">${errorPayload}</script>`;
-
-    // Remove any existing error block first
-    $('script#error').remove();
-
-    // Inject before closing </body> or at end
-    if ($('body').length > 0) {
-        $('body').append(scriptTag);
-    } else {
-        return html + scriptTag;
+    const chatMessages = $('#chatMessages');
+    if (chatMessages.length > 0) {
+        chatMessages.append(
+            `<div class="chat-message"><p><strong>User:</strong> ${escapeHtml(userMessage)}</p></div>`
+        );
+        chatMessages.append(
+            `<div class="chat-message chat-message-error"><p><strong>${escapeHtml(productName)}:</strong> Something went wrong \u2014 please try again.</p>`
+            + `<p class="chat-error-details">${escapeHtml(errorDetails)}</p></div>`
+        );
     }
-
     return $.html();
 }
 
@@ -610,19 +657,20 @@ export function parseChangeList(response: string): ChangeList {
 // Prompt constants
 // ---------------------------------------------------------------------------
 
-const messageFormat =
-`<MESSAGE_FORMAT>
-<div class="chat-message"><p><strong>{SynthOS: | User:}</strong> {message contents}</p></div>
-`
+export function getMessageFormat(productName: string): string {
+    return `<MESSAGE_FORMAT>
+<div class="chat-message"><p><strong>{${productName}: | User:}</strong> {message contents}</p></div>
+`;
+}
 
-const transformInstr =
-`Apply the users <USER_MESSAGE> to the .viewerPanel of the <CURRENT_PAGE> by generating a list of changes in JSON format.
+export function getTransformInstr(productName: string): string {
+    return `Apply the users <USER_MESSAGE> to the .viewerPanel of the <CURRENT_PAGE> by generating a list of changes in JSON format.
 Never remove any element that has a data-locked attribute. You may modfiy the inner text of a data-locked element or any of its unlocked child elements.
 
-If the <USER_MESSAGE> involves clearning the chat history, remove all .chat-message elements inside the #chatMessages container except for the first SynthOS: message. You may modify that message contents if requested.
-If there's no <USER_MESSAGE> add a SynthOS: message to the chat with aasking the user what they would like to do.
-If there is a <USER_MESSAGE> but the intent is unclear, add a User: message with the <USER_MESSAGE> to the chat and add a SynthOS: message asking the user for clarification on their intent.
-If there is a <USER_MESSAGE> with clear intent, add a User: message with the <USER_MESSAGE> to the chat and add a SynthOS: message explaining your change or answering their question.
+If the <USER_MESSAGE> involves clearning the chat history, remove all .chat-message elements inside the #chatMessages container except for the first ${productName}: message. You may modify that message contents if requested.
+If there's no <USER_MESSAGE> add a ${productName}: message to the chat with aasking the user what they would like to do.
+If there is a <USER_MESSAGE> but the intent is unclear, add a User: message with the <USER_MESSAGE> to the chat and add a ${productName}: message asking the user for clarification on their intent.
+If there is a <USER_MESSAGE> with clear intent, add a User: message with the <USER_MESSAGE> to the chat and add a ${productName}: message explaining your change or answering their question.
 If a <USER_MESSAGE> is overly long, summarize the User: message.
 
 When updating the .viewerPanel you may alse add/remove/update style blocks to the header unless they're data-locked. Use inline styles if you need to modify the .viewerPanel itself.
@@ -646,31 +694,11 @@ Do not add duplicate script blocks with the same logic! Consolidate inline scrip
 Each element in the CURRENT_PAGE has a data-node-id attribute. Don't use the id attribute for targeting nodes (reserve it for scripts and styles) — use data-node-id.
 If you're trying to assign an id to script or style block, use "replace" not "update".
 Your first operation should always be an update to your thoughts block, where you can reason through the user's request and plan your changes before applying them to the page.
-Return a JSON array of change operations to apply to the page. Do NOT return the full HTML page.
-
-Each operation must be one of:
-{ "op": "update", "nodeId": "<data-node-id>", "html": "<new innerHTML>" }
-  — replaces the innerHTML of the target element
 
-{ "op": "replace", "nodeId": "<data-node-id>", "html": "<new outerHTML>" }
-  — replaces the entire element (outerHTML) with new markup
-
-{ "op": "delete", "nodeId": "<data-node-id>" }
-  — removes the element from the page
-
-{ "op": "insert", "parentId": "<data-node-id>", "position": "prepend"|"append"|"before"|"after", "html": "<new element HTML>" }
-  — inserts new HTML relative to the parent element
-
-{ "op": "style-element", "nodeId": "<data-node-id>", "style": "<css style string>" }
-  — sets the style attribute of the target element (must be unlocked)
-
-Return ONLY the JSON array. Example:
-[
-  { "op": "update", "nodeId": "5", "html": "<p>Hello world</p>" },
-  { "op": "insert", "parentId": "3", "position": "append", "html": "<div class=\\"msg\\">New message</div>" }
-]`;
+CRITICAL — FluentLM components: If a <FLUENTLM_COMPONENTS> section is present, you MUST use those components for all standard UI elements (buttons, inputs, selects, dialogs, tabs, cards, toggles, etc.). Never create custom CSS classes for UI controls that have a FluentLM equivalent. Refer to <FLUENTLM_COMPONENTS> for the exact class names and markup patterns.`;
+}
 
-const AGENT_API_REFERENCE =
+export const AGENT_API_REFERENCE =
 `## Agent API
 
 Check availability first (required):
@@ -704,7 +732,221 @@ Stream with attachments:
 IMPORTANT: Always check synthos.agents.list({ enabled: true }) before calling an agent.
 If no agents are configured, show the user a link to Settings > Agents (/settings?tab=agents).`;
 
-const serverAPIs =
+// ---------------------------------------------------------------------------
+// Route hint blocks — keyed by feature group so they can be filtered
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ROUTE_HINTS = new Map<string, string>([
+    ['data', `GET /api/data/:page/:table
+description: Retrieve all rows from a page-scoped table (tables are stored per-page). Supports pagination via query params.
+query params: limit (number, optional) — max rows to return; offset (number, optional, default 0) — rows to skip
+response (without limit): Array of JSON rows [{ id: string, ... }]
+response (with limit): { items: [{ id: string, ... }], total: number, offset: number, limit: number, hasMore: boolean }
+
+GET /api/data/:page/:table/:id
+description: Retrieve a single row from a page-scoped table
+response: JSON row { id: string, ... }
+
+POST /api/data/:page/:table
+description: Replaces or adds a single row to a page-scoped table and returns the row
+request: JSON row { id?: string, ... }
+response: { id: string, ... }
+
+DELETE /api/data/:page/:table/:id
+description: Delete a single row from a page-scoped table
+response: { success: true }
+
+  synthos.data.list(table, opts?)       — GET /api/data/:page/:table  (auto-scoped to current page; opts: { limit?, offset? } — when limit is set, returns { items, total, offset, limit, hasMore })
+  synthos.data.get(table, id)           — GET /api/data/:page/:table/:id  (auto-scoped to current page)
+  synthos.data.save(table, row)         — POST /api/data/:page/:table  (auto-scoped to current page)
+  synthos.data.remove(table, id)        — DELETE /api/data/:page/:table/:id  (auto-scoped to current page)`],
+
+    ['api', `POST /api/generate/image
+description: Generate an image based on a prompt
+request: { prompt: string, shape: 'square' | 'portrait' | 'landscape', style: 'vivid' | 'natural' }
+response: { url: string }
+
+POST /api/generate/completion
+description: Generates a text completion based on a prompt
+request: { prompt: string, temperature?: number }
+response: { answer: string, explanation: string }
+
+  synthos.generate.image({ prompt, shape, style })       — POST /api/generate/image
+  synthos.generate.completion({ prompt, temperature? })  — POST /api/generate/completion`],
+
+    ['pages', `GET /api/pages
+description: Retrieve a list of all pages with metadata
+response: Array of { name: string, title: string, categories: string[], pinned: boolean, createdDate: string, lastModified: string, pageVersion: number, mode: 'unlocked' | 'locked' }
+
+GET /api/pages/:name
+description: Retrieve metadata for a single page
+response: { title: string, categories: string[], pinned: boolean, createdDate: string, lastModified: string, pageVersion: number, mode: 'unlocked' | 'locked' }
+
+POST /api/pages/:name
+description: Update page metadata (merge semantics — send only fields to change; lastModified is auto-set)
+request: { title?: string, categories?: string[], pinned?: boolean, mode?: 'unlocked' | 'locked' }
+response: Full metadata object
+
+DELETE /api/pages/:name
+description: Delete a user page (cannot delete required/system pages)
+response: { deleted: true }
+
+POST /api/pages/:name/ask
+description: Ask a question about a page with full HTML context
+request: { question: string }
+response: { answer: string }
+
+  synthos.pages.list()                  — GET /api/pages
+  synthos.pages.get(name)               — GET /api/pages/:name
+  synthos.pages.update(name, metadata)  — POST /api/pages/:name
+  synthos.pages.remove(name)            — DELETE /api/pages/:name
+  synthos.pages.ask(name, question)     — POST /api/pages/:name/ask`],
+
+    ['scripts', `POST /api/scripts/:id
+description: Execute a script with the passed in variables
+request: { [key: string]: string }
+response: string
+
+  synthos.scripts.run(id, variables)    — POST /api/scripts/:id`],
+
+    ['search', `POST /api/search/web
+description: Search the web using Brave Search (must be enabled in Settings > Connectors)
+request: { query: string, count?: number, country?: string, freshness?: string }
+response: { results: [{ title: string, url: string, description: string }] }
+
+  synthos.search.web(query, opts?)      — POST /api/search/web  (opts: { count?, country?, freshness? })`],
+
+    ['agents', `GET /api/agents
+description: List configured agents (A2A and OpenClaw). Supports ?enabled=true and ?provider=a2a|openclaw filters.
+response: [{ id: string, name: string, description: string, url: string, enabled: boolean, provider: 'a2a'|'openclaw', capabilities?: object }]
+
+POST /api/agents/:id/send
+description: Send a text message to an agent (works for both A2A and OpenClaw protocols) and receive a normalized response
+request: { message: string, attachments?: [{ fileName: string, mimeType: string, content: string }] }
+response: { kind: 'message'|'task', text?: string, raw: object }
+
+POST /api/agents/:id/stream
+description: Send a message and receive a streaming SSE response (text/event-stream). Each event is JSON: { kind: 'text'|'status'|'artifact'|'done'|'error', data: any }
+request: { message: string, attachments?: [{ fileName: string, mimeType: string, content: string }] }
+response: SSE stream
+
+  synthos.agents.list(opts?)             — GET /api/agents  (returns configured agents; opts: { enabled?, provider? }; returns [{ id, name, description, url, enabled, provider, capabilities }])
+  synthos.agents.send(agentId, message, attachments?) — POST /api/agents/:id/send  (sends a text message to any agent, returns normalized { kind, text, raw }; attachments: [{ fileName, mimeType, content }])
+  synthos.agents.sendStream(agentId, message, onEvent, attachments?) — POST /api/agents/:id/stream  (SSE streaming; onEvent receives { kind, data }; returns { close() } handle; attachments: [{ fileName, mimeType, content }])
+  synthos.agents.isEnabled(agentId)     — checks if an agent is enabled (returns Promise<boolean>)
+  synthos.agents.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)`],
+
+    ['connectors', `GET /api/connectors
+description: List available connectors (REST API proxies). Supports ?category=X and ?id=X filters.
+response: [{ id: string, name: string, category: string, configured: boolean }]
+
+GET /api/connectors/:id
+description: Get full detail for a connector including its definition and configuration status
+response: { id, name, category, description, baseUrl, authStrategy, authKey, fields, configured, enabled, hasKey }
+
+POST /api/connectors (proxy call)
+description: Proxy a request through a configured connector. The connector attaches auth automatically.
+request: { connector: string, method: string, path: string, headers?: object, body?: any, query?: object }
+response: Upstream API response (JSON or text)
+
+  synthos.connectors.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
+  synthos.connectors.list(opts?)        — GET /api/connectors  (opts: { category?, id? })`],
+
+    ['files', `GET /api/files/:page
+description: List files stored for a page (with sizes)
+response: { files: [{ name: string, size: number }] }
+
+POST /api/files/:page
+description: Upload a file to a page's file storage (raw body + x-filename header)
+request: Raw binary body with x-filename header
+response: { name: string, size: number }
+
+GET /api/files/:page/:filename
+description: Download/serve a specific file from a page's file storage
+response: File content (served with appropriate content-type)
+
+DELETE /api/files/:page/:filename
+description: Delete a file from a page's file storage
+response: { deleted: true }
+
+  synthos.files.list()                  — GET /api/files/:page  (auto-scoped to current page)
+  synthos.files.upload(filename, blob)  — POST /api/files/:page  (auto-scoped to current page; sends raw body with x-filename header)
+  synthos.files.url(filename)           — returns URL string /api/files/:page/:filename  (for <img src>, <a href>, etc.)
+  synthos.files.remove(filename)        — DELETE /api/files/:page/:filename  (auto-scoped to current page)`],
+
+    ['shared-data', `GET /api/shared/data/:table
+description: Retrieve all rows from a shared (cross-page) table. Supports pagination via query params.
+query params: limit (number, optional) — max rows to return; offset (number, optional, default 0) — rows to skip
+response (without limit): Array of JSON rows [{ id: string, ... }]
+response (with limit): { items: [{ id: string, ... }], total: number, offset: number, limit: number, hasMore: boolean }
+
+GET /api/shared/data/:table/:id
+description: Retrieve a single row from a shared table
+response: JSON row { id: string, ... }
+
+POST /api/shared/data/:table
+description: Replaces or adds a single row to a shared table and returns the row
+request: JSON row { id?: string, ... }
+response: { id: string, ... }
+
+DELETE /api/shared/data/:table/:id
+description: Delete a single row from a shared table
+response: { success: true }
+
+  synthos.shared.data.list(table, opts?)       — GET /api/shared/data/:table  (opts: { limit?, offset? } — when limit is set, returns { items, total, offset, limit, hasMore })
+  synthos.shared.data.get(table, id)           — GET /api/shared/data/:table/:id
+  synthos.shared.data.save(table, row)         — POST /api/shared/data/:table
+  synthos.shared.data.remove(table, id)        — DELETE /api/shared/data/:table/:id`],
+
+    ['shared-files', `GET /api/shared/files
+description: List files in shared (cross-page) file storage (with sizes)
+response: { files: [{ name: string, size: number }] }
+
+POST /api/shared/files
+description: Upload a file to shared file storage (raw body + x-filename header)
+request: Raw binary body with x-filename header
+response: { name: string, size: number }
+
+GET /api/shared/files/:filename
+description: Download/serve a specific file from shared file storage
+response: File content (served with appropriate content-type)
+
+DELETE /api/shared/files/:filename
+description: Delete a file from shared file storage
+response: { deleted: true }
+
+  synthos.shared.files.list()                  — GET /api/shared/files
+  synthos.shared.files.upload(filename, blob)  — POST /api/shared/files  (sends raw body with x-filename header)
+  synthos.shared.files.url(filename)           — returns URL string /api/shared/files/:filename  (for <img src>, <a href>, etc.)
+  synthos.shared.files.remove(filename)        — DELETE /api/shared/files/:filename`],
+]);
+
+/**
+ * Assemble the <SERVER_APIS> prompt block, including only hints for enabled
+ * feature groups and any custom route hints from the Customizer.
+ */
+export function buildRouteHints(customizer: Customizer): string {
+    const blocks: string[] = ['<SERVER_APIS>'];
+
+    // Built-in hints — only include enabled groups
+    for (const [group, hints] of DEFAULT_ROUTE_HINTS) {
+        if (customizer.isEnabled(group)) {
+            blocks.push(hints);
+        }
+    }
+
+    // Custom route hints from fork
+    for (const hint of customizer.getRouteHints()) {
+        blocks.push(hint);
+    }
+
+    blocks.push('PAGE HELPERS (available globally as window.synthos):');
+    blocks.push('All methods return Promises. Prefer these helpers over raw fetch().');
+    return blocks.join('\n\n');
+}
+
+// Backward-compatible full serverAPIs string (used when no Customizer is passed)
+export const serverAPIs =
 `<SERVER_APIS>
 GET /api/data/:page/:table
 description: Retrieve all rows from a page-scoped table (tables are stored per-page). Supports pagination via query params.
@@ -752,6 +994,11 @@ DELETE /api/pages/:name
 description: Delete a user page (cannot delete required/system pages)
 response: { deleted: true }
 
+POST /api/pages/:name/ask
+description: Ask a question about a page with full HTML context
+request: { question: string }
+response: { answer: string }
+
 POST /api/scripts/:id
 description: Execute a script with the passed in variables
 request: { [key: string]: string }
@@ -801,6 +1048,7 @@ PAGE HELPERS (available globally as window.synthos):
   synthos.pages.get(name)               — GET /api/pages/:name
   synthos.pages.update(name, metadata)  — POST /api/pages/:name
   synthos.pages.remove(name)            — DELETE /api/pages/:name
+  synthos.pages.ask(name, question)     — POST /api/pages/:name/ask
   synthos.search.web(query, opts?)      — POST /api/search/web  (opts: { count?, country?, freshness? })
   synthos.connectors.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
   synthos.connectors.list(opts?)        — GET /api/connectors  (opts: { category?, id? })
@@ -810,20 +1058,3 @@ PAGE HELPERS (available globally as window.synthos):
   synthos.agents.isEnabled(agentId)     — checks if an agent is enabled (returns Promise<boolean>)
   synthos.agents.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)
 All methods return Promises. Prefer these helpers over raw fetch().`;
-
-const repairUSER_MESSAGE =
-`Some change operations from the previous response failed because the target nodes no longer exist in the page (they were removed or replaced by earlier operations in the same batch).
-
-Below is the CURRENT state of the page after the successful operations were applied, followed by the list of operations that failed and why.
-
-Re-generate corrected versions of ONLY the failed operations, targeting nodes that actually exist in the current page. Each element has a data-node-id attribute you can reference.
-If a failed operation is no longer needed (e.g. the intended change was already accomplished by another op), omit it.
-Return an empty JSON array [] if no repairs are needed.
-
-Return ONLY a JSON array of change operations using the same format:
-{ "op": "update", "nodeId": "<data-node-id>", "html": "<new innerHTML>" }
-{ "op": "replace", "nodeId": "<data-node-id>", "html": "<new outerHTML>" }
-{ "op": "delete", "nodeId": "<data-node-id>" }
-{ "op": "insert", "parentId": "<data-node-id>", "position": "prepend"|"append"|"before"|"after", "html": "<new element HTML>" }
-{ "op": "style-element", "nodeId": "<data-node-id>", "style": "<css style string>" }`;
-