@meshxdata/fops 0.0.1 → 0.0.3

package/README.md

@@ -1,4 +1,4 @@
-# Foundation CLI
+# Foundation Operator CLI (`fops`)
 
 Install and manage **Foundation** data mesh platforms from the terminal.
 
@@ -8,90 +8,112 @@ Install and manage **Foundation** data mesh platforms from the terminal.
 
 ```bash
 # Run without installing
-npx foundation doctor
+npx @meshxdata/fops doctor
 
 # Install globally
-npm install -g foundation
-# or
-pnpm add -g foundation
+npm install -g @meshxdata/fops
 ```
 
 **From repo (development)**
 
 ```bash
-cd foundation-compose/foundation-cli
+cd foundation-compose/operator-cli
 npm install
-npm link   # optional: use `foundation` from anywhere
+npm link   # optional: use `fops` from anywhere
 ```
 
 **Shell installer (optional)**
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/meshxdata/foundation-compose/main/foundation-cli/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/meshxdata/foundation-compose/main/operator-cli/install.sh | bash
 ```
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `foundation setup` | Full automated setup (`.env`, netrc reminder, submodules; use `--download` to pull images). Replaces `setup.sh`. |
-| `foundation init` | Initialize a Foundation project (submodules, `.env`); same as `setup` with default options |
-| `foundation up` | Start all services (`make start`) |
-| `foundation down` | Stop services; use `--clean` to remove volumes |
-| `foundation status` | Show service status |
-| `foundation logs [service]` | Stream logs (all or one service) |
-| `foundation doctor` | Check Docker, git, `.env`, project layout; use `--fix` to apply fixes |
-| `foundation config` | Launch interactive configuration |
-| `foundation bootstrap` | Create demo data mesh |
-| `foundation test` | Run health checks |
-| `foundation agent` | AI assistant for the stack. Interactive or single-turn with `-m "message"`. |
-| `foundation chat` | Same as `foundation agent` (interactive). |
+| `fops login` | Authenticate with Claude (default) or other services |
+| `fops login coda` | Authenticate with Coda (guided API token setup) |
+| `fops setup` | Full automated setup (`.env`, netrc reminder, submodules; use `--download` to pull images) |
+| `fops init` | Initialize a Foundation project. Interactive wizard when not in a project root. |
+| `fops up` | Start all services (`make start`); launches interactive AI assistant after startup |
+| `fops down` | Stop services; use `--clean` to remove volumes |
+| `fops status` | Show service status |
+| `fops logs [service]` | Stream logs (all or one service) |
+| `fops doctor` | Check Docker, git, `.env`, AWS/ECR, ports, services; use `--fix` to apply fixes |
+| `fops config` | Launch interactive configuration |
+| `fops bootstrap` | Create demo data mesh |
+| `fops test` | Run health checks |
+| `fops agent` | AI assistant for the stack. Interactive or single-turn with `-m "message"`. |
+| `fops chat` | Interactive AI assistant (same as `fops agent`) |
+| `fops skill list` | List available agent skills (built-in and plugin-provided) |
+| `fops plugin list` | List installed plugins |
+| `fops plugin install <source>` | Install a plugin from a local directory |
+| `fops plugin remove <id>` | Remove an installed plugin |
 
 ### AI Assistant (agent / chat)
 
-- **Interactive:** `foundation agent` or `foundation chat` — in-CLI chat (no Claude Code app). Uses Anthropic or OpenAI APIs with streaming.
-- **Single-turn:** `foundation agent -m "why are my containers failing?"` — one question, one reply; optional “run suggested command?” prompt.
+- **Interactive:** `fops agent` or `fops chat` — in-CLI chat with streaming responses and command execution.
+- **Single-turn:** `fops agent -m "why are my containers failing?"` — one question, one reply; optional "run suggested command?" prompt.
+- **Model override:** `fops agent --model claude-sonnet-4-20250514`
 
 **Auth** (checked in order):
 
-1. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` environment variable  
-2. `~/.claude/settings.json` → `apiKeyHelper` (script that prints the API key)  
-3. `~/.claude/.credentials.json` → `anthropic_api_key` or `apiKey`  
-4. `~/.claude.json` → `anthropic_api_key` or `apiKey`  
+1. Claude Code CLI OAuth (if `claude` is installed and authenticated)
+2. `ANTHROPIC_API_KEY` environment variable
+3. `~/.claude/settings.json` → `apiKeyHelper` (script that prints the API key)
+4. `~/.claude/.credentials.json` or `~/.claude.json` → `anthropic_api_key` / `apiKey`
+5. `OPENAI_API_KEY` environment variable (fallback; uses OpenAI-compatible models)
 
-On macOS, Claude Code stores keys in Keychain; use `apiKeyHelper` in `~/.claude/settings.json` pointing to a script that reads the key (e.g. from keychain) and prints it, or put a key in `~/.claude/.credentials.json`.  
+Run `fops login` to authenticate via OAuth browser flow, or `fops login --no-browser` to paste an API key directly.
 
-Install optional deps: `npm install @anthropic-ai/sdk openai`.
+**Coda** — Run `fops login coda` to set up your Coda API token. The wizard opens your browser to coda.io/account and guides you through generating and pasting the token. Token is validated via the Coda API and saved to `~/.fops.json`. You can also set `CODA_API_TOKEN` as an env var.
+
+### Doctor
+
+Checks prerequisites (Docker, Git, Node.js, AWS CLI), AWS/ECR access, project structure, Docker resources, port conflicts, running services, and image freshness. Plugins can register additional checks.
+
+On `--fix`, doctor can automatically:
+- Install Docker (macOS via Homebrew, Windows via winget, Linux via get.docker.com)
+- Start the Docker daemon
+- Fix AWS SSO sessions and ECR authentication
+- Create missing `.env` from `.env.example`
+- Run `fops init` for missing projects
+- Rebuild stale images
+
+### Plugins
+
+Plugins extend the CLI with custom commands, doctor checks, lifecycle hooks, and agent skills.
+
+- **Global plugins:** `~/.fops/plugins/<id>/` (each with `fops.plugin.json`)
+- **NPM plugins:** packages named `fops-plugin-*` or `@scope/fops-plugin-*`
 
 ## Usage
 
-Run from a **foundation-compose** clone (or any directory that contains `docker-compose.yaml` and `Makefile`). You can also set `FOUNDATION_ROOT` to point to your repo root.
+Run from a **foundation-compose** clone (or any directory containing `docker-compose.yaml` and `Makefile`). You can also set `FOUNDATION_ROOT` to point to your repo root.
 
 ```bash
 cd /path/to/foundation-compose
-foundation doctor
-foundation up
-foundation status
+fops doctor
+fops up
+fops status
 ```
 
 First-time setup:
 
 ```bash
-git clone https://github.com/meshxdata/foundation-compose
-cd foundation-compose
-npx foundation init
-npx foundation up
+fops init
+fops up
 ```
 
-## Project structure
-
-The CLI is split into modules under `src/` for long-term maintainability. See [STRUCTURE.md](STRUCTURE.md) for layout and how to add commands.
+The init wizard will prompt to clone the repository if no project is found.
 
 ## Requirements
 
 - Node.js >= 18
 - Docker (Docker Compose)
-- Git (for `foundation init` submodules)
+- Git (for submodules)
+- Claude CLI (bundled — installed automatically via `npm install`)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshxdata/fops",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "CLI to install and manage Foundation data mesh platforms",
   "keywords": [
     "foundation",
@@ -16,8 +16,8 @@
   "files": [
     "foundation.mjs",
     "src/",
-    "README.md",
-    "STRUCTURE.md"
+    "!src/**/*.test.js",
+    "README.md"
   ],
   "scripts": {
     "start": "node foundation.mjs",
@@ -25,6 +25,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@anthropic-ai/claude-code": "^1.0.0",
     "boxen": "^8.0.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",

package/src/agent/agent.js

@@ -1,9 +1,10 @@
 import chalk from "chalk";
 import { execa } from "execa";
 import { resolveAnthropicApiKey, resolveOpenAiApiKey, authHelp, offerClaudeLogin } from "../auth/index.js";
-import { renderSpinner, renderBanner, promptInput, selectOption } from "../ui/index.js";
+import { PKG } from "../config.js";
+import { renderBanner, promptInput, selectOption } from "../ui/index.js";
 import { FOUNDATION_SYSTEM_PROMPT, gatherStackContext } from "./context.js";
-import { hasClaudeCode, hasClaudeCodeAuth, runViaClaudeCode, streamAssistantReply } from "./llm.js";
+import { hasClaudeCode, hasClaudeCodeAuth, streamAssistantReply } from "./llm.js";
 
 /**
  * Render inline markdown: **bold**, *italic*, `code`
@@ -209,6 +210,7 @@ export async function askToRunCommand(root, replyText) {
 
 export async function runAgentSingleTurn(root, message, opts = {}) {
   const runSuggestions = opts.runSuggestions !== false;
+  const registry = opts.registry;
   const useClaudeCode = hasClaudeCode() && hasClaudeCodeAuth();
   const anthropicKey = resolveAnthropicApiKey();
   const openaiKey = resolveOpenAiApiKey();
@@ -218,36 +220,18 @@ export async function runAgentSingleTurn(root, message, opts = {}) {
     process.exit(1);
   }
 
-  const context = await gatherStackContext(root);
+  const context = await gatherStackContext(root, { registry, message });
   const systemContent = FOUNDATION_SYSTEM_PROMPT + "\n\n" + context;
-  let replyText = "";
-
-  const spinner = renderSpinner();
 
+  let replyText = "";
   try {
-    if (useClaudeCode) {
-      // Use Claude Code CLI with OAuth auth
-      replyText = await runViaClaudeCode(message, systemContent);
-    } else if (anthropicKey) {
-      const { default: Anthropic } = await import("@anthropic-ai/sdk");
-      const client = new Anthropic({ apiKey: anthropicKey });
-      const response = await client.messages.create({
-        model: opts.model || "claude-sonnet-4-20250514",
-        max_tokens: 2048, system: systemContent,
-        messages: [{ role: "user", content: message }],
-      });
-      replyText = response.content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
-    } else if (openaiKey) {
-      const OpenAI = (await import("openai")).default;
-      const client = new OpenAI({ apiKey: openaiKey });
-      const response = await client.chat.completions.create({
-        model: opts.model || "gpt-4o-mini", max_tokens: 2048,
-        messages: [{ role: "system", content: systemContent }, { role: "user", content: message }],
-      });
-      replyText = response.choices?.[0]?.message?.content ?? "";
-    }
+    replyText = await streamAssistantReply(
+      root,
+      [{ role: "user", content: message }],
+      systemContent,
+      opts,
+    );
   } catch (err) {
-    spinner.stop();
     if (err.code === "MODULE_NOT_FOUND" || err.message?.includes("Cannot find module")) {
       console.log(chalk.yellow("Install optional deps for agent: npm install @anthropic-ai/sdk openai"));
       process.exit(1);
@@ -266,7 +250,6 @@ export async function runAgentSingleTurn(root, message, opts = {}) {
     throw err;
   }
 
-  spinner.stop();
   console.log("");
   console.log(formatResponse(replyText));
   console.log("");
@@ -279,7 +262,8 @@ export async function runAgentSingleTurn(root, message, opts = {}) {
   }
 }
 
-export async function runAgentInteractive(root) {
+export async function runAgentInteractive(root, opts = {}) {
+  const registry = opts.registry;
   const useClaudeCode = hasClaudeCode() && hasClaudeCodeAuth();
   const anthropicKey = resolveAnthropicApiKey();
   const openaiKey = resolveOpenAiApiKey();
@@ -301,8 +285,8 @@ export async function runAgentInteractive(root) {
     }
   }
 
-  const context = await gatherStackContext(root);
-  const systemContent = FOUNDATION_SYSTEM_PROMPT + "\n\n" + context;
+  // Gather base context (without message-specific RAG — that happens per-turn)
+  const baseContext = await gatherStackContext(root, { registry });
   const messages = [];
 
   // Show banner
@@ -313,7 +297,7 @@ export async function runAgentInteractive(root) {
 
   // Main chat loop
   while (true) {
-    const input = await promptInput();
+    const input = await promptInput(`fops v${PKG.version} \u00b7 /exit to quit \u00b7 \u2191\u2193 history`);
 
     // Exit on null (esc/ctrl+c) or exit command
     if (input === null || /^\/(exit|quit|q)$/i.test(input)) {
@@ -326,6 +310,15 @@ export async function runAgentInteractive(root) {
     messages.push({ role: "user", content: input });
 
     try {
+      // Re-gather knowledge per turn so RAG is query-specific
+      let ragBlock = null;
+      if (registry) {
+        const { searchKnowledge } = await import("../plugins/knowledge.js");
+        ragBlock = await searchKnowledge(registry, input);
+      }
+      const systemContent = FOUNDATION_SYSTEM_PROMPT + "\n\n" + baseContext
+        + (ragBlock ? "\n\n" + ragBlock : "");
+
       const replyText = await streamAssistantReply(root, messages, systemContent, {});
       console.log("");
       console.log(formatResponse(replyText));
@@ -342,7 +335,6 @@ export async function runAgentInteractive(root) {
 
         // Auto-follow-up if any command failed
         if (cmdResults.some((r) => !r.ok)) {
-          console.log("");
           const followUp = await streamAssistantReply(root, messages, systemContent, {});
           console.log("");
           console.log(formatResponse(followUp));

package/src/agent/context.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execa } from "execa";
-import { loadSkills } from "../plugins/index.js";
+import { loadSkills, searchKnowledge } from "../plugins/index.js";
 
 export const FOUNDATION_SYSTEM_PROMPT = `You are FOPS — the Foundation Operator. Think of yourself as the system admin who actually knows what they're doing. You're direct, no-BS, slightly irreverent. You don't sugarcoat problems — you diagnose and fix them. Channel the energy of someone who lives in the terminal and sees the matrix in docker logs.
 
@@ -11,44 +11,14 @@ export const FOUNDATION_SYSTEM_PROMPT = `You are FOPS — the Foundation Operato
 - When something is broken, say what's broken and how to fix it. No preambles.
 - Treat the user like a peer, not a customer.
 
-## Capabilities
-- **Setup & Init**: Prerequisites, environment config, first-run setup
-- **Operations**: Start/stop services, status, logs, diagnostics
-- **Debugging**: Troubleshoot issues, analyze logs, suggest fixes
-- **Security**: Validate configs, check credentials safely (never log secrets)
-
 ## Commands
 When suggesting commands, ALWAYS use \`fops\` commands, not raw \`make\` or \`git clone\`. Output each in its own fenced block.
 
-**Always suggest 2–3 commands** so the user can pick. For example, if someone asks "what's running?", suggest both a status check and a diagnostic:
-\`\`\`bash
-fops status
-\`\`\`
-\`\`\`bash
-fops doctor
-\`\`\`
-
-If a single action is needed, pair it with a follow-up (e.g. restart + logs, doctor + up).
-
-## Available fops Commands
-- fops init — clone repos, bootstrap environment
-- fops up / fops down — start/stop the stack
-- fops restart — restart all or specific services
-- fops status — show running containers
-- fops logs [service] — tail logs
-- fops doctor — run diagnostics
-- fops login — authenticate with AWS/ECR
-- fops agent / fops chat — talk to me
-
-## Services & Ports
-Backend:9001, Frontend:3002, Storage:9002, Trino:8081, OPA:8181, Kafka:9092, Postgres:5432, Hive:9083, Vault:18201
-
-## Setup Checklist (for new users)
-1. Install prerequisites: git, docker, node >= 18, aws cli (optional)
-2. \`npm install -g @meshxdata/fops\`
-3. \`fops init\` — clones repos, sets up .env
-4. \`fops up\` — boots the stack
-5. \`fops doctor\` — verifies everything is healthy
+**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.
 
 ## Security Rules
 - Never output API keys, passwords, or tokens in responses
@@ -60,84 +30,171 @@ export function getFoundationContextBlock(root) {
   return `Project root: ${root}. Commands run in this directory.`;
 }
 
-export async function gatherStackContext(root) {
-  const parts = [getFoundationContextBlock(root)];
-
-  // Check Docker status (only if we have a project root)
-  if (root) {
-    try {
-      const { stdout: psOut } = await execa("docker", ["compose", "ps", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
-      if (psOut && psOut.trim()) {
-        const lines = psOut.trim().split("\n").filter(Boolean);
-        const services = lines.map((line) => {
-          try {
-            const o = JSON.parse(line);
-            return `${o.Name || o.name || "?"}: ${o.State || o.Status || "?"}`;
-          } catch {
-            return null;
-          }
-        }).filter(Boolean);
-        if (services.length) parts.push("Running containers:\n" + services.join("\n"));
-        else parts.push("No containers running.");
+async function gatherDockerStatus(root) {
+  try {
+    const { stdout: psOut } = await execa("docker", ["compose", "ps", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
+    if (psOut && psOut.trim()) {
+      const lines = psOut.trim().split("\n").filter(Boolean);
+      const parsed = lines.map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      }).filter(Boolean);
+
+      if (!parsed.length) return "No containers running.";
+
+      let healthy = 0, unhealthy = 0, exited = 0, running = 0;
+      const services = parsed.map((o) => {
+        const name = o.Name || o.name || o.Service || "?";
+        const state = (o.State || "").toLowerCase();
+        const status = o.Status || "";
+        const health = (o.Health || "").toLowerCase();
+        const exitCode = o.ExitCode ?? "";
+
+        if (state === "exited" || state === "dead") {
+          exited++;
+          return `${name}: EXITED (code ${exitCode}) — ${status}`;
+        }
+        if (health === "unhealthy") {
+          unhealthy++;
+          return `${name}: UNHEALTHY — ${status}`;
+        }
+        if (state === "running" && (health === "healthy" || !health)) {
+          healthy++;
+          running++;
+          return `${name}: running ${health ? "(healthy)" : ""} — ${status}`;
+        }
+        running++;
+        return `${name}: ${state} ${health ? `(${health})` : ""} — ${status}`;
+      });
+
+      const summary = [];
+      if (running) summary.push(`${running} running`);
+      if (healthy) summary.push(`${healthy} healthy`);
+      if (unhealthy) summary.push(`${unhealthy} UNHEALTHY`);
+      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.";
       }
-    } catch {
-      parts.push("Docker: not available or not running.");
+
+      return header + "\n\nContainer details:\n" + services.join("\n");
     }
+  } catch {
+    return "Docker: not available or not running.";
   }
+  return null;
+}
 
-  // Check image ages
-  if (root) {
-    try {
-      const { stdout: imgOut } = await execa("docker", ["compose", "images", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
-      if (imgOut?.trim()) {
-        const ages = [];
-        for (const line of imgOut.trim().split("\n").filter(Boolean)) {
-          try {
-            const img = JSON.parse(line);
-            const id = img.ID || img.id || "";
-            const repo = img.Repository || img.repository || "";
-            const tag = img.Tag || img.tag || "";
-            if (!id) continue;
-            const { stdout: created } = await execa("docker", ["image", "inspect", id, "--format", "{{.Created}}"], { reject: false, timeout: 3000 });
-            if (created?.trim()) {
-              const days = Math.floor((Date.now() - new Date(created.trim()).getTime()) / 86400000);
-              const name = `${repo}:${tag}`.replace(/^:|:$/g, "") || id.slice(0, 12);
-              ages.push(`${name}: ${days}d old`);
-            }
-          } catch {}
-        }
-        if (ages.length) parts.push("Image ages:\n" + ages.join("\n"));
-      }
-    } catch {}
-  }
+async function gatherImageAges(root) {
+  try {
+    const { stdout: imgOut } = await execa("docker", ["compose", "images", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
+    if (imgOut?.trim()) {
+      const images = imgOut.trim().split("\n").filter(Boolean).map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      }).filter(Boolean);
+
+      // Inspect all images in parallel
+      const ageResults = await Promise.all(images.map(async (img) => {
+        try {
+          const id = img.ID || img.id || "";
+          const repo = img.Repository || img.repository || "";
+          const tag = img.Tag || img.tag || "";
+          if (!id) return null;
+          const { stdout: created } = await execa("docker", ["image", "inspect", id, "--format", "{{.Created}}"], { reject: false, timeout: 3000 });
+          if (created?.trim()) {
+            const days = Math.floor((Date.now() - new Date(created.trim()).getTime()) / 86400000);
+            const name = `${repo}:${tag}`.replace(/^:|:$/g, "") || id.slice(0, 12);
+            return `${name}: ${days}d old`;
+          }
+        } catch {}
+        return null;
+      }));
 
-  // Check prerequisites (each wrapped individually so one failure doesn't kill the rest)
-  const prereqs = [];
-  try { await execa("git", ["--version"], { reject: false, timeout: 3000 }); prereqs.push("git: ✓"); } catch { prereqs.push("git: ✗"); }
-  try { await execa("docker", ["info"], { reject: false, timeout: 5000 }); prereqs.push("docker: ✓"); } catch { prereqs.push("docker: ✗"); }
-  try { await execa("aws", ["--version"], { reject: false, timeout: 3000 }); prereqs.push("aws-cli: ✓"); } catch { prereqs.push("aws-cli: ✗ (optional)"); }
-  parts.push("Prerequisites: " + prereqs.join(", "));
+      const ages = ageResults.filter(Boolean);
+      if (ages.length) return "Image ages:\n" + ages.join("\n");
+    }
+  } catch {}
+  return null;
+}
 
-  // Check for .env file
-  if (root) {
-    const envPath = path.join(root, ".env");
-    const envExamplePath = path.join(root, ".env.example");
-    if (fs.existsSync(envPath)) {
-      parts.push(".env: configured");
-    } else if (fs.existsSync(envExamplePath)) {
-      parts.push(".env: not configured (run 'fops setup' or 'cp .env.example .env')");
+async function gatherPrereqs() {
+  const checks = await Promise.all([
+    execa("git", ["--version"], { reject: false, timeout: 3000 }).then(() => "git: ✓").catch(() => "git: ✗ (REQUIRED)"),
+    execa("docker", ["info"], { reject: false, timeout: 5000 }).then(() => "docker: ✓").catch(() => "docker: ✗ (REQUIRED)"),
+    execa("aws", ["--version"], { reject: false, timeout: 3000 }).then(() => "aws-cli: ✓").catch(() => "aws-cli: ✗ (REQUIRED)"),
+  ]);
+
+  // Check git netrc for GitHub auth
+  const homedir = (await import("node:os")).default.homedir();
+  const netrcPath = (await import("node:path")).default.join(homedir, ".netrc");
+  let netrc = "git-netrc: ✗ (REQUIRED — needed for private repo access)";
+  try {
+    const netrcContent = (await import("node:fs")).default.readFileSync(netrcPath, "utf8");
+    if (netrcContent.includes("github.com")) {
+      netrc = "git-netrc: ✓ (github.com configured)";
+    } else {
+      netrc = "git-netrc: ✗ (no github.com entry — REQUIRED)";
     }
+  } catch {}
+
+  checks.push(netrc);
+  return "Prerequisites: " + checks.join(", ");
+}
+
+function checkEnvFile(root) {
+  const envPath = path.join(root, ".env");
+  const envExamplePath = path.join(root, ".env.example");
+  if (fs.existsSync(envPath)) {
+    return ".env: configured";
+  } else if (fs.existsSync(envExamplePath)) {
+    return ".env: not configured (run 'fops setup' or 'cp .env.example .env')";
   }
+  return null;
+}
 
-  // Inject plugin skills into context
+async function gatherSkills() {
   try {
     const skills = await loadSkills();
     if (skills.length) {
-      parts.push("## Additional Skills\n" + skills.map((s) => s.content).join("\n\n"));
+      return "## Additional Skills\n" + skills.map((s) => s.content).join("\n\n");
     }
   } catch {
     // skip if skill loading fails
   }
+  return null;
+}
+
+export async function gatherStackContext(root, { registry, message } = {}) {
+  const parts = [getFoundationContextBlock(root)];
+
+  if (root) {
+    // Run all independent checks in parallel
+    const [dockerStatus, imageAges, prereqs, envInfo, skills, knowledge] = await Promise.all([
+      gatherDockerStatus(root),
+      gatherImageAges(root),
+      gatherPrereqs(),
+      Promise.resolve(checkEnvFile(root)),
+      gatherSkills(),
+      registry && message ? searchKnowledge(registry, message) : Promise.resolve(null),
+    ]);
+
+    if (dockerStatus) parts.push(dockerStatus);
+    if (imageAges) parts.push(imageAges);
+    parts.push(prereqs);
+    if (envInfo) parts.push(envInfo);
+    if (skills) parts.push(skills);
+    if (knowledge) parts.push(knowledge);
+  } else {
+    // No root — still check prereqs, skills, and knowledge
+    const [prereqs, skills, knowledge] = await Promise.all([
+      gatherPrereqs(),
+      gatherSkills(),
+      registry && message ? searchKnowledge(registry, message) : Promise.resolve(null),
+    ]);
+    parts.push(prereqs);
+    if (skills) parts.push(skills);
+    if (knowledge) parts.push(knowledge);
+  }
 
   return parts.join("\n\n");
 }