qavor 0.1.8 → 0.1.10

package/dist/index.js

@@ -4,87 +4,15 @@
 import process2 from "process";
 import { Command } from "commander";
 
-// src/util/exit-codes.ts
-var ExitCode = {
-  Ok: 0,
-  UserError: 1,
-  ManifestError: 2,
-  RuntimeError: 3
-};
-var QavorError = class extends Error {
-  exitCode;
-  constructor(message, exitCode = ExitCode.RuntimeError) {
-    super(message);
-    this.name = "QavorError";
-    this.exitCode = exitCode;
-  }
-};
-var UserError = class extends QavorError {
-  constructor(message) {
-    super(message, ExitCode.UserError);
-    this.name = "UserError";
-  }
-};
-var ManifestError = class extends QavorError {
-  constructor(message) {
-    super(message, ExitCode.ManifestError);
-    this.name = "ManifestError";
-  }
-};
-var RuntimeFailure = class extends QavorError {
-  constructor(message) {
-    super(message, ExitCode.RuntimeError);
-    this.name = "RuntimeFailure";
-  }
-};
-
-// src/util/logger.ts
-import pino from "pino";
-var rootLogger = null;
-function configureLogger(opts) {
-  const level = opts.verbose ? "debug" : "info";
-  const stderrIsTty = Boolean(process.stderr.isTTY);
-  if (opts.json || !stderrIsTty) {
-    rootLogger = pino({ level }, pino.destination({ fd: 2, sync: true }));
-  } else {
-    rootLogger = pino({
-      level,
-      transport: {
-        target: "pino-pretty",
-        options: {
-          destination: 2,
-          colorize: stderrIsTty,
-          translateTime: false,
-          ignore: "pid,hostname,time",
-          messageFormat: "{msg}",
-          singleLine: false,
-          sync: true
-        }
-      }
-    });
-  }
-  return rootLogger;
-}
-function getLogger() {
-  if (!rootLogger) {
-    rootLogger = pino({ level: "info" });
-  }
-  return rootLogger;
-}
-function emit(text) {
-  process.stdout.write(text + "\n");
-}
-function emitJson(payload) {
-  process.stdout.write(JSON.stringify(payload) + "\n");
-}
-
-// src/cli/commands/init.ts
-import path6 from "path";
+// src/cli/commands/doctor.ts
+import fs6 from "fs/promises";
+import path8 from "path";
+import { execa as execa2 } from "execa";
 
-// src/workspace/init.ts
-import { createHash as createHash2 } from "crypto";
-import fs4 from "fs/promises";
-import path5 from "path";
+// src/manifest/discovery.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+import pMap from "p-map";
 
 // src/util/fs.ts
 import { createHash } from "crypto";
@@ -124,7 +52,8 @@ async function readJsonFile(target) {
 }
 async function writeJsonFile(target, value) {
   await ensureDir(path.dirname(target));
-  await fs.writeFile(target, JSON.stringify(value, null, 2) + "\n", "utf8");
+  await fs.writeFile(target, `${JSON.stringify(value, null, 2)}
+`, "utf8");
 }
 function globalCacheDir(env = process.env) {
   const xdg = env.XDG_CACHE_HOME;
@@ -133,152 +62,51 @@ function globalCacheDir(env = process.env) {
   return path.join(home, ".cache", "qavor");
 }
 
-// src/git/git.ts
-import { execa } from "execa";
+// src/manifest/loader.ts
 import fs2 from "fs/promises";
 import path2 from "path";
-import simpleGit from "simple-git";
-async function runGit(args, opts) {
-  let child;
-  try {
-    child = execa("git", args, {
-      cwd: opts.cwd,
-      env: opts.env ? { ...process.env, ...opts.env } : process.env,
-      ...opts.signal ? { cancelSignal: opts.signal } : {},
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    const res = await child;
-    return typeof res.stdout === "string" ? res.stdout : "";
-  } catch (err) {
-    const ee = err;
-    const stderr = typeof ee.stderr === "string" ? ee.stderr : "";
-    const stdout = typeof ee.stdout === "string" ? ee.stdout : "";
-    const code2 = ee.exitCode ?? -1;
-    const tail = stderr.trim() || stdout.trim() || ee.shortMessage || ee.message;
-    throw new RuntimeFailure(`git ${args.join(" ")} (exit ${code2}) in ${opts.cwd}
-  ${tail}`);
-  }
-}
-async function isGitRepo(dir) {
-  if (!await isDirectory(dir)) return false;
-  try {
-    await fs2.access(path2.join(dir, ".git"));
-    return true;
-  } catch {
-    try {
-      const out = await runGit(["rev-parse", "--is-inside-work-tree"], { cwd: dir });
-      return out.trim() === "true";
-    } catch {
-      return false;
-    }
-  }
-}
-async function readRepoStatus(dir) {
-  const git = simpleGit({ baseDir: dir });
-  let branch = null;
-  try {
-    const summary = await git.branch();
-    branch = summary.current || null;
-  } catch {
-    branch = null;
-  }
-  let ahead = 0;
-  let behind = 0;
-  try {
-    const counts = await runGit(["rev-list", "--left-right", "--count", "@{u}...HEAD"], { cwd: dir });
-    const [b, a] = counts.trim().split(/\s+/).map((n) => Number.parseInt(n, 10));
-    behind = Number.isFinite(b) ? b ?? 0 : 0;
-    ahead = Number.isFinite(a) ? a ?? 0 : 0;
-  } catch {
-  }
-  let dirtyCount = 0;
-  try {
-    const status = await git.status();
-    dirtyCount = status.files.length;
-  } catch {
-  }
-  let lastCommit = null;
-  let lastCommitSubject = null;
-  try {
-    const log = await git.log({ maxCount: 1 });
-    if (log.latest) {
-      lastCommit = log.latest.hash.slice(0, 7);
-      lastCommitSubject = log.latest.message;
-    }
-  } catch {
+import { parseAllDocuments } from "yaml";
+
+// src/util/exit-codes.ts
+var ExitCode = {
+  Ok: 0,
+  UserError: 1,
+  ManifestError: 2,
+  RuntimeError: 3
+};
+var QavorError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = ExitCode.RuntimeError) {
+    super(message);
+    this.name = "QavorError";
+    this.exitCode = exitCode;
   }
-  return { branch, ahead, behind, dirtyCount, lastCommit, lastCommitSubject };
-}
-async function gitClone(opts) {
-  const args = ["clone"];
-  if (opts.branch && !opts.commit) args.push("--branch", opts.branch);
-  else if (opts.tag && !opts.commit) args.push("--branch", opts.tag);
-  if (opts.shallow) args.push("--depth", "1");
-  if (opts.submodules) args.push("--recurse-submodules");
-  args.push("--", opts.url, opts.dest);
-  await fs2.mkdir(path2.dirname(opts.dest), { recursive: true });
-  const runOpts = { cwd: path2.dirname(opts.dest) };
-  if (opts.signal) runOpts.signal = opts.signal;
-  await runGit(args, runOpts);
-  if (opts.commit) {
-    const checkoutOpts = { cwd: opts.dest };
-    if (opts.signal) checkoutOpts.signal = opts.signal;
-    await runGit(["checkout", opts.commit], checkoutOpts);
+};
+var UserError = class extends QavorError {
+  constructor(message) {
+    super(message, ExitCode.UserError);
+    this.name = "UserError";
   }
-}
-async function gitFetch(dir, signal) {
-  const opts = { cwd: dir };
-  if (signal) opts.signal = signal;
-  await runGit(["fetch", "--prune"], opts);
-}
-async function gitPullFastForward(dir, signal) {
-  const opts = { cwd: dir };
-  if (signal) opts.signal = signal;
-  await runGit(["pull", "--ff-only"], opts);
-}
-async function gitCommit(dir, message, opts = {}) {
-  const status = await runGit(["status", "--porcelain"], { cwd: dir });
-  if (status.trim().length === 0 && !opts.allowEmpty) {
-    return { committed: false };
+};
+var ManifestError = class extends QavorError {
+  constructor(message) {
+    super(message, ExitCode.ManifestError);
+    this.name = "ManifestError";
   }
-  const addOpts = { cwd: dir };
-  if (opts.signal) addOpts.signal = opts.signal;
-  await runGit(["add", "-A"], addOpts);
-  const args = ["commit", "-m", message];
-  if (opts.allowEmpty) args.push("--allow-empty");
-  const commitOpts = { cwd: dir };
-  if (opts.signal) commitOpts.signal = opts.signal;
-  await runGit(args, commitOpts);
-  return { committed: true };
-}
-async function gitPush(dir, signal) {
-  const opts = { cwd: dir };
-  if (signal) opts.signal = signal;
-  await runGit(["push"], opts);
-}
-function deriveCloneUrl(input) {
-  if (input.explicitUrl) return input.explicitUrl;
-  if (!input.rootUrl) {
-    throw new RuntimeFailure(
-      `Cannot derive clone URL for '${input.name}': project manifest has no git.root_url and no explicit url is set.`
-    );
+};
+var RuntimeFailure = class extends QavorError {
+  constructor(message) {
+    super(message, ExitCode.RuntimeError);
+    this.name = "RuntimeFailure";
   }
-  const prefix = input.repoPrefix ?? "";
-  const base = input.rootUrl.endsWith("/") ? input.rootUrl.slice(0, -1) : input.rootUrl;
-  const fullName = `${prefix}${input.name}`;
-  return `${base}/${fullName}.git`;
-}
+};
 
 // src/manifest/loader.ts
-import fs3 from "fs/promises";
-import path3 from "path";
-import { parseAllDocuments } from "yaml";
 async function loadManifestFile(filePath, opts = {}) {
-  const absFile = path3.resolve(filePath);
+  const absFile = path2.resolve(filePath);
   let source;
   try {
-    source = await fs3.readFile(absFile, "utf8");
+    source = await fs2.readFile(absFile, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       throw new ManifestError(`Manifest file not found: ${absFile}`);
@@ -293,6 +121,7 @@ async function loadManifestFile(filePath, opts = {}) {
   for (const doc of docs) {
     if (doc.errors.length && opts.throwOnParseError !== false) {
       const e = doc.errors[0];
+      if (!e) continue;
       const pos = errorPosition(absFile, source, e);
       throw new ManifestError(
         `${pos.file}:${pos.line}:${pos.column}: YAML parse error: ${e.message}`
@@ -388,11 +217,7 @@ var qavor_defs_schema_default = {
     },
     envScalar: {
       description: "Scalar value usable on the right-hand side of an env entry. Strings support ${VAR} and ${secret:NAME} interpolation.",
-      oneOf: [
-        { type: "string" },
-        { type: "number" },
-        { type: "boolean" }
-      ]
+      oneOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }]
     },
     envSpec: {
       description: "Long-form env entry. Use when you need typing, validation, default vs override, secret marking, or documentation.",
@@ -402,7 +227,10 @@ var qavor_defs_schema_default = {
         value: { $ref: "#/$defs/envScalar" },
         default: { $ref: "#/$defs/envScalar" },
         required: { type: "boolean", default: false },
-        type: { type: "string", enum: ["string", "int", "number", "bool", "url", "duration"] },
+        type: {
+          type: "string",
+          enum: ["string", "int", "number", "bool", "url", "duration"]
+        },
         pattern: { type: "string", format: "regex" },
         secret: { type: "boolean", default: false },
         description: { type: "string" }
@@ -413,10 +241,7 @@ var qavor_defs_schema_default = {
       type: "object",
       patternProperties: {
         "^[A-Z_][A-Z0-9_]*$": {
-          oneOf: [
-            { $ref: "#/$defs/envScalar" },
-            { $ref: "#/$defs/envSpec" }
-          ]
+          oneOf: [{ $ref: "#/$defs/envScalar" }, { $ref: "#/$defs/envSpec" }]
         }
       },
       additionalProperties: false
@@ -448,10 +273,19 @@ var qavor_defs_schema_default = {
       additionalProperties: false,
       required: ["cmd"],
       properties: {
-        cmd: { type: "string", description: "Shell command. Multiline strings are treated as a script." },
-        cwd: { type: "string", description: "Working directory relative to the manifest file." },
+        cmd: {
+          type: "string",
+          description: "Shell command. Multiline strings are treated as a script."
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory relative to the manifest file."
+        },
         env: { $ref: "#/$defs/envMap" },
-        shell: { type: "string", description: "Override shell. Defaults to `/bin/sh -c` (POSIX) or `cmd /C` on Windows." }
+        shell: {
+          type: "string",
+          description: "Override shell. Defaults to `/bin/sh -c` (POSIX) or `cmd /C` on Windows."
+        }
       }
     },
     runtimeBackend: {
@@ -490,7 +324,10 @@ var qavor_defs_schema_default = {
       type: "object",
       additionalProperties: false,
       properties: {
-        service: { type: "string", description: "Service reference. `<service>` for same-workspace, `<repo>:<service>` permitted." },
+        service: {
+          type: "string",
+          description: "Service reference. `<service>` for same-workspace, `<repo>:<service>` permitted."
+        },
         stateful: { $ref: "#/$defs/name" },
         group: { $ref: "#/$defs/name" },
         optional: { type: "boolean", default: false },
@@ -541,22 +378,37 @@ var qavor_defs_schema_default = {
   }
 };
 
-// src/schema/qavor.workspaces.schema.json
-var qavor_workspaces_schema_default = {
+// src/schema/qavor.profile.schema.json
+var qavor_profile_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://qavor.dev/schemas/qavor.workspaces.schema.json",
-  title: "qavor workspaces manifest",
-  description: "Workspace pointer file. Lives at the root of the workspace directory as `qavor.yaml` and is created automatically by `qavor init`. Its only job is to point at the project repo whose `kind: project` manifest enumerates the rest of the workspace.",
+  $id: "https://qavor.dev/schemas/qavor.profile.schema.json",
+  title: "qavor profile manifest",
+  description: "Reusable runtime + env bundle. Referenced by services and stateful manifests via the `profiles:` list. Profiles can themselves reference other profiles; resolution flattens the chain in declaration order with later entries winning. A profile's runtime/env layer below the referencing manifest's own runtime/env.",
   type: "object",
   additionalProperties: false,
-  required: ["kind", "root_project_path"],
+  required: ["kind", "name"],
   properties: {
-    kind: { const: "workspaces" },
-    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
-    root_project_path: {
+    kind: { const: "profile" },
+    schemaVersion: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion"
+    },
+    name: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
+      description: "Profile identifier. Referenced from `profiles:` lists and from CLI flags."
+    },
+    description: { type: "string" },
+    profiles: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/profileRef" },
+      uniqueItems: true,
+      description: "Other profiles this one extends. Resolved in declaration order before this profile's own values are applied."
+    },
+    runtime: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/runtimeBlock" },
+    mode: {
       type: "string",
-      description: "Workspace-relative path to the directory containing the project repo's `qavor.yaml` (kind: project)."
-    }
+      enum: ["native", "docker", "docker-compose"]
+    },
+    env: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/envBlock" }
   }
 };
 
@@ -571,7 +423,9 @@ var qavor_project_schema_default = {
   required: ["kind", "name", "repositories"],
   properties: {
     kind: { const: "project" },
-    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    schemaVersion: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion"
+    },
     name: {
       $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
       description: "Human-readable workspace name. Used as the compose project namespace and the on-disk workspace identifier."
@@ -690,7 +544,9 @@ var qavor_repo_schema_default = {
   required: ["kind", "name"],
   properties: {
     kind: { const: "repo" },
-    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    schemaVersion: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion"
+    },
     name: {
       $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
       description: "Repository identifier. Must match the `name` used in the project manifest's `repositories` list."
@@ -717,7 +573,9 @@ var qavor_service_schema_default = {
   required: ["kind", "name"],
   properties: {
     kind: { const: "service" },
-    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    schemaVersion: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion"
+    },
     name: {
       $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
       description: "Service identifier. Must be unique within the workspace; cross-repo references use this name."
@@ -765,7 +623,9 @@ var qavor_stateful_schema_default = {
   required: ["kind", "name"],
   properties: {
     kind: { const: "stateful" },
-    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    schemaVersion: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion"
+    },
     name: {
       $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
       description: "Stateful service identifier. Must be unique within the workspace."
@@ -804,35 +664,24 @@ var qavor_stateful_schema_default = {
   }
 };
 
-// src/schema/qavor.profile.schema.json
-var qavor_profile_schema_default = {
+// src/schema/qavor.workspaces.schema.json
+var qavor_workspaces_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://qavor.dev/schemas/qavor.profile.schema.json",
-  title: "qavor profile manifest",
-  description: "Reusable runtime + env bundle. Referenced by services and stateful manifests via the `profiles:` list. Profiles can themselves reference other profiles; resolution flattens the chain in declaration order with later entries winning. A profile's runtime/env layer below the referencing manifest's own runtime/env.",
+  $id: "https://qavor.dev/schemas/qavor.workspaces.schema.json",
+  title: "qavor workspaces manifest",
+  description: "Workspace pointer file. Lives at the root of the workspace directory as `qavor.yaml` and is created automatically by `qavor init`. Its only job is to point at the project repo whose `kind: project` manifest enumerates the rest of the workspace.",
   type: "object",
   additionalProperties: false,
-  required: ["kind", "name"],
+  required: ["kind", "root_project_path"],
   properties: {
-    kind: { const: "profile" },
-    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
-    name: {
-      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
-      description: "Profile identifier. Referenced from `profiles:` lists and from CLI flags."
-    },
-    description: { type: "string" },
-    profiles: {
-      type: "array",
-      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/profileRef" },
-      uniqueItems: true,
-      description: "Other profiles this one extends. Resolved in declaration order before this profile's own values are applied."
+    kind: { const: "workspaces" },
+    schemaVersion: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion"
     },
-    runtime: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/runtimeBlock" },
-    mode: {
+    root_project_path: {
       type: "string",
-      enum: ["native", "docker", "docker-compose"]
-    },
-    env: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/envBlock" }
+      description: "Workspace-relative path to the directory containing the project repo's `qavor.yaml` (kind: project)."
+    }
   }
 };
 
@@ -950,183 +799,222 @@ function formatIssue(i) {
   return `${i.file}:${i.line}:${i.column} [${i.kind}] ${i.path}: ${i.message}`;
 }
 
-// src/workspace/paths.ts
-import path4 from "path";
-function workspacePaths(root) {
-  const abs = path4.resolve(root);
-  const stateRoot = path4.join(abs, ".qavor");
-  return {
-    root: abs,
-    workspacesFile: path4.join(abs, "qavor.yaml"),
-    stateRoot,
-    stateDir: path4.join(stateRoot, "state"),
-    logsDir: path4.join(stateRoot, "logs"),
-    composeDir: path4.join(stateRoot, "compose"),
-    cacheDir: path4.join(stateRoot, "cache"),
-    workspaceMetaFile: path4.join(stateRoot, "workspace.json"),
-    stateGitignore: path4.join(stateRoot, ".gitignore")
-  };
-}
-
-// src/workspace/init.ts
-var URL_RE = /^(?:git@[^:]+:|https?:\/\/|git:\/\/|ssh:\/\/|file:\/\/)/;
-function looksLikeGitUrl(s) {
-  return URL_RE.test(s);
-}
-function projectRepoNameFromUrl(url) {
-  const cleaned = url.replace(/[?#].*$/, "");
-  const last = cleaned.split("/").pop() ?? cleaned.split(":").pop() ?? "project";
-  return last.replace(/\.git$/, "");
-}
-async function initWorkspace(opts) {
-  const workspaceRoot = path5.resolve(opts.into ?? process.cwd());
-  await ensureDir(workspaceRoot);
-  const paths = workspacePaths(workspaceRoot);
-  let projectRepoPath;
-  let cloned = false;
-  if (looksLikeGitUrl(opts.source)) {
-    const repoName = projectRepoNameFromUrl(opts.source);
-    const target = path5.join(workspaceRoot, `${repoName}.git`);
-    if (await isDirectory(target)) {
-      if (!await isGitRepo(target)) {
-        throw new UserError(
-          `Cannot reuse ${target}: directory exists but is not a git repo. Move it aside and re-run.`
-        );
-      }
-      opts.logger.info({ target }, "reusing existing project repo clone");
-      projectRepoPath = target;
-    } else {
-      const cacheDir = path5.join(globalCacheDir(), "projects", urlHash(opts.source));
-      await ensureDir(path5.dirname(cacheDir));
-      opts.logger.info({ url: opts.source, target }, "cloning project repo");
-      await gitClone({ url: opts.source, dest: target });
-      try {
-        await ensureDir(cacheDir);
-        await fs4.writeFile(
-          path5.join(cacheDir, "source.json"),
-          JSON.stringify({ url: opts.source, cloned_to: target, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
-        );
-      } catch {
-      }
-      projectRepoPath = target;
-      cloned = true;
-    }
-  } else {
-    const localPath = path5.resolve(opts.source);
-    if (!await isDirectory(localPath)) {
-      throw new UserError(`Project repo source does not exist or is not a directory: ${localPath}`);
-    }
-    projectRepoPath = localPath;
+// src/manifest/discovery.ts
+var MAX_DEPTH = 4;
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  ".qavor",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pycache__",
+  "dist",
+  "build",
+  "target",
+  ".next",
+  ".svelte-kit",
+  ".cache"
+]);
+async function discoverManifestFiles(repoRoot) {
+  const abs = path3.resolve(repoRoot);
+  const found = /* @__PURE__ */ new Set();
+  if (!await isDirectory(abs)) return [];
+  const rootFile = path3.join(abs, "qavor.yaml");
+  try {
+    await fs3.access(rootFile);
+    found.add(rootFile);
+  } catch {
   }
-  const projectManifestFile = path5.join(projectRepoPath, "qavor.yaml");
-  const docs = await loadManifestFile(projectManifestFile);
-  const projectDoc = docs.find((d) => d.kind === "project");
-  if (!projectDoc) {
-    throw new ManifestError(
-      `Project repo at ${projectRepoPath} is missing a \`kind: project\` document in qavor.yaml.`
-    );
+  const qavorDir = path3.join(abs, "qavor");
+  if (await isDirectory(qavorDir)) {
+    for await (const f of walk(qavorDir, qavorDir, 0)) found.add(f);
   }
-  const result = validateDocument(projectDoc);
-  if (!result.ok) {
-    const msg = result.issues.map((i) => `  ${i.file}:${i.line}:${i.column} ${i.path}: ${i.message}`).join("\n");
-    throw new ManifestError(`Invalid project manifest:
-${msg}`);
+  for await (const f of walk(abs, abs, 0)) {
+    found.add(f);
   }
-  const project = projectDoc.data;
-  await ensureDir(paths.stateRoot);
-  await ensureDir(paths.stateDir);
-  await ensureDir(paths.logsDir);
-  await ensureDir(paths.composeDir);
-  await ensureDir(paths.cacheDir);
-  await fs4.writeFile(
-    paths.stateGitignore,
-    [
-      "# qavor state directory \u2014 all files are generated. Do not commit.",
-      "*",
-      "!.gitignore",
-      ""
-    ].join("\n")
-  );
-  const relProjectPath = "./" + path5.relative(workspaceRoot, projectRepoPath).split(path5.sep).join("/");
-  const workspacesYaml = renderWorkspacesYaml(relProjectPath);
-  await fs4.writeFile(paths.workspacesFile, workspacesYaml, "utf8");
-  const manifestHash = createHash2("sha256").update(await fs4.readFile(projectManifestFile)).digest("hex");
-  await writeJsonFile(paths.workspaceMetaFile, {
-    project_name: project.name,
-    project_repo_path: projectRepoPath,
-    manifest_hash: manifestHash,
-    initialized_at: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  return { paths, projectRepoPath, project, cloned };
-}
-function urlHash(url) {
-  return createHash2("sha256").update(url).digest("hex").slice(0, 16);
-}
-function renderWorkspacesYaml(relProjectPath) {
-  return [
-    "# Generated by `qavor init`. Points at the project repo whose",
-    "# `kind: project` manifest enumerates the rest of the workspace.",
-    "kind: workspaces",
-    `root_project_path: ${relProjectPath}`,
-    ""
-  ].join("\n");
-}
-
-// src/cli/options.ts
-function rootOptions(cmd) {
-  const opts = cmd.opts();
-  return {
-    json: Boolean(opts.json),
-    verbose: Boolean(opts.verbose),
-    jobs: typeof opts.jobs === "string" ? Number.parseInt(opts.jobs, 10) : void 0,
-    config: typeof opts.config === "string" ? opts.config : void 0
-  };
+  return [...found].sort();
 }
-function inheritRootOptions(cmd) {
-  let current = cmd;
-  while (current && current.parent) current = current.parent;
-  if (!current) return { json: false, verbose: false, jobs: void 0, config: void 0 };
-  return rootOptions(current);
+async function* walk(rootBase, current, depth) {
+  if (depth > MAX_DEPTH) return;
+  let entries;
+  try {
+    entries = await fs3.readdir(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path3.join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      if (depth === 0 && entry.name === "qavor") continue;
+      yield* walk(rootBase, full, depth + 1);
+    } else if (entry.isFile() && entry.name === "qavor.yaml") {
+      if (depth === 0 && current === rootBase) continue;
+      yield full;
+    }
+  }
 }
-
-// src/cli/commands/init.ts
-function registerInit(program) {
-  program.command("init").description("Bootstrap a workspace from a project repo (local path or git URL).").argument("<source>", "Local path to a project repo, or a git URL.").option("--into <dir>", "Workspace root directory. Defaults to the current directory.").action(async (source, opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const logger = getLogger();
-    const initOpts = { source, logger };
-    if (opts.into) initOpts.into = opts.into;
-    const result = await initWorkspace(initOpts);
-    if (root.json) {
-      emitJson({
-        ok: true,
-        workspace: result.paths.root,
-        project_name: result.project.name,
-        project_repo_path: result.projectRepoPath,
-        cloned_project: result.cloned,
-        repositories: result.project.repositories.length
+async function buildWorkspaceRegistry(opts) {
+  const issues = [];
+  const all = [];
+  const reposList = [];
+  for (const [name, dir] of opts.repos) reposList.push({ name, dir });
+  await pMap(
+    reposList,
+    async ({ name: repoName, dir }) => {
+      const files = await discoverManifestFiles(dir);
+      for (const file of files) {
+        let docs;
+        try {
+          docs = await loadManifestFile(file);
+        } catch (err) {
+          issues.push({
+            file,
+            line: 1,
+            column: 1,
+            kind: "unknown",
+            path: "",
+            message: err instanceof Error ? err.message : String(err)
+          });
+          continue;
+        }
+        for (const doc of docs) {
+          if (!isKnownKind(doc.kind)) {
+            const pos = doc.position("/kind");
+            issues.push({
+              file: pos.file,
+              line: pos.line,
+              column: pos.column,
+              kind: String(doc.kind ?? "unknown"),
+              path: "/kind",
+              message: `Unknown or missing kind in this document`
+            });
+            continue;
+          }
+          const result = validateDocument(doc);
+          if (!result.ok) {
+            issues.push(...result.issues);
+            continue;
+          }
+          const data = doc.data;
+          all.push({
+            kind: doc.kind,
+            name: typeof data.name === "string" ? data.name : "",
+            file: doc.file,
+            docIndex: doc.docIndex,
+            dir: path3.dirname(doc.file),
+            repo: repoName,
+            data: doc.data,
+            position: doc.position
+          });
+        }
+      }
+    },
+    { concurrency: opts.concurrency ?? 8 }
+  );
+  const byName = /* @__PURE__ */ new Map();
+  for (const entry of all) {
+    if (!entry.name) continue;
+    if (entry.kind === "workspaces" || entry.kind === "project") continue;
+    const key = entry.name;
+    const existing = byName.get(key);
+    if (existing && existing.kind === entry.kind) {
+      const pos = entry.position("/name");
+      issues.push({
+        file: pos.file,
+        line: pos.line,
+        column: pos.column,
+        kind: entry.kind,
+        path: "/name",
+        message: `Duplicate ${entry.kind} name '${entry.name}'. Already declared at ${existing.file}.`
       });
-    } else {
-      emit(`Workspace initialized at ${result.paths.root}`);
-      emit(`  project: ${result.project.name}`);
-      emit(`  project repo: ${path6.relative(result.paths.root, result.projectRepoPath)}`);
-      emit(`  repositories declared: ${result.project.repositories.length}`);
-      emit(`  next: qavor clone`);
+      continue;
     }
-  });
+    if (!existing) byName.set(key, entry);
+  }
+  return { byName, entries: all, issues };
 }
 
-// src/cli/commands/workspace.ts
-import path8 from "path";
-import fs6 from "fs/promises";
+// src/util/concurrency.ts
+import os from "os";
+import pLimit from "p-limit";
+function resolveJobs(override) {
+  if (typeof override === "number" && Number.isFinite(override) && override >= 1) {
+    return Math.floor(override);
+  }
+  const avail = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+  return Math.max(1, avail);
+}
+
+// src/util/logger.ts
+import pino from "pino";
+var rootLogger = null;
+function configureLogger(opts) {
+  const level = opts.verbose ? "debug" : "info";
+  const stderrIsTty = Boolean(process.stderr.isTTY);
+  if (opts.json || !stderrIsTty) {
+    rootLogger = pino({ level }, pino.destination({ fd: 2, sync: true }));
+  } else {
+    rootLogger = pino({
+      level,
+      transport: {
+        target: "pino-pretty",
+        options: {
+          destination: 2,
+          colorize: stderrIsTty,
+          translateTime: false,
+          ignore: "pid,hostname,time",
+          messageFormat: "{msg}",
+          singleLine: false,
+          sync: true
+        }
+      }
+    });
+  }
+  return rootLogger;
+}
+function getLogger() {
+  if (!rootLogger) {
+    rootLogger = pino({ level: "info" });
+  }
+  return rootLogger;
+}
+function emit(text) {
+  process.stdout.write(`${text}
+`);
+}
+function emitJson(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}
+`);
+}
+
+// src/workspace/locate.ts
+import fs4 from "fs/promises";
+import path5 from "path";
+
+// src/workspace/paths.ts
+import path4 from "path";
+function workspacePaths(root) {
+  const abs = path4.resolve(root);
+  const stateRoot = path4.join(abs, ".qavor");
+  return {
+    root: abs,
+    workspacesFile: path4.join(abs, "qavor.yaml"),
+    stateRoot,
+    stateDir: path4.join(stateRoot, "state"),
+    logsDir: path4.join(stateRoot, "logs"),
+    composeDir: path4.join(stateRoot, "compose"),
+    cacheDir: path4.join(stateRoot, "cache"),
+    workspaceMetaFile: path4.join(stateRoot, "workspace.json"),
+    stateGitignore: path4.join(stateRoot, ".gitignore")
+  };
+}
 
 // src/workspace/locate.ts
-import fs5 from "fs/promises";
-import path7 from "path";
 async function findWorkspaceRoot(start) {
-  let cur = path7.resolve(start);
+  let cur = path5.resolve(start);
   for (let i = 0; i < 64; i++) {
-    const candidate = path7.join(cur, "qavor.yaml");
+    const candidate = path5.join(cur, "qavor.yaml");
     if (await isFile(candidate)) {
       try {
         const docs = await loadManifestFile(candidate, { throwOnParseError: false });
@@ -1134,7 +1022,7 @@ async function findWorkspaceRoot(start) {
       } catch {
       }
     }
-    const parent = path7.dirname(cur);
+    const parent = path5.dirname(cur);
     if (parent === cur) return null;
     cur = parent;
   }
@@ -1151,7 +1039,9 @@ async function resolveWorkspace(start = process.cwd()) {
   const docs = await loadManifestFile(paths.workspacesFile);
   const workspaceDoc = docs.find((d) => d.kind === "workspaces");
   if (!workspaceDoc) {
-    throw new UserError(`Workspace pointer at ${paths.workspacesFile} has no \`kind: workspaces\` document.`);
+    throw new UserError(
+      `Workspace pointer at ${paths.workspacesFile} has no \`kind: workspaces\` document.`
+    );
   }
   const rootProjectPath = workspaceDoc.data.root_project_path;
   if (typeof rootProjectPath !== "string" || rootProjectPath.length === 0) {
@@ -1159,8 +1049,8 @@ async function resolveWorkspace(start = process.cwd()) {
       `Workspace pointer at ${paths.workspacesFile} is missing \`root_project_path\`.`
     );
   }
-  const projectRepoPath = path7.isAbsolute(rootProjectPath) ? rootProjectPath : path7.resolve(paths.root, rootProjectPath);
-  const projectManifestFile = path7.join(projectRepoPath, "qavor.yaml");
+  const projectRepoPath = path5.isAbsolute(rootProjectPath) ? rootProjectPath : path5.resolve(paths.root, rootProjectPath);
+  const projectManifestFile = path5.join(projectRepoPath, "qavor.yaml");
   return { paths, projectRepoPath, projectManifestFile };
 }
 async function readProjectManifest(projectManifestFile) {
@@ -1172,139 +1062,149 @@ async function readProjectManifest(projectManifestFile) {
   return { data: project.data };
 }
 
-// src/cli/commands/workspace.ts
-function registerWorkspace(program) {
-  const ws = program.command("workspace").description("Workspace operations.");
-  ws.command("info").description("Show information about the workspace at or above the cwd.").action(async (_opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const resolved = await resolveWorkspace();
-    const project = await readProjectManifest(resolved.projectManifestFile);
-    let meta = {};
-    try {
-      meta = await readJsonFile(resolved.paths.workspaceMetaFile);
-    } catch {
-    }
-    const info = {
-      workspace_root: resolved.paths.root,
-      workspaces_file: resolved.paths.workspacesFile,
-      project_repo_path: resolved.projectRepoPath,
-      project_manifest_file: resolved.projectManifestFile,
-      project_name: typeof project.data.name === "string" ? project.data.name : null,
-      state_dir: resolved.paths.stateRoot,
-      meta
-    };
-    if (root.json) {
-      emitJson(info);
-      return;
-    }
-    emit(`Workspace root:        ${info.workspace_root}`);
-    emit(`Workspaces manifest:   ${path8.relative(info.workspace_root, info.workspaces_file)}`);
-    emit(`Project repo path:     ${path8.relative(info.workspace_root, info.project_repo_path)}`);
-    emit(`Project manifest:      ${path8.relative(info.workspace_root, info.project_manifest_file)}`);
-    emit(`Project name:          ${info.project_name ?? "<unknown>"}`);
-    emit(`State directory:       ${path8.relative(info.workspace_root, info.state_dir)}`);
-    if (Object.keys(meta).length > 0) {
-      emit("Workspace meta:");
-      for (const [k, v] of Object.entries(meta)) emit(`  ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
-    }
+// src/workspace/repos.ts
+import path7 from "path";
+
+// src/git/git.ts
+import fs5 from "fs/promises";
+import path6 from "path";
+import { execa } from "execa";
+import simpleGit from "simple-git";
+async function runGit(args, opts) {
+  let child;
+  try {
+    child = execa("git", args, {
+      cwd: opts.cwd,
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+      ...opts.signal ? { cancelSignal: opts.signal } : {},
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const res = await child;
+    return typeof res.stdout === "string" ? res.stdout : "";
+  } catch (err) {
+    const ee = err;
+    const stderr = typeof ee.stderr === "string" ? ee.stderr : "";
+    const stdout = typeof ee.stdout === "string" ? ee.stdout : "";
+    const code2 = ee.exitCode ?? -1;
+    const tail = stderr.trim() || stdout.trim() || ee.shortMessage || ee.message;
+    throw new RuntimeFailure(`git ${args.join(" ")} (exit ${code2}) in ${opts.cwd}
+  ${tail}`);
+  }
+}
+async function isGitRepo(dir) {
+  if (!await isDirectory(dir)) return false;
+  try {
+    await fs5.access(path6.join(dir, ".git"));
+    return true;
+  } catch {
     try {
-      await fs6.access(resolved.paths.workspaceMetaFile);
+      const out = await runGit(["rev-parse", "--is-inside-work-tree"], { cwd: dir });
+      return out.trim() === "true";
     } catch {
+      return false;
     }
-  });
-}
-
-// src/cli/commands/validate.ts
-import path9 from "path";
-import fs7 from "fs/promises";
-import pMap from "p-map";
-
-// src/util/concurrency.ts
-import os from "os";
-import pLimit from "p-limit";
-function resolveJobs(override) {
-  if (typeof override === "number" && Number.isFinite(override) && override >= 1) {
-    return Math.floor(override);
   }
-  const avail = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
-  return Math.max(1, avail);
 }
-
-// src/cli/commands/validate.ts
-function registerValidate(program) {
-  program.command("validate").description("Validate one or more qavor manifest files. Targets a file or a directory.").argument("<path>", "Path to a qavor.yaml file, a directory containing one, or a directory of multiple manifests.").action(async (target, _opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const logger = getLogger();
-    const abs = path9.resolve(target);
-    const files = [];
-    if (await isFile(abs)) {
-      files.push(abs);
-    } else if (await isDirectory(abs)) {
-      const direct = path9.join(abs, "qavor.yaml");
-      if (await isFile(direct)) files.push(direct);
-      try {
-        const entries = await fs7.readdir(abs, { withFileTypes: true });
-        for (const e of entries) {
-          if (e.isDirectory()) {
-            const child = path9.join(abs, e.name, "qavor.yaml");
-            if (await isFile(child)) files.push(child);
-          }
-          if (e.isFile() && e.name === "qavor.yaml") {
-          }
-        }
-      } catch {
-      }
-    } else {
-      throw new UserError(`Path not found: ${abs}`);
+async function readRepoStatus(dir) {
+  const git = simpleGit({ baseDir: dir });
+  let branch = null;
+  try {
+    const summary = await git.branch();
+    branch = summary.current || null;
+  } catch {
+    branch = null;
+  }
+  let ahead = 0;
+  let behind = 0;
+  try {
+    const counts = await runGit(["rev-list", "--left-right", "--count", "@{u}...HEAD"], {
+      cwd: dir
+    });
+    const [b, a] = counts.trim().split(/\s+/).map((n) => Number.parseInt(n, 10));
+    behind = Number.isFinite(b) ? b ?? 0 : 0;
+    ahead = Number.isFinite(a) ? a ?? 0 : 0;
+  } catch {
+  }
+  let dirtyCount = 0;
+  try {
+    const status = await git.status();
+    dirtyCount = status.files.length;
+  } catch {
+  }
+  let lastCommit = null;
+  let lastCommitSubject = null;
+  try {
+    const log = await git.log({ maxCount: 1 });
+    if (log.latest) {
+      lastCommit = log.latest.hash.slice(0, 7);
+      lastCommitSubject = log.latest.message;
     }
-    if (files.length === 0) throw new UserError(`No qavor.yaml files found under ${abs}.`);
-    const jobs = resolveJobs(root.jobs);
-    const issues = [];
-    await pMap(
-      files,
-      async (file) => {
-        try {
-          const docs = await loadManifestFile(file);
-          for (const d of docs) {
-            const r = validateDocument(d);
-            if (!r.ok) issues.push(...r.issues);
-          }
-        } catch (err) {
-          issues.push({
-            file,
-            line: 1,
-            column: 1,
-            kind: "unknown",
-            path: "",
-            message: err instanceof Error ? err.message : String(err)
-          });
-        }
-      },
-      { concurrency: jobs }
+  } catch {
+  }
+  return { branch, ahead, behind, dirtyCount, lastCommit, lastCommitSubject };
+}
+async function gitClone(opts) {
+  const args = ["clone"];
+  if (opts.branch && !opts.commit) args.push("--branch", opts.branch);
+  else if (opts.tag && !opts.commit) args.push("--branch", opts.tag);
+  if (opts.shallow) args.push("--depth", "1");
+  if (opts.submodules) args.push("--recurse-submodules");
+  args.push("--", opts.url, opts.dest);
+  await fs5.mkdir(path6.dirname(opts.dest), { recursive: true });
+  const runOpts = { cwd: path6.dirname(opts.dest) };
+  if (opts.signal) runOpts.signal = opts.signal;
+  await runGit(args, runOpts);
+  if (opts.commit) {
+    const checkoutOpts = { cwd: opts.dest };
+    if (opts.signal) checkoutOpts.signal = opts.signal;
+    await runGit(["checkout", opts.commit], checkoutOpts);
+  }
+}
+async function gitFetch(dir, signal) {
+  const opts = { cwd: dir };
+  if (signal) opts.signal = signal;
+  await runGit(["fetch", "--prune"], opts);
+}
+async function gitPullFastForward(dir, signal) {
+  const opts = { cwd: dir };
+  if (signal) opts.signal = signal;
+  await runGit(["pull", "--ff-only"], opts);
+}
+async function gitCommit(dir, message, opts = {}) {
+  const status = await runGit(["status", "--porcelain"], { cwd: dir });
+  if (status.trim().length === 0 && !opts.allowEmpty) {
+    return { committed: false };
+  }
+  const addOpts = { cwd: dir };
+  if (opts.signal) addOpts.signal = opts.signal;
+  await runGit(["add", "-A"], addOpts);
+  const args = ["commit", "-m", message];
+  if (opts.allowEmpty) args.push("--allow-empty");
+  const commitOpts = { cwd: dir };
+  if (opts.signal) commitOpts.signal = opts.signal;
+  await runGit(args, commitOpts);
+  return { committed: true };
+}
+async function gitPush(dir, signal) {
+  const opts = { cwd: dir };
+  if (signal) opts.signal = signal;
+  await runGit(["push"], opts);
+}
+function deriveCloneUrl(input) {
+  if (input.explicitUrl) return input.explicitUrl;
+  if (!input.rootUrl) {
+    throw new RuntimeFailure(
+      `Cannot derive clone URL for '${input.name}': project manifest has no git.root_url and no explicit url is set.`
     );
-    if (root.json) {
-      emitJson({ ok: issues.length === 0, files: files.length, issues });
-    } else {
-      if (issues.length === 0) {
-        emit(`OK \u2014 ${files.length} file(s) validated.`);
-      } else {
-        emit(`FAILED \u2014 ${issues.length} issue(s) across ${files.length} file(s):`);
-        for (const i of issues) emit(`  ${formatIssue(i)}`);
-      }
-    }
-    if (issues.length > 0) {
-      logger.debug({ count: issues.length }, "validation failed");
-      throw new ManifestError(`Validation failed with ${issues.length} issue(s).`);
-    }
-  });
+  }
+  const prefix = input.repoPrefix ?? "";
+  const base = input.rootUrl.endsWith("/") ? input.rootUrl.slice(0, -1) : input.rootUrl;
+  const fullName = `${prefix}${input.name}`;
+  return `${base}/${fullName}.git`;
 }
 
-// src/cli/commands/git.ts
-import path11 from "path";
-import pMap2 from "p-map";
-
 // src/workspace/repos.ts
-import path10 from "path";
 function resolveRepos(opts) {
   const list = opts.project.repositories;
   const repos = [];
@@ -1317,7 +1217,7 @@ function resolveRepos(opts) {
       throw new ManifestError(`Duplicate repository name in project manifest: '${name}'.`);
     }
     seen.add(name);
-    const dir = normalized.path ? path10.isAbsolute(normalized.path) ? normalized.path : path10.resolve(opts.workspaceRoot, normalized.path) : path10.join(opts.workspaceRoot, `${name}.git`);
+    const dir = normalized.path ? path7.isAbsolute(normalized.path) ? normalized.path : path7.resolve(opts.workspaceRoot, normalized.path) : path7.join(opts.workspaceRoot, `${name}.git`);
     const url = deriveCloneUrl({
       explicitUrl: normalized.url,
       rootUrl: opts.project.git?.root_url,
@@ -1334,399 +1234,179 @@ function resolveRepos(opts) {
       shallow: normalized.shallow ?? opts.project.git?.shallow,
       submodules: normalized.submodules ?? opts.project.git?.submodules,
       optional: Boolean(normalized.optional),
-      isProjectRepo: path10.resolve(dir) === path10.resolve(opts.projectRepoPath)
+      isProjectRepo: path7.resolve(dir) === path7.resolve(opts.projectRepoPath)
     });
   }
   return repos;
 }
 
-// src/cli/repos.ts
-function selectRepos(all, selector) {
-  if (!selector || selector.length === 0) return all;
-  const set = new Set(selector);
-  const out = [];
-  for (const r of all) {
-    if (set.has(r.name)) {
-      out.push(r);
-      set.delete(r.name);
-    }
-  }
-  if (set.size > 0) {
-    throw new Error(
-      `Unknown repo${set.size > 1 ? "s" : ""}: ${[...set].join(", ")}`
-    );
-  }
-  return out;
+// src/cli/options.ts
+function rootOptions(cmd) {
+  const opts = cmd.opts();
+  return {
+    json: Boolean(opts.json),
+    verbose: Boolean(opts.verbose),
+    jobs: typeof opts.jobs === "string" ? Number.parseInt(opts.jobs, 10) : void 0,
+    config: typeof opts.config === "string" ? opts.config : void 0
+  };
 }
-async function reposPresent(repos) {
-  const out = [];
-  for (const r of repos) {
-    if (await isDirectory(r.dir)) out.push(r);
-  }
-  return out;
+function inheritRootOptions(cmd) {
+  let current = cmd;
+  while (current?.parent) current = current.parent;
+  if (!current) return { json: false, verbose: false, jobs: void 0, config: void 0 };
+  return rootOptions(current);
 }
 
-// src/cli/commands/git.ts
-async function loadProjectRepos() {
-  const ws = await resolveWorkspace();
-  const project = await readProjectManifest(ws.projectManifestFile);
-  const repos = resolveRepos({
-    workspaceRoot: ws.paths.root,
-    project: project.data,
-    projectRepoPath: ws.projectRepoPath
-  });
-  return { workspaceRoot: ws.paths.root, repos };
-}
-function repoOption(c) {
-  return c.option("--repo <name...>", "Operate on a subset of repos by name.");
+// src/cli/commands/doctor.ts
+async function runShell(cmd, cwd) {
+  try {
+    const res = await execa2("/bin/sh", ["-c", cmd], { cwd, reject: false });
+    return { ok: res.exitCode === 0, exitCode: res.exitCode ?? -1 };
+  } catch {
+    return { ok: false, exitCode: -1 };
+  }
 }
-function registerGitCommands(program) {
-  repoOption(
-    program.command("clone").description("Clone every repo enumerated in the project manifest.")
-  ).action(async (opts, cmd) => {
+function registerDoctor(program) {
+  program.command("doctor").description(
+    "Verify toolchain prerequisites, workspace paths, and per-service check_installed steps."
+  ).action(async (_opts, cmd) => {
     const root = inheritRootOptions(cmd);
     const logger = getLogger();
-    const { workspaceRoot, repos } = await loadProjectRepos();
-    const selected = selectRepos(repos, opts.repo);
-    const jobs = resolveJobs(root.jobs);
-    const results = [];
-    await pMap2(
-      selected,
-      async (r) => {
-        if (r.isProjectRepo) {
-          results.push({ repo: r.name, status: "present", message: "project repo (already cloned)" });
-          return;
-        }
-        if (await isGitRepo(r.dir)) {
-          results.push({ repo: r.name, status: "present" });
-          return;
-        }
-        try {
-          logger.info({ repo: r.name, url: r.url, dir: r.dir }, "clone: starting");
-          await gitClone({
-            url: r.url,
-            dest: r.dir,
-            branch: r.branch,
-            tag: r.tag,
-            commit: r.commit,
-            shallow: r.shallow,
-            submodules: r.submodules
-          });
-          results.push({ repo: r.name, status: "cloned" });
-        } catch (err) {
-          if (r.optional) {
-            results.push({ repo: r.name, status: "skipped", message: "optional; clone failed" });
-          } else {
-            throw new RuntimeFailure(
-              `Clone failed for ${r.name}: ${err instanceof Error ? err.message : String(err)}`
-            );
-          }
-        }
-      },
-      { concurrency: jobs }
-    );
-    if (root.json) {
-      emitJson({ workspace: workspaceRoot, results });
-      return;
-    }
-    for (const r of results) {
-      emit(`${r.status.padEnd(8)} ${r.repo}${r.message ? "  \u2014 " + r.message : ""}`);
-    }
-  });
-  repoOption(
-    program.command("sync").description("Run `git fetch && git pull --ff-only` across selected repos.")
-  ).action(async (opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const { repos } = await loadProjectRepos();
-    const selected = await reposPresent(selectRepos(repos, opts.repo));
-    const jobs = resolveJobs(root.jobs);
-    const results = [];
-    await pMap2(
-      selected,
-      async (r) => {
-        try {
-          await gitFetch(r.dir);
-          await gitPullFastForward(r.dir);
-          results.push({ repo: r.name, ok: true });
-        } catch (err) {
-          results.push({ repo: r.name, ok: false, error: err instanceof Error ? err.message : String(err) });
-        }
-      },
-      { concurrency: jobs }
-    );
-    if (root.json) {
-      emitJson({ results });
-      return;
+    const checks = [];
+    try {
+      const res = await execa2("git", ["--version"]);
+      const version = res.stdout.trim().replace(/^git version /, "");
+      const [maj, min] = version.split(".").map((s) => Number.parseInt(s, 10));
+      if (Number.isFinite(maj) && Number.isFinite(min) && ((maj ?? 0) > 2 || (maj ?? 0) === 2 && (min ?? 0) >= 30)) {
+        checks.push({ name: "git \u2265 2.30", status: "ok", message: version });
+      } else {
+        checks.push({ name: "git \u2265 2.30", status: "warn", message: `found ${version}` });
+      }
+    } catch {
+      checks.push({
+        name: "git \u2265 2.30",
+        status: "fail",
+        message: "git not found",
+        hint: "Install git."
+      });
     }
-    for (const r of results) emit(`${r.ok ? "ok  " : "fail"} ${r.repo}${r.error ? "  \u2014 " + r.error : ""}`);
-    if (results.some((r) => !r.ok)) throw new RuntimeFailure("Some repos failed to sync.");
-  });
-  repoOption(
-    program.command("status").description("Aggregated repo status across selected repos.")
-  ).action(async (opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const { workspaceRoot, repos } = await loadProjectRepos();
-    const selected = await reposPresent(selectRepos(repos, opts.repo));
-    const jobs = resolveJobs(root.jobs);
-    const rows = await pMap2(
-      selected,
-      async (r) => {
-        const s = await readRepoStatus(r.dir);
-        return {
-          repo: r.name,
-          branch: s.branch,
-          ahead: s.ahead,
-          behind: s.behind,
-          dirty: s.dirtyCount,
-          last_commit: s.lastCommit,
-          last_commit_subject: s.lastCommitSubject
-        };
-      },
-      { concurrency: jobs }
-    );
-    if (root.json) {
-      emitJson({ workspace: workspaceRoot, repos: rows });
-      return;
+    try {
+      await execa2("docker", ["--version"]);
+      checks.push({ name: "docker (optional v0)", status: "ok" });
+    } catch {
+      checks.push({
+        name: "docker (optional v0)",
+        status: "warn",
+        message: "docker not detected"
+      });
     }
-    const headers = ["REPO", "BRANCH", "AHEAD", "BEHIND", "DIRTY", "COMMIT", "SUBJECT"];
-    const data = rows.map((r) => [
-      r.repo,
-      r.branch ?? "-",
-      String(r.ahead),
-      String(r.behind),
-      String(r.dirty),
-      r.last_commit ?? "-",
-      (r.last_commit_subject ?? "").split("\n")[0]?.slice(0, 60) ?? ""
-    ]);
-    const widths = headers.map(
-      (h, i) => Math.max(h.length, ...data.map((row) => (row[i] ?? "").length))
-    );
-    const fmt = (row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ");
-    emit(fmt(headers));
-    for (const row of data) emit(fmt(row));
-  });
-  repoOption(
-    program.command("commit").description("Commit pending changes across selected repos.").requiredOption("-m, --message <msg>", "Commit message.").option("--allow-empty", "Allow empty commits.")
-  ).action(
-    async (opts, cmd) => {
-      const root = inheritRootOptions(cmd);
-      if (!opts.message || opts.message.trim().length === 0) {
-        throw new UserError(`Commit message must not be empty.`);
+    try {
+      const ws = await resolveWorkspace();
+      await ensureDir(ws.paths.stateRoot);
+      const probe = path8.join(ws.paths.stateRoot, ".doctor-write-check");
+      await fs6.writeFile(probe, "");
+      await fs6.unlink(probe);
+      checks.push({
+        name: "workspace .qavor/ writable",
+        status: "ok",
+        message: ws.paths.stateRoot
+      });
+    } catch (err) {
+      checks.push({
+        name: "workspace .qavor/ writable",
+        status: "fail",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const cache = globalCacheDir();
+    try {
+      await ensureDir(cache);
+      const probe = path8.join(cache, ".doctor-write-check");
+      await fs6.writeFile(probe, "");
+      await fs6.unlink(probe);
+      checks.push({ name: "global cache writable", status: "ok", message: cache });
+    } catch (err) {
+      checks.push({
+        name: "global cache writable",
+        status: "fail",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    try {
+      const ws = await resolveWorkspace();
+      const project = await readProjectManifest(ws.projectManifestFile);
+      const repos = resolveRepos({
+        workspaceRoot: ws.paths.root,
+        project: project.data,
+        projectRepoPath: ws.projectRepoPath
+      });
+      const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
+      repoMap.set("__project__", ws.projectRepoPath);
+      const registry = await buildWorkspaceRegistry({
+        workspaceRoot: ws.paths.root,
+        repos: repoMap,
+        concurrency: resolveJobs(root.jobs)
+      });
+      for (const entry of registry.entries) {
+        if (entry.kind !== "service") continue;
+        const svc = entry.data;
+        const checkCmd = svc.runtime?.native?.check_installed?.cmd;
+        if (!checkCmd) {
+          checks.push({
+            name: `service ${entry.name}: check_installed`,
+            status: "warn",
+            message: "no runtime.native.check_installed.cmd"
+          });
+          continue;
+        }
+        const docs = await loadManifestFile(entry.file);
+        const serviceDoc = docs[entry.docIndex];
+        const cwd = svc.runtime?.native?.check_installed?.cwd ? path8.resolve(path8.dirname(serviceDoc.file), svc.runtime.native.check_installed.cwd) : path8.dirname(serviceDoc.file);
+        const res = await runShell(checkCmd, cwd);
+        if (res.ok) {
+          checks.push({ name: `service ${entry.name}: check_installed`, status: "ok" });
+        } else {
+          const installHint = svc.runtime?.native?.install?.cmd;
+          const failCheck = {
+            name: `service ${entry.name}: check_installed`,
+            status: "fail",
+            message: `exit ${res.exitCode}`
+          };
+          if (installHint) failCheck.hint = `Hint: \`${installHint}\``;
+          checks.push(failCheck);
+        }
       }
-      const { repos } = await loadProjectRepos();
-      const selected = await reposPresent(selectRepos(repos, opts.repo));
-      const jobs = resolveJobs(root.jobs);
-      const results = [];
-      await pMap2(
-        selected,
-        async (r) => {
-          try {
-            const res = await gitCommit(r.dir, opts.message, { allowEmpty: Boolean(opts.allowEmpty) });
-            results.push({ repo: r.name, committed: res.committed });
-          } catch (err) {
-            results.push({ repo: r.name, committed: false, error: err instanceof Error ? err.message : String(err) });
-          }
-        },
-        { concurrency: jobs }
+    } catch (err) {
+      logger.debug(
+        { err: err instanceof Error ? err.message : String(err) },
+        "doctor: workspace probe failed"
       );
-      if (root.json) {
-        emitJson({ results });
-        return;
-      }
-      for (const r of results) {
-        const verb = r.committed ? "committed" : r.error ? "failed" : "skipped";
-        emit(`${verb.padEnd(10)} ${r.repo}${r.error ? "  \u2014 " + r.error : ""}`);
-      }
-      if (results.some((r) => r.error)) throw new RuntimeFailure("Some commits failed.");
     }
-  );
-  repoOption(
-    program.command("push").description("git push the current branch across selected repos.")
-  ).action(async (opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const { repos } = await loadProjectRepos();
-    const selected = await reposPresent(selectRepos(repos, opts.repo));
-    const jobs = resolveJobs(root.jobs);
-    const results = [];
-    await pMap2(
-      selected,
-      async (r) => {
-        try {
-          await gitPush(r.dir);
-          results.push({ repo: r.name, ok: true });
-        } catch (err) {
-          results.push({ repo: r.name, ok: false, error: err instanceof Error ? err.message : String(err) });
-        }
-      },
-      { concurrency: jobs }
-    );
     if (root.json) {
-      emitJson({ results });
-      return;
+      emitJson({ checks, ok: checks.every((c) => c.status !== "fail") });
+    } else {
+      for (const c of checks) {
+        const sym = c.status === "ok" ? "\u2713" : c.status === "warn" ? "!" : "\u2717";
+        let line = `${sym} ${c.status.toUpperCase().padEnd(5)} ${c.name}`;
+        if (c.message) line += ` \u2014 ${c.message}`;
+        emit(line);
+        if (c.hint) emit(`     ${c.hint}`);
+      }
+    }
+    if (checks.some((c) => c.status === "fail")) {
+      throw new RuntimeFailure("doctor: one or more checks failed.");
     }
-    for (const r of results) emit(`${r.ok ? "ok  " : "fail"} ${r.repo}${r.error ? "  \u2014 " + r.error : ""}`);
-    if (results.some((r) => !r.ok)) throw new RuntimeFailure("Some pushes failed.");
   });
-  void path11;
 }
 
-// src/cli/commands/prepare.ts
-import pMap4 from "p-map";
-
-// src/manifest/discovery.ts
-import fs8 from "fs/promises";
-import path12 from "path";
-import pMap3 from "p-map";
-var MAX_DEPTH = 4;
-var SKIP_DIRS = /* @__PURE__ */ new Set([
-  ".git",
-  ".qavor",
-  "node_modules",
-  ".venv",
-  "venv",
-  "__pycache__",
-  "dist",
-  "build",
-  "target",
-  ".next",
-  ".svelte-kit",
-  ".cache"
-]);
-async function discoverManifestFiles(repoRoot) {
-  const abs = path12.resolve(repoRoot);
-  const found = /* @__PURE__ */ new Set();
-  if (!await isDirectory(abs)) return [];
-  const rootFile = path12.join(abs, "qavor.yaml");
-  try {
-    await fs8.access(rootFile);
-    found.add(rootFile);
-  } catch {
-  }
-  const qavorDir = path12.join(abs, "qavor");
-  if (await isDirectory(qavorDir)) {
-    for await (const f of walk(qavorDir, qavorDir, 0)) found.add(f);
-  }
-  for await (const f of walk(abs, abs, 0)) {
-    found.add(f);
-  }
-  return [...found].sort();
-}
-async function* walk(rootBase, current, depth) {
-  if (depth > MAX_DEPTH) return;
-  let entries;
-  try {
-    entries = await fs8.readdir(current, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const full = path12.join(current, entry.name);
-    if (entry.isDirectory()) {
-      if (SKIP_DIRS.has(entry.name)) continue;
-      if (depth === 0 && entry.name === "qavor") continue;
-      yield* walk(rootBase, full, depth + 1);
-    } else if (entry.isFile() && entry.name === "qavor.yaml") {
-      if (depth === 0 && current === rootBase) continue;
-      yield full;
-    }
-  }
-}
-async function buildWorkspaceRegistry(opts) {
-  const issues = [];
-  const all = [];
-  const reposList = [];
-  for (const [name, dir] of opts.repos) reposList.push({ name, dir });
-  await pMap3(
-    reposList,
-    async ({ name: repoName, dir }) => {
-      const files = await discoverManifestFiles(dir);
-      for (const file of files) {
-        let docs;
-        try {
-          docs = await loadManifestFile(file);
-        } catch (err) {
-          issues.push({
-            file,
-            line: 1,
-            column: 1,
-            kind: "unknown",
-            path: "",
-            message: err instanceof Error ? err.message : String(err)
-          });
-          continue;
-        }
-        for (const doc of docs) {
-          if (!isKnownKind(doc.kind)) {
-            const pos = doc.position("/kind");
-            issues.push({
-              file: pos.file,
-              line: pos.line,
-              column: pos.column,
-              kind: String(doc.kind ?? "unknown"),
-              path: "/kind",
-              message: `Unknown or missing kind in this document`
-            });
-            continue;
-          }
-          const result = validateDocument(doc);
-          if (!result.ok) {
-            issues.push(...result.issues);
-            continue;
-          }
-          const data = doc.data;
-          all.push({
-            kind: doc.kind,
-            name: typeof data.name === "string" ? data.name : "",
-            file: doc.file,
-            docIndex: doc.docIndex,
-            dir: path12.dirname(doc.file),
-            repo: repoName,
-            data: doc.data,
-            position: doc.position
-          });
-        }
-      }
-    },
-    { concurrency: opts.concurrency ?? 8 }
-  );
-  const byName = /* @__PURE__ */ new Map();
-  for (const entry of all) {
-    if (!entry.name) continue;
-    if (entry.kind === "workspaces" || entry.kind === "project") continue;
-    const key = entry.name;
-    const existing = byName.get(key);
-    if (existing && existing.kind === entry.kind) {
-      const pos = entry.position("/name");
-      issues.push({
-        file: pos.file,
-        line: pos.line,
-        column: pos.column,
-        kind: entry.kind,
-        path: "/name",
-        message: `Duplicate ${entry.kind} name '${entry.name}'. Already declared at ${existing.file}.`
-      });
-      continue;
-    }
-    if (!existing) byName.set(key, entry);
-  }
-  return { byName, entries: all, issues };
-}
-
-// src/prepare/prepare.ts
-import { createHash as createHash3 } from "crypto";
-import { createReadStream as createReadStream2 } from "fs";
-import fs10 from "fs/promises";
-import path14 from "path";
-import { execa as execa3 } from "execa";
-
-// src/env/composer.ts
-import path13 from "path";
+// src/env/composer.ts
+import path9 from "path";
 
 // src/env/dotenv.ts
-import fs9 from "fs/promises";
+import fs7 from "fs/promises";
 async function loadDotenvFile(file) {
   if (!await pathExists(file)) return [];
-  const raw = await fs9.readFile(file, "utf8");
+  const raw = await fs7.readFile(file, "utf8");
   const lines = raw.split(/\r?\n/);
   const out = [];
   for (let i = 0; i < lines.length; i++) {
@@ -1757,18 +1437,39 @@ async function loadDotenvFile(file) {
 async function composeServiceEnv(input) {
   const issues = [];
   const layers = [];
-  const manifestDir = path13.dirname(input.serviceDoc.file);
+  const manifestDir = path9.dirname(input.serviceDoc.file);
   const env = input.service.env;
   const positionFor = input.serviceDoc.position;
   if (env?.common) {
-    pushEnvMap(layers, env.common, "service.env.common", input.serviceDoc.file, positionFor, "/env/common");
+    pushEnvMap(
+      layers,
+      env.common,
+      "service.env.common",
+      input.serviceDoc.file,
+      positionFor,
+      "/env/common"
+    );
   }
   if (input.mode === "native" && env?.native) {
-    pushEnvMap(layers, env.native, "service.env.native", input.serviceDoc.file, positionFor, "/env/native");
+    pushEnvMap(
+      layers,
+      env.native,
+      "service.env.native",
+      input.serviceDoc.file,
+      positionFor,
+      "/env/native"
+    );
   } else if (input.mode === "docker" && env?.docker) {
-    pushEnvMap(layers, env.docker, "service.env.docker", input.serviceDoc.file, positionFor, "/env/docker");
+    pushEnvMap(
+      layers,
+      env.docker,
+      "service.env.docker",
+      input.serviceDoc.file,
+      positionFor,
+      "/env/docker"
+    );
   }
-  const baseDotenv = await loadDotenvFile(path13.join(manifestDir, ".env"));
+  const baseDotenv = await loadDotenvFile(path9.join(manifestDir, ".env"));
   for (const e of baseDotenv) {
     layers.push({
       key: e.key,
@@ -1779,7 +1480,10 @@ async function composeServiceEnv(input) {
       spec: null
     });
   }
-  const modeDotenvFile = path13.join(manifestDir, input.mode === "native" ? ".env.native" : ".env.docker");
+  const modeDotenvFile = path9.join(
+    manifestDir,
+    input.mode === "native" ? ".env.native" : ".env.docker"
+  );
   const modeDotenv = await loadDotenvFile(modeDotenvFile);
   for (const e of modeDotenv) {
     layers.push({
@@ -1791,7 +1495,7 @@ async function composeServiceEnv(input) {
       spec: null
     });
   }
-  const wsEnv = await loadDotenvFile(path13.join(input.workspaceRoot, ".env"));
+  const wsEnv = await loadDotenvFile(path9.join(input.workspaceRoot, ".env"));
   for (const e of wsEnv) {
     layers.push({
       key: e.key,
@@ -1914,54 +1618,529 @@ function interpolateLayers(layers, issues) {
       });
     }
   }
-  return { values, issues };
-}
-function interpolate(raw, resolved, procEnv) {
-  if (!raw) return { value: raw, missing: [], secrets: [] };
-  const missing = [];
-  const secrets = [];
-  const value = raw.replace(INTERP_RE, (_m, expr) => {
-    const trimmed = expr.trim();
-    if (trimmed.startsWith(SECRET_PREFIX)) {
-      secrets.push(trimmed.slice(SECRET_PREFIX.length));
-      return "";
-    }
-    const fromResolved = resolved.get(trimmed);
-    if (fromResolved) return fromResolved.value;
-    const fromProc = procEnv[trimmed];
-    if (typeof fromProc === "string") return fromProc;
-    missing.push(trimmed);
-    return "";
+  return { values, issues };
+}
+function interpolate(raw, resolved, procEnv) {
+  if (!raw) return { value: raw, missing: [], secrets: [] };
+  const missing = [];
+  const secrets = [];
+  const value = raw.replace(INTERP_RE, (_m, expr) => {
+    const trimmed = expr.trim();
+    if (trimmed.startsWith(SECRET_PREFIX)) {
+      secrets.push(trimmed.slice(SECRET_PREFIX.length));
+      return "";
+    }
+    const fromResolved = resolved.get(trimmed);
+    if (fromResolved) return fromResolved.value;
+    const fromProc = procEnv[trimmed];
+    if (typeof fromProc === "string") return fromProc;
+    missing.push(trimmed);
+    return "";
+  });
+  return { value, missing, secrets };
+}
+function parseCliEnv(items) {
+  const out = {};
+  for (const item of items) {
+    const eq = item.indexOf("=");
+    if (eq <= 0) throw new UserError(`Invalid --env value '${item}'. Expected KEY=VALUE.`);
+    const key = item.slice(0, eq);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new UserError(`Invalid env key '${key}' in --env. Use UPPER_SNAKE_CASE.`);
+    }
+    out[key] = item.slice(eq + 1);
+  }
+  return out;
+}
+function toEnvObject(resolved) {
+  const out = {};
+  for (const [k, v] of resolved.values) out[k] = v.value;
+  return out;
+}
+function assertNoIssues(resolved) {
+  if (resolved.issues.length === 0) return;
+  const lines = resolved.issues.map((i) => `${i.file}:${i.line}: ${i.message}`);
+  throw new ManifestError(`Environment composition failed:
+  ${lines.join("\n  ")}`);
+}
+
+// src/cli/commands/env.ts
+function registerEnv(program) {
+  program.command("env").description("Print the fully-resolved environment for a service, with provenance per key.").argument("<service>", "Service name.").option("--mode <mode>", "native | docker (default: native).", "native").option("--env <kv...>", "Layer KEY=VAL on top of the composed env.").action(async (service, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const mode = opts.mode === "docker" ? "docker" : "native";
+    if (opts.mode !== "native" && opts.mode !== "docker") {
+      throw new UserError(`--mode must be 'native' or 'docker'.`);
+    }
+    const ws = await resolveWorkspace();
+    const projectDoc = await readProjectManifest(ws.projectManifestFile);
+    const repos = resolveRepos({
+      workspaceRoot: ws.paths.root,
+      project: projectDoc.data,
+      projectRepoPath: ws.projectRepoPath
+    });
+    const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
+    repoMap.set("__project__", ws.projectRepoPath);
+    const registry = await buildWorkspaceRegistry({
+      workspaceRoot: ws.paths.root,
+      repos: repoMap,
+      concurrency: resolveJobs(root.jobs)
+    });
+    const entry = registry.entries.find((e) => e.kind === "service" && e.name === service);
+    if (!entry) throw new UserError(`Service '${service}' not found in workspace.`);
+    const docs = await loadManifestFile(entry.file);
+    const serviceDoc = docs[entry.docIndex];
+    const cliEnv = opts.env ? parseCliEnv(opts.env) : void 0;
+    const composeOpts = {
+      mode,
+      serviceDoc,
+      service: entry.data,
+      workspaceRoot: ws.paths.root
+    };
+    if (cliEnv) composeOpts.cliEnv = cliEnv;
+    const resolved = await composeServiceEnv(composeOpts);
+    if (root.json) {
+      emitJson({
+        service,
+        mode,
+        issues: resolved.issues,
+        env: [...resolved.values].map(([k, v]) => ({
+          key: k,
+          value: v.secret ? "<redacted>" : v.value,
+          secret: v.secret,
+          required: v.required,
+          provenance: v.provenance.map((p) => ({
+            file: p.file,
+            line: p.line,
+            layer: p.layer,
+            raw: v.secret ? "<redacted>" : p.raw
+          }))
+        }))
+      });
+      return;
+    }
+    if (resolved.issues.length > 0) {
+      emit("Issues:");
+      for (const i of resolved.issues) emit(`  ${i.file}:${i.line}: ${i.message}`);
+      emit("");
+    }
+    emit(`Resolved environment for ${service} (mode=${mode}):`);
+    for (const [k, v] of resolved.values) {
+      const printed = v.secret ? "<redacted>" : v.value;
+      emit(`  ${k} = ${printed}`);
+      for (const p of v.provenance) {
+        const rawPrinted = v.secret ? "<redacted>" : p.raw;
+        emit(`    via ${p.layer} (${p.file}:${p.line}) = ${rawPrinted}`);
+      }
+    }
+  });
+}
+
+// src/cli/commands/git.ts
+import path10 from "path";
+import pMap2 from "p-map";
+
+// src/cli/repos.ts
+function selectRepos(all, selector) {
+  if (!selector || selector.length === 0) return all;
+  const set = new Set(selector);
+  const out = [];
+  for (const r of all) {
+    if (set.has(r.name)) {
+      out.push(r);
+      set.delete(r.name);
+    }
+  }
+  if (set.size > 0) {
+    throw new Error(`Unknown repo${set.size > 1 ? "s" : ""}: ${[...set].join(", ")}`);
+  }
+  return out;
+}
+async function reposPresent(repos) {
+  const out = [];
+  for (const r of repos) {
+    if (await isDirectory(r.dir)) out.push(r);
+  }
+  return out;
+}
+
+// src/cli/commands/git.ts
+async function loadProjectRepos() {
+  const ws = await resolveWorkspace();
+  const project = await readProjectManifest(ws.projectManifestFile);
+  const repos = resolveRepos({
+    workspaceRoot: ws.paths.root,
+    project: project.data,
+    projectRepoPath: ws.projectRepoPath
+  });
+  return { workspaceRoot: ws.paths.root, repos };
+}
+function repoOption(c) {
+  return c.option("--repo <name...>", "Operate on a subset of repos by name.");
+}
+function registerGitCommands(program) {
+  repoOption(
+    program.command("clone").description("Clone every repo enumerated in the project manifest.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const { workspaceRoot, repos } = await loadProjectRepos();
+    const selected = selectRepos(repos, opts.repo);
+    const jobs = resolveJobs(root.jobs);
+    const results = [];
+    await pMap2(
+      selected,
+      async (r) => {
+        if (r.isProjectRepo) {
+          results.push({
+            repo: r.name,
+            status: "present",
+            message: "project repo (already cloned)"
+          });
+          return;
+        }
+        if (await isGitRepo(r.dir)) {
+          results.push({ repo: r.name, status: "present" });
+          return;
+        }
+        try {
+          logger.info({ repo: r.name, url: r.url, dir: r.dir }, "clone: starting");
+          await gitClone({
+            url: r.url,
+            dest: r.dir,
+            branch: r.branch,
+            tag: r.tag,
+            commit: r.commit,
+            shallow: r.shallow,
+            submodules: r.submodules
+          });
+          results.push({ repo: r.name, status: "cloned" });
+        } catch (err) {
+          if (r.optional) {
+            results.push({ repo: r.name, status: "skipped", message: "optional; clone failed" });
+          } else {
+            throw new RuntimeFailure(
+              `Clone failed for ${r.name}: ${err instanceof Error ? err.message : String(err)}`
+            );
+          }
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ workspace: workspaceRoot, results });
+      return;
+    }
+    for (const r of results) {
+      emit(`${r.status.padEnd(8)} ${r.repo}${r.message ? `  \u2014 ${r.message}` : ""}`);
+    }
+  });
+  repoOption(
+    program.command("sync").description("Run `git fetch && git pull --ff-only` across selected repos.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const { repos } = await loadProjectRepos();
+    const selected = await reposPresent(selectRepos(repos, opts.repo));
+    const jobs = resolveJobs(root.jobs);
+    const results = [];
+    await pMap2(
+      selected,
+      async (r) => {
+        try {
+          await gitFetch(r.dir);
+          await gitPullFastForward(r.dir);
+          results.push({ repo: r.name, ok: true });
+        } catch (err) {
+          results.push({
+            repo: r.name,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ results });
+      return;
+    }
+    for (const r of results)
+      emit(`${r.ok ? "ok  " : "fail"} ${r.repo}${r.error ? `  \u2014 ${r.error}` : ""}`);
+    if (results.some((r) => !r.ok)) throw new RuntimeFailure("Some repos failed to sync.");
+  });
+  repoOption(
+    program.command("status").description("Aggregated repo status across selected repos.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const { workspaceRoot, repos } = await loadProjectRepos();
+    const selected = await reposPresent(selectRepos(repos, opts.repo));
+    const jobs = resolveJobs(root.jobs);
+    const rows = await pMap2(
+      selected,
+      async (r) => {
+        const s = await readRepoStatus(r.dir);
+        return {
+          repo: r.name,
+          branch: s.branch,
+          ahead: s.ahead,
+          behind: s.behind,
+          dirty: s.dirtyCount,
+          last_commit: s.lastCommit,
+          last_commit_subject: s.lastCommitSubject
+        };
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ workspace: workspaceRoot, repos: rows });
+      return;
+    }
+    const headers = ["REPO", "BRANCH", "AHEAD", "BEHIND", "DIRTY", "COMMIT", "SUBJECT"];
+    const data = rows.map((r) => [
+      r.repo,
+      r.branch ?? "-",
+      String(r.ahead),
+      String(r.behind),
+      String(r.dirty),
+      r.last_commit ?? "-",
+      (r.last_commit_subject ?? "").split("\n")[0]?.slice(0, 60) ?? ""
+    ]);
+    const widths = headers.map(
+      (h, i) => Math.max(h.length, ...data.map((row) => (row[i] ?? "").length))
+    );
+    const fmt = (row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ");
+    emit(fmt(headers));
+    for (const row of data) emit(fmt(row));
+  });
+  repoOption(
+    program.command("commit").description("Commit pending changes across selected repos.").requiredOption("-m, --message <msg>", "Commit message.").option("--allow-empty", "Allow empty commits.")
+  ).action(
+    async (opts, cmd) => {
+      const root = inheritRootOptions(cmd);
+      if (!opts.message || opts.message.trim().length === 0) {
+        throw new UserError(`Commit message must not be empty.`);
+      }
+      const { repos } = await loadProjectRepos();
+      const selected = await reposPresent(selectRepos(repos, opts.repo));
+      const jobs = resolveJobs(root.jobs);
+      const results = [];
+      await pMap2(
+        selected,
+        async (r) => {
+          try {
+            const res = await gitCommit(r.dir, opts.message, {
+              allowEmpty: Boolean(opts.allowEmpty)
+            });
+            results.push({ repo: r.name, committed: res.committed });
+          } catch (err) {
+            results.push({
+              repo: r.name,
+              committed: false,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        },
+        { concurrency: jobs }
+      );
+      if (root.json) {
+        emitJson({ results });
+        return;
+      }
+      for (const r of results) {
+        const verb = r.committed ? "committed" : r.error ? "failed" : "skipped";
+        emit(`${verb.padEnd(10)} ${r.repo}${r.error ? `  \u2014 ${r.error}` : ""}`);
+      }
+      if (results.some((r) => r.error)) throw new RuntimeFailure("Some commits failed.");
+    }
+  );
+  repoOption(
+    program.command("push").description("git push the current branch across selected repos.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const { repos } = await loadProjectRepos();
+    const selected = await reposPresent(selectRepos(repos, opts.repo));
+    const jobs = resolveJobs(root.jobs);
+    const results = [];
+    await pMap2(
+      selected,
+      async (r) => {
+        try {
+          await gitPush(r.dir);
+          results.push({ repo: r.name, ok: true });
+        } catch (err) {
+          results.push({
+            repo: r.name,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ results });
+      return;
+    }
+    for (const r of results)
+      emit(`${r.ok ? "ok  " : "fail"} ${r.repo}${r.error ? `  \u2014 ${r.error}` : ""}`);
+    if (results.some((r) => !r.ok)) throw new RuntimeFailure("Some pushes failed.");
+  });
+  void path10;
+}
+
+// src/cli/commands/init.ts
+import path12 from "path";
+
+// src/workspace/init.ts
+import { createHash as createHash2 } from "crypto";
+import fs8 from "fs/promises";
+import path11 from "path";
+var URL_RE = /^(?:git@[^:]+:|https?:\/\/|git:\/\/|ssh:\/\/|file:\/\/)/;
+function looksLikeGitUrl(s) {
+  return URL_RE.test(s);
+}
+function projectRepoNameFromUrl(url) {
+  const cleaned = url.replace(/[?#].*$/, "");
+  const last = cleaned.split("/").pop() ?? cleaned.split(":").pop() ?? "project";
+  return last.replace(/\.git$/, "");
+}
+async function initWorkspace(opts) {
+  const workspaceRoot = path11.resolve(opts.into ?? process.cwd());
+  await ensureDir(workspaceRoot);
+  const paths = workspacePaths(workspaceRoot);
+  let projectRepoPath;
+  let cloned = false;
+  if (looksLikeGitUrl(opts.source)) {
+    const repoName = projectRepoNameFromUrl(opts.source);
+    const target = path11.join(workspaceRoot, `${repoName}.git`);
+    if (await isDirectory(target)) {
+      if (!await isGitRepo(target)) {
+        throw new UserError(
+          `Cannot reuse ${target}: directory exists but is not a git repo. Move it aside and re-run.`
+        );
+      }
+      opts.logger.info({ target }, "reusing existing project repo clone");
+      projectRepoPath = target;
+    } else {
+      const cacheDir = path11.join(globalCacheDir(), "projects", urlHash(opts.source));
+      await ensureDir(path11.dirname(cacheDir));
+      opts.logger.info({ url: opts.source, target }, "cloning project repo");
+      await gitClone({ url: opts.source, dest: target });
+      try {
+        await ensureDir(cacheDir);
+        await fs8.writeFile(
+          path11.join(cacheDir, "source.json"),
+          JSON.stringify(
+            { url: opts.source, cloned_to: target, at: (/* @__PURE__ */ new Date()).toISOString() },
+            null,
+            2
+          )
+        );
+      } catch {
+      }
+      projectRepoPath = target;
+      cloned = true;
+    }
+  } else {
+    const localPath = path11.resolve(opts.source);
+    if (!await isDirectory(localPath)) {
+      throw new UserError(`Project repo source does not exist or is not a directory: ${localPath}`);
+    }
+    projectRepoPath = localPath;
+  }
+  const projectManifestFile = path11.join(projectRepoPath, "qavor.yaml");
+  const docs = await loadManifestFile(projectManifestFile);
+  const projectDoc = docs.find((d) => d.kind === "project");
+  if (!projectDoc) {
+    throw new ManifestError(
+      `Project repo at ${projectRepoPath} is missing a \`kind: project\` document in qavor.yaml.`
+    );
+  }
+  const result = validateDocument(projectDoc);
+  if (!result.ok) {
+    const msg = result.issues.map((i) => `  ${i.file}:${i.line}:${i.column} ${i.path}: ${i.message}`).join("\n");
+    throw new ManifestError(`Invalid project manifest:
+${msg}`);
+  }
+  const project = projectDoc.data;
+  await ensureDir(paths.stateRoot);
+  await ensureDir(paths.stateDir);
+  await ensureDir(paths.logsDir);
+  await ensureDir(paths.composeDir);
+  await ensureDir(paths.cacheDir);
+  await fs8.writeFile(
+    paths.stateGitignore,
+    [
+      "# qavor state directory \u2014 all files are generated. Do not commit.",
+      "*",
+      "!.gitignore",
+      ""
+    ].join("\n")
+  );
+  const relProjectPath = `./${path11.relative(workspaceRoot, projectRepoPath).split(path11.sep).join("/")}`;
+  const workspacesYaml = renderWorkspacesYaml(relProjectPath);
+  await fs8.writeFile(paths.workspacesFile, workspacesYaml, "utf8");
+  const manifestHash = createHash2("sha256").update(await fs8.readFile(projectManifestFile)).digest("hex");
+  await writeJsonFile(paths.workspaceMetaFile, {
+    project_name: project.name,
+    project_repo_path: projectRepoPath,
+    manifest_hash: manifestHash,
+    initialized_at: (/* @__PURE__ */ new Date()).toISOString()
   });
-  return { value, missing, secrets };
+  return { paths, projectRepoPath, project, cloned };
 }
-function parseCliEnv(items) {
-  const out = {};
-  for (const item of items) {
-    const eq = item.indexOf("=");
-    if (eq <= 0) throw new UserError(`Invalid --env value '${item}'. Expected KEY=VALUE.`);
-    const key = item.slice(0, eq);
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-      throw new UserError(`Invalid env key '${key}' in --env. Use UPPER_SNAKE_CASE.`);
-    }
-    out[key] = item.slice(eq + 1);
-  }
-  return out;
+function urlHash(url) {
+  return createHash2("sha256").update(url).digest("hex").slice(0, 16);
 }
-function toEnvObject(resolved) {
-  const out = {};
-  for (const [k, v] of resolved.values) out[k] = v.value;
-  return out;
+function renderWorkspacesYaml(relProjectPath) {
+  return [
+    "# Generated by `qavor init`. Points at the project repo whose",
+    "# `kind: project` manifest enumerates the rest of the workspace.",
+    "kind: workspaces",
+    `root_project_path: ${relProjectPath}`,
+    ""
+  ].join("\n");
 }
-function assertNoIssues(resolved) {
-  if (resolved.issues.length === 0) return;
-  const lines = resolved.issues.map((i) => `${i.file}:${i.line}: ${i.message}`);
-  throw new ManifestError(`Environment composition failed:
-  ${lines.join("\n  ")}`);
+
+// src/cli/commands/init.ts
+function registerInit(program) {
+  program.command("init").description("Bootstrap a workspace from a project repo (local path or git URL).").argument("<source>", "Local path to a project repo, or a git URL.").option("--into <dir>", "Workspace root directory. Defaults to the current directory.").action(async (source, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const initOpts = { source, logger };
+    if (opts.into) initOpts.into = opts.into;
+    const result = await initWorkspace(initOpts);
+    if (root.json) {
+      emitJson({
+        ok: true,
+        workspace: result.paths.root,
+        project_name: result.project.name,
+        project_repo_path: result.projectRepoPath,
+        cloned_project: result.cloned,
+        repositories: result.project.repositories.length
+      });
+    } else {
+      emit(`Workspace initialized at ${result.paths.root}`);
+      emit(`  project: ${result.project.name}`);
+      emit(`  project repo: ${path12.relative(result.paths.root, result.projectRepoPath)}`);
+      emit(`  repositories declared: ${result.project.repositories.length}`);
+      emit(`  next: qavor clone`);
+    }
+  });
 }
 
+// src/cli/commands/prepare.ts
+import pMap3 from "p-map";
+
+// src/prepare/prepare.ts
+import { createHash as createHash3 } from "crypto";
+import { createReadStream as createReadStream2 } from "fs";
+import fs9 from "fs/promises";
+import path13 from "path";
+import { execa as execa4 } from "execa";
+
 // src/util/hooks.ts
-import { execa as execa2 } from "execa";
+import { execa as execa3 } from "execa";
 function toList(cmds) {
   if (!cmds) return [];
   return Array.isArray(cmds) ? [...cmds] : [cmds];
@@ -1972,7 +2151,7 @@ async function runHooks(opts) {
   for (const cmd of cmds) {
     opts.logger.info({ event: opts.event, cmd }, "hook: running");
     try {
-      await execa2("/bin/sh", ["-c", cmd], {
+      await execa3("/bin/sh", ["-c", cmd], {
         cwd: opts.cwd,
         env: opts.env ? { ...process.env, ...opts.env } : process.env,
         stdout: "inherit",
@@ -2009,13 +2188,16 @@ async function prepareService(input) {
       hash: null
     };
   }
-  const manifestDir = path14.dirname(input.serviceDoc.file);
-  const cacheFile = path14.join(input.paths.cacheDir, "prepare", `${input.service.name}.json`);
+  const manifestDir = path13.dirname(input.serviceDoc.file);
+  const cacheFile = path13.join(input.paths.cacheDir, "prepare", `${input.service.name}.json`);
   const hash = await computePrepareHash(manifestDir, cmd);
   if (!input.force) {
     const prev = await readPrev(cacheFile);
     if (prev && prev.hash === hash) {
-      input.logger.info({ service: input.service.name }, "prepare: lockfile hash unchanged; skipping");
+      input.logger.info(
+        { service: input.service.name },
+        "prepare: lockfile hash unchanged; skipping"
+      );
       return { serviceName: input.service.name, status: "skipped", cacheFile, hash };
     }
   }
@@ -2036,11 +2218,11 @@ async function prepareService(input) {
     logger: input.logger,
     ...input.signal ? { signal: input.signal } : {}
   });
-  await ensureDir(path14.join(input.paths.logsDir, input.service.name));
-  const logFile = path14.join(input.paths.logsDir, input.service.name, "prepare.log");
+  await ensureDir(path13.join(input.paths.logsDir, input.service.name));
+  const logFile = path13.join(input.paths.logsDir, input.service.name, "prepare.log");
   input.logger.info({ service: input.service.name, cmd }, "prepare: starting");
-  const cwd = input.service.runtime?.native?.prepare?.cwd ? path14.resolve(manifestDir, input.service.runtime.native.prepare.cwd) : manifestDir;
-  const fileHandle = await fs10.open(logFile, "a");
+  const cwd = input.service.runtime?.native?.prepare?.cwd ? path13.resolve(manifestDir, input.service.runtime.native.prepare.cwd) : manifestDir;
+  const fileHandle = await fs9.open(logFile, "a");
   const shell = input.service.runtime?.native?.prepare?.shell ?? "/bin/sh";
   try {
     const opts = {
@@ -2050,7 +2232,7 @@ async function prepareService(input) {
       ...input.signal ? { cancelSignal: input.signal } : {},
       reject: false
     };
-    const res = await execa3(shell, ["-c", cmd], opts);
+    const res = await execa4(shell, ["-c", cmd], opts);
     if (res.exitCode !== 0) {
       throw new RuntimeFailure(
         `prepare failed for ${input.service.name} (exit ${res.exitCode}). See ${logFile}.`
@@ -2091,9 +2273,10 @@ async function readPrev(file) {
 }
 async function computePrepareHash(manifestDir, cmd) {
   const hash = createHash3("sha256");
-  hash.update("cmd:" + cmd + "\n");
+  hash.update(`cmd:${cmd}
+`);
   for (const candidate of DEFAULT_LOCK_PATTERNS) {
-    const file = path14.join(manifestDir, candidate);
+    const file = path13.join(manifestDir, candidate);
     const stat = await safeStat(file);
     if (!stat) {
       hash.update(`missing:${candidate}
@@ -2112,7 +2295,7 @@ mtime:${stat.mtimeMs}
 }
 async function safeStat(file) {
   try {
-    return await fs10.stat(file);
+    return await fs9.stat(file);
   } catch {
     return null;
   }
@@ -2162,7 +2345,7 @@ function registerPrepare(program) {
       }
       const cliEnv = opts.env ? parseCliEnv(opts.env) : void 0;
       const jobs = resolveJobs(root.jobs);
-      const results = await pMap4(
+      const results = await pMap3(
         services,
         async (entry) => {
           const docs = await loadManifestFile(entry.file);
@@ -2191,82 +2374,84 @@ function registerPrepare(program) {
   );
 }
 
-// src/cli/commands/env.ts
-function registerEnv(program) {
-  program.command("env").description("Print the fully-resolved environment for a service, with provenance per key.").argument("<service>", "Service name.").option("--mode <mode>", "native | docker (default: native).", "native").option("--env <kv...>", "Layer KEY=VAL on top of the composed env.").action(async (service, opts, cmd) => {
-    const root = inheritRootOptions(cmd);
-    const mode = opts.mode === "docker" ? "docker" : "native";
-    if (opts.mode !== "native" && opts.mode !== "docker") {
-      throw new UserError(`--mode must be 'native' or 'docker'.`);
-    }
-    const ws = await resolveWorkspace();
-    const projectDoc = await readProjectManifest(ws.projectManifestFile);
-    const repos = resolveRepos({
-      workspaceRoot: ws.paths.root,
-      project: projectDoc.data,
-      projectRepoPath: ws.projectRepoPath
-    });
-    const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
-    repoMap.set("__project__", ws.projectRepoPath);
-    const registry = await buildWorkspaceRegistry({
-      workspaceRoot: ws.paths.root,
-      repos: repoMap,
-      concurrency: resolveJobs(root.jobs)
-    });
-    const entry = registry.entries.find((e) => e.kind === "service" && e.name === service);
-    if (!entry) throw new UserError(`Service '${service}' not found in workspace.`);
-    const docs = await loadManifestFile(entry.file);
-    const serviceDoc = docs[entry.docIndex];
-    const cliEnv = opts.env ? parseCliEnv(opts.env) : void 0;
-    const composeOpts = {
-      mode,
-      serviceDoc,
-      service: entry.data,
-      workspaceRoot: ws.paths.root
-    };
-    if (cliEnv) composeOpts.cliEnv = cliEnv;
-    const resolved = await composeServiceEnv(composeOpts);
-    if (root.json) {
-      emitJson({
-        service,
-        mode,
-        issues: resolved.issues,
-        env: [...resolved.values].map(([k, v]) => ({
-          key: k,
-          value: v.secret ? "<redacted>" : v.value,
-          secret: v.secret,
-          required: v.required,
-          provenance: v.provenance.map((p) => ({
-            file: p.file,
-            line: p.line,
-            layer: p.layer,
-            raw: v.secret ? "<redacted>" : p.raw
-          }))
-        }))
-      });
-      return;
-    }
-    if (resolved.issues.length > 0) {
-      emit("Issues:");
-      for (const i of resolved.issues) emit(`  ${i.file}:${i.line}: ${i.message}`);
-      emit("");
+// src/cli/commands/run.ts
+import path17 from "path";
+
+// src/supervisor/logs.ts
+import { createReadStream as createReadStream3 } from "fs";
+import fs10 from "fs/promises";
+import path14 from "path";
+async function tailFile(opts) {
+  if (!await pathExists(opts.file)) {
+    if (!opts.follow) return;
+    await waitForFile(opts.file, opts.signal);
+  }
+  let offset = await initialOffset(opts.file, opts.initialBytes ?? 16 * 1024);
+  await streamFrom(opts.file, offset, opts.out);
+  if (!opts.follow) return;
+  const stat = await fs10.stat(opts.file);
+  offset = stat.size;
+  const watcher = fs10.watch(opts.file, { persistent: true });
+  const abort = opts.signal ?? new AbortController().signal;
+  const pollTimer = setInterval(async () => {
+    try {
+      const cur = await fs10.stat(opts.file);
+      if (cur.size < offset) {
+        offset = 0;
+      }
+      if (cur.size > offset) {
+        await streamFrom(opts.file, offset, opts.out);
+        offset = cur.size;
+      }
+    } catch {
     }
-    emit(`Resolved environment for ${service} (mode=${mode}):`);
-    for (const [k, v] of resolved.values) {
-      const printed = v.secret ? "<redacted>" : v.value;
-      emit(`  ${k} = ${printed}`);
-      for (const p of v.provenance) {
-        const rawPrinted = v.secret ? "<redacted>" : p.raw;
-        emit(`    via ${p.layer} (${p.file}:${p.line}) = ${rawPrinted}`);
+  }, 500);
+  try {
+    for await (const _event of watcher) {
+      if (abort.aborted) break;
+      const cur = await fs10.stat(opts.file).catch(() => null);
+      if (!cur) continue;
+      if (cur.size < offset) {
+        offset = 0;
+      }
+      if (cur.size > offset) {
+        await streamFrom(opts.file, offset, opts.out);
+        offset = cur.size;
       }
     }
+  } catch (err) {
+    if (err.code === "ABORT_ERR") return;
+    throw err;
+  } finally {
+    clearInterval(pollTimer);
+  }
+}
+async function initialOffset(file, fromEndBytes) {
+  const st = await fs10.stat(file);
+  return Math.max(0, st.size - fromEndBytes);
+}
+async function streamFrom(file, start, out) {
+  return new Promise((resolve, reject) => {
+    const rs = createReadStream3(file, { start, encoding: "utf8" });
+    rs.on("data", (chunk) => out.write(chunk));
+    rs.on("end", () => resolve());
+    rs.on("error", (err) => reject(err));
   });
 }
+async function waitForFile(file, signal) {
+  const dir = path14.dirname(file);
+  await fs10.mkdir(dir, { recursive: true });
+  for (; ; ) {
+    if (signal?.aborted) return;
+    if (await pathExists(file)) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
 
 // src/supervisor/native.ts
 import fs12 from "fs/promises";
 import path16 from "path";
-import { execa as execa4 } from "execa";
+import { execa as execa5 } from "execa";
 
 // src/supervisor/state.ts
 import fs11 from "fs/promises";
@@ -2374,7 +2559,7 @@ async function startNativeService(opts) {
       stdio: ["ignore", fh.fd, fh.fd],
       reject: false
     };
-    child = execa4(shell, ["-c", cmd], spawnOpts);
+    child = execa5(shell, ["-c", cmd], spawnOpts);
   } catch (err) {
     await fh.close().catch(() => void 0);
     throw new RuntimeFailure(
@@ -2411,7 +2596,10 @@ async function stopNativeService(opts) {
     return { stopped: false };
   }
   if (!isPidAlive(state.pid)) {
-    opts.logger.info({ service: opts.service, pid: state.pid }, "down: process already gone; clearing state");
+    opts.logger.info(
+      { service: opts.service, pid: state.pid },
+      "down: process already gone; clearing state"
+    );
     await clearState(opts.paths, opts.service);
     return { stopped: true };
   }
@@ -2505,79 +2693,7 @@ async function listServicesState(paths) {
   return out;
 }
 
-// src/supervisor/logs.ts
-import fs13 from "fs/promises";
-import { createReadStream as createReadStream3 } from "fs";
-import path17 from "path";
-async function tailFile(opts) {
-  if (!await pathExists(opts.file)) {
-    if (!opts.follow) return;
-    await waitForFile(opts.file, opts.signal);
-  }
-  let offset = await initialOffset(opts.file, opts.initialBytes ?? 16 * 1024);
-  await streamFrom(opts.file, offset, opts.out);
-  if (!opts.follow) return;
-  let stat = await fs13.stat(opts.file);
-  offset = stat.size;
-  const watcher = fs13.watch(opts.file, { persistent: true });
-  const abort = opts.signal ?? new AbortController().signal;
-  const pollTimer = setInterval(async () => {
-    try {
-      const cur = await fs13.stat(opts.file);
-      if (cur.size < offset) {
-        offset = 0;
-      }
-      if (cur.size > offset) {
-        await streamFrom(opts.file, offset, opts.out);
-        offset = cur.size;
-      }
-    } catch {
-    }
-  }, 500);
-  try {
-    for await (const _event of watcher) {
-      if (abort.aborted) break;
-      const cur = await fs13.stat(opts.file).catch(() => null);
-      if (!cur) continue;
-      if (cur.size < offset) {
-        offset = 0;
-      }
-      if (cur.size > offset) {
-        await streamFrom(opts.file, offset, opts.out);
-        offset = cur.size;
-      }
-    }
-  } catch (err) {
-    if (err.code === "ABORT_ERR") return;
-    throw err;
-  } finally {
-    clearInterval(pollTimer);
-  }
-}
-async function initialOffset(file, fromEndBytes) {
-  const st = await fs13.stat(file);
-  return Math.max(0, st.size - fromEndBytes);
-}
-async function streamFrom(file, start, out) {
-  return new Promise((resolve, reject) => {
-    const rs = createReadStream3(file, { start, encoding: "utf8" });
-    rs.on("data", (chunk) => out.write(chunk));
-    rs.on("end", () => resolve());
-    rs.on("error", (err) => reject(err));
-  });
-}
-async function waitForFile(file, signal) {
-  const dir = path17.dirname(file);
-  await fs13.mkdir(dir, { recursive: true });
-  for (; ; ) {
-    if (signal?.aborted) return;
-    if (await pathExists(file)) return;
-    await new Promise((r) => setTimeout(r, 250));
-  }
-}
-
 // src/cli/commands/run.ts
-import path18 from "path";
 async function findService(name, jobs) {
   const ws = await resolveWorkspace();
   const projectDoc = await readProjectManifest(ws.projectManifestFile);
@@ -2601,7 +2717,7 @@ async function findService(name, jobs) {
     serviceDoc,
     service: entry.data,
     paths: ws.paths,
-    manifestDir: path18.dirname(entry.file)
+    manifestDir: path17.dirname(entry.file)
   };
 }
 function registerRunCommands(program) {
@@ -2654,7 +2770,7 @@ function registerRunCommands(program) {
     const root = inheritRootOptions(cmd);
     const jobs = resolveJobs(root.jobs);
     const ctx = await findService(name, jobs);
-    const logFile = path18.join(ctx.paths.logsDir, name, "service.log");
+    const logFile = path17.join(ctx.paths.logsDir, name, "service.log");
     const ac = new AbortController();
     process.on("SIGINT", () => ac.abort());
     process.on("SIGTERM", () => ac.abort());
@@ -2687,136 +2803,133 @@ function registerRunCommands(program) {
       s.uptimeSec !== null ? `${s.uptimeSec}s` : "-",
       s.logFile ?? "-"
     ]);
-    const widths = headers.map((h, i) => Math.max(h.length, ...data.map((row) => (row[i] ?? "").length)));
+    const widths = headers.map(
+      (h, i) => Math.max(h.length, ...data.map((row) => (row[i] ?? "").length))
+    );
     const fmt = (row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ");
     emit(fmt(headers));
     for (const row of data) emit(fmt(row));
   });
 }
 
-// src/cli/commands/doctor.ts
-import path19 from "path";
-import fs14 from "fs/promises";
-import { execa as execa5 } from "execa";
-async function runShell(cmd, cwd) {
-  try {
-    const res = await execa5("/bin/sh", ["-c", cmd], { cwd, reject: false });
-    return { ok: res.exitCode === 0, exitCode: res.exitCode ?? -1 };
-  } catch {
-    return { ok: false, exitCode: -1 };
-  }
-}
-function registerDoctor(program) {
-  program.command("doctor").description("Verify toolchain prerequisites, workspace paths, and per-service check_installed steps.").action(async (_opts, cmd) => {
+// src/cli/commands/validate.ts
+import fs13 from "fs/promises";
+import path18 from "path";
+import pMap4 from "p-map";
+function registerValidate(program) {
+  program.command("validate").description("Validate one or more qavor manifest files. Targets a file or a directory.").argument(
+    "<path>",
+    "Path to a qavor.yaml file, a directory containing one, or a directory of multiple manifests."
+  ).action(async (target, _opts, cmd) => {
     const root = inheritRootOptions(cmd);
     const logger = getLogger();
-    const checks = [];
-    try {
-      const res = await execa5("git", ["--version"]);
-      const version = res.stdout.trim().replace(/^git version /, "");
-      const [maj, min] = version.split(".").map((s) => Number.parseInt(s, 10));
-      if (Number.isFinite(maj) && Number.isFinite(min) && ((maj ?? 0) > 2 || (maj ?? 0) === 2 && (min ?? 0) >= 30)) {
-        checks.push({ name: "git \u2265 2.30", status: "ok", message: version });
+    const abs = path18.resolve(target);
+    const files = [];
+    if (await isFile(abs)) {
+      files.push(abs);
+    } else if (await isDirectory(abs)) {
+      const direct = path18.join(abs, "qavor.yaml");
+      if (await isFile(direct)) files.push(direct);
+      try {
+        const entries = await fs13.readdir(abs, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isDirectory()) {
+            const child = path18.join(abs, e.name, "qavor.yaml");
+            if (await isFile(child)) files.push(child);
+          }
+          if (e.isFile() && e.name === "qavor.yaml") {
+          }
+        }
+      } catch {
+      }
+    } else {
+      throw new UserError(`Path not found: ${abs}`);
+    }
+    if (files.length === 0) throw new UserError(`No qavor.yaml files found under ${abs}.`);
+    const jobs = resolveJobs(root.jobs);
+    const issues = [];
+    await pMap4(
+      files,
+      async (file) => {
+        try {
+          const docs = await loadManifestFile(file);
+          for (const d of docs) {
+            const r = validateDocument(d);
+            if (!r.ok) issues.push(...r.issues);
+          }
+        } catch (err) {
+          issues.push({
+            file,
+            line: 1,
+            column: 1,
+            kind: "unknown",
+            path: "",
+            message: err instanceof Error ? err.message : String(err)
+          });
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ ok: issues.length === 0, files: files.length, issues });
+    } else {
+      if (issues.length === 0) {
+        emit(`OK \u2014 ${files.length} file(s) validated.`);
       } else {
-        checks.push({ name: "git \u2265 2.30", status: "warn", message: `found ${version}` });
+        emit(`FAILED \u2014 ${issues.length} issue(s) across ${files.length} file(s):`);
+        for (const i of issues) emit(`  ${formatIssue(i)}`);
       }
-    } catch {
-      checks.push({ name: "git \u2265 2.30", status: "fail", message: "git not found", hint: "Install git." });
     }
+    if (issues.length > 0) {
+      logger.debug({ count: issues.length }, "validation failed");
+      throw new ManifestError(`Validation failed with ${issues.length} issue(s).`);
+    }
+  });
+}
+
+// src/cli/commands/workspace.ts
+import fs14 from "fs/promises";
+import path19 from "path";
+function registerWorkspace(program) {
+  const ws = program.command("workspace").description("Workspace operations.");
+  ws.command("info").description("Show information about the workspace at or above the cwd.").action(async (_opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const resolved = await resolveWorkspace();
+    const project = await readProjectManifest(resolved.projectManifestFile);
+    let meta = {};
     try {
-      await execa5("docker", ["--version"]);
-      checks.push({ name: "docker (optional v0)", status: "ok" });
+      meta = await readJsonFile(resolved.paths.workspaceMetaFile);
     } catch {
-      checks.push({ name: "docker (optional v0)", status: "warn", message: "docker not detected" });
     }
-    try {
-      const ws = await resolveWorkspace();
-      await ensureDir(ws.paths.stateRoot);
-      const probe = path19.join(ws.paths.stateRoot, ".doctor-write-check");
-      await fs14.writeFile(probe, "");
-      await fs14.unlink(probe);
-      checks.push({ name: "workspace .qavor/ writable", status: "ok", message: ws.paths.stateRoot });
-    } catch (err) {
-      checks.push({
-        name: "workspace .qavor/ writable",
-        status: "fail",
-        message: err instanceof Error ? err.message : String(err)
-      });
+    const info = {
+      workspace_root: resolved.paths.root,
+      workspaces_file: resolved.paths.workspacesFile,
+      project_repo_path: resolved.projectRepoPath,
+      project_manifest_file: resolved.projectManifestFile,
+      project_name: typeof project.data.name === "string" ? project.data.name : null,
+      state_dir: resolved.paths.stateRoot,
+      meta
+    };
+    if (root.json) {
+      emitJson(info);
+      return;
     }
-    const cache = globalCacheDir();
-    try {
-      await ensureDir(cache);
-      const probe = path19.join(cache, ".doctor-write-check");
-      await fs14.writeFile(probe, "");
-      await fs14.unlink(probe);
-      checks.push({ name: "global cache writable", status: "ok", message: cache });
-    } catch (err) {
-      checks.push({
-        name: "global cache writable",
-        status: "fail",
-        message: err instanceof Error ? err.message : String(err)
-      });
+    emit(`Workspace root:        ${info.workspace_root}`);
+    emit(`Workspaces manifest:   ${path19.relative(info.workspace_root, info.workspaces_file)}`);
+    emit(`Project repo path:     ${path19.relative(info.workspace_root, info.project_repo_path)}`);
+    emit(
+      `Project manifest:      ${path19.relative(info.workspace_root, info.project_manifest_file)}`
+    );
+    emit(`Project name:          ${info.project_name ?? "<unknown>"}`);
+    emit(`State directory:       ${path19.relative(info.workspace_root, info.state_dir)}`);
+    if (Object.keys(meta).length > 0) {
+      emit("Workspace meta:");
+      for (const [k, v] of Object.entries(meta))
+        emit(`  ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
     }
     try {
-      const ws = await resolveWorkspace();
-      const project = await readProjectManifest(ws.projectManifestFile);
-      const repos = resolveRepos({
-        workspaceRoot: ws.paths.root,
-        project: project.data,
-        projectRepoPath: ws.projectRepoPath
-      });
-      const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
-      repoMap.set("__project__", ws.projectRepoPath);
-      const registry = await buildWorkspaceRegistry({
-        workspaceRoot: ws.paths.root,
-        repos: repoMap,
-        concurrency: resolveJobs(root.jobs)
-      });
-      for (const entry of registry.entries) {
-        if (entry.kind !== "service") continue;
-        const svc = entry.data;
-        const checkCmd = svc.runtime?.native?.check_installed?.cmd;
-        if (!checkCmd) {
-          checks.push({
-            name: `service ${entry.name}: check_installed`,
-            status: "warn",
-            message: "no runtime.native.check_installed.cmd"
-          });
-          continue;
-        }
-        const docs = await loadManifestFile(entry.file);
-        const serviceDoc = docs[entry.docIndex];
-        const cwd = svc.runtime?.native?.check_installed?.cwd ? path19.resolve(path19.dirname(serviceDoc.file), svc.runtime.native.check_installed.cwd) : path19.dirname(serviceDoc.file);
-        const res = await runShell(checkCmd, cwd);
-        if (res.ok) {
-          checks.push({ name: `service ${entry.name}: check_installed`, status: "ok" });
-        } else {
-          const installHint = svc.runtime?.native?.install?.cmd;
-          const failCheck = {
-            name: `service ${entry.name}: check_installed`,
-            status: "fail",
-            message: `exit ${res.exitCode}`
-          };
-          if (installHint) failCheck.hint = `Hint: \`${installHint}\``;
-          checks.push(failCheck);
-        }
-      }
-    } catch (err) {
-      logger.debug({ err: err instanceof Error ? err.message : String(err) }, "doctor: workspace probe failed");
-    }
-    if (root.json) {
-      emitJson({ checks, ok: checks.every((c) => c.status !== "fail") });
-    } else {
-      for (const c of checks) {
-        const sym = c.status === "ok" ? "\u2713" : c.status === "warn" ? "!" : "\u2717";
-        let line = `${sym} ${c.status.toUpperCase().padEnd(5)} ${c.name}`;
-        if (c.message) line += ` \u2014 ${c.message}`;
-        emit(line);
-        if (c.hint) emit(`     ${c.hint}`);
-      }
-    }
-    if (checks.some((c) => c.status === "fail")) {
-      throw new RuntimeFailure("doctor: one or more checks failed.");
+      await fs14.access(resolved.paths.workspaceMetaFile);
+    } catch {
     }
   });
 }
@@ -2825,7 +2938,9 @@ function registerDoctor(program) {
 var PKG_VERSION = "0.1.0";
 function buildProgram() {
   const program = new Command();
-  program.name("qavor").description("A CLI for managing a constellation of related repositories as one cohesive developer workspace.").version(PKG_VERSION, "-V, --version").option("--json", "Emit machine-readable JSON output. One object per line on stdout.").option("-v, --verbose", "Enable debug-level logging on stderr.").option("-c, --config <path>", "Override the path to the workspace pointer file.").option("-j, --jobs <n>", "Maximum concurrency for fan-out operations.", (raw) => {
+  program.name("qavor").description(
+    "A CLI for managing a constellation of related repositories as one cohesive developer workspace."
+  ).version(PKG_VERSION, "-V, --version").option("--json", "Emit machine-readable JSON output. One object per line on stdout.").option("-v, --verbose", "Enable debug-level logging on stderr.").option("-c, --config <path>", "Override the path to the workspace pointer file.").option("-j, --jobs <n>", "Maximum concurrency for fan-out operations.", (raw) => {
     const n = Number.parseInt(raw, 10);
     if (!Number.isFinite(n) || n < 1) {
       throw new Error(`--jobs must be a positive integer (got '${raw}').`);
@@ -2856,7 +2971,8 @@ async function main(argv) {
 }
 function handleError(err) {
   const e = err;
-  if (e && (e.code === "commander.helpDisplayed" || e.code === "commander.help")) return ExitCode.Ok;
+  if (e && (e.code === "commander.helpDisplayed" || e.code === "commander.help"))
+    return ExitCode.Ok;
   if (e && e.code === "commander.version") return ExitCode.Ok;
   if (e && typeof e.code === "string" && e.code.startsWith("commander.")) {
     process2.stderr.write(`${e.message ?? "command error"}