@kontourai/flow-agents 0.4.0 → 1.0.1

package/.github/workflows/kit-gates-demo.yml

@@ -0,0 +1,171 @@
+name: Kit Gates Demo (Agentless)
+
+# Proves that Flow Kit gates can be evaluated over claim files in CI with no
+# agent in the loop. The workflow runs:
+#   flow validate-definition   — validates the Flow Definition in the kit
+#   flow validate-kit          — validates kit.json container (requires
+#                                @kontourai/flow >= 0.1.21; merged in source
+#                                PR #67 but not yet in the published package
+#                                as of 0.1.20 — step is continue-on-error)
+#   flow start                 — creates a Flow run
+#   flow attach-evidence --trust-artifact — attaches a claim file to the gate
+#   flow evaluate --exit-code  — evaluates gate; exits 1 when gate does not pass
+#
+# Two jobs exercise one passing and one failing claim fixture:
+#   pass-case: trusted claim → evaluate exits 0 → job succeeds
+#   fail-case: rejected claim → evaluate exits 1 → workflow asserts the
+#              failure is detected (non-zero exit) rather than silently ignored
+#
+# Triggered on: workflow_dispatch or PR touching kits/release-evidence/** or
+# this workflow file.
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "kits/release-evidence/**"
+      - ".github/workflows/kit-gates-demo.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  pass-case:
+    name: Gate pass — trusted release.evidence claim
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Flow CLI
+        # Mirrors the FLOW_CLI_ROOT install pattern used in ci.yml.
+        run: |
+          mkdir -p .flow-cli
+          cd .flow-cli
+          printf '{"name":"flow-cli-host","private":true}\n' > package.json
+          npm install --no-save @kontourai/flow
+        env:
+          FLOW_CLI_ROOT: ${{ github.workspace }}/.flow-cli/node_modules/@kontourai/flow
+
+      - name: Validate Flow Definition (available in published CLI)
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            validate-definition \
+            kits/release-evidence/flows/release-evidence.flow.json \
+            --json
+
+      - name: Validate kit container (requires @kontourai/flow >= next release after 0.1.20)
+        # validate-kit is merged in kontourai/flow source (PR #67) but not yet
+        # validate-kit ships in @kontourai/flow >= 0.2.0 (published 2026-06-12).
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            validate-kit kits/release-evidence
+
+      - name: Init Flow workspace and start run
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js init
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            start kits/release-evidence/flows/release-evidence.flow.json \
+            --run-id gate-pass-demo
+
+      - name: Attach trusted release.evidence claim
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            attach-evidence gate-pass-demo \
+            --gate release-evidence-gate \
+            --file kits/release-evidence/fixtures/claims/pass-trusted-release.trust.json \
+            --trust-artifact
+
+      - name: Evaluate gate — trusted claim must produce pass and exit 0
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            evaluate gate-pass-demo --exit-code
+
+      - name: Show run status
+        if: always()
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            status gate-pass-demo --format summary
+
+  fail-case:
+    name: Gate fail — rejected claim (failure MUST be detected)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Flow CLI
+        run: |
+          mkdir -p .flow-cli
+          cd .flow-cli
+          printf '{"name":"flow-cli-host","private":true}\n' > package.json
+          npm install --no-save @kontourai/flow
+        env:
+          FLOW_CLI_ROOT: ${{ github.workspace }}/.flow-cli/node_modules/@kontourai/flow
+
+      - name: Validate Flow Definition
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            validate-definition \
+            kits/release-evidence/flows/release-evidence.flow.json \
+            --json
+
+      - name: Validate kit container (requires @kontourai/flow >= next release after 0.1.20)
+        continue-on-error: true
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            validate-kit kits/release-evidence
+
+      - name: Init Flow workspace and start run
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js init
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            start kits/release-evidence/flows/release-evidence.flow.json \
+            --run-id gate-fail-demo
+
+      - name: Attach rejected release.evidence claim
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            attach-evidence gate-fail-demo \
+            --gate release-evidence-gate \
+            --file kits/release-evidence/fixtures/claims/fail-rejected-release.trust.json \
+            --trust-artifact
+
+      - name: Evaluate gate — rejected claim must produce non-pass and exit 1
+        # --exit-code makes the CLI exit 1 when the gate does not pass.
+        # continue-on-error: true captures the outcome without failing the job here.
+        id: evaluate_fail
+        continue-on-error: true
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            evaluate gate-fail-demo --exit-code
+
+      - name: Assert failure was detected (gate must NOT pass a rejected claim)
+        # If evaluate exited 0 (outcome == success), the gate incorrectly
+        # accepted a rejected claim — false negative in gate evaluation.
+        run: |
+          if [ "${{ steps.evaluate_fail.outcome }}" = "success" ]; then
+            echo "ERROR: gate passed a rejected claim — false negative in gate evaluation"
+            exit 1
+          fi
+          echo "PASS: gate correctly did not pass the rejected claim (outcome=${{ steps.evaluate_fail.outcome }})"
+
+      - name: Show run status
+        if: always()
+        run: |
+          node .flow-cli/node_modules/@kontourai/flow/dist/cli.js \
+            status gate-fail-demo --format summary

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [1.0.1](https://github.com/kontourai/flow-agents/compare/v1.0.0...v1.0.1) (2026-06-12)
+
+
+### Fixes
+
+* resolve three kit-distribution blockers ([#55](https://github.com/kontourai/flow-agents/issues/55) [#56](https://github.com/kontourai/flow-agents/issues/56) [#57](https://github.com/kontourai/flow-agents/issues/57)) ([3350cb1](https://github.com/kontourai/flow-agents/commit/3350cb15f44bff92d8d9c57f447761d0e1a1b20c))
+* resolve three kit-distribution blockers ([#55](https://github.com/kontourai/flow-agents/issues/55), [#56](https://github.com/kontourai/flow-agents/issues/56), [#57](https://github.com/kontourai/flow-agents/issues/57)) ([13bf732](https://github.com/kontourai/flow-agents/commit/13bf732ff365efa84423e9ea46042e501d202db8))
+
+## [1.0.0](https://github.com/kontourai/flow-agents/compare/v0.4.0...v1.0.0) (2026-06-12)
+
+
+### Features
+
+* agentless Flow Kit gate evaluation proof (issue [#52](https://github.com/kontourai/flow-agents/issues/52) item 3) ([f7857ec](https://github.com/kontourai/flow-agents/commit/f7857ec8ba69d614b0c3c70548d724f7a97c164a))
+* agentless Flow Kit gate evaluation proof (issue [#52](https://github.com/kontourai/flow-agents/issues/52) item 3) ([86c881f](https://github.com/kontourai/flow-agents/commit/86c881f579a08ab75787cd32e401f83b77952c39))
+* config-protection blocks git hook-skip flags ([#41](https://github.com/kontourai/flow-agents/issues/41)) ([6d9e981](https://github.com/kontourai/flow-agents/commit/6d9e9810b3d4e60fe172ade340e61dbe4053d0c9))
+* K-level conformance, degradation invariant, and consumer-target derivation ([#52](https://github.com/kontourai/flow-agents/issues/52) items 1+2) ([d5c332a](https://github.com/kontourai/flow-agents/commit/d5c332a3f4400eb29e9f8fd4e845ec34cf30ae0b))
+* K-level conformance, degradation invariant, and consumer-target derivation (issue [#52](https://github.com/kontourai/flow-agents/issues/52) items 1+2) ([6ac62eb](https://github.com/kontourai/flow-agents/commit/6ac62eb4cec195baca3d039b398f29e45e5d62de))
+* **knowledge-kit:** obsidian layout — insights at node root, sources nested; dimension frontmatter ([5d6489b](https://github.com/kontourai/flow-agents/commit/5d6489b6dc30eacc3a4d0c51487c1a7d3a004f00))
+* **knowledge-kit:** Obsidian store adapter — file-is-the-record spike ([#43](https://github.com/kontourai/flow-agents/issues/43)) ([83d9ff4](https://github.com/kontourai/flow-agents/commit/83d9ff43c2e1d59ac8d3235ae7250fc43be47725))
+* **knowledge-kit:** Obsidian store adapter spike — file-is-the-record RATIFIED ([#43](https://github.com/kontourai/flow-agents/issues/43)) ([467c8dc](https://github.com/kontourai/flow-agents/commit/467c8dc60180a5f6bf15b30a4f0e29e486803fb8))
+* **knowledge-kit:** person entity cards with backlinks + gated resolution ([#48](https://github.com/kontourai/flow-agents/issues/48)) ([9456cef](https://github.com/kontourai/flow-agents/commit/9456cef3b55c639bd50a9aeaea675bef425ea0be))
+* **knowledge-kit:** person entity cards with backlinks + gated resolution ([#48](https://github.com/kontourai/flow-agents/issues/48)) ([ac5ccb0](https://github.com/kontourai/flow-agents/commit/ac5ccb08e40bb6adadd35ff165a617be29e8d23a))
+
+
+### Fixes
+
+* **entity-extractor:** parse trailing-period last-entry correctly ([76abd87](https://github.com/kontourai/flow-agents/commit/76abd87ce2e6bfa3650c3d20de7309d498a446f8))
+* **entity-extractor:** parse trailing-period last-entry correctly ([#48](https://github.com/kontourai/flow-agents/issues/48)) ([ac64fc1](https://github.com/kontourai/flow-agents/commit/ac64fc1cb3151af9032948ac463337da3eeaf907))
+
+
+### Documentation
+
+* elevate Flow Kits as the authorable-ecosystem pillar ([#45](https://github.com/kontourai/flow-agents/issues/45)) ([fa81820](https://github.com/kontourai/flow-agents/commit/fa8182089c4e3c404e3020c6d516be93353a897b))
+* elevate Flow Kits as the authorable-ecosystem pillar ([#45](https://github.com/kontourai/flow-agents/issues/45)) ([7ffa44e](https://github.com/kontourai/flow-agents/commit/7ffa44ea8be799e709b41d4ac4220948e3819fb8))
+* kit container/extension layering — container contract is Flow-owned ([#50](https://github.com/kontourai/flow-agents/issues/50)) ([33d6ec0](https://github.com/kontourai/flow-agents/commit/33d6ec0bf0fefd9095c19dc76b995ee7dd8079fb))
+* kit container/extension layering — container contract is Flow-owned ([#50](https://github.com/kontourai/flow-agents/issues/50)) ([fd87366](https://github.com/kontourai/flow-agents/commit/fd873663d64e205e1a8c2b898b913a56d410591f))
+
+
+### Maintenance
+
+* cut v1.0.0 ([5f88ac5](https://github.com/kontourai/flow-agents/commit/5f88ac51598fe3f13b16360572ff851b822013a2))
+
 ## [0.4.0](https://github.com/kontourai/flow-agents/compare/v0.3.0...v0.4.0) (2026-06-12)
 
 

package/CONTEXT.md

@@ -75,7 +75,7 @@ A reusable procedure Flow Agents can invoke to carry out part of a work mode. Sk
 
 ### Flow Kit
 
-An installable, authorable bundle of Flow-backed workflows and optional supporting assets, such as Flow Definitions, docs, skills, adapters, provider contracts, and evals. Flow Kits are runtime-neutral: skills are one supported asset type, not a requirement.
+Flow's distribution unit for portable workflow bundles. A Flow Kit has two layers: (1) the **container** (owned by Kontour Flow) — a `kit.json` manifest with `schema_version`, `id`, `name`, and a non-empty `flows` list, plus optional `description` and `product_name`; and (2) the **agent extension** (owned by Flow Agents) — optional `skills`, `docs`, `adapters`, `evals`, and `assets` fields that make it a Flow Agents Kit. The container contract permits unknown top-level fields so consumers can extend it without breaking core validation. A kit with only core container fields is a valid Flow Kit; adding Flow Agents extension fields makes it a Flow Agents Kit.
 _Avoid_: Pack, plugin, marketplace package
 
 ### Flow Kit Repository

package/README.md

@@ -71,6 +71,8 @@ L2 means all four policy classes with blocking; L1 means steering and stop-goal-
 
 ## Install
 
+Requires Node.js 22 or newer.
+
 ```bash
 # guided install into your workspace (auto-detects runtime)
 npx @kontourai/flow-agents init --dest /path/to/workspace
@@ -111,9 +113,15 @@ The [Workflow Usage Guide](docs/workflow-usage-guide.md) has example prompts and
 
 ## Flow Kits
 
-A Flow Kit is a portable workflow bundle: a `kit.json` manifest, one or more Flow Definitions, and optional skills, docs, adapters, evals, and assets — all validated and installed as a unit. Kits are the extension model for Flow Agents: they let you package a workflow once and deploy it into any workspace through the same path as the built-in workflows.
+A Flow Kit bundles a workflow AND its opinionated output shape into a single validated unit: a `kit.json` manifest (schema version 1.0), one or more Flow Definitions, and optional skills, docs, adapters, evals, and assets. Authoring a kit means deciding not just _what_ an agent does but _how the result is rendered_ — the same pipeline produces different representations depending on which store adapter is active. Kits are the extension model for Flow Agents: validated by the `flow-kit` CLI, installed through a single command, and activatable into any workspace that runs Flow Agents.
+
+**Builder Kit** — ships with `builder.shape` (shape a problem into slices and fileable work items) and `builder.build` (pull ready work through design probing, planning, execution, verification, PR readiness, merge readiness, and learning). Installed automatically by `npx @kontourai/flow-agents init`.
+
+**Knowledge Kit** — a Flow Kit for durable, gated knowledge storage. It ships a store contract with four record types (`raw`, `compiled`, `concept`, `snapshot`), five pipeline flows (`ingest`, `compile`, `synthesize`, `consolidate`, `retire`), and a mutation policy of propose→evidence-gate→apply/reject with supersede-not-delete. All mutations require provenance; nothing is silently overwritten or deleted. Ships with 198 tests.
 
-**Builder Kit** is the first Kontour-authored kit. It ships with `builder.shape` (shape a problem into slices and fileable work items) and `builder.build` (pull ready work through design probing, planning, execution, verification, PR readiness, merge readiness, and learning). Builder Kit is installed automatically by `npx @kontourai/flow-agents init`.
+The output-shape story is the core reason kits matter. The Knowledge Kit store contract is representation-neutral: two adapters ship today. The **default adapter** stores records as flat markdown files with YAML frontmatter and a JSON graph index. The **Obsidian adapter** renders the same workflow into the shape a human already thinks in — one canonical note per record, category→folder hierarchy, configurable frontmatter dimensions (e.g. territory/customer/initiative as filterable fields), living overview notes with sources nested below, and superseded records moved to an `archive/` folder rather than deleted. Same flows, same mutation gates, different rendering layer. (The Obsidian adapter is shipped; layout/dimensions refinements and person/entity card support are in development.)
+
+The Knowledge Kit is also LIVE-proven: the default adapter passes the parameterized contract suite; keyless operation is validated via a Strands agent + local ollama acceptance harness; vector similarity clustering uses ollama embeddings (`nomic-embed-text`) with a pluggable detector interface.
 
 Install a local kit:
 
@@ -123,6 +131,9 @@ npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to
 
 - [Kit Authoring Guide](docs/kit-authoring-guide.md) — build your own kit from scratch: directory layout, `kit.json`, a flow file, validation, install, and activation.
 - [Flow Kit Repository Contract](docs/flow-kit-repository-contract.md) — the full validation rules, registry schema, and activation diagnostics.
+- [Knowledge Kit docs](kits/knowledge/docs/README.md) — store contract, record types, mutation ops, similarity detectors, and the Obsidian adapter.
+
+**Direction** (not shipped): domain kits that compose this substrate — a Sales Kit (territory/customer/initiative schema with side-effect adapters for CRM logging), a Research Kit (transcript capture→compile→recall). Distribution follows sequencing: authoring tooling and covetable reference kits first, then a registry, then a marketplace. No marketplace claims are shipped.
 
 ## Framework adapters
 

package/build/src/cli/flow-kit.js

@@ -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");
 const REPOSITORIES_REL = path.join("kits", "local", "repositories");
@@ -27,6 +30,22 @@ function contentHash(root) {
     }
     return `sha256:${hash.digest("hex")}`;
 }
+/** Content hash that excludes .git and other VCS/cache directories (for install-git clones). */
+function kitContentHash(root) {
+    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) {
     const args = parseArgs(argv);
     const source = path.resolve(args.positionals[0] ?? "");
@@ -36,13 +55,11 @@ function installLocal(argv) {
         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.diagnostics ?? [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);
@@ -126,18 +143,170 @@ function activate(argv) {
     console.log(JSON.stringify(result, null, 2));
     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) {
+    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;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch (err) {
+        console.error(`inspect: invalid JSON in ${manifestPath}: ${err.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) {
+    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 = 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.stderr
+                ? err.stderr.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;
+        try {
+            manifest = assertKitRepository(tmpBase);
+        }
+        catch (error) {
+            console.log("Flow Kit repository validation failed:");
+            for (const diagnostic of (error.diagnostics ?? [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 = {
+            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)) {
     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/build/src/cli/validate-source-tree.js

@@ -27,5 +27,22 @@ export function main(argv = process.argv.slice(2)) {
     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).
+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/build/src/flow-kit/validate.js

@@ -2,6 +2,91 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { readJson } from "../lib/fs.js";
 const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+// Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
+// agent-extension fields are skills, docs, adapters, evals, assets.
+const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
+const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
+/**
+ * Validates that the manifest satisfies the core Flow Kit container contract
+ * (as specified by kontourai/flow PR #67) with all agent-extension fields stripped.
+ * Returns a list of violation messages (empty = valid).
+ *
+ * The degradation invariant: every Flow Agents Kit MUST remain a valid core
+ * Flow Kit container when agent-extension fields are ignored.
+ */
+export function validateCoreContainer(manifest, label) {
+    const errors = [];
+    if (manifest.schema_version !== "1.0") {
+        errors.push(`${label}: .schema_version must be "1.0"`);
+    }
+    if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
+        errors.push(`${label}: .id must be a stable kebab-case string`);
+    }
+    if (typeof manifest.name !== "string" || !manifest.name.trim()) {
+        errors.push(`${label}: .name must be a non-empty string`);
+    }
+    if (!Array.isArray(manifest.flows) || manifest.flows.length === 0) {
+        errors.push(`${label}: .flows must be a non-empty list`);
+    }
+    else {
+        manifest.flows.forEach((entry, index) => {
+            if (typeof entry !== "object" || entry === null) {
+                errors.push(`${label}: flows[${index}] must be an object`);
+                return;
+            }
+            const flow = entry;
+            if (typeof flow.id !== "string" || !flow.id) {
+                errors.push(`${label}: flows[${index}].id must be a string`);
+            }
+            if (typeof flow.path !== "string" || !flow.path) {
+                errors.push(`${label}: flows[${index}].path must be a string`);
+            }
+        });
+    }
+    return errors;
+}
+/**
+ * Derives the consumer-target level (K0/K1/K2) and target audience list from
+ * observable asset classes in the kit manifest. Does not require file I/O.
+ *
+ * Derivation rules (from kontourai/flow-agents#52 and Brian's layering review):
+ *  - K0: valid core container (schema_version, id, name, flows non-empty).
+ *  - K1: K0 + any Flow Agents extension field present (skills/docs/adapters/evals/assets).
+ *  - K2: K1 + evals present.
+ *  - targets.flow: always present when K0 (any Flow consumer can evaluate gates).
+ *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
+ *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
+ */
+export function deriveKitTargets(manifest) {
+    const kitId = typeof manifest.id === "string" ? manifest.id : "<unknown>";
+    const kitName = typeof manifest.name === "string" ? manifest.name : "<unknown>";
+    const coreErrors = validateCoreContainer(manifest, "kit.json");
+    const k0 = coreErrors.length === 0;
+    const hasAgentExtension = AGENT_EXTENSION_CLASSES.size > 0 &&
+        [...AGENT_EXTENSION_CLASSES].some((cls) => Array.isArray(manifest[cls]) && manifest[cls].length > 0);
+    const hasEvals = Array.isArray(manifest["evals"]) && manifest["evals"].length > 0;
+    const k1 = k0 && hasAgentExtension;
+    const k2 = k1 && hasEvals;
+    // Detect third-party extension namespaces: top-level keys that are neither
+    // core fields nor Flow Agents extension classes.
+    const thirdPartyExtensions = Object.keys(manifest)
+        .filter((key) => !CORE_CONTAINER_FIELDS.has(key) && !AGENT_EXTENSION_CLASSES.has(key))
+        .sort();
+    const targets = [];
+    if (k0)
+        targets.push("flow");
+    if (k1)
+        targets.push("flow-agents");
+    for (const ns of thirdPartyExtensions)
+        targets.push(ns);
+    return {
+        kit_id: kitId,
+        kit_name: kitName,
+        conformance: { k0, k1, k2 },
+        targets,
+        third_party_extensions: thirdPartyExtensions,
+    };
+}
 export function validateKitRepository(kitDir) {
     const errors = [];
     const manifestPath = path.join(kitDir, "kit.json");
@@ -20,6 +105,19 @@ export function validateKitRepository(kitDir) {
     }
     if (typeof manifest.name !== "string" || !manifest.name.trim())
         errors.push(`${manifestPath}: .name must be a non-empty string`);
+    // Degradation invariant: every Flow Agents Kit must remain a valid core Flow Kit container
+    // when agent-extension fields are stripped. Strip extensions and re-validate core contract.
+    const coreManifest = {};
+    for (const key of Object.keys(manifest)) {
+        if (CORE_CONTAINER_FIELDS.has(key))
+            coreManifest[key] = manifest[key];
+    }
+    const coreErrors = validateCoreContainer(coreManifest, manifestPath);
+    for (const err of coreErrors) {
+        // Deduplicate: only add if not already covered by top-level checks above.
+        if (!errors.some((existing) => existing === err))
+            errors.push(err);
+    }
     for (const section of ASSET_CLASSES) {
         const entries = manifest[section];
         if (entries === undefined)

package/build/src/runtime-adapters.js

@@ -74,7 +74,7 @@ export function readKitInventory(sourceRoot, dest) {
     const assets = [];
     const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
     if (!fs.existsSync(catalogPath))
-        errors.push(`${catalogPath}: missing Kit Catalog`);
+        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);
         const kits = catalog.kits;