gazetta 0.7.0 → 0.8.0

package/dist/cli/index.js

@@ -5,14 +5,16 @@ import { serve } from '@hono/node-server';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
-import yaml from 'js-yaml';
 import { loadSite } from '../site-loader.js';
 import { resolvePage } from '../resolver.js';
 import { renderPage } from '../renderer.js';
 import { createFilesystemProvider } from '../providers/filesystem.js';
 import { invalidateTemplate, invalidateAllTemplates } from '../template-loader.js';
+import { REQUIRED_NODE_FLOOR } from '../node-floor.js';
+import { isTemplateEventRecent, TEMPLATE_RECENT_CHANGE_WINDOW_MS } from './dev-template-watcher.js';
 import { getEnvironment, getType, isEditable } from '../types.js';
-import { createAdminApp } from '../admin-api/index.js';
+import { buildHooksRegistry, createAdminApp } from '../admin-api/index.js';
+import { parseValidateFlags } from './validate-flags.js';
 // ANSI color helpers — no dependency, suppressed when NO_COLOR or CI
 const noColor = !!process.env.NO_COLOR || !process.stdout.isTTY;
 const c = {
@@ -27,6 +29,39 @@ const c = {
 };
 const args = process.argv.slice(2);
 const command = args[0];
+/**
+ * Load a site manifest from `siteDir` via the TS config loader. Recognizes
+ * `site.config.ts`, `site.config.js`, and `site.config.mjs`.
+ *
+ * Returns null when no config file is found.
+ */
+async function loadSiteManifestForCli(siteDir) {
+    const tsConfigCandidates = ['site.config.ts', 'site.config.js', 'site.config.mjs'];
+    if (!tsConfigCandidates.some(f => existsSync(join(siteDir, f))))
+        return null;
+    const { loadSiteConfig, siteConfigToManifest } = await import('../config/loader.js');
+    const loaded = await loadSiteConfig(siteDir);
+    if (!loaded)
+        return null;
+    return siteConfigToManifest(loaded.config);
+}
+/**
+ * Read `admin.hooks` factory contributions from a site manifest.
+ *
+ * The manifest types `admin?` as a loose record (`Record<string, unknown>`)
+ * to keep `SiteManifest` stable across foundation additions; each foundation
+ * narrow-types its own block at the consumption site. For hooks the runtime
+ * shape is `ReadonlyArray<HookContribution>` (per design-hooks.md
+ * "Registration"); we accept it as `unknown` here and cast at the boundary.
+ *
+ * Returns undefined when the field is absent or empty.
+ */
+function readHookContributions(manifest) {
+    const hooks = manifest?.admin?.hooks;
+    if (!Array.isArray(hooks) || hooks.length === 0)
+        return undefined;
+    return hooks;
+}
 // Served to /admin/* requests during dev-server startup before Vite middleware
 // is attached. Polls /admin/ping every 500ms and reloads when the admin becomes
 // reachable. See #132 and cli/index.ts for why this is needed.
@@ -122,6 +157,84 @@ function detectProjectRoot(siteDir) {
     // Fallback — use siteDir (templates/ may not exist yet)
     return siteDir;
 }
+/**
+ * Resolve the siteDir for any CLI command by extracting the site
+ * positional from the parsed args per the command's documented
+ * positional layout. Pure fs walk; no config eval — safe to call
+ * before env-load.
+ *
+ * Single dispatch table so env-load happens exactly once at the top
+ * of `main()`, before any config-eval can read process.env.
+ */
+async function resolveSiteDirForCommand(cmd, parsed) {
+    // Commands whose site positional sits at a fixed index.
+    if (cmd === 'build')
+        return resolveSiteDir(parsed.positional[0]);
+    if (cmd === 'dev' || cmd === 'validate' || cmd === 'admin')
+        return resolveSiteDir(parsed.positional[0]);
+    // `rollback <rev> [target|site] [site]`: site is positional[1] when
+    // site-shaped, else positional[2].
+    if (cmd === 'rollback') {
+        const second = parsed.positional[1];
+        const third = parsed.positional[2];
+        const secondIsSite = second && (second.includes('/') || hasSiteConfig(resolve(second)));
+        return resolveSiteDir(secondIsSite ? second : third);
+    }
+    // `publish|serve|deploy|history|undo [target|site] [site]`: site is
+    // positional[0] when site-shaped, else positional[1].
+    if (cmd === 'publish' || cmd === 'serve' || cmd === 'deploy' || cmd === 'history' || cmd === 'undo') {
+        const first = parsed.positional[0];
+        const firstIsSite = first && (first.includes('/') || hasSiteConfig(resolve(first)));
+        return resolveSiteDir(firstIsSite ? first : parsed.positional[1]);
+    }
+    // `translate <item> --to <locale> [target]` — no explicit site arg.
+    if (cmd === 'translate')
+        return resolveSiteDir(undefined);
+    // `assets <subcmd> [args...] [target] [site]`: layout differs by subcmd.
+    if (cmd === 'assets') {
+        const subcmd = parsed.positional[0];
+        const sitePositional = subcmd === 'info' ? parsed.positional[3] : parsed.positional[2];
+        return resolveSiteDir(sitePositional);
+    }
+    // `archive <subcmd> [args...] [target] [site]`: site at trailingStart+1.
+    if (cmd === 'archive') {
+        const subcmd = parsed.positional[0];
+        const requiredArgs = subcmd === 'rename' ? 2 : subcmd === 'purge' || subcmd === 'restore' ? 1 : 0;
+        return resolveSiteDir(parsed.positional[1 + requiredArgs + 1]);
+    }
+    // Unknown command → auto-detect (main's switch will reject with a
+    // clear "Unknown command" error after env-load runs).
+    return resolveSiteDir(undefined);
+}
+/**
+ * Load `.env` + `.env.local` from project root and site dir, in that
+ * order, so per-site secrets override project-wide defaults. Must run
+ * BEFORE the first config-eval (the site's storage / deploy / etc.
+ * factories read `process.env` synchronously at construction). Skipped
+ * in CI — CI runners inject env directly.
+ *
+ * Per Q1 of CLI env-loading discipline: site-local `.env` is honored
+ * (gazetta.studio has its own `.env` with R2/Cloudflare creds; this
+ * function ensures factories see them at config-eval time).
+ */
+function loadEnvFiles(siteDir) {
+    if (process.env.CI)
+        return;
+    const projectRoot = detectProjectRoot(siteDir);
+    const envDirs = projectRoot !== siteDir ? [projectRoot, siteDir] : [siteDir];
+    for (const dir of envDirs) {
+        for (const name of ['.env', '.env.local']) {
+            const envPath = join(dir, name);
+            if (!existsSync(envPath))
+                continue;
+            for (const line of readFileSync(envPath, 'utf-8').split('\n')) {
+                const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/);
+                if (m && !(m[1] in process.env))
+                    process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+            }
+        }
+    }
+}
 function printHelp() {
     console.log(`
   gazetta - Stateless CMS for composable websites
@@ -147,6 +260,14 @@ function printHelp() {
                                     Show full detail (variants, overrides, refs) for one asset
     gazetta assets reindex [target] [site]
                                     Rebuild the asset-refs sidecar index from manifests
+    gazetta archive list [--kind=page|fragment] [target] [site]
+                                    List archived items
+    gazetta archive purge <name> [--kind=...] [--force] [target] [site]
+                                    Permanently delete an archive
+    gazetta archive restore <name> [--kind=...] [target] [site]
+                                    Unarchive an item (back to live)
+    gazetta archive rename <oldname> <newname> [--kind=...] [--no-keep-alias] [target] [site]
+                                    Rename a live item; keeps the redirect by default
     gazetta help                    Show this help message
 
   Options:
@@ -160,7 +281,7 @@ function printHelp() {
     Site is auto-detected from sites/ directory. If multiple sites exist,
     you'll be prompted to choose (or pass it as an argument).
 
-    Target is auto-detected as the first target in site.yaml. If multiple
+    Target is auto-detected as the first target in site.config.ts. If multiple
     targets exist, you'll be prompted to choose (or pass it as an argument).
 
   Examples:
@@ -213,24 +334,30 @@ function parseArgs(input) {
  * For commands like `publish` and `serve`, the first positional is the target
  * and the second is the site.
  */
+/** Returns true if the directory contains a Gazetta site config (`site.config.ts`/.js/.mjs). */
+function hasSiteConfig(dir) {
+    return (existsSync(join(dir, 'site.config.ts')) ||
+        existsSync(join(dir, 'site.config.js')) ||
+        existsSync(join(dir, 'site.config.mjs')));
+}
 async function resolveSiteDir(positionalSite) {
     // Explicit site dir provided
     if (positionalSite) {
         const dir = resolve(positionalSite);
-        if (existsSync(join(dir, 'site.yaml')))
+        if (hasSiteConfig(dir))
             return dir;
         // Maybe it's a site name under sites/
         const sitesSubdir = resolve('sites', positionalSite);
-        if (existsSync(join(sitesSubdir, 'site.yaml')))
+        if (hasSiteConfig(sitesSubdir))
             return sitesSubdir;
         // Maybe it's a project root with sites/
         const mainSite = resolve(dir, 'sites/main');
-        if (existsSync(join(mainSite, 'site.yaml')))
+        if (hasSiteConfig(mainSite))
             return mainSite;
         return dir; // let loadSite produce a clear error
     }
     // Auto-detect: check current dir first
-    if (existsSync(join(resolve('.'), 'site.yaml')))
+    if (hasSiteConfig(resolve('.')))
         return resolve('.');
     // Check sites/ directory
     const sitesDir = resolve('sites');
@@ -238,7 +365,7 @@ async function resolveSiteDir(positionalSite) {
         const { readdirSync, statSync } = await import('node:fs');
         const sites = readdirSync(sitesDir).filter(name => {
             const dir = join(sitesDir, name);
-            return statSync(dir).isDirectory() && existsSync(join(dir, 'site.yaml'));
+            return statSync(dir).isDirectory() && hasSiteConfig(dir);
         });
         if (sites.length === 1)
             return join(sitesDir, sites[0]);
@@ -270,11 +397,10 @@ async function resolveSiteDir(positionalSite) {
 async function resolveTarget(positionalTarget, siteDir) {
     if (positionalTarget)
         return positionalTarget;
-    const siteYamlPath = join(siteDir, 'site.yaml');
-    if (!existsSync(siteYamlPath))
+    const manifest = await loadSiteManifestForCli(siteDir);
+    if (!manifest)
         return undefined;
-    const siteYaml = yaml.load(readFileSync(siteYamlPath, 'utf-8'));
-    const targets = Object.keys(siteYaml.targets ?? {});
+    const targets = Object.keys(manifest.targets ?? {});
     if (targets.length <= 1)
         return targets[0]; // auto-select if 0 or 1
     if (process.env.CI) {
@@ -293,13 +419,27 @@ async function resolveTarget(positionalTarget, siteDir) {
 async function runInit(dir) {
     const { writeFile, mkdir } = await import('node:fs/promises');
     const target = resolve(dir);
-    if (existsSync(join(target, 'sites')) || existsSync(join(target, 'site.yaml'))) {
+    if (existsSync(join(target, 'sites')) || existsSync(join(target, 'site.config.ts'))) {
         console.error(`\n  Error: project already exists in ${target}\n`);
         process.exit(1);
     }
     const name = target.split('/').pop() ?? 'my-site';
     const files = {
-        'sites/main/site.yaml': `name: ${name}\nversion: 1.0.0\nsystemPages:\n  - "404"\ntargets:\n  local:\n    storage:\n      type: filesystem\n    # environment=local, editable=true (defaults); path=./targets/local (default)\n`,
+        'sites/main/site.config.ts': `import { defineSite, filesystemStorage } from 'gazetta'
+
+export default defineSite({
+  name: '${name}',
+  version: '1.0.0',
+  systemPages: ['404'],
+  targets: {
+    local: {
+      storage: filesystemStorage(),
+      // environment: 'local' (default); editable: true (default for local);
+      // filesystemStorage() defaults path to ./targets/local
+    },
+  },
+})
+`,
         'templates/page-layout/index.ts': `import { z } from 'zod'
 import type { TemplateFunction } from 'gazetta'
 
@@ -419,7 +559,7 @@ export default template
             name,
             private: true,
             type: 'module',
-            engines: { node: '>=22' },
+            engines: { node: REQUIRED_NODE_FLOOR },
             scripts: { dev: 'gazetta dev' },
             dependencies: { gazetta: '*', react: '^19.0.0', 'react-dom': '^19.0.0', zod: '^4.0.0' },
         }, null, 2) + '\n',
@@ -437,7 +577,7 @@ export default template
         `  ${c.dim('pages/home/')}       ${c.dim('home page with hero + intro')}\n` +
         `  ${c.dim('pages/404/')}        ${c.dim('error page')}\n` +
         `  ${c.dim('fragments/header/')} ${c.dim('shared header nav')}\n` +
-        `  ${c.dim('site.yaml')}         ${c.dim('site config + local target')}\n` +
+        `  ${c.dim('site.config.ts')}    ${c.dim('site config + local target')}\n` +
         `${c.bold('package.json')}`, `Created ${c.green(name)}/`);
     // Run npm install
     const s = spinner();
@@ -456,7 +596,7 @@ export default template
 async function runPublish(siteDir, targetName, opts = {}) {
     const projectRoot = detectProjectRoot(siteDir);
     const templatesDir = join(projectRoot, 'templates');
-    // Source comes from the default editable target in site.yaml.
+    // Source comes from the default editable target in site.config.ts.
     const { buildSourceContext } = await import('./bootstrap.js');
     let source, manifest, targetConfigs;
     try {
@@ -471,7 +611,7 @@ async function runPublish(siteDir, targetName, opts = {}) {
     const site = await loadSite({ contentRoot: source.contentRoot, templatesDir, manifest });
     const siteYaml = manifest;
     if (!siteYaml.targets || Object.keys(siteYaml.targets).length === 0) {
-        console.error(`\n  Error: no targets configured in site.yaml`);
+        console.error(`\n  Error: no targets configured in site.config.ts`);
         process.exit(1);
     }
     // Determine which targets to publish to
@@ -484,19 +624,23 @@ async function runPublish(siteDir, targetName, opts = {}) {
     }
     // Initialize targets
     const { createTargetRegistry } = await import('../targets.js');
-    const targets = await createTargetRegistry(Object.fromEntries(targetNames.map(n => [n, siteYaml.targets[n]])), siteDir);
-    const { publishPageRendered, publishPageStatic, publishFragmentRendered, publishSiteManifest, publishDepIndices } = await import('../publish-rendered.js');
-    const { publishPageAllLocales, publishFragmentAllLocales } = await import('../publish-locale.js');
-    const { scanTemplates, templateHashesFrom, reportTemplateErrors } = await import('../templates-scan.js');
-    const { hashManifest } = await import('../hash.js');
-    // Validate + hash templates once for this publish run
+    const targets = await createTargetRegistry(Object.fromEntries(targetNames.map(n => [n, siteYaml.targets[n]])));
+    // Per Cut 6 cutover: per-target render loop now goes through publishRun
+    // (imported below at use site). publishRun owns: per-item dispatch +
+    // asset publish + dep indices + site manifest. CLI keeps: incremental
+    // skip via compareTargets, locale fan-out into ItemRefs, console
+    // output via onProgress, sitemap+robots+redirects+purge post-loop.
+    const { scanTemplates, reportTemplateErrors } = await import('../templates-scan.js');
+    // Validate templates once for this publish run. publishRun consumes
+    // templateInfos directly and computes hashes internally (per Cut 5
+    // expansion); CLI only needs to scan + bail on invalid templates
+    // before launching the run.
     const templateInfos = await scanTemplates(templatesDir, projectRoot);
     const invalid = reportTemplateErrors(templateInfos);
     if (invalid > 0) {
         console.error(`\n  ${c.red('✗')} Refusing to publish with invalid templates.`);
         process.exit(1);
     }
-    const templateHashes = templateHashesFrom(templateInfos);
     console.log();
     console.log(`  ${c.bgGreen(c.bold(' gazetta '))} ${c.green('publish')} ${c.dim(site.manifest.name)}`);
     console.log();
@@ -504,6 +648,24 @@ async function runPublish(siteDir, targetName, opts = {}) {
     console.log(`  ${c.dim('┃')} Fragments  ${c.dim([...site.fragments.keys()].join(', '))}`);
     console.log(`  ${c.dim('┃')} Targets    ${targetNames.join(', ')}`);
     console.log();
+    // Cutover (Cut 6 of publish-pipeline-extraction): per-target render
+    // loop now delegates to `publishRun` for the per-target × per-item
+    // dispatch + asset publish + dep indices + site manifest. CLI keeps
+    // ownership of:
+    //   - target registry init + per-target loop (so target-init failures
+    //     can short-circuit just that target)
+    //   - incremental skip via compareTargets (publishRun is filter-blind;
+    //     CLI pre-filters ItemRefs[] based on per-locale unchanged sets)
+    //   - locale fan-out (CLI expands page name → ItemRef[] including all
+    //     locale variants supported by the target)
+    //   - console output (onProgress callback formats human-readable lines)
+    //   - sitemap / robots.txt / _redirects / cache purge (post-publishRun
+    //     side effects on each target — kept inline)
+    //
+    // publishRun owns: per-item mode dispatch, archive short-circuit,
+    // sidecar emit, asset publish, dep indices, site manifest emit.
+    const { publishRun } = await import('../publish-run.js');
+    const { createContentRoot: _createContentRoot } = await import('../content-root.js');
     for (const name of targetNames) {
         const targetStorage = targets.get(name);
         if (!targetStorage) {
@@ -513,7 +675,6 @@ async function runPublish(siteDir, targetName, opts = {}) {
         const targetConfig = siteYaml.targets[name];
         const { getType } = await import('../types.js');
         const targetType = targetConfig ? getType(targetConfig) : 'static';
-        const isStatic = targetType === 'static';
         console.log(`  ${c.bold(name)} ${c.dim(`(${targetType})`)}`);
         let totalFiles = 0;
         let totalRemoved = 0;
@@ -535,117 +696,102 @@ async function runPublish(siteDir, targetName, opts = {}) {
                 unchanged.add(item);
         }
         let skipped = 0;
-        const sourceRoot = source.contentRoot;
-        // Asset publish — before any page render, so static-mode page HTML
-        // doesn't bake in URLs to bytes that aren't on the target yet. Skips
-        // assets that are already on target (content-addressed dedupe).
-        {
-            const { publishAssets } = await import('../assets/publish.js');
-            const { createContentRoot } = await import('../content-root.js');
-            const targetRoot = createContentRoot(targetStorage);
-            const itemNames = [
-                ...[...site.pages.keys()].map(n => `pages/${n}`),
-                ...[...site.fragments.keys()].map(n => `fragments/${n}`),
-            ];
-            const assetResult = await publishAssets({ sourceRoot, targetRoot, itemNames });
-            if (!assetResult.ok) {
-                console.error(`    ${c.red('✗')} Asset publish failed: source is missing — ${assetResult.missing.join(', ')}`);
-                process.exit(1);
-            }
-            if (assetResult.copiedAssets > 0) {
-                console.log(`    ${c.green('✓')} ${assetResult.copiedAssets} asset(s), ${assetResult.copiedFiles} file(s)`);
-            }
-            totalFiles += assetResult.copiedFiles;
-        }
-        // SEO context for this target — built once, shared across all page renders.
-        const seo = {
-            siteName: site.manifest.name,
-            siteUrl: targetConfig?.siteUrl,
-            locale: site.manifest.locale,
-            defaultOgImage: site.manifest.defaultOgImage,
-        };
-        if (isStatic) {
-            // Static mode — fully assembled HTML, no fragments needed separately.
-            // Page hash must include fragment hashes so a fragment change
-            // invalidates every page that bakes it in (compareTargets uses the
-            // same combination on the local side).
-            const fragmentHashes = new Map();
-            for (const [fragName, frag] of site.fragments) {
-                fragmentHashes.set(fragName, hashManifest(frag, { templateHashes }));
+        // Build the per-target ItemRef list. CLI does the locale fan-out
+        // explicitly here (vs publishRun, which treats the input list
+        // verbatim). Each (page|fragment, locale) cell becomes one ItemRef
+        // unless the unchanged set covers it.
+        const targetLocales = targetConfig?.locales;
+        const itemRefs = [];
+        const skippedNames = new Set(); // for console output (item entirely skipped)
+        // Pages — default + per-locale variants, filtered by target.locales when set.
+        for (const [pageName] of site.pages) {
+            const pageLocales = site.pageLocales.get(pageName);
+            const localesForPage = [undefined];
+            if (pageLocales) {
+                for (const loc of pageLocales.locales.keys()) {
+                    if (targetLocales && !targetLocales.includes(loc))
+                        continue;
+                    localesForPage.push(loc);
+                }
             }
-            for (const [pageName, page] of site.pages) {
-                if (unchanged.has(`pages/${pageName}`)) {
-                    skipped++;
+            let added = 0;
+            for (const loc of localesForPage) {
+                const key = loc ? `pages/${pageName}:${loc}` : `pages/${pageName}`;
+                if (unchanged.has(key))
                     continue;
-                }
-                const manifestHash = hashManifest(page, { templateHashes, fragmentHashes });
-                const { files } = await publishPageStatic(pageName, sourceRoot, targetStorage, templatesDir, manifestHash, site, seo);
-                totalFiles += files;
-                console.log(`    ${c.green('✓')} ${pageName}`);
+                itemRefs.push({ kind: 'page', name: pageName, locale: loc });
+                added++;
+            }
+            if (added === 0 && localesForPage.length > 0) {
+                skippedNames.add(`pages/${pageName}`);
+                skipped++;
             }
         }
-        else {
-            // ESI mode — fragments separate, pages with placeholders
+        // Fragments — only emitted as separate items for non-static targets
+        // (static bakes them into pages). For static, the publishRun spine
+        // still needs them in the site for page rendering (already loaded).
+        if (targetType !== 'static') {
             for (const [fragName] of site.fragments) {
-                // Build per-locale unchanged set: null = default, 'fr' = French
-                const fragUnchanged = new Set();
-                if (unchanged.has(`fragments/${fragName}`))
-                    fragUnchanged.add(null);
                 const fragLocales = site.fragmentLocales.get(fragName);
+                const localesForFrag = [undefined];
                 if (fragLocales) {
                     for (const loc of fragLocales.locales.keys()) {
-                        if (unchanged.has(`fragments/${fragName}:${loc}`))
-                            fragUnchanged.add(loc);
+                        if (targetLocales && !targetLocales.includes(loc))
+                            continue;
+                        localesForFrag.push(loc);
                     }
                 }
-                // Skip entirely if all locales unchanged
-                const totalFragLocales = 1 + (fragLocales?.locales.size ?? 0);
-                if (fragUnchanged.size >= totalFragLocales) {
+                let added = 0;
+                for (const loc of localesForFrag) {
+                    const key = loc ? `fragments/${fragName}:${loc}` : `fragments/${fragName}`;
+                    if (unchanged.has(key))
+                        continue;
+                    itemRefs.push({ kind: 'fragment', name: fragName, locale: loc });
+                    added++;
+                }
+                if (added === 0 && localesForFrag.length > 0) {
+                    skippedNames.add(`fragments/${fragName}`);
                     skipped++;
-                    continue;
                 }
-                const { files, removed } = await publishFragmentAllLocales(fragName, sourceRoot, targetStorage, site, { templateHashes }, { templatesDir, targetLocales: targetConfig?.locales, unchangedLocales: fragUnchanged });
-                totalFiles += files;
-                totalRemoved += removed;
-                const skippedCount = fragUnchanged.size > 0 ? ` (${fragUnchanged.size} locale${fragUnchanged.size > 1 ? 's' : ''} skipped)` : '';
-                console.log(`    ${c.green('✓')} @${fragName}${skippedCount}`);
             }
-            for (const [pageName] of site.pages) {
-                // Build per-locale unchanged set
-                const pageUnchanged = new Set();
-                if (unchanged.has(`pages/${pageName}`))
-                    pageUnchanged.add(null);
-                const pageLocales = site.pageLocales.get(pageName);
-                if (pageLocales) {
-                    for (const loc of pageLocales.locales.keys()) {
-                        if (unchanged.has(`pages/${pageName}:${loc}`))
-                            pageUnchanged.add(loc);
+        }
+        // Delegate the per-item × per-target render loop + asset publish +
+        // dep indices + site manifest to publishRun. Single-target call;
+        // CLI loops targets itself so per-target init failures (storage
+        // missing) short-circuit just that target.
+        const runResult = await publishRun({
+            items: itemRefs,
+            targets: [name],
+            site,
+            sourceRoot: source.contentRoot,
+            siteManifest: manifest,
+            targetStorages: new Map([[name, targetStorage]]),
+            templateInfos,
+            onProgress: ev => {
+                if (ev.kind === 'item-done') {
+                    if (ev.result.ok) {
+                        const label = ev.result.kind === 'fragment' ? `@${ev.result.name}` : ev.result.name;
+                        const localeMark = ev.result.locale ? c.dim(` (${ev.result.locale})`) : '';
+                        console.log(`    ${c.green('✓')} ${label}${localeMark}`);
+                    }
+                    else {
+                        const label = ev.result.kind === 'fragment' ? `@${ev.result.name}` : ev.result.name;
+                        console.error(`    ${c.red('✗')} ${label}: ${ev.result.code}`);
                     }
                 }
-                const totalPageLocales = 1 + (pageLocales?.locales.size ?? 0);
-                if (pageUnchanged.size >= totalPageLocales) {
-                    skipped++;
-                    continue;
-                }
-                const { files, removed } = await publishPageAllLocales(pageName, sourceRoot, targetStorage, site, { templateHashes }, {
-                    cache: targetConfig?.cache,
-                    templatesDir,
-                    seo,
-                    targetLocales: targetConfig?.locales,
-                    unchangedLocales: pageUnchanged,
-                });
-                totalFiles += files;
-                totalRemoved += removed;
-                const skippedCount = pageUnchanged.size > 0 ? ` (${pageUnchanged.size} locale${pageUnchanged.size > 1 ? 's' : ''} skipped)` : '';
-                console.log(`    ${c.green('✓')} ${pageName}${skippedCount}`);
+            },
+        });
+        // Aggregate counts from publishRun's per-target result.
+        const tr = runResult.targets.find(t => t.name === name);
+        if (tr) {
+            totalFiles += tr.filesWritten;
+            totalRemoved += tr.filesRemoved;
+            if (tr.failed) {
+                console.error(`    ${c.red('✗')} target failed: ${tr.failureReason ?? 'all items failed'}`);
             }
         }
         if (skipped > 0)
             console.log(`    ${c.dim(`· ${skipped} unchanged (skipped)`)}`);
-        // Site manifest + dep-sidecar indices
-        await publishSiteManifest(sourceRoot, targetStorage, site);
-        await publishDepIndices(sourceRoot, targetStorage, site);
-        totalFiles += 1;
         // Sitemap + robots.txt — generated from target sidecars
         const siteUrl = targetConfig?.siteUrl;
         if (siteUrl) {
@@ -755,6 +901,36 @@ async function runPublish(siteDir, targetName, opts = {}) {
                 console.log(`    ${c.dim('· robots.txt')}`);
             }
         }
+        // Host-format redirects file (e.g. _redirects for Cloudflare/Netlify).
+        // Per design-soft-delete.md Q10: plain-static targets without a worker
+        // can't read the per-page HTML marker; this file is the host-glue
+        // that makes archived-page redirects work for them. Independent of
+        // siteUrl — the format determines whether to emit at all.
+        const redirectsFormat = targetConfig?.redirects?.format;
+        if (redirectsFormat && redirectsFormat !== 'none') {
+            const { emitRedirects } = await import('../runtime/redirects-emit.js');
+            const { allPageEntries, deriveRoute } = await import('../site-loader.js');
+            const archives = [];
+            for (const entry of allPageEntries(site)) {
+                if (entry.page.archived !== true)
+                    continue;
+                // Locale variants share the parent's archive state in v1; the
+                // default-locale row is the canonical entry. Per-locale archive
+                // is reserved for a future cut (per `design-soft-delete.md`
+                // future directions).
+                if (entry.locale)
+                    continue;
+                const from = deriveRoute(entry.name);
+                const to = entry.page.aliasOf ? deriveRoute(entry.page.aliasOf) : undefined;
+                archives.push(to !== undefined ? { from, to } : { from });
+            }
+            const result = emitRedirects(redirectsFormat, archives);
+            if (result && result.body !== '') {
+                await targetStorage.writeFile(result.filename, result.body);
+                totalFiles++;
+                console.log(`    ${c.dim(`· ${result.filename}`)}`);
+            }
+        }
         const removedMsg = totalRemoved > 0 ? c.dim(` (${totalRemoved} old files cleaned)`) : '';
         console.log(`\n  ${c.green('✓')} ${c.bold(name)}: ${totalFiles} files published${removedMsg}\n`);
     }
@@ -960,7 +1136,9 @@ async function runAdmin(siteDir, port) {
     app.get('/__reload', ctx => ctx.body(null, 204));
     const { buildSourceContext } = await import('./bootstrap.js');
     const { source, targetConfigs } = await buildSourceContext({ projectSiteDir: siteDir });
-    await setupProductionMode(app, source, siteDir, builtAdminDir, templatesDir, adminDir, targetConfigs);
+    const manifest = await loadSiteManifestForCli(siteDir);
+    const hookContributions = readHookContributions(manifest);
+    await setupProductionMode(app, source, siteDir, builtAdminDir, templatesDir, adminDir, targetConfigs, hookContributions, manifest);
     // SPA fallback for non-API admin routes
     app.get('*', ctx => {
         const indexPath = join(builtAdminDir, 'index.html');
@@ -968,10 +1146,10 @@ async function runAdmin(siteDir, port) {
             return ctx.html(readFileSync(indexPath, 'utf-8'));
         return ctx.notFound();
     });
-    const siteYaml = yaml.load(readFileSync(join(siteDir, 'site.yaml'), 'utf-8'));
+    const siteManifest = (await loadSiteManifestForCli(siteDir)) ?? { name: 'gazetta' };
     const server = serve({ fetch: app.fetch, port }, () => {
         console.log();
-        console.log(`  ${c.bgGreen(c.bold(' gazetta '))} ${c.green('admin')} ${c.dim(siteYaml.name)}`);
+        console.log(`  ${c.bgGreen(c.bold(' gazetta '))} ${c.green('admin')} ${c.dim(siteManifest.name)}`);
         console.log();
         console.log(`  ${c.dim('┃')} Admin    ${c.cyan(`http://localhost:${port}/admin`)}`);
         console.log();
@@ -984,25 +1162,24 @@ async function runAdmin(siteDir, port) {
     }
 }
 async function runServe(siteDir, port, targetName) {
-    const siteYamlPath = join(siteDir, 'site.yaml');
-    if (!existsSync(siteYamlPath)) {
-        console.error(`\n  Error: ${siteYamlPath} not found\n`);
+    const siteYaml = await loadSiteManifestForCli(siteDir);
+    if (!siteYaml) {
+        console.error(`\n  Error: no site config found in ${siteDir} (looked for site.config.ts)\n`);
         process.exit(1);
     }
-    const siteYaml = yaml.load(readFileSync(siteYamlPath, 'utf-8'));
     if (!siteYaml.targets || Object.keys(siteYaml.targets).length === 0) {
-        console.error('\n  Error: no targets configured in site.yaml\n');
+        console.error('\n  Error: no targets configured in site config\n');
         process.exit(1);
     }
     const name = targetName ?? Object.keys(siteYaml.targets)[0];
     const config = siteYaml.targets[name];
     if (!config) {
-        console.error(`\n  Error: target "${name}" not found in site.yaml\n`);
+        console.error(`\n  Error: target "${name}" not found in site config\n`);
         process.exit(1);
     }
-    const { createStorageProvider } = await import('../targets.js');
-    // Pass targetName so filesystem path defaults to ./targets/<name> when unset.
-    const storage = await createStorageProvider(config.storage, siteDir, name);
+    // Storage is already a constructed provider (Path X — operator-facing
+    // factory ran at config-eval).
+    const storage = config.storage;
     const { getType } = await import('../types.js');
     const { createServer } = await import('../serve.js');
     const app = createServer({ storage, type: getType(config) });
@@ -1021,16 +1198,13 @@ async function runServe(siteDir, port, targetName) {
     }
 }
 async function runDeploy(siteDir, targetName) {
-    const { execSync } = await import('node:child_process');
-    const { writeFile, mkdir, rm } = await import('node:fs/promises');
-    const siteYamlPath = join(siteDir, 'site.yaml');
-    if (!existsSync(siteYamlPath)) {
-        console.error(`\n  Error: No site.yaml found at ${siteDir}\n`);
+    const siteYaml = await loadSiteManifestForCli(siteDir);
+    if (!siteYaml) {
+        console.error(`\n  Error: no site config found at ${siteDir} (looked for site.config.ts)\n`);
         process.exit(1);
     }
-    const siteYaml = yaml.load(readFileSync(siteYamlPath, 'utf-8'));
     if (!siteYaml.targets) {
-        console.error(`\n  Error: No targets configured in site.yaml\n`);
+        console.error(`\n  Error: No targets configured in site config\n`);
         process.exit(1);
     }
     if (!targetName) {
@@ -1042,130 +1216,193 @@ async function runDeploy(siteDir, targetName) {
         console.error(`\n  Error: Unknown target "${targetName}". Available: ${Object.keys(siteYaml.targets).join(', ')}\n`);
         process.exit(1);
     }
-    if (!target.worker) {
-        console.error(`\n  Error: Target "${targetName}" has no worker config. Add to site.yaml:\n\n  worker:\n    type: cloudflare\n    name: my-site\n`);
+    if (!target.deploy) {
+        console.error(`\n  Error: Target "${targetName}" has no \`deploy:\` adapter configured. Add to site.config.ts:\n\n  ` +
+            `import { cloudflareWorkersDeploy } from 'gazetta'\n  ` +
+            `deploy: cloudflareWorkersDeploy({\n  ` +
+            `  apiToken: process.env.CLOUDFLARE_API_TOKEN!,\n  ` +
+            `  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,\n  ` +
+            `  name: '${targetName}',\n  ` +
+            `  bucket: '${targetName}',\n  })\n\n` +
+            `For container hosts (Fly.io, Cloud Run, Railway, Render), use platform-native\n` +
+            `deploy tooling; see docs/container-deployment.md.\n`);
         process.exit(1);
     }
-    if (target.worker.type !== 'cloudflare') {
-        console.error(`\n  Error: Unsupported worker type "${target.worker.type}". Currently only "cloudflare" is supported.\n`);
-        process.exit(1);
-    }
-    // Generate worker in temp dir
-    const workerName = target.worker.name ?? targetName;
-    const bucketName = target.storage.bucket ?? workerName;
-    const tmpDir = join(siteDir, '.gazetta-deploy');
-    await rm(tmpDir, { recursive: true, force: true });
-    await mkdir(tmpDir, { recursive: true });
-    // Generate wrangler.toml
-    let wranglerToml = `name = "${workerName}"\nmain = "index.ts"\ncompatibility_date = "2024-12-01"\nworkers_dev = true\n\n[[r2_buckets]]\nbinding = "SITE_BUCKET"\nbucket_name = "${bucketName}"\n`;
-    // Add custom domain route if siteUrl is configured
-    if (target.siteUrl) {
-        const url = new URL(target.siteUrl);
-        const hostname = url.hostname;
-        wranglerToml += `\n[[routes]]\npattern = "${hostname}/*"\nzone_name = "${hostname}"\n`;
-    }
-    await writeFile(join(tmpDir, 'wrangler.toml'), wranglerToml);
-    // Generate worker entry point
-    const workerCode = `import { createWorker } from 'gazetta/workers/cloudflare-r2'\nexport default createWorker()\n`;
-    await writeFile(join(tmpDir, 'index.ts'), workerCode);
-    // Generate package.json for wrangler
-    const pkgJson = JSON.stringify({
-        type: 'module',
-        dependencies: { gazetta: '*', hono: '*' },
-    });
-    await writeFile(join(tmpDir, 'package.json'), pkgJson);
-    // Install deps and deploy
-    console.log(`  Deploying worker "${workerName}" to Cloudflare...`);
+    const adapter = target.deploy;
+    console.log(`  ${c.cyan(`Deploying via ${adapter.name}...`)}`);
+    // Build a no-op logger; v1 deploy doesn't require structured logging yet.
+    const logger = {
+        debug: (_o, _m) => { },
+        info: (_o, _m) => { },
+        warn: (o, m) => console.warn(`  ${typeof o === 'string' ? o : (m ?? '')}`),
+        error: (o, m) => console.error(`  ${typeof o === 'string' ? o : (m ?? '')}`),
+    };
     try {
-        execSync('npm install --install-links ' + resolve(import.meta.dirname, '../..'), { cwd: tmpDir, stdio: 'pipe' });
-        const output = execSync('npx wrangler deploy', { cwd: tmpDir, stdio: 'pipe' }).toString();
-        const urlMatch = output.match(/https:\/\/[^\s]+/);
-        console.log(`  Worker deployed: ${urlMatch?.[0] ?? workerName}`);
+        const result = await adapter.execute({
+            target,
+            targetName,
+            // outputDir not used by worker-deploy adapters (worker reads R2 at request).
+            // Adapters that need bytes (static-host) read storage themselves.
+            outputDir: join(siteDir, 'dist', targetName),
+            storage: target.storage,
+            env: process.env,
+            logger,
+            signal: new AbortController().signal,
+        });
+        if (result.url)
+            console.log(`  ${c.green('✓')} Deployed: ${result.url}`);
+        else
+            console.log(`  ${c.green('✓')} Deployed.`);
         if (target.siteUrl)
             console.log(`  Site: ${target.siteUrl}`);
     }
     catch (err) {
-        const stderr = err.stderr?.toString() ?? err.message;
-        console.error(`\n  Deploy failed: ${stderr}\n`);
+        const message = err instanceof Error ? err.message : String(err);
+        const adapterTag = err.adapter ?? adapter.name;
+        console.error(`\n  ${c.red(`Deploy failed (${adapterTag}):`)} ${message}\n`);
         process.exit(1);
     }
-    finally {
-        await rm(tmpDir, { recursive: true, force: true });
-    }
-    console.log(`\n  ${c.green('✓')} Worker deployed. Now publish content:\n    ${c.cyan(`gazetta publish ${targetName}`)}\n`);
+    console.log(`\n  ${c.green('✓')} Deploy complete. Publish content with:\n    ${c.cyan(`gazetta publish ${targetName}`)}\n`);
 }
-async function runValidate(siteDir) {
+const QUALITY_VALIDATORS = new Set(['accessibility', 'html-validity', 'broken-links']);
+async function runValidate(siteDir, rawArgs = []) {
     const projectRoot = detectProjectRoot(siteDir);
     const templatesDir = join(projectRoot, 'templates');
+    const opts = parseValidateFlags(rawArgs);
     console.log();
     console.log(`  ${c.bgGreen(c.bold(' gazetta '))} ${c.green('validate')} ${c.dim(siteDir)}`);
     console.log();
-    // 1. Check site.yaml + load default editable target's content
+    // 1. Load site
+    const configLabel = existsSync(join(siteDir, 'site.config.ts'))
+        ? 'site.config.ts'
+        : existsSync(join(siteDir, 'site.config.js'))
+            ? 'site.config.js'
+            : 'site.config.mjs';
+    const { buildSourceContext } = await import('./bootstrap.js');
     let site;
+    let source;
     try {
-        const { buildSourceContext } = await import('./bootstrap.js');
-        const { source, manifest } = await buildSourceContext({ projectSiteDir: siteDir });
-        site = await loadSite({ contentRoot: source.contentRoot, templatesDir, manifest });
-        console.log(`  ${c.green('✓')} site.yaml ${c.dim(`— ${site.manifest.name}`)}`);
+        const built = await buildSourceContext({ projectSiteDir: siteDir });
+        source = built.source;
+        site = await loadSite({ contentRoot: source.contentRoot, templatesDir, manifest: built.manifest });
+        console.log(`  ${c.green('✓')} ${configLabel} ${c.dim(`— ${site.manifest.name}`)}`);
     }
     catch (err) {
-        console.error(`  ${c.red('✗')} site.yaml ${c.dim(`— ${err.message}`)}`);
+        console.error(`  ${c.red('✗')} ${configLabel} ${c.dim(`— ${err.message}`)}`);
         process.exit(1);
     }
-    let errors = 0;
-    // 2. Validate all fragments
-    for (const [fragName, frag] of site.fragments) {
-        try {
-            const { resolveComponent } = await import('../resolver.js');
-            const ctx = { site, templatesDir: site.templatesDir, visited: new Set(), path: [`@${fragName}`] };
-            await resolveComponent(`@${fragName}`, ctx);
-            const childCount = frag.components?.length ?? 0;
-            console.log(`  ${c.green('✓')} @${fragName} ${c.dim(`(${childCount} components)`)}`);
-        }
-        catch (err) {
-            console.error(`  ${c.red('✗')} @${fragName} ${c.dim(`— ${err.message}`)}`);
-            errors++;
-        }
+    // 2. Build the registry. Skip quality validators (a11y, html-validity)
+    //    unless `--include-quality` — they trigger rendering and add seconds
+    //    per page; default keeps the CLI snappy for CI ref-existence gating.
+    const { defaultValidatorRegistry } = await import('../validation/default-registry.js');
+    const { createValidatorRegistry } = await import('../validation/registry.js');
+    const fullRegistry = defaultValidatorRegistry();
+    const filtered = opts.includeQuality
+        ? fullRegistry
+        : createValidatorRegistry(fullRegistry.all().filter(v => !QUALITY_VALIDATORS.has(v.name)));
+    // 3. Run via the scanner — same orchestrator as the admin background scan,
+    //    so the CLI exercises identical code paths.
+    const { createValidationScanner } = await import('../validation/scanner.js');
+    const { createMemoryCache } = await import('../cache/memory.js');
+    const scanner = createValidationScanner({
+        storage: source.storage,
+        contentRoot: source.contentRoot,
+        registry: filtered,
+        cache: createMemoryCache(),
+        siteOptions: { templatesDir, manifest: site.manifest },
+        loadSiteImpl: async () => site,
+    });
+    await scanner.scanAll();
+    const allIssues = scanner.allIssues();
+    // 4. Per-item summary. Pages first, then fragments — matches the existing
+    //    output ordering for unsurprising diff vs. the prior implementation.
+    let errorCount = 0;
+    let warnCount = 0;
+    let infoCount = 0;
+    const issuesByPath = new Map();
+    for (const issue of allIssues) {
+        const list = issuesByPath.get(issue.itemPath) ?? [];
+        list.push(issue);
+        issuesByPath.set(issue.itemPath, list);
+        if (issue.severity === 'error')
+            errorCount++;
+        else if (issue.severity === 'warn')
+            warnCount++;
+        else
+            infoCount++;
+    }
+    function summaryGlyph(issues) {
+        if (issues.some(i => i.severity === 'error'))
+            return { glyph: '✗', color: c.red };
+        if (issues.some(i => i.severity === 'warn'))
+            return { glyph: '⚠', color: c.yellow };
+        if (issues.length > 0)
+            return { glyph: 'ⓘ', color: c.cyan };
+        return { glyph: '✓', color: c.green };
+    }
+    function shouldShow(severity) {
+        if (opts.severity === 'all')
+            return true;
+        if (opts.severity === 'warn')
+            return severity !== 'info';
+        return severity === 'error';
     }
-    // 3. Validate all pages
     for (const [pageName, page] of site.pages) {
-        try {
-            await resolvePage(pageName, site);
-            const componentCount = page.components?.length ?? 0;
-            const fragmentCount = page.components?.filter(cc => typeof cc === 'string' && cc.startsWith('@')).length ?? 0;
-            console.log(`  ${c.green('✓')} ${pageName} ${c.dim(`(${componentCount} components, ${fragmentCount} fragments)`)}`);
+        const path = `${page.dir}/page.json`;
+        const issues = issuesByPath.get(path) ?? [];
+        const visible = issues.filter(i => shouldShow(i.severity));
+        const { glyph, color } = summaryGlyph(visible);
+        const componentCount = page.components?.length ?? 0;
+        console.log(`  ${color(glyph)} ${pageName} ${c.dim(`(${componentCount} components)`)}`);
+        if (opts.verbose) {
+            for (const issue of visible) {
+                console.log(`      ${severityIcon(issue.severity)} ${issue.message}`);
+            }
         }
-        catch (err) {
-            console.error(`  ${c.red('✗')} ${pageName} ${c.dim(`— ${err.message}`)}`);
-            errors++;
+    }
+    for (const [fragName, frag] of site.fragments) {
+        const path = `${frag.dir}/fragment.json`;
+        const issues = issuesByPath.get(path) ?? [];
+        const visible = issues.filter(i => shouldShow(i.severity));
+        const { glyph, color } = summaryGlyph(visible);
+        const childCount = frag.components?.length ?? 0;
+        console.log(`  ${color(glyph)} @${fragName} ${c.dim(`(${childCount} components)`)}`);
+        if (opts.verbose) {
+            for (const issue of visible) {
+                console.log(`      ${severityIcon(issue.severity)} ${issue.message}`);
+            }
         }
     }
-    // 4. List templates (project-level filesystem, not target content)
+    // 5. Project-structure checks (orphaned editors, missing custom fields).
+    //    These are project-layout concerns rather than per-item content rules,
+    //    so they don't fit the Validator interface — kept inline here.
+    const adminDir = join(projectRoot, 'admin');
     const projectStorage = createFilesystemProvider();
     let templateNames = [];
     try {
         const entries = await projectStorage.readDir(templatesDir);
-        templateNames = entries.filter(e => e.isDirectory).map((e) => e.name);
-        console.log(`  ${c.green('✓')} ${c.dim(`${templateNames.length} templates`)}`);
+        templateNames = entries.filter(e => e.isDirectory).map(e => e.name);
     }
     catch {
-        console.log(`  ${c.yellow('⚠')} ${c.dim('templates/ directory not found')}`);
+        /* templates dir missing — site already errored above */
     }
-    // 5. Check for orphaned editors (editor exists but template doesn't)
-    const adminDir = join(projectRoot, 'admin');
+    // 5a. Orphaned editors: editor file exists but no matching template.
+    //     Always shown regardless of --severity since these are structural
+    //     issues operators need to know about even at the strictest filter.
     const editorsDir = join(adminDir, 'editors');
     if (existsSync(editorsDir)) {
-        const editorFiles = (await import('node:fs'))
-            .readdirSync(editorsDir)
-            .filter(f => f.endsWith('.ts') || f.endsWith('.tsx'));
+        const fs = await import('node:fs');
+        const editorFiles = fs.readdirSync(editorsDir).filter(f => f.endsWith('.ts') || f.endsWith('.tsx'));
         for (const file of editorFiles) {
             const editorName = file.replace(/\.(ts|tsx)$/, '');
             if (!templateNames.includes(editorName)) {
                 console.log(`  ${c.yellow('⚠')} orphaned editor: ${c.dim(`admin/editors/${file}`)} ${c.dim('— no matching template')}`);
+                warnCount++;
             }
         }
     }
-    // 6. Check for missing custom fields (schema references field but file doesn't exist)
+    // 5b. Missing custom fields: schema references field: 'name' but no
+    //     admin/fields/name.{ts,tsx}. Hard error — render fails without it.
     const fieldsDir = join(adminDir, 'fields');
     const fieldFiles = existsSync(fieldsDir)
         ? (await import('node:fs'))
@@ -1173,96 +1410,60 @@ async function runValidate(siteDir) {
             .filter(f => f.endsWith('.ts') || f.endsWith('.tsx'))
             .map(f => f.replace(/\.(ts|tsx)$/, ''))
         : [];
-    const { loadTemplate } = await import('../template-loader.js');
-    const zod = await import('zod');
-    for (const tplName of templateNames) {
-        try {
-            const loaded = await loadTemplate(projectStorage, templatesDir, tplName);
-            const jsonSchema = zod.z.toJSONSchema(loaded.schema);
-            const props = jsonSchema.properties;
-            if (!props)
-                continue;
-            for (const [propName, prop] of Object.entries(props)) {
-                const fieldRef = prop.field;
-                if (fieldRef && !fieldFiles.includes(fieldRef)) {
-                    console.error(`  ${c.red('✗')} template ${tplName}.${propName} references field "${fieldRef}" ${c.dim('— not found in admin/fields/')}`);
-                    errors++;
-                }
-            }
-        }
-        catch {
-            /* template load errors already caught above */
-        }
-    }
-    // 7. Locale validation
-    const { defaultLocaleFor } = await import('../locale.js');
-    const defLoc = defaultLocaleFor(site.manifest);
-    const hasI18n = !!site.manifest.locales?.supported?.length;
-    // 7a. Warn about orphaned locale files when i18n is disabled
-    if (!hasI18n && (site.pageLocales.size > 0 || site.fragmentLocales.size > 0)) {
-        const orphanCount = site.pageLocales.size + site.fragmentLocales.size;
-        console.log(`  ${c.yellow('⚠')} ${orphanCount} locale file${orphanCount > 1 ? 's' : ''} found but i18n is disabled ${c.dim('— add locales.supported to site.yaml or remove *.locale.json files')}`);
-    }
-    // 7b. Warn about ambiguous page.en.json when en is default
-    if (hasI18n) {
-        for (const [name, entry] of site.pageLocales) {
-            if (entry.locales.has(defLoc)) {
-                console.log(`  ${c.yellow('⚠')} page.${defLoc}.json in ${name} is ambiguous ${c.dim(`— "${defLoc}" is the default locale, use page.json instead`)}`);
-            }
-        }
-        for (const [name, entry] of site.fragmentLocales) {
-            if (entry.locales.has(defLoc)) {
-                console.log(`  ${c.yellow('⚠')} fragment.${defLoc}.json in ${name} is ambiguous ${c.dim(`— "${defLoc}" is the default locale, use fragment.json instead`)}`);
-            }
-        }
-    }
-    // 7c. Validate locale variant template/fragment refs
-    if (hasI18n) {
-        for (const [pageName, entry] of site.pageLocales) {
-            for (const [locale] of entry.locales) {
-                try {
-                    await resolvePage(pageName, site, locale);
-                }
-                catch (err) {
-                    console.error(`  ${c.red('✗')} ${pageName} (${locale}) ${c.dim(`— ${err.message}`)}`);
-                    errors++;
-                }
-            }
-        }
-    }
-    // 8. Cross-domain hreflang bidirectional check
-    // For per-domain targets (each with siteUrl + single locale), verify that
-    // all targets serving the same page cross-link to each other.
-    if (hasI18n && site.manifest.targets) {
-        const targetsWithSiteUrl = Object.entries(site.manifest.targets).filter(([, cfg]) => cfg.siteUrl && cfg.locales?.length === 1);
-        if (targetsWithSiteUrl.length > 1) {
-            const localeToUrl = new Map();
-            for (const [, cfg] of targetsWithSiteUrl) {
-                localeToUrl.set(cfg.locales[0], cfg.siteUrl);
-            }
-            const missingPairs = [];
-            for (const [locA, urlA] of localeToUrl) {
-                for (const [locB, urlB] of localeToUrl) {
-                    if (locA === locB)
-                        continue;
-                    // Each target's sitemap should cross-link to the other
-                    // We can't check the actual sitemaps here (would need network),
-                    // but we can verify the config is consistent
+    if (templateNames.length > 0) {
+        const { loadTemplate } = await import('../template-loader.js');
+        const zod = await import('zod');
+        for (const tplName of templateNames) {
+            try {
+                const loaded = await loadTemplate(projectStorage, templatesDir, tplName);
+                const jsonSchema = zod.z.toJSONSchema(loaded.schema);
+                const props = jsonSchema.properties;
+                if (!props)
+                    continue;
+                for (const [propName, prop] of Object.entries(props)) {
+                    const fieldRef = prop.field;
+                    if (fieldRef && !fieldFiles.includes(fieldRef)) {
+                        console.error(`  ${c.red('✗')} template ${tplName}.${propName} references field "${fieldRef}" ${c.dim('— not found in admin/fields/')}`);
+                        errorCount++;
+                    }
                 }
             }
-            if (localeToUrl.size > 1) {
-                console.log(`  ${c.green('✓')} cross-domain hreflang: ${[...localeToUrl.entries()].map(([l, u]) => `${l} → ${u}`).join(', ')}`);
+            catch {
+                /* template load errors surface via referenced-template-exists */
             }
         }
     }
+    // 6. Footer + exit code.
     console.log();
-    if (errors > 0) {
-        console.error(`  ${errors} error${errors > 1 ? 's' : ''} found.\n`);
-        process.exit(1);
-    }
-    else {
-        console.log(`  All good.\n`);
+    const totalShown = opts.severity === 'all'
+        ? errorCount + warnCount + infoCount
+        : opts.severity === 'warn'
+            ? errorCount + warnCount
+            : errorCount;
+    if (totalShown === 0) {
+        console.log(`  ${c.green('All good.')}\n`);
+        return;
     }
+    const parts = [];
+    if (errorCount > 0)
+        parts.push(`${errorCount} error${errorCount > 1 ? 's' : ''}`);
+    if (warnCount > 0 && opts.severity !== 'error')
+        parts.push(`${warnCount} warning${warnCount > 1 ? 's' : ''}`);
+    if (infoCount > 0 && opts.severity === 'all')
+        parts.push(`${infoCount} info`);
+    const summary = parts.join(', ');
+    console.log(`  ${summary}.\n`);
+    // Exit non-zero if errors OR (warns AND warn-as-error is on).
+    const fail = errorCount > 0 || (opts.warnAsError && warnCount > 0);
+    if (fail)
+        process.exit(1);
+}
+function severityIcon(severity) {
+    if (severity === 'error')
+        return c.red('✗');
+    if (severity === 'warn')
+        return c.yellow('⚠');
+    return c.cyan('ⓘ');
 }
 function renderErrorOverlay(err) {
     const message = err.message.replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -1313,7 +1514,7 @@ async function runDev(siteDir, port) {
     const projectRoot = detectProjectRoot(siteDir);
     const templatesDir = join(projectRoot, 'templates');
     const adminDir = join(projectRoot, 'admin');
-    // Build the source context from the default editable target in site.yaml.
+    // Build the source context from the default editable target in site.config.ts.
     // Cloud targets aren't init'd — admin API handles them lazily.
     const { buildSourceContext } = await import('./bootstrap.js');
     const { source, manifest, targetConfigs } = await buildSourceContext({ projectSiteDir: siteDir });
@@ -1368,6 +1569,7 @@ async function runDev(siteDir, port) {
     app.route('/', assetServeRoutes(async () => source.storage));
     // ---- Site page routes (default + locale variants) ----
     const { allPageEntries } = await import('../site-loader.js');
+    const { defaultLocaleFor: _devDefaultLocaleFor } = await import('../locale.js');
     for (const { name: pageName, page, locale: pageLocale } of allPageEntries(site)) {
         app.get(page.route, async (c) => {
             try {
@@ -1382,7 +1584,7 @@ async function runDev(siteDir, port) {
                     route: freshPage?.route ?? page.route,
                     seo: {
                         siteName: freshSite.manifest.name,
-                        locale: pageLocale ?? freshSite.manifest.locale,
+                        locale: pageLocale ?? _devDefaultLocaleFor(freshSite.manifest),
                         defaultOgImage: freshSite.manifest.defaultOgImage,
                     },
                 });
@@ -1437,14 +1639,17 @@ async function runDev(siteDir, port) {
     const isDevMode = cmsWebDir !== null;
     // Admin Hono instance — captured so the template file watcher can
     // invalidate its memoized template-scan cache on .ts/.tsx changes.
+    // `rescanForTemplate` is optional: only the dev-mode setup decorates
+    // it (production has no file watcher). Watcher uses optional-chaining.
     let cmsApp = null;
+    const hookContributions = readHookContributions(manifest);
     if (isDevMode) {
         // Dev mode: mount CMS API inline (same process = shared template cache)
-        cmsApp = await setupCmsApi(app, source, siteDir, templatesDir, adminDir, targetConfigs);
+        cmsApp = await setupCmsApi(app, source, siteDir, templatesDir, adminDir, targetConfigs, hookContributions, manifest);
     }
     else if (cmsStaticDir) {
         // Production mode: inline CMS API + static files
-        cmsApp = await setupProductionMode(app, source, siteDir, cmsStaticDir, templatesDir, adminDir, targetConfigs);
+        cmsApp = await setupProductionMode(app, source, siteDir, cmsStaticDir, templatesDir, adminDir, targetConfigs, hookContributions, manifest);
     }
     // ---- 404 ----
     app.notFound(c => {
@@ -1493,8 +1698,10 @@ async function runDev(siteDir, port) {
                 const env = getEnvironment(cfg);
                 const type = getType(cfg);
                 const ed = isEditable(cfg) ? 'editable ' : 'read-only';
-                const storagePath = cfg.storage?.type === 'filesystem' ? (cfg.storage.path ?? `targets/${name}`) : `${cfg.storage?.type ?? '?'}`;
-                console.log(`  ${c.dim('┃')}     ${c.dim('•')} ${name.padEnd(14)} ${c.dim(env.padEnd(11))} ${c.dim(ed)} ${c.dim(type.padEnd(8))} ${c.dim('→ ' + storagePath)}`);
+                // Path X — the storage provider is opaque (operator constructed it via
+                // factory at config-eval). Display target name + axes; the provider
+                // identity is not introspectable from the StorageProvider interface.
+                console.log(`  ${c.dim('┃')}     ${c.dim('•')} ${name.padEnd(14)} ${c.dim(env.padEnd(11))} ${c.dim(ed)} ${c.dim(type.padEnd(8))}`);
             }
         }
         if (isDevMode && cmsWebDir) {
@@ -1580,7 +1787,15 @@ async function runDev(siteDir, port) {
                         // written into the source, so the scanner misses it. Include it
                         // explicitly to avoid a mid-session page reload when a TSX editor
                         // is first loaded (#122).
-                        include: ['react/jsx-dev-runtime', 'react/jsx-runtime'],
+                        //
+                        // @formkit/drag-and-drop/vue is the ComponentTree's reorder lib
+                        // (#105). The package's main entry is CJS; the Vue subpath is
+                        // ESM. Vite's auto-scanner doesn't always pre-bundle subpath
+                        // ESM imports with mixed CJS-main packages on first load,
+                        // which triggers a runtime "Re-optimizing dependencies"
+                        // page reload mid-test on CI cold start. Explicit include
+                        // pins the subpath in the boot-time pre-bundle.
+                        include: ['react/jsx-dev-runtime', 'react/jsx-runtime', '@formkit/drag-and-drop/vue'],
                     },
                     server: {
                         middlewareMode: true,
@@ -1646,7 +1861,7 @@ async function runDev(siteDir, port) {
         console.log();
     });
     // ---- File watching ----
-    // Watch site dir for content changes (JSON manifests + site.yaml config).
+    // Watch site dir for content changes (JSON manifests + site.config.ts).
     // Swallow FSWatcher 'error' events — Node's recursive watcher throws ENOENT
     // when a watched subdir disappears (rm -rf during publish, git checkout).
     // Letting it crash would take the whole dev server down; logging a warning
@@ -1665,6 +1880,12 @@ async function runDev(siteDir, port) {
         if (filename.endsWith('.json') || filename.endsWith('.yaml')) {
             console.log(`  Manifest changed: ${filename}`);
             invalidateAllTemplates();
+            // Out-of-band manifest changes (git pull, manual edit, e2e
+            // test wipes) bypass the admin-api save handler that would
+            // otherwise invalidate the AdminCache. Drop content-summary
+            // entries so the next /api/pages or /api/fragments rebuilds
+            // from disk. Best-effort; the void promise is fire-and-forget.
+            void cmsApp?.invalidateContentCache();
             notifyReload();
         }
     });
@@ -1677,12 +1898,34 @@ async function runDev(siteDir, port) {
             if (filename.endsWith('.ts') || filename.endsWith('.tsx')) {
                 const parts = filename.split('/');
                 if (parts.length >= 1) {
-                    console.log(`  Template changed: ${parts[0]}`);
-                    invalidateTemplate(parts[0]);
-                    // Drop the admin-api's cached scan so next compare/publish
-                    // rehashes. Cheap (the scan is what's slow, not invalidation).
-                    cmsApp?.invalidateTemplatesCache();
-                    notifyReload();
+                    const templateName = parts[0];
+                    const fullPath = join(templatesDir, filename);
+                    // Suppress spurious events for files whose mtime predates the
+                    // watcher's recent window — these are kernel-delayed metadata
+                    // flushes for files written before the watcher began observing,
+                    // typical of the worker-scoped `cp -r` setup in the e2e fixture
+                    // (#286). Without the gate, the resulting notifyReload() closes
+                    // any open admin UI mid-interaction.
+                    void (async () => {
+                        if (!(await isTemplateEventRecent(fullPath, TEMPLATE_RECENT_CHANGE_WINDOW_MS))) {
+                            return;
+                        }
+                        console.log(`  Template changed: ${templateName}`);
+                        invalidateTemplate(templateName);
+                        // Drop the admin-api's cached scan so next compare/publish
+                        // rehashes. Cheap (the scan is what's slow, not invalidation).
+                        cmsApp?.invalidateTemplatesCache();
+                        // Cut 6 — fire a validation rescan with the template-edit
+                        // cause so the scanner re-runs schema-conformance against
+                        // every page+fragment using this template. The ScanEvent
+                        // emits on the /__validation SSE channel; the admin's
+                        // TemplateChangedBanner consumes it to show the
+                        // template-developer's "did I break anything?" surface.
+                        // Fire-and-forget — the scan runs in the background and
+                        // the SSE event is the signal that it finished.
+                        void cmsApp?.rescanForTemplate?.(templateName);
+                        notifyReload();
+                    })();
                 }
             }
         });
@@ -1711,16 +1954,98 @@ function mountUserThemeRoute(cmsApp, adminDir) {
         return c.body(readFileSync(themePath, 'utf-8'));
     });
 }
-async function setupCmsApi(app, source, siteDir, templatesDir, adminDir, targetConfigs) {
-    const cmsApp = createAdminApp({ source, siteDir, templatesDir, adminDir, targetConfigs });
+/**
+ * Build the background validation scanner (validation Cut 2). The scanner
+ * is constructed against the resolved source's storage + cache; the boot
+ * path kicks off an initial full-site scan in the background so admin
+ * responses don't block on it.
+ *
+ * Returns null when the manifest is unavailable (site lacks site.config.ts)
+ * — the admin app degrades gracefully (route returns empty issues; SSE
+ * channel idle).
+ */
+async function buildValidationScanner(opts) {
+    if (!opts.manifest)
+        return null;
+    const { createValidationScanner } = await import('../validation/scanner.js');
+    const { defaultValidatorRegistry } = await import('../validation/default-registry.js');
+    const scanner = createValidationScanner({
+        storage: opts.source.storage,
+        contentRoot: opts.source.contentRoot,
+        registry: defaultValidatorRegistry(),
+        cache: opts.source.cache,
+        siteOptions: { templatesDir: opts.templatesDir, manifest: opts.manifest },
+    });
+    // Boot warm: kick off the initial scan in the background. Errors are
+    // logged but don't block boot — broken validators surface as info-issues
+    // rather than failing the admin process.
+    void scanner.scanAll().catch(err => {
+        console.error('[validation] initial scan failed:', err);
+    });
+    return scanner;
+}
+async function setupCmsApi(app, source, siteDir, templatesDir, adminDir, targetConfigs, contributions, manifest) {
+    // Build + seal the hook registry from `admin.hooks` factory
+    // contributions before wiring the admin app. Hooks are an opt-in
+    // extension surface; sites without `admin.hooks` get an empty
+    // registry (no overhead).
+    const hooks = await buildHooksRegistry({ contributions });
+    const validationScanner = await buildValidationScanner({ source, templatesDir, manifest });
+    // Mount SSE on the OUTER Hono app — matches `/__reload`'s placement so
+    // the browser EventSource (which connects without an `/admin/` prefix)
+    // bypasses Vite's middleware and reaches the route. Same in prod for
+    // consistency: a save from one tab updates the badge in every other
+    // tab without polling.
+    const { mountValidationSse } = await import('../admin-api/routes/validation.js');
+    mountValidationSse(app, validationScanner);
+    const cmsApp = createAdminApp({
+        source,
+        siteDir,
+        templatesDir,
+        adminDir,
+        targetConfigs,
+        hooks,
+        validationScanner,
+    });
+    // Decorate cmsApp with the template-rescan hook before returning. The
+    // file watcher in startServer() invokes this on `.ts/.tsx` changes
+    // under `templates/{name}/`. Failure is fail-open (logged + dropped)
+    // — a scan failure shouldn't break dev-mode hot reload.
+    const decoratedApp = cmsApp;
+    decoratedApp.rescanForTemplate = async (name) => {
+        if (!validationScanner)
+            return;
+        try {
+            await validationScanner.rescan({ kind: 'template', name });
+        }
+        catch (err) {
+            console.warn(`  Validation scanner: template rescan failed for "${name}": ${err.message}`);
+        }
+    };
     mountUserThemeRoute(cmsApp, adminDir);
     app.route('/admin', cmsApp);
-    return cmsApp;
+    return decoratedApp;
 }
 // ---- Production mode: inline CMS API + static files from admin-dist/ ----
-async function setupProductionMode(app, source, siteDir, cmsStaticDir, templatesDir, adminDir, targetConfigs) {
+async function setupProductionMode(app, source, siteDir, cmsStaticDir, templatesDir, adminDir, targetConfigs, contributions, manifest) {
+    // Same shape as dev mode — `gazetta serve` reads `admin.hooks`
+    // factory contributions from the same site config.
+    const hooks = await buildHooksRegistry({ contributions });
+    const validationScanner = await buildValidationScanner({ source, templatesDir, manifest });
+    // SSE channel at the outer app's root; see setupCmsApi for rationale.
+    const { mountValidationSse } = await import('../admin-api/routes/validation.js');
+    mountValidationSse(app, validationScanner);
     // Mount CMS API inline at /admin (production mode — bundled editors/fields)
-    const cmsApp = createAdminApp({ source, siteDir, templatesDir, adminDir, production: true, targetConfigs });
+    const cmsApp = createAdminApp({
+        source,
+        siteDir,
+        templatesDir,
+        adminDir,
+        production: true,
+        targetConfigs,
+        hooks,
+        validationScanner,
+    });
     mountUserThemeRoute(cmsApp, adminDir);
     app.route('/admin', cmsApp);
     // Serve pre-built CMS static files (includes bundled editors/fields)
@@ -1785,77 +2110,76 @@ async function main() {
         await runInit(parsed.positional[0] ?? '.');
         return;
     }
-    else if (command === 'build') {
-        const siteDir = await resolveSiteDir(parsed.positional[0]);
+    // ── Resolve siteDir once (fs walk; no config eval) + load .env
+    // ── BEFORE any config-eval. Storage / deploy / AI factories read
+    // ── process.env synchronously at construction; resolveTarget()
+    // ── triggers config-eval, so env must be in place first. Per-
+    // ── command positional layouts determine which slot carries the
+    // ── site path. Site-local `.env` is honored (e.g.,
+    // ── sites/gazetta.studio/.env with R2 creds) per design-config.md.
+    siteDir = await resolveSiteDirForCommand(command, parsed);
+    loadEnvFiles(siteDir);
+    if (command === 'build') {
         await runBuild(siteDir);
         return;
     }
     else if (command === 'rollback') {
         // gazetta rollback <rev> [target] [site]
-        const [rev, second, third] = parsed.positional;
+        const [rev, second] = parsed.positional;
         if (!rev || !rev.startsWith('rev-')) {
             console.error(`\n  Error: rollback requires a revision id as the first argument (e.g. gazetta rollback rev-1776337441608 [target])\n`);
             process.exit(1);
             return;
         }
         rollbackRevisionId = rev;
-        const secondIsSite = second && (second.includes('/') || existsSync(join(resolve(second), 'site.yaml')));
-        if (secondIsSite) {
-            siteDir = await resolveSiteDir(second);
-            targetName = await resolveTarget(undefined, siteDir);
-        }
-        else {
-            siteDir = await resolveSiteDir(third);
-            targetName = await resolveTarget(second, siteDir);
-        }
+        const secondIsSite = second && (second.includes('/') || hasSiteConfig(resolve(second)));
+        targetName = secondIsSite ? await resolveTarget(undefined, siteDir) : await resolveTarget(second, siteDir);
     }
     else if (targetFirstCommands.has(command)) {
         // gazetta publish [target] [site]
-        const [first, second] = parsed.positional;
-        // If first arg looks like a site path (contains / or has site.yaml), it's the site
-        const firstIsSite = first && (first.includes('/') || existsSync(join(resolve(first), 'site.yaml')));
-        if (firstIsSite) {
-            siteDir = await resolveSiteDir(first);
-            targetName = await resolveTarget(undefined, siteDir);
-        }
-        else {
-            siteDir = await resolveSiteDir(second);
-            targetName = await resolveTarget(first, siteDir);
-        }
+        const [first] = parsed.positional;
+        const firstIsSite = first && (first.includes('/') || hasSiteConfig(resolve(first)));
+        targetName = firstIsSite ? await resolveTarget(undefined, siteDir) : await resolveTarget(first, siteDir);
     }
     else if (siteOnlyCommands.has(command)) {
-        siteDir = await resolveSiteDir(parsed.positional[0]);
+        // siteDir set up front; nothing more needed.
     }
     else if (command === 'translate') {
         // gazetta translate <item> --to <locale> [target]
-        // positional args after the item are the optional target name
-        siteDir = await resolveSiteDir(undefined);
-        // Find the target arg — skip the item (pages/... or fragments/...) and --to/locale flags
         const translatePositionals = parsed.positional.filter(p => !p.startsWith('pages/') && !p.startsWith('fragments/'));
         if (translatePositionals.length > 0)
             targetName = translatePositionals[0];
     }
     else if (command === 'assets') {
         // gazetta assets <subcommand> [args...] [target] [site]
-        //
-        // Subcommand layouts:
         //   assets list [target] [site]        → subcmd, target, site
         //   assets info <name> [target] [site] → subcmd, name, target, site
         //   assets reindex [target] [site]     → subcmd, target, site
+        const subcmd = parsed.positional[0];
+        const targetArg = subcmd === 'info' ? parsed.positional[2] : parsed.positional[1];
+        targetName = targetArg ? await resolveTarget(targetArg, siteDir) : undefined;
+    }
+    else if (command === 'archive') {
+        // gazetta archive <subcommand> [args...]
         //
-        // The dispatcher in the assets-cli module reads the asset name
-        // from its `args` slice; here we resolve target/site by checking
-        // the positional layout.
+        // Site/target resolution: positional after the subcommand's
+        // required args are interpreted as [target] [site]. The archive
+        // module honors `--kind=` / `--force` / `--no-keep-alias` flags
+        // separately (those don't reach the parsed.positional list per
+        // global parseArgs).
+        //
+        // Subcommand positional shapes:
+        //   archive list                              → []
+        //   archive purge <name>                      → [name]
+        //   archive restore <name>                    → [name]
+        //   archive rename <oldname> <newname>        → [oldname, newname]
+        //
+        // Remaining slots are [target] [site] in that order.
         const subcmd = parsed.positional[0];
-        if (subcmd === 'info') {
-            // info has an extra positional (the asset name) before target/site.
-            siteDir = await resolveSiteDir(parsed.positional[3]);
-            targetName = parsed.positional[2] ? await resolveTarget(parsed.positional[2], siteDir) : undefined;
-        }
-        else {
-            siteDir = await resolveSiteDir(parsed.positional[2]);
-            targetName = parsed.positional[1] ? await resolveTarget(parsed.positional[1], siteDir) : undefined;
-        }
+        const requiredArgs = subcmd === 'rename' ? 2 : subcmd === 'purge' || subcmd === 'restore' ? 1 : 0;
+        const trailingStart = 1 + requiredArgs;
+        const targetArg = parsed.positional[trailingStart];
+        targetName = targetArg ? await resolveTarget(targetArg, siteDir) : undefined;
     }
     else {
         console.error(`  Unknown command: ${command}\n`);
@@ -1863,23 +2187,6 @@ async function main() {
         process.exit(1);
         return;
     }
-    // Load .env from project root and site dir (skipped in CI)
-    if (!process.env.CI) {
-        const projectRoot = detectProjectRoot(siteDir);
-        const envDirs = projectRoot !== siteDir ? [projectRoot, siteDir] : [siteDir];
-        for (const dir of envDirs) {
-            for (const name of ['.env', '.env.local']) {
-                const envPath = join(dir, name);
-                if (existsSync(envPath)) {
-                    for (const line of readFileSync(envPath, 'utf-8').split('\n')) {
-                        const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/);
-                        if (m && !(m[1] in process.env))
-                            process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
-                    }
-                }
-            }
-        }
-    }
     switch (command) {
         case 'publish':
             await runPublish(siteDir, targetName, { force: parsed.force });
@@ -1891,7 +2198,7 @@ async function main() {
             await runDeploy(siteDir, targetName);
             break;
         case 'validate':
-            await runValidate(siteDir);
+            await runValidate(siteDir, args.slice(1));
             break;
         case 'dev':
             await runDev(siteDir, parsed.port ?? 3000);
@@ -1921,7 +2228,11 @@ async function main() {
             }
             // Resolve the content directory — translate operates on a target's filesystem.
             // Uses the specified target or falls back to the first editable target.
-            const siteYaml = yaml.load(readFileSync(join(siteDir, 'site.yaml'), 'utf-8'));
+            const siteYaml = await loadSiteManifestForCli(siteDir);
+            if (!siteYaml) {
+                console.error(`  Error: no site config found at ${siteDir}`);
+                process.exit(1);
+            }
             const { isEditable } = await import('../types.js');
             const resolvedTarget = targetName ?? Object.entries(siteYaml.targets ?? {}).find(([, cfg]) => isEditable(cfg))?.[0];
             if (!resolvedTarget) {
@@ -1930,26 +2241,27 @@ async function main() {
             }
             const targetConfig = siteYaml.targets[resolvedTarget];
             if (!targetConfig) {
-                console.error(`  Error: target "${resolvedTarget}" not found in site.yaml`);
+                console.error(`  Error: target "${resolvedTarget}" not found in site config`);
                 process.exit(1);
             }
-            const storagePath = targetConfig.storage.path ?? join('targets', resolvedTarget);
-            const contentDir = resolve(siteDir, storagePath);
+            // Translate goes through the storage provider so it works on any
+            // storage backend (filesystem / R2 / S3 / Azure). Path X — the storage
+            // provider was constructed by the operator's factory at config-eval.
+            const storage = targetConfig.storage;
             const baseName = isPage ? 'page' : 'fragment';
-            const dir = join(contentDir, itemArg);
-            const sourceFile = join(dir, `${baseName}.json`);
-            const destFile = join(dir, localeFilename(baseName, locale));
-            const fs = await import('node:fs/promises');
-            if (!existsSync(sourceFile)) {
-                console.error(`  Error: ${sourceFile} not found`);
+            const sourcePath = `${itemArg}/${baseName}.json`;
+            const destPath = `${itemArg}/${localeFilename(baseName, locale)}`;
+            if (!(await storage.exists(sourcePath))) {
+                console.error(`  Error: ${sourcePath} not found on target "${resolvedTarget}"`);
                 process.exit(1);
             }
-            if (existsSync(destFile)) {
-                console.error(`  Error: ${destFile} already exists`);
+            if (await storage.exists(destPath)) {
+                console.error(`  Error: ${destPath} already exists on target "${resolvedTarget}"`);
                 process.exit(1);
             }
-            await fs.copyFile(sourceFile, destFile);
-            console.log(`  ${c.green('✓')} Created ${relative(process.cwd(), destFile)}`);
+            const sourceContent = await storage.readFile(sourcePath);
+            await storage.writeFile(destPath, sourceContent);
+            console.log(`  ${c.green('✓')} Created ${destPath}`);
             console.log(`  Edit the file to translate the content.`);
             break;
         }
@@ -1971,12 +2283,17 @@ async function main() {
             await runAssetsSubcommand({ args: args.slice(1), siteDir, targetName });
             break;
         }
+        case 'archive': {
+            const { runArchiveSubcommand } = await import('./archive.js');
+            await runArchiveSubcommand({ args: args.slice(1), siteDir, targetName });
+            break;
+        }
     }
 }
 /**
  * Resolve site + target + config into the shape HistoryCommandContext
  * expects. Lives here rather than in cli/history.ts so the target-
- * resolution logic (site.yaml parsing, CI env handling) stays with
+ * resolution logic (site config parsing, CI env handling) stays with
  * the other CLI commands that already do it the same way.
  */
 async function resolveHistoryContext(siteDir, targetName) {