@meshxdata/fops 0.1.31 → 0.1.34

package/src/plugins/bundled/fops-plugin-foundation/index.js

@@ -41,11 +41,31 @@ export function register(api) {
 
   api.registerCommand((program) => {
     program
-      .command("apply <file>")
-      .description("Apply a landscape file (FCL/HCL/YAML) — supports stack: and mesh: blocks")
+      .command("apply [file]")
+      .description("Apply a landscape file (FCL/HCL/YAML) — supports stack: and mesh: blocks. Use - or omit to read from stdin.")
       .option("--dry-run", "Preview changes without applying")
       .option("--no-restart", "Don't restart the stack after applying changes")
       .action(async (file, opts) => {
+        const fromStdin = !file || file === "-";
+
+        if (fromStdin) {
+          // Read YAML from stdin
+          const chunks = [];
+          for await (const chunk of process.stdin) chunks.push(chunk);
+          const content = Buffer.concat(chunks).toString("utf8").trim();
+          if (!content) {
+            console.log(WARN("\n  No content received on stdin\n"));
+            return;
+          }
+          const { parseYamlContent, applyLandscape } = await import("./lib/apply.js");
+          const { operations, fileName } = parseYamlContent(content);
+          const c = new FoundationClient(api.config, {
+            getCredentials: typeof api.getFoundationCredentials === "function" ? api.getFoundationCredentials : undefined,
+          });
+          await applyLandscape(c, operations, { dryRun: opts.dryRun, fileName });
+          return;
+        }
+
         const resolved = path.resolve(file);
         const ext = path.extname(resolved).toLowerCase();
 
@@ -254,6 +274,1698 @@ export function register(api) {
           process.exit(1);
         }
       });
+
+    // ── align ─────────────────────────────────────────────────────────────
+    foundation
+      .command("align <source> [target]")
+      .description("Align source column names to target schema columns (exact → embedding → levenshtein)")
+      .option("--threshold <number>", "Similarity threshold 0–1 (default 0.7)", "0.7")
+      .option("--drop-unmapped-source", "Drop source columns with no match (default: keep)")
+      .option("--fill-missing-expected", "Add unmapped expected columns with empty values to preserve schema")
+      .option("--output <file>", "Apply the transformation and write transformed CSV(s) here")
+      .option("--create <name>", "Create a new Foundation DataObject entity after applying")
+      .option("--overwrite <identifier>", "Update config of an existing Foundation DataObject after applying")
+      .option("--no-semantic", "Skip MiniLM embeddings — use exact + Levenshtein only (avoids ONNX load in scripts)")
+      .option("--fcl [file]", "Write a landscape YAML patch with the rename_column pipeline step (omit file → stdout)")
+      .option("--json", "Output raw JSON")
+      .action(async (source, target, opts) => {
+        const { alignColumns } = await import("./lib/align.js");
+        const { fetchEntityColumns } = await import("./lib/tools-write.js");
+        const { statSync, readdirSync, readFileSync, writeFileSync } = await import("node:fs");
+        const threshold = Number.parseFloat(opts.threshold) || 0.7;
+        const dropUnmappedSource = !!opts.dropUnmappedSource;
+        const fillMissingExpected = !!opts.fillMissingExpected;
+
+        // Resolve source columns — directory of CSVs, comma-separated names, or entity identifier
+        const isDirectory = (s) => { try { return statSync(s).isDirectory(); } catch { return false; } };
+        const isFile = (s) => { try { return statSync(s).isFile(); } catch { return false; } };
+        const isIdentifier = (s) => s && !/,/.test(s) && !/\s/.test(s.trim());
+
+        let sourceCols;
+        let sourceCsvFiles = []; // track actual CSV paths for --output
+        if (isDirectory(source)) {
+          const csvFiles = readdirSync(source).filter((f) => /\.csv$/i.test(f));
+          if (csvFiles.length === 0) {
+            console.error(ERR(`  ✗ No CSV files found in: ${source}`));
+            process.exit(1);
+          }
+          sourceCsvFiles = csvFiles.map((f) => path.join(source, f));
+          const seen = new Set();
+          for (const file of sourceCsvFiles) {
+            try {
+              const firstLine = readFileSync(file, "utf8").split("\n")[0]?.trim();
+              if (!firstLine) continue;
+              for (const col of firstLine.split(",").map((c) => c.trim().replace(/^["']|["']$/g, ""))) {
+                if (col) seen.add(col);
+              }
+            } catch { /* skip unreadable file */ }
+          }
+          sourceCols = [...seen];
+          console.log(DIM(`  Reading ${csvFiles.length} CSV file(s) from ${source} — ${sourceCols.length} unique columns`));
+        } else if (isFile(source)) {
+          sourceCsvFiles = [path.resolve(source)];
+          const firstLine = readFileSync(source, "utf8").split("\n")[0]?.trim();
+          sourceCols = firstLine ? firstLine.split(",").map((c) => c.trim().replace(/^["']|["']$/g, "")).filter(Boolean) : [];
+          console.log(DIM(`  Reading ${source} — ${sourceCols.length} columns`));
+        } else if (isIdentifier(source)) {
+          sourceCols = await fetchEntityColumns(client, source.trim(), "data_object");
+        } else {
+          sourceCols = source.split(",").map((c) => c.trim()).filter(Boolean);
+        }
+        if (!sourceCols || sourceCols.length === 0) {
+          console.error(ERR(`  ✗ Could not resolve source columns from: ${source}`));
+          process.exit(1);
+        }
+
+        // Get embeddings service (used for both target inference and column alignment)
+        let embSvc;
+        try {
+          embSvc = typeof api.getService === "function" ? api.getService("embeddings:search") : null;
+        } catch { /* embeddings not available */ }
+        const embedTexts = (!opts.noSemantic && embSvc?.embedTexts) ? embSvc.embedTexts.bind(embSvc) : null;
+
+        // Resolve target — explicit arg, or auto-infer by schema column overlap
+        let targetCols;
+        let resolvedTarget = target;
+        if (!target) {
+          let dpIdentifier = null;
+          let dpName = null;
+          try {
+            const res = await client.get("/data/data_product/list?per_page=200");
+            const { parseListResponse: parseDP } = await import("./lib/api-spec.js");
+            const products = parseDP(res).filter((p) => p.identifier);
+            if (products.length === 0) {
+              console.error(ERR("  ✗ No data products found. Specify a target explicitly."));
+              process.exit(1);
+            }
+            if (products.length === 1) {
+              dpIdentifier = products[0].identifier;
+              dpName = products[0].name || dpIdentifier;
+            } else {
+              // Fetch all schemas concurrently
+              const withCols = await Promise.all(products.map(async (p) => {
+                try {
+                  const cols = await fetchEntityColumns(client, p.identifier, "data_product");
+                  return { id: p.identifier, name: p.name || p.identifier, cols: cols || [] };
+                } catch {
+                  return { id: p.identifier, name: p.name || p.identifier, cols: [] };
+                }
+              }));
+              const candidates = withCols.filter((p) => p.cols.length > 0);
+              if (candidates.length === 0) {
+                console.error(ERR("  ✗ Could not resolve target schemas. Specify a target explicitly."));
+                process.exit(1);
+              }
+
+              // Signal 1: Jaccard on normalised column names
+              const srcNorm = sourceCols.map((c) => c.toLowerCase().replace(/[^a-z0-9]/g, ""));
+              const srcSet = new Set(srcNorm);
+              const jaccardScore = (cols) => {
+                const expSet = new Set(cols.map((c) => c.toLowerCase().replace(/[^a-z0-9]/g, "")));
+                let inter = 0;
+                for (const c of srcSet) if (expSet.has(c)) inter++;
+                const union = srcSet.size + expSet.size - inter;
+                return union > 0 ? inter / union : 0;
+              };
+
+              // Signal 2: MiniLM bipartite column match (when embeddings available)
+              let embScores = null;
+              if (typeof embedTexts === "function") {
+                try {
+                  // Plain word split for target selection — no suffix boost needed here.
+                  // Suffix boost is for within-product mapping; here it would make
+                  // any _id column (cust_id, span_id, user_id) equally similar.
+                  const toHuman = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim() || s;
+                  const allRefCols = candidates.flatMap((p) => p.cols);
+                  const allTexts = [...sourceCols.map(toHuman), ...allRefCols.map(toHuman)];
+                  const allVecs = await embedTexts(allTexts);
+                  if (allVecs?.length === allTexts.length) {
+                    const srcVecs = allVecs.slice(0, sourceCols.length);
+                    let offset = sourceCols.length;
+                    embScores = candidates.map((p) => {
+                      const refVecs = allVecs.slice(offset, offset + p.cols.length);
+                      offset += p.cols.length;
+                      // Greedy bipartite: average cosine of best-matched pairs
+                      const M = srcVecs.length, N = refVecs.length;
+                      const pairs = [];
+                      for (let i = 0; i < M; i++) {
+                        for (let j = 0; j < N; j++) {
+                          let dot = 0, na = 0, nb = 0;
+                          for (let k = 0; k < srcVecs[i].length; k++) {
+                            dot += srcVecs[i][k] * refVecs[j][k];
+                            na += srcVecs[i][k] ** 2;
+                            nb += refVecs[j][k] ** 2;
+                          }
+                          const sim = (na && nb) ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+                          pairs.push({ i, j, sim });
+                        }
+                      }
+                      pairs.sort((a, b) => b.sim - a.sim);
+                      const usedI = new Set(), usedJ = new Set();
+                      let sum = 0, matched = 0;
+                      for (const { i, j, sim } of pairs) {
+                        if (usedI.has(i) || usedJ.has(j)) continue;
+                        usedI.add(i); usedJ.add(j);
+                        sum += sim; matched++;
+                        if (matched === Math.min(M, N)) break;
+                      }
+                      return matched > 0 ? sum / Math.max(M, N) : 0;
+                    });
+                  }
+                } catch { /* embeddings unavailable — fall through to Jaccard only */ }
+              }
+
+              // Signal 3: Levenshtein bipartite match score across column pairs
+              const { levenshteinRatio } = await import("./lib/align.js");
+              const levScore = (cols) => {
+                const src = sourceCols.map((c) => c.toLowerCase().replace(/[^a-z0-9]/g, ""));
+                const exp = cols.map((c) => c.toLowerCase().replace(/[^a-z0-9]/g, ""));
+                const pairs = [];
+                for (let i = 0; i < src.length; i++)
+                  for (let j = 0; j < exp.length; j++)
+                    pairs.push({ i, j, sim: levenshteinRatio(src[i], exp[j]) });
+                pairs.sort((a, b) => b.sim - a.sim);
+                const usedI = new Set(), usedJ = new Set();
+                let sum = 0, matched = 0;
+                for (const { i, j, sim } of pairs) {
+                  if (usedI.has(i) || usedJ.has(j)) continue;
+                  usedI.add(i); usedJ.add(j);
+                  sum += sim; matched++;
+                  if (matched === Math.min(src.length, exp.length)) break;
+                }
+                return matched > 0 ? sum / Math.max(src.length, exp.length) : 0;
+              };
+
+              // Signal 4: column count similarity
+              const sizeScore = (cols) => 1 - Math.abs(sourceCols.length - cols.length) / Math.max(sourceCols.length, cols.length, 1);
+
+              // RRF fusion (k=60) — dense ranking: equal scores share same rank
+              const K = 60;
+              const rank = (arr) => {
+                const sortedVals = [...new Set(arr.map((x) => x.v))].sort((a, b) => b - a);
+                return arr.map((x) => ({ id: x.id, rank: sortedVals.indexOf(x.v) }));
+              };
+              const jList = candidates.map((p) => ({ id: p.id, v: jaccardScore(p.cols) }));
+              const lList = candidates.map((p) => ({ id: p.id, v: levScore(p.cols) }));
+              const sList = candidates.map((p) => ({ id: p.id, v: sizeScore(p.cols) }));
+              const lists = [rank(jList), rank(lList), rank(sList)];
+              if (embScores) {
+                const eList = candidates.map((p, i) => ({ id: p.id, v: embScores[i] }));
+                lists.push(rank(eList));
+              }
+              const rrfMap = new Map();
+              for (const ranked of lists) {
+                for (const { id, rank: r } of ranked) {
+                  rrfMap.set(id, (rrfMap.get(id) || 0) + 1 / (K + r + 1));
+                }
+              }
+              // Sort by RRF descending; use size similarity as tiebreaker
+              candidates.sort((a, b) => {
+                const diff = (rrfMap.get(b.id) || 0) - (rrfMap.get(a.id) || 0);
+                if (Math.abs(diff) > 1e-6) return diff;
+                return sizeScore(b.cols) - sizeScore(a.cols);
+              });
+              dpIdentifier = candidates[0].id;
+              dpName = candidates[0].name;
+              targetCols = candidates[0].cols;
+            }
+          } catch (e) {
+            console.error(ERR(`  ✗ Could not list data products: ${e.message}`));
+            process.exitCode = 1;
+            return;
+          }
+          console.log(DIM(`  Auto-selected target: ${dpName} (${dpIdentifier})`));
+          resolvedTarget = dpIdentifier;
+          if (!targetCols) targetCols = await fetchEntityColumns(client, dpIdentifier, "data_product");
+        } else if (isIdentifier(target)) {
+          targetCols = await fetchEntityColumns(client, target.trim(), "data_product");
+        } else {
+          targetCols = target.split(",").map((c) => c.trim()).filter(Boolean);
+        }
+        if (!targetCols || targetCols.length === 0) {
+          console.error(ERR(`  ✗ Could not resolve target columns from: ${resolvedTarget}`));
+          process.exit(1);
+        }
+
+        const result = await alignColumns(sourceCols, targetCols, { embedTexts, threshold });
+
+        // Extend the suggested transformation with unmapped handling decisions
+        if (!result.suggestedTransformation) result.suggestedTransformation = { transform: "rename_column", mapping: {} };
+        if (dropUnmappedSource && result.unmappedSource.length > 0) {
+          result.suggestedTransformation.drop_columns = result.unmappedSource;
+        }
+        if (fillMissingExpected && result.unmappedExpected.length > 0) {
+          result.suggestedTransformation.fill_columns = result.unmappedExpected;
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        // ── Formatted table output ────────────────────────────────────────────
+        const title = `Column Alignment: ${source} → ${resolvedTarget}`;
+        banner(title);
+        console.log();
+
+        // Always show full greedy table: confirmed (above threshold) + suggestions (below)
+        const allMappings = await alignColumns(sourceCols, targetCols, { embedTexts, threshold: 0 });
+        const confirmedSet = new Set(result.mappings.map((m) => m.sourceColumn));
+
+        const COL_W = 20, EXP_W = 24, MET_W = 12;
+        console.log(DIM(`  ${"Source".padEnd(COL_W)}  ${"Expected".padEnd(EXP_W)}  ${"Method".padEnd(MET_W)}  Confidence`));
+        console.log(DIM("  " + "─".repeat(COL_W + EXP_W + MET_W + 20)));
+        for (const m of allMappings.mappings) {
+          const conf = `${Math.round(m.confidence * 100)}%`;
+          const isConfirmed = confirmedSet.has(m.sourceColumn);
+          if (isConfirmed) {
+            const methodColor = m.method === "exact" ? OK : m.method === "embedding" ? ACCENT : WARN;
+            console.log(
+              `  ${m.sourceColumn.slice(0, COL_W - 1).padEnd(COL_W)}  ${m.expectedColumn.slice(0, EXP_W - 1).padEnd(EXP_W)}  ${methodColor(m.method.padEnd(MET_W))}  ${conf}`,
+            );
+          } else {
+            console.log(DIM(
+              `  ${m.sourceColumn.slice(0, COL_W - 1).padEnd(COL_W)}  ${m.expectedColumn.slice(0, EXP_W - 1).padEnd(EXP_W)}  ${m.method.padEnd(MET_W)}  ${conf}`,
+            ));
+          }
+        }
+        // Columns with no match at all
+        for (const src of allMappings.unmappedSource) {
+          console.log(DIM(`  ${src.slice(0, COL_W - 1).padEnd(COL_W)}  ${"—".padEnd(EXP_W)}  ${"unmatched".padEnd(MET_W)}  —`));
+        }
+
+        const hasSuggestions = allMappings.mappings.some((m) => !confirmedSet.has(m.sourceColumn));
+        if (hasSuggestions) {
+          console.log(DIM(`\n  Dimmed rows are suggestions below the ${threshold} threshold.`));
+          const lowestConf = Math.min(...allMappings.mappings.filter((m) => !confirmedSet.has(m.sourceColumn)).map((m) => m.confidence));
+          console.log(DIM(`  Use --threshold ${Math.max(0.1, Math.ceil(lowestConf * 10) / 10 - 0.1).toFixed(1)} to accept all, or specify a value.`));
+        }
+
+        if (allMappings.unmappedExpected.length > 0) {
+          const action = fillMissingExpected ? chalk.yellow("fill with NaN") : chalk.dim("skip");
+          console.log(`\n  Unmapped expected [${action}]: ${DIM(allMappings.unmappedExpected.join(", "))}`);
+        }
+
+        if (Object.keys(result.suggestedTransformation.mapping).length > 0) {
+          console.log(ACCENT("\n  Suggested rename_column step:"));
+          console.log(`  ${JSON.stringify(result.suggestedTransformation.mapping, null, 2).replace(/\n/g, "\n  ")}`);
+        }
+
+        // ── FCL patch output ──────────────────────────────────────────────────
+        if (opts.fcl !== undefined) {
+          const mapping = { ...(result.suggestedTransformation?.mapping || {}) };
+
+          if (Object.keys(mapping).length === 0 && (result.unmappedSource || []).length === 0) {
+            console.log(WARN("  No confirmed mappings to write — use --threshold to lower the bar."));
+          } else {
+            const toFile = typeof opts.fcl === "string";
+            const dpId = resolvedTarget || "YOUR_DATA_PRODUCT_IDENTIFIER";
+
+            // Try to resolve the data object ref from the existing builder
+            let inputRef = "YOUR_DATA_OBJECT_REF";
+            let inputType = "data_object";
+            if (resolvedTarget) {
+              try {
+                const { qs } = await import("./lib/helpers.js");
+                const builder = await client.get(`/data/data_product/compute/builder${qs({ identifier: resolvedTarget })}`);
+                const firstInput = Object.values(builder?.inputs || {})[0];
+                if (firstInput?.identifier) {
+                  inputRef = firstInput.identifier;
+                  inputType = firstInput.input_type === "data_product" ? "data_product" : "data_object";
+                }
+              } catch { /* builder not available — leave placeholder */ }
+            }
+
+            const mappingLines = Object.entries(mapping)
+              .map(([from, to]) => from === to
+                ? `            ${from}: ${to}  # new column — rename or remove`
+                : `            ${from}: ${to}`)
+              .join("\n");
+            const applyHint = toFile ? `fops apply ${opts.fcl}` : "fops apply <file>";
+            const yaml = [
+              `# Landscape patch — apply with: ${applyHint}`,
+              `# Adds a rename_column step to the data product pipeline.`,
+              `# Review the mapping before applying — dimmed suggestions not included.`,
+              `data_product:`,
+              `  ${dpId}:`,
+              `    pipeline:`,
+              `      inputs:`,
+              `        - type: ${inputType}`,
+              `          ref: ${inputRef}`,
+              `      transforms:`,
+              `        - transform: rename_column`,
+              `          mapping:`,
+              mappingLines,
+            ].join("\n") + "\n";
+            if (toFile) {
+              const { writeFileSync: wfs } = await import("node:fs");
+              const fclPath = path.resolve(opts.fcl);
+              wfs(fclPath, yaml);
+              console.log(OK(`\n  ✓ FCL patch written: ${fclPath}`));
+              console.log(DIM(`    Edit the inputs.ref, then: fops apply ${fclPath}`));
+            } else {
+              process.stdout.write(yaml);
+            }
+          }
+        }
+
+        // ── Apply transformation to CSV(s) ────────────────────────────────────
+        if (opts.output && sourceCsvFiles.length > 0) {
+          const Papa = (await import("papaparse")).default;
+          const renameMap = result.suggestedTransformation.mapping || {};
+          const dropCols = new Set(dropUnmappedSource ? result.unmappedSource : []);
+          const fillCols = fillMissingExpected ? result.unmappedExpected : [];
+
+          let outputPath = path.resolve(opts.output);
+          // If multiple source files and output is a directory, write each there
+          const outputIsDir = sourceCsvFiles.length > 1 || isDirectory(opts.output);
+          if (outputIsDir) {
+            const { mkdirSync } = await import("node:fs");
+            mkdirSync(outputPath, { recursive: true });
+          }
+
+          for (const csvFile of sourceCsvFiles) {
+            const raw = readFileSync(csvFile, "utf8");
+            const parsed = Papa.parse(raw, { header: true, skipEmptyLines: true });
+            const origHeaders = parsed.meta.fields || [];
+
+            // Build output header: renamed mapped cols + kept unmapped source + fill cols
+            const outHeaders = [
+              ...origHeaders
+                .filter((h) => !dropCols.has(h))
+                .map((h) => renameMap[h] || h),
+              ...fillCols,
+            ];
+
+            const outRows = parsed.data.map((row) => {
+              const out = {};
+              for (const h of origHeaders) {
+                if (dropCols.has(h)) continue;
+                out[renameMap[h] || h] = row[h] ?? "";
+              }
+              for (const h of fillCols) out[h] = "";
+              return out;
+            });
+
+            const csv = Papa.unparse({ fields: outHeaders, data: outRows });
+            const dest = outputIsDir ? path.join(outputPath, path.basename(csvFile)) : outputPath;
+            writeFileSync(dest, csv);
+            console.log(OK(`  ✓ Written: ${dest}`));
+            outputPath = dest; // track final path for --create/--overwrite
+          }
+
+          // ── Create or overwrite Foundation DataObject ─────────────────────
+          if (opts.create) {
+            try {
+              const body = {
+                entity: { name: opts.create, label: opts.create.slice(0, 3).toLowerCase() },
+                entity_info: { owner: api.config?.email || "" },
+              };
+              const created = await client.post("/data/data_object", body);
+              const newId = created?.identifier || created?.entity?.identifier;
+              if (newId) {
+                await client.put(`/data/data_object/config?identifier=${newId}`, {
+                  data_object_type: "csv",
+                  path: outputPath,
+                  has_header: true,
+                });
+                console.log(OK(`  ✓ DataObject created: ${newId}`));
+              }
+            } catch (e) {
+              console.error(ERR(`  ✗ Failed to create DataObject: ${e.message}`));
+            }
+          } else if (opts.overwrite) {
+            try {
+              await client.put(`/data/data_object/config?identifier=${opts.overwrite}`, {
+                data_object_type: "csv",
+                path: outputPath,
+                has_header: true,
+              });
+              console.log(OK(`  ✓ DataObject updated: ${opts.overwrite}`));
+            } catch (e) {
+              console.error(ERR(`  ✗ Failed to update DataObject: ${e.message}`));
+            }
+          }
+        } else if ((opts.create || opts.overwrite) && !opts.output) {
+          console.log(WARN("  --create/--overwrite require --output to specify the transformed CSV path."));
+        }
+
+        console.log();
+      });
+
+    // ── run ───────────────────────────────────────────────────────────────────
+    foundation
+      .command("run")
+      .description("Open the Foundation UI in an Electron window")
+      .option("--url <url>", "Override the frontend URL")
+      .action(async (opts) => {
+        const { spawn } = await import("node:child_process");
+        const { readFileSync } = await import("node:fs");
+        const { findComposeRoot } = await import("./lib/tools-write.js");
+
+        // Resolve frontend URL: flag → env → .env file → default
+        let frontendUrl = opts.url || process.env.FOUNDATION_PUBLIC_URL;
+        if (!frontendUrl) {
+          const root = program._fopsRoot || findComposeRoot();
+          if (root) {
+            try {
+              const envContent = readFileSync(`${root}/.env`, "utf8");
+              const m = envContent.match(/^FOUNDATION_PUBLIC_URL=(.+)$/m);
+              if (m) frontendUrl = m[1].trim();
+            } catch { /* .env not found */ }
+          }
+        }
+        frontendUrl = frontendUrl || "http://127.0.0.1:3002";
+
+        const { writeFileSync, existsSync, realpathSync } = await import("node:fs");
+        const { tmpdir, homedir } = await import("node:os");
+        const { join, dirname } = await import("node:path");
+        const { execSync } = await import("node:child_process");
+
+        const composeRoot = program._fopsRoot || findComposeRoot() || "";
+
+        // Resolve icon from the fops install
+        let iconPath = "";
+        try {
+          const pluginsNodeModules = join(homedir(), ".fops", "plugins", "node_modules");
+          const fopsRoot = dirname(realpathSync(pluginsNodeModules));
+          const src = join(fopsRoot, "src", "electron", "icon.png");
+          if (existsSync(src)) iconPath = src;
+        } catch { /* icon is optional */ }
+
+        // ── Swift WKWebView app (uses Safari's WebKit engine + Keychain) ─────
+        const swiftScript = join(tmpdir(), "fops-webkit-main.swift");
+        // Control panel JS injected into the WKWebView page
+        const controlJS = `
+(function() {
+  var API = "http://127.0.0.1:9001";
+  var style = document.createElement("style");
+  style.textContent = "#fops-ctrl{position:fixed;bottom:18px;right:18px;z-index:2147483647;font-family:-apple-system,BlinkMacSystemFont,sans-serif;font-size:12px;color:#e2e8f0;user-select:none}" +
+    "#fops-pill{display:flex;align-items:center;gap:8px;background:rgba(15,15,20,0.85);backdrop-filter:blur(12px);border:1px solid rgba(255,255,255,0.12);border-radius:999px;padding:6px 12px 6px 10px;cursor:default;box-shadow:0 4px 16px rgba(0,0,0,0.4)}" +
+    "#fops-panel{display:none;flex-direction:column;gap:1px;background:rgba(15,15,20,0.92);backdrop-filter:blur(12px);border:1px solid rgba(255,255,255,0.12);border-radius:10px;padding:6px;margin-bottom:6px;box-shadow:0 4px 20px rgba(0,0,0,0.5);min-width:300px}" +
+    "#fops-ctrl:hover #fops-panel{display:flex}" +
+    ".fops-svc{display:flex;align-items:center;gap:8px;padding:5px 8px;border-radius:6px}" +
+    ".fops-svc:hover{background:rgba(255,255,255,0.06)}" +
+    ".fops-svc-name{flex:1;font-size:11px;color:#cbd5e1}" +
+    ".fops-dot{width:7px;height:7px;border-radius:50%;flex-shrink:0}" +
+    ".fops-btn{padding:2px 8px;border-radius:999px;border:1px solid rgba(255,255,255,0.18);background:rgba(255,255,255,0.08);color:#e2e8f0;font-size:10px;cursor:pointer}" +
+    ".fops-btn:hover{background:rgba(255,255,255,0.18)}" +
+    ".fops-btn:disabled{opacity:0.4;cursor:default}";
+  document.head.appendChild(style);
+
+  var ctrl = document.createElement("div"); ctrl.id = "fops-ctrl";
+  var panel = document.createElement("div"); panel.id = "fops-panel";
+  var pill = document.createElement("div"); pill.id = "fops-pill";
+  var dot = document.createElement("span"); dot.className = "fops-dot"; dot.style.background = "#64748b";
+  var lbl = document.createElement("span"); lbl.textContent = "Checking\\u2026";
+  var mainBtn = document.createElement("button"); mainBtn.className = "fops-btn"; mainBtn.style.display = "none";
+  pill.append(dot, lbl, mainBtn);
+  ctrl.append(panel, pill);
+  document.body.appendChild(ctrl);
+
+  var status = "checking", busy = false;
+
+  function setStatus(s) {
+    status = s;
+    if (s === "running")       { dot.style.background="#22c55e"; lbl.textContent="Running";       mainBtn.textContent="Stop";          mainBtn.disabled=false; mainBtn.style.display=""; }
+    else if (s === "stopped")  { dot.style.background="#ef4444"; lbl.textContent="Stopped";       mainBtn.textContent="Start";         mainBtn.disabled=false; mainBtn.style.display=""; }
+    else if (s === "starting") { dot.style.background="#f59e0b"; lbl.textContent="Starting\\u2026"; mainBtn.textContent="Starting\\u2026"; mainBtn.disabled=true;  mainBtn.style.display=""; }
+    else if (s === "stopping") { dot.style.background="#f59e0b"; lbl.textContent="Stopping\\u2026"; mainBtn.textContent="Stopping\\u2026"; mainBtn.disabled=true;  mainBtn.style.display=""; }
+    else                       { dot.style.background="#64748b"; lbl.textContent="Checking\\u2026"; mainBtn.style.display="none"; }
+  }
+
+  function send(action, payload) {
+    window.webkit.messageHandlers.fopsStack.postMessage({action: action, payload: payload || ""});
+  }
+
+  function poll() {
+    fetch(API, {mode:"no-cors"}).then(function(){ setStatus("running"); }).catch(function(){ setStatus("stopped"); });
+  }
+
+  mainBtn.onclick = function() {
+    if (busy) return; busy = true;
+    if (status === "running") { setStatus("stopping"); send("stop"); }
+    else                      { setStatus("starting"); send("start"); }
+    setTimeout(function() { busy = false; poll(); }, 4000);
+  };
+
+  window._fopsServices = function(json) {
+    panel.innerHTML = "";
+    var svcs = [];
+    try { svcs = JSON.parse(json); } catch(e) {}
+    if (!Array.isArray(svcs)) svcs = [svcs].filter(Boolean);
+    svcs.forEach(function(svc) {
+      var name = svc.Service || svc.Name || "?";
+      var running = (svc.State || "").toLowerCase() === "running";
+      var row = document.createElement("div"); row.className = "fops-svc";
+      var d = document.createElement("span"); d.className = "fops-dot"; d.style.background = running ? "#22c55e" : "#ef4444";
+      var n = document.createElement("span"); n.className = "fops-svc-name"; n.textContent = name;
+      var rb = document.createElement("button"); rb.className = "fops-btn"; rb.textContent = "\\u21BA";
+      var sb = document.createElement("button"); sb.className = "fops-btn"; sb.textContent = "\\u25A0";
+      rb.onclick = function() { rb.disabled=sb.disabled=true; rb.textContent="\\u2026"; send("restart", name); setTimeout(function(){ send("services"); }, 3000); };
+      sb.onclick = function() { rb.disabled=sb.disabled=true; sb.textContent="\\u2026"; send("stopSvc", name); setTimeout(function(){ send("services"); }, 2000); };
+      row.append(d, n, rb, sb);
+      panel.appendChild(row);
+    });
+  };
+
+  ctrl.addEventListener("mouseenter", function() { send("services"); });
+
+  poll();
+  setInterval(poll, 5000);
+})();
+`;
+
+        writeFileSync(swiftScript, `
+import AppKit
+import WebKit
+
+ProcessInfo.processInfo.processName = "Foundation"
+
+class Handler: NSObject, WKScriptMessageHandler {
+    var exec: (String, String) -> Void = { _, _ in }
+    func userContentController(_ c: WKUserContentController, didReceive msg: WKScriptMessage) {
+        guard let d = msg.body as? [String: String] else { return }
+        exec(d["action"] ?? "", d["payload"] ?? "")
+    }
+}
+
+class WD: NSObject, NSWindowDelegate {
+    func windowWillClose(_ n: Notification) { NSApp.terminate(nil) }
+}
+
+// Allow popups (Google OAuth, etc.) to open in a new window
+class UI: NSObject, WKUIDelegate {
+    func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
+                 for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
+        configuration.websiteDataStore = WKWebsiteDataStore.default()
+        let popWin = NSWindow(contentRect: NSRect(x:0,y:0,width:900,height:700),
+            styleMask: [.titled,.closable,.resizable], backing: .buffered, defer: false)
+        let popWV = WKWebView(frame: popWin.contentLayoutRect, configuration: configuration)
+        popWV.autoresizingMask = [.width, .height]
+        popWin.contentView = popWV
+        popWin.center()
+        popWin.makeKeyAndOrderFront(nil)
+        return popWV
+    }
+}
+
+let foundationURL = ProcessInfo.processInfo.environment["FOUNDATION_URL"] ?? "http://127.0.0.1:3002"
+let composeRoot   = ProcessInfo.processInfo.environment["FOUNDATION_COMPOSE_ROOT"] ?? ""
+let iconPath      = ProcessInfo.processInfo.environment["FOUNDATION_ICON"] ?? ""
+
+func docker() -> String {
+    for p in ["/opt/homebrew/bin/docker", "/usr/local/bin/docker", "/usr/bin/docker"] {
+        if FileManager.default.isExecutableFile(atPath: p) { return p }
+    }
+    return "docker"
+}
+
+func compose(_ args: [String], completion: ((String) -> Void)? = nil) {
+    let p = Process(); let pipe = Pipe()
+    p.executableURL = URL(fileURLWithPath: docker())
+    p.arguments = ["compose"] + args
+    if !composeRoot.isEmpty { p.currentDirectoryURL = URL(fileURLWithPath: composeRoot) }
+    if completion != nil { p.standardOutput = pipe; p.standardError = pipe }
+    try? p.run()
+    if let completion = completion {
+        p.waitUntilExit()
+        let out = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+        DispatchQueue.main.async { completion(out) }
+    }
+}
+
+// Use default (persistent) data store so Keychain autofill works
+let cfg = WKWebViewConfiguration()
+cfg.websiteDataStore = WKWebsiteDataStore.default()
+let handler = Handler()
+cfg.userContentController.add(handler, name: "fopsStack")
+cfg.userContentController.addUserScript(WKUserScript(
+    source: ${JSON.stringify(controlJS)},
+    injectionTime: .atDocumentEnd, forMainFrameOnly: true))
+
+let ui = UI()
+let wv = WKWebView(frame: NSRect(x:0,y:0,width:1400,height:900), configuration: cfg)
+wv.autoresizingMask = [.width, .height]
+wv.uiDelegate = ui
+
+handler.exec = { action, payload in
+    switch action {
+    case "start":
+        compose(["up", "-d"])
+    case "stop":
+        compose(["down"])
+    case "restart":
+        compose(["restart", payload])
+    case "stopSvc":
+        compose(["stop", payload])
+    case "services":
+        compose(["ps", "--format", "json"]) { out in
+            let escaped = out.replacingOccurrences(of: "\\\\", with: "\\\\\\\\")
+                             .replacingOccurrences(of: "\\"", with: "\\\\\\"")
+                             .replacingOccurrences(of: "\\n", with: "\\\\n")
+            wv.evaluateJavaScript("window._fopsServices(\\"[\\(escaped)]\\")", completionHandler: nil)
+        }
+    default: break
+    }
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.regular)
+
+// ── App menu with Cmd+Q ───────────────────────────────────────────────────
+let menuBar = NSMenu()
+let appItem = NSMenuItem()
+menuBar.addItem(appItem)
+let appMenu = NSMenu()
+appItem.submenu = appMenu
+appMenu.addItem(NSMenuItem(title: "Quit Foundation", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q"))
+app.mainMenu = menuBar
+
+// ── Dock icon — padded so it matches other macOS app proportions ──────────
+if !iconPath.isEmpty, let src = NSImage(contentsOfFile: iconPath) {
+    let size: CGFloat = 512
+    let pad: CGFloat = size * 0.15
+    let inner = size - pad * 2
+    let padded = NSImage(size: NSSize(width: size, height: size))
+    padded.lockFocus()
+    src.draw(in: NSRect(x: pad, y: pad, width: inner, height: inner),
+             from: .zero, operation: .sourceOver, fraction: 1)
+    padded.unlockFocus()
+    app.applicationIconImage = padded
+}
+
+let wd = WD()
+let win = NSWindow(contentRect: NSRect(x:0,y:0,width:1400,height:900),
+    styleMask: [.titled,.closable,.miniaturizable,.resizable], backing: .buffered, defer: false)
+win.title = "Foundation"
+win.contentView = wv
+win.delegate = wd
+win.center()
+win.makeKeyAndOrderFront(nil)
+
+app.activate(ignoringOtherApps: true)
+wv.load(URLRequest(url: URL(string: foundationURL)!))
+app.run()
+`);
+
+        console.log(ACCENT(`  Opening Foundation at ${frontendUrl}`));
+
+        const child = spawn("swift", [swiftScript], {
+          stdio: "ignore",
+          detached: true,
+          env: { ...process.env, FOUNDATION_URL: frontendUrl, FOUNDATION_ICON: iconPath, FOUNDATION_COMPOSE_ROOT: composeRoot },
+        });
+        child.unref();
+      });
+
+    // ── tray ──────────────────────────────────────────────────────────────────
+    foundation
+      .command("tray")
+      .description("Run a macOS menu bar tray for the Foundation stack")
+      .option("--url <url>", "Override the backend API URL")
+      .action(async (opts) => {
+        const { spawn } = await import("node:child_process");
+        const { writeFileSync, existsSync, realpathSync, readFileSync } = await import("node:fs");
+        const { tmpdir, homedir } = await import("node:os");
+        const { join, dirname } = await import("node:path");
+        const { findComposeRoot } = await import("./lib/tools-write.js");
+
+        const composeRoot = program._fopsRoot || findComposeRoot() || "";
+
+        let apiUrl = opts.url || process.env.FOPS_API_URL || "http://127.0.0.1:9001";
+
+        // Current fops version
+        let fopsVersion = "0.0.0";
+        try {
+          const pluginsNodeModules2 = join(homedir(), ".fops", "plugins", "node_modules");
+          const fopsRoot2 = dirname(realpathSync(pluginsNodeModules2));
+          const pkgJson = JSON.parse(readFileSync(join(fopsRoot2, "package.json"), "utf8"));
+          fopsVersion = pkgJson.version || "0.0.0";
+        } catch { /* fallback */ }
+
+        // Resolve icon
+        let iconPath = "";
+        try {
+          const pluginsNodeModules = join(homedir(), ".fops", "plugins", "node_modules");
+          const fopsRoot = dirname(realpathSync(pluginsNodeModules));
+          const src = join(fopsRoot, "src", "electron", "icon.png");
+          if (existsSync(src)) iconPath = src;
+        } catch { /* icon optional */ }
+
+        // Discover installed plugins for the Plugins submenu
+        let fopsPluginsJson = "[]";
+        try {
+          const { discoverPlugins } = await import("../../discovery.js");
+          const { validateManifest } = await import("../../manifest.js");
+          const candidates = discoverPlugins();
+          const pluginList = candidates.map((c) => {
+            const manifest = validateManifest(c.path);
+            return { id: c.id, name: manifest?.name || c.id, source: c.source };
+          }).filter((p) => p.id);
+          fopsPluginsJson = JSON.stringify(pluginList);
+        } catch { /* optional */ }
+
+        // ── Windows tray (PowerShell NotifyIcon) ─────────────────────────────
+        if (process.platform === "win32") {
+          const ps1Tray = join(tmpdir(), "fops-tray.ps1");
+          writeFileSync(ps1Tray, `
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+$script:apiUrl       = $env:FOUNDATION_API_URL
+$script:composeRoot  = $env:FOUNDATION_COMPOSE_ROOT
+$script:foundationUrl = if ($env:FOUNDATION_URL) { $env:FOUNDATION_URL } else { "http://127.0.0.1:3002" }
+$script:allPlugins   = @()
+try { $script:allPlugins = $env:FOPS_PLUGINS | ConvertFrom-Json } catch {}
+
+function Get-Docker {
+    foreach ($p in @("C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe")) {
+        if (Test-Path $p) { return $p }
+    }
+    $d = (Get-Command docker -ErrorAction SilentlyContinue).Source
+    if ($d) { return $d }
+    return "docker"
+}
+
+function Get-Fops {
+    $f = (Get-Command fops -ErrorAction SilentlyContinue).Source
+    if ($f) { return $f }
+    return "fops"
+}
+
+function Invoke-Compose {
+    param([string[]]$CArgs, [switch]$Capture)
+    $docker = Get-Docker
+    $proj = @()
+    if ($script:composeRoot) { $proj = @("--project-directory", $script:composeRoot) }
+    if ($Capture) {
+        & $docker compose @proj @CArgs 2>$null
+    } else {
+        & $docker compose @proj @CArgs 2>$null | Out-Null
+    }
+}
+
+function Read-PluginEnabled($id) {
+    $cfgPath = "$env:USERPROFILE\\.fops.json"
+    if (!(Test-Path $cfgPath)) { return $true }
+    try {
+        $cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json
+        $entry = $cfg.plugins.entries.$id
+        if ($null -eq $entry) { return $true }
+        return $entry.enabled -ne $false
+    } catch { return $true }
+}
+
+# ── Tray icon ──────────────────────────────────────────────────────────────────
+$tray = New-Object System.Windows.Forms.NotifyIcon
+$tray.Icon = [System.Drawing.SystemIcons]::Application
+$tray.Text = "Foundation"
+$tray.Visible = $true
+
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+
+$statusItem = [System.Windows.Forms.ToolStripLabel]::new("Checking...")
+$statusItem.Enabled = $false
+$menu.Items.Add($statusItem) | Out-Null
+$menu.Items.Add([System.Windows.Forms.ToolStripSeparator]::new()) | Out-Null
+
+$startItem = [System.Windows.Forms.ToolStripMenuItem]::new("Start")
+$startItem.add_Click({ Invoke-Compose "up","-d"; Update-Status })
+$stopItem = [System.Windows.Forms.ToolStripMenuItem]::new("Stop")
+$stopItem.add_Click({ Invoke-Compose "down"; Update-Status })
+$restartItem = [System.Windows.Forms.ToolStripMenuItem]::new("Restart")
+$restartItem.add_Click({ Invoke-Compose "restart"; Update-Status })
+$menu.Items.Add($startItem) | Out-Null
+$menu.Items.Add($stopItem) | Out-Null
+$menu.Items.Add($restartItem) | Out-Null
+$menu.Items.Add([System.Windows.Forms.ToolStripSeparator]::new()) | Out-Null
+
+# Compose submenu
+$composeItem = [System.Windows.Forms.ToolStripMenuItem]::new("Compose")
+$composeItem.add_DropDownOpening({
+    $composeItem.DropDownItems.Clear()
+    $raw = Invoke-Compose "ps","--format","json" -Capture
+    $services = @()
+    try { $services = ($raw -join "") | ConvertFrom-Json } catch {}
+    if (!$services) { $services = @() }
+    if ($services -isnot [array]) { $services = @($services) }
+    if ($services.Count -eq 0) {
+        $n = [System.Windows.Forms.ToolStripMenuItem]::new("No services found")
+        $n.Enabled = $false; $composeItem.DropDownItems.Add($n) | Out-Null; return
+    }
+    foreach ($svc in $services) {
+        $name  = if ($svc.Service) { $svc.Service } else { $svc.Name }
+        $state = if ($svc.State)   { $svc.State }   else { "" }
+        $label = if ($name -like "foundation-*") { $name.Substring(11) } else { $name }
+        $dot   = if ($state -eq "running") { [char]0x25CF + " " } else { [char]0x25CB + " " }
+        $svcItem = [System.Windows.Forms.ToolStripMenuItem]::new($dot + $label)
+
+        $logsI = [System.Windows.Forms.ToolStripMenuItem]::new("Logs")
+        $n2 = $name
+        $logsI.add_Click({ Start-Process powershell -ArgumentList "-NoExit","-Command","& '$(Get-Docker)' compose $(if ($script:composeRoot) { '--project-directory ' + $script:composeRoot }) logs -f --tail=200 $n2" }.GetNewClosure())
+        $svcItem.DropDownItems.Add($logsI) | Out-Null
+
+        $startI = [System.Windows.Forms.ToolStripMenuItem]::new("Start"); $startI.Enabled = ($state -ne "running")
+        $startI.add_Click({ Invoke-Compose "start",$n2 }.GetNewClosure()); $svcItem.DropDownItems.Add($startI) | Out-Null
+
+        $stopI = [System.Windows.Forms.ToolStripMenuItem]::new("Stop"); $stopI.Enabled = ($state -eq "running")
+        $stopI.add_Click({ Invoke-Compose "stop",$n2 }.GetNewClosure()); $svcItem.DropDownItems.Add($stopI) | Out-Null
+
+        $restI = [System.Windows.Forms.ToolStripMenuItem]::new("Restart")
+        $restI.add_Click({ Invoke-Compose "restart",$n2 }.GetNewClosure()); $svcItem.DropDownItems.Add($restI) | Out-Null
+
+        $exI = [System.Windows.Forms.ToolStripMenuItem]::new("Exec Shell")
+        $exI.add_Click({ Start-Process powershell -ArgumentList "-NoExit","-Command","& '$(Get-Docker)' compose $(if ($script:composeRoot) { '--project-directory ' + $script:composeRoot }) exec $n2 bash" }.GetNewClosure())
+        $svcItem.DropDownItems.Add($exI) | Out-Null
+
+        $composeItem.DropDownItems.Add($svcItem) | Out-Null
+    }
+})
+$menu.Items.Add($composeItem) | Out-Null
+
+# Plugins submenu
+$pluginsItem = [System.Windows.Forms.ToolStripMenuItem]::new("Plugins")
+$pluginsItem.add_DropDownOpening({
+    $pluginsItem.DropDownItems.Clear()
+    if ($script:allPlugins.Count -eq 0) {
+        $n = [System.Windows.Forms.ToolStripMenuItem]::new("No plugins installed")
+        $n.Enabled = $false; $pluginsItem.DropDownItems.Add($n) | Out-Null; return
+    }
+    foreach ($plugin in $script:allPlugins) {
+        $enabled = Read-PluginEnabled $plugin.id
+        $prefix  = if ($enabled) { [char]0x2713 + " " } else { "  " }
+        $pItem   = [System.Windows.Forms.ToolStripMenuItem]::new($prefix + $plugin.name)
+        $pid2    = $plugin.id
+        $pItem.add_Click({
+            $fops   = Get-Fops
+            $isOn   = Read-PluginEnabled $pid2
+            $subCmd = if ($isOn) { "disable" } else { "enable" }
+            & $fops plugin $subCmd $pid2
+        }.GetNewClosure())
+        $pluginsItem.DropDownItems.Add($pItem) | Out-Null
+    }
+})
+$menu.Items.Add($pluginsItem) | Out-Null
+
+$menu.Items.Add([System.Windows.Forms.ToolStripSeparator]::new()) | Out-Null
+
+$openItem = [System.Windows.Forms.ToolStripMenuItem]::new("Open Foundation...")
+$openItem.add_Click({ Start-Process $script:foundationUrl })
+$menu.Items.Add($openItem) | Out-Null
+
+$doctorItem = [System.Windows.Forms.ToolStripMenuItem]::new("Doctor")
+$doctorItem.add_Click({
+    $fops = Get-Fops
+    $cd   = if ($script:composeRoot) { "cd '$($script:composeRoot)'; " } else { "" }
+    Start-Process powershell -ArgumentList "-NoExit","-Command","${cd}& '$fops' doctor"
+})
+$menu.Items.Add($doctorItem) | Out-Null
+
+$menu.Items.Add([System.Windows.Forms.ToolStripSeparator]::new()) | Out-Null
+
+$quitItem = [System.Windows.Forms.ToolStripMenuItem]::new("Quit")
+$quitItem.add_Click({
+    $tray.Visible = $false
+    [System.Windows.Forms.Application]::Exit()
+})
+$menu.Items.Add($quitItem) | Out-Null
+
+$tray.ContextMenuStrip = $menu
+
+function Update-Status {
+    $raw = Invoke-Compose "ps","--format","json","--status","running" -Capture
+    $running = $raw -and ($raw -match "\\{")
+    if ($running) {
+        $statusItem.Text = [char]0x25CF + " Running"
+        $startItem.Enabled = $false; $stopItem.Enabled = $true; $restartItem.Enabled = $true
+    } else {
+        $statusItem.Text = [char]0x25CB + " Stopped"
+        $startItem.Enabled = $true; $stopItem.Enabled = $false; $restartItem.Enabled = $false
+    }
+}
+Update-Status
+
+$timer = [System.Windows.Forms.Timer]::new()
+$timer.Interval = 8000
+$timer.add_Tick({ Update-Status })
+$timer.Start()
+
+[System.Windows.Forms.Application]::Run()
+$timer.Stop()
+$tray.Visible = $false
+`);
+          console.log(ACCENT("  Foundation tray started — look for the icon in your taskbar"));
+          const winChild = spawn("powershell", [
+            "-WindowStyle", "Hidden",
+            "-NonInteractive",
+            "-ExecutionPolicy", "Bypass",
+            "-File", ps1Tray,
+          ], {
+            stdio: "ignore",
+            detached: true,
+            env: trayEnv,
+            windowsHide: true,
+          });
+          winChild.unref();
+          return;
+        }
+
+        // ── macOS tray (Swift) ────────────────────────────────────────────────
+        const swiftTray = join(tmpdir(), "fops-tray.swift");
+        writeFileSync(swiftTray, `
+import AppKit
+import Foundation
+
+ProcessInfo.processInfo.processName = "Foundation"
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+func docker() -> String {
+    for p in ["/opt/homebrew/bin/docker", "/usr/local/bin/docker", "/usr/bin/docker"] {
+        if FileManager.default.isExecutableFile(atPath: p) { return p }
+    }
+    return "docker"
+}
+
+func git() -> String {
+    for p in ["/opt/homebrew/bin/git", "/usr/bin/git"] {
+        if FileManager.default.isExecutableFile(atPath: p) { return p }
+    }
+    return "git"
+}
+
+let composeRoot  = ProcessInfo.processInfo.environment["FOUNDATION_COMPOSE_ROOT"] ?? ""
+let iconPath     = ProcessInfo.processInfo.environment["FOUNDATION_ICON"] ?? ""
+let fopsVersion  = ProcessInfo.processInfo.environment["FOPS_VERSION"] ?? "0.0.0"
+
+// ── Plugin registry ───────────────────────────────────────────────────────────
+
+struct PluginEntry {
+    let id: String
+    let name: String
+    let source: String
+}
+
+let allPlugins: [PluginEntry] = {
+    let raw = ProcessInfo.processInfo.environment["FOPS_PLUGINS"] ?? "[]"
+    guard let data = raw.data(using: .utf8),
+          let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else { return [] }
+    return arr.compactMap { obj in
+        guard let id = obj["id"] as? String, let name = obj["name"] as? String else { return nil }
+        return PluginEntry(id: id, name: name, source: (obj["source"] as? String) ?? "")
+    }
+}()
+
+func readPluginEnabled(_ id: String) -> Bool {
+    let home = ProcessInfo.processInfo.environment["HOME"] ?? ""
+    guard !home.isEmpty,
+          let data = try? Data(contentsOf: URL(fileURLWithPath: home + "/.fops.json")),
+          let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+          let plugins = json["plugins"] as? [String: Any],
+          let entries = plugins["entries"] as? [String: Any],
+          let entry = entries[id] as? [String: Any],
+          let enabled = entry["enabled"] as? Bool else { return true }
+    return enabled
+}
+
+func run(_ exe: String, _ args: [String], cwd: String? = nil, capture: Bool = false, done: ((String, Bool) -> Void)? = nil) {
+    let p = Process(); let pipe = Pipe()
+    p.executableURL = URL(fileURLWithPath: exe)
+    p.arguments = args
+    if let d = cwd ?? (composeRoot.isEmpty ? nil : composeRoot) { p.currentDirectoryURL = URL(fileURLWithPath: d) }
+    p.standardOutput = capture ? pipe : FileHandle.nullDevice
+    p.standardError  = FileHandle.nullDevice
+    DispatchQueue.global().async {
+        guard (try? p.run()) != nil else { DispatchQueue.main.async { done?("", false) }; return }
+        p.waitUntilExit()
+        let out = capture ? (String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? "") : ""
+        DispatchQueue.main.async { done?(out, p.terminationStatus == 0) }
+    }
+}
+
+func compose(_ args: [String], capture: Bool = false, done: ((String, Bool) -> Void)? = nil) {
+    run(docker(), ["compose"] + args, capture: capture, done: done)
+}
+
+// ── Service discovery ─────────────────────────────────────────────────────────
+
+struct Service {
+    let name: String   // docker compose service name  e.g. "foundation-backend"
+    let label: String  // short label                  e.g. "backend"
+    let state: String  // "running" | "exited" | …
+    let dir: String    // submodule dir for git ops (may be empty)
+}
+
+// Parse one or more JSON objects/arrays from docker compose ps output
+func parseServices(_ raw: String) -> [Service] {
+    var services: [Service] = []
+    // docker compose ps --format json emits one JSON object per line (NDJSON) or a JSON array
+    let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+    var jsonData: Data? = nil
+    if trimmed.hasPrefix("[") {
+        jsonData = trimmed.data(using: .utf8)
+    } else {
+        // NDJSON — wrap lines into array
+        let lines = trimmed.components(separatedBy: "\\n").filter { $0.hasPrefix("{") }
+        jsonData = ("[" + lines.joined(separator: ",") + "]").data(using: .utf8)
+    }
+    guard let data = jsonData,
+          let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else { return [] }
+    for obj in arr {
+        let name  = (obj["Service"] as? String) ?? (obj["Name"] as? String) ?? ""
+        let state = (obj["State"]   as? String) ?? ""
+        guard !name.isEmpty else { continue }
+        // Strip "foundation-" prefix for the label
+        let label = name.hasPrefix("foundation-") ? String(name.dropFirst("foundation-".count)) : name
+        // Resolve submodule dir: submodules live inside composeRoot
+        // e.g. foundation-frontend-dev → foundation-frontend, foundation-backend-broker → foundation-backend
+        let dir: String
+        if composeRoot.isEmpty {
+            dir = ""
+        } else {
+            let base = URL(fileURLWithPath: composeRoot)
+            let fm2  = FileManager.default
+            // Try progressively shorter suffixes until we find a directory
+            var candidate = "foundation-" + label
+            var found = ""
+            while true {
+                let path = base.appendingPathComponent(candidate).standardized.path
+                if fm2.fileExists(atPath: path + "/.git") { found = path; break }
+                // strip last -component
+                guard let dash = candidate.lastIndex(of: "-") else { break }
+                candidate = String(candidate[candidate.startIndex..<dash])
+            }
+            dir = found
+        }
+        services.append(Service(name: name, label: label, state: state, dir: dir))
+    }
+    return services
+}
+
+// ── isRunning via docker compose ps ──────────────────────────────────────────
+
+func isRunning(completion: @escaping (Bool) -> Void) {
+    compose(["ps", "--format", "json", "--status", "running"], capture: true) { out, ok in
+        let up = !out.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty && out.contains("{")
+        completion(up)
+    }
+}
+
+// ── Open Terminal with a command ──────────────────────────────────────────────
+
+func openTerminal(command: String) {
+    let escaped = command.replacingOccurrences(of: "\\\\", with: "\\\\\\\\")
+                         .replacingOccurrences(of: "\\"", with: "\\\\\\"")
+    let script = "tell application \\"Terminal\\" to do script \\"\\(escaped)\\""
+    let p = Process()
+    p.executableURL = URL(fileURLWithPath: "/usr/bin/osascript")
+    p.arguments = ["-e", script]
+    try? p.run()
+}
+
+// ── App setup ─────────────────────────────────────────────────────────────────
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory)
+
+let bar      = NSStatusBar.system
+let trayItem = bar.statusItem(withLength: NSStatusItem.squareLength)
+
+if !iconPath.isEmpty, let img = NSImage(contentsOfFile: iconPath) {
+    img.size = NSSize(width: 18, height: 18)
+    img.isTemplate = false
+    trayItem.button?.image = img
+} else {
+    trayItem.button?.title = "F"
+}
+
+// ── Menu skeleton ─────────────────────────────────────────────────────────────
+
+let menu = NSMenu()
+
+let statusMenuItem = NSMenuItem(title: "Checking…", action: nil, keyEquivalent: "")
+statusMenuItem.isEnabled = false
+menu.addItem(statusMenuItem)
+
+menu.addItem(NSMenuItem.separator())
+
+let startItem   = NSMenuItem(title: "Start",   action: #selector(AppDelegate.startStack),   keyEquivalent: "")
+let stopItem    = NSMenuItem(title: "Stop",    action: #selector(AppDelegate.stopStack),    keyEquivalent: "")
+let restartItem = NSMenuItem(title: "Restart", action: #selector(AppDelegate.restartStack), keyEquivalent: "")
+menu.addItem(startItem)
+menu.addItem(stopItem)
+menu.addItem(restartItem)
+
+menu.addItem(NSMenuItem.separator())
+
+// Compose > (services populated dynamically)
+let composeItem = NSMenuItem(title: "Compose", action: nil, keyEquivalent: "")
+let composeMenu = NSMenu(title: "Compose")
+composeItem.submenu = composeMenu
+menu.addItem(composeItem)
+
+// Plugins > (populated dynamically)
+let pluginsItem = NSMenuItem(title: "Plugins", action: nil, keyEquivalent: "")
+let pluginsMenu = NSMenu(title: "Plugins")
+pluginsItem.submenu = pluginsMenu
+menu.addItem(pluginsItem)
+
+menu.addItem(NSMenuItem.separator())
+
+let openItem = NSMenuItem(title: "Open Foundation…", action: #selector(AppDelegate.openBrowser), keyEquivalent: "o")
+menu.addItem(openItem)
+
+// Frontend mode toggle — title updated dynamically in refresh()
+let frontendModeItem = NSMenuItem(title: "Frontend: checking…", action: #selector(AppDelegate.switchFrontendMode), keyEquivalent: "")
+menu.addItem(frontendModeItem)
+
+let doctorItem = NSMenuItem(title: "Doctor", action: #selector(AppDelegate.runDoctor), keyEquivalent: "")
+menu.addItem(doctorItem)
+
+menu.addItem(NSMenuItem.separator())
+
+// Update item — hidden until a newer version is detected
+let updateItem = NSMenuItem(title: "", action: #selector(AppDelegate.runUpdate), keyEquivalent: "")
+updateItem.isHidden = true
+menu.addItem(updateItem)
+
+menu.addItem(NSMenuItem.separator())
+menu.addItem(NSMenuItem(title: "Quit", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q"))
+
+trayItem.menu = menu
+
+// ── AppDelegate ───────────────────────────────────────────────────────────────
+
+class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
+    var running = false
+    var busy    = false
+
+    func applicationDidFinishLaunching(_ n: Notification) {
+        composeMenu.delegate = self
+        pluginsMenu.delegate = pluginsMenuDelegate
+        refresh()
+        let pollTimer = Timer(timeInterval: 8, repeats: true) { _ in self.refresh() }
+        RunLoop.main.add(pollTimer, forMode: .common)
+        // Check for updates on launch, then every hour
+        checkForUpdate()
+        let updateTimer = Timer(timeInterval: 3600, repeats: true) { _ in self.checkForUpdate() }
+        RunLoop.main.add(updateTimer, forMode: .common)
+    }
+
+    func checkForUpdate() {
+        guard let url = URL(string: "https://registry.npmjs.org/@meshxdata/fops/latest") else { return }
+        let task = URLSession.shared.dataTask(with: url) { data, _, _ in
+            guard let data = data,
+                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                  let latest = json["version"] as? String else { return }
+            DispatchQueue.main.async {
+                if self.isNewer(latest, than: fopsVersion) {
+                    updateItem.title = "⬆ Update available: v\\(latest)"
+                    updateItem.isHidden = false
+                    // Also pulse the tray button once to draw attention
+                    self.pulseUpdateBadge()
+                } else {
+                    updateItem.isHidden = true
+                }
+            }
+        }
+        task.resume()
+    }
+
+    // Simple semver comparison: returns true if a > b
+    func isNewer(_ a: String, than b: String) -> Bool {
+        let av = a.split(separator: ".").compactMap { Int($0) }
+        let bv = b.split(separator: ".").compactMap { Int($0) }
+        for i in 0..<max(av.count, bv.count) {
+            let x = i < av.count ? av[i] : 0
+            let y = i < bv.count ? bv[i] : 0
+            if x != y { return x > y }
+        }
+        return false
+    }
+
+    func pulseUpdateBadge() {
+        var count = 0
+        let pulse = Timer(timeInterval: 0.4, repeats: true) { t in
+            trayItem.button?.title = count % 2 == 0 ? "⬆" : ""
+            if !iconPath.isEmpty, let img = NSImage(contentsOfFile: iconPath) {
+                img.size = NSSize(width: 18, height: 18)
+                trayItem.button?.image = count % 2 == 0 ? nil : img
+            }
+            count += 1
+            if count >= 6 { // 3 flashes
+                t.invalidate()
+                trayItem.button?.title = ""
+                if !iconPath.isEmpty, let img = NSImage(contentsOfFile: iconPath) {
+                    img.size = NSSize(width: 18, height: 18)
+                    trayItem.button?.image = img
+                }
+            }
+        }
+        RunLoop.main.add(pulse, forMode: .common)
+    }
+
+    @objc func runUpdate() {
+        let npm = "/opt/homebrew/bin/npm"
+        openTerminal(command: npm + " install -g @meshxdata/fops")
+    }
+
+    // Rebuild Compose submenu each time it opens
+    func menuWillOpen(_ m: NSMenu) {
+        guard m === composeMenu else { return }
+        m.removeAllItems()
+        let loading = NSMenuItem(title: "Loading services…", action: nil, keyEquivalent: "")
+        loading.isEnabled = false
+        m.addItem(loading)
+
+        compose(["ps", "--format", "json"], capture: true) { out, _ in
+            m.removeAllItems()
+            let services = parseServices(out)
+            if services.isEmpty {
+                let none = NSMenuItem(title: "No services found", action: nil, keyEquivalent: "")
+                none.isEnabled = false
+                m.addItem(none)
+                return
+            }
+            for svc in services {
+                let dot    = svc.state == "running" ? "● " : "○ "
+                let svcItem = NSMenuItem(title: dot + svc.label, action: nil, keyEquivalent: "")
+                let sub    = NSMenu()
+
+                let logsItem = NSMenuItem(title: "Logs", action: #selector(AppDelegate.noop), keyEquivalent: "")
+                logsItem.representedObject = svc.name
+                logsItem.target = self
+                logsItem.action = #selector(AppDelegate.openLogs(_:))
+                sub.addItem(logsItem)
+
+                let startSvc = NSMenuItem(title: "Start", action: #selector(AppDelegate.startService(_:)), keyEquivalent: "")
+                startSvc.representedObject = svc.name
+                startSvc.target = self
+                startSvc.isEnabled = svc.state != "running"
+                sub.addItem(startSvc)
+
+                let stopSvc = NSMenuItem(title: "Stop", action: #selector(AppDelegate.stopService(_:)), keyEquivalent: "")
+                stopSvc.representedObject = svc.name
+                stopSvc.target = self
+                stopSvc.isEnabled = svc.state == "running"
+                sub.addItem(stopSvc)
+
+                let restartSvc = NSMenuItem(title: "Restart", action: #selector(AppDelegate.restartService(_:)), keyEquivalent: "")
+                restartSvc.representedObject = svc.name
+                restartSvc.target = self
+                sub.addItem(restartSvc)
+
+                let buildItem = NSMenuItem(title: "Build", action: #selector(AppDelegate.buildService(_:)), keyEquivalent: "")
+                buildItem.representedObject = svc.name
+                buildItem.target = self
+                sub.addItem(buildItem)
+
+                let execItem = NSMenuItem(title: "Exec Shell", action: #selector(AppDelegate.execService(_:)), keyEquivalent: "")
+                execItem.representedObject = svc.name
+                execItem.target = self
+                sub.addItem(execItem)
+
+                // Switch Branch submenu — populated lazily when opened
+                let fm = FileManager.default
+                if !svc.dir.isEmpty {
+                    sub.addItem(NSMenuItem.separator())
+                    let branchParent = NSMenuItem(title: "Switch Branch", action: nil, keyEquivalent: "")
+                    let branchMenu   = NSMenu()
+                    let branchDelegate = BranchMenuDelegate(dir: svc.dir, svc: svc.name)
+                    branchMenu.delegate = branchDelegate
+                    branchParent.submenu = branchMenu
+                    // Keep delegate alive via the menu item
+                    branchParent.representedObject = branchDelegate
+                    sub.addItem(branchParent)
+                }
+
+                svcItem.submenu = sub
+                m.addItem(svcItem)
+            }
+        }
+    }
+
+    @objc func noop() {}
+
+    // ── Stack-level actions ───────────────────────────────────────────────────
+
+    func refresh() {
+        isRunning { up in
+            self.running = up
+            statusMenuItem.title = up ? "● Running" : "○ Stopped"
+            startItem.isEnabled   = !up && !self.busy
+            stopItem.isEnabled    =  up && !self.busy
+            restartItem.isEnabled =  up && !self.busy
+        }
+        self.refreshFrontendMode()
+    }
+
+    func refreshFrontendMode() {
+        compose(["ps", "--format", "json", "--status", "running"], capture: true) { out, _ in
+            let services = parseServices(out)
+            let names = services.map { $0.name }
+            let devRunning  = names.contains("foundation-frontend-dev")
+            let prodRunning = names.contains("foundation-frontend")
+            if devRunning {
+                frontendModeItem.title = "Frontend: Dev (switch to Prod)"
+                frontendModeItem.isEnabled = true
+            } else if prodRunning {
+                frontendModeItem.title = "Frontend: Prod (switch to Dev)"
+                frontendModeItem.isEnabled = true
+            } else {
+                frontendModeItem.title = "Frontend: stopped"
+                frontendModeItem.isEnabled = false
+            }
+        }
+    }
+
+    func setBusy(_ b: Bool, label: String) {
+        busy = b
+        statusMenuItem.title = label
+        [startItem, stopItem, restartItem].forEach { $0.isEnabled = false }
+    }
+
+    @objc func startStack() {
+        guard !busy else { return }
+        setBusy(true, label: "Starting…")
+        compose(["up", "-d"]) { _, _ in self.busy = false; self.refresh() }
+    }
+
+    @objc func stopStack() {
+        guard !busy else { return }
+        setBusy(true, label: "Stopping…")
+        compose(["down"]) { _, _ in self.busy = false; self.refresh() }
+    }
+
+    @objc func restartStack() {
+        guard !busy else { return }
+        setBusy(true, label: "Restarting…")
+        compose(["restart"]) { _, _ in self.busy = false; self.refresh() }
+    }
+
+    var spinnerTimer: Timer?
+    var spinnerFrame = 0
+    let spinnerFrames = ["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"]
+
+    func startSpinner(label: String) {
+        frontendModeItem.isEnabled = false
+        frontendModeItem.title = "Frontend: \\(label)"
+        // Use AttributedTitle to render grey text
+        let attrs: [NSAttributedString.Key: Any] = [
+            .foregroundColor: NSColor.secondaryLabelColor
+        ]
+        frontendModeItem.attributedTitle = NSAttributedString(string: "Frontend: \\(label)", attributes: attrs)
+        spinnerFrame = 0
+        spinnerTimer?.invalidate()
+        trayItem.button?.image = nil
+        let t = Timer(timeInterval: 0.1, repeats: true) { _ in
+            let frame = self.spinnerFrames[self.spinnerFrame % self.spinnerFrames.count]
+            trayItem.button?.title = frame
+            let str = NSAttributedString(string: "\\(frame) Frontend: \\(label)", attributes: attrs)
+            frontendModeItem.attributedTitle = str
+            self.spinnerFrame += 1
+        }
+        RunLoop.main.add(t, forMode: .common)
+        spinnerTimer = t
+    }
+
+    func stopSpinner() {
+        spinnerTimer?.invalidate()
+        spinnerTimer = nil
+        frontendModeItem.attributedTitle = nil
+        trayItem.button?.title = ""
+        if !iconPath.isEmpty, let img = NSImage(contentsOfFile: iconPath) {
+            img.size = NSSize(width: 18, height: 18)
+            trayItem.button?.image = img
+        } else {
+            trayItem.button?.title = "F"
+        }
+    }
+
+    @objc func switchFrontendMode() {
+        frontendModeItem.isEnabled = false
+        compose(["ps", "--format", "json", "--status", "running"], capture: true) { out, _ in
+            let names = parseServices(out).map { $0.name }
+            if names.contains("foundation-frontend-dev") {
+                self.startSpinner(label: "switching to Prod…")
+                compose(["stop", "foundation-frontend-dev"]) { _, _ in
+                    run(docker(), ["compose", "--profile", "frontend-prod", "up", "-d", "foundation-frontend"]) { _, _ in
+                        self.stopSpinner()
+                        self.refreshFrontendMode()
+                    }
+                }
+            } else if names.contains("foundation-frontend") {
+                self.startSpinner(label: "switching to Dev…")
+                compose(["stop", "foundation-frontend"]) { _, _ in
+                    compose(["up", "-d", "foundation-frontend-dev"]) { _, _ in
+                        self.stopSpinner()
+                        self.refreshFrontendMode()
+                    }
+                }
+            }
+        }
+    }
+
+    @objc func openBrowser() {
+        let url = ProcessInfo.processInfo.environment["FOUNDATION_URL"] ?? "http://127.0.0.1:3002"
+        if let u = URL(string: url) { NSWorkspace.shared.open(u) }
+    }
+
+    @objc func checkoutBranch(_ sender: NSMenuItem) {
+        guard let arr = sender.representedObject as? [String], arr.count == 3 else { return }
+        let dir = arr[0]; let svc = arr[1]; let branch = arr[2]
+        run(git(), ["checkout", branch], cwd: dir) { _, ok in
+            if ok { compose(["up", "-d", "--build", svc]) }
+        }
+    }
+
+    @objc func runDoctor() {
+        let fops = "/opt/homebrew/bin/fops"
+        let cd   = composeRoot.isEmpty ? "" : "cd \\"\\(composeRoot)\\" && "
+        openTerminal(command: cd + fops + " doctor")
+    }
+
+    // ── Per-service actions ───────────────────────────────────────────────────
+
+    @objc func openLogs(_ sender: NSMenuItem) {
+        guard let svc = sender.representedObject as? String else { return }
+        let cmd = docker() + " compose" + (composeRoot.isEmpty ? "" : " --project-directory \\"\\(composeRoot)\\"") + " logs -f --tail=200 " + svc
+        openTerminal(command: cmd)
+    }
+
+    @objc func startService(_ sender: NSMenuItem) {
+        guard let svc = sender.representedObject as? String else { return }
+        compose(["start", svc])
+    }
+
+    @objc func stopService(_ sender: NSMenuItem) {
+        guard let svc = sender.representedObject as? String else { return }
+        compose(["stop", svc])
+    }
+
+    @objc func restartService(_ sender: NSMenuItem) {
+        guard let svc = sender.representedObject as? String else { return }
+        compose(["restart", svc])
+    }
+
+    @objc func buildService(_ sender: NSMenuItem) {
+        guard let svc = sender.representedObject as? String else { return }
+        // svc is the docker compose service name e.g. "foundation-backend" — strip prefix for fops build target
+        let target = svc.hasPrefix("foundation-") ? String(svc.dropFirst("foundation-".count)) : svc
+        let fops = "/opt/homebrew/bin/fops"
+        let cd   = composeRoot.isEmpty ? "" : "cd \\"\\(composeRoot)\\" && "
+        let cmd  = cd + fops + " build " + target
+        openTerminal(command: cmd)
+    }
+
+    @objc func execService(_ sender: NSMenuItem) {
+        guard let svc = sender.representedObject as? String else { return }
+        let proj = composeRoot.isEmpty ? "" : " --project-directory \\"\\(composeRoot)\\""
+        // Try bash first, fall back to sh
+        let cmd = docker() + " compose\\(proj) exec \\(svc) bash 2>/dev/null || " + docker() + " compose\\(proj) exec \\(svc) sh"
+        openTerminal(command: cmd)
+    }
+
+    @objc func togglePlugin(_ sender: NSMenuItem) {
+        guard let id = sender.representedObject as? String else { return }
+        let enabled = readPluginEnabled(id)
+        let subCmd = enabled ? "disable" : "enable"
+        // Try homebrew path, fall back to PATH
+        let fopsBin: String
+        if FileManager.default.isExecutableFile(atPath: "/opt/homebrew/bin/fops") {
+            fopsBin = "/opt/homebrew/bin/fops"
+        } else if FileManager.default.isExecutableFile(atPath: "/usr/local/bin/fops") {
+            fopsBin = "/usr/local/bin/fops"
+        } else {
+            fopsBin = "fops"
+        }
+        run(fopsBin, ["plugin", subCmd, id])
+    }
+
+}
+
+// ── BranchMenuDelegate ────────────────────────────────────────────────────────
+// Fetches branches lazily when the submenu opens, then checks out on click.
+
+class BranchMenuDelegate: NSObject, NSMenuDelegate {
+    let dir: String
+    let svc: String
+    init(dir: String, svc: String) { self.dir = dir; self.svc = svc }
+
+    func menuWillOpen(_ menu: NSMenu) {
+        menu.removeAllItems()
+        let loading = NSMenuItem(title: "Fetching branches…", action: nil, keyEquivalent: "")
+        loading.isEnabled = false
+        menu.addItem(loading)
+
+        DispatchQueue.global().async {
+            // fetch to get latest remote branches
+            let fp = Process()
+            fp.executableURL = URL(fileURLWithPath: git())
+            fp.arguments = ["fetch", "--all", "--prune"]
+            fp.currentDirectoryURL = URL(fileURLWithPath: self.dir)
+            fp.standardOutput = FileHandle.nullDevice
+            fp.standardError  = FileHandle.nullDevice
+            try? fp.run(); fp.waitUntilExit()
+
+            // list all branches (local + remote), deduplicated
+            let bp = Process(); let pipe = Pipe()
+            bp.executableURL = URL(fileURLWithPath: git())
+            bp.arguments = ["branch", "-a", "--format=%(refname:short)"]
+            bp.currentDirectoryURL = URL(fileURLWithPath: self.dir)
+            bp.standardOutput = pipe
+            bp.standardError  = FileHandle.nullDevice
+            try? bp.run(); bp.waitUntilExit()
+            let raw = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+
+            // Current branch — use rev-parse so detached HEAD returns "HEAD"
+            let cb = Process(); let cbPipe = Pipe()
+            cb.executableURL = URL(fileURLWithPath: git())
+            cb.arguments = ["rev-parse", "--abbrev-ref", "HEAD"]
+            cb.currentDirectoryURL = URL(fileURLWithPath: self.dir)
+            cb.standardOutput = cbPipe
+            cb.standardError  = FileHandle.nullDevice
+            try? cb.run(); cb.waitUntilExit()
+            let current = (String(data: cbPipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? "")
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            let isDetached = current == "HEAD" || current.isEmpty
+
+            // If detached, find which branches contain the current commit
+            var containsBranches = Set<String>()
+            if isDetached {
+                let cp = Process(); let cpipe = Pipe()
+                cp.executableURL = URL(fileURLWithPath: git())
+                cp.arguments = ["branch", "-a", "--contains", "HEAD", "--format=%(refname:short)"]
+                cp.currentDirectoryURL = URL(fileURLWithPath: self.dir)
+                cp.standardOutput = cpipe
+                cp.standardError  = FileHandle.nullDevice
+                try? cp.run(); cp.waitUntilExit()
+                let cout = String(data: cpipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+                for line in cout.components(separatedBy: "\\n") {
+                    var b = line.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if b.isEmpty || b.contains("HEAD") { continue }
+                    if b.hasPrefix("origin/") { b = String(b.dropFirst("origin/".count)) }
+                    containsBranches.insert(b)
+                }
+            }
+
+            // Deduplicate: strip "origin/" prefix, ignore HEAD refs
+            var seen = Set<String>()
+            var branches: [String] = []
+            for line in raw.components(separatedBy: "\\n") {
+                var b = line.trimmingCharacters(in: .whitespacesAndNewlines)
+                if b.isEmpty || b.contains("HEAD") { continue }
+                if b.hasPrefix("origin/") { b = String(b.dropFirst("origin/".count)) }
+                if seen.insert(b).inserted { branches.append(b) }
+            }
+            branches.sort()
+
+            DispatchQueue.main.async {
+                menu.removeAllItems()
+
+                // Show detached HEAD notice
+                if isDetached {
+                    let h = NSMenuItem(title: "⚠ Detached HEAD", action: nil, keyEquivalent: "")
+                    h.isEnabled = false
+                    menu.addItem(h)
+                    menu.addItem(NSMenuItem.separator())
+                }
+
+                if branches.isEmpty {
+                    let none = NSMenuItem(title: "No branches found", action: nil, keyEquivalent: "")
+                    none.isEnabled = false
+                    menu.addItem(none)
+                    return
+                }
+                for branch in branches {
+                    let isCurrent = !isDetached && branch == current
+                    let isPinned  = isDetached && containsBranches.contains(branch)
+                    let prefix = isCurrent ? "✓ " : (isPinned ? "◆ " : "  ")
+                    let item = NSMenuItem(title: prefix + branch, action: #selector(AppDelegate.checkoutBranch(_:)), keyEquivalent: "")
+                    item.representedObject = [self.dir, self.svc, branch] as AnyObject
+                    item.target = NSApp.delegate as? AppDelegate
+                    item.isEnabled = !isCurrent
+                    menu.addItem(item)
+                }
+            }
+        }
+    }
+}
+
+// ── PluginMenuDelegate ────────────────────────────────────────────────────────
+// Populates the Plugins submenu lazily; clicking a plugin item toggles it.
+
+class PluginMenuDelegate: NSObject, NSMenuDelegate {
+    func menuWillOpen(_ menu: NSMenu) {
+        menu.removeAllItems()
+        if allPlugins.isEmpty {
+            let none = NSMenuItem(title: "No plugins installed", action: nil, keyEquivalent: "")
+            none.isEnabled = false
+            menu.addItem(none)
+            return
+        }
+        for plugin in allPlugins {
+            let enabled = readPluginEnabled(plugin.id)
+            let prefix = enabled ? "✓ " : "  "
+            let item = NSMenuItem(
+                title: prefix + plugin.name,
+                action: #selector(AppDelegate.togglePlugin(_:)),
+                keyEquivalent: ""
+            )
+            item.representedObject = plugin.id as AnyObject
+            item.target = NSApp.delegate as? AppDelegate
+            menu.addItem(item)
+        }
+    }
+}
+
+let pluginsMenuDelegate = PluginMenuDelegate()
+
+let delegate = AppDelegate()
+app.delegate = delegate
+app.run()
+`);
+
+        const trayEnv = {
+          ...process.env,
+          FOUNDATION_API_URL: apiUrl,
+          FOUNDATION_URL: "http://127.0.0.1:3002",
+          FOUNDATION_ICON: iconPath,
+          FOUNDATION_COMPOSE_ROOT: composeRoot,
+          FOPS_VERSION: fopsVersion,
+          FOPS_PLUGINS: fopsPluginsJson,
+        };
+
+        console.log(ACCENT("  Foundation tray started — look for the icon in your menu bar"));
+
+        const child = spawn("swift", [swiftTray], {
+          stdio: "ignore",
+          detached: true,
+          env: trayEnv,
+        });
+        child.unref();
+      });
   });
 
   // ─── Landscape cache state (used by tools + service) ────────────────────
@@ -479,6 +2191,7 @@ foundation_entity is only for: SQL query action, or if foundation_graphql return
       "foundation_iam",
       "foundation_iam_manage",
       "foundation_graphql",
+      "foundation_align",
       "memory",
     ],
     maxIterations: resolveFoundationMaxIterations(),