@kontourai/flow-agents 3.3.0 → 3.4.1

package/context/scripts/telemetry/lib/usage.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # usage.sh — Session usage metric functions
 
+# Module directory, resolved once at source time (cwd-independent).
+USAGE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Single-source pricing registry loader (local / remote / bundled).
+source "${USAGE_LIB_DIR}/pricing.sh"
+
 # Resolve model from agent-spec.json
 usage_get_model() {
   local agent_name="$1"
@@ -14,16 +20,211 @@ usage_get_model() {
   echo "unknown"
 }
 
+# Given the JSON object produced by usage_parse_transcript (has a top-level
+# `by_model[]` array), return the runtime-agnostic session model: the model
+# with the most total tokens (input+output+cache_creation+cache_read). This
+# lets any runtime that exposes a transcript (Claude Code, Codex, ...) resolve
+# a real model name instead of the kiro-only ~/.kiro/agents lookup, which
+# never matches non-kiro agent names (e.g. Claude Code's fixed "dev" hook
+# arg) and falls through to "unknown". Returns empty string when $1 is
+# null/empty or has no by_model entries, so the caller falls back to
+# usage_get_model().
+usage_model_from_transcript_usage() {
+  local transcript_usage="$1"
+  [[ -z "$transcript_usage" || "$transcript_usage" == "null" ]] && { echo ""; return; }
+  echo "$transcript_usage" | jq -r '
+    (.by_model // [])
+    | map({model, total: ((.input_tokens // 0) + (.output_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0))})
+    | sort_by([-.total, .model])
+    | .[0].model // empty
+  ' 2>/dev/null
+}
+
 # Count tool invocations for a session
 usage_count_tool_calls() {
   local session_id="$1" jsonl_path="$2"
-  [[ ! -f "$jsonl_path" ]] && echo 0 && return
-  grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"tool.invoke\"" "$jsonl_path" 2>/dev/null || echo 0
+  [[ ! -f "$jsonl_path" ]] && { echo 0; return; }
+  # grep -c prints "0" (not empty) on zero matches but still exits non-zero,
+  # so `grep -c ... || echo 0` double-emits "0\n0" here — that malformed
+  # value then breaks the caller's `jq --argjson tc "$tool_count"`, silently
+  # discarding the *entire* session.usage event whenever a session has no
+  # prior tool.invoke lines yet (a common, not-rare case). Capture the count
+  # first and only fall back when it's genuinely empty.
+  local count
+  count=$(grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"tool.invoke\"" "$jsonl_path" 2>/dev/null)
+  echo "${count:-0}"
 }
 
 # Count subagent delegations for a session
 usage_count_delegations() {
   local session_id="$1" jsonl_path="$2"
-  [[ ! -f "$jsonl_path" ]] && echo 0 && return
-  grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"agent.delegate\"" "$jsonl_path" 2>/dev/null || echo 0
+  [[ ! -f "$jsonl_path" ]] && { echo 0; return; }
+  # See usage_count_tool_calls above for why this can't be `grep -c ... || echo 0`.
+  local count
+  count=$(grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"agent.delegate\"" "$jsonl_path" 2>/dev/null)
+  echo "${count:-0}"
+}
+
+# Parse a runtime transcript (JSONL) into real per-model token + cost usage.
+# Ground truth lives in each assistant message's `.message.usage` block:
+#   input_tokens (uncached), output_tokens, cache_creation_input_tokens,
+#   cache_read_input_tokens — plus `.message.model`.
+# Cost is derived from the versioned pricing registry: cache writes bill at
+# input*write_5m, cache reads at input*read. Cost uses the registry's
+# current_version (override with arg $2) and the result stamps `pricing_version`
+# so the console can reproduce or recompute it. Emits a compact JSON object:
+#   { by_model: [ {model, input_tokens, output_tokens,
+#                  cache_creation_input_tokens, cache_read_input_tokens,
+#                  estimated_cost_usd} ],
+#     input_tokens, output_tokens, cache_creation_input_tokens,
+#     cache_read_input_tokens, estimated_cost_usd, pricing_version }
+# Tokens are source-of-truth and survive independently of pricing: if the
+# pricing registry is unavailable (or an explicit version arg doesn't exist in
+# it), by_model[]/input_tokens/output_tokens/etc. are still emitted — only
+# estimated_cost_usd and pricing_version degrade to null (the console
+# recomputes cost authoritatively from tokens). Prints nothing (non-zero) only
+# when the transcript itself is missing/empty/unreadable or truly carries zero
+# usage, so the caller can fall back to null usage. Never blocks agent work.
+# Expected transcript usage path (Claude Code / Anthropic usage object). Bumped
+# if the on-disk schema changes so drift is logged rather than silently zeroed.
+USAGE_TRANSCRIPT_SCHEMA="message.usage.input_tokens"
+
+# Append a one-line schema-drift warning (transcript carried usage data we could
+# not parse). Goes to TELEMETRY_DRIFT_LOG if set, else stderr. Never fatal.
+usage_log_drift() {
+  local transcript="$1"
+  local msg="[telemetry] pricing/usage drift: ${transcript} has usage data but expected path '${USAGE_TRANSCRIPT_SCHEMA}' parsed 0 tokens — transcript schema may have changed"
+  if [[ -n "${TELEMETRY_DRIFT_LOG:-}" ]]; then
+    echo "$msg" >> "${TELEMETRY_DRIFT_LOG}" 2>/dev/null || echo "$msg" >&2
+  else
+    echo "$msg" >&2
+  fi
+}
+
+# Opt-in persistent diagnostics for usage_parse_transcript's no-usage/degraded
+# outcomes (gated by TELEMETRY_USAGE_DEBUG=1 so it never fires by default).
+# Goes to TELEMETRY_DRIFT_LOG if set, else stderr. Never fatal, never blocks —
+# purely so intermittent live "session.usage has null tokens" reports can be
+# distinguished (empty transcript_path vs missing file vs no pricing registry
+# vs a real zero-token parse) instead of being an unexplained black box.
+usage_log_debug() {
+  [[ "${TELEMETRY_USAGE_DEBUG:-}" == "1" ]] || return 0
+  local reason="$1"
+  local msg="[telemetry] usage_parse_transcript: ${reason}"
+  if [[ -n "${TELEMETRY_DRIFT_LOG:-}" ]]; then
+    echo "$msg" >> "${TELEMETRY_DRIFT_LOG}" 2>/dev/null || echo "$msg" >&2
+  else
+    echo "$msg" >&2
+  fi
+}
+
+usage_parse_transcript() {
+  local transcript="$1" version="${2:-}"
+  if [[ -z "$transcript" ]]; then
+    usage_log_debug "no usage — reason: empty transcript_path"
+    return 1
+  fi
+  if [[ ! -f "$transcript" ]]; then
+    usage_log_debug "no usage — reason: transcript file missing (${transcript})"
+    return 1
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    usage_log_debug "no usage — reason: jq unavailable"
+    return 1
+  fi
+
+  # Pricing registry is best-effort: when unavailable, tokens are still
+  # extracted below and only the cost fields degrade to null (defect #2 fix —
+  # previously this hard-returned 1 here, discarding token extraction
+  # entirely whenever pricing_registry() failed).
+  local registry has_registry
+  registry="$(pricing_registry 2>/dev/null)"
+  if [[ $? -eq 0 && -n "$registry" ]]; then
+    has_registry=true
+  else
+    has_registry=false
+    registry='null'
+    usage_log_debug "pricing registry unavailable (${transcript}) — extracting tokens without cost"
+  fi
+  # A non-empty registry can still be malformed (corrupt/truncated pricing.json,
+  # or a bad remote 200) — validate it parses before handing it to `jq -n
+  # --argjson`, which would otherwise abort the whole parse and discard tokens
+  # (the exact intermittent-null-tokens defect this function exists to fix).
+  if [[ "$has_registry" == true ]] && ! jq -e . >/dev/null 2>&1 <<<"$registry"; then
+    has_registry=false
+    registry='null'
+    usage_log_debug "pricing registry unparseable (${transcript}) — extracting tokens without cost"
+  fi
+
+  local out
+  out="$(jq -n --argjson registry "$registry" --argjson has_registry "$has_registry" --arg version "$version" '
+    ($has_registry and ($registry != null)) as $has_reg
+    | (if $has_reg then (if $version == "" then $registry.current_version else $version end) else null end) as $ver
+    | (if $has_reg and ($ver != null) then ($registry.versions[$ver]) else null end) as $p
+    | ($p != null) as $priced
+    | (if $priced then $p.cache_multipliers else null end) as $cm
+    | (reduce inputs as $l ({};
+        ($l.message.usage) as $u
+        | if $u then
+            (($l.message.model) // "unknown") as $m
+            | .[$m].input          = ((.[$m].input // 0)          + (($u.input_tokens) // 0))
+            | .[$m].output         = ((.[$m].output // 0)         + (($u.output_tokens) // 0))
+            | .[$m].cache_creation = ((.[$m].cache_creation // 0) + (($u.cache_creation_input_tokens) // 0))
+            | .[$m].cache_read     = ((.[$m].cache_read // 0)     + (($u.cache_read_input_tokens) // 0))
+          else . end)) as $agg
+    | ($agg | to_entries
+        | map(
+            .key as $m | .value as $u
+            | (if $priced then (($p.models[$m]) // $p.default) else null end) as $rate
+            | (if $priced then (if ([$m] | inside($p.zero_cost_models)) then 0 else 1 end) else null end) as $billable
+            | {
+                model: $m,
+                input_tokens: ($u.input // 0),
+                output_tokens: ($u.output // 0),
+                cache_creation_input_tokens: ($u.cache_creation // 0),
+                cache_read_input_tokens: ($u.cache_read // 0),
+                estimated_cost_usd: (
+                  if $priced then
+                    $billable * (
+                      ($u.input // 0)          * $rate.input
+                      + ($u.output // 0)         * $rate.output
+                      + ($u.cache_creation // 0) * $rate.input * $cm.write_5m
+                      + ($u.cache_read // 0)     * $rate.input * $cm.read
+                    ) / 1000000
+                  else null end
+                )
+              })) as $by_model
+    | {
+        by_model: $by_model,
+        input_tokens: ([$by_model[].input_tokens] | add // 0),
+        output_tokens: ([$by_model[].output_tokens] | add // 0),
+        cache_creation_input_tokens: ([$by_model[].cache_creation_input_tokens] | add // 0),
+        cache_read_input_tokens: ([$by_model[].cache_read_input_tokens] | add // 0),
+        estimated_cost_usd: (if $priced then (([$by_model[].estimated_cost_usd] | add // 0) * 1000000 | round / 1000000) else null end),
+        pricing_version: (if $priced then $ver else null end)
+      }
+  ' < "$transcript" 2>/dev/null)"
+
+  if [[ -z "$out" ]]; then
+    usage_log_debug "no usage — reason: jq parse failed (${transcript})"
+    return 1
+  fi
+
+  # Drift / emptiness check: if we parsed zero tokens but the transcript clearly
+  # contains usage data, the schema drifted — warn and fall back to null usage.
+  # This only discards tokens when there truly are none (total == 0); it never
+  # discards a non-zero token extraction, including the pricing-unavailable
+  # case above.
+  local total
+  total="$(printf '%s' "$out" | jq -r '((.input_tokens // 0) + (.output_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0))' 2>/dev/null)"
+  if [[ -z "$total" || "$total" == "0" ]]; then
+    if grep -q '"input_tokens"' "$transcript" 2>/dev/null; then
+      usage_log_drift "$transcript"
+    else
+      usage_log_debug "no usage — reason: parsed 0 tokens (no usage entries found in ${transcript})"
+    fi
+    return 1
+  fi
+
+  printf '%s\n' "$out"
 }

package/context/scripts/telemetry/telemetry.conf

@@ -8,6 +8,12 @@ channel.analytics.redact=tool.input,tool.output,turn.prompt_text,delegation.targ
 # The transport derives /api/telemetry/records from console_telemetry_url.
 # console_telemetry_token=
 # console_tenant_id=
+# Kit-economics relay (#469): once console_telemetry_url/console_telemetry_endpoint_url
+# resolves, the per-run kit-economics record relay defaults ON (opt-out, not silent-off).
+# Set console_economics_relay=0 to opt out while keeping the telemetry mirror; or run
+# install-console-config.sh --no-economics-relay to write this at install time.
+# console_economics_relay=0
+# console_economics_endpoint_url=
 # Live pricing registry source. If unset, derived from console_telemetry_url as
 # <console>/api/telemetry/pricing so bash/Python/TS runtimes read one live
 # source; lib/pricing.sh caches it and falls back to bundled pricing.json.

package/context/scripts/telemetry/telemetry.sh

@@ -318,6 +318,18 @@ add_stop_data_and_emit_usage() {
     transcript_usage=$(usage_parse_transcript "$transcript_path")
     [[ -z "$transcript_usage" ]] && transcript_usage='null'
 
+    # Prefer the transcript-derived model (runtime-agnostic — works for any
+    # runtime that exposes a transcript) over the kiro-only ~/.kiro/agents
+    # lookup above, which never resolves for non-kiro agent names (e.g.
+    # Claude Code's fixed "dev" hook arg) and falls through to "unknown".
+    # Falls back to usage_get_model's kiro result when no transcript usage
+    # is available (kiro-cli path is unchanged: transcript_usage stays null).
+    if [[ "$transcript_usage" != "null" ]]; then
+      local transcript_model
+      transcript_model=$(usage_model_from_transcript_usage "$transcript_usage")
+      [[ -n "$transcript_model" ]] && model="$transcript_model"
+    fi
+
     local usage_event
     usage_event=$(echo "$event" | jq -c \
       --arg m "$model" \
@@ -340,6 +352,42 @@ add_stop_data_and_emit_usage() {
         })
       }')
     transport_emit "$usage_event"
+
+    # Per-run kit-economics record (#349, console ADR 0003). Best-effort + DETACHED so it can never
+    # alter existing telemetry timing or fail the stop hook: assemble one kontour.console.economics
+    # fact from this session.usage event + the run's review sidecars, write it local-first, then
+    # opt-in relay it. Resolve the sidecar paths from the run cwd's active-session pointer; the
+    # emitter defaults every field cleanly when a sidecar is absent.
+    local econ_script="${TELEMETRY_DIR}/economics-record.sh"
+    if [[ -f "$econ_script" ]]; then
+      local econ_cwd econ_slug econ_state econ_acceptance econ_critique
+      econ_cwd=$(echo "$usage_event" | jq -r '.context.cwd // ""' 2>/dev/null)
+      [[ -z "$econ_cwd" || ! -d "$econ_cwd" ]] && econ_cwd="$PWD"
+      # Active slug from the canonical current pointer first, falling back to the legacy pointer.
+      econ_slug=""
+      if [[ -f "$econ_cwd/.kontourai/flow-agents/current.json" ]]; then
+        econ_slug=$(jq -r '.active_slug // .artifact_dir // empty' "$econ_cwd/.kontourai/flow-agents/current.json" 2>/dev/null)
+      elif [[ -f "$econ_cwd/.flow-agents/current.json" ]]; then
+        econ_slug=$(jq -r '.active_slug // .artifact_dir // empty' "$econ_cwd/.flow-agents/current.json" 2>/dev/null)
+      fi
+      econ_state="" econ_acceptance="" econ_critique="" econ_agents_dir=""
+      if [[ -n "$econ_slug" ]]; then
+        # state.json under .kontourai/flow-agents/<slug>/ (fallback .flow-agents/<slug>/); the run's
+        # per-agent event logs live alongside it in <slug>/agents/ (#415 delegations[] source).
+        for d in "$econ_cwd/.kontourai/flow-agents/$econ_slug" "$econ_cwd/.flow-agents/$econ_slug"; do
+          [[ -f "$d/state.json" ]] && { econ_state="$d/state.json"; [[ -d "$d/agents" ]] && econ_agents_dir="$d/agents"; break; }
+        done
+        [[ -f "$econ_cwd/.flow-agents/$econ_slug/acceptance.json" ]] && econ_acceptance="$econ_cwd/.flow-agents/$econ_slug/acceptance.json"
+        [[ -f "$econ_cwd/.flow-agents/$econ_slug/critique.json" ]] && econ_critique="$econ_cwd/.flow-agents/$econ_slug/critique.json"
+      fi
+      local econ_args=("$usage_event")
+      [[ -n "$econ_state" ]] && econ_args+=(--state "$econ_state")
+      [[ -n "$econ_acceptance" ]] && econ_args+=(--acceptance "$econ_acceptance")
+      [[ -n "$econ_critique" ]] && econ_args+=(--critique "$econ_critique")
+      [[ -n "$econ_agents_dir" ]] && econ_args+=(--agents-dir "$econ_agents_dir")
+      (bash "$econ_script" "${econ_args[@]}") </dev/null >/dev/null 2>&1 &
+      disown 2>/dev/null || true
+    fi
   fi
 
   echo "$event"

package/context/settings/workspace-backlog-provider-settings.example.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "../../schemas/backlog-provider-settings.schema.json",
+  "schema_version": "1.0",
+  "workspace": {
+    "repos": ["flow-agents", "surface", "veritas"]
+  },
+  "defaults": {
+    "work_item_provider": {
+      "role": "WorkItemProvider",
+      "kind": "github",
+      "repo": {
+        "owner": "kontourai",
+        "name": "flow-agents",
+        "url": "https://github.com/kontourai/flow-agents"
+      },
+      "capabilities": ["issues", "labels", "assignees", "pr_links", "comments"]
+    },
+    "board_provider": {
+      "role": "BoardProvider",
+      "kind": "github",
+      "repo": {
+        "owner": "kontourai",
+        "name": "flow-agents",
+        "url": "https://github.com/kontourai/flow-agents"
+      },
+      "board": {
+        "type": "github_project",
+        "owner": "kontourai",
+        "number": 1,
+        "url": "https://github.com/orgs/kontourai/projects/1"
+      },
+      "capabilities": ["projects_boards", "status_fields", "custom_fields"]
+    },
+    "selection": {
+      "filters": {
+        "issue_state": "open",
+        "include_labels": [],
+        "ready_statuses": ["ready"],
+        "exclude_statuses": ["in_progress", "blocked", "review", "verification", "done"]
+      },
+      "wip_policy": {
+        "prefer_finishing_active_work": true,
+        "active_statuses": ["in_progress", "review", "verification"],
+        "block_new_work_when_active_count_exceeds": 0
+      }
+    }
+  }
+}

package/docs/agent-usage-feedback-loop.md

@@ -62,6 +62,41 @@ Use `flow-agents init --yes` or `--headless` with the same flags in CI. The
 legacy sink names `kontour-cloud` and `hosted-kontour-console` are still
 accepted for existing scripts.
 
+### Owner machine mirror
+
+For a personal machine or repo where an owner wants Claude Code (or other
+runtime) hook sessions mirrored to a hosted Console, without editing the
+tracked `scripts/telemetry/telemetry.conf` default template (that file ships
+verbatim into every packaged bundle, so writing a personal token/tenant into
+it would leak to downstream consumers) and without exporting env vars per
+session, `scripts/telemetry/lib/config.sh` auto-discovers a gitignored,
+operator-created conf at either of two conventional paths, no extra wiring
+required:
+
+1. `<workspace>/.kontourai/telemetry-console.conf` — repo-scoped, checked
+   first.
+2. `~/.flow-agents/telemetry-console.conf` — machine-scoped, used when no
+   workspace-scoped conf is present.
+
+Populate either path with the existing preset installer:
+`scripts/telemetry/install-console-config.sh <conf-path> --telemetry-sink
+kontour-hosted-console --console-token-file <token-file> --console-tenant
+<tenant>`. The installer `chmod 600`s the file, sets it to be owned by the
+current user, and never echoes the token. Both conditions matter: config.sh
+only honors a discovered conf if it is mode 600 and owned by the current
+user, since that combination can only come from an operator running the
+installer (or an equivalent manual `chmod 600`) — it distinguishes an
+operator-created conf from one that arrived via `git clone`, a tarball, a
+PR, or any other supply-chain path, none of which can produce a 600-mode
+file. A conf that fails that check is treated as if it were absent (fail
+open) and resolution falls through to the next tier.
+
+The explicit `TELEMETRY_CONFIG_FILE` env var still overrides both
+auto-discovered paths and always wins. Wiring it from a login-shell profile
+(for example `~/.profile` on `bash -l` setups) remains available for exotic
+setups that need a config path outside both conventional locations, but is
+no longer required for the common case.
+
 Check an installed telemetry setup without opening an interactive prompt:
 
 ```bash

package/docs/architecture-engine-and-kits.md

@@ -0,0 +1,110 @@
+---
+title: Engine and Kits
+---
+
+# Engine and Kits
+
+**Flow Agents is an engine you build on — not a single product, and not the Builder Kit.** It has two layers:
+
+1. The **engine** is the product-neutral runtime layer: it interprets Flow Definitions, evaluates gates, adapts to host runtimes and harnesses, provides SDK/evidence/trust primitives, and validates Flow Kit containers and Flow Agents extensions.
+2. **Kits** are the swappable solution layer: bundles of flows, gates, skills, agents, hooks, docs, adapters, evals, and assets declared by `kit.json` and registered through `kits/catalog.json`.
+
+The engine is what you build on. Kits are what you build with.
+
+> **Flow Agents is not the Builder Kit.** Builder is one kit on the engine. So is Knowledge. So are the agentless Release-Evidence and Veritas-Governance kits — proof that the engine runs solutions shipping no agent at all. The engine gives no kit special runtime privilege; "official" is a marketplace label, not engine authority.
+
+## The engine
+
+The engine does not encode one product workflow. It supplies the common substrate that lets any kit run through the same install, validation, activation, steering, evidence, and gate-evaluation path.
+
+Concrete engine pieces in this repository include:
+
+- **FlowDefinition interpretation and gates** — kit manifests point at `.flow.json` definitions, and Flow Agents validates and activates those definitions for runtime use. The Kit Authoring Guide shows a minimal Flow Definition with steps, gates, and required evidence, while `kits/builder/kit.json`, `kits/knowledge/kit.json`, `kits/release-evidence/kit.json`, and `kits/veritas-governance/kit.json` show different real kit shapes.
+- **Runtime and harness adapters** — Flow Agents compiles the same canonical policy classes to host surfaces such as Claude Code, Codex, Kiro, opencode, pi, and framework adapters. The Runtime Hook Surface spec defines the runtime-neutral vocabulary.
+- **SDK, evidence, and trust primitives** — workflow sidecars, trust bundles, evidence records, command capture, and CI reconciliation give gates something inspectable to evaluate instead of relying on chat memory.
+- **Kit validation framework** — `kit.json` is validated as a Flow Kit container, then Flow Agents validates extension fields such as `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies`, `workflow_triggers`, and `hook_influence_expectations`.
+
+The important boundary: the engine owns the generic process machinery, not the domain workflow. A coding delivery workflow, a knowledge-store workflow, and an agentless CI evidence workflow all pass through the same container and gate model.
+
+## The kits
+
+A kit is a declared bundle. The catalog names available kits; each kit's manifest declares its own assets.
+
+Today `kits/catalog.json` registers four built-in examples:
+
+| Kit | Manifest | What it proves |
+| --- | --- | --- |
+| Builder Kit | `kits/builder/kit.json` | A full agent-facing delivery kit with shape/build/publish-learn flows, many skills, a dependency on Knowledge, and structured `workflow_triggers`. |
+| Knowledge Kit | `kits/knowledge/kit.json` | A durable knowledge-store kit with many Flow Definitions, one agent skill, docs, adapters, providers, evals, and its own `workflow_triggers`. |
+| Release Evidence Kit | `kits/release-evidence/kit.json` | A minimal flows-only kit for agentless gate evaluation in CI. It has no skills and is not a Builder workflow. |
+| Veritas Governance Kit | `kits/veritas-governance/kit.json` | An agentless governance kit that wraps `veritas readiness` evidence as trust.bundle claims without reimplementing Veritas standards evaluation. |
+
+Those examples are deliberately different. Builder is not the product. Builder is one kit on the engine. Knowledge is another. Release Evidence and Veritas Governance prove the engine can run useful kits that are not conversational coding workflows at all.
+
+## Manifest and catalog model
+
+`kits/catalog.json` is the registry of built-in kits. It records the kit id, name, path, and human-facing description.
+
+Each kit directory has a `kit.json` manifest. The shared container fields are small and portable:
+
+- `schema_version`
+- `id`
+- `name`
+- `description` or `product_name`
+- `flows`
+
+Flow Agents adds optional extension fields for agent use:
+
+- `skills`
+- `docs`
+- `adapters`
+- `evals`
+- `assets`
+- `dependencies`
+- `workflow_triggers`
+- `hook_influence_expectations`
+
+This is the plugin model. A third-party kit uses the same container shape and validation path as the built-in kits. Bring-your-own-kit is not a side channel; it is the extension point.
+
+## Kit-neutral steering
+
+The engine is kit-neutral. No kit gets special runtime branches just because it is built in, first-party, or official.
+
+Kits steer the engine only through structured `workflow_triggers`. For example, Builder declares a trigger for `implementation-work-detected` that points at `builder.build` and names `deliver` as the default skill. Knowledge declares a trigger for `knowledge-capture-detected` that points at `knowledge.ingest` and names `knowledge.knowledge-capture` as the default skill.
+
+The engine renders those structured fields through one steering path. It does not accept freeform kit steering text, and it does not grant runtime privilege based on provenance.
+
+`first_party` is legacy catalog or marketplace metadata. It can help a marketplace label a kit, but it does not change runtime authority. Built-in, official, and community kits all participate through the same manifest, catalog, activation, and trigger model.
+
+## Marketplace direction
+
+The growth path is a marketplace of kits, not a growing list of hardcoded engine behaviors.
+
+The pieces already in the repository are the same pieces a marketplace needs:
+
+- `catalog.json` as the registry shape for discoverable kits.
+- `kit.json` as the manifest and identity document.
+- validation as the admission check before install or activation.
+- kit identity and trust metadata as marketplace labels, not runtime privilege.
+- activation paths that copy declared assets without making one kit special.
+
+That means a team can bring its own kit for a domain workflow, install it, validate it, activate it, and have it steer through the same structured trigger model as the built-in kits.
+
+## Trust posture
+
+Kit trust is orthogonal to engine privilege. A marketplace may call a kit official, verified, unverified, first-party, or community-contributed. The runtime should still ask the same questions:
+
+- Is the kit manifest valid?
+- Are declared assets present and local to the kit?
+- Are dependencies installed and activated?
+- Are trigger fields structured and valid?
+- Does evidence satisfy the active FlowDefinition gate?
+
+The answer is determined by validation, activation, and gate evidence, not by a privileged kit list.
+
+## Related docs
+
+- [Flow Kit Authoring Guide](kit-authoring-guide.md)
+- [Flow Kit Repository Contract](flow-kit-repository-contract.md)
+- [Runtime Hook Surface spec](spec/runtime-hook-surface.md)
+- [Verifiable Trust](verifiable-trust.md)

package/docs/context-map.md

@@ -44,6 +44,7 @@ Generated by `npm run context-map`. Regenerate after changing agents, skills, sc
 | Claim lookup | npm run workflow:sidecar -- claim <id> <dir> |
 | Context map drift | npm run context-map:check |
 | Bundle build | npm run build:bundles |
+| Skill drift check | flow-agents skill-drift-check |
 
 ## Workflow Sidecars
 
@@ -94,6 +95,7 @@ Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`
 | dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
 | design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probing interview for turning unclear goals, designs, or workflow states into shared understanding before planning or execution. |
 | eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
+| exemption-usage-review | kits/veritas-governance/skills/exemption-usage-review/SKILL.md | Periodic audit of standing delivery/DECLARED no-agent-delivery exemptions (ADR 0022 §3): lists every current exemption's scope, reason, approver, and age since declared_at, flags entries overdue for owner re-confirmation against a config... |
 | github-cli | skills/github-cli/SKILL.md | Interact with GitHub via gh CLI — PRs, issues, repos, releases, workflows, gists. |
 | knowledge-capture | kits/knowledge/skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
 | pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work. |