primo-cli 0.1.3 → 0.1.5

package/dist/commands/dev.js

@@ -1,23 +1,400 @@
 import fs from 'fs/promises';
-import { watch } from 'fs';
 import path from 'path';
+import { createHash, randomInt } from 'crypto';
 import chalk from 'chalk';
 import ora from 'ora';
 import { spawn } from 'child_process';
 import archiver from 'archiver';
 import extract from 'extract-zip';
+import { dump as dump_yaml, load as load_yaml } from 'js-yaml';
+import chokidar from 'chokidar';
 import { ensure_binary, ensure_data_dir } from '../utils/binary.js';
+import { read_site_config, SITE_CONFIG_FILE } from '../utils/site-config.js';
+import { read_server_config, format_group_name, SERVER_CONFIG_FILE, resolve_format_options } from '../utils/server-config.js';
+import { format_file_contents, should_format } from '../utils/format.js';
 import { normalize_site } from './validate.js';
+function local_dev_host(name, port) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'site';
+    return `${slug}.localhost:${port}`;
+}
 let cms_process = null;
 let watchers = [];
 let reimport_timeout = null;
+let library_reimport_timeout = null;
 let sync_interval = null;
 let is_syncing = false;
 let is_importing = false;
 let is_cleaning_up = false;
+let last_import_time = 0; // Timestamp of last import completion
+let last_local_change_time = 0; // Timestamp of most recent local watcher event
+const importing_site_keys = new Set();
+const pending_local_site_keys = new Set();
+let is_importing_library = false;
+let has_pending_library_local_changes = false;
+let site_sync_baselines = new Map();
+// Tracks the last set of conflict paths logged per site so we don't reprint
+// the same conflict block every pull cycle when palacms's serialization
+// keeps producing the same divergence (e.g. data-key mangling, key reorder).
+const last_logged_conflicts = new Map();
 // Track files written by sync to prevent watcher from re-pushing them
 // Map of filepath -> mtime (ms) when we wrote it
 const synced_files = new Map();
+const synced_deleted_paths = new Map();
+const warned_empty_schema_writebacks = new Set();
+let library_snapshot = new Map();
+const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const SITES_DIR = 'sites';
+const LIBRARY_DIR = 'library';
+const MCP_CONFIG_FILE = '.mcp.json';
+const SITE_SYNC_DIRS = ['blocks', 'page-types', 'pages', 'site'];
+const LOCAL_PUSH_DEBOUNCE_MS = 150;
+const LOCAL_ZIP_COMPRESSION_LEVEL = 0;
+// Tolerance for matching a file mtime against the synced_files map to decide
+// whether an fs.watch event was caused by our own sync-write. Wider values
+// trade duplicate push work for safety against slow I/O and flaky watchers
+// (macOS fs.watch fires inconsistently for recursive writes).
+const SYNC_MTIME_TOLERANCE_MS = 3000;
+// When the user writes a file locally, suppress CMS->local pulls for this
+// long to prevent a pull that was in-flight before the watcher fired from
+// stomping the just-written content on arrival.
+const LOCAL_CHANGE_PULL_COOLDOWN_MS = 3000;
+// Prior file content is copied to .primo/trash/ before any CMS->file
+// overwrite so the user can recover work if the sync picked the wrong side.
+// Entries older than this are pruned on dev server startup.
+const TRASH_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+async function trash_existing_file(prior_content, workspace_dir, site_name, file_relative) {
+    const trash_dir = path.join(workspace_dir, '.primo', 'trash');
+    await fs.mkdir(trash_dir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const safe_path = file_relative.replace(/[/\\]/g, '__');
+    const trash_path = path.join(trash_dir, `${stamp}_${site_name}_${safe_path}`);
+    await fs.writeFile(trash_path, prior_content);
+}
+// Recursively trash every file under a path before it gets deleted, so
+// CMS->file deletes are recoverable the same way overwrites are.
+async function trash_path_recursive(target_path, workspace_dir, site_name, file_relative) {
+    let stat;
+    try {
+        stat = await fs.stat(target_path);
+    }
+    catch {
+        return;
+    }
+    if (stat.isFile()) {
+        const content = await fs.readFile(target_path, 'utf-8').catch(() => null);
+        if (content !== null) {
+            await trash_existing_file(content, workspace_dir, site_name, file_relative);
+        }
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    const entries = await fs.readdir(target_path, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const child_path = path.join(target_path, entry.name);
+        const child_relative = `${file_relative}/${entry.name}`;
+        await trash_path_recursive(child_path, workspace_dir, site_name, child_relative);
+    }
+}
+// Compare line counts between prior and incoming content to flag suspicious
+// shrinkage. Returns the negative delta (e.g. -12) when the file lost lines
+// or was emptied; null when it grew, stayed the same, or didn't exist before.
+function compute_shrink_delta(prior, next) {
+    if (!prior)
+        return null;
+    const prior_lines = prior.split('\n').length;
+    const next_lines = next.split('\n').length;
+    const delta = next_lines - prior_lines;
+    return delta < 0 ? delta : null;
+}
+// Write the most recent push outcome to a file the MCP build_preview tool
+// reads, so the agent learns when its file changes failed to land in the CMS.
+// Without this, build_preview compiles whatever stale DB state existed before
+// the failed push and reports ok:true, leaving the agent to chase phantom
+// rendering bugs instead of fixing the source error.
+async function write_sync_status(site_dir, status) {
+    const status_dir = path.join(site_dir, '.primo');
+    try {
+        await fs.mkdir(status_dir, { recursive: true });
+        await fs.writeFile(path.join(status_dir, 'sync_status.json'), JSON.stringify(status, null, 2));
+    }
+    catch {
+        // Status reporting must not break the push.
+    }
+}
+async function prune_old_trash(workspace_dir) {
+    const trash_dir = path.join(workspace_dir, '.primo', 'trash');
+    try {
+        const entries = await fs.readdir(trash_dir);
+        const cutoff = Date.now() - TRASH_RETENTION_MS;
+        await Promise.all(entries.map(async (name) => {
+            const full = path.join(trash_dir, name);
+            const stat = await fs.stat(full).catch(() => null);
+            if (stat && stat.mtimeMs < cutoff) {
+                await fs.unlink(full).catch(() => { });
+            }
+        }));
+    }
+    catch {
+        // trash dir doesn't exist yet — nothing to prune
+    }
+}
+function get_site_sync_key(site_dir, config) {
+    return config.site_id || site_dir;
+}
+function resolve_sync_policy(options) {
+    // Default mirrors the CLI's --author default: files-authoritative.
+    // This branch matters for callers that invoke dev_server programmatically
+    // (e.g. `primo new` after scaffolding) and bypass commander's default.
+    const raw = options.author ?? 'files';
+    if (raw !== 'files' && raw !== 'cms' && raw !== 'both') {
+        throw new Error(`Invalid --author value "${raw}". Use "files", "cms", or "both".`);
+    }
+    return { mode: raw };
+}
+function is_file_to_cms_active(sync_policy) {
+    return sync_policy.mode !== 'cms';
+}
+function is_cms_to_file_active(sync_policy) {
+    return sync_policy.mode !== 'files';
+}
+function describe_sync_state(sync_policy, sites) {
+    const file_state = is_file_to_cms_active(sync_policy)
+        ? 'file→CMS active'
+        : 'file→CMS paused (--author cms)';
+    let cms_state;
+    if (!is_cms_to_file_active(sync_policy)) {
+        cms_state = 'CMS→file paused (--author files)';
+    }
+    else {
+        const pending_sites = sites
+            .filter(site => pending_local_site_keys.has(get_site_sync_key(site.dir, site.config)))
+            .map(site => site.config.name);
+        if (pending_sites.length > 0) {
+            const shown = pending_sites.slice(0, 3).join(', ');
+            const suffix = pending_sites.length > 3 ? `, +${pending_sites.length - 3} more` : '';
+            cms_state = `CMS→file paused (pending local imports/warnings: ${shown}${suffix})`;
+        }
+        else if (sync_policy.mode === 'both') {
+            cms_state = 'CMS→file active (auto-pauses during local imports)';
+        }
+        else {
+            cms_state = 'CMS→file active';
+        }
+    }
+    return `${file_state}, ${cms_state}`;
+}
+function print_sync_status(sync_policy, sites) {
+    console.log(chalk.dim(`  watching: ${describe_sync_state(sync_policy, sites)}`));
+}
+function update_site_sync_state_after_import(site, timings, sync_policy) {
+    const site_key = get_site_sync_key(site.dir, site.config);
+    if (timings.warning_count > 0) {
+        pending_local_site_keys.add(site_key);
+        if (is_cms_to_file_active(sync_policy)) {
+            console.log(chalk.yellow(`  ${site.config.name}: CMS-to-file sync paused until import warnings are resolved.`));
+        }
+        return false;
+    }
+    const was_pending = pending_local_site_keys.delete(site_key);
+    if (was_pending && is_cms_to_file_active(sync_policy)) {
+        console.log(chalk.dim(`  ${site.config.name}: CMS-to-file sync resumed.`));
+    }
+    return true;
+}
+// The baseline must reflect what the CMS actually has after a write, not what
+// we wrote to disk. The import endpoint mutates records as a side effect
+// (bumps `updated`, delete+inserts page_sections and *_entries with new IDs,
+// normalizes field shapes), so a baseline snapshotted from local files
+// disagrees with the CMS export on the very next pull and find_conflict_paths
+// reports a phantom conflict — losing the user's edits to .primo/trash/.
+// Fetching the post-import export and snapshotting that keeps the baseline
+// aligned with the remote. Falls back to the local snapshot if the fetch
+// fails so we don't lose conflict detection on transient network errors.
+async function update_site_sync_baseline(site, api_url, server_config, workspace_dir) {
+    const site_key = get_site_sync_key(site.dir, site.config);
+    if (api_url && server_config && workspace_dir) {
+        try {
+            const cms_snapshot = await fetch_cms_site_snapshot(site.dir, api_url, site.config, server_config, workspace_dir, 'baseline-temp');
+            if (cms_snapshot) {
+                site_sync_baselines.set(site_key, cms_snapshot);
+                return;
+            }
+        }
+        catch {
+            // Fall through to local snapshot.
+        }
+    }
+    site_sync_baselines.set(site_key, await collect_site_snapshot(site.dir));
+}
+function get_site_sync_baseline(site) {
+    return site_sync_baselines.get(get_site_sync_key(site.dir, site.config));
+}
+function hash_snapshot_content(contents) {
+    return createHash('sha256').update(contents.trim()).digest('hex');
+}
+function snapshot_value(snapshot, file_path) {
+    return snapshot.has(file_path) ? snapshot.get(file_path) : null;
+}
+// Reads a file but treats ENOENT as a soft miss — palacms' export step can
+// reshape the on-disk layout (e.g. promoting pages/foo.yaml to
+// pages/foo/index.yaml when a child route is added) between when a directory
+// listing is captured and when each file is read. The vanished file isn't an
+// error; it's just out of scope for this snapshot.
+async function read_file_or_vanish(full_path, label) {
+    try {
+        return await fs.readFile(full_path, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            console.log(chalk.dim(`  skipped (vanished): ${label}`));
+            return null;
+        }
+        throw error;
+    }
+}
+// A path is "in conflict" when local has content that differs from CMS AND
+// the local content represents a real user change — not just CMS-side
+// serialization noise (palacms re-emits YAML with normalized key order,
+// ISO-coerced dates, etc., so the CMS export legitimately differs from a
+// freshly-scaffolded file forever, and we don't want to scream about that
+// every pull cycle).
+//
+// "Real user change" means one of:
+//   - No baseline entry exists for this path (brand-new local file the
+//     CMS hasn't seen yet — protects the post-scaffold race)
+//   - Local content differs from baseline (user has edited the file since
+//     the last successful sync)
+//
+// If the baseline matches local but CMS differs, that's pure CMS-side
+// drift — pure pull, no conflict, the CMS value is allowed to overwrite.
+function find_conflict_paths(base, local, cms) {
+    const conflicts = [];
+    for (const [file_path, local_value] of local) {
+        if (local_value === undefined || local_value === null)
+            continue;
+        const cms_value = snapshot_value(cms, file_path);
+        const base_value = base ? snapshot_value(base, file_path) : null;
+        // Same content on both sides → not a conflict.
+        if (cms_value !== null && cms_value === local_value)
+            continue;
+        // CMS-side delete: still a conflict if local has content the user
+        // authored (covers the case of a brand-new local file the CMS
+        // hasn't been told about yet).
+        const local_is_new = base_value === null;
+        const local_is_edited = base_value !== null && local_value !== base_value;
+        if (!local_is_new && !local_is_edited)
+            continue;
+        conflicts.push(file_path);
+    }
+    return conflicts.sort();
+}
+function log_sync_conflict(site_name, winner, reason, paths) {
+    if (paths.length === 0)
+        return;
+    const winner_text = winner === 'unresolved'
+        ? chalk.red('NO SIDE WON — files diverged')
+        : winner === 'files'
+            ? chalk.green('FILES WON')
+            : chalk.blue('CMS WON');
+    // Blank lines + bold header so the conflict is impossible to miss in
+    // the surrounding push/pull spam. Beta users need to see this clearly.
+    console.log('');
+    console.log(chalk.bold.yellow(`  ⚠ SYNC CONFLICT  ${site_name}  →  ${winner_text}`));
+    console.log(chalk.dim(`     reason: ${reason}`));
+    for (const p of paths.slice(0, 10)) {
+        console.log(chalk.yellow(`     • ${p}`));
+    }
+    if (paths.length > 10) {
+        console.log(chalk.dim(`     • +${paths.length - 10} more`));
+    }
+    if (winner === 'CMS') {
+        console.log(chalk.dim(`     prior file content saved to .primo/trash/`));
+    }
+    console.log('');
+}
+async function collect_site_snapshot(root_dir, options = {}) {
+    const snapshot = new Map();
+    for (const dir of SITE_SYNC_DIRS) {
+        await collect_directory_snapshot(path.join(root_dir, dir), dir, snapshot, options);
+    }
+    return snapshot;
+}
+async function collect_directory_snapshot(current_dir, relative_dir, snapshot, options) {
+    let entries;
+    try {
+        entries = await fs.readdir(current_dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const full_path = path.join(current_dir, entry.name);
+        const file_relative = relative_dir ? `${relative_dir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            await collect_directory_snapshot(full_path, file_relative, snapshot, options);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const initial = await read_file_or_vanish(full_path, file_relative);
+        if (initial === null)
+            continue;
+        let contents = initial;
+        const dest_path = options.dest_root ? path.join(options.dest_root, file_relative) : full_path;
+        if (options.format_options && options.workspace_dir && should_format(dest_path)) {
+            contents = await format_file_contents(dest_path, contents, options.workspace_dir, options.format_options);
+        }
+        snapshot.set(file_relative, hash_snapshot_content(contents));
+    }
+}
+async function fetch_cms_site_snapshot(site_dir, api_url, config, server_config, workspace_dir, temp_name) {
+    const response = await fetch_with_timeout(`${api_url}/api/palacms/export/${config.site_id}`, {}, 15000);
+    if (!response.ok)
+        return null;
+    const temp_dir = path.join(site_dir, '.primo', temp_name);
+    const temp_zip = path.join(temp_dir, 'export.zip');
+    await fs.rm(temp_dir, { recursive: true, force: true });
+    await fs.mkdir(temp_dir, { recursive: true });
+    try {
+        const zip_data = await response.arrayBuffer();
+        await fs.writeFile(temp_zip, Buffer.from(zip_data));
+        await extract(temp_zip, { dir: temp_dir });
+        await fs.unlink(temp_zip);
+        return await collect_site_snapshot(temp_dir, {
+            workspace_dir,
+            format_options: resolve_format_options(server_config),
+            dest_root: site_dir
+        });
+    }
+    finally {
+        await fs.rm(temp_dir, { recursive: true, force: true });
+    }
+}
+async function detect_site_file_push_conflicts(site, api_url, server_config, workspace_dir) {
+    const baseline = get_site_sync_baseline(site);
+    if (!baseline)
+        return [];
+    const [local_snapshot, cms_snapshot] = await Promise.all([
+        collect_site_snapshot(site.dir),
+        fetch_cms_site_snapshot(site.dir, api_url, site.config, server_config, workspace_dir, 'conflict-temp')
+    ]);
+    if (!cms_snapshot)
+        return [];
+    return find_conflict_paths(baseline, local_snapshot, cms_snapshot);
+}
+async function with_site_import_lock(site_dir, config, fn) {
+    const site_key = get_site_sync_key(site_dir, config);
+    importing_site_keys.add(site_key);
+    try {
+        return await fn();
+    }
+    finally {
+        importing_site_keys.delete(site_key);
+    }
+}
 // Check if a port is in use
 async function is_port_in_use(port) {
     try {
@@ -31,6 +408,30 @@ async function is_port_in_use(port) {
         return false;
     }
 }
+// Kill processes on a specific port
+async function kill_port(port) {
+    return new Promise((resolve) => {
+        const lsof = spawn('lsof', ['-ti', `:${port}`]);
+        let pids = '';
+        lsof.stdout.on('data', (data) => { pids += data.toString(); });
+        lsof.on('close', () => {
+            const pid_list = pids.trim().split('\n').filter(Boolean);
+            if (pid_list.length === 0) {
+                resolve(false);
+                return;
+            }
+            for (const pid of pid_list) {
+                try {
+                    process.kill(parseInt(pid, 10), 'SIGKILL');
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+            resolve(true);
+        });
+    });
+}
 // Fetch with timeout helper
 async function fetch_with_timeout(url, options = {}, timeout_ms = 10000) {
     const controller = new AbortController();
@@ -61,32 +462,44 @@ async function kill_process(proc) {
     }
 }
 export async function dev_server(options) {
-    const spinner = ora('Starting Pala...').start();
+    const spinner = ora('Starting Primo...').start();
     try {
+        const sync_policy = resolve_sync_policy(options);
+        site_sync_baselines = new Map();
         const base_dir = path.resolve(options.dir);
-        // Check for server.json (multi-site mode) or primo.json (single-site mode)
-        const server_config_path = path.join(base_dir, 'server.json');
-        const site_config_path = path.join(base_dir, 'primo.json');
+        await prune_old_trash(base_dir);
+        const mcp_registration_path = await register_primo_mcp_server(base_dir);
+        // Check for server config (multi-site mode) or site config (single-site mode)
+        const server_config_path = path.join(base_dir, SERVER_CONFIG_FILE);
         let server_config = {};
         let sites = [];
         let is_server_mode = false;
         try {
-            const server_data = await fs.readFile(server_config_path, 'utf-8');
-            server_config = JSON.parse(server_data);
+            server_config = await read_server_config(base_dir);
             is_server_mode = true;
         }
         catch {
-            // No server.json, check for primo.json
-        }
-        let port = server_config.port || parseInt(options.port, 10);
-        // Find an available port
-        const max_port_attempts = 10;
-        for (let i = 0; i < max_port_attempts; i++) {
-            if (!await is_port_in_use(port))
-                break;
-            port++;
-            if (i === max_port_attempts - 1) {
-                spinner.fail(`Ports ${port - max_port_attempts + 1}-${port} are all in use`);
+            // No server config, check for site config
+        }
+        const port = server_config.port || parseInt(options.port, 10);
+        // Check if ports are in use
+        const main_in_use = await is_port_in_use(port);
+        const reload_in_use = await is_port_in_use(port + 1);
+        if (main_in_use || reload_in_use) {
+            if (options.force) {
+                spinner.text = 'Killing existing processes...';
+                if (main_in_use)
+                    await kill_port(port);
+                if (reload_in_use)
+                    await kill_port(port + 1);
+                // Give processes time to release ports
+                await new Promise(resolve => setTimeout(resolve, 500));
+            }
+            else {
+                const ports_msg = main_in_use && reload_in_use
+                    ? `Ports ${port} and ${port + 1} are`
+                    : `Port ${main_in_use ? port : port + 1} is`;
+                spinner.fail(`${ports_msg} already in use. Use --force to kill existing processes.`);
                 process.exit(1);
             }
         }
@@ -99,12 +512,11 @@ export async function dev_server(options) {
         else {
             // Single site mode
             try {
-                const config_data = await fs.readFile(site_config_path, 'utf-8');
-                const config = JSON.parse(config_data);
+                const config = await read_site_config(base_dir);
                 sites = [{ dir: base_dir, config }];
             }
             catch {
-                spinner.fail('No server.json or primo.json found. Run `primo new` first.');
+                spinner.fail(`No ${SERVER_CONFIG_FILE} or ${SITE_CONFIG_FILE} found. Run \`primo new\` first.`);
                 process.exit(1);
             }
         }
@@ -114,10 +526,14 @@ export async function dev_server(options) {
         // Create data directory in project folder
         const data_dir = await ensure_data_dir(base_dir);
         spinner.text = 'Starting CMS...';
-        // Start the CMS binary with dev mode enabled
+        // Start the CMS binary with dev mode enabled. PRIMO_AUTHOR_MODE
+        // tells palacms which sync mode the CLI is running in so the CMS
+        // UI can gate its editable surfaces accordingly (read-only when
+        // the CLI is in --author files, since CMS edits would be discarded
+        // before they ever round-trip to disk).
         cms_process = spawn(binary_path, ['serve', '--http', `127.0.0.1:${port}`, '--dir', data_dir], {
             stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, PALA_DEV_MODE: '1' }
+            env: { ...process.env, PALA_DEV_MODE: '1', PRIMO_AUTHOR_MODE: sync_policy.mode }
         });
         // Capture stderr for errors
         let stderr_output = '';
@@ -133,26 +549,53 @@ export async function dev_server(options) {
             }
             process.exit(1);
         }
+        const api_url = `http://127.0.0.1:${port}`;
+        if (is_server_mode) {
+            spinner.text = sync_policy.mode === 'cms' ? 'Pulling shared library...' : 'Loading shared library...';
+            is_importing_library = true;
+            try {
+                if (sync_policy.mode === 'cms') {
+                    await sync_library_from_cms(base_dir, api_url);
+                }
+                else {
+                    await import_library_files(base_dir, api_url);
+                }
+            }
+            finally {
+                is_importing_library = false;
+            }
+        }
         // Normalize and load all sites
         spinner.text = `Loading ${sites.length} site${sites.length > 1 ? 's' : ''}...`;
-        const api_url = `http://127.0.0.1:${port}`;
         for (const site of sites) {
+            const use_bootstrap = !await site_exists(api_url, site.config.site_id);
+            if (sync_policy.mode === 'cms' && !use_bootstrap) {
+                await sync_from_cms(site.dir, api_url, site.config, server_config, base_dir, sync_policy);
+                continue;
+            }
             await normalize_site(site.dir);
-            await import_site_files(site.dir, api_url, site.config, port);
+            const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, use_bootstrap, base_dir));
+            if (update_site_sync_state_after_import(site, import_timings, sync_policy)) {
+                await update_site_sync_baseline(site, api_url, server_config, base_dir);
+            }
         }
         // Verify all sites are accessible before proceeding
         spinner.text = 'Verifying sites...';
         for (const site of sites) {
             await verify_site_ready(api_url, site.config.site_id);
         }
-        spinner.succeed('Pala running');
+        spinner.succeed('Primo running');
         console.log('');
+        if (mcp_registration_path) {
+            console.log(`  ${chalk.dim(`MCP server registered at ${mcp_registration_path} - agents in this directory can now use the Primo MCP server.`)}`);
+            console.log('');
+        }
         if (is_server_mode) {
             console.log(`  ${chalk.cyan('Dashboard:')} http://127.0.0.1:${port}/admin/dashboard`);
             console.log('');
         }
         for (const site of sites) {
-            const host = site.config.host || `${site.config.name.toLowerCase().replace(/\s+/g, '-')}.localhost:${port}`;
+            const host = local_dev_host(site.config.name, port);
             console.log(`  ${chalk.cyan(site.config.name)}`);
             console.log(`    ${chalk.dim('Edit:')}    http://${host}/admin/site`);
             console.log(`    ${chalk.dim('Preview:')} http://${host}/`);
@@ -163,52 +606,271 @@ export async function dev_server(options) {
         // Start watching for file changes
         const dirs_to_watch = ['blocks', 'page-types', 'pages', 'site'];
         const known_sites = new Set(sites.map(s => s.dir));
+        if (is_server_mode) {
+            const library_path = path.join(base_dir, LIBRARY_DIR);
+            // Prime the snapshot from the current disk state so the first
+            // post-startup push doesn't consider every existing folder as
+            // a potential delete.
+            library_snapshot = await scan_library_folders(library_path);
+            try {
+                const watcher = chokidar.watch(library_path, {
+                    ignored: (p) => path.basename(p).startsWith('.'),
+                    ignoreInitial: true,
+                    awaitWriteFinish: {
+                        stabilityThreshold: 60,
+                        pollInterval: 30
+                    }
+                });
+                const log_library_push_paused = (full_path) => {
+                    const filename = path.relative(library_path, full_path);
+                    console.log(chalk.dim(`  library: ${filename} ignored (file→CMS paused by --author cms)`));
+                };
+                const push_or_ignore_library_change = (full_path) => {
+                    if (!is_file_to_cms_active(sync_policy)) {
+                        log_library_push_paused(full_path);
+                        return;
+                    }
+                    // Mark pending synchronously so the sync interval cannot
+                    // sneak a pull through between the event and push.
+                    const was_pending = has_pending_library_local_changes;
+                    has_pending_library_local_changes = true;
+                    last_local_change_time = Date.now();
+                    if (!was_pending && sync_policy.mode === 'both') {
+                        console.log(chalk.dim('  library: CMS-to-file sync paused while local import is pending.'));
+                    }
+                    schedule_library_push();
+                };
+                const on_event = (full_path) => {
+                    if (should_skip_synced_delete(full_path))
+                        return;
+                    const synced_mtime = synced_files.get(full_path);
+                    if (synced_mtime) {
+                        // Our own sync-write — skip.
+                        fs.stat(full_path)
+                            .then(stat => {
+                            if (Math.abs(stat.mtimeMs - synced_mtime) < SYNC_MTIME_TOLERANCE_MS) {
+                                synced_files.delete(full_path);
+                                return;
+                            }
+                            synced_files.delete(full_path);
+                            push_or_ignore_library_change(full_path);
+                        })
+                            .catch(() => {
+                            synced_files.delete(full_path);
+                            push_or_ignore_library_change(full_path);
+                        });
+                        return;
+                    }
+                    push_or_ignore_library_change(full_path);
+                };
+                const schedule_library_push = () => {
+                    if (library_reimport_timeout)
+                        clearTimeout(library_reimport_timeout);
+                    library_reimport_timeout = setTimeout(async () => {
+                        if (is_importing) {
+                            // Re-arm; another push is in-flight.
+                            schedule_library_push();
+                            return;
+                        }
+                        try {
+                            is_importing = true;
+                            is_importing_library = true;
+                            // Diff current disk state against the last snapshot to
+                            // compute the deletes manifest. Only paths present in
+                            // the snapshot but absent on disk right now are real
+                            // user deletions. Race-free: we read disk AFTER the
+                            // debounce has settled.
+                            const current = await scan_library_folders(library_path);
+                            const delete_group_ids = [];
+                            const delete_symbol_ids = [];
+                            const delete_paths = [];
+                            for (const [snap_path, entry] of library_snapshot) {
+                                if (current.has(snap_path))
+                                    continue;
+                                delete_paths.push(snap_path);
+                                if (entry.id) {
+                                    if (entry.kind === 'group')
+                                        delete_group_ids.push(entry.id);
+                                    else
+                                        delete_symbol_ids.push(entry.id);
+                                }
+                            }
+                            delete_paths.sort();
+                            if (delete_paths.length > 0) {
+                                console.log(chalk.yellow(`  library: deleting ${delete_paths.length} path(s): ${delete_paths.join(', ')}`));
+                            }
+                            const import_timings = await import_library_files(base_dir, api_url, delete_group_ids, delete_symbol_ids);
+                            const reload_started = Date.now();
+                            await request_browser_reload(api_url);
+                            const reload_ms = Date.now() - reload_started;
+                            has_pending_library_local_changes = false;
+                            if (sync_policy.mode === 'both') {
+                                console.log(chalk.dim('  library: CMS-to-file sync resumed.'));
+                            }
+                            // Update snapshot only on successful push.
+                            library_snapshot = current;
+                            console.log(chalk.dim(`  library: zip ${import_timings.zip_ms}ms, import ${import_timings.request_ms}ms, reload ${reload_ms}ms`));
+                            console.log(chalk.green('  ✓ Library pushed'));
+                        }
+                        catch (err) {
+                            console.log(chalk.red(`  ✗ Library push failed: ${err}`));
+                        }
+                        finally {
+                            is_importing_library = false;
+                            is_importing = false;
+                            last_import_time = Date.now();
+                        }
+                    }, LOCAL_PUSH_DEBOUNCE_MS);
+                };
+                watcher.on('add', on_event);
+                watcher.on('change', on_event);
+                watcher.on('unlink', on_event);
+                watcher.on('addDir', on_event);
+                watcher.on('unlinkDir', on_event);
+                watchers.push(watcher);
+            }
+            catch {
+                // Library directory might not exist
+            }
+        }
         const setup_site_watchers = (site) => {
+            let pending_reload = false;
             const schedule_reimport = () => {
                 if (reimport_timeout) {
                     clearTimeout(reimport_timeout);
                 }
                 reimport_timeout = setTimeout(async () => {
+                    // If already importing, reschedule and wait
+                    if (is_importing) {
+                        schedule_reimport();
+                        return;
+                    }
                     try {
                         is_importing = true;
+                        const normalize_started = Date.now();
                         await normalize_site(site.dir);
-                        await import_site_files(site.dir, api_url, site.config, port);
+                        const normalize_ms = Date.now() - normalize_started;
+                        let conflict_paths = [];
+                        if (sync_policy.mode === 'both') {
+                            try {
+                                conflict_paths = await detect_site_file_push_conflicts(site, api_url, server_config, base_dir);
+                            }
+                            catch {
+                                // Conflict detection must not block the local push.
+                            }
+                        }
+                        const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, false, base_dir));
+                        let reload_ms = 0;
+                        if (pending_reload) {
+                            try {
+                                const reload_started = Date.now();
+                                await request_browser_reload(api_url);
+                                reload_ms = Date.now() - reload_started;
+                            }
+                            catch {
+                                console.log(chalk.yellow(`  Warning: Failed to trigger browser reload for ${site.config.name}`));
+                            }
+                            pending_reload = false;
+                        }
+                        if (conflict_paths.length > 0) {
+                            if (import_timings.warning_count > 0) {
+                                log_sync_conflict(site.config.name, 'unresolved', 'file push completed with import warnings; CMS-to-file sync paused until resolved', conflict_paths);
+                            }
+                            else {
+                                log_sync_conflict(site.config.name, 'files', 'both sides changed since last sync; local push was applied (CMS values from last poll were discarded)', conflict_paths);
+                            }
+                        }
+                        if (update_site_sync_state_after_import(site, import_timings, sync_policy)) {
+                            await update_site_sync_baseline(site, api_url, server_config, base_dir);
+                        }
+                        console.log(chalk.dim(`  ${site.config.name}: normalize ${normalize_ms}ms, zip ${import_timings.zip_ms}ms, ${import_timings.mode} ${import_timings.request_ms}ms${reload_ms ? `, reload ${reload_ms}ms` : ''}`));
                         console.log(chalk.green(`  ✓ ${site.config.name} pushed`));
+                        await write_sync_status(site.dir, { ok: true });
                     }
                     catch (err) {
-                        console.log(chalk.red(`  ✗ ${site.config.name} push failed: ${err}`));
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.log(chalk.red(`  ✗ ${site.config.name} push failed: ${message}`));
+                        await write_sync_status(site.dir, {
+                            ok: false,
+                            error: message,
+                            failed_at: new Date().toISOString()
+                        });
                     }
                     finally {
                         is_importing = false;
+                        last_import_time = Date.now(); // Track when import finished
                     }
-                }, 300);
+                }, LOCAL_PUSH_DEBOUNCE_MS);
             };
             for (const dir of dirs_to_watch) {
                 const watch_path = path.join(site.dir, dir);
                 try {
-                    const watcher = watch(watch_path, { recursive: true }, async (event, filename) => {
-                        if (!filename || filename.startsWith('.'))
+                    const watcher = chokidar.watch(watch_path, {
+                        ignored: (p) => path.basename(p).startsWith('.'),
+                        ignoreInitial: true,
+                        awaitWriteFinish: {
+                            stabilityThreshold: 60,
+                            pollInterval: 30
+                        }
+                    });
+                    const continue_event = (full_path) => {
+                        const filename = path.relative(watch_path, full_path);
+                        console.log(chalk.dim(`  ${site.config.name}: ${dir}/${filename}`));
+                        if (change_requires_reload(dir, filename)) {
+                            pending_reload = true;
+                        }
+                        schedule_reimport();
+                    };
+                    const mark_pending_local_change = () => {
+                        const site_key = get_site_sync_key(site.dir, site.config);
+                        const was_pending = pending_local_site_keys.has(site_key);
+                        pending_local_site_keys.add(site_key);
+                        last_local_change_time = Date.now();
+                        if (!was_pending && sync_policy.mode === 'both') {
+                            console.log(chalk.dim(`  ${site.config.name}: CMS-to-file sync paused while local import is pending.`));
+                        }
+                    };
+                    const log_file_push_paused = (full_path) => {
+                        const filename = path.relative(watch_path, full_path);
+                        console.log(chalk.dim(`  ${site.config.name}: ${dir}/${filename} ignored (file→CMS paused by --author cms)`));
+                    };
+                    const push_or_ignore_file_change = (full_path) => {
+                        if (!is_file_to_cms_active(sync_policy)) {
+                            log_file_push_paused(full_path);
+                            return;
+                        }
+                        // Mark site as pending synchronously so the sync interval
+                        // cannot pull against a site that's actively being edited.
+                        mark_pending_local_change();
+                        continue_event(full_path);
+                    };
+                    const on_event = (full_path) => {
+                        if (should_skip_synced_delete(full_path))
                             return;
-                        // Check if this file was just written by sync
-                        const full_path = path.join(watch_path, filename);
                         const synced_mtime = synced_files.get(full_path);
                         if (synced_mtime) {
-                            try {
-                                const stat = await fs.stat(full_path);
-                                // If mtime matches what we wrote, skip this event
-                                if (Math.abs(stat.mtimeMs - synced_mtime) < 1000) {
+                            fs.stat(full_path)
+                                .then(stat => {
+                                if (Math.abs(stat.mtimeMs - synced_mtime) < SYNC_MTIME_TOLERANCE_MS) {
                                     synced_files.delete(full_path);
                                     return;
                                 }
-                            }
-                            catch {
-                                // File might have been deleted
-                            }
-                            synced_files.delete(full_path);
+                                synced_files.delete(full_path);
+                                push_or_ignore_file_change(full_path);
+                            })
+                                .catch(() => {
+                                synced_files.delete(full_path);
+                                push_or_ignore_file_change(full_path);
+                            });
+                            return;
                         }
-                        console.log(chalk.dim(`  ${site.config.name}: ${dir}/${filename}`));
-                        schedule_reimport();
-                    });
+                        push_or_ignore_file_change(full_path);
+                    };
+                    watcher.on('add', on_event);
+                    watcher.on('change', on_event);
+                    watcher.on('unlink', on_event);
+                    watcher.on('addDir', on_event);
+                    watcher.on('unlinkDir', on_event);
                     watchers.push(watcher);
                 }
                 catch {
@@ -235,10 +897,19 @@ export async function dev_server(options) {
                         continue;
                     known_sites.add(site.dir);
                     sites.push(site);
-                    await normalize_site(site.dir);
-                    await import_site_files(site.dir, api_url, site.config, port);
+                    const use_bootstrap = !await site_exists(api_url, site.config.site_id);
+                    if (sync_policy.mode === 'cms' && !use_bootstrap) {
+                        await sync_from_cms(site.dir, api_url, site.config, server_config, base_dir, sync_policy);
+                    }
+                    else {
+                        await normalize_site(site.dir);
+                        const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, use_bootstrap, base_dir));
+                        if (update_site_sync_state_after_import(site, import_timings, sync_policy)) {
+                            await update_site_sync_baseline(site, api_url, server_config, base_dir);
+                        }
+                    }
                     setup_site_watchers(site);
-                    const host = site.config.host || `${path.basename(site.dir).toLowerCase().replace(/\s+/g, '-')}.localhost:${port}`;
+                    const host = local_dev_host(site.config.name || path.basename(site.dir), port);
                     console.log(chalk.green(`  ✓ New site loaded: ${site.config.name}`));
                     console.log(`    ${chalk.dim('Edit:')}    http://${host}/admin/site`);
                     console.log(`    ${chalk.dim('Preview:')} http://${host}/`);
@@ -246,22 +917,56 @@ export async function dev_server(options) {
                 res.writeHead(200);
                 res.end('ok');
             });
+            reload_server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    console.log(chalk.yellow(`\n  Warning: Reload server port ${port + 1} in use. Hot reload disabled.`));
+                }
+            });
             reload_server.listen(port + 1, '127.0.0.1');
         }
         // Start polling for CMS changes (sync back to local files)
-        sync_interval = setInterval(async () => {
-            if (is_syncing || is_importing)
-                return;
-            for (const site of sites) {
+        // Wait 3 seconds after import to avoid overwriting just-pushed changes
+        const IMPORT_COOLDOWN_MS = 3000;
+        if (is_cms_to_file_active(sync_policy)) {
+            sync_interval = setInterval(async () => {
+                if (is_syncing || is_importing)
+                    return;
+                if (Date.now() - last_import_time < IMPORT_COOLDOWN_MS)
+                    return;
+                // Skip the pull if the user just made a local change — otherwise a
+                // pull that started before the watcher fired could overwrite the
+                // fresh local edit on arrival.
+                if (Date.now() - last_local_change_time < LOCAL_CHANGE_PULL_COOLDOWN_MS)
+                    return;
+                is_syncing = true;
                 try {
-                    await sync_from_cms(site.dir, api_url, site.config);
+                    for (const site of sites) {
+                        try {
+                            const site_key = get_site_sync_key(site.dir, site.config);
+                            if (importing_site_keys.has(site_key) || pending_local_site_keys.has(site_key)) {
+                                continue;
+                            }
+                            await sync_from_cms(site.dir, api_url, site.config, server_config, base_dir, sync_policy);
+                        }
+                        catch {
+                            // Silently ignore sync errors
+                        }
+                    }
+                    if (is_server_mode && !is_importing_library && !has_pending_library_local_changes && await has_library_content(path.join(base_dir, LIBRARY_DIR))) {
+                        try {
+                            await sync_library_from_cms(base_dir, api_url);
+                        }
+                        catch {
+                            // Silently ignore library sync errors
+                        }
+                    }
                 }
-                catch {
-                    // Silently ignore sync errors
+                finally {
+                    is_syncing = false;
                 }
-            }
-        }, 5000);
-        console.log(chalk.dim('  Watching for changes...'));
+            }, 1000);
+        }
+        print_sync_status(sync_policy, sites);
         console.log(chalk.dim('  Press Ctrl+C to stop'));
         // Handle cleanup
         const cleanup = async () => {
@@ -282,6 +987,10 @@ export async function dev_server(options) {
                 clearTimeout(reimport_timeout);
                 reimport_timeout = null;
             }
+            if (library_reimport_timeout) {
+                clearTimeout(library_reimport_timeout);
+                library_reimport_timeout = null;
+            }
             if (sync_interval) {
                 clearInterval(sync_interval);
                 sync_interval = null;
@@ -310,16 +1019,55 @@ export async function dev_server(options) {
         process.exit(1);
     }
 }
+async function register_primo_mcp_server(base_dir) {
+    if (!await path_exists(path.join(base_dir, SERVER_CONFIG_FILE))) {
+        return null;
+    }
+    const mcp_config_path = path.join(base_dir, MCP_CONFIG_FILE);
+    let config = {};
+    try {
+        const raw = await fs.readFile(mcp_config_path, 'utf-8');
+        config = raw.trim() ? JSON.parse(raw) : {};
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            return null;
+        }
+    }
+    if (!is_plain_record(config)) {
+        return null;
+    }
+    if (config.mcpServers !== undefined && !is_plain_record(config.mcpServers)) {
+        return null;
+    }
+    const existing_mcp_servers = config.mcpServers;
+    const mcp_servers = { ...(existing_mcp_servers ?? {}) };
+    if (mcp_servers.primo !== undefined) {
+        return null;
+    }
+    const local_mcp = process.env.PRIMO_MCP_LOCAL
+        ?? '/Users/mateo/Desktop/primo/primo-mcp/dist/index.js';
+    mcp_servers.primo = local_mcp
+        ? { command: 'node', args: [local_mcp] }
+        : { command: 'npx', args: ['-y', '@primo/mcp'] };
+    config.mcpServers = mcp_servers;
+    // Claude Code reads project-root .mcp.json. .primo/ is gitignored local
+    // state, so the discoverable root file is the right registration target.
+    await fs.writeFile(mcp_config_path, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+    return MCP_CONFIG_FILE;
+}
+function is_plain_record(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
 async function discover_sites(base_dir) {
     const sites = [];
-    const entries = await fs.readdir(base_dir, { withFileTypes: true });
+    const sites_root = await get_sites_root(base_dir);
+    const entries = await fs.readdir(sites_root, { withFileTypes: true });
     for (const entry of entries) {
         if (entry.isDirectory() && !entry.name.startsWith('.')) {
-            const site_dir = path.join(base_dir, entry.name);
-            const config_path = path.join(site_dir, 'primo.json');
+            const site_dir = path.join(sites_root, entry.name);
             try {
-                const config_data = await fs.readFile(config_path, 'utf-8');
-                const config = JSON.parse(config_data);
+                const config = await read_site_config(site_dir);
                 sites.push({ dir: site_dir, config });
             }
             catch {
@@ -329,6 +1077,46 @@ async function discover_sites(base_dir) {
     }
     return sites;
 }
+async function get_sites_root(base_dir) {
+    const candidate = path.join(base_dir, SITES_DIR);
+    try {
+        const stat = await fs.stat(candidate);
+        if (stat.isDirectory()) {
+            return candidate;
+        }
+    }
+    catch {
+        // Missing sites/ directory
+    }
+    throw new Error(`Server workspace is missing ${SITES_DIR}/. Run \`primo new\` from the workspace root or create ${SITES_DIR}/ first.`);
+}
+function resolve_site_group(config, server_config) {
+    const configured_groups = server_config.site_groups ?? [];
+    const group_ref = config.group?.trim();
+    const ensure_group_id = (group) => ({
+        ...group,
+        id: typeof group.id === 'string' && group.id.trim().length >= 15 ? group.id.trim() : generate_id()
+    });
+    if (group_ref) {
+        const existing_group = configured_groups.find((group) => group.id === group_ref || group.name === group_ref);
+        if (existing_group) {
+            return ensure_group_id(existing_group);
+        }
+        return ensure_group_id({
+            id: group_ref,
+            name: format_group_name(group_ref),
+            index: configured_groups.length
+        });
+    }
+    if (configured_groups[0]) {
+        return ensure_group_id(configured_groups[0]);
+    }
+    return ensure_group_id({
+        id: '',
+        name: 'Default',
+        index: 0
+    });
+}
 async function wait_for_ready(url, timeout_ms) {
     const start = Date.now();
     const health_url = `${url}/api/health`;
@@ -366,132 +1154,1083 @@ async function verify_site_ready(api_url, site_id) {
     }
     return false;
 }
-async function import_site_files(site_dir, api_url, config, port) {
-    const site_name = config.name || 'My Site';
-    const site_id = config.site_id;
-    // Create ZIP of site files
-    const zip_buffer = await create_site_zip(site_dir);
-    // Use hostname from config, or generate from folder name
-    const folder_name = path.basename(site_dir);
-    const host = config.host || (folder_name.includes('.')
-        ? `${folder_name}:${port}` // Looks like a domain
-        : `${folder_name.toLowerCase().replace(/\s+/g, '-')}.localhost:${port}`);
-    // Retry bootstrap up to 3 times (collections may not be ready immediately)
-    const max_retries = 3;
-    for (let attempt = 1; attempt <= max_retries; attempt++) {
-        const form_data = new FormData();
-        form_data.append('site_id', site_id);
-        form_data.append('name', site_name);
-        form_data.append('host', host);
-        form_data.append('file', new Blob([zip_buffer]), 'site.zip');
-        try {
-            const bootstrap_response = await fetch_with_timeout(`${api_url}/api/palacms/bootstrap`, {
-                method: 'POST',
-                body: form_data
-            }, 30000); // 30s timeout for imports
-            if (bootstrap_response.ok) {
-                return;
-            }
-            const error_text = await bootstrap_response.text();
-            // Check if it's a collection not found error (timing issue)
-            if (error_text.includes('collection') && attempt < max_retries) {
-                await new Promise(resolve => setTimeout(resolve, 500 * attempt));
-                continue;
-            }
-            console.log(chalk.yellow(`  Bootstrap failed (${bootstrap_response.status}): ${error_text}`));
-            // Bootstrap failed, try regular import
-            const import_form = new FormData();
-            import_form.append('file', new Blob([zip_buffer]), 'site.zip');
-            const import_response = await fetch_with_timeout(`${api_url}/api/palacms/import/${site_id}`, {
-                method: 'POST',
-                body: import_form
-            }, 30000); // 30s timeout for imports
+async function site_exists(api_url, site_id) {
+    // Only 404 means the site genuinely doesn't exist. Any other non-ok status
+    // (401/403 from auth, 5xx, rate limits) leaves us uncertain — default to
+    // "exists" so we take the additive `import` path instead of the destructive
+    // `bootstrap` path. Bootstrapping a site that already exists discards
+    // remote state when the request later fails, and the next pull then
+    // stomps in-progress local edits with stale DB content.
+    try {
+        const response = await fetch_with_timeout(`${api_url}/api/collections/sites/records/${site_id}`, {}, 5000);
+        if (response.ok)
+            return true;
+        if (response.status === 404)
+            return false;
+        return true;
+    }
+    catch {
+        return true;
+    }
+}
+function change_requires_reload(_dir, _filename) {
+    return true;
+}
+async function request_browser_reload(api_url) {
+    await fetch_with_timeout(`${api_url}/api/palacms/dev/reload`, {
+        method: 'POST'
+    }, 5000);
+}
+function generate_id(length = 15) {
+    let id = '';
+    for (let i = 0; i < length; i++) {
+        id += ID_ALPHABET[randomInt(ID_ALPHABET.length)];
+    }
+    return id;
+}
+function get_entity_id(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (typeof record._id === 'string' && record._id)
+        return record._id;
+    if (typeof record.id === 'string' && record.id)
+        return record.id;
+    return undefined;
+}
+function get_fields_array(data) {
+    if (Array.isArray(data)) {
+        return data.filter((item) => !!item && typeof item === 'object');
+    }
+    if (data && typeof data === 'object' && Array.isArray(data.fields)) {
+        return data.fields
+            .filter((item) => !!item && typeof item === 'object');
+    }
+    return [];
+}
+function get_sections_array(data) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data.filter((item) => !!item && typeof item === 'object');
+}
+function collect_field_ids(fields, visit) {
+    for (const field of fields) {
+        const field_id = get_entity_id(field);
+        if (field_id) {
+            visit(field_id);
+        }
+        if (Array.isArray(field.subfields)) {
+            const subfields = field.subfields.filter((item) => !!item && typeof item === 'object');
+            collect_field_ids(subfields, visit);
+        }
+    }
+}
+function track_duplicate(duplicates, category, id, occurrence) {
+    let by_id = duplicates.get(category);
+    if (!by_id) {
+        by_id = new Map();
+        duplicates.set(category, by_id);
+    }
+    const existing = by_id.get(id) ?? [];
+    existing.push(occurrence);
+    by_id.set(id, existing);
+}
+async function mark_written_file(file_path) {
+    synced_files.set(file_path, Date.now());
+    try {
+        const stat = await fs.stat(file_path);
+        synced_files.set(file_path, stat.mtimeMs);
+    }
+    catch {
+        // Ignore files that disappeared
+    }
+}
+function mark_deleted_path(file_path) {
+    synced_deleted_paths.set(file_path, Date.now());
+}
+function should_skip_synced_delete(file_path) {
+    const deleted_at = synced_deleted_paths.get(file_path);
+    if (!deleted_at) {
+        return false;
+    }
+    if (Date.now() - deleted_at < 10_000) {
+        synced_deleted_paths.delete(file_path);
+        return true;
+    }
+    synced_deleted_paths.delete(file_path);
+    return false;
+}
+async function mark_deleted_tree(root_path) {
+    mark_deleted_path(root_path);
+    let entries;
+    try {
+        entries = await fs.readdir(root_path, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        await mark_deleted_tree(path.join(root_path, entry.name));
+    }
+}
+async function remove_tracked_path(target_path) {
+    await mark_deleted_tree(target_path);
+    await fs.rm(target_path, { recursive: true, force: true });
+}
+async function path_exists(target_path) {
+    try {
+        await fs.stat(target_path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function find_page_files(dir, relative_dir = 'pages') {
+    const files = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const full_path = path.join(dir, entry.name);
+        const relative_path = `${relative_dir}/${entry.name}`;
+        if (entry.isDirectory()) {
+            files.push(...await find_page_files(full_path, relative_path));
+            continue;
+        }
+        if (entry.name.endsWith('.yaml')) {
+            files.push(relative_path);
+        }
+    }
+    return files;
+}
+function to_posix_path(file_path) {
+    return file_path.split(path.sep).join('/');
+}
+function sanitize_file_name(name) {
+    return name
+        .replaceAll('/', '-')
+        .replaceAll('\\', '-')
+        .replaceAll(':', '-')
+        .replaceAll(' ', '-')
+        .toLowerCase();
+}
+function add_block_alias(aliases, alias, block_name) {
+    const trimmed = alias.trim();
+    if (!trimmed)
+        return;
+    aliases.set(trimmed, block_name);
+    aliases.set(trimmed.toLowerCase(), block_name);
+    aliases.set(sanitize_file_name(trimmed), block_name);
+}
+function content_keys(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return [];
+    }
+    return Object.keys(value);
+}
+function is_empty_fields_yaml(contents) {
+    try {
+        const parsed = load_yaml(contents);
+        if (parsed == null)
+            return true;
+        return Array.isArray(parsed) && parsed.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function is_empty_content_yaml(contents) {
+    try {
+        const parsed = load_yaml(contents);
+        if (parsed == null)
+            return true;
+        if (typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        return Object.keys(parsed).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function has_user_authored_fields(contents) {
+    try {
+        return get_fields_array(load_yaml(contents)).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function has_user_authored_content(contents) {
+    try {
+        const parsed = load_yaml(contents);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        return Object.keys(parsed).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function block_fields_path_block_name(relative_path) {
+    const parts = relative_path.split('/');
+    if (parts.length !== 3 || parts[0] !== 'blocks' || parts[2] !== 'fields.yaml') {
+        return null;
+    }
+    return parts[1] || null;
+}
+function is_site_fields_path(relative_path) {
+    return relative_path === 'site/fields.yaml';
+}
+function is_site_content_path(relative_path) {
+    return relative_path === 'site/content.yaml';
+}
+async function collect_block_aliases(site_dir) {
+    const aliases = new Map();
+    const blocks_dir = path.join(site_dir, 'blocks');
+    let block_names;
+    try {
+        block_names = await fs.readdir(blocks_dir);
+    }
+    catch {
+        return aliases;
+    }
+    for (const block_name of block_names) {
+        if (block_name.startsWith('.'))
+            continue;
+        add_block_alias(aliases, block_name, block_name);
+        try {
+            const raw = await fs.readFile(path.join(blocks_dir, block_name, 'config.yaml'), 'utf-8');
+            const parsed = load_yaml(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const display_name = parsed.name;
+                if (typeof display_name === 'string') {
+                    add_block_alias(aliases, display_name, block_name);
+                }
+            }
+        }
+        catch {
+            // Missing or invalid config.yaml should not make sync destructive.
+        }
+    }
+    return aliases;
+}
+async function collect_block_content_references(site_dir) {
+    const refs = new Map();
+    const aliases = await collect_block_aliases(site_dir);
+    const pages_dir = path.join(site_dir, 'pages');
+    for (const relative_page_path of await find_page_files(pages_dir)) {
+        const page_path = path.join(site_dir, relative_page_path);
+        let page;
+        try {
+            page = load_yaml(await fs.readFile(page_path, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        if (!page || typeof page !== 'object' || Array.isArray(page))
+            continue;
+        const sections = get_sections_array(page.sections);
+        for (const [index, section] of sections.entries()) {
+            const block_ref = section.block;
+            if (typeof block_ref !== 'string' || !block_ref.trim())
+                continue;
+            const keys = content_keys(section.content);
+            if (keys.length === 0)
+                continue;
+            const block_name = aliases.get(block_ref)
+                ?? aliases.get(block_ref.toLowerCase())
+                ?? aliases.get(sanitize_file_name(block_ref))
+                ?? block_ref;
+            const existing = refs.get(block_name) ?? [];
+            existing.push({
+                page: relative_page_path,
+                section_index: index,
+                keys
+            });
+            refs.set(block_name, existing);
+        }
+    }
+    return refs;
+}
+function describe_block_content_refs(refs) {
+    const details = refs.slice(0, 3).map(ref => {
+        const keys = ref.keys.slice(0, 6).join(', ');
+        const suffix = ref.keys.length > 6 ? ', ...' : '';
+        return `${ref.page} sections[${ref.section_index}] content keys: ${keys}${suffix}`;
+    });
+    if (refs.length > 3) {
+        details.push(`${refs.length - 3} more section${refs.length === 4 ? '' : 's'}`);
+    }
+    return details.join('; ');
+}
+function warn_empty_schema_writeback(site_name, relative_path, block_name, refs, preserved) {
+    const key = `${site_name}:${relative_path}:${preserved ? 'preserved' : 'empty'}:${refs.length}`;
+    if (warned_empty_schema_writebacks.has(key))
+        return;
+    warned_empty_schema_writebacks.add(key);
+    if (refs.length > 0) {
+        console.log(chalk.red(`  ✗ ${site_name}: refused CMS-to-file empty schema writeback for ${relative_path}`));
+        console.log(chalk.red(`    Block "${block_name}" has page section content, but the CMS export produced an empty fields.yaml.`));
+        console.log(chalk.red(`    ${describe_block_content_refs(refs)}`));
+        if (preserved) {
+            console.log(chalk.red('    Local fields.yaml was preserved. Re-run the local import or fix the CMS schema before pulling again.'));
+        }
+        return;
+    }
+    if (preserved) {
+        console.log(chalk.yellow(`  ⚠ ${site_name}: skipped empty CMS schema pull for ${relative_path}; local fields.yaml has authored fields.`));
+    }
+}
+function should_skip_empty_block_schema_writeback(relative_path, src_content, dest_content, options) {
+    const block_name = block_fields_path_block_name(relative_path);
+    if (!block_name || !is_empty_fields_yaml(src_content)) {
+        return false;
+    }
+    const refs = options.block_content_refs?.get(block_name) ?? [];
+    const local_has_fields = has_user_authored_fields(dest_content);
+    const should_skip = local_has_fields || refs.length > 0;
+    if (should_skip) {
+        warn_empty_schema_writeback(options.site_name ?? 'site', relative_path, block_name, refs, local_has_fields);
+    }
+    return should_skip;
+}
+// Symmetric guard for site-level files. The CMS export now always emits
+// site/fields.yaml and site/content.yaml (so the on-disk layout documents
+// itself), which means a site with no DB-side fields/values would
+// otherwise wipe local authored content on every pull. Refuse the
+// writeback when the local file has authored content and the incoming
+// CMS export is empty.
+const warned_empty_site_writebacks = new Set();
+function warn_empty_site_writeback(site_name, relative_path) {
+    const key = `${site_name}:${relative_path}`;
+    if (warned_empty_site_writebacks.has(key))
+        return;
+    warned_empty_site_writebacks.add(key);
+    console.log(chalk.yellow(`  ⚠ ${site_name}: skipped empty CMS pull for ${relative_path}; local file has authored content.`));
+}
+function should_skip_empty_site_writeback(relative_path, src_content, dest_content, options) {
+    if (is_site_fields_path(relative_path)) {
+        if (!is_empty_fields_yaml(src_content))
+            return false;
+        if (!has_user_authored_fields(dest_content))
+            return false;
+        warn_empty_site_writeback(options.site_name ?? 'site', relative_path);
+        return true;
+    }
+    if (is_site_content_path(relative_path)) {
+        if (!is_empty_content_yaml(src_content))
+            return false;
+        if (!has_user_authored_content(dest_content))
+            return false;
+        warn_empty_site_writeback(options.site_name ?? 'site', relative_path);
+        return true;
+    }
+    return false;
+}
+async function blocked_empty_schema_writebacks(temp_dir, site_dir, site_name, block_content_refs) {
+    const blocked = new Set();
+    const blocks_dir = path.join(temp_dir, 'blocks');
+    let block_names;
+    try {
+        block_names = await fs.readdir(blocks_dir);
+    }
+    catch {
+        return blocked;
+    }
+    for (const block_name of block_names) {
+        if (block_name.startsWith('.'))
+            continue;
+        const relative_path = `blocks/${block_name}/fields.yaml`;
+        let src_content;
+        try {
+            src_content = await fs.readFile(path.join(blocks_dir, block_name, 'fields.yaml'), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        if (!is_empty_fields_yaml(src_content))
+            continue;
+        let dest_content = '';
+        try {
+            dest_content = await fs.readFile(path.join(site_dir, relative_path), 'utf-8');
+        }
+        catch {
+            // Missing local file: still block if page content references the block.
+        }
+        const refs = block_content_refs.get(block_name) ?? [];
+        const local_has_fields = has_user_authored_fields(dest_content);
+        if (local_has_fields || refs.length > 0) {
+            warn_empty_schema_writeback(site_name, relative_path, block_name, refs, local_has_fields);
+        }
+        if (refs.length > 0) {
+            blocked.add(relative_path);
+        }
+    }
+    return blocked;
+}
+function is_excluded_path(relative_path, excluded_paths) {
+    const normalized = to_posix_path(relative_path);
+    for (const excluded of excluded_paths) {
+        if (normalized === excluded || normalized.startsWith(`${excluded}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function add_directory_to_archive(archive, full_dir, archive_dir, excluded_paths) {
+    let entries;
+    try {
+        entries = await fs.readdir(full_dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full_path = path.join(full_dir, entry.name);
+        const archive_path = archive_dir ? `${archive_dir}/${entry.name}` : entry.name;
+        if (is_excluded_path(archive_path, excluded_paths)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await add_directory_to_archive(archive, full_path, archive_path, excluded_paths);
+        }
+        else if (entry.isFile()) {
+            archive.file(full_path, { name: archive_path });
+        }
+    }
+}
+function describe_duplicate(category, id, occurrences) {
+    const files = [...new Set(occurrences.map((occurrence) => occurrence.file))].sort();
+    switch (category) {
+        case 'pages':
+            return `duplicate page _id "${id}" in ${files.join(' and ')}; skipping those pages`;
+        case 'page_sections':
+            return `duplicate section _id "${id}" in ${files.join(' and ')}; skipping those pages`;
+        case 'blocks':
+            return `duplicate block _id "${id}" in ${files.join(' and ')}; skipping those blocks`;
+        case 'page_types':
+            return `duplicate page type _id "${id}" in ${files.join(' and ')}; skipping those page types`;
+        case 'site_fields':
+            return `duplicate site field _id "${id}" in ${files.join(' and ')}; skipping site/fields.yaml`;
+        case 'block_fields':
+            return `duplicate block field _id "${id}" in ${files.join(' and ')}; skipping those blocks`;
+        case 'page_type_fields':
+            return `duplicate page type field _id "${id}" in ${files.join(' and ')}; skipping those page types`;
+    }
+}
+async function prepare_site_for_local_dev(site_dir) {
+    const excluded_paths = new Set();
+    const warnings = [];
+    const duplicates = new Map();
+    const track_occurrence = (category, id, owner, file) => {
+        track_duplicate(duplicates, category, id, { owner, file });
+    };
+    const pages_dir = path.join(site_dir, 'pages');
+    for (const relative_path of await find_page_files(pages_dir)) {
+        const full_path = path.join(site_dir, relative_path);
+        const raw = await read_file_or_vanish(full_path, relative_path);
+        if (raw === null)
+            continue;
+        const page = load_yaml(raw);
+        if (!page || typeof page !== 'object' || Array.isArray(page))
+            continue;
+        const page_id = get_entity_id(page);
+        const page_sections = get_sections_array(page.sections);
+        if (page_id) {
+            track_occurrence('pages', page_id, relative_path, relative_path);
+        }
+        for (const section of page_sections) {
+            const section_id = get_entity_id(section);
+            if (section_id) {
+                track_occurrence('page_sections', section_id, relative_path, relative_path);
+            }
+        }
+    }
+    const blocks_dir = path.join(site_dir, 'blocks');
+    try {
+        const block_names = await fs.readdir(blocks_dir);
+        for (const block_name of block_names) {
+            if (block_name.startsWith('.'))
+                continue;
+            // Block _id lives in config.yaml; fields (each with their own _id)
+            // live in a sibling fields.yaml as a bare list.
+            const owner = `blocks/${block_name}`;
+            const relative_config_path = `blocks/${block_name}/config.yaml`;
+            const config_path = path.join(site_dir, relative_config_path);
+            try {
+                const raw = await fs.readFile(config_path, 'utf-8');
+                const config = load_yaml(raw);
+                if (config && typeof config === 'object' && !Array.isArray(config)) {
+                    const block_id = get_entity_id(config);
+                    if (block_id) {
+                        track_occurrence('blocks', block_id, owner, relative_config_path);
+                    }
+                }
+            }
+            catch {
+                // No config.yaml — skip
+            }
+            const relative_fields_path = `blocks/${block_name}/fields.yaml`;
+            const fields_path = path.join(site_dir, relative_fields_path);
+            try {
+                const raw = await fs.readFile(fields_path, 'utf-8');
+                const block_fields = get_fields_array(load_yaml(raw));
+                collect_field_ids(block_fields, (field_id) => {
+                    track_occurrence('block_fields', field_id, owner, relative_fields_path);
+                });
+            }
+            catch {
+                // No fields.yaml — skip
+            }
+        }
+    }
+    catch {
+        // No blocks dir
+    }
+    const page_types_dir = path.join(site_dir, 'page-types');
+    try {
+        const page_type_names = await fs.readdir(page_types_dir);
+        for (const page_type_name of page_type_names) {
+            if (page_type_name.startsWith('.'))
+                continue;
+            // Page type _id lives in config.yaml; fields live in sibling
+            // fields.yaml as a bare list.
+            const owner = `page-types/${page_type_name}`;
+            const relative_config_path = `page-types/${page_type_name}/config.yaml`;
+            const config_path = path.join(site_dir, relative_config_path);
+            try {
+                const raw = await fs.readFile(config_path, 'utf-8');
+                const config = load_yaml(raw);
+                if (config && typeof config === 'object' && !Array.isArray(config)) {
+                    const page_type_id = typeof config._id === 'string' && config._id ? config._id : undefined;
+                    if (page_type_id) {
+                        track_occurrence('page_types', page_type_id, owner, relative_config_path);
+                    }
+                }
+            }
+            catch {
+                // No config.yaml — skip
+            }
+            const relative_fields_path = `page-types/${page_type_name}/fields.yaml`;
+            const fields_path = path.join(site_dir, relative_fields_path);
+            try {
+                const raw = await fs.readFile(fields_path, 'utf-8');
+                const page_type_fields = get_fields_array(load_yaml(raw));
+                collect_field_ids(page_type_fields, (field_id) => {
+                    track_occurrence('page_type_fields', field_id, owner, relative_fields_path);
+                });
+            }
+            catch {
+                // No fields.yaml — skip
+            }
+        }
+    }
+    catch {
+        // No page-types dir
+    }
+    const site_fields_path = path.join(site_dir, 'site', 'fields.yaml');
+    try {
+        const raw = await fs.readFile(site_fields_path, 'utf-8');
+        const site_fields_data = load_yaml(raw);
+        const site_fields = get_fields_array(site_fields_data);
+        if (site_fields.length > 0) {
+            collect_field_ids(site_fields, (field_id) => {
+                track_occurrence('site_fields', field_id, 'site/fields.yaml', 'site/fields.yaml');
+            });
+        }
+    }
+    catch {
+        // No site fields file
+    }
+    for (const [category, by_id] of duplicates) {
+        for (const [id, occurrences] of by_id) {
+            if (occurrences.length < 2) {
+                continue;
+            }
+            for (const occurrence of occurrences) {
+                excluded_paths.add(occurrence.owner);
+            }
+            warnings.push(describe_duplicate(category, id, occurrences));
+        }
+    }
+    return {
+        excluded_paths,
+        warnings
+    };
+}
+// Loudly surface non-fatal import problems (e.g. orphaned fields whose
+// content would otherwise be silently dropped). Printed in yellow with the
+// full details so agents and humans both see exactly what was lost and where.
+function print_import_warnings(site_name, warnings) {
+    if (!Array.isArray(warnings) || warnings.length === 0)
+        return 0;
+    const list = warnings;
+    console.log('');
+    console.log(chalk.yellow(`  ⚠ ${site_name}: ${list.length} import warning${list.length === 1 ? '' : 's'}`));
+    for (const w of list) {
+        const msg = w.message || `${w.kind} at ${w.path} in ${w.file}`;
+        console.log(chalk.yellow(`    • ${msg}`));
+    }
+    console.log('');
+    return list.length;
+}
+async function import_site_files(site_dir, api_url, config, port, server_config, use_bootstrap = true, workspace_dir = path.dirname(path.dirname(site_dir))) {
+    const site_name = config.name || 'My Site';
+    const site_id = config.site_id;
+    const site_group = resolve_site_group(config, server_config);
+    const preparation = await prepare_site_for_local_dev(site_dir);
+    for (const warning of preparation.warnings) {
+        console.log(chalk.yellow(`  ⚠ ${config.name}: ${warning}`));
+    }
+    // Create ZIP of site files
+    const zip_started = Date.now();
+    const zip_buffer = await create_site_zip(site_dir, preparation.excluded_paths);
+    const zip_ms = Date.now() - zip_started;
+    // Always use a localhost-style host in dev — the production host stays in
+    // site.yaml for push, but local routing must hit *.localhost
+    const host = local_dev_host(config.name || path.basename(site_dir), port);
+    if (!use_bootstrap) {
+        const import_form = new FormData();
+        import_form.append('file', new Blob([zip_buffer]), 'site.zip');
+        const request_started = Date.now();
+        const import_response = await fetch_with_timeout(`${api_url}/api/palacms/import/${site_id}`, {
+            method: 'POST',
+            body: import_form
+        }, 300000);
+        const request_ms = Date.now() - request_started;
+        if (!import_response.ok) {
+            const import_error = await import_response.text();
+            throw new Error(`Import failed (${import_response.status}): ${import_error}`);
+        }
+        // Write created IDs back to files
+        let warning_count = 0;
+        try {
+            const result = await import_response.json();
+            if (result.created_ids) {
+                await write_created_ids(site_dir, result.created_ids, server_config, workspace_dir);
+            }
+            warning_count = print_import_warnings(config.name, result.warnings);
+        }
+        catch {
+            // ignore JSON parse errors
+        }
+        return {
+            zip_ms,
+            request_ms,
+            mode: 'import',
+            warning_count
+        };
+    }
+    // Retry bootstrap up to 3 times (collections may not be ready immediately)
+    const max_retries = 3;
+    for (let attempt = 1; attempt <= max_retries; attempt++) {
+        const form_data = new FormData();
+        form_data.append('site_id', site_id);
+        form_data.append('name', site_name);
+        form_data.append('host', host);
+        form_data.append('group', site_group.id);
+        form_data.append('group_name', site_group.name);
+        form_data.append('group_index', String(site_group.index ?? 0));
+        form_data.append('server_groups', JSON.stringify(server_config.site_groups ?? [site_group]));
+        form_data.append('file', new Blob([zip_buffer]), 'site.zip');
+        try {
+            const bootstrap_started = Date.now();
+            const bootstrap_response = await fetch_with_timeout(`${api_url}/api/palacms/bootstrap`, {
+                method: 'POST',
+                body: form_data
+            }, 300000); // 300s timeout for imports
+            const bootstrap_ms = Date.now() - bootstrap_started;
+            let warning_count = 0;
+            if (bootstrap_response.ok) {
+                try {
+                    const result = await bootstrap_response.json();
+                    warning_count = print_import_warnings(config.name, result.warnings);
+                }
+                catch {
+                    // ignore JSON parse errors
+                }
+                return {
+                    zip_ms,
+                    request_ms: bootstrap_ms,
+                    mode: 'bootstrap',
+                    warning_count
+                };
+            }
+            const error_text = await bootstrap_response.text();
+            // Check if it's a collection not found error (timing issue)
+            if (error_text.includes('collection') && attempt < max_retries) {
+                await new Promise(resolve => setTimeout(resolve, 500 * attempt));
+                continue;
+            }
+            console.log(chalk.yellow(`  Bootstrap failed (${bootstrap_response.status}): ${error_text}`));
+            // Bootstrap failed, try regular import
+            const import_form = new FormData();
+            import_form.append('file', new Blob([zip_buffer]), 'site.zip');
+            const import_started = Date.now();
+            const import_response = await fetch_with_timeout(`${api_url}/api/palacms/import/${site_id}`, {
+                method: 'POST',
+                body: import_form
+            }, 300000); // 300s timeout for imports
+            const import_ms = Date.now() - import_started;
             if (!import_response.ok) {
                 const import_error = await import_response.text();
                 console.log(chalk.yellow(`  Import failed (${import_response.status}): ${import_error}`));
             }
-            return;
+            else {
+                // Write created IDs back to files
+                try {
+                    const result = await import_response.json();
+                    if (result.created_ids) {
+                        await write_created_ids(site_dir, result.created_ids, server_config, workspace_dir);
+                    }
+                    warning_count = print_import_warnings(config.name, result.warnings);
+                }
+                catch {
+                    // ignore JSON parse errors
+                }
+            }
+            return {
+                zip_ms,
+                request_ms: bootstrap_ms + import_ms,
+                mode: 'bootstrap+import',
+                warning_count
+            };
         }
         catch (err) {
             if (attempt < max_retries) {
                 await new Promise(resolve => setTimeout(resolve, 500 * attempt));
                 continue;
             }
-            console.log(chalk.yellow(`  Import error: ${err}`));
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Timed out importing ${config.name}. If the local .primo data is stale, delete .primo and rerun primo dev.`);
+            }
+            throw err instanceof Error ? err : new Error(String(err));
         }
     }
+    throw new Error(`Import failed for ${config.name}`);
+}
+async function import_library_files(base_dir, api_url, delete_group_ids = [], delete_symbol_ids = []) {
+    const library_dir = path.join(base_dir, LIBRARY_DIR);
+    try {
+        const stat = await fs.stat(library_dir);
+        if (!stat.isDirectory())
+            return { zip_ms: 0, request_ms: 0 };
+    }
+    catch {
+        return { zip_ms: 0, request_ms: 0 };
+    }
+    const has_deletes = delete_group_ids.length > 0 || delete_symbol_ids.length > 0;
+    // If the library is empty AND there are no explicit deletes, skip the
+    // push entirely. This preserves the old behavior of not wiping the CMS
+    // on accidental-empty-dir. Deletes are allowed through even on an empty
+    // tree so a user can intentionally clear the library.
+    if (!await has_library_content(library_dir) && !has_deletes) {
+        return { zip_ms: 0, request_ms: 0 };
+    }
+    const zip_started = Date.now();
+    const zip_buffer = await create_library_zip(base_dir);
+    const zip_ms = Date.now() - zip_started;
+    const form_data = new FormData();
+    form_data.append('file', new Blob([zip_buffer]), 'library.zip');
+    if (has_deletes) {
+        form_data.append('deletes', JSON.stringify({
+            group_ids: delete_group_ids,
+            symbol_ids: delete_symbol_ids
+        }));
+    }
+    const request_started = Date.now();
+    const response = await fetch_with_timeout(`${api_url}/api/palacms/import-library`, {
+        method: 'POST',
+        body: form_data
+    }, 120000);
+    const request_ms = Date.now() - request_started;
+    if (response.status === 404) {
+        throw new Error('Shared library sync is not supported by the current palacms binary/server. Rebuild or update palacms to use library sync.');
+    }
+    if (!response.ok) {
+        const error_text = await response.text();
+        throw new Error(error_text);
+    }
+    return { zip_ms, request_ms };
 }
-async function create_site_zip(dir) {
+// Returns a map of posix-style relative paths (under library_path) to the
+// underlying record ID for every group folder and block folder currently on
+// disk. Group IDs come from library/groups.yaml, block IDs from the block's
+// config.yaml. Missing IDs are null (new blocks that have never been pushed).
+async function scan_library_folders(library_path) {
+    const result = new Map();
+    // Load group ID mapping from groups.yaml
+    const group_ids = {};
+    try {
+        const raw = await fs.readFile(path.join(library_path, 'groups.yaml'), 'utf-8');
+        const parsed = load_yaml(raw);
+        if (Array.isArray(parsed)) {
+            for (const entry of parsed) {
+                if (entry && typeof entry === 'object' && entry.folder && entry.id) {
+                    group_ids[String(entry.folder)] = String(entry.id);
+                }
+            }
+        }
+    }
+    catch {
+        // no groups.yaml, leave group_ids empty
+    }
+    let groups;
+    try {
+        groups = await fs.readdir(library_path, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const group of groups) {
+        if (!group.isDirectory() || group.name.startsWith('.'))
+            continue;
+        const group_rel = group.name;
+        result.set(group_rel, { kind: 'group', id: group_ids[group_rel] ?? null });
+        const group_dir = path.join(library_path, group.name);
+        let blocks;
+        try {
+            blocks = await fs.readdir(group_dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const block of blocks) {
+            if (!block.isDirectory() || block.name.startsWith('.'))
+                continue;
+            const block_dir = path.join(group_dir, block.name);
+            let has_block_file = false;
+            let block_id = null;
+            try {
+                const files = await fs.readdir(block_dir);
+                has_block_file = files.some(f => f === 'component.svelte' || f === 'config.yaml' || f === 'fields.yaml' || f === 'content.yaml');
+                if (files.includes('config.yaml')) {
+                    try {
+                        const raw = await fs.readFile(path.join(block_dir, 'config.yaml'), 'utf-8');
+                        const parsed = load_yaml(raw);
+                        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                            const rec = parsed;
+                            if (typeof rec._id === 'string' && rec._id)
+                                block_id = rec._id;
+                            else if (typeof rec.id === 'string' && rec.id)
+                                block_id = rec.id;
+                        }
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+            catch {
+                // ignore
+            }
+            if (has_block_file) {
+                result.set(`${group_rel}/${block.name}`, { kind: 'block', id: block_id });
+            }
+        }
+    }
+    return result;
+}
+async function create_library_zip(base_dir) {
     return new Promise((resolve, reject) => {
-        const archive = archiver('zip', { zlib: { level: 9 } });
+        const archive = archiver('zip', { zlib: { level: LOCAL_ZIP_COMPRESSION_LEVEL } });
         const chunks = [];
         archive.on('data', chunk => chunks.push(chunk));
         archive.on('end', () => resolve(Buffer.concat(chunks)));
         archive.on('error', reject);
-        const dirs_to_include = ['blocks', 'page-types', 'pages', 'site', 'uploads'];
-        for (const subdir of dirs_to_include) {
-            const full_path = path.join(dir, subdir);
-            archive.directory(full_path, subdir);
-        }
-        const primo_json = path.join(dir, 'primo.json');
-        archive.file(primo_json, { name: 'primo.json' });
+        archive.directory(path.join(base_dir, LIBRARY_DIR), LIBRARY_DIR);
         archive.finalize();
     });
 }
-async function sync_from_cms(site_dir, api_url, config) {
-    is_syncing = true;
-    try {
-        const response = await fetch_with_timeout(`${api_url}/api/palacms/export/${config.site_id}`, {}, 15000);
-        if (!response.ok)
-            return;
-        const zip_data = await response.arrayBuffer();
-        // Extract to temp directory
-        const temp_dir = path.join(site_dir, '.primo', 'sync-temp');
-        const temp_zip = path.join(temp_dir, 'export.zip');
-        await fs.mkdir(temp_dir, { recursive: true });
-        await fs.writeFile(temp_zip, Buffer.from(zip_data));
-        await extract(temp_zip, { dir: temp_dir });
-        await fs.unlink(temp_zip);
-        // Compare and sync files
-        const dirs_to_sync = ['blocks', 'page-types', 'pages', 'site'];
-        const changed_files = [];
-        for (const dir of dirs_to_sync) {
-            const temp_path = path.join(temp_dir, dir);
-            const local_path = path.join(site_dir, dir);
+async function create_site_zip(dir, excluded_paths = new Set()) {
+    return new Promise((resolve, reject) => {
+        const archive = archiver('zip', { zlib: { level: LOCAL_ZIP_COMPRESSION_LEVEL } });
+        const chunks = [];
+        archive.on('data', chunk => chunks.push(chunk));
+        archive.on('end', () => resolve(Buffer.concat(chunks)));
+        archive.on('error', reject);
+        void (async () => {
             try {
-                const files = await sync_directory(temp_path, local_path, dir);
-                changed_files.push(...files);
+                const dirs_to_include = ['blocks', 'page-types', 'pages', 'site', 'uploads'];
+                for (const subdir of dirs_to_include) {
+                    const full_path = path.join(dir, subdir);
+                    await add_directory_to_archive(archive, full_path, subdir, excluded_paths);
+                }
+                const site_json = path.join(dir, SITE_CONFIG_FILE);
+                if (!is_excluded_path(SITE_CONFIG_FILE, excluded_paths)) {
+                    archive.file(site_json, { name: SITE_CONFIG_FILE });
+                }
+                await archive.finalize();
             }
-            catch {
-                // Directory might not exist in export
+            catch (error) {
+                reject(error);
             }
-        }
-        // Clean up temp directory
+        })();
+    });
+}
+async function sync_from_cms(site_dir, api_url, config, server_config, workspace_dir, sync_policy = { mode: 'both' }) {
+    const response = await fetch_with_timeout(`${api_url}/api/palacms/export/${config.site_id}`, {}, 15000);
+    if (!response.ok)
+        return;
+    const zip_data = await response.arrayBuffer();
+    // Extract to temp directory
+    const temp_dir = path.join(site_dir, '.primo', 'sync-temp');
+    const temp_zip = path.join(temp_dir, 'export.zip');
+    await fs.rm(temp_dir, { recursive: true, force: true });
+    await fs.mkdir(temp_dir, { recursive: true });
+    await fs.writeFile(temp_zip, Buffer.from(zip_data));
+    await extract(temp_zip, { dir: temp_dir });
+    await fs.unlink(temp_zip);
+    const format_options = resolve_format_options(server_config);
+    const block_content_refs = await collect_block_content_references(site_dir);
+    const blocked_writebacks = await blocked_empty_schema_writebacks(temp_dir, site_dir, config.name, block_content_refs);
+    if (blocked_writebacks.size > 0) {
         await fs.rm(temp_dir, { recursive: true, force: true });
-        if (changed_files.length > 0) {
-            for (const file of changed_files) {
-                console.log(chalk.blue(`  ↓ ${config.name}: ${file}`));
+        return;
+    }
+    const remote_snapshot = await collect_site_snapshot(temp_dir, {
+        workspace_dir,
+        format_options,
+        dest_root: site_dir
+    });
+    const local_snapshot = await collect_site_snapshot(site_dir);
+    const conflict_paths = sync_policy.mode === 'both'
+        ? find_conflict_paths(get_site_sync_baseline({ dir: site_dir, config }), local_snapshot, remote_snapshot)
+        : [];
+    // Default conflict policy: files win. The caller can override by
+    // running with --author cms, in which case the policy flips and the
+    // CMS export is allowed to overwrite the conflicted local files.
+    const skip_paths = sync_policy.mode === 'cms' ? new Set() : new Set(conflict_paths);
+    const sync_options = {
+        workspace_dir,
+        format_options,
+        block_content_refs,
+        site_name: config.name,
+        skip_paths
+    };
+    // Compare and sync files
+    const changed_files = [];
+    for (const dir of SITE_SYNC_DIRS) {
+        const temp_path = path.join(temp_dir, dir);
+        const local_path = path.join(site_dir, dir);
+        if (await path_exists(temp_path)) {
+            const files = await sync_directory(temp_path, local_path, dir, sync_options);
+            changed_files.push(...files);
+        }
+        else if (await path_exists(local_path)) {
+            await remove_tracked_path(local_path);
+            changed_files.push(dir);
+        }
+    }
+    // Clean up temp directory
+    await fs.rm(temp_dir, { recursive: true, force: true });
+    // Baseline reflects the on-disk state we just produced. For paths we
+    // skipped (files-win conflict resolution), the local snapshot's value
+    // is correct — using remote_snapshot would re-trigger the conflict on
+    // the next cycle since the file still differs from the CMS state.
+    const post_baseline = new Map(remote_snapshot);
+    for (const skipped of skip_paths) {
+        const local_value = local_snapshot.get(skipped);
+        if (local_value === undefined) {
+            post_baseline.delete(skipped);
+        }
+        else {
+            post_baseline.set(skipped, local_value);
+        }
+    }
+    site_sync_baselines.set(get_site_sync_key(site_dir, config), post_baseline);
+    if (conflict_paths.length > 0) {
+        const site_key = get_site_sync_key(site_dir, config);
+        const conflict_signature = conflict_paths.join('|');
+        if (last_logged_conflicts.get(site_key) !== conflict_signature) {
+            last_logged_conflicts.set(site_key, conflict_signature);
+            if (sync_policy.mode === 'cms') {
+                log_sync_conflict(config.name, 'CMS', 'local and CMS contents differ; CMS values were applied (--author cms; local edits saved to .primo/trash/)', conflict_paths);
+            }
+            else {
+                log_sync_conflict(config.name, 'files', 'local and CMS contents differ; local files were preserved (default policy: files win on conflict; pass --author cms to flip)', conflict_paths);
             }
         }
     }
-    finally {
-        is_syncing = false;
+    else {
+        // Cleared up — clear the dedupe key so a fresh conflict re-prints.
+        last_logged_conflicts.delete(get_site_sync_key(site_dir, config));
+    }
+    if (changed_files.length > 0) {
+        for (const file of changed_files) {
+            console.log(chalk.blue(`  ↓ ${config.name}: ${file}`));
+        }
+    }
+}
+async function sync_library_from_cms(base_dir, api_url) {
+    const response = await fetch_with_timeout(`${api_url}/api/palacms/export-library`, {}, 15000);
+    if (response.status === 404) {
+        throw new Error('Shared library sync is not supported by the current palacms binary/server. Rebuild or update palacms to use library sync.');
+    }
+    if (!response.ok)
+        return;
+    const zip_data = await response.arrayBuffer();
+    const temp_dir = path.join(base_dir, '.primo', 'library-sync-temp');
+    const temp_zip = path.join(temp_dir, 'library.zip');
+    await fs.rm(temp_dir, { recursive: true, force: true });
+    await fs.mkdir(temp_dir, { recursive: true });
+    await fs.writeFile(temp_zip, Buffer.from(zip_data));
+    await extract(temp_zip, { dir: temp_dir });
+    await fs.unlink(temp_zip);
+    const temp_library_path = path.join(temp_dir, LIBRARY_DIR);
+    const local_library_path = path.join(base_dir, LIBRARY_DIR);
+    let changed_files = [];
+    if (await path_exists(temp_library_path)) {
+        changed_files = await sync_directory(temp_library_path, local_library_path, LIBRARY_DIR);
+    }
+    else if (await path_exists(local_library_path)) {
+        await remove_tracked_path(local_library_path);
+        changed_files = [LIBRARY_DIR];
+    }
+    await fs.rm(temp_dir, { recursive: true, force: true });
+    library_snapshot = await scan_library_folders(local_library_path);
+    if (changed_files.length > 0) {
+        for (const file of changed_files) {
+            console.log(chalk.blue(`  ↓ library: ${file}`));
+        }
     }
 }
-async function sync_directory(src, dest, relative_path = '') {
+async function sync_directory(src, dest, relative_path = '', options = {}) {
     const changed_files = [];
     const entries = await fs.readdir(src, { withFileTypes: true });
+    const source_names = new Set(entries.map(entry => entry.name));
     await fs.mkdir(dest, { recursive: true });
     for (const entry of entries) {
         const src_path = path.join(src, entry.name);
         const dest_path = path.join(dest, entry.name);
         const file_relative = relative_path ? `${relative_path}/${entry.name}` : entry.name;
         if (entry.isDirectory()) {
-            const nested = await sync_directory(src_path, dest_path, file_relative);
+            const nested = await sync_directory(src_path, dest_path, file_relative, options);
             changed_files.push(...nested);
         }
         else {
-            const src_content = await fs.readFile(src_path, 'utf-8');
+            // "Files win on conflict" default: caller marked this path as
+            // conflicted, so leave the local file alone and discard the CMS
+            // value silently. Logging happens once at the call site.
+            if (options.skip_paths?.has(file_relative)) {
+                continue;
+            }
+            let src_content = await fs.readFile(src_path, 'utf-8');
+            // Run server-emitted file through the workspace's formatter so
+            // per-user style (tabs, line width, single quotes, etc.) survives
+            // the round-trip. Without this, every CMS export wipes out the
+            // user's formatting and the file watcher fires another reimport.
+            if (options.format_options && options.workspace_dir && should_format(dest_path)) {
+                src_content = await format_file_contents(dest_path, src_content, options.workspace_dir, options.format_options);
+            }
             let dest_content = '';
             try {
                 dest_content = await fs.readFile(dest_path, 'utf-8');
@@ -499,8 +2238,25 @@ async function sync_directory(src, dest, relative_path = '') {
             catch {
                 // File doesn't exist locally
             }
+            if (should_skip_empty_block_schema_writeback(file_relative, src_content, dest_content, options)) {
+                continue;
+            }
+            if (should_skip_empty_site_writeback(file_relative, src_content, dest_content, options)) {
+                continue;
+            }
             // Normalize to handle trailing newline/whitespace differences
             if (src_content.trim() !== dest_content.trim()) {
+                // Trash the prior content so the user can recover if this
+                // overwrite was unwanted. Skipped when there was no prior file.
+                // Trashing must never block the sync — failures are logged and ignored.
+                if (dest_content && options.workspace_dir && options.site_name) {
+                    try {
+                        await trash_existing_file(dest_content, options.workspace_dir, options.site_name, file_relative);
+                    }
+                    catch {
+                        console.log(chalk.dim(`  trash failed for ${file_relative}`));
+                    }
+                }
                 // Track this file BEFORE writing to avoid race with watcher
                 // Use current time as estimate, watcher allows 1 second tolerance
                 synced_files.set(dest_path, Date.now());
@@ -508,9 +2264,110 @@ async function sync_directory(src, dest, relative_path = '') {
                 // Update with actual mtime after write
                 const stat = await fs.stat(dest_path);
                 synced_files.set(dest_path, stat.mtimeMs);
-                changed_files.push(file_relative);
+                // Surface shrinkage on the change line itself so a user
+                // scanning the dev log notices when a YAML list silently
+                // loses entries (the failure mode reported during the
+                // column-accounting beta).
+                const shrink_delta = compute_shrink_delta(dest_content, src_content);
+                const annotated = shrink_delta !== null
+                    ? `${file_relative} (${shrink_delta} lines, prior in .primo/trash/)`
+                    : file_relative;
+                changed_files.push(annotated);
+            }
+        }
+    }
+    const dest_entries = await fs.readdir(dest, { withFileTypes: true });
+    for (const entry of dest_entries) {
+        if (source_names.has(entry.name)) {
+            continue;
+        }
+        const dest_path = path.join(dest, entry.name);
+        const file_relative = relative_path ? `${relative_path}/${entry.name}` : entry.name;
+        // "Files win on conflict": caller marked this path as conflicted,
+        // so leave the local file in place even though the CMS export
+        // dropped it.
+        if (options.skip_paths?.has(file_relative)) {
+            continue;
+        }
+        // Trash the file/tree before removing so a CMS-side delete
+        // (often triggered by an upstream parse error dropping references)
+        // is recoverable from .primo/trash/.
+        if (options.workspace_dir && options.site_name) {
+            try {
+                await trash_path_recursive(dest_path, options.workspace_dir, options.site_name, file_relative);
+            }
+            catch {
+                console.log(chalk.dim(`  trash failed for ${file_relative}`));
             }
         }
+        await remove_tracked_path(dest_path);
+        changed_files.push(`${file_relative} (deleted, prior in .primo/trash/)`);
     }
     return changed_files;
 }
+async function has_library_content(library_dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(library_dir, { withFileTypes: true });
+    }
+    catch (err) {
+        // Missing library/ is normal in workspaces that haven't been
+        // initialized for library sync — treat as empty rather than crashing
+        // the sync loop.
+        if (err?.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+async function write_created_ids(site_dir, created_ids, server_config, workspace_dir) {
+    const format_options = resolve_format_options(server_config);
+    for (const [relative_path, id_data] of Object.entries(created_ids)) {
+        if (!id_data._id && !Array.isArray(id_data.sections))
+            continue;
+        const file_path = path.join(site_dir, relative_path);
+        try {
+            const content = await fs.readFile(file_path, 'utf-8');
+            const parsed = load_yaml(content);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                continue;
+            let data = parsed;
+            let changed = false;
+            if (id_data._id && !data._id && !data.id) {
+                data = { _id: id_data._id, ...data };
+                changed = true;
+            }
+            if (Array.isArray(id_data.sections) && Array.isArray(data.sections)) {
+                const section_ids = id_data.sections;
+                const sections = data.sections.map((section, index) => {
+                    if (!section || typeof section !== 'object' || Array.isArray(section))
+                        return section;
+                    const section_record = section;
+                    const section_id = section_ids[index];
+                    if (!section_id || section_record._id || section_record.id)
+                        return section;
+                    changed = true;
+                    return { _id: section_id, ...section_record };
+                });
+                if (changed) {
+                    data = { ...data, sections };
+                }
+            }
+            if (changed) {
+                const raw = dump_yaml(data, { lineWidth: -1 });
+                const formatted = await format_file_contents(file_path, raw, workspace_dir, format_options);
+                await fs.writeFile(file_path, formatted, 'utf-8');
+                await mark_written_file(file_path);
+            }
+        }
+        catch {
+            // skip if file doesn't exist or can't be read
+        }
+    }
+}