kc-beta 0.1.2 → 0.3.0

package/src/providers.js

@@ -0,0 +1,367 @@
+/**
+ * Provider registry for Multi-LLM support.
+ * Centralizes provider metadata, default models, and model classification.
+ *
+ * Model tier assignments (LLM + VLM) are loaded from model-tiers.json
+ * so they can be updated without touching code.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** @type {Record<string, {conductor: string, llm: Record<string,string>, vlm: Record<string,string>}>} */
+let MODEL_TIERS;
+try {
+  MODEL_TIERS = JSON.parse(
+    readFileSync(join(__dirname, "model-tiers.json"), "utf-8")
+  );
+} catch {
+  MODEL_TIERS = {};
+}
+
+/** Helper: get tier config for a provider, with fallbacks */
+function getTierConfig(providerId) {
+  return MODEL_TIERS[providerId] || { conductor: "", llm: {}, vlm: {} };
+}
+
+const PROVIDERS = [
+  {
+    id: "siliconflow",
+    name: "SiliconFlow",
+    baseUrl: "https://api.siliconflow.cn/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    defaultModel: getTierConfig("siliconflow").conductor || "glm-5",
+    defaultTiers: getTierConfig("siliconflow").llm,
+    defaultVlm: getTierConfig("siliconflow").vlm,
+    labels: {
+      en: "SiliconFlow (recommended for China)",
+      zh: "SiliconFlow（国内推荐）",
+    },
+  },
+  {
+    id: "aliyun",
+    name: "Aliyun",
+    // Coding plan URL — regular API uses dashscope.aliyuncs.com/compatible-mode/v1
+    baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    codingPlanUrl: "https://coding.dashscope.aliyuncs.com/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: null, // Aliyun coding plan doesn't support /models
+    supportsCodingPlanKey: true,
+    defaultModel: getTierConfig("aliyun").conductor || "qwen3.6-plus",
+    defaultTiers: getTierConfig("aliyun").llm,
+    defaultVlm: getTierConfig("aliyun").vlm,
+    // Curated model list (coding plan doesn't have /models endpoint)
+    curatedModels: [
+      { id: "qwen3.6-plus", ownedBy: "qwen" },
+      { id: "qwen3.5-plus", ownedBy: "qwen" },
+      { id: "qwen3-max-2026-01-23", ownedBy: "qwen" },
+      { id: "qwen3-coder-next", ownedBy: "qwen" },
+      { id: "qwen3-coder-plus", ownedBy: "qwen" },
+      { id: "glm-5", ownedBy: "zhipu" },
+      { id: "glm-4.7", ownedBy: "zhipu" },
+      { id: "kimi-k2.5", ownedBy: "kimi" },
+      { id: "MiniMax-M2.5", ownedBy: "minimax" },
+    ],
+    labels: {
+      en: "Aliyun Bailian",
+      zh: "阿里云百炼",
+    },
+  },
+  {
+    id: "volcanocloud",
+    name: "VolcanoCloud",
+    baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: null, // VolcanoCloud coding plan — use curated list
+    defaultModel: getTierConfig("volcanocloud").conductor || "doubao-seed-2-0-pro-260215",
+    defaultTiers: getTierConfig("volcanocloud").llm,
+    defaultVlm: getTierConfig("volcanocloud").vlm,
+    curatedModels: [
+      { id: "doubao-seed-2-0-pro-260215", ownedBy: "bytedance" },
+      { id: "deepseek-v3-2-251201", ownedBy: "deepseek" },
+      { id: "glm-4-7-251222", ownedBy: "zhipu" },
+      { id: "doubao-1-5-pro-32k-250115", ownedBy: "bytedance" },
+      { id: "doubao-seed-2-0-mini-260215", ownedBy: "bytedance" },
+      { id: "doubao-seed-2-0-lite-260215", ownedBy: "bytedance" },
+      { id: "doubao-1-5-lite-32k-250115", ownedBy: "bytedance" },
+    ],
+    labels: {
+      en: "VolcanoCloud (ByteDance)",
+      zh: "火山云（字节跳动）",
+    },
+  },
+  {
+    id: "anthropic",
+    name: "Anthropic",
+    baseUrl: "https://api.anthropic.com",
+    authType: "x-api-key",
+    apiFormat: "anthropic",
+    modelsEndpoint: null, // Use curated list
+    defaultModel: getTierConfig("anthropic").conductor || "claude-sonnet-4-20250514",
+    defaultTiers: getTierConfig("anthropic").llm,
+    defaultVlm: getTierConfig("anthropic").vlm,
+    curatedModels: [
+      { id: "claude-opus-4-20250514", ownedBy: "anthropic" },
+      { id: "claude-sonnet-4-20250514", ownedBy: "anthropic" },
+      { id: "claude-haiku-4-5-20251001", ownedBy: "anthropic" },
+    ],
+    labels: {
+      en: "Anthropic",
+      zh: "Anthropic",
+    },
+  },
+  {
+    id: "openai",
+    name: "OpenAI",
+    baseUrl: "https://api.openai.com/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    defaultModel: getTierConfig("openai").conductor || "gpt-4o",
+    defaultTiers: getTierConfig("openai").llm,
+    defaultVlm: getTierConfig("openai").vlm,
+    labels: {
+      en: "OpenAI",
+      zh: "OpenAI",
+    },
+  },
+  {
+    id: "zhipu",
+    name: "Zhipu/GLM",
+    baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    defaultModel: getTierConfig("zhipu").conductor || "glm-4-plus",
+    defaultTiers: getTierConfig("zhipu").llm,
+    defaultVlm: getTierConfig("zhipu").vlm,
+    labels: {
+      en: "Zhipu GLM",
+      zh: "智谱 GLM",
+    },
+  },
+  {
+    id: "minimax",
+    name: "MiniMax",
+    baseUrl: "https://api.minimax.chat/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    defaultModel: getTierConfig("minimax").conductor || "MiniMax-M2.5",
+    defaultTiers: getTierConfig("minimax").llm,
+    defaultVlm: getTierConfig("minimax").vlm,
+    labels: {
+      en: "MiniMax",
+      zh: "MiniMax",
+    },
+  },
+  {
+    id: "openrouter",
+    name: "OpenRouter",
+    baseUrl: "https://openrouter.ai/api/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    defaultModel: getTierConfig("openrouter").conductor || "anthropic/claude-sonnet-4-20250514",
+    defaultTiers: getTierConfig("openrouter").llm,
+    defaultVlm: getTierConfig("openrouter").vlm,
+    labels: {
+      en: "OpenRouter",
+      zh: "OpenRouter",
+    },
+  },
+  {
+    id: "bedrock",
+    name: "Bedrock",
+    baseUrl: "",
+    authType: "aws-sigv4",
+    apiFormat: "anthropic",
+    modelsEndpoint: null,
+    defaultModel: getTierConfig("bedrock").conductor || "anthropic.claude-sonnet-4-20250514-v1:0",
+    defaultTiers: getTierConfig("bedrock").llm,
+    defaultVlm: getTierConfig("bedrock").vlm,
+    labels: {
+      en: "AWS Bedrock (not yet supported)",
+      zh: "AWS Bedrock（暂未支持）",
+    },
+  },
+  {
+    id: "custom",
+    name: "Custom",
+    baseUrl: "",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    defaultModel: getTierConfig("custom").conductor || "",
+    defaultTiers: getTierConfig("custom").llm,
+    defaultVlm: getTierConfig("custom").vlm,
+    labels: {
+      en: "Custom (enter base URL)",
+      zh: "自定义（输入接口地址）",
+    },
+  },
+];
+
+/**
+ * Known model capability rankings (partial — used to sort discovered models).
+ * Pattern-matched against lowercase model ID. Higher = more capable.
+ * Aligned with kc_reborn providers.py _MODEL_RANKING.
+ */
+const MODEL_RANKING = {
+  // Anthropic
+  "claude-opus-4": 100,
+  "claude-sonnet-4": 90,
+  "claude-haiku-4": 70,
+  // OpenAI
+  "gpt-4o": 90,
+  "gpt-4o-mini": 70,
+  "gpt-4-turbo": 85,
+  "o1": 95,
+  "o3": 95,
+  // Qwen (Aliyun Bailian)
+  "qwen3.6-plus": 90,
+  "qwen3.5-plus": 85,
+  "qwen3-max": 88,
+  "qwen3-coder-next": 85,
+  "qwen3-coder-plus": 80,
+  "qwen-plus": 75,
+  "qwen-turbo": 60,
+  "qwen3.5-397b": 85,
+  "qwen3.5-122b": 75,
+  "qwen3.5-35b": 65,
+  // Zhipu
+  "glm-5": 90,
+  "glm-4.7": 80,
+  "glm-4": 75,
+  // Others
+  "kimi-k2.5": 85,
+  "kimi-k2": 80,
+  "minimax-m2": 80,
+  "deepseek-v3": 85,
+  "deepseek-r1": 90,
+  // VolcanoCloud (ByteDance Doubao)
+  "doubao-seed-2-0-pro": 90,
+  "doubao-seed-2-0-code": 88,
+  "doubao-seed-2-0-mini": 75,
+  "doubao-seed-2-0-lite": 65,
+  "doubao-seed-1-8": 85,
+  "doubao-seed-1-6": 80,
+  "doubao-1-5-pro": 80,
+  "doubao-1-5-lite": 60,
+};
+
+/**
+ * Estimate model capability rank (0-100) based on known patterns.
+ * @param {string} modelId
+ * @returns {number}
+ */
+function rankModel(modelId) {
+  const lower = modelId.toLowerCase();
+  for (const [pattern, rank] of Object.entries(MODEL_RANKING)) {
+    if (lower.includes(pattern)) return rank;
+  }
+  return 50; // Unknown model: assume mid-tier
+}
+
+/**
+ * Patterns to filter out non-chat models from discovery results.
+ */
+const EXCLUDE_PATTERNS = [
+  /embed/i, /tts/i, /whisper/i, /dall-e/i, /audio/i, /image/i,
+  /moderation/i, /rerank/i,
+];
+
+/** @returns {Array} All provider definitions */
+export function getProviders() {
+  return PROVIDERS;
+}
+
+/**
+ * @param {string} id - Provider ID
+ * @returns {object|undefined}
+ */
+export function getProviderById(id) {
+  return PROVIDERS.find((p) => p.id === id);
+}
+
+/**
+ * Get display labels for the onboard menu.
+ * @param {string} lang - "en" or "zh"
+ * @returns {Array<{id: string, label: string}>}
+ */
+export function getProviderLabels(lang) {
+  return PROVIDERS.map((p) => ({
+    id: p.id,
+    label: p.labels[lang] || p.labels.en || p.name,
+  }));
+}
+
+/**
+ * Classify a list of discovered models into tier assignments.
+ * Uses the same ranking-based approach as kc_reborn's propose_tiers().
+ *
+ * @param {Array<{id: string, name?: string}>} models - Models from /models endpoint or curated list
+ * @returns {{ conductor: string, tiers: {tier1: string, tier2: string, tier3: string, tier4: string}, unclassified: string[] }}
+ */
+export function classifyModels(models) {
+  // Filter out non-chat models
+  const chatModels = models.filter((m) => {
+    const name = m.id || m.name || "";
+    return !EXCLUDE_PATTERNS.some((re) => re.test(name));
+  });
+
+  // Rank and sort by capability
+  const ranked = [...chatModels].sort((a, b) => rankModel(b.id) - rankModel(a.id));
+
+  // Select conductor (highest ranked)
+  const conductor = ranked[0]?.id || "";
+
+  // Distribute across tiers by rank
+  const tierBuckets = { tier1: [], tier2: [], tier3: [], tier4: [] };
+
+  for (const m of ranked) {
+    const rank = rankModel(m.id);
+    if (rank >= 85) tierBuckets.tier1.push(m.id);
+    else if (rank >= 70) tierBuckets.tier2.push(m.id);
+    else if (rank >= 55) tierBuckets.tier3.push(m.id);
+    else tierBuckets.tier4.push(m.id);
+  }
+
+  const tiers = {
+    tier1: tierBuckets.tier1.slice(0, 3).join(", "),
+    tier2: tierBuckets.tier2.slice(0, 3).join(", "),
+    tier3: tierBuckets.tier3.slice(0, 2).join(", "),
+    tier4: tierBuckets.tier4.slice(0, 2).join(", "),
+  };
+
+  const unclassified = ranked.filter((m) => rankModel(m.id) === 50).map((m) => m.id);
+
+  return { conductor, tiers, unclassified };
+}
+
+/**
+ * Get curated models for providers that don't support /models endpoint.
+ * @param {string} providerId
+ * @returns {Array<{id: string, ownedBy: string}>|null}
+ */
+export function getCuratedModels(providerId) {
+  const provider = getProviderById(providerId);
+  return provider?.curatedModels || null;
+}
+
+/**
+ * Get the raw model tier config for a provider (from model-tiers.json).
+ * @param {string} providerId
+ * @returns {{ conductor: string, llm: Record<string,string>, vlm: Record<string,string> }}
+ */
+export function getModelTierConfig(providerId) {
+  return getTierConfig(providerId);
+}

package/template/AGENT.md

@@ -0,0 +1,20 @@
+# AGENT.md — Project Context
+
+This file is your per-project memory. Update it as you learn about the project.
+The content here is injected into your system prompt on every turn.
+
+## Project
+
+<!-- What domain? What regulations? What documents? Fill this in during bootstrap. -->
+
+## Decisions
+
+<!-- Key decisions made with the developer user. Rule granularity, accuracy targets, model choices, scope boundaries. -->
+
+## Domain Notes
+
+<!-- Terminology, document formats, naming conventions, edge cases specific to this domain. -->
+
+## User Preferences
+
+<!-- How the developer user prefers to communicate. Reporting format, language, level of detail. -->

package/template/skills/en/meta/compliance-judgment/SKILL.md

@@ -9,53 +9,17 @@ Judgment is the moment of truth. You have the extracted entity. You have the rul
 
 ## The Judgment Spectrum
 
-Rules fall on a spectrum from fully deterministic to fully semantic:
+Rules range from trivially deterministic to deeply semantic. Pick the right tool for each rule.
 
-### Deterministic Judgments (Use Python)
+**Deterministic** — threshold checks, format validation, date arithmetic, cross-field consistency. Pure Python: free, instant, deterministic.
 
-Rules with clear, computable criteria:
+**Semantic** — adequacy, completeness, consistency, compliance with templates, detecting misleading or suggestive language, assessing whether a description is fair and balanced. These require language understanding — use worker LLM.
 
-- **Threshold checks**: "The capital adequacy ratio must be >= 8%."
-  ```python
-  result = "pass" if extracted_ratio >= 8.0 else "fail"
-  ```
-- **Format validation**: "The loan number must match pattern XX-YYYY-ZZZZZZ."
-  ```python
-  result = "pass" if re.match(r"[A-Z]{2}-\d{4}-\d{6}", loan_number) else "fail"
-  ```
-- **Date arithmetic**: "The contract must be signed within 30 days of application."
-  ```python
-  result = "pass" if (sign_date - app_date).days <= 30 else "fail"
-  ```
-- **Cross-field consistency**: "The total must equal the sum of line items."
-  ```python
-  result = "pass" if abs(total - sum(items)) < 0.01 else "fail"
-  ```
+Many real compliance rules require semantic judgment. "The risk disclosure must adequately describe the key risks" cannot be checked with regex or Python. "The contract description must not be misleading or suggestive" requires deep language understanding. Use worker LLM for these without hesitation.
 
-These are best implemented as pure Python. They are free, instant, and deterministic. When possible, prefer this form.
+Some rules combine both: extract a number (deterministic), compare to threshold (deterministic), then assess the explanation if borderline (semantic). The mix depends on the rule.
 
-### Semantic Judgments (Use LLM)
-
-Rules requiring language understanding:
-
-- **Adequacy**: "The risk disclosure must adequately describe the key risks."
-- **Completeness**: "The management discussion must address financial performance, strategic outlook, and market conditions."
-- **Consistency**: "The executive summary must be consistent with the detailed findings."
-- **Compliance with template**: "The report must follow the format specified in Regulation Appendix A."
-
-For these, design an LLM prompt:
-1. Provide the rule text (what constitutes compliance).
-2. Provide the extracted content (what the document says).
-3. Ask for a structured verdict: pass/fail, reasoning, and comment.
-4. Ask the model to be conservative — flag as fail only when clearly non-compliant. When truly ambiguous, use a "partial" or "uncertain" result rather than a hard fail.
-
-### Hybrid Judgments (Most Common)
-
-Most rules combine deterministic and semantic elements:
-- Extract the number (regex) → compare to threshold (Python) → if borderline, assess the explanation (LLM).
-- Check that a section exists (deterministic) → check that it covers required topics (semantic).
-
-Design the pipeline to run cheap steps first. Only invoke the LLM when the deterministic check is insufficient.
+The right method is whatever achieves accuracy at lowest cost. Simple threshold checks don't need LLM. Semantic assessments don't benefit from Python. Most projects will have a mix — let the nature of each rule determine the method.
 
 ## Output Format
 
@@ -80,6 +44,10 @@ For each rule × document combination:
 - **error**: Something went wrong during extraction or judgment (parsing failure, API error). Needs investigation.
 - **uncertain**: The judgment is ambiguous. May need human review.
 
+**Design exit criteria first:** Before writing judgment logic for a rule, define the exit conditions: what constitutes pass, what constitutes fail, what triggers escalation to human, how to handle empty/missing values, what value ranges are valid. Explicit exit criteria prevent ambiguous or inconsistent judgment.
+
+**Prompt design:** Design prompts for what you want, not against what you don't want. "Don't include reasoning" is less reliable than extracting the verdict from structured output in postprocessing. Use output filtering instead of prompt negation.
+
 **Comments:**
 - Required only when result is `fail`. Skip for `pass` unless the developer user specifically requests pass comments.
 - Be concise and factual: "Capital adequacy ratio is 7.2%, below the regulatory minimum of 8.0%."

package/template/skills/en/meta/document-chunking/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: document-chunking
+description: >
+  Fast, cheap chunking for processing batches of sample and input documents.
+  Use when you need to split documents into manageable pieces for initial observation,
+  data sensibility checks, or feeding to extraction workflows. Not for production
+  verification chunking — for that, use tree-processing to design a tailored chunking script.
+---
+
+# Document Chunking
+
+Split documents into pieces for downstream processing. This is the fast, cheap version — for batch processing of samples and inputs, not for precision verification workflows.
+
+## Methods
+
+**Page-level splits** — simplest. Each page is a chunk. Works for most document processing where you need to iterate over content.
+
+**Fixed-size chunks** — split by character/token count with overlap. Good for search and initial observation. Typical: 2000-4000 chars with 200 char overlap.
+
+**Header-based splits** — detect section headers and split at boundaries. Preserves semantic units. Use regex patterns for the document's header convention.
+
+## When to Use What
+
+Pick the simplest method that serves the task:
+- Batch document observation → page-level
+- Full-text search index → fixed-size with overlap
+- Section-level extraction → header-based
+- Table of contents available → parse TOC for structure
+
+## Relationship to tree-processing
+
+This skill is for quick, cheap chunking during exploration and batch processing. When you need production-grade chunking for verification workflows — where the chunking mechanism must be precise, consistent, and coded as a script — use `tree-processing` instead.

package/template/skills/en/meta/document-parsing/SKILL.md

@@ -12,28 +12,21 @@ Parsing is the foundation. If the text is wrong, everything downstream is wrong.
 Start with the simplest parser. Escalate only when necessary. This is not about saving money — it is about producing the most reliable output. Simple parsers have fewer failure modes.
 
 ### Level 1: Direct Text Extraction
-- Tool: pymupdf (PyMuPDF) or similar PDF text extraction.
+- Tool: pdfjs-dist or similar PDF text extraction.
 - When: Well-formed digital PDFs with embedded text. This covers most modern business documents.
 - Output: Raw text with basic structure preserved (paragraphs, basic formatting).
 - Limitations: Tables may come out as messy text. Charts and images are invisible. Scanned PDFs produce nothing.
 
-### Level 2: Layout-Aware Extraction
-- Tool: pdfplumber or similar layout-aware parser.
-- When: Level 1 produces messy table output, or when preserving spatial layout matters (forms, multi-column documents).
-- Output: Text with table detection and cell-level extraction.
-- Limitations: Still text-based. Cannot handle scanned content.
-
-### Level 3: OCR
-- Tool: Vision-capable models from OCR_MODEL_TIER in `.env` (PaddleOCR-VL, GLM-4.6V, etc.).
-- When: Scanned PDFs, image-based PDFs, or PDFs where Level 1-2 produce garbled/incomplete text.
-- Output: Recognized text from images.
-- Limitations: Slower, costs API calls, may introduce OCR errors.
-
-### Level 4: Vision Model Interpretation
-- Tool: High-capability vision models (OCR_MODEL_TIER1).
-- When: Complex tables that text extraction cannot parse correctly, charts that need data point extraction, mixed text-and-image layouts.
-- Output: Structured interpretation of visual content (table as markdown, chart data as JSON).
-- Limitations: Expensive, slow. Reserve for when the visual content genuinely needs interpretation.
+### Level 2: Provider VLM (Vision Language Model)
+- Tool: VLM models from configured provider (VLM_TIER3 for cheap OCR, VLM_TIER1 for complex interpretation).
+- When: Level 1 produces garbled/incomplete text, scanned PDFs, image-based PDFs.
+- Output: Recognized text from page images, or structured interpretation (table as markdown, chart data as JSON).
+- Calling a provider VLM is more convenient and reliable than deploying local OCR. Use the cheapest VLM tier first; escalate to a more capable tier for complex tables/charts.
+
+### Level 3: MineRU API or Local Tools (Optional)
+- Tool: MineRU API, pdfplumber, or locally deployed OCR — if configured.
+- When: Provider VLM is unavailable or too expensive for batch processing.
+- These are optional fallbacks. Most users will use Level 1 + Level 2.
 
 ## Quality Detection
 

package/template/skills/en/meta/entity-extraction/SKILL.md

@@ -33,40 +33,21 @@ The value could be anywhere, or the rule applies to the document as a whole.
 
 ## Method Selection
 
-### Regex / Python (Cost: zero, Speed: instant)
+Extraction method selection is a cost-accuracy search. The goal is finding the cheapest method that meets the accuracy threshold. Regex is the smallest, cheapest "model" — zero cost, instant, deterministic. Worker LLM is more capable but costs tokens and time. Any search strategy is valid: try the cheapest first and escalate, try the most capable first and downgrade, bisect, or jump directly to a known-good method based on past experience in AGENT.md.
 
-Use when the entity has a predictable format:
+### Available Methods
 
-- **Dates**: `\d{4}[-/年]\d{1,2}[-/月]\d{1,2}[日]?` or specific patterns for the document type.
-- **Monetary amounts**: `[\d,]+\.?\d*\s*(元|万元|亿元|USD|RMB)` or similar.
-- **Percentages**: `\d+\.?\d*\s*%`
-- **Identifiers**: Loan numbers, registration codes, ID numbers — usually fixed formats.
-- **Specific phrases**: "I hereby agree" or "本人同意" — exact string matching.
+**Regex / Python** — Cost: zero. Speed: instant. Deterministic.
+Works well for: dates, monetary amounts, percentages, identifiers, fixed phrases, any value with a predictable format.
 
-Build and test the regex on sample documents. A good regex is better than a good LLM prompt for structured values — it is faster, deterministic, and free.
+**Worker LLM** — Cost: API tokens. Speed: seconds. Semantic understanding.
+Works well for: contextual interpretation, conditional values, semantic matching, ambiguous structures, suggestive or misleading language detection, table interpretation, anything requiring understanding rather than pattern matching.
 
-### LLM Extraction (Cost: API call, Speed: seconds)
+Many real verification tasks require semantic understanding — "is this description misleading?", "does this clause adequately disclose risk?", "is this guarantor's business description consistent with their stated industry?" — regex cannot handle these. Use worker LLM without hesitation for such tasks.
 
-Use when the entity requires understanding:
+### The Search
 
-- **Named entities in context**: "the guarantor's main business" — requires understanding who the guarantor is and which text describes their business.
-- **Conditional values**: "the interest rate, including any adjustments" — requires understanding what constitutes an adjustment.
-- **Semantic matching**: "adequate risk disclosure" — requires judgment about what text constitutes risk disclosure.
-- **Table interpretation**: When a table's structure is not uniform and regex cannot reliably extract cells.
-
-Design the LLM prompt to:
-1. Include the narrowed context (from tree processing).
-2. Specify exactly what to extract.
-3. Define the output format (JSON with named fields).
-4. Provide one example if the extraction is non-obvious.
-
-### Hybrid Approach
-
-Often the best strategy:
-1. Use regex to extract candidates (fast, catches obvious matches).
-2. If regex finds a confident match, use it.
-3. If regex fails or is uncertain, fall back to LLM extraction.
-4. Use LLM to validate regex results when confidence matters.
+If a method's results fall below the accuracy threshold, try a different method or a more capable model. If regex works and meets accuracy — keep it, it's free. If regex produces results below threshold, escalate to worker LLM. If a cheap worker LLM isn't accurate enough, try a more capable tier. Record what works for each extraction type in AGENT.md for future reference.
 
 ## Schema Design
 
@@ -118,6 +99,10 @@ Every extraction should carry a confidence estimate:
 
 These are starting points. Calibrate based on actual accuracy (see `confidence-system`).
 
+## Prompt Design: Ask For What You Want
+
+Design prompts for what you want, not against what you don't want. "Don't include explanations" in a prompt is less reliable than stripping non-JSON text from the output in postprocessing. If you need to tell the LLM not to do something, use output filtering instead of prompt negation.
+
 ## Fitting Worker LLM Context
 
 When designing extraction for worker LLM workflows:

package/template/skills/en/meta/tree-processing/SKILL.md

@@ -1,12 +1,30 @@
 ---
 name: tree-processing
-description: Build hierarchical document trees and navigate to specific chapters or sections required by verification rules. Use when a rule targets a specific part of a document (e.g., "Chapter 3 must contain..."), when documents are too long for a single LLM context window, or when you need to find where a specific entity lives within a large document. Implements the "onion peeler" approach for chunking. Also use for documents over 100 pages where full-document processing is impractical.
+description: >
+  Design production-grade document chunking mechanisms for verification workflows. Use when
+  building the chunking step of a workflow that will run repeatedly on many documents.
+  The approach: observe sample documents, find structural patterns, write a chunking script
+  in code, that script runs in production. Also use for navigating large documents via
+  hierarchical structure when a rule targets a specific section.
+  For quick, cheap batch chunking during exploration, use document-chunking instead.
 ---
 
 # Tree Processing
 
 Most verification rules do not need the entire document. They need a specific section, a specific table, a specific disclosure. The tree is your map for navigating large documents efficiently.
 
+## Production Chunking Methodology
+
+For verification workflows that process many documents, the chunking mechanism must be precise, consistent, and fast. The approach:
+
+1. **Observe**: Read 3-5 sample documents. Note their structure — headers, numbering, section patterns.
+2. **Find patterns**: Identify what's consistent (header format, numbering convention, TOC structure).
+3. **Write code**: Design a chunking script (regex-based splitter, header detector, TOC parser) that captures the pattern.
+4. **Test**: Run the script on samples. Verify it produces correct, consistent chunks.
+5. **Deploy**: The script runs in production workflows. It's deterministic, free, and fast.
+
+This is different from `document-chunking` (quick, cheap splits for exploration). Production chunking is a one-time design effort that pays off across all documents of the same type.
+
 ## Why Trees
 
 Two reasons: