@kontourai/flow-agents 0.2.0 → 0.3.0

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

@@ -72,7 +72,7 @@ jobs:
           node-version: 24
 
       - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.12"
 

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.3.0](https://github.com/kontourai/flow-agents/compare/v0.2.0...v0.3.0) (2026-06-12)
+
+
+### Features
+
+* **knowledge-kit:** concept synthesis with evidence-gated mutations (S3, [#34](https://github.com/kontourai/flow-agents/issues/34)) ([f307165](https://github.com/kontourai/flow-agents/commit/f30716503b22202d8929876b3e0b5d0d4bcbd2cb))
+* **knowledge-kit:** decision-snapshot consolidation, supersede-not-delete (S6, [#36](https://github.com/kontourai/flow-agents/issues/36)) ([7211605](https://github.com/kontourai/flow-agents/commit/7211605fd19a0a332b7816c1fb0e66259771c3ba))
+* **knowledge-kit:** ingest/classify + compile flows with provenance gates (S2, [#33](https://github.com/kontourai/flow-agents/issues/33)) ([07dffd5](https://github.com/kontourai/flow-agents/commit/07dffd5f6c6ab8555fc8c7e029d6432cd854dd05))
+* **knowledge-kit:** keyless live example + acceptance harness (S5, [#35](https://github.com/kontourai/flow-agents/issues/35)) ([9a565aa](https://github.com/kontourai/flow-agents/commit/9a565aaa8deac236f07b63933bb8ce6887ac25f9))
+* **knowledge-kit:** store contract + default reference adapter (S1, [#31](https://github.com/kontourai/flow-agents/issues/31)) ([4ed06ba](https://github.com/kontourai/flow-agents/commit/4ed06ba7cad7865094feddf0bd5ac7f76639b9ed))
+* strands-local kit activation — framework-path kits (S4, [#32](https://github.com/kontourai/flow-agents/issues/32)) ([8dc05ec](https://github.com/kontourai/flow-agents/commit/8dc05ecf810dc3d205046c4773aa2c1e62159acb))
+
+
+### Fixes
+
+* dedup pi session.start; document opencode run-mode session.created gap ([4d7e5b1](https://github.com/kontourai/flow-agents/commit/4d7e5b1e2de6573b824852598b04a5da3485adf6))
+* telemetry-doctor reported the workspace parent as the local sink dir ([e15d7b2](https://github.com/kontourai/flow-agents/commit/e15d7b2e922225e4c30a39fceea304ca01e5ac17))
+
+
+### Documentation
+
+* Flow Kits authoring guide, README kits section, npx command forms ([a89a86c](https://github.com/kontourai/flow-agents/commit/a89a86cc488abb7f6cd3cd300a67044174afa154))
+
 ## [0.2.0](https://github.com/kontourai/flow-agents/compare/v0.1.2...v0.2.0) (2026-06-11)
 
 

package/README.md

@@ -45,17 +45,29 @@ The spec defines three conformance levels: **L0** (telemetry only), **L1** (stee
 
 ## Runtime and support matrix
 
-| Tier | Runtime | Ships | Tested | Conformance |
-| --- | --- | --- | --- | --- |
-| **Core harness** | Claude Code | install + hooks + bundle | 77 integration + 36 static assertions | L2 — reference implementation |
-| **Core harness** | Codex | install + hooks + bundle | 77 integration + 36 static assertions | L2 — reference implementation |
-| **Core harness** | Kiro | install + hooks + bundle | included in bundle assertions | L2 |
-| **Core harness** | opencode | `.opencode/agents/`, `.opencode/skills/`, `.opencode/plugins/flow-agents.js`, `opencode.json` | included in bundle assertions | L1 — no prompt-submit hook; steering wired to `session.created` + `tool.execute.before` |
-| **Core harness** | pi | `.pi/extensions/flow-agents.ts`, `.pi/skills/`, `AGENTS.md` | included in bundle assertions | L1 — no stop hook; stop-goal-fit unavailable |
-| **Official framework adapter** | AWS Strands (Python) | `integrations/strands/` — `flow-agents-strands` PyPI package | 50 unit tests (no Strands SDK required) | Spike/preview — see [integrations/strands/README.md](integrations/strands/README.md) |
-| **Conformance-certified** | Community / third-party | Self-certify using the conformance kit | — | Conformance kit in development; not yet shipped |
-
-Honest gaps are documented in the artifacts: opencode has no native `prompt.submit`-equivalent event; Codex live hook influence is limited to installed-command and protocol coverage; pi has no `permissionRequest` equivalent and no stop hook. The [Runtime Hook Surface spec](docs/spec/runtime-hook-surface.md) names every gap explicitly.
+L2 means all four policy classes with blocking; L1 means steering and stop-goal-fit warning only (no quality gate or blocking config protection). The [Runtime Hook Surface spec](docs/spec/runtime-hook-surface.md) defines the levels and names every hook-surface gap explicitly.
+
+**Full support — L2 (all four policies, blocking)**
+
+| Runtime | Ships | Tested |
+| --- | --- | --- |
+| Claude Code | install + hooks + bundle | 77 integration + 36 static assertions — reference implementation |
+| Codex | install + hooks + bundle | 77 integration + 36 static assertions — reference implementation |
+| Kiro | install + hooks + bundle | included in bundle assertions |
+
+**Partial support — L1 (steering + stop-goal-fit warning)**
+
+| Runtime | Ships | Gap | Tested |
+| --- | --- | --- | --- |
+| opencode | `.opencode/agents/`, `.opencode/skills/`, `.opencode/plugins/flow-agents.js`, `opencode.json` | No prompt-submit hook; steering wired to `session.created` + `tool.execute.before` | included in bundle assertions |
+| pi | `.pi/extensions/flow-agents.ts`, `.pi/skills/`, `AGENTS.md` | No stop hook; stop-goal-fit unavailable | included in bundle assertions |
+
+**Other**
+
+| Tier | Runtime | Ships | Tested |
+| --- | --- | --- | --- |
+| Official framework adapter | AWS Strands (Python) | `integrations/strands/` — `flow-agents-strands` PyPI package | 50 unit tests (no Strands SDK required) — spike/preview, see [integrations/strands/README.md](integrations/strands/README.md) |
+| Conformance-certified | Community / third-party | Self-certify using the conformance kit | Conformance kit in development; not yet shipped |
 
 ## Install
 
@@ -77,7 +89,7 @@ Working from a checkout (for contributors): `npm install && npm run build`, then
 
 The installer copies the bundled agents, skills, context, scripts, evals, Flow Kit assets, and the Flow Agents-owned `console.telemetry.json` descriptor into the target workspace. Telemetry writes to local files by default; optional sinks mirror it to a local, hosted, or self-hosted Kontour Console (`--telemetry-sink local-kontour-console | kontour-hosted-console | user-hosted-console --console-url …`).
 
-The low-level bundle installer remains available when you already have a generated bundle checkout:
+`bash install.sh` is the low-level option for CI pipelines or scripts that already have a generated bundle checkout (e.g. from a pinned `git clone` of this repo). Prefer `npx @kontourai/flow-agents init` for normal workspace setup — it fetches the latest published bundle and auto-detects the runtime:
 
 ```bash
 bash install.sh /path/to/workspace --telemetry-sink local-kontour-console
@@ -91,19 +103,26 @@ After installing, ask the agent for the workflow you want — in plain language:
 Use Builder Kit shape for this feature idea and create executable GitHub issues.
 ```
 
-```text
-Use pull-work, select the next ready issue, and hand it to plan-work.
-```
-
 ```text
 Use deliver for this issue. Plan it, execute it, verify it, and stop if evidence is missing.
 ```
 
-```text
-Use fix-bug. Reproduce the issue, diagnose root cause, plan the fix, implement it, 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 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.
+
+**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`.
+
+Install a local kit:
+
+```bash
+npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace
 ```
 
-The [Workflow Usage Guide](docs/workflow-usage-guide.md) walks every stage with example prompts and expected behavior; the [Agent System Guidebook](docs/agent-system-guidebook.md) is the plain-language map of how the pieces fit.
+- [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.
 
 ## Framework adapters
 

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

@@ -4,7 +4,7 @@ import * as path from "node:path";
 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 { activateCodexLocal } from "../runtime-adapters.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");
 function registryPath(dest) { return path.join(dest, REGISTRY_REL); }
@@ -108,16 +108,21 @@ function status(argv) {
     }
     return 0;
 }
+// Available adapters for the activate subcommand (Issue #32: added strands-local).
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 function activate(argv) {
     const args = parseArgs(argv);
     const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
     const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
     const adapter = flagString(args.flags, "adapter");
-    if (adapter && adapter !== "codex-local") {
-        console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+    if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+        console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
         return 2;
     }
-    const result = activateCodexLocal(sourceRoot, dest);
+    // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+    const result = adapter === "strands-local"
+        ? activateStrandsLocal(sourceRoot, dest)
+        : activateCodexLocal(sourceRoot, dest);
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/build/src/cli/runtime-adapter.js

@@ -1,21 +1,25 @@
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
-import { activateCodexLocal } from "../runtime-adapters.js";
+import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 export function main(argv = process.argv.slice(2)) {
     const [command, ...rest] = argv;
     if (command !== "activate") {
-        console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local]");
+        console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local|strands-local]");
         return 2;
     }
     const args = parseArgs(rest);
     const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
     const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
     const adapter = flagString(args.flags, "adapter");
-    if (adapter && adapter !== "codex-local") {
-        console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+    if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+        console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
         return 2;
     }
-    const result = activateCodexLocal(sourceRoot, dest);
+    // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+    const result = adapter === "strands-local"
+        ? activateStrandsLocal(sourceRoot, dest)
+        : activateCodexLocal(sourceRoot, dest);
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/build/src/cli/telemetry-doctor.js

@@ -46,7 +46,10 @@ function channelConfigValue(config, channel, key, fallback = "") {
 }
 function telemetryDataDir(dest) {
     const configured = process.env.TELEMETRY_DATA_DIR;
-    return configured ? path.resolve(dest, configured) : path.resolve(dest, "..", ".telemetry");
+    // Must mirror scripts/telemetry/lib/config.sh: the sink lives INSIDE the
+    // workspace at <dest>/.telemetry. The previous "../.telemetry" duplicated
+    // the parent-escape bug fixed in config.sh on 2026-06-11.
+    return configured ? path.resolve(dest, configured) : path.resolve(dest, ".telemetry");
 }
 function deriveConsoleEndpoint(consoleUrl, explicitEndpoint) {
     if (explicitEndpoint)

package/build/src/runtime-adapters.js

@@ -144,3 +144,37 @@ export function activateCodexLocal(sourceRoot, dest) {
     generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
     return { selected_adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
+// Decision Q3 (Issue #32): Option (a) — new adapter id "strands-local" rather than
+// loading kit flows inside FlowAgentsHooks. Rationale: activation is a workspace-prep
+// concern (reads catalog + installed kits, writes runtime files, produces diagnostics).
+// Keeping it in the CLI adapter layer maximises reuse of readKitInventory and safeSegment,
+// mirrors the codex-local pattern exactly, and keeps framework adapters free of catalog-
+// layout knowledge. The Strands steering layer then reads the written runtime files.
+export function activateStrandsLocal(sourceRoot, dest) {
+    const inventory = readKitInventory(sourceRoot, dest);
+    // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
+    // so the Strands steering context can glob for *.flow.json under this path.
+    const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
+    const generated = [];
+    const skipped = [];
+    for (const asset of inventory.assets) {
+        if (asset.asset_class !== "flows") {
+            skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for strands-local" });
+            continue;
+        }
+        if (!asset.asset_id) {
+            skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+            continue;
+        }
+        const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.copyFileSync(asset.source_path, output);
+        generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+    }
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+    const manifestPath = path.join(runtimeDir, "activation.json");
+    writeJson(manifestPath, manifest);
+    generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
+    return { selected_adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+}

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

@@ -384,6 +384,15 @@ function exportOpencodePlugin() {
     // (for session-start steering context) and tool.execute.before (for
     // policy). This is the closest reasonable approximation — documented here
     // as an honest gap matching the codex live-hook-influence caveat pattern.
+    //
+    // KNOWN GAP (verified 2026-06-11, opencode v1.16.2): session.created is NOT
+    // delivered to plugin event handlers in opencode  (non-interactive) mode.
+    // The session IS created server-side but the event fires before the plugin
+    // hook dispatch loop is active. As a result, agentSpawn telemetry (session.start)
+    // is never emitted in run-mode sessions — only tool.invoke/tool.result appear.
+    // This is an opencode runtime limitation, not a bug in this plugin.
+    // Session.start telemetry carries L1 conformance but is unavailable in run mode.
+    // See docs/spec/runtime-hook-surface.md opencode mapping row for the full gap note.
     return `/**
  * Flow Agents opencode plugin.
  *
@@ -398,6 +407,13 @@ function exportOpencodePlugin() {
  * cannot intercept mid-session user messages before they are processed.
  * This is an accepted gap documented here analogously to the codex
  * live-hook-influence caveat.
+ *
+ * KNOWN GAP: session.created is NOT delivered to plugin handlers in opencode
+ * run (non-interactive) mode (verified v1.16.2, 2026-06-11). agentSpawn
+ * telemetry (session.start) is therefore absent from run-mode sessions.
+ * tool.invoke and tool.result events (L1) are still recorded normally.
+ * This is an opencode runtime limitation; no workaround is available without
+ * a different hook surface. See docs/spec/runtime-hook-surface.md for details.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -577,7 +593,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", async (event, _ctx) => {
-    runTelemetry("before_agent_start");
+    // Telemetry for agentSpawn is emitted by session_start above; do not repeat it here
+    // to avoid duplicate session.start events in the telemetry log.
     // Inject workflow steering context at agent start
     const result = runAdapter("pi-hook-adapter.js", "before_agent_start", "workflow-steering", "workflow-steering.js");
     if (result.context) {

package/console.telemetry.json

@@ -9,7 +9,9 @@
       "id": "flow-agents-workflow-state",
       "label": "Workflow state",
       "root": "product:flow-agents:.flow-agents",
-      "files": ["state.json"],
+      "files": [
+        "state.json"
+      ],
       "attributes": {
         "taskSlug": "task_slug",
         "repo": "repo",
@@ -30,7 +32,9 @@
       "id": "flow-agents-acceptance",
       "label": "Acceptance criteria",
       "root": "product:flow-agents:.flow-agents",
-      "files": ["acceptance.json"],
+      "files": [
+        "acceptance.json"
+      ],
       "attributes": {
         "taskSlug": "task_slug",
         "repo": "repo",
@@ -47,7 +51,9 @@
       "id": "flow-agents-evidence",
       "label": "Verification evidence",
       "root": "product:flow-agents:.flow-agents",
-      "files": ["evidence.json"],
+      "files": [
+        "evidence.json"
+      ],
       "attributes": {
         "taskSlug": "task_slug",
         "repo": "repo",
@@ -67,7 +73,9 @@
       "id": "flow-agents-handoffs",
       "label": "Handoffs",
       "root": "product:flow-agents:.flow-agents",
-      "files": ["handoff.json"],
+      "files": [
+        "handoff.json"
+      ],
       "attributes": {
         "taskSlug": "task_slug",
         "repo": "repo",
@@ -87,7 +95,9 @@
       "id": "flow-agents-learning",
       "label": "Learning records",
       "root": "product:flow-agents:.flow-agents",
-      "files": ["learning.json"],
+      "files": [
+        "learning.json"
+      ],
       "attributes": {
         "taskSlug": "task_slug",
         "repo": "repo",
@@ -101,22 +111,75 @@
     }
   ],
   "facets": [
-    { "id": "skills", "label": "Skills", "attribute": "skill", "limit": 16 },
-    { "id": "tools", "label": "Tools", "attribute": "toolName", "limit": 16 },
-    { "id": "flows", "label": "Flows", "attribute": "flow", "limit": 16 },
-    { "id": "repositories", "label": "Repositories", "attribute": "repo", "limit": 16 },
-    { "id": "projects", "label": "Projects", "attribute": "project", "limit": 16 },
-    { "id": "runtimes", "label": "Runtimes", "attribute": "runtime", "limit": 12 },
-    { "id": "agents", "label": "Agents", "attribute": "agent", "limit": 16 },
-    { "id": "models", "label": "Models", "attribute": "model", "limit": 16 },
-    { "id": "statuses", "label": "Statuses", "attribute": "status", "limit": 12 },
-    { "id": "outcomes", "label": "Outcomes", "attribute": "outcome", "limit": 12 }
+    {
+      "id": "skills",
+      "label": "Skills",
+      "attribute": "skill",
+      "limit": 16
+    },
+    {
+      "id": "tools",
+      "label": "Tools",
+      "attribute": "toolName",
+      "limit": 16
+    },
+    {
+      "id": "flows",
+      "label": "Flows",
+      "attribute": "flow",
+      "limit": 16
+    },
+    {
+      "id": "repositories",
+      "label": "Repositories",
+      "attribute": "repo",
+      "limit": 16
+    },
+    {
+      "id": "projects",
+      "label": "Projects",
+      "attribute": "project",
+      "limit": 16
+    },
+    {
+      "id": "runtimes",
+      "label": "Runtimes",
+      "attribute": "runtime",
+      "limit": 12
+    },
+    {
+      "id": "agents",
+      "label": "Agents",
+      "attribute": "agent",
+      "limit": 16
+    },
+    {
+      "id": "models",
+      "label": "Models",
+      "attribute": "model",
+      "limit": 16
+    },
+    {
+      "id": "statuses",
+      "label": "Statuses",
+      "attribute": "status",
+      "limit": 12
+    },
+    {
+      "id": "outcomes",
+      "label": "Outcomes",
+      "attribute": "outcome",
+      "limit": 12
+    }
   ],
   "flows": [
     {
       "id": "builder.shape",
       "label": "Builder shape",
-      "match": { "attribute": "flow", "includes": "builder.shape" },
+      "match": {
+        "attribute": "flow",
+        "includes": "builder.shape"
+      },
       "titleAttribute": "title",
       "detailAttributes": {
         "Project": "project",
@@ -135,7 +198,10 @@
     {
       "id": "builder.build",
       "label": "Builder build",
-      "match": { "attribute": "flow", "includes": "builder.build" },
+      "match": {
+        "attribute": "flow",
+        "includes": "builder.build"
+      },
       "titleAttribute": "title",
       "detailAttributes": {
         "Project": "project",
@@ -154,22 +220,51 @@
     {
       "id": "delivery",
       "label": "Delivery workflows",
-      "match": { "attribute": "skill", "includes": "deliver" },
+      "match": {
+        "attribute": "skill",
+        "includes": "deliver"
+      },
       "titleAttribute": "title",
       "limit": 10
     },
     {
       "id": "verification",
       "label": "Verification workflows",
-      "match": { "attribute": "skill", "includes": "verify-work" },
+      "match": {
+        "attribute": "skill",
+        "includes": "verify-work"
+      },
       "titleAttribute": "title",
       "limit": 10
     },
     {
       "id": "review",
       "label": "Review workflows",
-      "match": { "attribute": "skill", "includes": "review-work" },
+      "match": {
+        "attribute": "skill",
+        "includes": "review-work"
+      },
+      "titleAttribute": "title",
+      "limit": 10
+    },
+    {
+      "id": "knowledge",
+      "label": "Knowledge flows",
+      "match": {
+        "attribute": "flow",
+        "includes": "knowledge."
+      },
       "titleAttribute": "title",
+      "detailAttributes": {
+        "Project": "project",
+        "Repository": "repo",
+        "Task": "taskSlug",
+        "Status": "status",
+        "Outcome": "outcome",
+        "Agent": "agent",
+        "Runtime": "runtime",
+        "Observed": "observedAt"
+      },
       "limit": 10
     }
   ]

package/docs/_layouts/default.html

@@ -44,6 +44,8 @@
           <a href="{{ '/workflow-usage-guide.html' | relative_url }}">Workflow Guide</a>
           <a href="{{ '/agent-system-guidebook.html' | relative_url }}">System Guidebook</a>
           <a href="{{ '/skills-map.html' | relative_url }}">Workflow Map</a>
+          <a href="{{ '/kit-authoring-guide.html' | relative_url }}">Kit Authoring Guide</a>
+          <a href="{{ '/flow-kit-repository-contract.html' | relative_url }}">Kit Contract</a>
           <a href="{{ '/north-star.html' | relative_url }}">North Star</a>
           <a href="{{ '/sandbox-policy.html' | relative_url }}">Execution Safety</a>
           <a href="{{ '/veritas-integration.html' | relative_url }}">Governance Evidence</a>

package/docs/index.md

@@ -106,6 +106,14 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>Workflow Map</strong>
     <span>See the core skills, gates, artifacts, and route-back behavior.</span>
   </a>
+  <a class="doc-card" href="kit-authoring-guide.html">
+    <strong>Kit Authoring Guide</strong>
+    <span>Build your own Flow Kit from scratch: directory layout, kit.json, a flow file, validation, local install, and activation.</span>
+  </a>
+  <a class="doc-card" href="flow-kit-repository-contract.html">
+    <strong>Flow Kit Repository Contract</strong>
+    <span>Full validation rules, registry schema, activation diagnostics, and the install/update/force semantics.</span>
+  </a>
   <a class="doc-card" href="spec/runtime-hook-surface.html">
     <strong>Runtime Hook Surface</strong>
     <span>Canonical event taxonomy, four policy classes, conformance levels L0/L1/L2, and host mapping tables for adapter authors.</span>

package/docs/integrations/index.md

@@ -45,6 +45,10 @@ The <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> de
     <strong>Runtime Hook Surface Spec</strong>
     <span>Canonical event taxonomy, four policy classes, conformance levels L0/L1/L2, mapping tables, and the engine contract for adapter authors.</span>
   </a>
+  <a class="doc-card" href="knowledge-kit-live.html">
+    <strong>Knowledge Kit Live Example</strong>
+    <span>End-to-end proof of the Knowledge Kit ingest + compile flows against a real Strands agent (OllamaModel / qwen3:1.7b). No API key required. Includes acceptance test with telemetry and provenance assertions.</span>
+  </a>
 </div>
 
 ---