@kontourai/flow-agents 0.4.0 → 1.0.1

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

@@ -84,7 +84,8 @@ const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
-    ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
+    ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
+    ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
     ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
     ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
     ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
@@ -359,7 +360,7 @@ function validateKits(reporter) {
     if (flowSchemaPath && fs.existsSync(flowSchemaPath))
         console.log(fs.existsSync(localCli) ? `info: validating kit Flow Definitions with Flow CLI at ${localCli}` : `warning: Flow validator unavailable; source-tree check only verifies Flow Definition top-level shape`);
     else
-        console.log("warning: Flow schema not configured; source-tree check only verifies Flow Definition top-level shape. Set FLOW_CLI_ROOT to enable Flow CLI validation.");
+        console.log("warning: Flow schema not configured; source-tree check only verifies Flow Definition top-level shape. Set FLOW_CLI_ROOT to enable Flow CLI validation. Container validation (kit.json core fields) will delegate to 'flow validate-kit' from @kontourai/flow when FLOW_CLI_ROOT is available.");
     kits.forEach((entry, index) => {
         const kitText = typeof entry === "string" ? entry : ["path", "directory", "dir", "id", "name"].map((key) => entry?.[key]).find((value) => typeof value === "string" && value);
         if (!kitText) {

package/context/scripts/hooks/config-protection.js

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

package/docs/fixture-ownership.md

@@ -16,7 +16,8 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
 | `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
 | `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |
-| `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
+| `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/integration/test_activate_npx_context.sh`, `evals/integration/test_flow_kit_install_git.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
+| `evals/fixtures/kit-conformance-levels` | K-level conformance and consumer-target derivation fixtures | `evals/integration/test_kit_conformance_levels.sh` | Keep while K-level derivation, degradation invariant, and consumer-target badge rules are tested. |
 | `evals/fixtures/hook-influence` | hook influence behavioral cases | `evals/integration/test_hook_influence_cases.sh`, `evals/static/test_workflow_skills.sh`, `scripts/validate-hook-influence-cases.js` | Keep while hook influence cases define agent guidance behavior. |
 | `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |
 | `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |

package/docs/index.md

@@ -19,6 +19,10 @@ title: Kontour Flow Agents
     <strong>Evidence over confidence</strong>
     <span>Hooks catch stop-short behavior, and important work ends with tests, browser checks, CI results, review findings, or an explicit <code>NOT_VERIFIED</code> gap — never just a confident summary.</span>
   </section>
+  <section>
+    <strong>Flow Kits — workflow + output shape</strong>
+    <span>A kit bundles a workflow and its opinionated output shape as a validated, installable unit. Two reference kits ship today: Builder Kit (shaping → delivery pipeline) and Knowledge Kit (gated store with five pipeline flows, pluggable adapters, and an Obsidian rendering layer). <a href="kit-authoring-guide.html">Author your own</a> using the same path.</span>
+  </section>
 </div>
 
 ## How it works
@@ -114,13 +118,17 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <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="knowledge-kit.html">
+    <strong>Knowledge Kit</strong>
+    <span>Gated knowledge storage with five pipeline flows, a representation-neutral store contract, default and Obsidian adapters, 198 tests, and a parameterized contract suite any adapter can run.</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>
   </a>
   <a class="doc-card" href="vision.html">
     <strong>Vision and Direction</strong>
-    <span>Where Flow Agents is going: kits beyond coding, TypeScript framework adapters, and Kontour Console as the unifying telemetry surface.</span>
+    <span>The kits-as-ecosystem arc (authoring today → domain kits → registry → marketplace), TypeScript framework adapters, and Kontour Console as the unifying telemetry surface.</span>
   </a>
   <a class="doc-card" href="north-star.html">
     <strong>North Star</strong>

package/docs/kit-authoring-guide.md

@@ -164,6 +164,132 @@ For conflicts on re-install: if you install a different source with an existing
 
 See the [Flow Kit Repository Contract](flow-kit-repository-contract.md) for the full validation rules, registry schema, activation diagnostics, and the install/update/force semantics.
 
+## Layering: container vs. agent extension
+
+A Flow Agents Kit is built on two distinct layers. Understanding the split helps you know which rules come from Flow and which come from Flow Agents.
+
+### Layer 1: the Flow Kit container (Flow-owned)
+
+The **container contract** is owned by [Kontour Flow](https://kontourai.github.io/flow/flow-kit-container). It governs:
+
+- `kit.json` required fields: `schema_version` ("1.0"), `id` (kebab-case), `name`, `flows` (non-empty list with `path` entries).
+- Optional core fields: `description`, `product_name`.
+- Path rules: all declared paths must be relative, must not contain `..`, and must resolve inside the kit directory.
+- The **extension model**: unknown top-level fields are consumer extensions; core validation ignores-but-permits them.
+
+Container validation is surfaced in Flow's CLI as `flow validate-kit <kit-dir>`. Flow Agents delegates container validation to Flow when `FLOW_CLI_ROOT` is configured; without it, Flow Agents applies the same rules internally.
+
+For the authoritative container spec and JSON Schema, see [kontourai/flow#67](https://github.com/kontourai/flow/pull/67) (the spec PR) and the published `schemas/flow-kit-container.schema.json` in the `@kontourai/flow` package.
+
+### Layer 2: the Flow Agents agent extension (Flow Agents-owned)
+
+The **agent extension** is owned by Flow Agents. It defines the optional asset classes that turn a Flow Kit into a **Flow Agents Kit**:
+
+| Extension field | Asset type |
+|---|---|
+| `skills` | Reusable agent skill procedures |
+| `docs` | Documentation assets |
+| `adapters` | Runtime or framework adapters |
+| `evals` | Evaluation suites |
+| `assets` | General supporting assets |
+
+Each extension field is an optional array of entries with `id`, `path`, and optional `description`. Extension fields are validated by Flow Agents using the same path rules as the container layer (relative, no `..`, must exist). Unknown extension entries are recorded as `skipped_assets` during activation rather than treated as errors.
+
+### When a kit "is" a Flow Agents Kit
+
+A kit is a **Flow Agents Kit** when it satisfies both layers:
+
+1. It passes Flow Kit container validation (valid `kit.json` with core fields and at least one `flows` entry).
+2. It optionally declares one or more Flow Agents extension fields (`skills`, `docs`, `adapters`, `evals`, `assets`).
+
+A kit with only core fields (no extension fields) is a valid Flow Kit and is also a valid Flow Agents Kit — it just installs and activates only its Flow Definitions.
+
+### Why two layers?
+
+The split keeps ownership clean:
+
+- Flow authors, installs, and validates the container shape. Any tool that understands Flow Kits can install any kit without knowing about Flow Agents.
+- Flow Agents extends the container for agent-specific assets without modifying the core contract. Third-party kit authors who don't need skills or adapters never have to know about the extension layer.
+
+## K-levels: kit conformance and consumer-target badges
+
+Every Flow Agents Kit declares assets in a manifest. The K-level system classifies what consumers can do with a kit based on observable asset classes — no extra declaration needed for the level itself. Levels derive from what is present.
+
+### Conformance levels
+
+| Level | What is present | Who can consume it |
+|---|---|---|
+| **K0** | Valid core Flow Kit container: `schema_version`, `id`, `name`, `flows` (non-empty). | Any Flow consumer: gates and definition-of-done are evaluable agentlessly in CI or without an agent framework. |
+| **K1** | K0 + at least one Flow Agents extension field present (`skills`, `docs`, `adapters`, `evals`, or `assets`). | Flow Agents (>= installed version) can activate the kit in at least one agent harness or framework. |
+| **K2** | K1 + `evals` present with at least one entry. | Live evidence layer: eval suites run against an adapter and produce verifiable output records. |
+
+Every kit published by Kontour is K0 or higher. K0 is the minimum bar — a kit that fails K0 is not distributable.
+
+### The degradation invariant
+
+Every Flow Agents Kit **must remain a valid core Flow Kit container when agent-extension fields are ignored**. This is the degradation invariant:
+
+- Strip `skills`, `docs`, `adapters`, `evals`, and `assets` from a kit's `kit.json`.
+- The remaining manifest must satisfy the Flow Kit container contract (`schema_version`, `id`, `name`, `flows` non-empty, no `..` traversal).
+- This invariant is enforced by the kit validator (`npm run validate:source -- --kit <dir>`).
+
+Why this matters: any Flow consumer (CI gate runner, definition-of-done checker, release audit tool) can evaluate a kit's gates without knowing about Flow Agents. The kit's flow definitions carry the definition-of-done independently of whether an agent ever runs.
+
+### Consumer-target derivation
+
+Consumer targets are **derived** from observable asset classes — no declaration is required for standard targets:
+
+| Observable state | Derived target |
+|---|---|
+| K0 (flows present) | `flow` — any Flow consumer (gate evaluation, definition-of-done) |
+| K1 (agent extension assets present) | `flow-agents` — Flow Agents activates the kit |
+| Unknown top-level key(s) | Listed verbatim as third-party consumer target(s) |
+
+Unknown top-level keys are permitted by the container spec's `additionalProperties: true` rule. A third-party tool built on Flow can extend a kit with its own namespace (e.g. `"my-platform.widgets": [...]`) — the key becomes a derived consumer-target badge without requiring any pre-registration.
+
+Version constraints (e.g. minimum `flow-agents` version) are the only case where a declaration is needed beyond what derivation can reach.
+
+**Marketplace listing format**: `Works with: Flow (gates-only) | Flow Agents | <Consumer X>`
+
+### Evidence layering: Surface and Veritas
+
+Kit gates reference evidence using `"kind": "surface.claim"`. This is **Flow-native vocabulary**: Flow is built on Surface, so Surface claims are the expected evidence substrate at the Flow level. Surface claims are not a Flow Agents coupling.
+
+Veritas is an **optional claim family** — a developer-repo specialization for evidence that has been through a trust pipeline. Kits may be opinionated about requiring Veritas-class evidence. Builder Kit requiring Veritas-class evidence is the kit's own policy choice, defined by Kontour as the kit author, not a platform requirement. Other kits may not require Veritas at all.
+
+Layering summary:
+
+- **Surface** = claim substrate (Flow-level, always available)
+- **Veritas** = optional claim kind, kit-opinionated (Builder Kit requires it; others need not)
+
+### Inspecting a kit's K-level
+
+Use the `inspect` subcommand to derive a kit's conformance level and consumer targets:
+
+```bash
+npm run flow-kit -- inspect path/to/my-kit
+```
+
+Output is stable JSON:
+
+```json
+{
+  "kit_id": "my-kit",
+  "kit_name": "My Kit",
+  "conformance": {
+    "k0": true,
+    "k1": true,
+    "k2": false
+  },
+  "targets": ["flow", "flow-agents"],
+  "third_party_extensions": []
+}
+```
+
+Exit code 0 when the kit is at least K0 (valid core container); exit code 1 when K0 validation fails.
+
+The `inspect` command is read-only and safe to run before install.
+
 ## Direction
 
 Flow Kits are designed to be shareable workflow units — authored once, carried across teams and workspaces. The intended growth path is distribution from git remotes and a curated Kontour kit catalog of Kontour-authored kits covering work modes beyond software delivery. Today install is local-path only; remote fetch is explicitly a non-goal in this version.

package/docs/knowledge-kit.md

@@ -0,0 +1,69 @@
+---
+title: Knowledge Kit
+---
+
+# Knowledge Kit
+
+The Knowledge Kit is a Flow Kit for durable, gated knowledge storage. It packages a store contract, five pipeline flows, pluggable store adapters, and a parameterized contract test suite — all validated and installed through the standard `flow-kit` path.
+
+## What it ships
+
+**Store contract** — four record types (`raw`, `compiled`, `concept`, `snapshot`) with a defined mutation policy: every write goes through propose→evidence-gate→apply/reject. Required evidence fields are enforced at runtime; a missing field throws `MISSING_EVIDENCE` rather than silently passing. Supersede-not-delete: records that are superseded move to an archive state with full provenance intact, not removed.
+
+**Pipeline flows** — five flows cover the full lifecycle:
+
+| Flow | What it does |
+|---|---|
+| `knowledge.ingest` | Capture → classify → route raw source material |
+| `knowledge.compile` | Normalize classified raws into durable notes with provenance links |
+| `knowledge.synthesize` | Detect similar clusters → propose a concept summary → evidence-gate → apply/reject |
+| `knowledge.consolidate` | Related-event trigger → decision snapshot → supersede prior snapshots (not delete) |
+| `knowledge.retire` | Gated status lifecycle: active → implemented → retired, with working-set exclusion |
+
+**Store adapters** — two adapters ship:
+
+- **Default adapter** — flat markdown files with YAML frontmatter, `[[wikilink]]` inline links, and a JSON graph index. Zero runtime dependencies; uses Node.js built-ins only.
+- **Obsidian adapter** — the same store contract rendered into one human-canonical Obsidian note per record. Category dots map to folder hierarchy; configurable frontmatter dimensions (e.g. territory/customer/initiative as filterable fields); living overview notes at the category root with sources nested below; superseded records moved to `archive/` rather than deleted. The file is the record — no separate database, no sync step.
+
+The output-shape story is why the adapter model matters: the same five flows and the same mutation gates produce a different rendering layer depending on which adapter is active. Authors choose the output shape that fits how they already think. (The Obsidian adapter is shipped; layout/dimensions refinements and person/entity card support are in development.)
+
+**Similarity detectors** — the `synthesize` and `consolidate` flows accept a pluggable `similarityDetector`:
+
+| Detector | Approach | Requires |
+|---|---|---|
+| `defaultSimilarityDetector` | Category prefix overlap + Jaccard link-overlap (≥ 0.10) | Nothing — built-in |
+| `createVectorSimilarityDetector` | Dense embeddings + cosine similarity | ollama (`nomic-embed-text`, default threshold 0.60) |
+
+The vector detector is fail-closed: infrastructure failures throw `EMBED_FAILURE` rather than silently returning an empty cluster (which would be indistinguishable from "no similar records found").
+
+**Tests** — 198 tests across six suites (contract, ingest/compile, synthesis, consolidation, similarity-vector, retirement). The contract suite is parameterized — any adapter can run it by pointing `KNOWLEDGE_ADAPTER` at the adapter module.
+
+**Live-proven** — keyless operation validated via a Strands agent + local ollama acceptance harness. The vector similarity detector is validated against `nomic-embed-text` with documented threshold guidance.
+
+## Quick reference
+
+```bash
+# Install the kit into a workspace
+npx @kontourai/flow-agents flow-kit install-local kits/knowledge --dest /path/to/workspace
+
+# Run the contract suite against the default adapter
+node --test kits/knowledge/evals/contract-suite/suite.test.js
+
+# Run against an alternative adapter
+KNOWLEDGE_ADAPTER=/path/to/my-adapter.js \
+  node --test kits/knowledge/evals/contract-suite/suite.test.js
+```
+
+## Source
+
+- Kit manifest: [`kits/knowledge/kit.json`](https://github.com/kontourai/flow-agents/blob/main/kits/knowledge/kit.json)
+- Store contract doc: [`kits/knowledge/docs/store-contract.md`](https://github.com/kontourai/flow-agents/blob/main/kits/knowledge/docs/store-contract.md)
+- Default adapter: [`kits/knowledge/adapters/default-store/index.js`](https://github.com/kontourai/flow-agents/blob/main/kits/knowledge/adapters/default-store/index.js)
+- Obsidian adapter: [`kits/knowledge/adapters/obsidian-store/index.js`](https://github.com/kontourai/flow-agents/blob/main/kits/knowledge/adapters/obsidian-store/index.js)
+- Vector similarity detector: [`kits/knowledge/adapters/similarity-vector/index.js`](https://github.com/kontourai/flow-agents/blob/main/kits/knowledge/adapters/similarity-vector/index.js)
+
+## Related
+
+- [Kit Authoring Guide](kit-authoring-guide.html) — build your own kit using the same `kit.json` contract
+- [Flow Kit Repository Contract](flow-kit-repository-contract.html) — validation rules and activation diagnostics
+- [Vision and Direction](vision.html) — the kits-as-ecosystem arc and the sequenced path toward domain kits and a registry

package/docs/vision.md

@@ -16,6 +16,28 @@ One official framework adapter spike exists: `integrations/strands/` is a Python
 
 ---
 
+## Flow Kits as an authorable ecosystem
+
+### What ships today
+
+Kit authoring is shipped. The `kit.json` contract at schema version 1.0 is validated by the `flow-kit` CLI before any install. The [Kit Authoring Guide](kit-authoring-guide.html) walks from an empty directory to a validated, locally installed kit. Two reference kits ship in `kits/`:
+
+**Builder Kit** packages the full `idea → backlog → plan → build → review → verify → evidence → release → learning` pipeline as two flows (`builder.shape`, `builder.build`). It installs automatically.
+
+**Knowledge Kit** packages durable gated knowledge storage: a store contract with four record types, five pipeline flows (`ingest`, `compile`, `synthesize`, `consolidate`, `retire`), and a mutation policy of propose→evidence-gate→apply/reject with supersede-not-delete. It ships with 198 tests, a parameterized contract suite that any adapter can run against, and a vector similarity detector (ollama embeddings, pluggable interface).
+
+The output-shape story is the reason kit authoring matters beyond workflow reuse. The Knowledge Kit store contract is representation-neutral — the pipeline is identical, but the rendering layer is swapped by adapter. Today two adapters ship: the default adapter (flat markdown records with YAML frontmatter and a JSON graph index) and the Obsidian adapter (one human-canonical note per record, category→folder hierarchy, configurable frontmatter dimensions, living overviews, superseded notes in `archive/` not deleted). Authors who choose the Obsidian adapter get the same gated workflow rendered into the shape they already think in. That is what kit authoring unlocks: packaging both the process discipline and the output opinion as a deployable unit. (The Obsidian adapter is shipped; layout/dimensions refinements and person/entity card support are in development.)
+
+### Direction: the sequenced path to a kit ecosystem
+
+The items below are direction, not committed delivery dates. They record the intended shape of where this work goes.
+
+**Domain kits composing the substrate.** The store contract, mutation gate, and adapter model are not knowledge-specific. The next intended kits compose this substrate for specific domains: a Sales Kit (territory/customer/initiative schema, flows for managing account snapshots, side-effect adapters for CRM event logging) and a Research Kit (transcript capture→compile→recall with configurable similarity thresholds). Both are direction — not shipped.
+
+**Distribution, sequenced.** A registry of validated kits and a marketplace for kit distribution are the intended end-state. The sequencing is explicit: authoring tooling and covetable reference kits first (shipped), then a registry (direction), then a marketplace (direction). Claims of a shipped marketplace or registry are not warranted.
+
+---
+
 ## Direction
 
 The items below are direction, not committed delivery dates. They record the intended shape of where this work goes.

package/evals/fixtures/kit-conformance-levels/k0-flows-only/flows/review.flow.json

@@ -0,0 +1,26 @@
+{
+  "id": "k0-flows-only.review",
+  "version": "1.0",
+  "steps": [
+    { "id": "review", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "review-gate": {
+      "step": "review",
+      "expects": [
+        {
+          "id": "review-finding",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Review finding recorded.",
+          "claim": {
+            "type": "k0.review.finding",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/evals/fixtures/kit-conformance-levels/k0-flows-only/kit.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "id": "k0-flows-only",
+  "name": "K0 Flows-Only Kit",
+  "description": "A kit with only Flow Definitions — K0 conformance, consumable by any Flow consumer.",
+  "flows": [
+    {
+      "id": "k0-flows-only.review",
+      "path": "flows/review.flow.json",
+      "description": "Review gate evaluable agentlessly."
+    }
+  ]
+}

package/evals/fixtures/kit-conformance-levels/k1-agent-extension/docs/README.md

@@ -0,0 +1,3 @@
+# K1 Agent Extension Kit
+
+Documentation asset for the K1 agent extension fixture kit.

package/evals/fixtures/kit-conformance-levels/k1-agent-extension/flows/build.flow.json

@@ -0,0 +1,26 @@
+{
+  "id": "k1-agent-extension.build",
+  "version": "1.0",
+  "steps": [
+    { "id": "build", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "build-gate": {
+      "step": "build",
+      "expects": [
+        {
+          "id": "build-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Build evidence recorded.",
+          "claim": {
+            "type": "k1.build.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}