@eigenpal/cli 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -467,6 +467,7 @@ actual) { ... }` declaration around your statements. Parameter order is
 
 - 71361fd: `workflow get-experiment-status --watch` now prints a per-example failure summary on stderr when the batch finishes with any failed/cancelled execution: example name, top-level error (truncated), and the exact `eigenpal execution get <exec-id>` command to drill into step-by-step detail. Removes the need for the agent to grep through a 1000-line JSON dump to find which example broke and why. `reference/debugging.md` documents the discovery path.
 - 71361fd: `eigenpal workflow get-experiment-status --watch` now polls until every execution in the batch reaches a terminal state (`completed` / `failed` / `cancelled`), then exits non-zero if any execution failed or was cancelled. Removes the need for agent-side polling loops that didn't notice all-terminal-already and kept ticking. Renders a one-line `N/M terminal (counts)` progress summary on stderr (in-place rewrite when stderr is a TTY), dumps the full JSON on stdout when done. `--interval <s>` and `--max-wait <s>` are configurable; defaults are 5s/30min.
+- 04e4018: Harden hidden Git materialization commands for package-ref installs, frozen lockfile replay, dependency materialization, and source authoring smoke flows.
 - 71361fd: `install-skill`: multi-tool support via interactive multiselect.
   - Opens a `@clack/prompts` multiselect picker over supported agent tools
     (Claude Code, Cursor). Toggle on to install, toggle off to uninstall —

package/dist/cli.js

@@ -181601,7 +181601,7 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.5.5",
+  version: "0.5.7",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",
@@ -184102,7 +184102,20 @@ init_src();
 init_zod();
 var import_yaml2 = __toESM(require_dist(), 1);
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync3, realpathSync, statSync } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  mkdtempSync,
+  readdirSync,
+  readFileSync as readFileSync3,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import path2 from "node:path";
 var SourceRepositorySchema = exports_external.object({
   gitRepositoryPath: exports_external.string(),
@@ -184122,12 +184135,28 @@ var ReleasesSchema = exports_external.object({
   packagePath: exports_external.string(),
   releases: exports_external.array(ReleaseSchema)
 });
+var CommitShaSchema = exports_external.string().regex(/^[0-9a-f]{40}$/);
+var InstallLockPackageSchema = exports_external.lazy(() => exports_external.object({
+  packagePath: SourcePackagePathSchema,
+  requestedRef: SourceVersionRefSchema,
+  resolvedRef: exports_external.string().min(1),
+  resolvedTag: exports_external.string().min(1).optional(),
+  commit: CommitShaSchema,
+  dependencies: exports_external.array(InstallLockPackageSchema)
+}));
+var InstallLockfileSchema = exports_external.object({
+  lockfileVersion: exports_external.literal(1),
+  eigenpalVersion: exports_external.string().min(1),
+  inputHash: exports_external.string().min(1),
+  root: InstallLockPackageSchema
+});
 var AuthCheckSchema = exports_external.object({
   ok: exports_external.literal(true),
   email: exports_external.string().email().nullable().optional(),
   name: exports_external.string().nullable().optional(),
   keyId: exports_external.string()
 });
+var INSTALL_LOCKFILE_NAME = "eigenpal.lock";
 function runGit(args, opts = {}) {
   const env2 = opts.config ? gitAuthEnv(opts.config, opts.env, opts.gitRemoteUrl) : { ...getProcessEnv(), ...opts.env };
   const result = spawnSync2("git", args, {
@@ -184187,6 +184216,11 @@ function sourcePathFromPackageRoot(gitRoot, packageRoot) {
 function resolveGitRoot(dir) {
   return gitOutput(["rev-parse", "--show-toplevel"], dir);
 }
+function isOrganizationSourceGitRoot(gitRoot) {
+  if (!gitRoot)
+    return false;
+  return Boolean(gitOutput(["remote", "get-url", "origin"], gitRoot)?.match(/\/orgs\/[^/]+\.git$/));
+}
 function findNearestPackageRoot(startDir, gitRoot) {
   let current = path2.resolve(startDir);
   while (true) {
@@ -184238,6 +184272,250 @@ function releaseTagExists(gitRoot, packagePath, version2) {
   const tag = formatReleaseTag(pathToDottedPackageName(packagePath), version2);
   return gitOutput(["tag", "--list", tag], gitRoot) === tag;
 }
+function readPackageManifest(packageRoot) {
+  return SourcePackageManifestSchema.parse(readYamlFile(path2.join(packageRoot, "eigenpal.yaml")));
+}
+function parsePackageRef(input) {
+  const [rawPackage, rawRef, extra] = input.split("@");
+  if (!rawPackage || extra !== undefined) {
+    throw new Error("Package ref must be <package>[@latest|main|version|range|commit].");
+  }
+  const packagePath = resolvePackagePath(rawPackage);
+  const ref = SourceVersionRefSchema.parse(rawRef || "latest");
+  return { packagePath, ref };
+}
+function versionMatchesRange(version2, range) {
+  const parts = semverParts(version2);
+  if (!parts)
+    return false;
+  const rangeParts = range.replace("*", "x").split(".");
+  if (String(parts[0]) !== rangeParts[0])
+    return false;
+  if (rangeParts.length === 2)
+    return rangeParts[1] === "x";
+  if (rangeParts.length !== 3)
+    return false;
+  if (rangeParts[1] === "x")
+    return true;
+  return String(parts[1]) === rangeParts[1];
+}
+function listLocalPackageReleases(gitRoot, packagePath) {
+  const tagPrefix = `${pathToDottedPackageName(packagePath)}@`;
+  const output = gitOutput(["tag", "--list", `${tagPrefix}*`], gitRoot) ?? "";
+  return output.split(`
+`).map((tag) => tag.trim()).filter(Boolean).map((tag) => {
+    const parsed = parseReleaseTag(tag);
+    const commit = gitOutput(["rev-list", "-n", "1", tag], gitRoot) ?? "";
+    return { tag, version: parsed.version, commit };
+  }).sort((left, right) => compareSemverDesc(left.version, right.version));
+}
+async function listPackageReleases(input) {
+  if (input.gitRoot) {
+    const local = listLocalPackageReleases(input.gitRoot, input.packagePath);
+    if (local.length > 0)
+      return local;
+  }
+  const client = new ApiClient(input.config);
+  return ReleasesSchema.parse(await client.get("/api/v1/source/releases", { packagePath: input.packagePath })).releases;
+}
+function hostedArchiveRequest(input) {
+  const match = input.repository.remoteUrl.match(/^(.*)\/orgs\/([^/]+)\.git$/);
+  if (!match)
+    return null;
+  const [, baseUrl, gitRepositoryPath] = match;
+  return `${baseUrl}/export/orgs/${encodeURIComponent(gitRepositoryPath)}/${encodeURIComponent(input.ref)}/${input.packagePath}`;
+}
+async function resolvePackageRef(input) {
+  if (input.ref === "main" || /^[0-9a-f]{40}$/.test(input.ref)) {
+    if (!input.gitRoot) {
+      throw new Error(`Source ref ${input.ref} requires a cloned organization source repository.`);
+    }
+    const commit = gitOutput(["rev-parse", input.ref], input.gitRoot);
+    if (!commit)
+      throw new Error(`Source ref ${input.ref} does not exist.`);
+    return { requestedRef: input.ref, resolvedRef: input.ref, commit };
+  }
+  const releases = await listPackageReleases({
+    config: input.config,
+    gitRoot: input.gitRoot,
+    packagePath: input.packagePath
+  });
+  const release = input.ref === "latest" ? sortReleasesNewestFirst(releases)[0] : /^\d+\.\d+\.\d+$/.test(input.ref) ? releases.find((candidate) => candidate.version === input.ref) : sortReleasesNewestFirst(releases).find((candidate) => versionMatchesRange(candidate.version, input.ref));
+  if (!release) {
+    throw new Error(`No release found for ${input.packagePath}@${input.ref}.`);
+  }
+  return {
+    requestedRef: input.ref,
+    resolvedRef: release.version,
+    resolvedTag: release.tag,
+    commit: release.commit || (input.gitRoot ? gitOutput(["rev-list", "-n", "1", release.tag], input.gitRoot) ?? "" : "")
+  };
+}
+function archivePackage(input) {
+  rmSync(input.outDir, { recursive: true, force: true });
+  mkdirSync2(input.outDir, { recursive: true });
+  const tarPath = path2.join(mkdtempSyncCompat("eigenpal-source-archive-"), "package.tar");
+  try {
+    runGit(["archive", "--format=tar", `--output=${tarPath}`, input.ref, input.packagePath], {
+      cwd: input.gitRoot
+    });
+    const extract2 = spawnSync2("tar", ["-xf", tarPath, "--strip-components", String(input.packagePath.split("/").length)], {
+      cwd: input.outDir,
+      encoding: "utf8"
+    });
+    if (extract2.status !== 0)
+      throw new Error(extract2.stderr.trim() || "tar extraction failed");
+  } finally {
+    rmSync(path2.dirname(tarPath), { recursive: true, force: true });
+  }
+}
+async function tryHostedArchive(input) {
+  const repository = input.repository ?? (input.gitRoot ? {
+    gitRepositoryPath: "",
+    remoteUrl: gitOutput(["remote", "get-url", "origin"], input.gitRoot) ?? ""
+  } : null);
+  if (!repository)
+    return false;
+  const url2 = hostedArchiveRequest({
+    repository,
+    ref: input.ref,
+    packagePath: input.packagePath
+  });
+  if (!url2)
+    return false;
+  const response = await fetch(url2, {
+    headers: { authorization: `Bearer ${requireApiKey(input.config)}` }
+  }).catch(() => null);
+  if (!response?.ok)
+    return false;
+  rmSync(input.outDir, { recursive: true, force: true });
+  mkdirSync2(input.outDir, { recursive: true });
+  const tarPath = path2.join(mkdtempSyncCompat("eigenpal-hosted-source-"), "package.tar");
+  try {
+    writeFileSync2(tarPath, Buffer.from(await response.arrayBuffer()));
+    const extract2 = spawnSync2("tar", ["-xf", tarPath, "--strip-components", String(input.packagePath.split("/").length)], {
+      cwd: input.outDir,
+      encoding: "utf8"
+    });
+    if (extract2.status !== 0)
+      throw new Error(extract2.stderr.trim() || "tar extraction failed");
+    return true;
+  } finally {
+    rmSync(path2.dirname(tarPath), { recursive: true, force: true });
+  }
+}
+function mkdtempSyncCompat(prefix) {
+  return mkdtempSync(path2.join(tmpdir(), prefix));
+}
+function dependencyInstallPath(parentRoot, packagePath) {
+  const modulesRoot = path2.resolve(parentRoot, "eigenpal_modules");
+  const destination = path2.resolve(modulesRoot, packagePath);
+  if (destination !== modulesRoot && !destination.startsWith(`${modulesRoot}${path2.sep}`)) {
+    throw new Error(`Dependency path escapes eigenpal_modules: ${packagePath}`);
+  }
+  return destination;
+}
+function lockfileInputHash(input) {
+  return createHash2("sha256").update(JSON.stringify(input)).digest("hex");
+}
+async function resolvePackageGraph(input) {
+  const seen = input.seen ?? [];
+  const key = `${input.packagePath}@${input.ref}`;
+  if (seen.includes(key)) {
+    throw new Error(`Dependency cycle detected: ${[...seen, key].join(" -> ")}`);
+  }
+  const resolved = await resolvePackageRef(input);
+  const tempDir = await mkdtemp(path2.join(tmpdir(), "eigenpal-install-resolve-"));
+  try {
+    const packageRoot = path2.join(tempDir, "package");
+    const ref = resolved.resolvedTag ?? resolved.resolvedRef;
+    if (input.gitRoot) {
+      archivePackage({
+        gitRoot: input.gitRoot,
+        ref,
+        packagePath: input.packagePath,
+        outDir: packageRoot
+      });
+    } else if (!await tryHostedArchive({
+      config: input.config,
+      repository: input.repository,
+      ref,
+      packagePath: input.packagePath,
+      outDir: packageRoot
+    })) {
+      throw new Error(`Hosted source export unavailable for ${input.packagePath}@${ref}.`);
+    }
+    const manifest = readPackageManifest(packageRoot);
+    const dependencies = "dependencies" in manifest ? Object.entries(manifest.dependencies ?? {}) : [];
+    return {
+      packagePath: input.packagePath,
+      requestedRef: input.ref,
+      resolvedRef: resolved.resolvedRef,
+      ...resolved.resolvedTag ? { resolvedTag: resolved.resolvedTag } : {},
+      commit: resolved.commit,
+      dependencies: await Promise.all(dependencies.map(([dependencyName, version2]) => resolvePackageGraph({
+        config: input.config,
+        gitRoot: input.gitRoot,
+        repository: input.repository,
+        packagePath: workspaceDependencyNameToPackagePath(dependencyName),
+        ref: SourceVersionRefSchema.parse(version2),
+        seen: [...seen, key]
+      })))
+    };
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+async function materializeLockPackage(input) {
+  const ref = input.lockPackage.resolvedTag ?? input.lockPackage.commit;
+  const usedHostedArchive = await tryHostedArchive({
+    config: input.config,
+    gitRoot: input.gitRoot,
+    repository: input.repository,
+    ref,
+    packagePath: input.lockPackage.packagePath,
+    outDir: input.outDir
+  });
+  if (!usedHostedArchive) {
+    if (!input.gitRoot) {
+      throw new Error(`Hosted source export unavailable for ${input.lockPackage.packagePath}@${ref}.`);
+    }
+    warn(`Hosted source export unavailable for ${input.lockPackage.packagePath}; using local git archive.`);
+    archivePackage({
+      gitRoot: input.gitRoot,
+      ref,
+      packagePath: input.lockPackage.packagePath,
+      outDir: input.outDir
+    });
+  }
+  const occupied = new Set;
+  for (const dependency of input.lockPackage.dependencies) {
+    const dependencyPath = dependencyInstallPath(input.outDir, dependency.packagePath);
+    if (occupied.has(dependencyPath)) {
+      throw new Error(`Dependency conflict at ${dependencyPath}`);
+    }
+    occupied.add(dependencyPath);
+    await materializeLockPackage({
+      config: input.config,
+      gitRoot: input.gitRoot,
+      repository: input.repository,
+      lockPackage: dependency,
+      outDir: dependencyPath
+    });
+  }
+}
+function writeLockfile(lockfilePath, lockfile) {
+  mkdirSync2(path2.dirname(lockfilePath), { recursive: true });
+  writeFileSync2(lockfilePath, `${JSON.stringify(lockfile, null, 2)}
+`);
+}
+function readLockfile(lockfilePath) {
+  const parsed = InstallLockfileSchema.safeParse(JSON.parse(readFileSync3(lockfilePath, "utf8")));
+  if (!parsed.success) {
+    throw new Error(`Invalid lockfile ${lockfilePath}: ${parsed.error.issues.map((issue2) => `${issue2.path.join(".")}: ${issue2.message}`).join("; ")}`);
+  }
+  return parsed.data;
+}
 function validatePackageReferences(input) {
   const errors3 = [];
   const dependencies = "dependencies" in input.manifest ? Object.entries(input.manifest.dependencies ?? {}) : [];
@@ -184440,7 +184718,12 @@ function gitCommandCreatesObjects(args) {
     "revert",
     "tag"
   ]);
-  return args.some((arg) => objectCreatingCommands.has(arg));
+  const command = gitSubcommandFromArgs(args);
+  if (!command)
+    return false;
+  if (command === "tag" && args.some((arg) => arg === "-l" || arg === "--list"))
+    return false;
+  return objectCreatingCommands.has(command);
 }
 function gitCwdFromArgs(args) {
   let cwd = process.cwd();
@@ -184452,6 +184735,25 @@ function gitCwdFromArgs(args) {
   }
   return cwd;
 }
+function gitSubcommandFromArgs(args) {
+  const optionsWithValue = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace"]);
+  for (let i = 0;i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--")
+      continue;
+    if (optionsWithValue.has(arg)) {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--git-dir=") || arg.startsWith("--work-tree=") || arg.startsWith("--namespace=")) {
+      continue;
+    }
+    if (arg.startsWith("-"))
+      continue;
+    return arg;
+  }
+  return null;
+}
 async function runGitPassthroughFromArgv(argv) {
   const gitIndex = argv.indexOf("git");
   const separatorIndex = argv.indexOf("--", gitIndex + 1);
@@ -184534,7 +184836,7 @@ function doctor(opts) {
       });
     }
   }
-  if (context.packageRoot) {
+  if (context.packageRoot && context.packageRoot !== context.gitRoot) {
     const result = validatePackage(context.packageRoot);
     checks3.push({
       check: "package structure",
@@ -184763,15 +185065,312 @@ async function release(versionOrBump, dir, opts) {
 }
 async function sync(target, opts) {
   const context = resolveGitSourceContext({ dir: opts.dir });
+  if (target?.includes("@")) {
+    throw new Error("Sync always uses latest; do not pass a versioned target.");
+  }
   const packagePath = target ? resolvePackagePath(target) : context.packagePath;
   if (!packagePath) {
     throw new Error("Pass an automation target or run sync inside a source package.");
   }
-  if (target?.includes("@")) {
-    throw new Error("Sync always uses latest; do not pass a versioned target.");
-  }
   await syncLatestAutomation(new ApiClient(resolveConfig(opts)), packagePath);
 }
+async function install(packageRef, opts) {
+  const config2 = resolveConfig(opts);
+  const context = resolveGitSourceContext();
+  const sourceGitRoot = isOrganizationSourceGitRoot(context.gitRoot) ? context.gitRoot : null;
+  if (sourceGitRoot)
+    checkRepoVersion(sourceGitRoot, false);
+  const installFromLock = async (lockfilePath, packageDestination, explicitRef, repository, expectedPackagePath, explicitGitRoot) => {
+    const lockfile2 = readLockfile(lockfilePath);
+    if (expectedPackagePath && lockfile2.root.packagePath !== expectedPackagePath) {
+      throw new Error(`Lockfile root package ${lockfile2.root.packagePath} does not match requested package ${expectedPackagePath}.`);
+    }
+    const destination = explicitRef ? path2.resolve(opts.out ?? path2.basename(lockfile2.root.packagePath)) : packageDestination;
+    if (!destination)
+      throw new Error("No package context found for lockfile install.");
+    const lockInstallGitRoot = explicitRef ? explicitGitRoot ?? sourceGitRoot : context.gitRoot;
+    if (explicitRef) {
+      await materializeLockPackage({
+        config: config2,
+        gitRoot: lockInstallGitRoot,
+        repository,
+        lockPackage: lockfile2.root,
+        outDir: destination
+      });
+      writeLockfile(path2.join(destination, ".eigenpal", INSTALL_LOCKFILE_NAME), lockfile2);
+    } else {
+      rmSync(path2.join(destination, "eigenpal_modules"), { recursive: true, force: true });
+      for (const dependency of lockfile2.root.dependencies) {
+        await materializeLockPackage({
+          config: config2,
+          gitRoot: lockInstallGitRoot,
+          repository,
+          lockPackage: dependency,
+          outDir: dependencyInstallPath(destination, dependency.packagePath)
+        });
+      }
+    }
+    success2(`Installed from lockfile ${lockfilePath}.`);
+  };
+  if (opts.frozenLockfile) {
+    const explicitRef = Boolean(packageRef);
+    const expectedPackagePath = packageRef ? parsePackageRef(packageRef).packagePath : null;
+    const explicitGitRoot = explicitRef && expectedPackagePath && context.gitRoot ? packageManifestExists(context.gitRoot, expectedPackagePath) ? context.gitRoot : sourceGitRoot : sourceGitRoot;
+    const repository = explicitRef && !explicitGitRoot ? await getSourceRepository(config2) : null;
+    const lockfilePath = opts.lockfile ?? path2.join(packageRef && opts.out ? path2.resolve(opts.out) : context.packageRoot ?? process.cwd(), ".eigenpal", INSTALL_LOCKFILE_NAME);
+    await installFromLock(lockfilePath, context.packageRoot, explicitRef, repository, expectedPackagePath, explicitGitRoot);
+    return;
+  }
+  if (packageRef) {
+    const parsed = parsePackageRef(packageRef);
+    const explicitGitRoot = context.gitRoot && packageManifestExists(context.gitRoot, parsed.packagePath) ? context.gitRoot : sourceGitRoot;
+    const repository = explicitGitRoot ? null : await getSourceRepository(config2);
+    if (parsed.ref === "main")
+      warn("Installing @main uses draft source and is not reproducible.");
+    const intendedLockfile2 = opts.lockfile ?? path2.join(path2.resolve(opts.out ?? path2.basename(parsed.packagePath)), ".eigenpal", INSTALL_LOCKFILE_NAME);
+    const inputHash2 = lockfileInputHash({ packageRef });
+    if (existsSync3(intendedLockfile2)) {
+      const existing = readLockfile(intendedLockfile2);
+      if (existing.inputHash !== inputHash2) {
+        throw new Error(`Existing lockfile ${intendedLockfile2} does not match requested package ref.`);
+      }
+      await installFromLock(intendedLockfile2, null, true, repository, parsed.packagePath);
+      return;
+    }
+    const lockRoot = await resolvePackageGraph({
+      config: config2,
+      gitRoot: explicitGitRoot,
+      repository,
+      packagePath: parsed.packagePath,
+      ref: parsed.ref
+    });
+    const outDir = path2.resolve(opts.out ?? path2.basename(parsed.packagePath));
+    await materializeLockPackage({
+      config: config2,
+      gitRoot: explicitGitRoot,
+      repository,
+      lockPackage: lockRoot,
+      outDir
+    });
+    const lockfile2 = {
+      lockfileVersion: 1,
+      eigenpalVersion: "1.0.0",
+      inputHash: inputHash2,
+      root: lockRoot
+    };
+    writeLockfile(intendedLockfile2, lockfile2);
+    success2(`Installed ${parsed.packagePath}@${lockRoot.resolvedRef} into ${outDir}.`);
+    return;
+  }
+  if (!context.packageRoot || !context.packagePath) {
+    throw new Error("Run git install inside a source package or pass a package ref.");
+  }
+  if (!context.gitRoot) {
+    throw new Error("Run git install inside an organization source repository.");
+  }
+  const manifest = readPackageManifest(context.packageRoot);
+  const dependencies = "dependencies" in manifest ? Object.entries(manifest.dependencies ?? {}) : [];
+  const inputHash = lockfileInputHash({ packagePath: context.packagePath, dependencies });
+  const intendedLockfile = opts.lockfile ?? path2.join(context.packageRoot, ".eigenpal", INSTALL_LOCKFILE_NAME);
+  if (existsSync3(intendedLockfile)) {
+    const existing = readLockfile(intendedLockfile);
+    if (existing.inputHash !== inputHash) {
+      throw new Error(`Existing lockfile ${intendedLockfile} does not match current package inputs.`);
+    }
+    await installFromLock(intendedLockfile, context.packageRoot, false);
+    return;
+  }
+  const root = {
+    packagePath: context.packagePath,
+    requestedRef: "main",
+    resolvedRef: "main",
+    commit: gitOutput(["rev-parse", "HEAD"], context.gitRoot) ?? "",
+    dependencies: await Promise.all(dependencies.map(([dependencyName, version2]) => resolvePackageGraph({
+      config: config2,
+      gitRoot: context.gitRoot,
+      packagePath: workspaceDependencyNameToPackagePath(dependencyName),
+      ref: SourceVersionRefSchema.parse(version2)
+    })))
+  };
+  rmSync(path2.join(context.packageRoot, "eigenpal_modules"), { recursive: true, force: true });
+  for (const dependency of root.dependencies) {
+    await materializeLockPackage({
+      config: config2,
+      gitRoot: context.gitRoot,
+      lockPackage: dependency,
+      outDir: dependencyInstallPath(context.packageRoot, dependency.packagePath)
+    });
+  }
+  const lockfile = {
+    lockfileVersion: 1,
+    eigenpalVersion: "1.0.0",
+    inputHash,
+    root
+  };
+  writeLockfile(intendedLockfile, lockfile);
+  success2(`Installed ${root.dependencies.length} dependencies for ${context.packagePath}.`);
+}
+function slugifyPackageSegment(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function packagePathForTemplate(template2, name) {
+  const slug = slugifyPackageSegment(name);
+  if (!slug)
+    throw new Error("Package name must include at least one letter or number.");
+  const rootByTemplate = {
+    agent: "agents",
+    workflow: "workflows",
+    skill: "resources/skills",
+    rule: "resources/rules",
+    knowledge: "resources/knowledge",
+    evaluator: "evaluators"
+  };
+  const root = rootByTemplate[template2];
+  if (!root)
+    throw new Error("Template must be agent, workflow, skill, rule, knowledge, or evaluator.");
+  return SourcePackagePathSchema.parse(`${root}/${slug}`);
+}
+function writePackageScaffold(packageRoot, packagePath, name) {
+  const [root, resourceKind] = packagePath.split("/");
+  mkdirSync2(packageRoot, { recursive: true });
+  const title = name.trim();
+  writeFileSync2(path2.join(packageRoot, "eigenpal.yaml"), import_yaml2.default.stringify({ schemaVersion: 1, name: title || path2.basename(packagePath) }));
+  if (root === "agents")
+    writeFileSync2(path2.join(packageRoot, "AGENT.md"), `# ${title}
+
+`);
+  if (root === "evaluators") {
+    writeFileSync2(path2.join(packageRoot, "evaluator.yaml"), import_yaml2.default.stringify({ schemaVersion: 1, type: "exact-diff", config: {} }));
+  }
+  if (root === "resources" && resourceKind === "skills") {
+    writeFileSync2(path2.join(packageRoot, "SKILL.md"), `# ${title}
+
+`);
+  }
+  if (root === "resources" && (resourceKind === "rules" || resourceKind === "knowledge")) {
+    writeFileSync2(path2.join(packageRoot, "README.md"), `# ${title}
+
+`);
+  }
+}
+function initPackage(name, opts) {
+  const startDir = path2.resolve(opts.dir ?? process.cwd());
+  const gitRoot = resolveGitRoot(startDir) ?? startDir;
+  mkdirSync2(gitRoot, { recursive: true });
+  if (!existsSync3(path2.join(gitRoot, ".git")))
+    runGit(["init", "-b", "main", gitRoot]);
+  if (!existsSync3(path2.join(gitRoot, "eigenpal.yaml"))) {
+    writeFileSync2(path2.join(gitRoot, "eigenpal.yaml"), `schemaVersion: 1
+eigenpalVersion: 1.0.0
+`);
+  }
+  const gitignorePath = path2.join(gitRoot, ".gitignore");
+  const gitignore = existsSync3(gitignorePath) ? readFileSync3(gitignorePath, "utf8") : "";
+  const additions = [".eigenpal/", "eigenpal_modules/"].filter((entry) => !gitignore.includes(entry));
+  if (additions.length > 0)
+    writeFileSync2(gitignorePath, `${gitignore}${gitignore.endsWith(`
+`) || !gitignore ? "" : `
+`}${additions.join(`
+`)}
+`);
+  const packagePath = packagePathForTemplate(opts.template, name);
+  const packageRoot = path2.join(gitRoot, packagePath);
+  if (existsSync3(packageRoot))
+    throw new Error(`Package already exists: ${packagePath}`);
+  writePackageScaffold(packageRoot, packagePath, name);
+  success2(`Created ${packagePath}.`);
+}
+async function pullSource(opts) {
+  const config2 = resolveConfig(opts);
+  const context = resolveGitSourceContext({ dir: opts.dir });
+  if (!context.gitRoot)
+    throw new Error("Not inside a Git repository.");
+  const remoteUrl = gitOutput(["remote", "get-url", "origin"], context.gitRoot);
+  runGit(["pull", "--ff-only", "origin", "main"], {
+    cwd: context.gitRoot,
+    config: config2,
+    gitRemoteUrl: remoteUrl ?? undefined
+  });
+}
+function dirtyPackagePaths(gitRoot) {
+  const status = gitOutput(["status", "--porcelain", "--untracked-files=all"], gitRoot) ?? "";
+  const packagePaths = new Set;
+  for (const line of status.split(`
+`)) {
+    const file2 = line.slice(2).trim().split(" -> ").pop().replace(/\\/g, "/");
+    const parts = file2.split("/");
+    for (let index = parts.length;index >= 2; index -= 1) {
+      const candidate = parts.slice(0, index).join("/");
+      if (SourcePackagePathSchema.safeParse(candidate).success && existsSync3(path2.join(gitRoot, candidate, "eigenpal.yaml"))) {
+        packagePaths.add(candidate);
+        break;
+      }
+    }
+  }
+  return [...packagePaths].sort();
+}
+async function commitSource(opts) {
+  if (!opts.message)
+    throw new Error("Commit requires -m <message>.");
+  const config2 = resolveConfig(opts);
+  const context = resolveGitSourceContext({ dir: opts.dir });
+  if (!context.gitRoot)
+    throw new Error("Not inside a Git repository.");
+  checkRepoVersion(context.gitRoot, true);
+  const packagePaths = dirtyPackagePaths(context.gitRoot);
+  if (packagePaths.length === 0) {
+    warn("No source package changes to commit.");
+    return;
+  }
+  for (const packagePath of packagePaths) {
+    const validation = validatePackage(path2.join(context.gitRoot, packagePath));
+    if (!validation.valid) {
+      throw new Error(`Package validation failed for ${packagePath}: ${validation.errors.join("; ")}`);
+    }
+  }
+  const rootFiles = ["eigenpal.yaml", ".gitignore"].filter((file2) => existsSync3(path2.join(context.gitRoot, file2)));
+  runGit(["add", ...rootFiles, ...packagePaths], { cwd: context.gitRoot });
+  const authorEnv = await resolveGitAuthorEnv(config2);
+  runGit(["commit", "-m", opts.message], { cwd: context.gitRoot, env: authorEnv });
+}
+async function pushSource(opts) {
+  const config2 = resolveConfig(opts);
+  const context = resolveGitSourceContext({ dir: opts.dir });
+  if (!context.gitRoot)
+    throw new Error("Not inside a Git repository.");
+  const remoteUrl = gitOutput(["remote", "get-url", "origin"], context.gitRoot);
+  runGit(["push", "origin", "main", "--follow-tags"], {
+    cwd: context.gitRoot,
+    config: config2,
+    gitRemoteUrl: remoteUrl ?? undefined
+  });
+}
+function upgradeSource(opts) {
+  const context = resolveGitSourceContext({ dir: opts.dir });
+  if (!context.gitRoot)
+    throw new Error("Not inside a Git repository.");
+  const manifestPath = path2.join(context.gitRoot, "eigenpal.yaml");
+  const manifest = readRootManifest(context.gitRoot);
+  if (!manifest.ok)
+    throw new Error(manifest.error);
+  if (manifest.version === "1.0.0") {
+    success2("Repository source schema is already 1.0.0.");
+    return;
+  }
+  if (opts.dryRun) {
+    console.log(`Would upgrade repository source schema from ${manifest.version} to 1.0.0.`);
+    return;
+  }
+  console.log("Source repository changelog:");
+  console.log(`- ${manifest.version} -> 1.0.0: normalize root eigenpal.yaml schema version.`);
+  writeFileSync2(manifestPath, `schemaVersion: 1
+eigenpalVersion: 1.0.0
+`);
+  doctor({
+    dir: context.packagePath && context.packageRoot ? context.packageRoot : context.gitRoot
+  });
+  success2(`Upgraded repository source schema from ${manifest.version} to 1.0.0.`);
+}
 function parseReleaseVersion(value) {
   if (!/^\d+\.\d+\.\d+$/.test(value) && !["patch", "minor", "major"].includes(value)) {
     throw new InvalidArgumentError("version must be X.Y.Z, patch, minor, or major");
@@ -184783,9 +185382,21 @@ function parseType(value) {
     throw new InvalidArgumentError("type must be agent or workflow");
   return value;
 }
+function parseTemplate(value) {
+  if (!["agent", "workflow", "skill", "rule", "knowledge", "evaluator"].includes(value)) {
+    throw new InvalidArgumentError("template must be agent, workflow, skill, rule, knowledge, or evaluator");
+  }
+  return value;
+}
 function registerGitCommands(program2) {
   const git = program2.command("git", { hidden: true }).description("Experimental Git-backed source commands.").allowUnknownOption(true).allowExcessArguments(true).argument("[gitArgs...]", "Git arguments after --").action(action(async (gitArgs, opts) => gitPassthrough(gitArgs ?? [], opts)));
   withBaseUrl(git.command("clone")).description("Clone the organization source repository.").option("--out <dir>", "Output directory").action(action(cloneSource));
+  withBaseUrl(git.command("install [packageRef]")).description("Materialize a source package and its workspace dependencies.").option("--out <dir>", "Output directory for an explicit package ref").option("--lockfile <path>", "Lockfile path").option("--frozen-lockfile", "Install exactly from the existing lockfile").action(action(install));
+  git.command("init <name>").description("Create a new source package scaffold.").addOption(new Option("--template <template>", "Package template").argParser(parseTemplate).makeOptionMandatory()).option("--dir <dir>", "Repository directory").action(action(async (name, opts) => initPackage(name, opts)));
+  withBaseUrl(git.command("pull")).description("Pull organization source from origin/main with --ff-only.").option("--dir <dir>", "Repository directory").action(action(pullSource));
+  withBaseUrl(git.command("commit")).description("Validate changed source packages and commit them.").addOption(new Option("-m, --message <message>", "Commit message").makeOptionMandatory()).option("--dir <dir>", "Repository directory").action(action(commitSource));
+  withBaseUrl(git.command("push")).description("Push organization source main and tags.").option("--dir <dir>", "Repository directory").action(action(pushSource));
+  git.command("upgrade").description("Upgrade the source repository schema in place.").option("--dir <dir>", "Repository directory").option("--dry-run", "Print upgrade actions without changing files").action(action(async (opts) => upgradeSource(opts)));
   addJsonFlag(git.command("doctor")).description("Check organization source repository health.").option("--dir <dir>", "Directory to inspect").action(action(async (opts) => doctor(opts)));
   addJsonFlag(git.command("validate [dir]")).description("Validate the nearest source package.").action(action(async (dir, opts) => validate({ ...opts, dir })));
   addJsonFlag(git.command("status")).description("Show source repo and package status.").option("--dir <dir>", "Directory to inspect").action(action(async (opts) => packageStatus(opts)));
@@ -184803,11 +185414,11 @@ init_dist4();
 import {
   copyFileSync,
   existsSync as existsSync4,
-  mkdirSync as mkdirSync2,
+  mkdirSync as mkdirSync3,
   readdirSync as readdirSync2,
   readFileSync as readFileSync4,
   statSync as statSync2,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "node:fs";
 import { dirname as dirname2, join as join2, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -184901,10 +185512,10 @@ function copyTemplate(src, dst, projectName) {
         stack.push(sourcePath);
         continue;
       }
-      mkdirSync2(dirname2(targetPath), { recursive: true });
+      mkdirSync3(dirname2(targetPath), { recursive: true });
       if (isTextFile(sourcePath)) {
         const text = readFileSync4(sourcePath, "utf-8").replaceAll(PLACEHOLDER, projectName);
-        writeFileSync2(targetPath, text);
+        writeFileSync3(targetPath, text);
       } else {
         copyFileSync(sourcePath, targetPath);
       }
@@ -184935,17 +185546,17 @@ function isTextFile(path3) {
 
 // src/commands/skill.ts
 init_dist4();
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import {
   existsSync as existsSync5,
   lstatSync,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   readFileSync as readFileSync5,
   readdirSync as readdirSync3,
-  rmSync,
+  rmSync as rmSync2,
   rmdirSync,
   unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync3
+  writeFileSync as writeFileSync4
 } from "node:fs";
 import { sep as PATH_SEP, dirname as dirname3, join as join3, relative as relative2, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
@@ -185034,7 +185645,7 @@ function resolveSkillTarget(opts) {
   return opts.target ?? defaultClaudeTarget();
 }
 function sha256(buffer) {
-  return createHash2("sha256").update(buffer).digest("hex");
+  return createHash3("sha256").update(buffer).digest("hex");
 }
 var CLI_VERSION_PLACEHOLDER = "__CLI_VERSION__";
 function templateSourceFile(relativePath, bytes, cliVersion) {
@@ -185061,8 +185672,8 @@ async function installSkill(opts) {
     const sourceBytes = templateSourceFile(relativePath, readFileSync5(sourcePath), cliVersion);
     const sourceHash = sha256(sourceBytes);
     if (!existsSync5(targetPath)) {
-      mkdirSync3(dirname3(targetPath), { recursive: true });
-      writeFileSync3(targetPath, sourceBytes);
+      mkdirSync4(dirname3(targetPath), { recursive: true });
+      writeFileSync4(targetPath, sourceBytes);
       written += 1;
       continue;
     }
@@ -185075,7 +185686,7 @@ async function installSkill(opts) {
     const previousEntry = existingManifest?.files.find((f) => f.path === relativePath);
     const userEdited = previousEntry ? previousEntry.sha256 !== targetHash : true;
     if (!userEdited || opts.force) {
-      writeFileSync3(targetPath, sourceBytes);
+      writeFileSync4(targetPath, sourceBytes);
       written += 1;
       continue;
     }
@@ -185086,7 +185697,7 @@ async function installSkill(opts) {
     prompted += 1;
     const choice = await promptThreeWay(targetPath, sourceBytes, targetBytes);
     if (choice === "overwrite") {
-      writeFileSync3(targetPath, sourceBytes);
+      writeFileSync4(targetPath, sourceBytes);
       written += 1;
     } else {
       skipped += 1;
@@ -185104,7 +185715,7 @@ async function installSkill(opts) {
     installedAt: new Date().toISOString(),
     files: manifestEntries
   };
-  writeFileSync3(join3(target, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}
+  writeFileSync4(join3(target, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}
 `);
   const displayTarget = relative2(process.cwd(), target) || target;
   success2(`Installed skill at ${ui.bold(displayTarget)} — ${written} written, ${skipped} unchanged${prompted > 0 ? `, ${prompted} prompted` : ""}.`);
@@ -185146,7 +185757,7 @@ async function uninstallSkill(opts) {
     unlinkSync2(path3);
     removed += 1;
   }
-  rmSync(join3(target, MANIFEST_NAME), { force: true });
+  rmSync2(join3(target, MANIFEST_NAME), { force: true });
   pruneEmptyDirs(target);
   const displayTarget = relative2(process.cwd(), target) || target;
   success2(`Uninstalled skill from ${ui.bold(displayTarget)} — ${removed} removed${kept > 0 ? `, ${kept} user-edited kept` : ""}.`);
@@ -186303,7 +186914,7 @@ async function resolveWorkflowId(client, idOrSlug) {
 }
 
 // src/commands/clear.ts
-import { existsSync as existsSync8, readdirSync as readdirSync5, rmSync as rmSync2, statSync as statSync4 } from "fs";
+import { existsSync as existsSync8, readdirSync as readdirSync5, rmSync as rmSync3, statSync as statSync4 } from "fs";
 import { basename, join as join7 } from "path";
 
 // src/lib/payload.ts
@@ -186420,7 +187031,7 @@ function removeDirEntriesWithRetention(path3, removeAll) {
   for (const entry of entries) {
     if (keepSet.has(entry))
       continue;
-    rmSync2(join7(path3, entry), { recursive: true, force: true });
+    rmSync3(join7(path3, entry), { recursive: true, force: true });
     removed++;
   }
   return { removed, kept: keepSet.size, touched: entries.length };
@@ -186447,7 +187058,7 @@ function removeJudgeSummaryFilesWithRetention(exampleDir, removeAll) {
       kept++;
       continue;
     }
-    rmSync2(join7(exampleDir, fileName), { force: true });
+    rmSync3(join7(exampleDir, fileName), { force: true });
     removed++;
   }
   return { removed, kept, touched: stampByFile.size };
@@ -186643,11 +187254,11 @@ async function watchExecution(opts) {
 import { join as join11 } from "path";
 
 // src/lib/execution-artifacts.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync4, readdirSync as readdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5, readdirSync as readdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "fs";
 import { join as join10 } from "path";
 
 // src/lib/format.ts
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
 import { extname as extname3, resolve as resolve5 } from "path";
 var PRETTIER_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
 async function formatFileIfAvailable(filepath) {
@@ -186660,7 +187271,7 @@ async function formatFileIfAvailable(filepath) {
       filepath: resolve5(filepath)
     });
     if (formatted !== content) {
-      writeFileSync4(filepath, formatted, "utf-8");
+      writeFileSync5(filepath, formatted, "utf-8");
     }
   } catch (err2) {
     if (env.DEBUG?.includes("prettier")) {
@@ -186694,7 +187305,7 @@ async function writeExecutionArtifacts(client, exampleDir, payload) {
   const folderName = timestampFolderName(payload);
   const executionsDir = join10(exampleDir, "executions", folderName);
   const filesDir = join10(executionsDir, "files");
-  mkdirSync4(filesDir, { recursive: true });
+  mkdirSync5(filesDir, { recursive: true });
   const generatedFiles = [];
   const result = payload.result;
   if (isWorkflowResult2(result) && result.files.length > 0) {
@@ -186711,7 +187322,7 @@ async function writeExecutionArtifacts(client, exampleDir, payload) {
         const safe = safeFilename(filename, `file-${i5}${filename.includes(".") ? "" : ".bin"}`);
         const destPath = join10(filesDir, safe);
         const buf = Buffer.from(await res.arrayBuffer());
-        writeFileSync5(destPath, buf);
+        writeFileSync6(destPath, buf);
         generatedFiles.push({ fileId, stepName, filename: safe });
       } catch (err2) {
         console.warn(`  Warning: could not download file ${fileId}:`, err2);
@@ -186723,7 +187334,7 @@ async function writeExecutionArtifacts(client, exampleDir, payload) {
     generatedFiles: generatedFiles.length > 0 ? generatedFiles : undefined
   };
   const outputPath = join10(executionsDir, "output.json");
-  writeFileSync5(outputPath, JSON.stringify(output, null, 2) + `
+  writeFileSync6(outputPath, JSON.stringify(output, null, 2) + `
 `, "utf-8");
   await formatFileIfAvailable(outputPath);
   return executionsDir;

package/dist/skill/reference/cli/git.md

@@ -2,212 +2,6 @@
 
 Experimental Git-backed source commands.
 
-## Contents
+Experimental.
 
-- [Surface](#surface)
-- [Commands](#commands)
-  - [Core](#core)
-- [Details](#details)
-  - [`eigenpal git clone [options]`](#eigenpal-git-clone-options)
-  - [`eigenpal git doctor [options]`](#eigenpal-git-doctor-options)
-  - [`eigenpal git validate [options] [dir]`](#eigenpal-git-validate-options-dir)
-  - [`eigenpal git status [options]`](#eigenpal-git-status-options)
-  - [`eigenpal git deps [options]`](#eigenpal-git-deps-options)
-  - [`eigenpal git clean [options]`](#eigenpal-git-clean-options)
-  - [`eigenpal git list|ls [options]`](#eigenpal-git-listls-options)
-  - [`eigenpal git show [options] <automation>`](#eigenpal-git-show-options-automation)
-  - [`eigenpal git versions [options] <package>`](#eigenpal-git-versions-options-package)
-  - [`eigenpal git release [options] <version> [dir]`](#eigenpal-git-release-options-version-dir)
-  - [`eigenpal git sync [options] [automation]`](#eigenpal-git-sync-options-automation)
-
-## Surface
-
-```
-git
-├── clone
-├── doctor
-├── validate [dir]
-├── status
-├── deps
-├── clean
-├── list|ls
-├── show <automation>
-├── versions <package>
-├── release <version> [dir]
-└── sync [automation]
-```
-
-## Commands
-
-### Core
-
-| Command                                          | Description                                            |
-| ------------------------------------------------ | ------------------------------------------------------ | ---------------------------- |
-| `eigenpal git clone [options]`                   | Clone the organization source repository.              |
-| `eigenpal git doctor [options]`                  | Check organization source repository health.           |
-| `eigenpal git validate [options] [dir]`          | Validate the nearest source package.                   |
-| `eigenpal git status [options]`                  | Show source repo and package status.                   |
-| `eigenpal git deps [options]`                    | List package workspace dependencies.                   |
-| `eigenpal git clean [options]`                   | Require a clean source working tree.                   |
-| `eigenpal git list                               | ls [options]`                                          | List Git-backed automations. |
-| `eigenpal git show [options] <automation>`       | Show Git-backed automation details.                    |
-| `eigenpal git versions [options] <package>`      | List package release versions.                         |
-| `eigenpal git release [options] <version> [dir]` | Create and push a package release tag.                 |
-| `eigenpal git sync [options] [automation]`       | Sync an automation from the latest Git source release. |
-
-## Details
-
-### `eigenpal git clone [options]`
-
-Clone the organization source repository.
-
-### Options
-
-| Flag               | Required | Default | Description      |
-| ------------------ | -------- | ------- | ---------------- |
-| `--base-url <url>` | no       |         | Server base URL  |
-| `--out <dir>`      | no       |         | Output directory |
-
-### `eigenpal git doctor [options]`
-
-Check organization source repository health.
-
-### Options
-
-| Flag          | Required | Default | Description                            |
-| ------------- | -------- | ------- | -------------------------------------- |
-| `--json`      | no       |         | Output the raw server response as JSON |
-| `--dir <dir>` | no       |         | Directory to inspect                   |
-
-### `eigenpal git validate [options] [dir]`
-
-Validate the nearest source package.
-
-### Arguments
-
-| Name  | Required | Variadic | Description |
-| ----- | -------- | -------- | ----------- |
-| `dir` | no       | no       |             |
-
-### Options
-
-| Flag     | Required | Default | Description                            |
-| -------- | -------- | ------- | -------------------------------------- |
-| `--json` | no       |         | Output the raw server response as JSON |
-
-### `eigenpal git status [options]`
-
-Show source repo and package status.
-
-### Options
-
-| Flag          | Required | Default | Description                            |
-| ------------- | -------- | ------- | -------------------------------------- |
-| `--json`      | no       |         | Output the raw server response as JSON |
-| `--dir <dir>` | no       |         | Directory to inspect                   |
-
-### `eigenpal git deps [options]`
-
-List package workspace dependencies.
-
-### Options
-
-| Flag          | Required | Default | Description                            |
-| ------------- | -------- | ------- | -------------------------------------- |
-| `--json`      | no       |         | Output the raw server response as JSON |
-| `--dir <dir>` | no       |         | Directory to inspect                   |
-
-### `eigenpal git clean [options]`
-
-Require a clean source working tree.
-
-### Options
-
-| Flag          | Required | Default | Description          |
-| ------------- | -------- | ------- | -------------------- |
-| `--dir <dir>` | no       |         | Directory to inspect |
-
-### `eigenpal git list|ls [options]`
-
-List Git-backed automations.
-
-### Options
-
-| Flag                 | Required | Default | Description                            |
-| -------------------- | -------- | ------- | -------------------------------------- |
-| `--base-url <url>`   | no       |         | Server base URL                        |
-| `--limit <n>`        | no       | `50`    | Page size                              |
-| `--offset <n>`       | no       | `0`     | Page offset                            |
-| `--json`             | no       |         | Output the raw server response as JSON |
-| `--type <type>`      | no       |         | Filter by automation type              |
-| `--search <q>`       | no       |         | Search by slug, name, or description   |
-| `--include-archived` | no       |         | Include archived automations           |
-
-### `eigenpal git show [options] <automation>`
-
-Show Git-backed automation details.
-
-### Arguments
-
-| Name         | Required | Variadic | Description |
-| ------------ | -------- | -------- | ----------- |
-| `automation` | yes      | no       |             |
-
-### Options
-
-| Flag               | Required | Default | Description                            |
-| ------------------ | -------- | ------- | -------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                        |
-| `--json`           | no       |         | Output the raw server response as JSON |
-
-### `eigenpal git versions [options] <package>`
-
-List package release versions.
-
-### Arguments
-
-| Name      | Required | Variadic | Description |
-| --------- | -------- | -------- | ----------- |
-| `package` | yes      | no       |             |
-
-### Options
-
-| Flag               | Required | Default | Description                            |
-| ------------------ | -------- | ------- | -------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                        |
-| `--json`           | no       |         | Output the raw server response as JSON |
-
-### `eigenpal git release [options] <version> [dir]`
-
-Create and push a package release tag.
-
-### Arguments
-
-| Name      | Required | Variadic | Description           |
-| --------- | -------- | -------- | --------------------- |
-| `version` | yes      | no       | Version or bump level |
-| `dir`     | no       | no       | Package directory     |
-
-### Options
-
-| Flag                      | Required | Default | Description           |
-| ------------------------- | -------- | ------- | --------------------- |
-| `--base-url <url>`        | no       |         | Server base URL       |
-| `-m, --message <message>` | yes      |         | Annotated tag message |
-
-### `eigenpal git sync [options] [automation]`
-
-Sync an automation from the latest Git source release.
-
-### Arguments
-
-| Name         | Required | Variadic | Description |
-| ------------ | -------- | -------- | ----------- |
-| `automation` | no       | no       |             |
-
-### Options
-
-| Flag               | Required | Default | Description          |
-| ------------------ | -------- | ------- | -------------------- |
-| `--base-url <url>` | no       |         | Server base URL      |
-| `--dir <dir>`      | no       |         | Directory to inspect |
+This command namespace is intentionally not documented in detail yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/cli",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   "keywords": [
     "eigenpal",