@kontourai/flow-agents 0.4.0 → 1.0.1

package/kits/knowledge/kit.json

@@ -61,6 +61,11 @@
       "id": "knowledge.similarity-vector",
       "path": "adapters/similarity-vector/index.js",
       "description": "Vector similarity detector: createVectorSimilarityDetector(options) returns a drop-in SimilarityDetector backed by dense embeddings and cosine similarity. Supports injectable embed fn (tests) or ollama /api/embed (default). Fail-closed: throws EMBED_FAILURE on infrastructure errors rather than silently masking them as empty clusters."
+    },
+    {
+      "id": "knowledge.obsidian-store",
+      "path": "adapters/obsidian-store/index.js",
+      "description": "Obsidian store adapter: each record is one human-canonical Obsidian markdown note. Frontmatter carries all contract fields; body rendered with callouts (raw), readable prose + Sources/Related wikilink sections (compiled/concept/snapshot). Category dots map to folder hierarchy; title-slugified filenames with collision suffix; superseded records move to archive/ (supersede-not-delete invariant). Backed by shared codec with default-store."
     }
   ],
   "evals": [
@@ -93,6 +98,11 @@
       "id": "knowledge.retirement-suite",
       "path": "evals/retirement/suite.test.js",
       "description": "Eval cases for retire: AC1 (retirement only via approved proposal with rationale/ref, transition table enforcement); AC2 (retired excluded from listByType/listByCategory/similarity defaults, returned with includeRetired flag, provenance intact via get()); AC3 (consolidation after retirement reflects pruned working set; retired record still reachable from snapshot provenance history); rejection leaves status byte-identical; gate telemetry."
+    },
+    {
+      "id": "knowledge.entity-cards-suite",
+      "path": "evals/entities/suite.test.js",
+      "description": "Eval cases for person/entity cards (issue #48): AC1-AC4 \u2014 entity extraction from Attendees lines, exact-match resolution, possible-duplicate detection, merge via propose/apply/reject (union aliases+backlinks, supersede duplicate), Obsidian people/ folder rendering, and extended contract suite (person type validity) on both adapters."
     }
   ]
 }

package/kits/release-evidence/fixtures/claims/README.md

@@ -0,0 +1,14 @@
+# Claim Fixtures
+
+These trust-report JSON files are used by `.github/workflows/kit-gates-demo.yml` to prove
+agentless gate evaluation against the `release-evidence` Flow Kit.
+
+| File | Purpose |
+| --- | --- |
+| `pass-trusted-release.trust.json` | Passing case: `release.evidence` claim with status `trusted`. Gate verdict: `pass`. |
+| `fail-rejected-release.trust.json` | Failing case: `release.evidence` claim with status `rejected`. Gate verdict: `route-back` or `block`. The workflow asserts the failure is detected (non-zero exit) rather than letting it silently pass. |
+
+## Format
+
+Each file is a Surface trust-report artifact (`artifact_type: "trust-report"`).
+The Flow CLI normalizes these via `flow attach-evidence --trust-artifact` before gate evaluation.

package/kits/release-evidence/fixtures/claims/fail-rejected-release.trust.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "0.1",
+  "artifact_type": "trust-report",
+  "subject": "ci/release-evidence-gate",
+  "producer": "ci/release-evidence-probe",
+  "status": "rejected",
+  "issued_at": "2026-06-12T00:00:00.000Z",
+  "authority_traces": [
+    "github:main"
+  ],
+  "claims": [
+    {
+      "type": "release.evidence",
+      "subject": "ci/release-evidence-gate",
+      "status": "rejected",
+      "issued_at": "2026-06-12T00:00:00.000Z"
+    }
+  ],
+  "integrity": {
+    "verified": true
+  }
+}

package/kits/release-evidence/fixtures/claims/pass-trusted-release.trust.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "0.1",
+  "artifact_type": "trust-report",
+  "subject": "ci/release-evidence-gate",
+  "producer": "ci/release-evidence-probe",
+  "status": "trusted",
+  "issued_at": "2026-06-12T00:00:00.000Z",
+  "authority_traces": [
+    "github:main"
+  ],
+  "claims": [
+    {
+      "type": "release.evidence",
+      "subject": "ci/release-evidence-gate",
+      "status": "trusted",
+      "issued_at": "2026-06-12T00:00:00.000Z"
+    }
+  ],
+  "integrity": {
+    "verified": true
+  }
+}

package/kits/release-evidence/flows/release-evidence.flow.json

@@ -0,0 +1,38 @@
+{
+  "id": "release-evidence",
+  "version": "1.0",
+  "steps": [
+    {
+      "id": "gate-check",
+      "next": null
+    }
+  ],
+  "gates": {
+    "release-evidence-gate": {
+      "step": "gate-check",
+      "expects": [
+        {
+          "id": "release-claim-present",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A trusted release.evidence claim must be attached before this gate can pass.",
+          "explore_hint": "Attach a trust-report JSON file with claim type release.evidence and status trusted.",
+          "claim": {
+            "type": "release.evidence",
+            "accepted_statuses": [
+              "trusted"
+            ]
+          }
+        }
+      ],
+      "on_route_back": {
+        "missing_evidence": "gate-check",
+        "default": "gate-check"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      }
+    }
+  }
+}

package/kits/release-evidence/kit.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "id": "release-evidence",
+  "name": "Release Evidence Kit",
+  "description": "A minimal flows-only Flow Kit for proving agentless gate evaluation over surface claims in CI. One gate expects a trusted release.evidence claim; CI attaches a claim file and calls flow evaluate.",
+  "flows": [
+    {
+      "id": "release-evidence",
+      "path": "flows/release-evidence.flow.json",
+      "description": "Single-gate flow that requires a trusted release.evidence claim before the gate-check step can pass."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/packaging/conformance/fixtures/config-protection--allow-no-verify-in-string.json

@@ -0,0 +1,20 @@
+{
+  "description": "config-protection allows a command whose string content merely mentions the bypass flag",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Bash",
+    "tool_input": {
+      "command": "gh issue create --body \"git commit --no-verify is blocked by the hook\""
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stderr_is_empty": true,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/config-protection--block-git-no-verify.json

@@ -0,0 +1,23 @@
+{
+  "description": "config-protection blocks a Bash command carrying the bypass flag in actual flag position",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Bash",
+    "tool_input": {
+      "command": "git commit --no-verify -m fix"
+    }
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": [
+      "BLOCKED",
+      "verification hooks"
+    ],
+    "stdout_is_empty": true
+  }
+}

package/scripts/hooks/config-protection.js

@@ -5,6 +5,9 @@
  * Blocks modifications to linter/formatter config files.
  * Steers the agent to fix source code instead of weakening configs.
  *
+ * Also blocks git verification-bypass flags in actual flag positions only.
+ * Text that merely mentions the flag inside quoted strings or prose is allowed.
+ *
  * Exit codes: 0 = allow, 2 = block
  */
 
@@ -25,6 +28,195 @@ const PROTECTED_FILES = new Set([
   '.markdownlint.json', '.markdownlint.yaml', '.markdownlintrc',
 ]);
 
+// ---------------------------------------------------------------------------
+// Shell-aware tokenizer
+//
+// Splits a shell command string into tokens, respecting single/double quotes
+// and backslash escapes.  Quoted content stays inside its parent token so
+// flag text inside a -m argument string is never matched as a flag.
+// ---------------------------------------------------------------------------
+
+/**
+ * tokenize(cmd) -- shell-aware tokenizer for a single command segment.
+ * Returns an array of unquoted token strings.
+ */
+function tokenize(cmd) {
+  const tokens = [];
+  let i = 0;
+  const len = cmd.length;
+
+  while (i < len) {
+    // Skip whitespace between tokens.
+    while (i < len && /\s/.test(cmd[i])) i++;
+    if (i >= len) break;
+
+    let token = '';
+
+    // Consume one token -- stop at unquoted whitespace.
+    while (i < len) {
+      const ch = cmd[i];
+
+      if (ch === '\\') {
+        // Backslash escape outside of quotes.
+        i++;
+        if (i < len) token += cmd[i++];
+      } else if (ch === "'") {
+        // Single-quoted string: no escape processing, read until closing quote.
+        i++;
+        while (i < len && cmd[i] !== "'") token += cmd[i++];
+        i++; // consume closing quote
+      } else if (ch === '"') {
+        // Double-quoted string: honour \" and \\ escape sequences.
+        i++;
+        while (i < len && cmd[i] !== '"') {
+          if (cmd[i] === '\\' && i + 1 < len && (cmd[i + 1] === '"' || cmd[i + 1] === '\\')) {
+            i++; // skip the backslash
+            token += cmd[i++];
+          } else {
+            token += cmd[i++];
+          }
+        }
+        i++; // consume closing quote
+      } else if (/\s/.test(ch)) {
+        break; // end of token
+      } else {
+        token += ch;
+        i++;
+      }
+    }
+
+    if (token.length > 0) tokens.push(token);
+  }
+
+  return tokens;
+}
+
+/**
+ * splitSegments(cmd) -- split on shell connectors && || ; | outside of quotes.
+ */
+function splitSegments(cmd) {
+  const segments = [];
+  let i = 0;
+  const len = cmd.length;
+  let segStart = 0;
+
+  while (i < len) {
+    const ch = cmd[i];
+
+    if (ch === '\\') {
+      i += 2; // skip escaped character
+    } else if (ch === "'") {
+      i++;
+      while (i < len && cmd[i] !== "'") i++;
+      i++; // skip closing quote
+    } else if (ch === '"') {
+      i++;
+      while (i < len) {
+        if (cmd[i] === '\\' && i + 1 < len) { i += 2; continue; }
+        if (cmd[i] === '"') { i++; break; }
+        i++;
+      }
+    } else if (ch === '&' && i + 1 < len && cmd[i + 1] === '&') {
+      segments.push(cmd.slice(segStart, i).trim());
+      i += 2; segStart = i;
+    } else if (ch === '|' && i + 1 < len && cmd[i + 1] === '|') {
+      segments.push(cmd.slice(segStart, i).trim());
+      i += 2; segStart = i;
+    } else if (ch === ';') {
+      segments.push(cmd.slice(segStart, i).trim());
+      i++; segStart = i;
+    } else if (ch === '|') {
+      // single pipe
+      segments.push(cmd.slice(segStart, i).trim());
+      i++; segStart = i;
+    } else {
+      i++;
+    }
+  }
+
+  const tail = cmd.slice(segStart).trim();
+  if (tail.length > 0) segments.push(tail);
+  return segments.filter(s => s.length > 0);
+}
+
+// Git global flags that consume a following argument value.
+const GIT_GLOBAL_FLAGS_WITH_ARG = new Set(['-C', '-c', '--exec-path', '--git-dir', '--work-tree', '--namespace']);
+// Git global flags that are standalone (no following argument).
+const GIT_GLOBAL_FLAGS_STANDALONE = new Set([
+  '--version', '--help', '--html-path', '--man-path', '--info-path',
+  '-p', '--paginate', '-P', '--no-pager', '--no-replace-objects',
+  '--bare', '--literal-pathspecs', '--glob-pathspecs', '--noglob-pathspecs',
+  '--icase-pathspecs', '--no-optional-locks', '--list-cmds',
+]);
+
+/**
+ * resolveGitSubcommand(tokens) -- walk past global git flags and return the
+ * subcommand token, or null if not determinable.
+ */
+function resolveGitSubcommand(tokens) {
+  let i = 1;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (GIT_GLOBAL_FLAGS_WITH_ARG.has(t)) {
+      i += 2;
+    } else if (GIT_GLOBAL_FLAGS_STANDALONE.has(t)) {
+      i += 1;
+    } else if (t.startsWith('-')) {
+      i += 1; // unknown global flag -- skip conservatively
+    } else {
+      return { subcommand: t, flagsStart: i + 1 };
+    }
+  }
+  return null;
+}
+
+// Flags for git commit that consume the immediately following token as a value.
+const COMMIT_FLAGS_WITH_VALUE = new Set([
+  '-m', '--message', '-F', '--file', '-C', '-c',
+  '--author', '--date', '--fixup', '--squash', '--pathspec-from-file',
+]);
+
+// Flags for git push that consume the following token as a value.
+const PUSH_FLAGS_WITH_VALUE = new Set([
+  '--receive-pack', '--repo', '--push-option', '-o', '--recurse-submodules',
+]);
+
+const BYPASS_NV = '--no-verify';
+const BYPASS_N = '-n'; // short alias (commit only; on push -n means --dry-run)
+
+function checkSegmentForBypass(tokens) {
+  if (tokens.length === 0 || tokens[0] !== 'git') return null;
+  const resolved = resolveGitSubcommand(tokens);
+  if (!resolved) return null;
+  const { subcommand, flagsStart } = resolved;
+  if (subcommand === 'commit') {
+    for (let i = flagsStart; i < tokens.length; i++) {
+      const t = tokens[i];
+      if (t === BYPASS_NV || t === BYPASS_N) return `git ${subcommand} ${t}`;
+      if (COMMIT_FLAGS_WITH_VALUE.has(t)) i++;
+    }
+  } else if (subcommand === 'push') {
+    for (let i = flagsStart; i < tokens.length; i++) {
+      const t = tokens[i];
+      if (t === BYPASS_NV) return `git ${subcommand} ${t}`;
+      if (PUSH_FLAGS_WITH_VALUE.has(t)) i++;
+    }
+  }
+  return null;
+}
+
+function checkCommandForBypass(command) {
+  if (typeof command !== 'string' || !command) return null;
+  if (!command.includes('git')) return null;
+  const segments = splitSegments(command);
+  for (const seg of segments) {
+    const tokens = tokenize(seg);
+    const result = checkSegmentForBypass(tokens);
+    if (result) return result;
+  }
+  return null;
+}
+
 function run(inputOrRaw, options = {}) {
   if (options.truncated) {
     return {
@@ -33,30 +225,40 @@ function run(inputOrRaw, options = {}) {
         'Refusing to bypass config-protection on a truncated payload.',
     };
   }
-
   let input;
   try {
     input = typeof inputOrRaw === 'string' ? JSON.parse(inputOrRaw) : inputOrRaw;
   } catch { return { exitCode: 0 }; }
-
   const filePath = input?.tool_input?.path || input?.tool_input?.file_path || '';
-  if (!filePath) return { exitCode: 0 };
-
-  const basename = path.basename(filePath);
-  if (PROTECTED_FILES.has(basename)) {
-    return {
-      exitCode: 2,
-      stderr: `BLOCKED: Modifying ${basename} is not allowed. ` +
-        'Fix the source code to satisfy linter/formatter rules instead of ' +
-        'weakening the config. If this is a legitimate config change, ' +
-        'disable the config-protection hook temporarily.',
-    };
+  if (filePath) {
+    const basename = path.basename(filePath);
+    if (PROTECTED_FILES.has(basename)) {
+      return {
+        exitCode: 2,
+        stderr: `BLOCKED: Modifying ${basename} is not allowed. ` +
+          'Fix the source code to satisfy linter/formatter rules instead of ' +
+          'weakening the config. If this is a legitimate config change, ' +
+          'disable the config-protection hook temporarily.',
+      };
+    }
+  }
+  const command = input?.tool_input?.command || '';
+  if (command) {
+    const bypass = checkCommandForBypass(command);
+    if (bypass) {
+      return {
+        exitCode: 2,
+        stderr: `BLOCKED: "${bypass}" bypasses git verification hooks. ` +
+          'Verification hooks enforce project quality gates and must not be opted out. ' +
+          'Fix the failing check instead of skipping it. ' +
+          'If the hook is genuinely misconfigured, correct the hook configuration directly.',
+      };
+    }
   }
-
   return { exitCode: 0 };
 }
 
-module.exports = { run };
+module.exports = { run, tokenize, splitSegments, checkCommandForBypass };
 
 // Stdin fallback for spawnSync execution
 if (require.main === module) {

package/src/cli/flow-kit.ts

@@ -1,9 +1,12 @@
+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 } from "../flow-kit/validate.js";
+import { assertKitRepository, deriveKitTargets } from "../flow-kit/validate.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 
 const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
@@ -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);
@@ -132,14 +149,154 @@ function activate(argv: string[]): number {
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
 
+/**
+ * inspect <kit-dir> [--json]
+ *
+ * Derives conformance level (K0/K1/K2) and consumer targets from a kit's
+ * observable asset classes. Exits 1 if the kit fails core container validation.
+ * Outputs stable JSON suitable for use by catalog tooling and CI.
+ *
+ * K-levels (issue #52):
+ *   K0  valid core Flow Kit container — gates evaluable agentlessly by any Flow consumer.
+ *   K1  K0 + Flow Agents extension assets present (skills/docs/adapters/evals/assets).
+ *   K2  K1 + evals present (live evidence layer).
+ *
+ * Consumer targets derived from observable asset classes:
+ *   flow          always present at K0 (any Flow consumer: gates/definition-of-done)
+ *   flow-agents   present at K1+ (Flow Agents extension activated)
+ *   <namespace>   unknown top-level keys list verbatim as third-party consumer targets
+ */
+function inspect(argv: string[]): number {
+  const args = parseArgs(argv);
+  const kitDir = path.resolve(args.positionals[0] ?? ".");
+  const manifestPath = path.join(kitDir, "kit.json");
+  if (!fs.existsSync(manifestPath)) {
+    console.error(`inspect: kit.json not found at ${manifestPath}`);
+    return 1;
+  }
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+  } catch (err) {
+    console.error(`inspect: invalid JSON in ${manifestPath}: ${(err as Error).message}`);
+    return 1;
+  }
+  const result = deriveKitTargets(manifest);
+  console.log(JSON.stringify(result, null, 2));
+  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);
-  console.error("usage: flow-kit <install-local|list|status|activate> ...");
+  if (command === "inspect") return inspect(rest);
+  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/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(); }