@meshxdata/fops 0.0.3 → 0.0.4

package/src/agent/context.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import { execa } from "execa";
 import { loadSkills, searchKnowledge } from "../plugins/index.js";
@@ -17,8 +18,23 @@ When suggesting commands, ALWAYS use \`fops\` commands, not raw \`make\` or \`gi
 **Always suggest 2–3 commands** so the user can pick. Pair a primary action with a follow-up (e.g. restart + logs, doctor + up).
 
 ## Accuracy Rules
-- ALWAYS check the container status context carefully. If ANY container is exited, unhealthy, or failed, report it — never claim "all healthy" when failures exist.
-- When containers have failed, lead with the failures and suggest diagnostics.
+- ALWAYS check BOTH container status AND service health context. Container "running (healthy)" only means the Docker healthcheck passed — the service may still be initializing, have failed migrations, or be unresponsive.
+- Cross-reference the "Service health" section (HTTP endpoint checks) with container status. If any endpoint is DOWN or unreachable, the stack is NOT fully ready — report this even if containers look healthy.
+- If ANY container is exited, unhealthy, or failed, report it — never claim "all healthy" when failures exist.
+- When containers have failed or services are unreachable, lead with the failures and suggest diagnostics.
+- If "Missing images" context is present, report which images are missing and whether they need building or pulling. Suggest \`fops build\` for buildable images or \`make download\` (after ECR auth) for registry images.
+
+## Auto-Fix Rules
+When you detect failing containers, DO NOT just report them — diagnose and fix:
+1. Read the container logs provided in context. Look for: missing files/volumes, permission errors, config issues, dependency failures, image problems.
+2. Apply the RIGHT fix based on the diagnosis:
+   - **Restarting/crash-loop with no logs**: likely a missing volume mount or stale image → suggest \`fops build\` then \`docker compose up -d <service>\`
+   - **Image not found / pull access denied**: missing image → \`fops build\` (for buildable) or \`fops download\` (for registry images)
+   - **Dependency unhealthy**: fix the dependency first, then restart dependents → \`docker compose up -d <dep-service>\`
+   - **Port conflict**: another process using the port → identify and kill or change port in .env
+   - **Migration failed**: database issue → \`docker compose restart <service>-migrations\`
+   - **Config error / env missing**: check .env file → \`fops setup\`
+3. Output the fix commands in fenced bash blocks so they auto-execute. Be decisive — don't hedge with "you might try", just say what to do and give the command.
 
 ## Security Rules
 - Never output API keys, passwords, or tokens in responses
@@ -42,8 +58,10 @@ async function gatherDockerStatus(root) {
       if (!parsed.length) return "No containers running.";
 
       let healthy = 0, unhealthy = 0, exited = 0, running = 0;
+      const failingContainers = [];
       const services = parsed.map((o) => {
         const name = o.Name || o.name || o.Service || "?";
+        const service = o.Service || name;
         const state = (o.State || "").toLowerCase();
         const status = o.Status || "";
         const health = (o.Health || "").toLowerCase();
@@ -51,11 +69,13 @@ async function gatherDockerStatus(root) {
 
         if (state === "exited" || state === "dead") {
           exited++;
+          failingContainers.push(service);
           return `${name}: EXITED (code ${exitCode}) — ${status}`;
         }
-        if (health === "unhealthy") {
+        if (health === "unhealthy" || state === "restarting") {
           unhealthy++;
-          return `${name}: UNHEALTHY — ${status}`;
+          failingContainers.push(service);
+          return `${name}: ${state === "restarting" ? "RESTARTING" : "UNHEALTHY"} — ${status}`;
         }
         if (state === "running" && (health === "healthy" || !health)) {
           healthy++;
@@ -69,15 +89,36 @@ async function gatherDockerStatus(root) {
       const summary = [];
       if (running) summary.push(`${running} running`);
       if (healthy) summary.push(`${healthy} healthy`);
-      if (unhealthy) summary.push(`${unhealthy} UNHEALTHY`);
+      if (unhealthy) summary.push(`${unhealthy} UNHEALTHY/RESTARTING`);
       if (exited) summary.push(`${exited} EXITED/FAILED`);
 
       let header = `Container summary: ${parsed.length} total — ${summary.join(", ")}`;
       if (unhealthy || exited) {
-        header += "\n⚠ ATTENTION: Some containers are failing. Diagnose and report the failures.";
+        header += "\n⚠ ATTENTION: Some containers are failing. Diagnose and fix the failures.";
+      }
+
+      let result = header + "\n\nContainer details:\n" + services.join("\n");
+
+      // Auto-collect logs from failing containers (last 15 lines each, max 3)
+      if (failingContainers.length > 0) {
+        const logsToFetch = failingContainers.slice(0, 3);
+        const logResults = await Promise.all(
+          logsToFetch.map(async (svc) => {
+            try {
+              const { stdout, stderr } = await execa(
+                "docker", ["compose", "logs", svc, "--tail", "15", "--no-color"],
+                { cwd: root, reject: false, timeout: 5000 },
+              );
+              const output = (stdout || "") + (stderr || "");
+              if (output.trim()) return `\n--- Logs: ${svc} (last 15 lines) ---\n${output.trim()}`;
+            } catch { /* skip */ }
+            return `\n--- Logs: ${svc} ---\n(no logs available)`;
+          }),
+        );
+        result += "\n" + logResults.join("\n");
       }
 
-      return header + "\n\nContainer details:\n" + services.join("\n");
+      return result;
     }
   } catch {
     return "Docker: not available or not running.";
@@ -85,6 +126,95 @@ async function gatherDockerStatus(root) {
   return null;
 }
 
+/**
+ * HTTP GET with timeout. Returns { ok, status } or { ok: false, error }.
+ */
+function httpPing(url, timeout = 3000) {
+  return new Promise((resolve) => {
+    const req = http.get(url, { timeout }, (res) => {
+      res.resume(); // drain
+      resolve({ ok: res.statusCode < 500, status: res.statusCode });
+    });
+    req.on("error", (err) => resolve({ ok: false, error: err.code || err.message }));
+    req.on("timeout", () => { req.destroy(); resolve({ ok: false, error: "TIMEOUT" }); });
+  });
+}
+
+const SERVICE_ENDPOINTS = [
+  { name: "Backend API", url: "http://localhost:9001/api/data/mesh/list?per_page=1", port: 9001 },
+  { name: "Frontend", url: "http://localhost:3002", port: 3002 },
+  { name: "Storage Engine (MinIO)", url: "http://localhost:9002/minio/health/live", port: 9002 },
+  { name: "Trino", url: "http://localhost:8081/v1/info", port: 8081 },
+];
+
+async function gatherServiceHealth() {
+  const results = await Promise.all(
+    SERVICE_ENDPOINTS.map(async ({ name, url }) => {
+      const r = await httpPing(url);
+      if (r.ok) return `${name}: UP (HTTP ${r.status})`;
+      return `${name}: DOWN (${r.error || "HTTP " + r.status})`;
+    }),
+  );
+  return "Service health (HTTP checks):\n" + results.join("\n");
+}
+
+/**
+ * Detect which compose images are missing locally.
+ * Compares `docker compose config --images` against `docker images`.
+ */
+async function gatherMissingImages(root) {
+  try {
+    // Get all images required by compose
+    const { stdout: configImages } = await execa(
+      "docker", ["compose", "config", "--images"],
+      { cwd: root, reject: false, timeout: 10000 },
+    );
+    if (!configImages?.trim()) return null;
+
+    const required = [...new Set(configImages.trim().split("\n").filter(Boolean))];
+
+    // Get locally available images
+    const { stdout: localImages } = await execa(
+      "docker", ["images", "--format", "{{.Repository}}:{{.Tag}}"],
+      { reject: false, timeout: 5000 },
+    );
+    const localSet = new Set((localImages || "").trim().split("\n").filter(Boolean));
+
+    // Also check by repo without tag (docker sometimes lists <none> tag)
+    const localRepos = new Set(
+      (localImages || "").trim().split("\n").filter(Boolean).map((i) => i.split(":")[0]),
+    );
+
+    // Find which compose services have build contexts
+    const { stdout: configJson } = await execa(
+      "docker", ["compose", "config", "--format", "json"],
+      { cwd: root, reject: false, timeout: 10000 },
+    );
+    const buildableImages = new Set();
+    if (configJson?.trim()) {
+      try {
+        const config = JSON.parse(configJson);
+        for (const [, svc] of Object.entries(config.services || {})) {
+          if (svc.build && svc.image) buildableImages.add(svc.image);
+        }
+      } catch { /* ignore */ }
+    }
+
+    const missing = required.filter((img) => !localSet.has(img) && !localRepos.has(img.split(":")[0]));
+    if (missing.length === 0) return null;
+
+    const lines = missing.map((img) => {
+      const action = buildableImages.has(img) ? "needs BUILD (has build context)" : "needs PULL from registry";
+      return `  ${img} — ${action}`;
+    });
+
+    return `Missing images (${missing.length}/${required.length}):\n` + lines.join("\n") +
+      "\n\nTo build local images: make build\nTo pull registry images: make download (requires ECR auth)";
+  } catch {
+    return null;
+  }
+}
+
 async function gatherImageAges(root) {
   try {
     const { stdout: imgOut } = await execa("docker", ["compose", "images", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
@@ -152,9 +282,9 @@ function checkEnvFile(root) {
   return null;
 }
 
-async function gatherSkills() {
+async function gatherSkills(registry) {
   try {
-    const skills = await loadSkills();
+    const skills = await loadSkills(registry);
     if (skills.length) {
       return "## Additional Skills\n" + skills.map((s) => s.content).join("\n\n");
     }
@@ -169,16 +299,20 @@ export async function gatherStackContext(root, { registry, message } = {}) {
 
   if (root) {
     // Run all independent checks in parallel
-    const [dockerStatus, imageAges, prereqs, envInfo, skills, knowledge] = await Promise.all([
+    const [dockerStatus, serviceHealth, missingImages, imageAges, prereqs, envInfo, skills, knowledge] = await Promise.all([
       gatherDockerStatus(root),
+      gatherServiceHealth(),
+      gatherMissingImages(root),
       gatherImageAges(root),
       gatherPrereqs(),
       Promise.resolve(checkEnvFile(root)),
-      gatherSkills(),
+      gatherSkills(registry),
       registry && message ? searchKnowledge(registry, message) : Promise.resolve(null),
     ]);
 
     if (dockerStatus) parts.push(dockerStatus);
+    if (serviceHealth) parts.push(serviceHealth);
+    if (missingImages) parts.push(missingImages);
     if (imageAges) parts.push(imageAges);
     parts.push(prereqs);
     if (envInfo) parts.push(envInfo);
@@ -188,7 +322,7 @@ export async function gatherStackContext(root, { registry, message } = {}) {
     // No root — still check prereqs, skills, and knowledge
     const [prereqs, skills, knowledge] = await Promise.all([
       gatherPrereqs(),
-      gatherSkills(),
+      gatherSkills(registry),
       registry && message ? searchKnowledge(registry, message) : Promise.resolve(null),
     ]);
     parts.push(prereqs);

package/src/agent/index.js

@@ -1,2 +1,3 @@
 export { runAgentSingleTurn, runAgentInteractive } from "./agent.js";
 export { gatherStackContext } from "./context.js";
+export { BUILTIN_AGENTS, loadBuiltinAgents } from "./agents.js";

package/src/agent/llm.js

@@ -37,10 +37,10 @@ function buildConversationPrompt(messages) {
 /**
  * Run a prompt through Claude Code CLI (uses OAuth auth)
  */
-export async function runViaClaudeCode(prompt, systemPrompt) {
+export async function runViaClaudeCode(prompt, systemPrompt, { replaceSystemPrompt = false } = {}) {
   const args = ["-p", "--no-session-persistence"];
   if (systemPrompt) {
-    args.push("--append-system-prompt", systemPrompt);
+    args.push(replaceSystemPrompt ? "--system-prompt" : "--append-system-prompt", systemPrompt);
   }
 
   const { stdout } = await execa("claude", args, {
@@ -53,12 +53,20 @@ export async function runViaClaudeCode(prompt, systemPrompt) {
 }
 
 /**
- * Stream response via Claude Code CLI with thinking display
+ * Stream response via Claude Code CLI with thinking display.
+ * Uses --output-format stream-json --include-partial-messages to get
+ * token-level streaming events (content_block_delta for text and thinking).
  */
-export async function streamViaClaudeCode(prompt, systemPrompt, onChunk, onThinking) {
-  const args = ["-p", "--no-session-persistence"];
+export async function streamViaClaudeCode(prompt, systemPrompt, onChunk, onThinking, onBlockStart, { replaceSystemPrompt = false } = {}) {
+  const args = [
+    "-p",
+    "--output-format", "stream-json",
+    "--verbose",
+    "--include-partial-messages",
+    "--no-session-persistence",
+  ];
   if (systemPrompt) {
-    args.push("--append-system-prompt", systemPrompt);
+    args.push(replaceSystemPrompt ? "--system-prompt" : "--append-system-prompt", systemPrompt);
   }
 
   const proc = execa("claude", args, {
@@ -68,14 +76,62 @@ export async function streamViaClaudeCode(prompt, systemPrompt, onChunk, onThink
   });
 
   let fullText = "";
+  let lineBuf = "";
 
   proc.stdout.on("data", (chunk) => {
-    const text = chunk.toString();
-    fullText += text;
-    if (onChunk) onChunk(text);
+    lineBuf += chunk.toString();
+    const lines = lineBuf.split("\n");
+    lineBuf = lines.pop(); // keep incomplete line
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let evt;
+      try { evt = JSON.parse(line); } catch { continue; }
+
+      if (evt.type === "stream_event") {
+        const inner = evt.event;
+        if (inner?.type === "content_block_start") {
+          const blockType = inner.content_block?.type;
+          if (onBlockStart) onBlockStart(blockType);
+        } else if (inner?.type === "content_block_delta") {
+          if (inner.delta?.type === "thinking_delta" && inner.delta.thinking) {
+            if (onThinking) onThinking(inner.delta.thinking);
+          }
+          if (inner.delta?.type === "text_delta" && inner.delta.text) {
+            fullText += inner.delta.text;
+            if (onChunk) onChunk(inner.delta.text);
+          }
+        }
+      } else if (evt.type === "assistant") {
+        // Final assistant message — extract any remaining text
+        const content = evt.message?.content || [];
+        const textParts = content.filter(b => b.type === "text").map(b => b.text).join("");
+        // Only use this if streaming didn't capture everything
+        if (textParts && !fullText) {
+          fullText = textParts;
+          if (onChunk) onChunk(textParts);
+        }
+      }
+    }
   });
 
   await proc;
+
+  // Process any remaining buffer
+  if (lineBuf.trim()) {
+    try {
+      const evt = JSON.parse(lineBuf);
+      if (evt.type === "assistant") {
+        const content = evt.message?.content || [];
+        const textParts = content.filter(b => b.type === "text").map(b => b.text).join("");
+        if (textParts && !fullText) {
+          fullText = textParts;
+          if (onChunk) onChunk(textParts);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
   return fullText;
 }
 
@@ -91,10 +147,25 @@ export async function streamAssistantReply(root, messages, systemContent, opts)
   try {
     if (useClaudeCode) {
       const prompt = buildConversationPrompt(messages);
-      fullText = await streamViaClaudeCode(prompt, systemContent, (chunk) => {
-        display.setStatus("Responding");
-        display.appendContent(chunk);
-      });
+      fullText = await streamViaClaudeCode(
+        prompt,
+        systemContent,
+        (chunk) => {
+          display.appendContent(chunk);
+        },
+        (thinking) => {
+          display.appendThinking(thinking);
+        },
+        (blockType) => {
+          if (blockType === "thinking") {
+            display.setStatus("Reasoning");
+          } else if (blockType === "text") {
+            display.setThinking(""); // clear thinking preview
+            display.setStatus("Responding");
+          }
+        },
+        { replaceSystemPrompt: !!opts.replaceSystemPrompt },
+      );
     } else if (anthropicKey) {
       const { default: Anthropic } = await import("@anthropic-ai/sdk");
       const client = new Anthropic({ apiKey: anthropicKey });

package/src/auth/coda.js

@@ -67,7 +67,7 @@ export async function runCodaLogin() {
       default: false,
     }]);
     if (!overwrite) {
-      console.log(chalk.gray("Keeping existing Coda token."));
+      console.log(chalk.dim("Keeping existing Coda token."));
       return true;
     }
   }
@@ -77,11 +77,11 @@ export async function runCodaLogin() {
   console.log("");
   console.log(chalk.white("  To connect Foundation to Coda, you need an API token."));
   console.log(chalk.white("  Here's how to get one:\n"));
-  console.log(chalk.gray("  1. Go to ") + chalk.cyan(CODA_ACCOUNT_URL));
-  console.log(chalk.gray("  2. Scroll to ") + chalk.white("\"API Settings\""));
-  console.log(chalk.gray("  3. Click ") + chalk.white("\"Generate API token\""));
-  console.log(chalk.gray("  4. Give it a name (e.g. \"Foundation CLI\")"));
-  console.log(chalk.gray("  5. Copy the token and paste it below"));
+  console.log(chalk.dim("  1. Go to ") + chalk.cyan(CODA_ACCOUNT_URL));
+  console.log(chalk.dim("  2. Scroll to ") + chalk.white("\"API Settings\""));
+  console.log(chalk.dim("  3. Click ") + chalk.white("\"Generate API token\""));
+  console.log(chalk.dim("  4. Give it a name (e.g. \"Foundation CLI\")"));
+  console.log(chalk.dim("  5. Copy the token and paste it below"));
   console.log("");
 
   const { openIt } = await inquirer.prompt([{
@@ -111,18 +111,18 @@ export async function runCodaLogin() {
     },
   }]);
 
-  console.log(chalk.gray("\n  Validating token..."));
+  console.log(chalk.dim("\n  Validating token..."));
   const result = await validateCodaToken(token.trim());
 
   if (!result.valid) {
     console.log(chalk.red(`\n  ${result.error}`));
-    console.log(chalk.gray("  Check the token and try again with: fops login coda\n"));
+    console.log(chalk.dim("  Check the token and try again with: fops login coda\n"));
     return false;
   }
 
   saveCodaToken(token);
   console.log(chalk.green(`\n  Coda login successful!`));
-  console.log(chalk.gray(`  Logged in as: ${result.name || result.loginId}`));
-  console.log(chalk.gray("  Token saved to ~/.fops.json\n"));
+  console.log(chalk.dim(`  Logged in as: ${result.name || result.loginId}`));
+  console.log(chalk.dim("  Token saved to ~/.fops.json\n"));
   return true;
 }

package/src/auth/login.js

@@ -9,10 +9,10 @@ const ANTHROPIC_KEYS_URL = "https://console.anthropic.com/settings/keys";
 
 export function authHelp() {
   console.log(chalk.yellow("No API key found. Try one of:"));
-  console.log(chalk.gray("  • Open " + chalk.cyan(ANTHROPIC_KEYS_URL) + " in your browser to sign in and create a key"));
-  console.log(chalk.gray("  • ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable"));
-  console.log(chalk.gray("  • ~/.claude/.credentials.json with anthropic_api_key or apiKey"));
-  console.log(chalk.gray("  • ~/.claude/settings.json with apiKeyHelper (script that prints the key)\n"));
+  console.log(chalk.dim("  • Open " + chalk.cyan(ANTHROPIC_KEYS_URL) + " in your browser to sign in and create a key"));
+  console.log(chalk.dim("  • ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable"));
+  console.log(chalk.dim("  • ~/.claude/.credentials.json with anthropic_api_key or apiKey"));
+  console.log(chalk.dim("  • ~/.claude/settings.json with apiKeyHelper (script that prints the key)\n"));
 }
 
 export function openBrowser(url) {
@@ -46,7 +46,7 @@ export function saveApiKey(apiKey) {
   fs.writeFileSync(CLAUDE_CREDENTIALS, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
 
   console.log(chalk.green("\nLogin successful"));
-  console.log(chalk.gray("Key saved to ~/.claude/.credentials.json\n"));
+  console.log(chalk.dim("Key saved to ~/.claude/.credentials.json\n"));
   return true;
 }
 
@@ -65,11 +65,11 @@ export async function offerClaudeLogin() {
   if (!opened) {
     console.log(chalk.yellow("  Could not open browser. Visit: " + ANTHROPIC_KEYS_URL + "\n"));
   }
-  console.log(chalk.gray("  1. Sign in and create an API key"));
-  console.log(chalk.gray("  2. Add it to ~/.claude/.credentials.json:"));
-  console.log(chalk.gray('     { "anthropic_api_key": "sk-ant-..." }'));
-  console.log(chalk.gray("  3. Or run: export ANTHROPIC_API_KEY=\"sk-ant-...\""));
-  console.log(chalk.gray("  4. Then run foundation chat again.\n"));
+  console.log(chalk.dim("  1. Sign in and create an API key"));
+  console.log(chalk.dim("  2. Add it to ~/.claude/.credentials.json:"));
+  console.log(chalk.dim('     { "anthropic_api_key": "sk-ant-..." }'));
+  console.log(chalk.dim("  3. Or run: export ANTHROPIC_API_KEY=\"sk-ant-...\""));
+  console.log(chalk.dim("  4. Then run foundation chat again.\n"));
   return true;
 }
 
@@ -310,7 +310,7 @@ export async function runLogin(options = {}) {
       },
     ]);
     if (!overwrite) {
-      console.log(chalk.gray("Keeping existing credentials."));
+      console.log(chalk.dim("Keeping existing credentials."));
       return true;
     }
   }
@@ -405,8 +405,8 @@ async function runDeviceLogin() {
       const url = `http://127.0.0.1:${port}`;
 
       console.log(chalk.blue("\nOpening browser for authentication...\n"));
-      console.log(chalk.gray(`  If browser doesn't open, visit: ${chalk.cyan(url)}\n`));
-      console.log(chalk.gray("  Waiting for authentication..."));
+      console.log(chalk.dim(`  If browser doesn't open, visit: ${chalk.cyan(url)}\n`));
+      console.log(chalk.dim("  Waiting for authentication..."));
 
       openBrowser(url);
     });

package/src/auth/oauth.js

@@ -153,9 +153,9 @@ export async function runOAuthLogin() {
 
           console.log(chalk.green("\nLogin successful"));
           if (process.platform === "darwin") {
-            console.log(chalk.gray("Token saved to macOS Keychain\n"));
+            console.log(chalk.dim("Token saved to macOS Keychain\n"));
           } else {
-            console.log(chalk.gray("Token saved to ~/.claude/.credentials.json\n"));
+            console.log(chalk.dim("Token saved to ~/.claude/.credentials.json\n"));
           }
 
           server.close();
@@ -187,8 +187,8 @@ export async function runOAuthLogin() {
       authUrl.searchParams.set("code_challenge_method", "S256");
 
       console.log(chalk.blue("\nOpening browser for Claude login...\n"));
-      console.log(chalk.gray(`  If browser doesn't open, visit:\n  ${chalk.cyan(authUrl.toString())}\n`));
-      console.log(chalk.gray("  Waiting for authentication..."));
+      console.log(chalk.dim(`  If browser doesn't open, visit:\n  ${chalk.cyan(authUrl.toString())}\n`));
+      console.log(chalk.dim("  Waiting for authentication..."));
 
       openBrowser(authUrl.toString());
     });

package/src/commands/index.js

@@ -4,12 +4,14 @@ import path from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 import { PKG } from "../config.js";
-import { rootDir, requireRoot, hasComposeInDir, isFoundationRoot, findComposeRootUp } from "../project.js";
-import { make } from "../shell.js";
+import { rootDir, requireRoot, hasComposeInDir, isFoundationRoot, findComposeRootUp, checkInitState } from "../project.js";
+import { execa } from "execa";
+import { make, dockerCompose } from "../shell.js";
 import { runSetup, runInitWizard } from "../setup/index.js";
 import { ensureEcrAuth } from "../setup/aws.js";
 import { runAgentSingleTurn, runAgentInteractive } from "../agent/index.js";
 import { runDoctor } from "../doctor.js";
+import { runFeatureFlags } from "../feature-flags.js";
 import { runLogin, runCodaLogin } from "../auth/index.js";
 import { runHook, loadSkills } from "../plugins/index.js";
 
@@ -104,14 +106,53 @@ export function registerCommands(program, registry) {
     .option("--no-chat", "Skip interactive AI assistant after startup")
     .action(async (opts) => {
       const root = requireRoot(program);
+
+      // Pre-flight: check if project is initialised
+      const initIssue = checkInitState(root);
+      if (initIssue) {
+        console.error(chalk.red(`\n  Project not ready: ${initIssue}.`));
+        console.error(chalk.dim("  Run `fops init` first to set up the project.\n"));
+        process.exit(1);
+      }
+
       await ensureEcrAuth(root);
       await runHook(registry, "before:up", { root });
-      const result = await make(root, "start");
+
+      // Detect stuck containers (restarting / unhealthy) and force-recreate them
+      const forceRecreate = [];
+      try {
+        const { stdout } = await execa("docker", ["compose", "ps", "--format", "json"], {
+          cwd: root, reject: false, timeout: 10000,
+        });
+        if (stdout?.trim()) {
+          for (const line of stdout.trim().split("\n").filter(Boolean)) {
+            try {
+              const svc = JSON.parse(line);
+              const state = (svc.State || "").toLowerCase();
+              const health = (svc.Health || "").toLowerCase();
+              if (state === "restarting" || health === "unhealthy") {
+                forceRecreate.push(svc.Service || svc.Name);
+              }
+            } catch {}
+          }
+        }
+      } catch {}
+
+      if (forceRecreate.length > 0) {
+        console.log(chalk.yellow(`  Recreating stuck containers: ${forceRecreate.join(", ")}`));
+        await dockerCompose(root, ["rm", "-f", "-s", ...forceRecreate]);
+      }
+
+      console.log(chalk.green("  Starting services..."));
+      const result = await dockerCompose(root, ["up", "-d", "--remove-orphans", "--pull", "always"]);
+      // Clear any trailing \r progress line from docker compose output
+      process.stdout.write("\x1b[2K\r");
       await runHook(registry, "after:up", { root });
       if (result.exitCode !== 0) {
         console.error(chalk.red(`\n  Some services failed to start (exit code ${result.exitCode}).`));
-        console.error(chalk.gray("  Run `fops doctor` to diagnose or `fops logs` to inspect.\n"));
-        process.exit(result.exitCode);
+        console.error(chalk.dim("  Dropping into debug agent to diagnose...\n"));
+        await runAgentInteractive(root, { registry, initialAgent: "debug" });
+        return;
       }
       if (opts.chat !== false) await runAgentInteractive(root, { registry });
     });
@@ -164,10 +205,28 @@ export function registerCommands(program, registry) {
 
   program
     .command("config")
-    .description("Launch interactive configuration (make config)")
+    .description("Toggle MX_FF_* feature flags and restart affected services")
     .action(async () => {
       const root = requireRoot(program);
-      await make(root, "config");
+      await runFeatureFlags(root);
+    });
+
+  program
+    .command("build")
+    .description("Build all Foundation service images from source")
+    .action(async () => {
+      const root = requireRoot(program);
+      await ensureEcrAuth(root);
+      await make(root, "build");
+    });
+
+  program
+    .command("download")
+    .description("Pull all container images from registry (requires ECR auth)")
+    .action(async () => {
+      const root = requireRoot(program);
+      await ensureEcrAuth(root);
+      await make(root, "download");
     });
 
   program
@@ -197,14 +256,14 @@ export function registerCommands(program, registry) {
     .action(async () => {
       const skills = await loadSkills(registry);
       if (skills.length === 0) {
-        console.log(chalk.gray("  No skills available."));
+        console.log(chalk.dim("  No skills available."));
         return;
       }
       console.log(chalk.bold.cyan("\n  Agent Skills\n"));
       for (const s of skills) {
-        const source = s.pluginId ? chalk.gray(`(plugin: ${s.pluginId})`) : chalk.gray("(built-in)");
+        const source = s.pluginId ? chalk.dim(`(plugin: ${s.pluginId})`) : chalk.dim("(built-in)");
         console.log(`  ${chalk.green("●")} ${chalk.bold(s.name)} ${source}`);
-        if (s.description) console.log(chalk.gray(`    ${s.description}`));
+        if (s.description) console.log(chalk.dim(`    ${s.description}`));
       }
       console.log("");
     });
@@ -219,15 +278,15 @@ export function registerCommands(program, registry) {
     .description("List installed plugins with status")
     .action(async () => {
       if (registry.plugins.length === 0) {
-        console.log(chalk.gray("  No plugins installed."));
-        console.log(chalk.gray("  Install plugins to ~/.fops/plugins/ or via npm (fops-plugin-*)."));
+        console.log(chalk.dim("  No plugins installed."));
+        console.log(chalk.dim("  Install plugins to ~/.fops/plugins/ or via npm (fops-plugin-*)."));
         return;
       }
       console.log(chalk.bold.cyan("\n  Installed Plugins\n"));
       for (const p of registry.plugins) {
-        const source = chalk.gray(`(${p.source})`);
-        console.log(`  ${chalk.green("●")} ${chalk.bold(p.name)} ${chalk.gray("v" + p.version)} ${source}`);
-        console.log(chalk.gray(`    id: ${p.id}  path: ${p.path}`));
+        const source = chalk.dim(`(${p.source})`);
+        console.log(`  ${chalk.green("●")} ${chalk.bold(p.name)} ${chalk.dim("v" + p.version)} ${source}`);
+        console.log(chalk.dim(`    id: ${p.id}  path: ${p.path}`));
       }
       console.log("");
     });

package/src/config.js

@@ -18,7 +18,7 @@ export const CLI_BRAND = {
 export function printFoundationBanner(cwd) {
   const cwdShort = cwd.replace(os.homedir(), "~");
   console.log(chalk.cyan(`  ${CLI_BRAND.title} ${CLI_BRAND.version}`));
-  console.log(chalk.gray(`  ${CLI_BRAND.byline}`));
-  console.log(chalk.gray(`  ${cwdShort}`));
+  console.log(chalk.dim(`  ${CLI_BRAND.byline}`));
+  console.log(chalk.dim(`  ${cwdShort}`));
   console.log("");
 }