kc-beta 0.6.2 → 0.7.1

package/src/cli/index.js

@@ -76,6 +76,13 @@ function App({ engine, config }) {
   }, []);
 
   const addMessage = useCallback((msg) => {
+    // v0.7.0 H6: dismiss welcome banner once any real message lands.
+    // The banner state was initialized true and never set false — the
+    // banner stayed on every frame for the entire session, eating
+    // permanent screen real estate. Conditionally clear on first
+    // user/agent/tool-result message; system-only messages don't
+    // dismiss (they're often just the banner-side info itself).
+    if (msg && msg.role !== "system") setShowWelcome(false);
     setMessages((prev) => {
       if (prev.length < MAX_RETAINED_MESSAGES) return [...prev, msg];
       // Cap hit: drop the oldest non-system entry. If everything is system
@@ -385,7 +392,16 @@ function App({ engine, config }) {
         const sched = new Scheduler(engineRef.current.workspace);
         const jobs = sched.list();
         if (jobs.length === 0) {
-          addMessage({ role: "system", content: "No scheduled ingestion jobs. Ask KC to set one up via the schedule_fetch tool." });
+          // v0.6.3.1: also surface pending input files. The welcome banner
+          // tells the user "run /schedule for details" when input/ has
+          // unseen files, but the no-jobs branch used to ignore those —
+          // user got a dead-end "no jobs" reply with the files invisible.
+          const pending = sched.pendingInputCount();
+          const tail = sched.tailLog(8);
+          let body = "No scheduled ingestion jobs. Ask KC to set one up via the schedule_fetch tool.";
+          if (pending > 0) body += `\n\nPending in input/: ${pending} file(s) (drop into workspace input/ to be picked up).`;
+          if (tail) body += `\n\nlogs/ingest.log (last 8):\n${tail}`;
+          addMessage({ role: "system", content: body });
         } else {
           const lines = jobs.map((j) => {
             const status = j.enabled ? "✓ enabled" : "· disabled";
@@ -423,6 +439,11 @@ function App({ engine, config }) {
         streamingRef.current = true;
         setStreaming(true);
         setSpinnerStatus("Compacting...");
+        // v0.7.0 H7: top-level .catch on the IIFE — the inner try/catch
+        // handles the compact() failure path; this tail .catch silences
+        // any secondary rejection from the catch handler or finally
+        // block (e.g., addMessage throw). Without it, those would be
+        // UnhandledPromiseRejection in strict-mode Node.
         (async () => {
           try {
             const result = await engineRef.current.compact();
@@ -469,7 +490,7 @@ function App({ engine, config }) {
               runTurn(next);
             }
           }
-        })();
+        })().catch(() => { /* H7 defensive tail */ });
         return true;
       }
 
@@ -528,6 +549,10 @@ function App({ engine, config }) {
           }
         } else {
           // Resume a previous session
+          // v0.7.0 H8: top-level .catch on the IIFE so a throw inside
+          // addMessage()/setMessages() (e.g., during the catch handler
+          // itself, or in Ink reconciler) doesn't surface as an
+          // UnhandledPromiseRejection that crashes Node strict-mode.
           (async () => {
             try {
               const client = new LLMClient({
@@ -541,6 +566,17 @@ function App({ engine, config }) {
               setSessionId(resumed.workspace.sessionId);
               setPhase(resumed.currentPhase);
               setMessages([]);
+              // v0.7.0 F2: re-populate TaskBoard state from the resumed
+              // engine's TaskManager. Without this, the TUI showed an
+              // empty task list after /resume even when tasks.json on
+              // disk had pending work. The setTaskList path mirrors what
+              // the per-event tasks_progress handler does for live
+              // sessions.
+              try {
+                const tasks = resumed.taskManager.getAllTasks();
+                setTaskList(tasks);
+                setTaskProgress(resumed.taskManager.progress);
+              } catch { /* taskManager unavailable on very old session-state */ }
               addMessage({
                 role: "system",
                 content:
@@ -552,7 +588,8 @@ function App({ engine, config }) {
             } catch (err) {
               addMessage({ role: "system", content: `Resume failed: ${err.message}` });
             }
-          })();
+          })().catch(() => { /* defended above; tail catch silences any
+            secondary rejection from the catch handler itself */ });
         }
         return true;
 
@@ -562,6 +599,13 @@ function App({ engine, config }) {
         try { engineRef.current.saveState(); } catch { /* ignore */ }
         try { engineRef.current.stop(); } catch { /* ignore */ }
         exit();
+        // v0.6.3.1: force-exit after a brief grace window. Ink's exit()
+        // unmounts the TUI but in-flight LLM streams / subagent fetches
+        // / unflushed appendFileSync handles can keep the Node event loop
+        // alive indefinitely on long sessions. The 500ms gives saveState
+        // and any synchronous flushes time to complete; after that we
+        // hard-exit so the user's terminal returns to the shell promptly.
+        setTimeout(() => process.exit(0), 500).unref();
         return true;
 
       default:
@@ -756,9 +800,24 @@ export async function main({ languageOverride } = {}) {
 
   // Save state on process exit + stop background diagnostics (B0.1 heap
   // sampler). saveState is idempotent; stop() is safe to call twice.
+  //
+  // v0.6.3.1: handler must terminate. Pre-fix it only saved + returned, which
+  // overrides Node's default SIGINT behavior — the process kept running with
+  // active LLM streams / subagent fetches keeping the event loop alive, and
+  // mashing ^C did nothing visible. Now: first ^C saves and tries clean exit
+  // after 500ms; second ^C hard-kills with no further saves.
+  let interruptCount = 0;
   const saveOnExit = () => {
+    interruptCount++;
+    if (interruptCount >= 2) {
+      // Second interrupt — user wants out NOW
+      process.stderr.write("\nForce-exiting (second interrupt).\n");
+      process.exit(130); // 128 + SIGINT
+    }
     try { engine.saveState(); } catch { /* ignore */ }
     try { engine.stop(); } catch { /* ignore */ }
+    process.stderr.write("\nReceived interrupt — saving state, then exiting in 500ms (press again to force).\n");
+    setTimeout(() => process.exit(130), 500).unref();
   };
   process.on("SIGINT", saveOnExit);
   process.on("SIGTERM", saveOnExit);

package/src/cli/meme.js

@@ -1,32 +1,34 @@
-import React, { useState } from "react";
+// AUTO-GENERATED by scripts/build-meme.js — DO NOT EDIT BY HAND.
+// Source of truth lives in src/cli/meme.source.js.
+//
+// v0.7.0 Group K2: the textual easter-egg payload (lyrics, team
+// handles, watermark) is XOR-encoded + base64 in BLOB below. The
+// decoder is intentionally simple — the goal is to defeat grep-based
+// plagiarism scraping, not to provide cryptographic protection.
+// Determined reverse-engineering can recover the data; the watermark
+// survives and identifies origin in any copies. Please leave it in.
+
+import React from "react";
 import { Box, Text, useInput } from "ink";
 
 const h = React.createElement;
 
-// F6: /meme easter egg. Intentionally not listed in /help — discovery
-// is the point. Press ESC or Enter to dismiss. Content per the v0.6.0
-// plan (item 15) — lyrics + team credit.
+const _K = Buffer.from([
+  0x4b, 0x43, 0x37, 0x31, 0x2a, 0x68, 0x61, 0x72, 0x6e, 0x65, 0x73, 0x73, 0x2a, 0x66, 0x61, 0x74,
+]);
+const _BLOB = "MGFbSFgBAgFMXyhRY0ENGGs0VlheSAAcCkUAHEUIQ1hpFFIWWA1BARoXEh1OAwVUJC0XRUINQRALBBAbCEpDPSVjWERYSAUACwQeUQZENhFrM1ZDXkgVHQFFABxFCENYaQFCRQoBD1IBEAFTRg8EB2lvFWVCDRMXSRZTEgoSEwE/KxdFRUgHGwABUV8IMgkRayZZVQoBElIAAARRBkQgVD8sWl5YGg4FThIWU0cTEgBrMVJQSQBBFAEXUV8IMg5UKSYXWU8JExZMOF9RXgMAGWl5bBNqWFA0BxYbUQZEITUmJltYS0pNUC4kHQBPCiobKCZZEwZKITMaFxYGWURNVgsAVkNFBAgcCyYhPwhKQzQPKkFYWQEOHCoMARZJEg4GEzYVHQgoJgAPBhY0XwlDWGkDcENPDQ89HAQdFE9ETVYLC1ZdTCVDXkwlGBpeBQkRJW5SX00BDxcLF0dBCEpDNAcqW0hiHQAcCUdfUWorAAY+KFgTBkohIwcEHR9DCghWZ2F3QkUGBh8PClFfCCYVHC4sWRMGSiEqBwIGEghKQzQTGseupvdDXkwlChtCC0NYaQNNXk8SDhdMSVEzUB8ZACMmQ0NFBA1QM0lRBEsSBAYmIkVaCFJDOS1FscQKNg4YMgVYQ0dILx0ABhweRwMTFyIiWxEbRlFcXkWxxAqkyFQGJlpYXwVBXU4OGgdJDgQaZiZZVkMGBBccUUFT6NFBHD83R0IQR04VBxEbBkhIAhsmbFxYXgsJFwBIFh1NDw8RLjEDAwUDAl8NCRpRVw==";
 
-const LYRICS = [
-  "I'll wait and soon",
-  "We're stranded on the beach",
-  "In our dream",
-  "We part too soon",
-  "But in our lies",
-  "There's a truth to find",
-  "The end is new",
-  "A tomorrow we must reach for",
-  "To be heard",
-];
+function _decode() {
+  const buf = Buffer.from(_BLOB, "base64");
+  const out = Buffer.alloc(buf.length);
+  for (let i = 0; i < buf.length; i++) out[i] = buf[i] ^ _K[i % _K.length];
+  return JSON.parse(out.toString("utf-8"));
+}
 
-const TEAM = [
-  "@kitchen-engineer42", "@Xigua", "@Amelia", "@01Fish",
-  "@zyxthetroll", "@theon", "@DivisionDirectorXu",
-  "@AnselKocen", "@CarolineCRL", "@GraceGuo",
-  "@XY🌟", "@HalfM", "@GreenOrange",
-  "@LilyHuang", "@Qianlili", "@songmao",
-  "@zoezoe", "@yhhm",
-];
+const _payload = _decode();
+const LYRICS = _payload.lyrics;
+const TEAM = _payload.team;
+const __KC_MEME_WATERMARK__ = _payload.watermark;
 
 export function MemeOverlay({ onDismiss }) {
   useInput((input, key) => {
@@ -34,7 +36,6 @@ export function MemeOverlay({ onDismiss }) {
   });
 
   return h(Box, { flexDirection: "column", borderStyle: "round", borderColor: "magenta", paddingLeft: 2, paddingRight: 2, paddingTop: 1, paddingBottom: 1, marginTop: 1, marginBottom: 1 },
-    // Lyrics block
     h(Box, { flexDirection: "column" },
       ...LYRICS.map((line, i) =>
         h(Text, { key: `l-${i}`, color: "cyan", italic: true }, line),
@@ -43,7 +44,6 @@ export function MemeOverlay({ onDismiss }) {
     h(Text, null, ""),
     h(Text, { dimColor: true }, "─".repeat(60)),
     h(Text, null, ""),
-    // Team credit
     h(Text, { color: "yellow", bold: true },
       "Here's to all the smart minds that are/were part of our team:"),
     h(Text, null, ""),
@@ -54,5 +54,6 @@ export function MemeOverlay({ onDismiss }) {
     ),
     h(Text, null, ""),
     h(Text, { dimColor: true }, "Press ESC or Enter to dismiss."),
+    h(Text, { dimColor: true }, __KC_MEME_WATERMARK__),
   );
 }

package/src/config.js

@@ -23,8 +23,20 @@ function loadGlobalConfig() {
  */
 function loadEnvFile(envPath) {
   if (!fs.existsSync(envPath)) return {};
+  // v0.7.0 H9: defend bootstrap against a .env that exists but isn't
+  // readable (permission denied, unexpected directory, encoding error,
+  // race with concurrent write). Old code threw and crashed config
+  // bootstrap before the CLI was even up — return empty {} on any
+  // read failure so the user sees the more actionable
+  // "no API key configured" error from loadSettings instead.
+  let raw;
+  try {
+    raw = fs.readFileSync(envPath, "utf-8");
+  } catch {
+    return {};
+  }
   const env = {};
-  const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+  const lines = raw.split("\n");
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith("#")) continue;
@@ -51,8 +63,13 @@ export function loadSettings(workspacePath) {
   const gc = loadGlobalConfig();
   const env = workspacePath ? loadEnvFile(path.join(workspacePath, ".env")) : {};
 
+  // Session-scoped overrides (process.env). Internal knob for benchmarking
+  // — lets a single launch swap conductor/workspace/context without touching
+  // ~/.kc_agent/config.json. Not exposed in --help or onboard.
+  const penv = process.env;
+
   // Resolve provider metadata for authType/apiFormat defaults
-  const provider = gc.provider || "siliconflow";
+  const provider = penv.KC_PROVIDER || gc.provider || "siliconflow";
   const providerDef = getProviderById(provider);
 
   const settings = {
@@ -61,10 +78,10 @@ export function loadSettings(workspacePath) {
     authType: gc.auth_type || providerDef?.authType || "bearer",
     apiFormat: gc.api_format || providerDef?.apiFormat || "openai",
 
-    // Conductor LLM (generic keys with legacy fallback)
-    llmApiKey: env.LLM_API_KEY || env.SILICONFLOW_API_KEY || gc.api_key || "",
-    llmBaseUrl: env.LLM_BASE_URL || env.SILICONFLOW_BASE_URL || gc.base_url || "https://api.siliconflow.cn/v1",
-    kcModel: gc.conductor_model || "glm-5",
+    // Conductor LLM (process.env wins → workspace .env → global config)
+    llmApiKey: penv.KC_LLM_API_KEY || env.LLM_API_KEY || env.SILICONFLOW_API_KEY || gc.api_key || "",
+    llmBaseUrl: penv.KC_LLM_BASE_URL || env.LLM_BASE_URL || env.SILICONFLOW_BASE_URL || gc.base_url || "https://api.siliconflow.cn/v1",
+    kcModel: penv.KC_CONDUCTOR_MODEL || gc.conductor_model || "glm-5",
     kcMaxTokens: parseInt(env.KC_MAX_TOKENS || gc.kc_max_tokens?.toString() || "65536", 10),
 
     // Tier models (from .env or global config tiers)
@@ -78,10 +95,10 @@ export function loadSettings(workspacePath) {
     vlmTier2: env.VLM_TIER2 || gc.vlm_tiers?.tier2 || "",
     vlmTier3: env.VLM_TIER3 || gc.vlm_tiers?.tier3 || "",
 
-    // Worker LLM — optional, defaults to conductor config
-    workerProvider: gc.worker_provider || "",
-    workerApiKey: env.WORKER_API_KEY || gc.worker_api_key || "",
-    workerBaseUrl: env.WORKER_BASE_URL || gc.worker_base_url || "",
+    // Worker LLM — optional, defaults to conductor config (process.env wins)
+    workerProvider: penv.KC_WORKER_PROVIDER || gc.worker_provider || "",
+    workerApiKey: penv.KC_WORKER_API_KEY || env.WORKER_API_KEY || gc.worker_api_key || "",
+    workerBaseUrl: penv.KC_WORKER_BASE_URL || env.WORKER_BASE_URL || gc.worker_base_url || "",
     workerAuthType: gc.worker_auth_type || "",
     workerApiFormat: gc.worker_api_format || "",
 
@@ -89,8 +106,8 @@ export function loadSettings(workspacePath) {
     mineruApiUrl: env.MINERU_API_URL || "",
     mineruApiKey: env.MINERU_API_KEY || "",
 
-    // Workspace
-    kcWorkspaceRoot: gc.workspace_root || path.join(os.homedir(), ".kc_agent", "workspaces"),
+    // Workspace (process.env wins — for parallel benchmark runs)
+    kcWorkspaceRoot: penv.KC_WORKSPACE_ROOT || gc.workspace_root || path.join(os.homedir(), ".kc_agent", "workspaces"),
     kcExecTimeout: parseInt(env.KC_EXEC_TIMEOUT || "30", 10),
 
     // Accuracy thresholds
@@ -110,16 +127,42 @@ export function loadSettings(workspacePath) {
     tavilyApiKey: env.TAVILY_API_KEY || gc.tavily_api_key || "",
 
     // Context management — A2: prefer per-provider cap from providers.js
-    // over the generic 200000 default. KC_CONTEXT_LIMIT env still wins.
-    // gc.kc_context_limit (global config) is next. Then provider.contextLimit.
-    // Then a safe 200000 fallback for unknown/custom providers.
-    kcContextLimit: parseInt(
-      env.KC_CONTEXT_LIMIT ||
-        gc.kc_context_limit?.toString() ||
-        providerDef?.contextLimit?.toString() ||
-        "200000",
-      10,
-    ),
+    // over the generic 200000 default. process.env.KC_CONTEXT_LIMIT wins
+    // (session-scoped override for benchmarking long-context models without
+    // editing global config), then workspace .env, then global config, then
+    // provider.contextLimit, then a safe 200000 fallback.
+    //
+    // v0.7.0 E3 (#96): providerContextCap is the deployment hard ceiling
+    // (e.g., SiliconFlow's GLM-5.1 caps at 202_752 despite the model's
+    // native 1M). Effective contextLimit = min(user-requested,
+    // providerContextCap). E2E #5 GLM hit HTTP 413 because user set
+    // KC_CONTEXT_LIMIT=400000 but the deployment refused at ~203k.
+    // The cap is applied AFTER user-priority resolution so the user
+    // can't accidentally bypass it.
+    kcContextLimit: (() => {
+      const requested = parseInt(
+        penv.KC_CONTEXT_LIMIT ||
+          env.KC_CONTEXT_LIMIT ||
+          gc.kc_context_limit?.toString() ||
+          providerDef?.contextLimit?.toString() ||
+          "200000",
+        10,
+      );
+      const cap = providerDef?.providerContextCap;
+      if (typeof cap === "number" && cap > 0 && requested > cap) {
+        // Surface a one-time warning so users notice the clamp without
+        // burying it in events.jsonl.
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[config] KC_CONTEXT_LIMIT=${requested} clamped to ${cap} ` +
+          `(provider ${providerDef.id} hardCap). E2E #5 hit HTTP 413 at ` +
+          `~203k on SiliconFlow GLM-5.1; cap protects against deployment ` +
+          `hard-ceiling rejections.`,
+        );
+        return cap;
+      }
+      return requested;
+    })(),
     toolOutputOffloadTokens: parseInt(env.TOOL_OUTPUT_OFFLOAD_TOKENS || gc.tool_output_offload_tokens?.toString() || "2000", 10),
     toolOutputOffloadErrorTokens: parseInt(env.TOOL_OUTPUT_OFFLOAD_ERROR_TOKENS || gc.tool_output_offload_error_tokens?.toString() || "500", 10),
     maxMessageTokens: parseInt(env.MAX_MESSAGE_TOKENS || gc.max_message_tokens?.toString() || "60000", 10),

package/src/model-tiers.json

@@ -139,18 +139,34 @@
     }
   },
 
+  "tencent": {
+    "_comment": "Tencent Hunyuan via Lkeap plan endpoint. hy3-preview is the hidden flagship (not in /models listing but accepts requests). hunyuan-t1 is a thinking model — if used as conductor, ensure v0.6.3.1 reasoning_content roundtrip is in place.",
+    "conductor": "hy3-preview",
+    "llm": {
+      "tier1": "hy3-preview, hunyuan-t1",
+      "tier2": "hunyuan-turbos, hunyuan-2.0-thinking",
+      "tier3": "hunyuan-2.0-instruct, tc-code-latest",
+      "tier4": "tc-code-latest"
+    },
+    "vlm": {
+      "tier1": "",
+      "tier2": "",
+      "tier3": ""
+    }
+  },
+
   "xiaomi": {
-    "_comment": "Xiaomi MiMo coding plan — flagship Pro + standard + multimodal Omni. Native 1M context but KC caps to 200K. TTS variants excluded (no KC use case).",
-    "conductor": "MiMo-V2.5-Pro",
+    "_comment": "Xiaomi MiMo coding plan — flagship Pro + standard + multimodal Omni. Native 1M context but KC caps to 200K. TTS variants excluded (no KC use case). Endpoint normalizes IDs to lowercase — must match exactly.",
+    "conductor": "mimo-v2.5-pro",
     "llm": {
-      "tier1": "MiMo-V2.5-Pro",
-      "tier2": "MiMo-V2.5",
-      "tier3": "MiMo-V2-Pro",
-      "tier4": "MiMo-V2-Pro"
+      "tier1": "mimo-v2.5-pro",
+      "tier2": "mimo-v2.5",
+      "tier3": "mimo-v2-pro",
+      "tier4": "mimo-v2-pro"
     },
     "vlm": {
-      "tier1": "MiMo-V2-Omni",
-      "tier2": "MiMo-V2-Omni",
+      "tier1": "mimo-v2-omni",
+      "tier2": "mimo-v2-omni",
       "tier3": ""
     }
   },

package/src/providers.js

@@ -47,6 +47,14 @@ const PROVIDERS = [
     apiFormat: "openai",
     modelsEndpoint: "/models",
     contextLimit: 200000, // GLM-5.1, Kimi-K2.5 — 200K native
+    // v0.7.0 E3 (#96): provider hardCap. SiliconFlow's GLM-5.1
+    // deployment caps prompts at ~202,752 tokens despite the model's
+    // native 1M — E2E #5 GLM hit HTTP 413 at 203,363 tokens with
+    // KC_CONTEXT_LIMIT=400000 set. providerContextCap protects against
+    // user-set context limits exceeding the deployment hard ceiling.
+    // Effective limit becomes min(providerContextCap, modelContextLimit,
+    // KC_CONTEXT_LIMIT). When undefined, no provider cap applied.
+    providerContextCap: 200000,
     defaultModel: getTierConfig("siliconflow").conductor || "glm-5",
     defaultTiers: getTierConfig("siliconflow").llm,
     defaultVlm: getTierConfig("siliconflow").vlm,
@@ -256,6 +264,40 @@ const PROVIDERS = [
       zh: "小米 MiMo（V2.5 系列，编程计划）",
     },
   },
+  {
+    // Tencent Hunyuan via the Lkeap "plan" coding-token endpoint. The /models
+    // endpoint exposes a multi-vendor menu (glm-5.x, kimi-k2.5, minimax,
+    // hunyuan-*, tc-code-latest); hy3-preview is a hidden flagship that
+    // accepts requests but doesn't appear in /models. Curated list reflects
+    // what was advertised + the preview model the user has access to.
+    id: "tencent",
+    name: "Tencent Hunyuan",
+    baseUrl: "https://api.lkeap.cloud.tencent.com/plan/v3",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    supportsCodingPlanKey: true,
+    contextLimit: 200000, // hy3-preview is officially 256K; keep below cap with margin
+    defaultModel: getTierConfig("tencent").conductor || "hy3-preview",
+    defaultTiers: getTierConfig("tencent").llm,
+    defaultVlm: getTierConfig("tencent").vlm,
+    curatedModels: [
+      { id: "hy3-preview", ownedBy: "tencent" }, // hidden flagship
+      { id: "hunyuan-t1", ownedBy: "tencent" }, // thinking model
+      { id: "hunyuan-turbos", ownedBy: "tencent" },
+      { id: "hunyuan-2.0-thinking", ownedBy: "tencent" },
+      { id: "hunyuan-2.0-instruct", ownedBy: "tencent" },
+      { id: "tc-code-latest", ownedBy: "tencent" },
+      // Multi-vendor pass-throughs on the same plan key:
+      { id: "glm-5.1", ownedBy: "system" },
+      { id: "kimi-k2.5", ownedBy: "system" },
+      { id: "minimax-m2.7", ownedBy: "system" },
+    ],
+    labels: {
+      en: "Tencent Hunyuan (Lkeap plan)",
+      zh: "腾讯混元（Lkeap 编程计划）",
+    },
+  },
   {
     id: "openrouter",
     name: "OpenRouter",

package/template/release/v1/README.md.tmpl

@@ -0,0 +1,108 @@
+# KC Verification Release — v1
+
+This bundle is a self-contained verification system produced by KC's
+finalization phase. It runs without KC's CLI installed.
+
+## Project
+
+- **Generated by**: KC v{{kc_version}}
+- **Session**: `{{session_id}}`
+- **Generated at**: {{generated_at}}
+- **Rules**: {{rule_count}}
+- **Workflows**: {{workflow_count}}
+
+## What this does
+
+{{project_description}}
+
+## How to run
+
+### Prerequisites
+
+```
+python3 >= 3.9
+# Optional native parsers (recommended; falls back to LibreOffice if missing):
+pip install pypdf python-docx
+```
+
+### Single-document smoke test
+
+```bash
+python3 run.py --doc /path/to/document.pdf
+```
+
+### Full batch
+
+```bash
+python3 run.py /path/to/input_dir/
+# results land in output/results/<doc_stem>.json
+# summary in output/results/summary.json
+```
+
+### Filter by rule
+
+```bash
+python3 run.py /path/to/input_dir/ --rules R001,R005,R012
+```
+
+### Render dashboard
+
+```bash
+python3 render_dashboard.py output/results/ > dashboard.html
+./serve.sh           # http://localhost:8765/dashboard.html
+```
+
+## Layout
+
+```
+release/v1/
+├── run.py                      # entry point
+├── render_dashboard.py         # HTML dashboard renderer
+├── serve.sh                    # local http server shim
+├── manifest.json               # populated bundle manifest
+├── catalog.json                # populated rule catalog
+├── confidence_calibration.json # historical accuracy per rule (for confidence calibration)
+├── README.md                   # this file
+├── kc_runtime/
+│   ├── __init__.py
+│   ├── doc_parser.py           # PDF/DOCX/TXT → text
+│   └── confidence.py           # calibration helpers
+└── workflows/
+    └── <rule_id>/workflow_v1.py
+```
+
+## Workflow contract
+
+Each `workflows/<rule_id>/workflow_v1.py` is a standalone Python script:
+
+- Takes a document path on `sys.argv[1]`
+- Emits a single JSON line on stdout containing the verdict
+- Exit code 0 on success, non-zero on workflow-internal error
+
+Verdict shape:
+
+```json
+{
+  "rule_id": "R001",
+  "verdict": "PASS|FAIL|PARTIAL|NOT_APPLICABLE|UNDETERMINED|ERROR",
+  "confidence": 0.0,
+  "reason": "human-readable explanation",
+  "evidence": ["snippet 1", "snippet 2"]
+}
+```
+
+## Known limitations
+
+{{known_limitations}}
+
+## License
+
+This bundle is licensed under the same terms as KC itself
+(PolyForm Noncommercial 1.0.0). For commercial use, see KC's
+LICENSE-COMMERCIAL.md.
+
+---
+
+*Re-running this bundle on a new document set is the recommended path.
+For methodology changes (new rules, threshold tuning), re-run KC's
+distillation + production_qc phases and re-emit a fresh release.*

package/template/release/v1/catalog.json.tmpl

@@ -0,0 +1,4 @@
+[
+  /* Populated by KC finalization from rules/catalog.json. Each entry: */
+  /* { "id": "R001", "title": "...", "description": "...", "source_ref": "..." } */
+]

package/template/release/v1/kc_runtime/__init__.py

@@ -0,0 +1,11 @@
+"""KC release runtime — v1.
+
+Minimal Python helpers used by run.py to dispatch verification
+workflows. Designed to be drop-in self-contained: stdlib + a handful
+of optional native parsers (pypdf, python-docx) for document
+parsing. Falls back to plaintext + LibreOffice CLI if natives
+unavailable — never crashes the run on a missing dep.
+"""
+
+__version__ = "1.0.0"
+__all__ = ["doc_parser", "confidence"]

package/template/release/v1/kc_runtime/confidence.py

@@ -0,0 +1,63 @@
+"""
+Confidence calibration helpers for the release runtime.
+
+Workflows return raw verdicts with a self-reported confidence score.
+This module re-weights that score against the historical accuracy
+captured during KC's distillation phase, so users see calibrated
+confidence rather than the agent's prior. Falls back to identity
+when no calibration data is available.
+"""
+
+from __future__ import annotations
+
+
+def calibrate(verdict: dict, historical: dict) -> dict:
+    """
+    Adjust verdict["confidence"] using historical accuracy for the rule.
+
+    Schema for `historical`:
+        {
+          "historical_accuracy": {
+            "<rule_id>": {"accuracy": float in [0, 1], "n_samples": int},
+            ...
+          }
+        }
+
+    If the rule has no calibration data, the verdict is returned
+    unchanged. If the rule's accuracy is < 0.5 (worse than coin flip),
+    confidence is dampened by the calibration ratio. If accuracy is
+    high but n_samples is small, calibration trusts the raw score
+    more (avoid over-correcting on weak prior).
+    """
+    rule_id = verdict.get("rule_id")
+    if not rule_id:
+        return verdict
+
+    hist = historical.get("historical_accuracy", {}).get(rule_id)
+    if not hist:
+        return verdict
+
+    accuracy = float(hist.get("accuracy", 1.0))
+    n_samples = int(hist.get("n_samples", 0))
+
+    raw = float(verdict.get("confidence", 0.5))
+
+    # Bayesian-ish blend: weight raw confidence vs accuracy by n_samples.
+    # Small n → trust the raw score; large n → trust the prior more.
+    weight = min(0.5, n_samples / 100.0)
+    calibrated = raw * (1 - weight) + raw * accuracy * weight
+
+    out = dict(verdict)
+    out["confidence"] = round(calibrated, 4)
+    out["confidence_raw"] = raw
+    out["confidence_calibrated"] = True
+    return out
+
+
+def confidence_band(score: float) -> str:
+    """Map numeric score to a verbal band: high / medium / low."""
+    if score >= 0.8:
+        return "high"
+    if score >= 0.5:
+        return "medium"
+    return "low"