synthos 0.10.1 → 0.11.0

package/src/builders/claudecode.ts

@@ -0,0 +1,310 @@
+import { spawn } from 'child_process';
+import { ChangeOp, getTransformInstr } from '../service/transformPage';
+import { parseBuilderResponse } from './anthropic';
+import { Builder, BuilderResult, CHANGE_OPS_FORMAT_INSTRUCTION } from './types';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface ClaudeCodeBuilderOptions {
+    /** Model to pass as --model to the CLI. */
+    model?: string;
+    /** Override path to the claude binary (defaults to 'claude' on PATH). */
+    commandPath?: string;
+    /** Request timeout in milliseconds (default 120 000). */
+    timeout?: number;
+    /** Additional CLI flags passed to every invocation. */
+    extraFlags?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Strip ANSI escape codes from CLI output. */
+function stripAnsi(text: string): string {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+}
+
+/**
+ * Spawn the Claude CLI with a prompt on stdin and capture stdout.
+ * Returns the raw text output (ANSI-stripped).
+ */
+function runClaude(
+    prompt: string,
+    options: ClaudeCodeBuilderOptions
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const cmd = options.commandPath ?? 'claude';
+    const args: string[] = ['-p', '--output-format', 'text'];
+    if (options.model) {
+        args.push('--model', options.model);
+    }
+    if (options.extraFlags) {
+        args.push(...options.extraFlags);
+    }
+
+    const timeout = options.timeout ?? 120_000;
+
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                FORCE_COLOR: '0',       // suppress ANSI in captured output
+                CLAUDECODE: undefined,   // prevent recursive detection
+            },
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+
+        // EOF protection — swallow EPIPE if the child closes stdin early
+        child.stdin.on('error', (err: NodeJS.ErrnoException) => {
+            if (err.code !== 'EPIPE' && err.code !== 'EOF') throw err;
+        });
+
+        // Timeout handling: SIGTERM → 5 s → SIGKILL
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                if (!child.killed) child.kill('SIGKILL');
+            }, 5_000);
+        }, timeout);
+
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({
+                stdout: stripAnsi(stdout),
+                stderr: stripAnsi(stderr),
+                exitCode: code ?? 1,
+            });
+        });
+
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+
+        // Pipe the prompt via stdin
+        child.stdin.write(prompt, () => {
+            child.stdin.end();
+        });
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Spawn + retry wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the Claude CLI and return trimmed output.
+ * Retries once on empty output with a simplified prompt prefix.
+ */
+async function executeWithRetry(
+    prompt: string,
+    options: ClaudeCodeBuilderOptions,
+): Promise<string> {
+    const attempt = async (p: string): Promise<string> => {
+        const result = await runClaude(p, options);
+
+        // Handle process-level failures
+        if (result.exitCode !== 0 && !result.stdout.trim()) {
+            if (result.stderr.includes('ENOENT') || result.stderr.includes('not found') || result.stderr.includes('not recognized')) {
+                throw new Error(
+                    'Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-code'
+                );
+            }
+            throw new Error(result.stderr || `Claude CLI exited with code ${result.exitCode}`);
+        }
+
+        return result.stdout.trim();
+    };
+
+    // First attempt
+    const output = await attempt(prompt);
+    if (output) return output;
+
+    // Retry once with a nudge prepended to the prompt
+    console.warn('[ClaudeCode] Empty response — retrying once');
+    const retryOutput = await attempt(
+        'IMPORTANT: You must produce output. Do not return an empty response.\n\n' + prompt
+    );
+    if (retryOutput) return retryOutput;
+
+    throw new Error('Claude CLI returned empty output after retry');
+}
+
+// ---------------------------------------------------------------------------
+// Change-op validation
+// ---------------------------------------------------------------------------
+
+const VALID_OPS = new Set(['update', 'replace', 'delete', 'insert', 'style-element', 'search-replace', 'search-insert']);
+
+/**
+ * Validate a single change operation against the expected schema.
+ * Returns true if the op is structurally valid, false otherwise.
+ */
+function isValidChangeOp(op: unknown): op is ChangeOp {
+    if (!op || typeof op !== 'object') return false;
+    const o = op as Record<string, unknown>;
+    if (typeof o.op !== 'string' || !VALID_OPS.has(o.op)) return false;
+
+    switch (o.op) {
+        case 'update':
+        case 'replace':
+            return typeof o.nodeId === 'string' && typeof o.html === 'string';
+        case 'delete':
+            return typeof o.nodeId === 'string';
+        case 'insert':
+            return typeof o.parentId === 'string'
+                && typeof o.position === 'string'
+                && typeof o.html === 'string';
+        case 'style-element':
+            return typeof o.nodeId === 'string' && typeof o.style === 'string';
+        case 'search-replace':
+            return typeof o.nodeId === 'string'
+                && typeof o.search === 'string'
+                && typeof o.replace === 'string';
+        case 'search-insert':
+            return typeof o.nodeId === 'string'
+                && typeof o.after === 'string'
+                && typeof o.content === 'string';
+        default:
+            return false;
+    }
+}
+
+/**
+ * Filter a list of change ops, keeping only valid ones.
+ * Logs warnings for any skipped ops.
+ */
+function filterValidOps(ops: unknown[]): ChangeOp[] {
+    const valid: ChangeOp[] = [];
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        if (isValidChangeOp(op)) {
+            valid.push(op);
+        } else {
+            console.warn(`[ClaudeCode] Skipping invalid change op at index ${i}:`, JSON.stringify(ops[i]));
+        }
+    }
+    return valid;
+}
+
+// ---------------------------------------------------------------------------
+// Chat mode heuristic
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple heuristic to detect chat/question messages.
+ * Per spec: message ends with `?` and is under 100 characters.
+ */
+function isChatQuestion(message: string): boolean {
+    const trimmed = message.trim();
+    return trimmed.length < 100 && trimmed.endsWith('?');
+}
+
+// ---------------------------------------------------------------------------
+// Builder factory
+// ---------------------------------------------------------------------------
+
+export function createClaudeCodeBuilder(
+    userInstructions?: string,
+    productName?: string,
+    options?: ClaudeCodeBuilderOptions,
+): Builder {
+    const name = productName ?? 'SynthOS';
+    const opts: ClaudeCodeBuilderOptions = options ?? {};
+
+    return {
+        async run(currentPage, additionalSections, userMessage, newBuild, _attachments?): Promise<BuilderResult> {
+            try {
+                const chatMode = !newBuild && isChatQuestion(userMessage);
+
+                let prompt: string;
+
+                if (chatMode) {
+                    // -- Chat prompt: no change-ops, no node annotations --
+                    const contextParts: string[] = [
+                        `<CURRENT_PAGE>\n${currentPage.content}\n</CURRENT_PAGE>`,
+                    ];
+                    for (const section of additionalSections) {
+                        if (section.content) {
+                            contextParts.push(`${section.title}\n${section.content}`);
+                        }
+                    }
+
+                    prompt = `You are ${name}, a helpful assistant. Answer the user's question about their page.\n\n`
+                        + contextParts.join('\n\n')
+                        + `\n\n<USER_MESSAGE>\n${userMessage}\n</USER_MESSAGE>`;
+                } else {
+                    // -- Build/change prompt (same structure as before) --
+                    const systemParts: string[] = [
+                        `${currentPage.title}\n${currentPage.content}`,
+                    ];
+                    for (const section of additionalSections) {
+                        if (section.content) {
+                            systemParts.push(`${section.title}\n${section.content}`);
+                        }
+                    }
+                    const systemContent = systemParts.join('\n\n');
+
+                    const instructionParts: string[] = [];
+                    if (userInstructions?.trim()) {
+                        instructionParts.push(userInstructions);
+                    }
+                    for (const section of additionalSections) {
+                        if (section.instructions?.trim()) {
+                            instructionParts.push(section.instructions);
+                        }
+                    }
+                    instructionParts.push(getTransformInstr(name));
+                    instructionParts.push(CHANGE_OPS_FORMAT_INSTRUCTION);
+
+                    const instructions = instructionParts.filter(s => s.trim() !== '').join('\n');
+
+                    prompt = `${systemContent}\n\n<USER_MESSAGE>\n${userMessage}\n\n<INSTRUCTIONS>\n${instructions}`;
+                }
+
+                // -- Spawn claude CLI (with retry on empty output) --
+                const output = await executeWithRetry(prompt, opts);
+
+                // Chat mode always returns a reply — skip change-ops parsing
+                if (chatMode) {
+                    return { kind: 'reply', text: output };
+                }
+
+                // Try to parse as builder response (JSON change ops or reply)
+                const parsed = parseBuilderResponse(output);
+
+                // Validate individual change ops — skip invalid ones
+                if (parsed.kind === 'transforms') {
+                    const validated = filterValidOps(parsed.changes);
+                    if (validated.length === 0) {
+                        // All ops were invalid — treat the raw output as a text reply
+                        return { kind: 'reply', text: output };
+                    }
+                    return { kind: 'transforms', changes: validated };
+                }
+
+                return parsed;
+            } catch (err: unknown) {
+                // Spawn failure (e.g. ENOENT when claude is not on PATH)
+                if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+                    return {
+                        kind: 'error',
+                        error: new Error(
+                            'Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-code'
+                        ),
+                    };
+                }
+                return { kind: 'error', error: err instanceof Error ? err : new Error(String(err)) };
+            }
+        }
+    };
+}

package/src/builders/index.ts

@@ -2,12 +2,14 @@ import { ProviderName, completePrompt } from '../models';
 import { createAnthropicBuilder, AnthropicBuilderOptions } from './anthropic';
 import { createOpenAIBuilder } from './openai';
 import { createFireworksAIBuilder } from './fireworksai';
+import { createClaudeCodeBuilder } from './claudecode';
 import { Builder } from './types';
 
-export { ContextSection, BuilderResult, Builder, Attachment } from './types';
+export { ContextSection, SectionMode, BuilderResult, Builder, Attachment } from './types';
 export { createAnthropicBuilder, AnthropicBuilderOptions } from './anthropic';
 export { createOpenAIBuilder } from './openai';
 export { createFireworksAIBuilder } from './fireworksai';
+export { createClaudeCodeBuilder, ClaudeCodeBuilderOptions } from './claudecode';
 export { parseBuilderResponse } from './anthropic';
 
 /**
@@ -27,6 +29,10 @@ export function createBuilder(
             return createOpenAIBuilder(complete, userInstructions, productName);
         case 'FireworksAI':
             return createFireworksAIBuilder(complete, userInstructions, productName);
+        case 'ClaudeCode':
+            return createClaudeCodeBuilder(userInstructions, productName, {
+                model: options?.model,
+            });
         default:
             throw new Error(`Unknown provider: ${provider}`);
     }

package/src/builders/openai.ts

@@ -80,7 +80,8 @@ function parseOpenAIResponse(raw: string): BuilderResult {
     try {
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.changes)) {
-            return { kind: 'transforms', changes: parsed.changes };
+            const message = typeof parsed.message === 'string' ? parsed.message : undefined;
+            return { kind: 'transforms', changes: parsed.changes, message };
         }
     } catch {
         // fall through to shared parser

package/src/builders/types.ts

@@ -1,4 +1,5 @@
 import { ChangeList } from '../service/transformPage';
+import { ToolDefinition, ToolHandler } from '../models/types';
 
 // ---------------------------------------------------------------------------
 // Change operations output format — text instruction for non-structured builders
@@ -8,28 +9,31 @@ import { ChangeList } from '../service/transformPage';
  * Text instruction that tells the model to return a JSON array of change operations.
  * Append this to <INSTRUCTIONS> for builders that don't support structured outputs.
  */
-export const CHANGE_OPS_FORMAT_INSTRUCTION = `Return a JSON array of change operations to apply to the page. Do NOT return the full HTML page.
+export const CHANGE_OPS_FORMAT_INSTRUCTION = `Return a JSON object with two fields: "message" and "changes".
 
-Each operation must be one of:
-{ "op": "update", "nodeId": "<data-node-id>", "html": "<new innerHTML>" }
+"message" is a brief (1 sentence) message to the user explaining what you changed. It is shown in the chat feed as the assistant's reply — write it directly to the user, not a description of the JSON.
+"changes" is an array of change operations to apply to the page. Do NOT return the full HTML page.
+
+Each change operation must be one of:
+{ "op": "update", "nodeId": "<data-nid>", "html": "<new innerHTML>" }
   — replaces the innerHTML of the target element
 
-{ "op": "replace", "nodeId": "<data-node-id>", "html": "<new outerHTML>" }
+{ "op": "replace", "nodeId": "<data-nid>", "html": "<new outerHTML>" }
   — replaces the entire element (outerHTML) with new markup
 
-{ "op": "delete", "nodeId": "<data-node-id>" }
+{ "op": "delete", "nodeId": "<data-nid>" }
   — removes the element from the page
 
-{ "op": "insert", "parentId": "<data-node-id>", "position": "prepend"|"append"|"before"|"after", "html": "<new element HTML>" }
+{ "op": "insert", "parentId": "<data-nid>", "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>" }
+{ "op": "style-element", "nodeId": "<data-nid>", "style": "<css style string>" }
   — sets the style attribute of the target element (must be unlocked)
 
-{ "op": "search-replace", "nodeId": "<data-node-id>", "search": "<exact text to find>", "replace": "<replacement text>" }
+{ "op": "search-replace", "nodeId": "<data-nid>", "search": "<exact text to find>", "replace": "<replacement text>" }
   — finds exact text within a script/style block and replaces it. Use empty string for replace to delete.
 
-{ "op": "search-insert", "nodeId": "<data-node-id>", "after": "<exact text to find>", "content": "<new lines to insert>" }
+{ "op": "search-insert", "nodeId": "<data-nid>", "after": "<exact text to find>", "content": "<new lines to insert>" }
   — inserts new content immediately after the matched text in a script/style block.
 
 For partial edits to large scripts/styles, use search-replace or search-insert instead of
@@ -38,21 +42,26 @@ Copy the search/after text exactly as it appears in the source.
 When making multiple edits to the same block, ensure each search string targets distinct text.
 To delete code, use search-replace with an empty replace string.
 
-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>" }
-]`;
+Return ONLY the JSON object. Example:
+{
+  "message": "Changed the heading and added a new notice.",
+  "changes": [
+    { "op": "update", "nodeId": "5", "html": "<p>Hello world</p>" },
+    { "op": "insert", "parentId": "3", "position": "append", "html": "<div class=\\"msg\\">New message</div>" }
+  ]
+}`;
 
 // ---------------------------------------------------------------------------
 // Change operations JSON schema — for structured output (constrained decoding)
 // ---------------------------------------------------------------------------
 
-/**
- * JSON schema matching the ChangeOp union type for Anthropic structured outputs.
- * The top-level schema is an array of change operations.
- */
-export const CHANGE_OPS_SCHEMA: Record<string, unknown> = {
+const CHANGE_OP_MESSAGE_SCHEMA = {
+    type: 'string',
+    description: 'Brief (1 sentence) message to the user explaining the change. Written directly to the user; shown in the chat feed as the assistant reply.',
+};
+
+/** Array schema for the full change-op union (ranged writes allowed). */
+const CHANGE_OPS_ARRAY_SCHEMA: Record<string, unknown> = {
     type: 'array',
     items: {
         anyOf: [
@@ -132,12 +141,8 @@ export const CHANGE_OPS_SCHEMA: Record<string, unknown> = {
     },
 };
 
-/**
- * Variant of CHANGE_OPS_SCHEMA that omits ranged write operations (search-replace, search-insert).
- * Used for medium/hard/re-write changes where the model should replace full blocks instead of
- * attempting partial edits.
- */
-export const CHANGE_OPS_SCHEMA_NO_RANGED: Record<string, unknown> = {
+/** Array schema with ranged write ops omitted. */
+const CHANGE_OPS_ARRAY_SCHEMA_NO_RANGED: Record<string, unknown> = {
     type: 'array',
     items: {
         anyOf: [
@@ -195,6 +200,36 @@ export const CHANGE_OPS_SCHEMA_NO_RANGED: Record<string, unknown> = {
     },
 };
 
+/**
+ * JSON schema for Anthropic structured outputs.
+ * Wraps the change-ops array in `{ message, changes }` so the model always
+ * emits a user-facing message alongside its page changes.
+ */
+export const CHANGE_OPS_SCHEMA: Record<string, unknown> = {
+    type: 'object',
+    properties: {
+        message: CHANGE_OP_MESSAGE_SCHEMA,
+        changes: CHANGE_OPS_ARRAY_SCHEMA,
+    },
+    required: ['message', 'changes'],
+    additionalProperties: false,
+};
+
+/**
+ * Variant of CHANGE_OPS_SCHEMA that omits ranged write operations (search-replace, search-insert).
+ * Used for medium/hard/re-write changes where the model should replace full blocks instead of
+ * attempting partial edits.
+ */
+export const CHANGE_OPS_SCHEMA_NO_RANGED: Record<string, unknown> = {
+    type: 'object',
+    properties: {
+        message: CHANGE_OP_MESSAGE_SCHEMA,
+        changes: CHANGE_OPS_ARRAY_SCHEMA_NO_RANGED,
+    },
+    required: ['message', 'changes'],
+    additionalProperties: false,
+};
+
 /**
  * Text instruction variant for no-ranged-writes mode.
  * Tells the model to use `update` for full innerHTML replacement instead of partial edits.
@@ -203,14 +238,15 @@ export const CHANGE_OPS_FORMAT_INSTRUCTION_NO_RANGED = `For script and style blo
 
 /**
  * OpenAI structured outputs require a root-level object.
- * This wraps CHANGE_OPS_SCHEMA in { changes: [...] }.
+ * Matches the Anthropic shape: { message, changes }.
  */
 export const OPENAI_CHANGE_OPS_SCHEMA: Record<string, unknown> = {
     type: 'object',
     properties: {
-        changes: CHANGE_OPS_SCHEMA,
+        message: CHANGE_OP_MESSAGE_SCHEMA,
+        changes: CHANGE_OPS_ARRAY_SCHEMA,
     },
-    required: ['changes'],
+    required: ['message', 'changes'],
     additionalProperties: false,
 };
 
@@ -218,11 +254,33 @@ export const OPENAI_CHANGE_OPS_SCHEMA: Record<string, unknown> = {
 // Context sections — structured blocks passed to the builder
 // ---------------------------------------------------------------------------
 
+export type SectionMode =
+    /** Always rendered in full. Never sketched. Used for small/universally relevant sections. */
+    | 'always-full'
+    /** Sketched by default; rendered in full when the classifier expands it. */
+    | 'classifier-decides'
+    /** Skipped entirely when sketch === null; otherwise sketched/expanded like classifier-decides. */
+    | 'always-omit-when-empty';
+
 export interface ContextSection {
-    /** Section title, e.g. "<CURRENT_PAGE>", "<SERVER_SCRIPTS>" */
+    /** Section title, e.g. "<CURRENT_PAGE>", "<SERVER_SCRIPTS>". Used as the classifier expand-set key. */
     title: string;
-    /** The text body of this section */
+    /** Full render — what the model sees when this section is expanded. */
     content: string;
+    /**
+     * Compact render — what the classifier sees, and what the model sees when this
+     * section is NOT expanded. `null` means "omit entirely from the prompt when not
+     * expanded" (used by always-omit-when-empty sections that have nothing to say,
+     * or by always-full sections where sketch is irrelevant).
+     */
+    sketch: string | null;
+    /** Default behavior for this section. Producer-declared. */
+    mode: SectionMode;
+    /**
+     * If true, this section is always rendered in full on the initial page build,
+     * regardless of classifier output. Defaults to false.
+     */
+    forceFullOnInitial?: boolean;
     /** How the model should work with this section (appended to instructions) */
     instructions: string;
 }
@@ -232,7 +290,7 @@ export interface ContextSection {
 // ---------------------------------------------------------------------------
 
 export type BuilderResult =
-    | { kind: 'transforms'; changes: ChangeList }
+    | { kind: 'transforms'; changes: ChangeList; message?: string }
     | { kind: 'reply'; text: string }
     | { kind: 'error'; error: Error };
 
@@ -256,6 +314,9 @@ export interface Builder {
         additionalSections: ContextSection[],
         userMessage: string,
         newBuild: boolean,
-        attachments?: Attachment[]
+        attachments?: Attachment[],
+        tools?: ToolDefinition[],
+        toolHandlers?: Record<string, ToolHandler>,
+        onToolCall?: (names: string[]) => void,
     ): Promise<BuilderResult>;
 }

package/src/connectors/types.ts

@@ -30,6 +30,10 @@ export interface ConnectorDefinition {
     tokenUrl?: string;
     /** OAuth2: Requested scopes. */
     scopes?: string[];
+    /** OAuth2: Use PKCE (RFC 7636) on the authorization-code flow. Required by Buffer, Canva, etc. */
+    usePkce?: boolean;
+    /** OAuth2: Separator used to join scopes in the authorize request. Defaults to comma; RFC 6749 mandates space. */
+    scopeSeparator?: ' ' | ',';
 }
 
 export interface ConnectorJson {
@@ -46,6 +50,8 @@ export interface ConnectorJson {
     authorizationUrl?: string;
     tokenUrl?: string;
     scopes?: string[];
+    usePkce?: boolean;
+    scopeSeparator?: ' ' | ',';
 }
 
 export interface ConnectorConfig {
@@ -61,6 +67,8 @@ export interface ConnectorOAuthConfig extends ConnectorConfig {
     accountName?: string;
     clientId?: string;
     clientSecret?: string;
+    /** Stored between /authorize and /callback for PKCE-enabled connectors. Cleared after callback. */
+    codeVerifier?: string;
 }
 
 export type ConnectorsConfig = Record<string, ConnectorConfig | ConnectorOAuthConfig>;

package/src/init.ts

@@ -38,6 +38,11 @@ export async function createConfig(
         customizer?.requiredPagesFolders ?? ['default'],
         path.join(__dirname, '../required-pages')
     );
+    // Starter pages (category "_Starters") ship in the package's starters/
+    // folder and act as a read-only fallback for the runtime: they are
+    // discoverable by listPages, loadPageMetadata, and loadPageWithFallback
+    // without being copied into .synthos/pages/.
+    requiredPagesFolders.push(path.join(__dirname, '../starters'));
     const requiredPages = await getRequiredPages(requiredPagesFolders);
     return {
         localFolder: pagesFolder,
@@ -107,10 +112,6 @@ export async function init(config: SynthOSConfig, includeDefaultPages: boolean =
 
     await sp.saveFile(path.join(scriptsFolder, 'example.sh'), `#!/bin/bash\n\n# This is an example script\n\n# You can run this script using the following command:\n# sh ${config.localFolder}/scripts/example.sh\n\n# This script will print "Hello, World!" to the console\n\necho "Hello, World!"\n`);
 
-    // Create empty themes folder — default themes are served directly from
-    // defaultThemesFolders; users can add custom themes here.
-    await sp.ensureFolderExists(path.join(config.pagesFolder, 'themes'));
-
     // Copy pages
     if (includeDefaultPages) {
         console.log(`Copying default pages to ${config.localFolder} folder...`);
@@ -141,9 +142,14 @@ async function repairMissingFolders(config: SynthOSConfig): Promise<void> {
         await sp.saveFile(path.join(scriptsFolder, 'example.sh'), `#!/bin/bash\n\n# This is an example script\n\n# You can run this script using the following command:\n# sh ${config.localFolder}/scripts/example.sh\n\n# This script will print "Hello, World!" to the console\n\necho "Hello, World!"\n`);
     }
 
-    // Ensure themes folder exists — default themes are served directly from
-    // defaultThemesFolders; this folder is for user-added custom themes only.
-    await sp.ensureFolderExists(path.join(config.pagesFolder, 'themes'));
+    // User-local themes are no longer supported — all themes are served from
+    // defaultThemesFolders. Remove any stale .synthos/themes/ folder left over
+    // from previous versions so it can't shadow default themes.
+    const staleThemesFolder = path.join(config.pagesFolder, 'themes');
+    if (await sp.checkIfExists(staleThemesFolder)) {
+        console.log(`Removing stale ${config.localFolder}/themes folder (themes now come from default-themes)...`);
+        await sp.deleteFolder(staleThemesFolder);
+    }
 
     // Ensure pages/ subfolder exists
     const pagesSubdir = path.join(config.pagesFolder, 'pages');