@kontourai/flow-agents 1.0.0 → 1.1.0

package/src/cli/flow-kit.ts

@@ -1,6 +1,9 @@
+import * as child_process from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
 import { assertKitRepository, deriveKitTargets } from "../flow-kit/validate.js";
@@ -31,6 +34,22 @@ function contentHash(root: string): string {
   return `sha256:${hash.digest("hex")}`;
 }
 
+/** Content hash that excludes .git and other VCS/cache directories (for install-git clones). */
+function kitContentHash(root: string): string {
+  const EXCLUDE_DIRS = new Set([".git", "__pycache__", ".pytest_cache"]);
+  const hash = crypto.createHash("sha256");
+  for (const file of walkFiles(root)) {
+    const parts = path.relative(root, file).split(path.sep);
+    if (parts.some((p) => EXCLUDE_DIRS.has(p))) continue;
+    const rel = parts.join("/");
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
 function installLocal(argv: string[]): number {
   const args = parseArgs(argv);
   const source = path.resolve(args.positionals[0] ?? "");
@@ -39,12 +58,10 @@ function installLocal(argv: string[]): number {
   try {
     manifest = assertKitRepository(source);
   } catch (error) {
-    console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
     console.log("Flow Kit repository validation failed:");
     for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) console.log(` - ${diagnostic}`);
     return 1;
   }
-  console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
   const kitId = String(manifest.id);
   const hash = contentHash(source);
   const registry = loadRegistry(dest);
@@ -169,15 +186,117 @@ function inspect(argv: string[]): number {
   return result.conformance.k0 ? 0 : 1;
 }
 
+
+/**
+ * install-git <repo-url>[#ref] [--ref <branch|tag|sha>] [--dest <path>] [--force] [--update]
+ *
+ * Shallow-clones a remote git repository to a temporary directory, validates the kit
+ * container with the same logic used by install-local, then delegates to the existing
+ * install path. Supports an optional #ref fragment in the URL or a separate --ref flag.
+ *
+ * Implements kontourai/flow-agents#56 (git-ref install surface).
+ */
+function installGit(argv: string[]): number {
+  const args = parseArgs(argv);
+  const rawUrl = args.positionals[0] ?? "";
+  if (!rawUrl) {
+    console.error("install-git: missing <repo-url> argument");
+    console.error("usage: flow-kit install-git <repo-url>[#ref] [--ref <branch|tag|sha>] [--dest <path>]");
+    return 2;
+  }
+
+  // Parse ref: #fragment in URL takes precedence over --ref flag.
+  let repoUrl = rawUrl;
+  let ref: string | null = null;
+  const hashIdx = rawUrl.indexOf("#");
+  if (hashIdx !== -1) {
+    repoUrl = rawUrl.slice(0, hashIdx);
+    ref = rawUrl.slice(hashIdx + 1) || null;
+  }
+  if (!ref) ref = flagString(args.flags, "ref") ?? null;
+
+  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const force = flagBool(args.flags, "force") ?? false;
+  const update = flagBool(args.flags, "update") ?? false;
+
+  // Shallow-clone into a temporary directory.
+  const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), "flow-kit-git-"));
+  try {
+    const cloneArgs = ["clone", "--depth", "1"];
+    if (ref) cloneArgs.push("--branch", ref);
+    cloneArgs.push("--", repoUrl, tmpBase);
+    try {
+      child_process.execFileSync("git", cloneArgs, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      const msg = err instanceof Error && (err as NodeJS.ErrnoException & { stderr?: Buffer }).stderr
+        ? ((err as NodeJS.ErrnoException & { stderr?: Buffer }).stderr as Buffer).toString().trim()
+        : String(err);
+      console.error(`install-git: git clone failed: ${msg}`);
+      return 1;
+    }
+
+    // Validate the cloned kit using the same logic as install-local.
+    let manifest: Record<string, unknown>;
+    try {
+      manifest = assertKitRepository(tmpBase);
+    } catch (error) {
+      console.log("Flow Kit repository validation failed:");
+      for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) {
+        console.log(` - ${diagnostic}`);
+      }
+      return 1;
+    }
+
+    // Delegate to the shared install logic (copy + registry update).
+    const kitId = String(manifest.id);
+    const hash = kitContentHash(tmpBase);
+    const registry = loadRegistry(dest);
+    const existing = registry.kits.find((entry) => entry.id === kitId);
+    const target = installedPath(dest, kitId);
+    assertPathContained(dest, target);
+    const sourceText = repoUrl + (ref ? `#${ref}` : "");
+    if (existing && existing.source !== sourceText && !update) {
+      console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
+      return 2;
+    }
+    if (existing && existing.source === sourceText && existing.hash === hash && fs.existsSync(target) && !force) {
+      console.log(`kit '${kitId}' is already installed from ${sourceText}`);
+      return 0;
+    }
+    copyDir(tmpBase, target);
+    const entry: Record<string, unknown> = {
+      id: kitId,
+      source: sourceText,
+      hash,
+      installed_at: existing && existing.source === sourceText && !update ? existing.installed_at : isoNow(),
+      installed_path: target,
+      state: "installed",
+    };
+    if (typeof manifest.version === "string" && manifest.version) entry.version = manifest.version;
+    registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
+    writeJson(registryPath(dest), registry);
+    console.log(`${existing ? "updated" : "installed"} git kit '${kitId}' from ${sourceText} at ${target}`);
+    return 0;
+  } finally {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  }
+}
+
 export function main(argv = process.argv.slice(2)): number {
   const [command, ...rest] = argv;
   if (command === "install-local") return installLocal(rest);
+  if (command === "install-git") return installGit(rest);
   if (command === "list") return list(rest);
   if (command === "status") return status(rest);
   if (command === "activate") return activate(rest);
   if (command === "inspect") return inspect(rest);
-  console.error("usage: flow-kit <install-local|list|status|activate|inspect> ...");
+  console.error("usage: flow-kit <install-local|install-git|list|status|activate|inspect> ...");
   return 2;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/init.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -458,4 +459,9 @@ export async function mainDogfood(argv = process.argv.slice(2)): Promise<number>
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(await main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = await main(); }

package/src/cli/promote-workflow-artifact.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { isoNow, relPath } from "../lib/fs.js";
@@ -61,4 +62,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/publish-change-helper.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { readJson } from "../lib/fs.js";
@@ -140,4 +141,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/pull-work-provider.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import { parseArgs, flagList, flagString } from "../lib/args.js";
 
 const FLOW_ARTIFACT_PATTERN = /(?<path>\.flow-agents\/[^\s`'")]+)/g;
@@ -478,4 +479,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/runtime-adapter.ts

@@ -1,3 +1,5 @@
+import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
@@ -26,4 +28,9 @@ export function main(argv = process.argv.slice(2)): number {
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/usage-feedback.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
@@ -415,4 +416,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/utterance-check.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
 
@@ -321,4 +322,9 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
   return runCheck(rest);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(await main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = await main(); }

package/src/cli/validate-hook-influence.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const validTiers = new Set(["adapter", "design-target", "installed-command", "live-acceptance", "documented-runtime-gap"]);
 const validRuntimes = new Set(["codex", "claude-code", "kiro-cli"]);
@@ -116,4 +117,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/validate-source-tree.ts

@@ -27,4 +27,10 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS).
+import * as _fsVST from "node:fs";
+import { fileURLToPath as _ftpVST } from "node:url";
+const _selfVST = (() => { try { return _fsVST.realpathSync(_ftpVST(import.meta.url)); } catch { return _ftpVST(import.meta.url); } })();
+const _argv1VST = (() => { try { return _fsVST.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfVST === _argv1VST) { process.exitCode = main(); }

package/src/cli/veritas-governance.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
@@ -319,4 +320,9 @@ export function main(argv = process.argv.slice(2)): number {
   return options ? runEvidence(options) : 2;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/cli/workflow-artifact-cleanup-audit.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
 
@@ -278,4 +279,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/runtime-adapters.ts

@@ -86,7 +86,7 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
   const errors: string[] = [];
   const assets: KitAsset[] = [];
   const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
-  if (!fs.existsSync(catalogPath)) errors.push(`${catalogPath}: missing Kit Catalog`);
+  if (!fs.existsSync(catalogPath)) warnings.push(`${catalogPath}: built-in Kit Catalog not found; skipping built-in kits (this is normal when running outside a flow-agents checkout)`);
   else {
     const catalog = readJson(catalogPath) as Record<string, unknown>;
     const kits = catalog.kits;
@@ -126,31 +126,47 @@ function safeSegment(value: string): string {
   return value.replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^[.-]+|[.-]+$/g, "") || "asset";
 }
 
+// Asset classes that are directly activated (copied to the runtime directory) by both adapters.
+// flows: gate definitions read by the adapter's flow-routing layer.
+// skills: agent guidance markdown copied to skills/<kit-id>/ for agent discovery.
+// docs: documentation markdown copied to docs/<kit-id>/ for agent reference.
+const ACTIVATED_ASSET_CLASSES = new Set(["flows", "skills", "docs"]);
+
 export function activateCodexLocal(sourceRoot: string, dest: string): Record<string, unknown> {
   const inventory = readKitInventory(sourceRoot, dest);
   const runtimeDir = path.join(dest, ".flow-agents", "runtime", "codex");
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
-    if (asset.asset_class !== "flows") {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for codex-local" });
-      continue;
-    }
-    if (!asset.asset_id) {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
-      continue;
+    if (asset.asset_class === "flows") {
+      if (!asset.asset_id) {
+        skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+        continue;
+      }
+      const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+    } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
+      // Copy skills and docs to runtime/<adapter>/<class>/<kit-id>/<filename> so the
+      // agent's guidance index (AGENTS.md) can reference them and they are co-located
+      // with flow definitions for the same kit.
+      const filename = path.basename(asset.source_path);
+      const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
+    } else {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by codex-local" });
     }
-    const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-    fs.mkdirSync(path.dirname(output), { recursive: true });
-    fs.copyFileSync(asset.source_path, output);
-    generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
   }
   fs.mkdirSync(runtimeDir, { recursive: true });
-  const manifest = { schema_version: "1.0", adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
+  const manifest = { schema_version: "1.0", adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
   const manifestPath = path.join(runtimeDir, "activation.json");
   writeJson(manifestPath, manifest);
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
-  return { selected_adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  return { selected_adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
 
 // Decision Q3 (Issue #32): Option (a) — new adapter id "strands-local" rather than
@@ -163,27 +179,39 @@ export function activateStrandsLocal(sourceRoot: string, dest: string): Record<s
   const inventory = readKitInventory(sourceRoot, dest);
   // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
   // so the Strands steering context can glob for *.flow.json under this path.
+  // Runtime skills land at .flow-agents/runtime/strands/skills/<kit-id>/<filename> and
+  // docs at .flow-agents/runtime/strands/docs/<kit-id>/<filename> for system-prompt injection.
   const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
-    if (asset.asset_class !== "flows") {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for strands-local" });
-      continue;
-    }
-    if (!asset.asset_id) {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
-      continue;
+    if (asset.asset_class === "flows") {
+      if (!asset.asset_id) {
+        skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+        continue;
+      }
+      const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+    } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
+      // Mirror the codex-local layout: strands/<class>/<kit-id>/<filename>.
+      // The Strands system-prompt injection layer can glob for all *.md files under
+      // .flow-agents/runtime/strands/skills/ to include agent guidance in the context.
+      const filename = path.basename(asset.source_path);
+      const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
+    } else {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by strands-local" });
     }
-    const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-    fs.mkdirSync(path.dirname(output), { recursive: true });
-    fs.copyFileSync(asset.source_path, output);
-    generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
   }
   fs.mkdirSync(runtimeDir, { recursive: true });
-  const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
+  const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
   const manifestPath = path.join(runtimeDir, "activation.json");
   writeJson(manifestPath, manifest);
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
-  return { selected_adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  return { selected_adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }

package/src/tools/build-universal-bundles.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
 
@@ -646,4 +647,9 @@ export function main(): number {
   }
   return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/tools/generate-context-map.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { exists, loadJson, markdownTable, oneLine, readText, rel, root, writeText } from "./common.js";
 
@@ -196,4 +197,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/tools/validate-package.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 export function main(argv = process.argv.slice(2)): number {
@@ -54,4 +55,9 @@ export function main(argv = process.argv.slice(2)): number {
   console.log(errors === 0 ? "Result: PASS" : `Result: FAIL (${errors} error(s))`);
   return errors === 0 ? 0 : 1;
 }
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/tools/validate-source-tree.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
@@ -84,7 +85,7 @@ const fixtureOwnerPolicies = new Map<string, { owners: string[]; classification:
   ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
   ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
   ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
-  ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
+  ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
   ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
   ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
   ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
@@ -491,4 +492,9 @@ export function main(argv = process.argv.slice(2)): number {
   console.log("Source tree validation passed.");
   return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }