@kontourai/flow-agents 0.1.2 → 0.3.0

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

@@ -361,6 +361,287 @@ function buildCodex(agents) {
     writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace"));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
+function exportOpencodeAgent(spec) {
+    // Determine agent mode: orchestrator-like agents -> primary, others -> subagent
+    const primaryAgents = new Set(["dev"]);
+    const mode = primaryAgents.has(spec.name) ? "primary" : "subagent";
+    const prompt = appendExportNote(sanitizeText(spec.prompt, "opencode", "<bundle-root>"), "Kiro hook wiring and JSON-only runtime fields were omitted. If this agent mentions Kiro-specific scheduler or hook behavior, treat that as optional operational guidance rather than a hard dependency.");
+    const lines = ["---"];
+    lines.push(`description: ${String(spec.description ?? "").trim()}`);
+    lines.push(`mode: ${mode}`);
+    lines.push(`model: ${mapped("claude_model_map", spec.model)}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(prompt);
+    return lines.join("\n");
+}
+function exportOpencodePlugin() {
+    // Generate the Flow Agents opencode plugin.
+    // opencode plugins are auto-loaded from .opencode/plugins/*.js at startup.
+    //
+    // NOTE: opencode has no direct user-prompt-submit hook. For prompt-submit
+    // workflow steering, we wire the steering command behind session.created
+    // (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.
+ *
+ * Auto-loaded from .opencode/plugins/flow-agents.js at opencode startup.
+ * Delegates policy and telemetry decisions to shared scripts in scripts/hooks/
+ * using the same payload contract as the claude/codex adapters.
+ *
+ * EVENT MAPPING NOTE: opencode has no direct user-prompt-submit hook.
+ * Workflow steering (workflow-steering.js) is wired to session.created
+ * (session-start context) and tool.execute.before (per-tool policy).
+ * This approximates the UserPromptSubmit behavior in other runtimes but
+ * 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';
+import { join, basename } from 'node:path';
+
+// opencode runs plugins inside its own compiled (Bun-based) binary, so
+// process.execPath points at opencode itself — spawning it with a script
+// path silently does nothing (caught by live acceptance smoke 2026-06-11).
+// Resolve a real node binary instead; fall back to PATH lookup.
+const NODE_BIN = basename(process.execPath).startsWith('node') ? process.execPath : 'node';
+
+export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree }) => {
+  const root = directory || process.cwd();
+
+  // The hook scripts read the event payload from stdin; an empty stdin makes
+  // the telemetry pipeline silently skip the emit (fail-open), so every spawn
+  // must pass a payload (caught by live acceptance smoke 2026-06-11).
+  function hookPayload(eventName, detail) {
+    return JSON.stringify({ hook_event_name: eventName, cwd: root, ...(detail || {}) });
+  }
+
+  function runAdapter(adapterScript, eventName, detail, ...args) {
+    const adapterPath = join(root, 'scripts', 'hooks', adapterScript);
+    const result = spawnSync(NODE_BIN, [adapterPath, eventName, ...args], {
+      input: hookPayload(eventName, detail),
+      encoding: 'utf8',
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_HOOK_RUNTIME: 'opencode' },
+      timeout: 30000,
+    });
+    try {
+      return JSON.parse(result.stdout || '{}');
+    } catch {
+      return { allow: true };
+    }
+  }
+
+  function runTelemetry(eventName, detail) {
+    const telemetryPath = join(root, 'scripts', 'hooks', 'opencode-telemetry-hook.js');
+    spawnSync(NODE_BIN, [telemetryPath, eventName, 'dev'], {
+      input: hookPayload(eventName, detail),
+      encoding: 'utf8',
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_TELEMETRY_RUNTIME: 'opencode' },
+      timeout: 10000,
+    });
+  }
+
+  return {
+    'session.created': async (_input, _output) => {
+      runTelemetry('session.created');
+      // Wire workflow steering on session start for context injection
+      runAdapter('opencode-hook-adapter.js', 'session.created', null, 'workflow-steering', 'workflow-steering.js', 'default');
+    },
+    'tool.execute.before': async (input, output) => {
+      const detail = { tool: input && input.tool, args: output && output.args };
+      runTelemetry('tool.execute.before', detail);
+      const policyResult = runAdapter('opencode-hook-adapter.js', 'tool.execute.before', detail, 'config-protection', 'config-protection.js', 'default');
+      if (policyResult && policyResult.allow === false) {
+        throw new Error(policyResult.reason || 'Blocked by Flow Agents hook policy.');
+      }
+    },
+    'tool.execute.after': async (input, output) => {
+      const detail = { tool: input && input.tool };
+      runTelemetry('tool.execute.after', detail);
+      runAdapter('opencode-hook-adapter.js', 'tool.execute.after', detail, 'quality-gate', 'quality-gate.js', 'default');
+    },
+    'session.idle': async (_input, _output) => {
+      runTelemetry('session.idle');
+      runAdapter('opencode-hook-adapter.js', 'session.idle', null, 'stop-goal-fit', 'stop-goal-fit.js', 'default');
+    },
+    'session.error': async (_input, _output) => {
+      runTelemetry('session.error');
+    },
+    'session.compacted': async (_input, _output) => {
+      runTelemetry('session.compacted');
+    },
+    'permission.asked': async (_input, _output) => {
+      runTelemetry('permission.asked');
+    },
+    'file.edited': async (_input, _output) => {
+      runTelemetry('file.edited');
+    },
+  };
+};
+`;
+}
+function exportOpencodeConfig() {
+    // opencode's config schema requires `instructions` to be an ARRAY of
+    // instruction file paths/globs (a bare string fails validation and aborts
+    // startup). AGENTS.md is loaded natively by opencode, so the config stays
+    // minimal rather than double-including it.
+    return `${JSON.stringify({
+        $schema: "https://opencode.ai/config.json",
+    }, null, 2)}\n`;
+}
+function buildOpencode(agents) {
+    const bundle = path.join(dist, "opencode");
+    resetDir(bundle);
+    copySharedContent(bundle, "opencode", "<bundle-root>");
+    writeText(path.join(bundle, manifest.opencode.task_dir, ".gitkeep"), "");
+    for (const spec of agents) {
+        writeText(path.join(bundle, ".opencode/agents", `${spec.name}.md`), exportOpencodeAgent(spec));
+    }
+    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
+        const skillPath = path.join(root, "skills", skill, "SKILL.md");
+        if (fs.existsSync(skillPath))
+            writeText(path.join(bundle, ".opencode/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "opencode", "<bundle-root>"));
+    }
+    writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
+    writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
+    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("opencode", agents, manifest.opencode.task_dir));
+    writeText(path.join(bundle, "README.md"), exportTargetReadme("opencode", "bash install.sh /path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("opencode", "/path/to/workspace"));
+    fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
+}
+function exportPiExtension() {
+    // Generate the Flow Agents pi extension.
+    // pi extensions are auto-discovered from .pi/extensions/*.ts (needs project trust).
+    // pi has no named-subagent registry; agents are not exported. The extension
+    // provides workflow steering (via before_agent_start context injection),
+    // tool-call policy (via tool_call event), and telemetry delegation to shared scripts.
+    return `/**
+ * Flow Agents pi extension.
+ *
+ * Auto-discovered from .pi/extensions/flow-agents.ts at startup (needs project trust).
+ * Delegates policy and telemetry to shared scripts/hooks/ using spawnSync,
+ * mirroring the payload contract used by the claude/codex adapters.
+ *
+ * NOTE: pi has no named-subagent registry. Agents are not exported for pi.
+ * Rely on AGENTS.md + skills + this extension for workflow guidance.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process";
+import { join, basename } from "node:path";
+
+// pi may run extensions under a non-node runtime (Bun), where process.execPath
+// is not a node binary and spawning it with a script path silently fails.
+// Same failure class the opencode live smoke caught on 2026-06-11.
+const NODE_BIN = basename(process.execPath).startsWith("node") ? process.execPath : "node";
+
+export default function (pi: ExtensionAPI) {
+  const root = process.cwd();
+
+  function runAdapter(adapterScript: string, eventName: string, hookId: string, relScript: string): { allow: boolean; context?: string; reason?: string } {
+    const adapterPath = join(root, "scripts", "hooks", adapterScript);
+    const payload = JSON.stringify({ hook_event_name: eventName, cwd: root });
+    const result = spawnSync(NODE_BIN, [adapterPath, eventName, hookId, relScript, "default"], {
+      input: payload,
+      encoding: "utf8",
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_HOOK_RUNTIME: "pi" },
+      timeout: 30000,
+    });
+    try {
+      return JSON.parse(result.stdout || "{}") as { allow: boolean; context?: string; reason?: string };
+    } catch {
+      return { allow: true };
+    }
+  }
+
+  function runTelemetry(eventName: string): void {
+    const telemetryPath = join(root, "scripts", "hooks", "pi-telemetry-hook.js");
+    const payload = JSON.stringify({ hook_event_name: eventName, cwd: root });
+    spawnSync(NODE_BIN, [telemetryPath, eventName, "dev"], {
+      input: payload,
+      encoding: "utf8",
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_TELEMETRY_RUNTIME: "pi" },
+      timeout: 10000,
+    });
+  }
+
+  pi.on("session_start", async (_event, _ctx) => {
+    runTelemetry("session_start");
+  });
+
+  pi.on("before_agent_start", async (event, _ctx) => {
+    // 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) {
+      return {
+        systemPrompt: event.systemPrompt + "\\n\\n" + result.context,
+      };
+    }
+  });
+
+  pi.on("tool_call", async (event, _ctx) => {
+    runTelemetry("tool_call");
+    const result = runAdapter("pi-hook-adapter.js", "tool_call", "config-protection", "config-protection.js");
+    if (result && result.allow === false) {
+      return { block: true, reason: result.reason || "Blocked by Flow Agents hook policy." };
+    }
+  });
+
+  pi.on("tool_result", async (_event, _ctx) => {
+    runTelemetry("tool_result");
+    runAdapter("pi-hook-adapter.js", "tool_result", "quality-gate", "quality-gate.js");
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    runTelemetry("session_shutdown");
+    runAdapter("pi-hook-adapter.js", "session_shutdown", "stop-goal-fit", "stop-goal-fit.js");
+  });
+}
+`;
+}
+function buildPi(agents) {
+    const bundle = path.join(dist, "pi");
+    resetDir(bundle);
+    copySharedContent(bundle, "pi", "<bundle-root>");
+    writeText(path.join(bundle, manifest.pi.task_dir, ".gitkeep"), "");
+    // pi has no named-subagent registry; agents are left canonical/unexported.
+    // Skills are exported to .pi/skills/ (direct .md files supported in that dir).
+    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
+        const skillPath = path.join(root, "skills", skill, "SKILL.md");
+        if (fs.existsSync(skillPath))
+            writeText(path.join(bundle, ".pi/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "pi", "<bundle-root>"));
+    }
+    writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
+    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
+    writeText(path.join(bundle, "README.md"), exportTargetReadme("pi", "bash install.sh /path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("pi", "/path/to/workspace"));
+    fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
+}
 function buildCatalog(agents) {
     const kitsCatalog = path.join(root, "kits/catalog.json");
     return {
@@ -379,6 +660,8 @@ export function main() {
     buildKiro(agents);
     buildClaudeCode(agents);
     buildCodex(agents);
+    buildOpencode(agents);
+    buildPi(agents);
     writeText(path.join(dist, "catalog.json"), `${JSON.stringify(buildCatalog(agents), null, 2)}\n`);
     writeText(path.join(dist, "README.md"), "# Universal Bundles\n\nRun `npm run build:bundles` from the repo root to regenerate these bundles.\n");
     console.log("Built bundles:");
@@ -386,6 +669,8 @@ export function main() {
     console.log(" - dist/kiro");
     console.log(" - dist/claude-code");
     console.log(" - dist/codex");
+    console.log(" - dist/opencode");
+    console.log(" - dist/pi");
     if (printDiagnostics && dropDiagnostics.length) {
         console.error("Export sanitization diagnostics:");
         for (const item of dropDiagnostics)

package/build/src/tools/filter-installed-packs.js

@@ -108,10 +108,13 @@ export function main(argv = process.argv.slice(2)) {
     removed += pruneNamedDirs(rootDir, "skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, ".claude/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, ".codex/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".opencode/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".pi/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, "powers", allPackMembers(packs, "powers"), selected.powers, dryRun);
     removed += pruneAgentFiles(rootDir, "agents", ".json", allPackMembers(packs, "agents"), selected.agents, dryRun);
     removed += pruneAgentFiles(rootDir, ".claude/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
     removed += pruneAgentFiles(rootDir, ".codex/agents", ".toml", allPackMembers(packs, "agents"), selected.agents, dryRun);
+    removed += pruneAgentFiles(rootDir, ".opencode/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
     const summary = {
         selected_packs: [...selectedNames].sort(),
         removed_entries: removed,

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

@@ -62,6 +62,10 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/run-hook.js", { category: "hook runner", requiredNeedles: ["isHookEnabled", "Path traversal rejected"] }],
     ["scripts/hooks/config-protection.js", { category: "policy hook", requiredNeedles: ["Config Protection Hook"] }],
     ["scripts/hooks/governance-audit.sh", { category: "policy hook", requiredNeedles: ["governance-audit.sh", "audit_emit"] }],
+    ["scripts/hooks/opencode-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["opencode", "run-hook.js"] }],
+    ["scripts/hooks/opencode-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["opencode", "telemetry"] }],
+    ["scripts/hooks/pi-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["pi", "run-hook.js"] }],
+    ["scripts/hooks/pi-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["pi", "telemetry"] }],
     ["scripts/hooks/post-edit-accumulator.js", { category: "policy hook", requiredNeedles: ["Post-Edit"] }],
     ["scripts/hooks/pre-commit-quality.js", { category: "repo guardrail hook", requiredNeedles: ["staged"] }],
     ["scripts/hooks/quality-gate.js", { category: "policy hook", requiredNeedles: ["Quality"] }],
@@ -95,7 +99,7 @@ const requiredUsageFeedbackFiles = [
 const fixtureOwnershipSelfAuditRefs = new Set([
     "evals/integration/test_fixture_retirement_audit.sh",
 ]);
-const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build"]);
+const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build", "integrations"]);
 const pythonCommandScanRoots = ["README.md", "docs", "context", "skills", "prompts", "agents", "evals", "scripts", "packaging", "package.json"];
 const allowedPythonCommandFiles = [
     /^agents\/tool-explore-deps\.json$/,

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/context/scripts/telemetry/lib/config.sh

@@ -6,7 +6,11 @@ TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}
 
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../../.." && pwd)/.telemetry}"
+# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
+# two levels up. Three levels escaped into the workspace's PARENT directory
+# (caught by live acceptance smoke 2026-06-11: events landed in /tmp/.telemetry
+# instead of the installed workspace).
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"

package/context/settings/flow-agents-settings.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../schemas/flow-agents-settings.schema.json",
+  "schema_version": "1.0",
+  "utteranceCheck": {
+    "enabled": false
+  }
+}

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/context-map.md

@@ -50,6 +50,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents
 | Schema | Title | ID |
 | --- | --- | --- |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
+| flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |
 | workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
 | workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
 | workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |