mango-cms 0.3.34 → 0.3.36

package/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { execSync, spawn } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import inquirer from 'inquirer';
@@ -14,6 +14,22 @@ import os from 'os';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// When `mango` is invoked from a global install (npm i -g mango-cms) inside a
+// project that has its own mango-cms in node_modules, defer to the project-local
+// CLI so the version pinned in package.json always wins. This is what lets users
+// type plain `mango dev` / `mango deploy` instead of prefixing with `yarn`/`npx`.
+const localCli = path.join(process.cwd(), 'node_modules', 'mango-cms', 'cli.js');
+if (fs.existsSync(localCli)) {
+    let isSelf = false;
+    try {
+        isSelf = fs.realpathSync(localCli) === fs.realpathSync(__filename);
+    } catch (e) { /* fall through and run this copy */ }
+    if (!isSelf) {
+        const result = spawnSync(process.execPath, [localCli, ...process.argv.slice(2)], { stdio: 'inherit' });
+        process.exit(result.status ?? 0);
+    }
+}
+
 const program = new Command();
 
 // Helper function to download and extract versioned src zip file
@@ -522,15 +538,16 @@ async function detectWebServer() {
 }
 
 // Helper function to generate nginx config
-function generateNginxConfig(settings, buildPath) {
+function generateNginxConfig(settings, buildPath, deployUi = false) {
     const domain = settings.mangoDomain;
     const port = settings.port || 3002;
     const frontPort = settings.frontPort || 3001;
     const uiDomain = settings.uiDomain;
     const uiPort = settings.uiPort || 3001;
 
-    // Reverse-proxy the Mango UI (Nuxt SSR server) on its own subdomain, when configured.
-    const uiServerBlock = uiDomain ? `
+    // Reverse-proxy the Mango UI (Nuxt SSR server) on its own subdomain,
+    // only when the UI is part of this deploy and a uiDomain is configured.
+    const uiServerBlock = (deployUi && uiDomain) ? `
 server {
     server_name ${uiDomain};
 
@@ -617,15 +634,16 @@ ${uiServerBlock}`;
 }
 
 // Helper function to generate apache config
-function generateApacheConfig(settings, buildPath) {
+function generateApacheConfig(settings, buildPath, deployUi = false) {
     const domain = settings.mangoDomain;
     const port = settings.port || 3002;
     const frontPort = settings.frontPort || 3001;
     const uiDomain = settings.uiDomain;
     const uiPort = settings.uiPort || 3001;
 
-    // Reverse-proxy the Mango UI (Nuxt SSR server) on its own subdomain, when configured.
-    const uiVirtualHost = uiDomain ? `
+    // Reverse-proxy the Mango UI (Nuxt SSR server) on its own subdomain,
+    // only when the UI is part of this deploy and a uiDomain is configured.
+    const uiVirtualHost = (deployUi && uiDomain) ? `
 <VirtualHost *:80>
     ServerName ${uiDomain}
 
@@ -697,7 +715,7 @@ ${uiVirtualHost}`;
 }
 
 // Helper function to configure web server
-async function configureWebServer(settings, buildPath) {
+async function configureWebServer(settings, buildPath, deployUi = false) {
     let webServer = await detectWebServer();
 
     if (!webServer) {
@@ -713,8 +731,8 @@ async function configureWebServer(settings, buildPath) {
     }
 
     const config = webServer === 'nginx' ?
-        generateNginxConfig(settings, buildPath) :
-        generateApacheConfig(settings, buildPath);
+        generateNginxConfig(settings, buildPath, deployUi) :
+        generateApacheConfig(settings, buildPath, deployUi);
 
     const configPath = webServer === 'nginx' ?
         `/etc/nginx/sites-available/${settings.database.toLowerCase()}` :
@@ -796,7 +814,9 @@ async function managePM2Process(settings) {
     }
 }
 
-// Helper function to build and (re)start the Mango UI (Nuxt) under PM2
+// Helper function to build and (re)start the Mango UI (Nuxt) under PM2.
+// Only called when the UI deploy is explicitly enabled (--ui flag or
+// "deployUi": true in settings.json) — the admin UI is opt-in on deploy.
 async function manageUiPM2Process(settings, mangoCmsRoot, userProjectRoot) {
     if (!settings.uiDomain) {
         console.log('No uiDomain configured, skipping Mango UI deploy.');
@@ -843,29 +863,39 @@ async function manageUiPM2Process(settings, mangoCmsRoot, userProjectRoot) {
 program
     .command('deploy')
     .description('Build and deploy Mango CMS using PM2')
-    .action(async () => {
+    .option('--ui', 'also build and deploy the Mango admin UI (off by default; or set "deployUi": true in settings.json)')
+    .action(async (options) => {
         try {
             const configPath = path.join(process.cwd(), 'mango/config/settings.json');
             const settings = JSON.parse(fs.readFileSync(configPath, 'utf8'));
             const mangoCmsRoot = path.resolve(__dirname);
             const userProjectRoot = process.cwd();
 
+            // The admin UI is opt-in: deployed only with --ui or "deployUi": true.
+            const deployUi = Boolean(options.ui || settings.deployUi);
+
             // Run build command
             console.log('Building Mango CMS...');
             execSync('npm run mango build', { stdio: 'inherit' });
 
-            // Make sure a UI bundle is available for deploy.
-            await ensureUiExists(mangoCmsRoot);
+            // Make sure a UI bundle is available for deploy (only when deploying it).
+            if (deployUi) {
+                await ensureUiExists(mangoCmsRoot);
+            }
 
             // Check if PM2 is installed
             if (await checkPM2()) {
                 await managePM2Process(settings);
-                await manageUiPM2Process(settings, mangoCmsRoot, userProjectRoot);
+                if (deployUi) {
+                    await manageUiPM2Process(settings, mangoCmsRoot, userProjectRoot);
+                } else {
+                    console.log('Skipping Mango UI deploy (opt in with "mango deploy --ui" or "deployUi": true in settings.json).');
+                }
 
                 // Configure web server
                 const buildPath = path.join(process.cwd(), 'build');
                 try {
-                    await configureWebServer(settings, buildPath);
+                    await configureWebServer(settings, buildPath, deployUi);
                 } catch (error) {
                     console.warn('Warning: Could not configure web server:', error.message);
                     console.warn('You may need to configure your web server manually.');
@@ -881,8 +911,9 @@ program
 
 program
     .command('launch')
-    .description('One-shot server deploy: git pull, install, build the site, and deploy backend + UI')
-    .action(async () => {
+    .description('One-shot server deploy: git pull, install, build the site, and deploy the backend (add --ui for the admin UI)')
+    .option('--ui', 'also build and deploy the Mango admin UI (off by default; or set "deployUi": true in settings.json)')
+    .action(async (options) => {
         try {
             const cwd = process.cwd();
             const useYarn = fs.existsSync(path.join(cwd, 'yarn.lock'));
@@ -909,12 +940,14 @@ program
                 console.log('\n→ Skipping site build (no "build" script found)');
             }
 
-            // 4. Deploy backend + UI + web server config via the freshly installed mango.
-            //    `mango deploy` builds the backend, (re)starts PM2 for {db}-mango, {db}
-            //    and {db}-ui, and writes the nginx/apache blocks for all three domains.
-            run('Deploying backend + UI', 'npx mango deploy');
+            // 4. Deploy backend (+ UI when opted in) + web server config via the
+            //    freshly installed mango. `mango deploy` builds the backend and
+            //    (re)starts PM2 for {db}-mango and {db}; with --ui it also builds
+            //    the admin UI, starts {db}-ui, and writes its web server block.
+            const deployCmd = options.ui ? 'npx mango deploy --ui' : 'npx mango deploy';
+            run(options.ui ? 'Deploying backend + UI' : 'Deploying backend', deployCmd);
 
-            console.log('\n✨ Launch complete! Backend, site, and UI are deployed.');
+            console.log(`\n✨ Launch complete! Backend and site are deployed${options.ui ? ', along with the admin UI' : ''}.`);
         } catch (error) {
             console.error('\nLaunch failed:', error.message);
             process.exit(1);
@@ -1210,4 +1243,61 @@ To stop: mango proxy stop
         }
     });
 
+// --- Vibe Orchestrator Command (HAP-1253) ---
+// Runs the bundled vibe-orchestrator straight from the installed mango package —
+// no copied source. The orchestrator drives Claude Code headless in each branch
+// worktree, streams the chat to the ⌘K drawer, and verifies the owner token that
+// Mango mints (shared VIBE_ORCH_TOKEN_SECRET). It is dependency-free (node:http
+// only), so it ships inside lib/ and runs in-process from this CLI.
+//
+// Env contract:
+//   VIBE_ORCH_TOKEN_SECRET  (required for owner auth — UNSET ⇒ fails closed, 503)
+//   VIBE_STAGING_ROOT       root holding each <site> clone (default /root/Staging)
+//   VIBE_ALLOWED_SITES      comma-list of site slugs (defaults to this project's
+//                           siteName when run from a mango project root)
+//   CLAUDE_CODE_OAUTH_TOKEN or ~/.claude/.credentials.json  (Claude credentials)
+//   VIBE_ORCH_PORT          loopback listen port (default 7130; --port overrides)
+// See lib/vibe-orchestrator/README.md for the full contract.
+program
+    .command('vibe-orchestrator')
+    .description('Run the bundled Vibe orchestrator (Claude Code headless → ⌘K drawer). '
+        + 'Env: VIBE_ORCH_TOKEN_SECRET (required), VIBE_STAGING_ROOT, VIBE_ALLOWED_SITES, '
+        + 'CLAUDE_CODE_OAUTH_TOKEN (or ~/.claude). See lib/vibe-orchestrator/README.md.')
+    .option('-p, --port <port>', 'loopback port to listen on (overrides VIBE_ORCH_PORT)')
+    .action(async (options) => {
+        const serverPath = path.join(__dirname, 'lib', 'vibe-orchestrator', 'server.js');
+        if (!fs.existsSync(serverPath)) {
+            console.error(`Error: bundled orchestrator not found at ${serverPath}`);
+            process.exit(1);
+        }
+
+        const env = { ...process.env };
+        if (options.port) env.VIBE_ORCH_PORT = String(options.port);
+
+        // Convenience: when run from a mango project root and the site allow-list
+        // isn't set explicitly, default it to this project's siteName so the
+        // orchestrator only touches this site's clones. Explicit env always wins.
+        if (!env.VIBE_ALLOWED_SITES) {
+            const settingsPath = path.join(process.cwd(), 'mango/config/settings.json');
+            try {
+                if (fs.existsSync(settingsPath)) {
+                    const { siteName } = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+                    if (siteName) env.VIBE_ALLOWED_SITES = siteName;
+                }
+            } catch (e) {
+                console.warn(`[vibe-orchestrator] could not read siteName from settings.json: ${e.message}`);
+            }
+        }
+
+        console.log(`[vibe-orchestrator] launching from ${serverPath}`);
+        const child = spawn(process.execPath, [serverPath], { stdio: 'inherit', env });
+        const forward = (sig) => { try { child.kill(sig); } catch { /* already gone */ } };
+        process.on('SIGINT', () => forward('SIGINT'));
+        process.on('SIGTERM', () => forward('SIGTERM'));
+        child.on('exit', (code, signal) => {
+            if (signal) process.kill(process.pid, signal);
+            else process.exit(code ?? 0);
+        });
+    });
+
 program.parse(process.argv);

package/default/infra/vibe/README.md

@@ -0,0 +1,43 @@
+# Vibe infra templates
+
+Default, environment-agnostic templates for the **environment-specific layer** of
+the Vibe drop-in (HAP-1255). The rest of Vibe is portable — you `npm`-upgrade
+mango-cms for the server half, flip `settings.vibe.enabled`, and consume the
+mango-ui Vibe module for the front. These templates cover the one part that can't
+be packaged: the box's reverse proxy, process supervision, and DNS.
+
+Fill in the `__PLACEHOLDERS__` and install. Nothing here is read automatically by
+Mango — they're starting points you copy to `/etc/...` (or your pm2 setup).
+
+| File | What it sets up |
+| --- | --- |
+| `nginx-vibe-staging.conf.template` | nginx vhost: the staging host **and** every `<branch>--<host>` (wildcard `server_name`) → the loopback staging gateway, with the Vite HMR WebSocket upgrade. |
+| `nginx-vibe-orchestrator.conf.template` | nginx vhost: the orchestrator host → loopback `:7130`, tuned for SSE (no buffering, long read timeout). |
+| `vibe-gateway.service` | systemd unit running `lib/staging-gateway.js` from the installed package. |
+| `vibe-orchestrator.service` | systemd unit running `lib/vibe-orchestrator/server.js` from the installed package (secrets via an `EnvironmentFile`). |
+| `ecosystem.vibe.config.cjs` | pm2 alternative that launches both processes. |
+| `cloudflare.ini.template` | the scoped `Zone:DNS:Edit` token file for `settings.vibe.gatewayDns` (per-branch DNS automation). |
+| `vibe.env.template` | the front-build `VITE_*` vars (`VITE_VIBE_SHELL`, `VITE_ORCH_URL`, …). |
+
+## Topology these templates assume
+
+```
+  Browser
+   │  page + HMR  → https://<branch>--staging-vibe.example.com ─┐
+   │  ⌘K chat     → https://vibe-orch.example.com ─────────────┐│
+   ▼                                                           ││
+  nginx ──(staging vhost)──► staging gateway :7123 ────────────┘│  demux <branch>--host
+   │                              │                              │  ├─► per-branch dev server (portRange)
+   │                              └──────────────────────────────┘  └─► shared front :7121 (no branch signal)
+   └────(orchestrator vhost)──► vibe-orchestrator :7130 ──► Claude Code headless in the worktree
+                                                            verifies owner token (VIBE_ORCH_TOKEN_SECRET,
+  Mango backend :7122 ── mints owner token, owns                    shared with Mango)
+   /system/vibe/staging-resolve · /branches · /endpoints/vibe/token
+```
+
+Default ports (all overridable): backend `7122`, shared front `7121`, gateway
+`7123`, orchestrator `7130`, per-branch dev servers from `settings.vibe.portRange`
+(default `[7200, 7399]`). Keep the gateway/orchestrator on loopback; nginx is the
+only public listener.
+
+**Full step-by-step:** see [`docs/VIBE_ACTIVATION.md`](../../../docs/VIBE_ACTIVATION.md).

package/default/infra/vibe/cloudflare.ini.template

@@ -0,0 +1,26 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Cloudflare credentials for settings.vibe.gatewayDns
+#
+# When settings.vibe.gatewayDns.enabled = true, Mango's per-branch DNS service
+# creates/cleans a proxied DNS record for each `<branch>--<staging-host>` as
+# branches are provisioned and reaped — so you do NOT have to manage a wildcard
+# record by hand. Point settings.vibe.gatewayDns.credentialsFile at a copy of
+# this file (chmod 600, OUTSIDE the repo).
+#
+# This file holds ONLY the token. The zone + control host come from
+# settings.vibe.gatewayDns ({ zone, controlHost }), not from here.
+#
+# The service resolves the token as (first hit wins):
+#   1. env  CF_API_TOKEN
+#   2. the `dns_cloudflare_api_token = …` line below (certbot-style)
+#   3. a file whose entire contents are the bare token
+#
+# The token needs Zone:DNS:Edit on the single zone in settings.vibe.gatewayDns.zone.
+# Create it: Cloudflare → My Profile → API Tokens → Create Token
+#            → "Edit zone DNS" template → scope to your zone.
+#
+# If the feature is enabled but no token resolves, per-branch DNS is logged and
+# DISABLED (provisioning still succeeds) — it never crashes a dev box.
+# ─────────────────────────────────────────────────────────────────────────────
+
+dns_cloudflare_api_token = __CF_ZONE_DNS_EDIT_TOKEN__

package/default/infra/vibe/ecosystem.vibe.config.cjs

@@ -0,0 +1,44 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// pm2 ecosystem — Vibe gateway + orchestrator (alternative to the systemd units)
+//
+//   pm2 start ecosystem.vibe.config.cjs && pm2 save
+//
+// Both processes run the bundled code from node_modules/mango-cms — no copied
+// source. Replace the __PLACEHOLDERS__ (or export them in the shell first).
+// Keep secrets OUT of source control: set VIBE_ORCH_TOKEN_SECRET and the Claude
+// credential in the environment that launches pm2, not inline here.
+// ─────────────────────────────────────────────────────────────────────────────
+const APP_DIR = process.env.VIBE_APP_DIR || '__APP_DIR__';
+
+module.exports = {
+  apps: [
+    {
+      name: 'vibe-gateway',
+      script: `${APP_DIR}/node_modules/mango-cms/lib/staging-gateway.js`,
+      cwd: APP_DIR,
+      env: {
+        BACKEND_PORT: process.env.BACKEND_PORT || '__BACKEND_PORT__', // e.g. 7122
+        LISTEN_PORT: process.env.GATEWAY_PORT || '__GATEWAY_PORT__',  // e.g. 7123
+        LISTEN_HOST: '127.0.0.1',
+        FALLBACK_PORT: process.env.FALLBACK_PORT || '__FALLBACK_PORT__', // e.g. 7121
+        STAGING_DOMAIN: process.env.STAGING_HOST || '__STAGING_HOST__',
+        READINESS_TIMEOUT_MS: '25000',
+      },
+    },
+    {
+      name: 'vibe-orchestrator',
+      script: `${APP_DIR}/node_modules/mango-cms/lib/vibe-orchestrator/server.js`,
+      cwd: APP_DIR,
+      env: {
+        VIBE_ORCH_PORT: process.env.VIBE_ORCH_PORT || '__ORCH_PORT__',     // e.g. 7130
+        VIBE_STAGING_ROOT: process.env.VIBE_STAGING_ROOT || '__STAGING_ROOT__',
+        VIBE_ALLOWED_SITES: process.env.VIBE_ALLOWED_SITES || '__ALLOWED_SITES__',
+        VIBE_ALLOWED_ORIGINS: process.env.VIBE_ALLOWED_ORIGINS || '__ALLOWED_ORIGINS__',
+        // REQUIRED, set in the launching shell — unset ⇒ orchestrator 503s:
+        VIBE_ORCH_TOKEN_SECRET: process.env.VIBE_ORCH_TOKEN_SECRET,
+        // One of these for live runs (else /health reports canRunLive:false):
+        CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN,
+      },
+    },
+  ],
+};

package/default/infra/vibe/nginx-vibe-orchestrator.conf.template

@@ -0,0 +1,50 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Vibe orchestrator — nginx vhost template
+#
+# Fronts the bundled vibe-orchestrator (`mango vibe-orchestrator`, loopback
+# :7130). The browser's ⌘K drawer talks to this host (VITE_ORCH_URL). The
+# orchestrator binds loopback only and verifies a server-minted owner token on
+# every route except GET /health, so nginx just needs to forward and NOT buffer
+# (the /prompt response is a long-lived SSE stream).
+#
+# Placeholders to replace:
+#   __ORCH_HOST__        public orchestrator host, e.g. vibe-orch.example.com
+#   __ORCH_PORT__        loopback port (VIBE_ORCH_PORT; default 7130)
+#   __TLS_CERT__ / __TLS_KEY__   cert covering __ORCH_HOST__
+#
+# CORS is handled by the orchestrator itself (VIBE_ALLOWED_ORIGINS) — do not add
+# add_header Access-Control-* here or you will double up the headers.
+# ─────────────────────────────────────────────────────────────────────────────
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name __ORCH_HOST__;
+
+    ssl_certificate     __TLS_CERT__;
+    ssl_certificate_key __TLS_KEY__;
+
+    client_max_body_size 25m;   # screenshot + attachment uploads ride on /prompt
+
+    location / {
+        proxy_pass http://127.0.0.1:__ORCH_PORT__;
+        proxy_http_version 1.1;
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # SSE: stream tokens to the drawer as they arrive, never buffer.
+        proxy_buffering    off;
+        proxy_cache        off;
+        proxy_read_timeout 3600s;   # a long agent turn can run for minutes
+        chunked_transfer_encoding on;
+    }
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __ORCH_HOST__;
+    return 301 https://$host$request_uri;
+}

package/default/infra/vibe/nginx-vibe-staging.conf.template

@@ -0,0 +1,73 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Vibe staging gateway — nginx vhost template
+#
+# Fronts the Mango Vibe staging surface. nginx terminates the public hostname(s)
+# and proxy_passes to the loopback **staging gateway** process
+# (`node node_modules/mango-cms/lib/staging-gateway.js`, default :7123), which
+# demuxes by selected branch into each per-branch dev server, and falls back to
+# the shared front for any request without a deliberate branch signal.
+#
+# This single server block matches BOTH:
+#   • the base staging host        →  staging-vibe.example.com
+#   • every per-branch hostname     →  <branch>--staging-vibe.example.com
+# because the gateway parses `<branch>--<host>` itself. The wildcard server_name
+# means you only manage ONE vhost no matter how many branches exist.
+#
+# Placeholders to replace:
+#   __STAGING_HOST__     base staging host, e.g. staging-vibe.example.com
+#   __GATEWAY_PORT__     loopback port the gateway binds (settings/LISTEN_PORT; default 7123)
+#   __TLS_CERT__ / __TLS_KEY__   wildcard cert covering *.__STAGING_HOST__ and __STAGING_HOST__
+#                        (a Cloudflare Origin cert is simplest when the zone is proxied).
+#
+# DNS: point __STAGING_HOST__ at this box, and EITHER a wildcard
+# `*.__STAGING_HOST__` record OR enable settings.vibe.gatewayDns so Mango creates
+# each `<branch>--__STAGING_HOST__` record on demand (see cloudflare.ini.template).
+# ─────────────────────────────────────────────────────────────────────────────
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    # Base host AND every per-branch host. The leading dot matches the apex too.
+    server_name __STAGING_HOST__ *.__STAGING_HOST__;
+
+    ssl_certificate     __TLS_CERT__;
+    ssl_certificate_key __TLS_KEY__;
+
+    # Vite dev assets are large and the gateway streams them; don't buffer.
+    proxy_buffering off;
+    client_max_body_size 25m;
+
+    location / {
+        proxy_pass http://127.0.0.1:__GATEWAY_PORT__;
+        proxy_http_version 1.1;
+
+        # Preserve the real Host so the gateway can read `<branch>--<host>`.
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Vite HMR WebSocket upgrade — required or the preview never hot-reloads.
+        proxy_set_header Upgrade    $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        # Cold per-branch boots can take a few seconds (the gateway shows a
+        # branded "starting" page via READINESS_TIMEOUT_MS); keep nginx patient.
+        proxy_read_timeout  120s;
+        proxy_send_timeout  120s;
+    }
+}
+
+# Optional: redirect plain HTTP to HTTPS.
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __STAGING_HOST__ *.__STAGING_HOST__;
+    return 301 https://$host$request_uri;
+}

package/default/infra/vibe/vibe-gateway.service

@@ -0,0 +1,38 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# systemd unit — Vibe staging gateway
+#
+# Runs the bundled gateway from the installed mango-cms package (no copied
+# source). It fronts the per-branch dev servers and the shared front.
+# Install:
+#   cp vibe-gateway.service /etc/systemd/system/
+#   # edit the placeholders below, then:
+#   systemctl daemon-reload && systemctl enable --now vibe-gateway
+#
+# Placeholders:
+#   __APP_DIR__       project root that contains node_modules/mango-cms
+#   __RUN_USER__      unix user to run as
+#   __BACKEND_PORT__  Mango port owning /system/vibe/staging-resolve (e.g. 7122)
+#   __GATEWAY_PORT__  loopback port to bind (must match the nginx vhost; e.g. 7123)
+#   __FALLBACK_PORT__ shared front port for un-signaled requests (e.g. 7121)
+#   __STAGING_HOST__  exact staging host, e.g. staging-vibe.example.com
+# ─────────────────────────────────────────────────────────────────────────────
+[Unit]
+Description=Mango Vibe staging gateway
+After=network.target
+
+[Service]
+Type=simple
+User=__RUN_USER__
+WorkingDirectory=__APP_DIR__
+Environment=BACKEND_PORT=__BACKEND_PORT__
+Environment=LISTEN_PORT=__GATEWAY_PORT__
+Environment=LISTEN_HOST=127.0.0.1
+Environment=FALLBACK_PORT=__FALLBACK_PORT__
+Environment=STAGING_DOMAIN=__STAGING_HOST__
+Environment=READINESS_TIMEOUT_MS=25000
+ExecStart=/usr/bin/node __APP_DIR__/node_modules/mango-cms/lib/staging-gateway.js
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

package/default/infra/vibe/vibe-orchestrator.service

@@ -0,0 +1,44 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# systemd unit — Vibe orchestrator
+#
+# Runs the bundled orchestrator from the installed mango-cms package (no copied
+# source). Drives Claude Code headless and verifies the owner token Mango mints.
+# Install:
+#   cp vibe-orchestrator.service /etc/systemd/system/
+#   # edit the placeholders below, then:
+#   systemctl daemon-reload && systemctl enable --now vibe-orchestrator
+#
+# Placeholders:
+#   __APP_DIR__         project root that contains node_modules/mango-cms
+#   __RUN_USER__        unix user (its $HOME/.claude holds Claude credentials)
+#   __ORCH_PORT__       loopback port (must match the nginx vhost; e.g. 7130)
+#   __STAGING_ROOT__    root holding each <site> clone the orchestrator edits
+#   __ALLOWED_SITES__   comma-list of site slugs (e.g. mysite)
+#   __ALLOWED_ORIGINS__ comma-list of browser origins, e.g.
+#                       https://staging-vibe.example.com,https://example.com
+#
+# Secrets — set VIBE_ORCH_TOKEN_SECRET (MUST equal Mango's settings.vibe secret)
+# and the Claude credential out of band (an EnvironmentFile is shown below so the
+# secret never lives in this unit). Unset token secret ⇒ orchestrator fails
+# closed (every gated route returns 503).
+# ─────────────────────────────────────────────────────────────────────────────
+[Unit]
+Description=Mango Vibe orchestrator (Claude Code headless)
+After=network.target
+
+[Service]
+Type=simple
+User=__RUN_USER__
+WorkingDirectory=__APP_DIR__
+Environment=VIBE_ORCH_PORT=__ORCH_PORT__
+Environment=VIBE_STAGING_ROOT=__STAGING_ROOT__
+Environment=VIBE_ALLOWED_SITES=__ALLOWED_SITES__
+Environment=VIBE_ALLOWED_ORIGINS=__ALLOWED_ORIGINS__
+# Secrets live here, mode 600, root-owned (VIBE_ORCH_TOKEN_SECRET=..., CLAUDE_CODE_OAUTH_TOKEN=...):
+EnvironmentFile=/etc/vibe/orchestrator.env
+ExecStart=/usr/bin/node __APP_DIR__/node_modules/mango-cms/lib/vibe-orchestrator/server.js
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

package/default/infra/vibe/vibe.env.template

@@ -0,0 +1,24 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Vibe front-build environment (Vite)
+#
+# These VITE_* vars are read at BUILD time of the project's front (the mango-ui
+# chrome that renders <VibeLauncher/>). Set them in the front's build env so the
+# themed Vibe button appears and the drawer points at your orchestrator.
+# (See default/infra/vibe/vibe-orchestrator.service for the SERVER-side secrets.)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Master switch for the Vibe shell + button. Without this the launcher renders
+# nothing, so a plain Mango build is unaffected. (helpers/vibe/orchestrator.js →
+# vibeShellEnabled())
+VITE_VIBE_SHELL=true
+
+# Public URL of the orchestrator vhost (nginx-vibe-orchestrator.conf.template).
+VITE_ORCH_URL=https://vibe-orch.example.com
+
+# Site slug the drawer edits (defaults to settings.siteName when unset).
+VITE_ORCH_SITE=mysite
+
+# OPTIONAL — encode the branch in the hostname instead of a cookie so it stays
+# sticky across the iframe's sub-resources + HMR WebSocket. Must match the
+# wildcard the staging gateway/nginx serve. `{branch}` is substituted live.
+VITE_VIBE_SHELL_HOST_TEMPLATE={branch}--staging-vibe.example.com

package/default/mango/config/settings.json

@@ -19,6 +19,11 @@
 	"mongoURI": "mongodb://127.0.0.1:27017",
 	"database": "exampleMongoDB",
 
+	"s3AccessKeyId": null,
+	"s3AccessKeySecret": null,
+	"s3Region": null,
+	"s3Bucket": "exampleBucket",
+
 	"emailProvider": "resend",
     "emailFrom": "Example <info@example.com>",
 	"resendKey": null,
@@ -29,5 +34,39 @@
 	"algoliaSearchKey": null,
 	"algoliaIndex": null,
 
-	"corsOrigins": "*"
+	"corsOrigins": "*",
+
+	"_vibeDoc": "Optional in-page Vibe coding feature (HAP-1096). DISABLED by default (vibe.enabled = false): with this block inert the site behaves exactly as a normal Mango project. To turn it on, set vibe.enabled = true and configure workspaceRoot + (for the staging gateway) gatewayDns. Every key is documented inline under vibe._doc. settings.json is strict JSON so guidance lives in these _doc fields rather than comments. The block is validated at boot by validateVibeConfig — an invalid value throws with a clear message. See default/vite.config.js for the matching front-end resilient config loader a Vibe project needs.",
+
+	"vibe": {
+		"_doc": {
+			"enabled": "Master switch. false = feature inert (site behaves as a normal Mango project). Set true to enable per-branch Vibe workspaces.",
+			"portRange": "[min, max] inclusive pool of TCP ports the provisioner allocates to per-branch dev servers. Must not overlap reserved ports 6121, 6122, 7121, 7122, 7130.",
+			"workspaceRoot": "Absolute, writable directory where per-branch git worktrees and their dev servers are created.",
+			"idleTimeoutMs": "Milliseconds of inactivity before the idle reaper tears a workspace down. Default 1800000 (30 min).",
+			"reaperIntervalMs": "How often (ms) the idle reaper sweeps for workspaces past idleTimeoutMs. Default 60000 (1 min).",
+			"allowedRoles": "User roles permitted to open the Vibe panel and spawn workspaces. Non-empty array of role-name strings.",
+			"defaultBranch": "Branch a request resolves to when none travels with it (e.g. a cold load before a branch is picked).",
+			"devServerCommand": "Command the provisioner spawns inside each worktree to start its front dev server. cwd = the worktree; the allocated port is passed in PORT/MANGO_PORT.",
+			"sessionCookieDomain": "Optional shared parent domain (e.g. \".example.com\") so the session cookie rides across the gateway and api subdomains. null = host-scoped (default).",
+			"sessionCookieName": "Optional override for the express-session cookie name. Pair with sessionCookieDomain to stop staging/prod under one parent from colliding. null = default name.",
+			"gatewayDns": "Optional per-branch Cloudflare DNS lifecycle for the staging gateway: { enabled, zone, controlHost, credentialsFile }. enabled = false means no DNS automation (default)."
+		},
+		"enabled": false,
+		"portRange": [7200, 7399],
+		"workspaceRoot": "/Staging",
+		"idleTimeoutMs": 1800000,
+		"reaperIntervalMs": 60000,
+		"allowedRoles": ["admin", "owner"],
+		"defaultBranch": "main",
+		"devServerCommand": "mango dev",
+		"sessionCookieDomain": null,
+		"sessionCookieName": null,
+		"gatewayDns": {
+			"enabled": false,
+			"zone": "example.com",
+			"controlHost": "vibe.example.com",
+			"credentialsFile": "/path/to/.cloudflare.ini"
+		}
+	}
 }

package/default/package.json

@@ -24,7 +24,7 @@
         "dayjs": "^1.10.7",
         "express": "^4.18.1",
         "google-maps": "^4.3.3",
-        "mango-cms": "^0.3.31",
+        "mango-cms": "^0.3.36",
         "mapbox-gl": "^2.7.0",
         "vite": "^6.2.2",
         "vue": "^3.2.37",