@kontourai/flow-agents 1.1.0 → 1.2.0

package/.github/workflows/runtime-compat.yml

@@ -40,7 +40,7 @@ jobs:
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
 
@@ -49,6 +49,9 @@ jobs:
           ${{ matrix.install }}
           ${{ matrix.version }}
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Build bundles
         run: npm run build:bundles
 
@@ -67,7 +70,7 @@ jobs:
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
 

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.2.0](https://github.com/kontourai/flow-agents/compare/v1.1.0...v1.2.0) (2026-06-15)
+
+
+### Features
+
+* **#62:** move Builder Kit skills into kits/builder, add Knowledge Kit skill, remove orphans ([3822e07](https://github.com/kontourai/flow-agents/commit/3822e075e9cd488f46124179ebf9a8459825b9c6))
+* **#62:** move Builder Kit skills into kits/builder, Knowledge Kit skill, remove orphans ([31f63ca](https://github.com/kontourai/flow-agents/commit/31f63ca18019d51438accd3b5f1e03cb5f2873f2))
+* delegate container validation to @kontourai/flow; rename flow-kit → flow-agents kit ([d39e909](https://github.com/kontourai/flow-agents/commit/d39e9090dad220a8159d2148d5a1effb2460ac9f))
+* delegate container validation to @kontourai/flow; rename flow-kit → flow-agents kit (ADR 0008) ([4343e84](https://github.com/kontourai/flow-agents/commit/4343e845a992858c9441258bedbbf3c7302a8532))
+
+
+### Fixes
+
+* **ci:** install repo deps before building bundles in runtime-compat canary ([#76](https://github.com/kontourai/flow-agents/issues/76)) ([f8947aa](https://github.com/kontourai/flow-agents/commit/f8947aab5723ba9325372ea4054458ce21875bee))
+* lazy-load @kontourai/flow in validate.ts so list/status/activate work without it ([99beebb](https://github.com/kontourai/flow-agents/commit/99beebb58f02dba374b35ae5e3df229cb39ea8d0))
+
+
+### Documentation
+
+* add ADR 0007 flow/skill/kit/tool boundary + skill audit ([20b5c7b](https://github.com/kontourai/flow-agents/commit/20b5c7b272e7ad7985640e70b6be71733cec9995))
+* add Builder Kit quick-start guide and update index/README Quick Start ([2e89bf0](https://github.com/kontourai/flow-agents/commit/2e89bf08968a6f45a26ceddcddf5a66bf77d3f44))
+* ADR 0007 flow/skill/kit/tool boundary + skill audit ([a1dde52](https://github.com/kontourai/flow-agents/commit/a1dde52eb3b051a0eab5712395f0266c7428ae0f))
+* Builder Kit quick-start guide (zero to gated build flow) ([83237f7](https://github.com/kontourai/flow-agents/commit/83237f77812917d49c86547db87986d6dbfdbfd9))
+* fold orphan rulings into ADR 0007, add ADR 0008 kit-operation boundary ([d547edc](https://github.com/kontourai/flow-agents/commit/d547edc954ea9d9a12039003d41401802f994097))
+* mark ADRs 0007 + 0008 Accepted (decisions reached in 2026-06-15 design conversation) ([3eb7636](https://github.com/kontourai/flow-agents/commit/3eb7636c1c4f866fd119195936ec856425573dda))
+
 ## [1.1.0](https://github.com/kontourai/flow-agents/compare/v1.0.1...v1.1.0) (2026-06-15)
 
 

package/README.md

@@ -99,21 +99,42 @@ bash install.sh /path/to/workspace --telemetry-sink local-kontour-console
 
 ## Use it
 
-After installing, ask the agent for the workflow you want — in plain language:
+After installing, ask the agent for the workflow you want — in plain language.
+
+### Builder Kit quick start
+
+The Builder Kit installs automatically and gives your agent two gated flows: `builder.shape` turns a raw idea into slices and executable work items; `builder.build` takes a selected work item through design probe, planning, execution, verification, PR readiness, merge readiness, and learning.
+
+Shape an idea:
+
+```text
+Use Builder Kit shape. I want to add a progress indicator to the CLI output
+so users can see what step the installer is on. Shape this into an executable
+work item and stop at the backlog gate.
+```
+
+Build it:
 
 ```text
-Use Builder Kit shape for this feature idea and create executable GitHub issues.
+Use deliver for the issue you just filed. Pull it, probe the design, plan it,
+implement it, verify it, and stop if any evidence is missing.
 ```
 
+Each step has an evidence gate. The agent either presents the expected evidence and advances, or blocks and explains what is missing — it does not produce a confident summary and proceed on partial work. Session state is written to `.flow-agents/<slug>/` and survives context loss or compaction.
+
+For a full walkthrough — what each gate checks, what you observe, and how to invoke individual skills — read the [Builder Kit Quick Start](docs/getting-started.md).
+
+For bugs:
+
 ```text
-Use deliver for this issue. Plan it, execute it, verify it, and stop if evidence is missing.
+Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and verify the regression path.
 ```
 
 The [Workflow Usage Guide](docs/workflow-usage-guide.md) has example prompts and expected behavior for every stage — `pull-work`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, `fix-bug`, `release-readiness`, and more. The [Agent System Guidebook](docs/agent-system-guidebook.md) is the plain-language map of how the pieces fit.
 
 ## Flow Kits
 
-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.
+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 and installed through the `flow-agents kit` CLI, 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`.
 
@@ -126,7 +147,7 @@ The Knowledge Kit is also LIVE-proven: the default adapter passes the parameteri
 Install a local kit:
 
 ```bash
-npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace
+npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace
 ```
 
 - [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.

package/build/src/cli/{flow-kit.js → kit.js}

@@ -30,7 +30,7 @@ function contentHash(root) {
     }
     return `sha256:${hash.digest("hex")}`;
 }
-/** Content hash that excludes .git and other VCS/cache directories (for install-git clones). */
+/** 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");
@@ -46,13 +46,37 @@ function kitContentHash(root) {
     }
     return `sha256:${hash.digest("hex")}`;
 }
-function installLocal(argv) {
+/**
+ * install <source> [--dest <path>] [--force] [--update] [--ref <branch|tag|sha>]
+ *
+ * Installs a Flow Kit from a local path or a git URL.
+ *
+ * - Local path: validates then copies the kit into the destination registry.
+ * - Git URL (http://, https://, git+, ssh://, file://): shallow-clones the repository,
+ *   validates the kit container with @kontourai/flow, then delegates to the install path.
+ *   Supports an optional #ref fragment in the URL or a separate --ref flag.
+ */
+async function install(argv) {
+    const args = parseArgs(argv);
+    const source = args.positionals[0] ?? "";
+    if (!source) {
+        console.error("install: missing <source> argument");
+        console.error("usage: flow-agents kit install <path-or-git-url> [--dest <path>] [--ref <ref>] [--force] [--update]");
+        return 2;
+    }
+    // Detect git URL: starts with http(s)://, git+, ssh://, file://, or ends with .git
+    const isGitUrl = /^(https?:\/\/|git\+|ssh:\/\/|file:\/\/)/.test(source) || source.endsWith(".git");
+    if (isGitUrl) {
+        return await installGitSource(source, argv);
+    }
+    return await installLocalSource(path.resolve(source), argv);
+}
+async function installLocalSource(source, argv) {
     const args = parseArgs(argv);
-    const source = path.resolve(args.positionals[0] ?? "");
     const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
     let manifest;
     try {
-        manifest = assertKitRepository(source);
+        manifest = await assertKitRepository(source);
     }
     catch (error) {
         console.log("Flow Kit repository validation failed:");
@@ -91,6 +115,86 @@ function installLocal(argv) {
     console.log(`${existing ? "updated" : "installed"} local kit '${kitId}' at ${target}`);
     return 0;
 }
+async function installGitSource(rawUrl, argv) {
+    const args = parseArgs(argv);
+    // 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 clone failed: ${msg}`);
+            return 1;
+        }
+        // Validate the cloned kit using the same logic as install local.
+        let manifest;
+        try {
+            manifest = await 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 });
+    }
+}
 function list(argv) {
     const args = parseArgs(argv);
     const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
@@ -147,7 +251,8 @@ function activate(argv) {
  * 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.
+ * observable asset classes. Delegates core container validation to @kontourai/flow.
+ * Exits 1 if the kit fails core container validation.
  * Outputs stable JSON suitable for use by catalog tooling and CI.
  *
  * K-levels (issue #52):
@@ -160,7 +265,7 @@ function activate(argv) {
  *   flow-agents   present at K1+ (Flow Agents extension activated)
  *   <namespace>   unknown top-level keys list verbatim as third-party consumer targets
  */
-function inspect(argv) {
+async function inspect(argv) {
     const args = parseArgs(argv);
     const kitDir = path.resolve(args.positionals[0] ?? ".");
     const manifestPath = path.join(kitDir, "kit.json");
@@ -176,111 +281,20 @@ function inspect(argv) {
         console.error(`inspect: invalid JSON in ${manifestPath}: ${err.message}`);
         return 1;
     }
-    const result = deriveKitTargets(manifest);
+    // Pass the real kitDir so @kontourai/flow can validate flow file existence for K0.
+    const result = await deriveKitTargets(manifest, kitDir);
     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)) {
+export async function main(argv = process.argv.slice(2)) {
     const [command, ...rest] = argv;
+    if (command === "install")
+        return await install(rest);
+    // Legacy sub-subcommands forwarded for backward compatibility within the kit subcommand.
     if (command === "install-local")
-        return installLocal(rest);
+        return await installLocalSource(path.resolve(rest[0] ?? ""), rest);
     if (command === "install-git")
-        return installGit(rest);
+        return await installGitSource(rest[0] ?? "", rest);
     if (command === "list")
         return list(rest);
     if (command === "status")
@@ -288,8 +302,8 @@ export function main(argv = process.argv.slice(2)) {
     if (command === "activate")
         return activate(rest);
     if (command === "inspect")
-        return inspect(rest);
-    console.error("usage: flow-kit <install-local|install-git|list|status|activate|inspect> ...");
+        return await inspect(rest);
+    console.error("usage: flow-agents kit <install|activate|inspect|list|status> ...");
     return 2;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
@@ -308,5 +322,5 @@ catch {
     return process.argv[1];
 } })();
 if (_selfRealPath === _argv1RealPath) {
-    process.exitCode = main();
+    main().then((code) => { process.exitCode = code; }).catch((err) => { console.error(err); process.exitCode = 1; });
 }

package/build/src/cli/validate-source-tree.js

@@ -1,11 +1,11 @@
 import * as path from "node:path";
 import { parseArgs } from "../lib/args.js";
 import { validateKitRepository } from "../flow-kit/validate.js";
-export function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2)) {
     const args = parseArgs(argv);
     const kit = args.flags.kit;
     if (typeof kit === "string") {
-        const errors = validateKitRepository(path.resolve(kit));
+        const errors = await validateKitRepository(path.resolve(kit));
         if (errors.length) {
             console.log("Flow Kit repository validation failed:");
             for (const error of errors)
@@ -17,7 +17,7 @@ export function main(argv = process.argv.slice(2)) {
     }
     const root = path.resolve(".");
     const builder = path.join(root, "kits", "builder");
-    const errors = validateKitRepository(builder);
+    const errors = await validateKitRepository(builder);
     if (errors.length) {
         console.log("Source tree validation failed:");
         for (const error of errors)
@@ -44,5 +44,5 @@ catch {
     return process.argv[1];
 } })();
 if (_selfVST === _argv1VST) {
-    process.exitCode = main();
+    main().then((code) => { process.exitCode = code; }).catch((err) => { console.error(err); process.exitCode = 1; });
 }

package/build/src/cli.js

@@ -2,7 +2,7 @@
 import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
-import { main as flowKit } from "./cli/flow-kit.js";
+import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
 import { main as init } from "./cli/init.js";
 import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
@@ -27,7 +27,7 @@ const availableCommands = new Map([
     ["effective-backlog-settings", effectiveBacklogSettings],
     ["filter-installed-packs", filterInstalledPacks],
     ["fixture-retirement-audit", fixtureRetirementAudit],
-    ["flow-kit", flowKit],
+    ["kit", kit],
     ["init", init],
     ["promote-workflow-artifact", promoteWorkflowArtifact],
     ["publish-change", publishChange],
@@ -49,7 +49,7 @@ const aliases = new Map([
     ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
     ["flow-agents-filter-installed-packs", "filter-installed-packs"],
     ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
-    ["flow-agents-flow-kit", "flow-kit"],
+    ["flow-agents-kit", "kit"],
     ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
     ["flow-agents-publish-change", "publish-change"],
     ["flow-agents-pull-work-provider", "pull-work-provider"],

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

@@ -1,49 +1,52 @@
 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"];
+// Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
+const EXTENSION_ASSET_CLASSES = ["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"]);
+let _validateKitContainerCache = null;
+async function loadValidateKitContainer() {
+    if (_validateKitContainerCache)
+        return _validateKitContainerCache;
+    let mod;
+    try {
+        mod = await import("@kontourai/flow");
+    }
+    catch (err) {
+        throw new Error("container validation requires @kontourai/flow; run from an npm-installed flow-agents workspace " +
+            `or use 'flow kit validate' (original error: ${err.message})`);
+    }
+    if (typeof mod.validateKitContainer !== "function") {
+        throw new Error("@kontourai/flow did not export validateKitContainer");
+    }
+    _validateKitContainerCache = mod.validateKitContainer;
+    return _validateKitContainerCache;
+}
 /**
- * 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).
+ * Delegates core Flow Kit container validation to @kontourai/flow's validateKitContainer.
+ * The container contract lives once, in Flow. 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.
+ *
+ * Loads @kontourai/flow lazily (on first call) so that runtime ops (list/status/activate)
+ * that never invoke validation can run in standalone installed bundles where
+ * @kontourai/flow is not present.
+ *
+ * @param kitDir  Real kit directory path for file-existence checks on flows[].path entries.
+ *                Pass the actual kit directory when available; pass "" for structural-only checks.
  */
-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;
+async function delegateCoreContainerValidation(kitDir, manifest) {
+    const validateKitContainer = await loadValidateKitContainer();
+    const result = validateKitContainer(kitDir, manifest);
+    if (result.valid)
+        return [];
+    return result.diagnostics
+        .filter((d) => d.severity === "error")
+        .map((d) => `${d.path}: ${d.message}`);
 }
 /**
  * Derives the consumer-target level (K0/K1/K2) and target audience list from
@@ -56,11 +59,16 @@ export function validateCoreContainer(manifest, label) {
  *  - 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.
+ *
+ * @param manifest  The kit.json manifest object.
+ * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
+ *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
  */
-export function deriveKitTargets(manifest) {
+export async function deriveKitTargets(manifest, kitDir = "") {
     const kitId = typeof manifest.id === "string" ? manifest.id : "<unknown>";
     const kitName = typeof manifest.name === "string" ? manifest.name : "<unknown>";
-    const coreErrors = validateCoreContainer(manifest, "kit.json");
+    // Delegate core container validation to @kontourai/flow.
+    const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
     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);
@@ -87,7 +95,7 @@ export function deriveKitTargets(manifest) {
         third_party_extensions: thirdPartyExtensions,
     };
 }
-export function validateKitRepository(kitDir) {
+export async function validateKitRepository(kitDir) {
     const errors = [];
     const manifestPath = path.join(kitDir, "kit.json");
     let manifest;
@@ -98,27 +106,16 @@ export function validateKitRepository(kitDir) {
         errors.push(`${manifestPath}: invalid JSON: ${error.message}`);
         return errors;
     }
-    if (manifest.schema_version !== "1.0")
-        errors.push(`${manifestPath}: .schema_version must be "1.0"`);
-    if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
-        errors.push(`${manifestPath}: .id must be a stable kebab-case string`);
-    }
-    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) {
+    // Delegate core container validation (schema_version, id, name, flows including file
+    // existence) to @kontourai/flow — the container contract lives once, in Flow.
+    // This enforces the degradation invariant: a Flow Agents Kit must remain a valid
+    // core Flow Kit container when extension fields are stripped.
+    const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
+    for (const err of coreErrors)
+        errors.push(err);
+    // Flow Agents extension validation: skills, docs, adapters, evals, assets.
+    // Flows are validated above by @kontourai/flow; only extension classes are checked here.
+    for (const section of EXTENSION_ASSET_CLASSES) {
         const entries = manifest[section];
         if (entries === undefined)
             continue;
@@ -155,15 +152,14 @@ export function validateKitRepository(kitDir) {
                 return;
             }
             if (!fs.existsSync(resolved)) {
-                const noun = section === "flows" ? "Flow Definition" : "asset";
-                errors.push(`${manifestPath}: ${section}[${index}].path points at missing ${noun}: ${rel}`);
+                errors.push(`${manifestPath}: ${section}[${index}].path points at missing asset: ${rel}`);
             }
         });
     }
     return errors;
 }
-export function assertKitRepository(kitDir) {
-    const errors = validateKitRepository(kitDir);
+export async function assertKitRepository(kitDir) {
+    const errors = await validateKitRepository(kitDir);
     if (errors.length) {
         const error = new Error("Flow Kit repository validation failed");
         error.diagnostics = errors;