@kontourai/flow-agents 1.0.1 → 1.2.0

package/.github/workflows/ci.yml

@@ -196,6 +196,55 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check bundle-install-integration
 
+      - name: Bundle lifecycle integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check bundle-lifecycle-integration
+
+      - name: Activate npx context integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check activate-npx-context-integration
+
+      - name: Kit conformance levels integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check kit-conformance-levels-integration
+
+      - name: Local Flow Kit install integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check local-flow-kit-install-integration
+
+      - name: Flow Kit install-git integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check flow-kit-install-git-integration
+
+
+      - name: Context map integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check context-map-integration
+
+      - name: Effective backlog settings integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check effective-backlog-settings-integration
+
+      - name: Flow agents statusline integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check flow-agents-statusline-integration
+
+      - name: Telemetry contract integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-contract-integration
+
+      - name: Telemetry doctor integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-doctor-integration
+
+      - name: Utterance check integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check utterance-check-integration
+
+      - name: Pull work provider integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check pull-work-provider-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize
@@ -208,3 +257,64 @@ jobs:
           path: evals/results/ci-baseline/runtime-and-kit/
           if-no-files-found: warn
           retention-days: 14
+
+  usage-feedback:
+    name: Usage Feedback
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      FLOW_AGENTS_CI_LANE: usage-feedback
+      FLOW_AGENTS_CI_RESULTS_DIR: evals/results/ci-baseline/usage-feedback
+
+    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 Node dependencies
+        run: npm ci
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Initialize CI evidence
+        run: bash evals/ci/run-baseline.sh --init
+
+      - name: Usage feedback import integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-import-integration
+
+      - name: Usage feedback outcomes integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-outcomes-integration
+
+      - name: Usage feedback report integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-report-integration
+
+      - name: Usage feedback dashboard integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-dashboard-integration
+
+      - name: Usage feedback global integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-global-integration
+
+      - name: Finalize CI evidence
+        if: always()
+        run: bash evals/ci/run-baseline.sh --finalize
+
+      - name: Upload CI evidence artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flow-agents-ci-usage-feedback
+          path: evals/results/ci-baseline/usage-feedback/
+          if-no-files-found: warn
+          retention-days: 14

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,47 @@
 # 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)
+
+
+### Features
+
+* activate skills and docs in kit runtime adapters (fix [#58](https://github.com/kontourai/flow-agents/issues/58)) ([dc726fd](https://github.com/kontourai/flow-agents/commit/dc726fd1d56e79b5bda577985aa87befe3a1eb9d))
+* activate skills and docs in kit runtime adapters (fix [#58](https://github.com/kontourai/flow-agents/issues/58)) ([dc774e0](https://github.com/kontourai/flow-agents/commit/dc774e001b54f7a09f6ab81a6aafcf2ad8552b6d))
+
+
+### Fixes
+
+* apply realpathSync entry-guard to 7 remaining CLI/tool files ([c1b3272](https://github.com/kontourai/flow-agents/commit/c1b3272c623055662a63c5d11c6dbef5aabe1cf0))
+* apply realpathSync entry-guard to all 16 affected CLI/tool files (closes [#71](https://github.com/kontourai/flow-agents/issues/71)) ([8a676b0](https://github.com/kontourai/flow-agents/commit/8a676b0c9c91464d64755719ff778a13e298beb9))
+* apply realpathSync entry-guard to remaining 10 CLI/tool files ([159bb78](https://github.com/kontourai/flow-agents/commit/159bb785b6b28f99b0a3a5c95e0d4428512f4314))
+* use hosted console io preset ([5b4bb7b](https://github.com/kontourai/flow-agents/commit/5b4bb7bc86d154bcf4d529a62e398a2196b702cc))
+
 ## [1.0.1](https://github.com/kontourai/flow-agents/compare/v1.0.0...v1.0.1) (2026-06-12)
 
 

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/console-learning-projection.js

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

package/build/src/cli/effective-backlog-settings.js

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

package/build/src/cli/fixture-retirement-audit.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 const root = path.resolve(".");
 const fixtureRoot = "evals/fixtures";
@@ -136,5 +137,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/init.js

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

package/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; });
 }