@sidub-inc/docuoria.cli 1.0.15

package/payload/references/workflow.md

@@ -0,0 +1,163 @@
+# Workflow
+
+The pipeline has seven steps operating through a template store — a directory (or API endpoint) of JSON template files that define extraction and classification rules. Store-aware scripts (`classify`, `evaluate-match`, `list-templates`, `load-template`, `save-template`) require `--store-path <dir>` or `--store-url <url>` to locate the store; always pass the store location explicitly.
+
+**Step 1 (Classify) always runs first** and determines whether steps 2–4 are needed. Never skip step 1 — classification is cheap and avoids redundant exploration.
+
+```
+1 Classify ──► strong match (≥ 0.8) ──────────────────────► 5 Dry-run ──► 6 Execute ──► done
+     │
+     ├──► partial match (0.4–0.8) ──► 3 Test pattern ──► 4 Build template ──► 5 Dry-run ──► 6 Execute ──► 7 Store
+     │         (load existing template, fix broken fields only)
+     │
+     └──► no match / error ──► 2 Inspect ──► 3 Test pattern ──► 4 Build template ──► 5 Dry-run ──► 6 Execute ──► 7 Store
+```
+
+---
+
+## Step 1 — Classify
+
+Determine whether an existing template already handles this PDF. If the templates directory location is unknown, confirm it before classifying — check for a directory containing `.json` template files near the workspace root, or ask the user.
+
+- **Script:** `dotnet script scripts/classify.csx -- --pdf <pdf> --store-path <templates-dir>`
+- **API:** `IDocuoriaEngine.ClassifyAsync` — evaluates every stored template's `rootMatchRule` and returns them ranked by `confidence` (`ruleConfidence × extractionProbeScore`).
+- **Output:** `{ "matches": [ { "templateId": "...", "confidence": 0.92 }, ... ] }` — descending by confidence.
+
+**Routing:** see [`classification.md` § Interpreting the gradient](classification.md#interpreting-the-gradient) for the canonical confidence-to-action table (≥ 0.8 strong, 0.4–0.8 partial, < 0.4 author new). On `error: no-store` (no templates found at the given path, or no store configured), skip to **Step 2** and author from scratch.
+
+---
+
+## Step 2 — Inspect
+
+See what the engine actually reads from the PDF before writing any patterns. The engine's text output often differs from the visual layout.
+
+- **Script:** `dotnet script scripts/inspect.csx -- --pdf <pdf>` (optionally `--page N` for a single page)
+- **API:** `IDocuoriaEngine.InspectAsync`
+- **Returns:** `PdfInspection` — `PageCount`, `Pages[*].FlattenedText`, `Pages[*].TextBlocks`, `Pages[*].Tables` snapshots.
+- **Gate:** if `PageCount` is 0 or every page has empty `TextBlocks`, the PDF is scanned/image-only — **STOP**. OCR upstream first.
+- **Next:** Step 3.
+
+---
+
+## Step 3 — Test pattern
+
+Prove each regex matches the engine's flattened haystack — not the visible text.
+
+- **Scripts:**
+  - `dotnet script scripts/test-pattern.csx -- --pdf <pdf> --pattern "<regex>"` — test a single pattern.
+  - `dotnet script scripts/test-groups.csx -- --pdf <pdf> --pattern "<regex>"` — test each capture group independently when a multi-group regex partially fails.
+- **API:** `IDocuoriaEngine.TestPatternAsync` / `IDocuoriaEngine.TestGroupsAsync`
+- **Returns:** `PatternTestResult` — `HasMatches`, `Matches`, `Gaps`. For groups: `PatternGroupTestResult.Groups[*].MatchesIndependently`.
+- **Iterate:** use `patterns.md` and `pattern-authoring.md` as reference. Repeat until `HasMatches` is `true` and match count matches expectation.
+- **Next:** Step 4.
+
+---
+
+## Step 4 — Build template
+
+Assemble the template JSON, design its classification rules, and validate the schema. This step has three sub-tasks that must all pass before proceeding.
+
+### 4a — Author template JSON
+
+- Combine confirmed patterns with the appropriate `ExtractionSource` subtype (consult `decision-tree.md`).
+- Design a discriminating `rootMatchRule` that identifies this **document type**, not just the vendor (consult `classification.md`).
+  - Use `CompositeMatchRule` (And) with discriminator children weighted ≥ 2.0.
+  - Identify tokens unique to this document type — section headers, product identifiers, column names that siblings do not share.
+
+### 4b — Validate classification rules
+
+- **Script:** `dotnet script scripts/evaluate-match.csx -- --pdf <pdf> --template <template.json>`
+- **API:** `IDocuoriaEngine.EvaluateMatchAsync` — returns `confidence` (`ruleConfidence × extractionProbeScore`).
+- **Positive test:** target PDF → confidence ≥ 0.8.
+- **Negative test:** same-vendor PDFs that should NOT match → confidence near zero. If 0.4–0.7, the rules lack discrimination — strengthen the discriminator.
+- See `classification.md` for the full design guide.
+
+### 4c — Validate schema
+
+- **Script:** `dotnet script scripts/validate-template.csx -- --template <template.json>`
+- Fix every reported error before proceeding. A schema failure corresponds to `RejectionReason.MalformedTemplate` at runtime.
+
+**Next:** Step 5.
+
+---
+
+## Step 5 — Dry-run
+
+Extract and transform without generating output. Confirms the template produces correct data before committing to a full run.
+
+- **Script:** `dotnet script scripts/dry-run.csx -- --pdf <pdf> --template <template.json>`
+- **API:** `IDocuoriaEngine.DryRunAsync`
+- **Returns:** `DryRunSucceeded` (extracted fields + diagnostics), `DryRunFailed` (`Step`, `FieldPath`, `SourceText`, `TargetTypeName`, `InnerDetail`), or `DryRunRejected` (`RejectionReason`).
+
+**On success:** verify all collection fields have the expected element count. An empty `[]` for a `RepeatingFieldMapping` means the pattern didn't match — see `failure-tree.md` Branch D.
+
+**On failure:** go to `failure-tree.md` indexed by `Step` (for `DryRunFailed`) or `RejectionReason` (for `DryRunRejected`).
+
+**Multi-variant check:** repeat dry-run with every available PDF from the same vendor/template category. If any variant produces empty collections or null scalars where data should exist, the template may be over-fitted — see `failure-tree.md` Branch D (layout variant splitting).
+
+**Next:** Step 6.
+
+---
+
+## Step 6 — Execute
+
+Full pipeline run including the output generator.
+
+- **Script:** `dotnet script scripts/execute.csx -- --pdf <pdf> --template <template.json> --format csv|json` (optionally `--output <path>`)
+- **API:** `IDocuoriaEngine.ExecuteTemplateAsync<TGenerator, TOptions>`
+- **Returns:** `SucceededResult`, `FailedResult`, or `RejectedResult` with `RejectionReason` in {`InvalidPdf`, `MalformedTemplate`, `UnknownOutputGenerator`, `GeneratorRejected`}.
+- **On failure:** go to `failure-tree.md`.
+- **Next:** if this was a strong classify match (step 1 routed here directly) → done. If this is a new or modified template → Step 7.
+
+---
+
+## Step 7 — Store
+
+Persist the template and verify it ranks correctly in the store. This prevents the new template from stealing classifications from existing templates or ranking too low for its own target.
+
+- **Save:** `dotnet script scripts/save-template.csx -- --template <template.json> --store-path <templates-dir>`
+- **Verify ranking:**
+  - `dotnet script scripts/classify.csx -- --pdf <target.pdf> --store-path <templates-dir>` → new template must rank **#1**, confidence ≥ 0.8.
+  - `dotnet script scripts/classify.csx -- --pdf <sibling.pdf> --store-path <templates-dir>` → new template should score < 0.4; existing sibling templates should still rank #1 for their own PDFs.
+- **API:** `IDocuoriaEngine.ClassifyAsync`, `IDocuoriaEngine.EvaluateMatchAsync`
+- **Other store scripts:** `list-templates.csx --store-path <templates-dir>` (enumerate all), `load-template.csx --id <id> --store-path <templates-dir>` (fetch one).
+
+**Done.** The template is stored and will be found by Step 1 on future PDFs of this type.
+
+---
+
+## Quick reference
+
+| Step | Script(s) | Engine API | Result |
+|---|---|---|---|
+| 1 Classify | `classify.csx` | `ClassifyAsync` | Ranked matches with `confidence` |
+| 2 Inspect | `inspect.csx` | `InspectAsync` | `PdfInspection` |
+| 3 Test pattern | `test-pattern.csx`, `test-groups.csx` | `TestPatternAsync`, `TestGroupsAsync` | `PatternTestResult` |
+| 4 Build | (editor), `evaluate-match.csx`, `validate-template.csx` | `EvaluateMatchAsync` | Template JSON + validation |
+| 5 Dry-run | `dry-run.csx` | `DryRunAsync` | `DryRunResult` |
+| 6 Execute | `execute.csx` | `ExecuteTemplateAsync` | `ProcessingResult` |
+| 7 Store | `save-template.csx`, `classify.csx` | `ClassifyAsync` | Ranking verification |
+
+---
+
+## CSV output behaviour
+
+When `--format csv` is used with `execute.csx`, the `CsvOutputGenerator` flattens the hierarchical `DataRecord` into tabular CSV.
+
+| Template shape | Behaviour |
+|---|---|
+| Scalar fields only | One data row, one column per field |
+| One `RepeatingFieldMapping` | Denormalised: scalars repeat on every row, collection elements get one row each. Column headers use dot notation (`lineItems.description`) |
+| Two+ `RepeatingFieldMapping` | **Rejected** (`RejectionReason.GeneratorRejected`). Use JSON output or split into separate templates |
+| Nested `RecordFieldDefinition` | Flattened with dot notation (`address.city`) |
+
+### CsvGeneratorOptions
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `Delimiter` | `char` | `,` | Field separator |
+| `Encoding` | `Encoding` | UTF-8 (no BOM) | Output encoding |
+| `NewlineReplacement` | `string?` | `"\n"` | Replace embedded newlines with literal escape text; `" "` collapses to spaces; `null` preserves raw newlines in RFC 4180 quoted cells |
+| `IncludeHeaderRow` | `bool` | `true` | Whether to emit a header row |
+| `DateFormat` | `string?` | `null` (ISO 8601) | .NET date format string for `Date` fields |
+| `NumberFormat` | `string?` | `null` (general `G`) | .NET format string for `Number` fields |

package/payload/scripts/_common.csx

@@ -0,0 +1,250 @@
+#r "nuget: Microsoft.Extensions.Hosting, 10.0.0"
+#r "nuget: Microsoft.Extensions.DependencyInjection, 10.0.0"
+#r "nuget: Microsoft.Extensions.Http, 10.0.0"
+#r "nuget: PdfPig, 0.1.14"
+#r "nuget: Tabula, 1.0.1"
+#r "nuget: CsvHelper, 33.1.0"
+#r "nuget: pythonnet, 3.0.5"
+#r "../assets/lib/Docuoria.dll"
+
+#nullable enable
+
+// Phase 29: Shared bootstrap for every script under `scripts/` (D-Area-2 in 29-CONTEXT.md).
+// Every script `#load`s this file. It deduplicates DI wiring, arg parsing,
+// and JSON I/O so individual scripts can focus on their semantics.
+//
+// The `dotnet-script` runtime is required to execute these scripts:
+//   dotnet tool install -g dotnet-script
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Reflection;
+using System.Text.Json;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Docuoria.Contracts;
+using Docuoria.Registration;
+using Docuoria.Serialization;
+using Docuoria.Storage;
+
+// Dev-time override: DOCUORIA_SDK_DLL can point at an alternate Docuoria.dll.
+// The `#r` literal above resolves at script-compile time; this LoadFrom call after-the-fact
+// ensures the override assembly is available for reflection-based DI lookups even when the
+// literal succeeded.
+if (Environment.GetEnvironmentVariable("DOCUORIA_SDK_DLL") is string __sdkPath
+    && !string.IsNullOrWhiteSpace(__sdkPath)
+    && File.Exists(__sdkPath))
+{
+    try
+    {
+        Assembly.LoadFrom(__sdkPath);
+    }
+    catch (Exception __sdkLoadEx)
+    {
+        // WR-02: DOCUORIA_SDK_DLL is an explicit opt-in dev override. If the user set it
+        // but loading failed, do NOT silently fall back to the #r literal — emit a structured
+        // JSON error envelope to stderr and exit non-zero so the override failure is visible.
+        var payload = new { error = new { code = "sdk-load-failed", message = $"DOCUORIA_SDK_DLL load failed: {__sdkLoadEx.Message}", detail = __sdkPath } };
+        var json = JsonSerializer.Serialize(payload, DocuoriaJsonOptions.Default);
+        Console.Error.WriteLine(json);
+        Environment.Exit(1);
+    }
+}
+
+/// <summary>
+/// Builds a Generic Host with the SDK engine + (optionally) the configured template store.
+/// </summary>
+public static class ScriptHost
+{
+    /// <summary>
+    /// Construct an IHost containing IDocuoriaEngine and (optionally) ITemplateStoreProvider.
+    /// </summary>
+    /// <param name="args">Forwarded to Host.CreateDefaultBuilder for configuration binding.</param>
+    /// <param name="includeStore">When false, ITemplateStoreProvider is NOT registered — used by
+    /// scripts that don't touch the store (inspect, test-pattern, test-groups, validate-template,
+    /// dry-run) to avoid forcing store configuration on irrelevant invocations.</param>
+    public static IHost CreateHost(string[] args, bool includeStore = true)
+    {
+        var builder = Host.CreateDefaultBuilder(args);
+        builder.ConfigureServices(services =>
+        {
+            services.AddDocuoriaEngine(b =>
+            {
+                b.AddBuiltInMatchRules();
+                b.AddCsvOutputGenerator();
+                b.AddJsonOutputGenerator();
+                if (includeStore)
+                    RegisterStore(b, args);
+            });
+        });
+        return builder.Build();
+    }
+
+    public static IDocuoriaEngine GetEngine(IHost host)
+        => host.Services.GetRequiredService<IDocuoriaEngine>();
+
+    public static ITemplateStoreProvider? GetStore(IHost host)
+        => host.Services.GetService<ITemplateStoreProvider>();
+
+    private static void RegisterStore(IDocuoriaEngineBuilder builder, string[] args)
+    {
+        var storePath = Cli.Get(args, "store-path");
+        var storeUrl = Cli.Get(args, "store-url");
+        var storeKey = Cli.Get(args, "store-key");
+
+        if (!string.IsNullOrWhiteSpace(storePath) && !string.IsNullOrWhiteSpace(storeUrl))
+        {
+            throw new InvalidOperationException(
+                "--store-path and --store-url are mutually exclusive. Use --store-path for a local file store or --store-url for an API store.");
+        }
+
+        if (!string.IsNullOrWhiteSpace(storeUrl))
+        {
+            var creds = new ApiTemplateStoreCredentials { FunctionKey = storeKey };
+            builder.AddApiTemplateStore(new Uri(storeUrl), creds);
+        }
+        else
+        {
+            // IN-01: directory is created lazily by LocalFileTemplateStoreProvider on first
+            // write; ListAsync tolerates a missing root. Avoid littering arbitrary cwds with
+            // an empty ./templates dir at script startup.
+            var path = string.IsNullOrWhiteSpace(storePath) ? "./templates" : storePath;
+            builder.AddLocalTemplateStore(path);
+        }
+    }
+}
+
+/// <summary>Hand-rolled `--key value` / `--flag` arg parser (System.CommandLine deferred).</summary>
+/// <remarks>Named <c>Cli</c> rather than <c>Args</c> because <c>dotnet-script</c> exposes a
+/// top-level <c>Args</c> global (<see cref="System.Collections.Generic.IList{T}"/> of
+/// <see cref="string"/>) that would shadow a static class of the same name.</remarks>
+public static class Cli
+{
+    private static readonly List<(string Name, bool Required, string Description, bool IsFlag)> _registeredArgs = new();
+    private static string? _scriptDescription;
+
+    /// <summary>
+    /// Register the script description and check for --help. Call at the top of each script.
+    /// If --help is present, prints usage and exits.
+    /// </summary>
+    public static void Help(IList<string> args, string scriptName, string description, params (string Name, bool Required, string Description, bool IsFlag)[] argDefs)
+    {
+        _scriptDescription = description;
+        _registeredArgs.Clear();
+        _registeredArgs.AddRange(argDefs);
+
+        if (Has(args, "help") || Has(args, "h"))
+        {
+            Console.WriteLine();
+            Console.WriteLine($"  {scriptName}");
+            Console.WriteLine($"  {description}");
+            Console.WriteLine();
+            Console.WriteLine("  Usage:");
+            Console.WriteLine($"    dotnet script scripts/{scriptName} -- [args]");
+            Console.WriteLine();
+            Console.WriteLine("  Arguments:");
+            foreach (var (name, required, desc, isFlag) in argDefs)
+            {
+                var req = required ? "(required)" : "(optional)";
+                var kind = isFlag ? "flag" : "value";
+                Console.WriteLine($"    --{name,-20} {req,-12} {desc}");
+            }
+            Console.WriteLine($"    --{"help",-20} {"(optional)",-12} Show this help message");
+            Console.WriteLine();
+            Environment.Exit(0);
+        }
+    }
+
+    /// <summary>Returns the value following <c>--key</c>, or null when absent.</summary>
+    public static string? Get(string[] args, string key)
+    {
+        if (args is null) return null;
+        var marker = "--" + key;
+        for (int i = 0; i < args.Length; i++)
+        {
+            if (string.Equals(args[i], marker, StringComparison.Ordinal))
+            {
+                if (i + 1 < args.Length) return args[i + 1];
+                return null;
+            }
+        }
+        return null;
+    }
+
+    /// <summary>True when <c>--key</c> is present (regardless of any following value).</summary>
+    public static bool Has(string[] args, string key)
+    {
+        if (args is null) return false;
+        var marker = "--" + key;
+        foreach (var a in args)
+        {
+            if (string.Equals(a, marker, StringComparison.Ordinal)) return true;
+        }
+        return false;
+    }
+
+    /// <summary>
+    /// Required-arg lookup. On missing key emits a JSON error to stderr and exits with code 2.
+    /// </summary>
+    public static string Require(IList<string> args, string key) => Require(args.ToArray(), key);
+    public static string? Get(IList<string> args, string key) => Get(args.ToArray(), key);
+    public static bool Has(IList<string> args, string key) => Has(args.ToArray(), key);
+
+    public static string Require(string[] args, string key)
+    {
+        var v = Get(args, key);
+        if (v is null)
+        {
+            JsonOut.Error("missing-arg", $"--{key} is required", null, 2);
+        }
+        return v!;
+    }
+}
+
+/// <summary>JSON stdout / stderr writers using DocuoriaJsonOptions.Default (D-Area-1).</summary>
+public static class JsonOut
+{
+    /// <summary>Serialize <paramref name="value"/> to a single stdout line.</summary>
+    public static void Write(object value)
+    {
+        var json = JsonSerializer.Serialize(value, value?.GetType() ?? typeof(object), DocuoriaJsonOptions.Default);
+        Console.Out.WriteLine(json);
+    }
+
+    /// <summary>Write a pre-serialized JSON string to stdout (avoids double-serialization).</summary>
+    public static void WriteRaw(string json)
+    {
+        Console.Out.WriteLine(json);
+    }
+
+    /// <summary>
+    /// Emit a structured error envelope to stderr and terminate the script with
+    /// <paramref name="exitCode"/> (default 1). Errors NEVER go to stdout. This method
+    /// does not return; <see cref="Environment.Exit(int)"/> terminates the process. The
+    /// trailing <c>throw</c> is unreachable in practice but communicates the no-return
+    /// contract to the C# flow analyzer so callers don't need to null-forgive the result.
+    /// </summary>
+    [DoesNotReturn]
+    public static void Error(string code, string message, string? detail = null, int exitCode = 1)
+    {
+        var payload = new { error = new { code, message, detail } };
+        var json = JsonSerializer.Serialize(payload, DocuoriaJsonOptions.Default);
+        Console.Error.WriteLine(json);
+        Environment.Exit(exitCode);
+        throw new InvalidOperationException("Environment.Exit returned unexpectedly.");
+    }
+}
+
+/// <summary>
+/// Opens a readable+seekable FileStream over <paramref name="path"/>, or emits a JSON error and
+/// exits when the file is missing.
+/// </summary>
+public static FileStream LoadPdf(string path)
+{
+    if (string.IsNullOrWhiteSpace(path) || !File.Exists(path))
+    {
+        JsonOut.Error("pdf-not-found", $"PDF not found at '{path}'", null, 1);
+    }
+    return new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read);
+}

package/payload/scripts/classify.csx

@@ -0,0 +1,53 @@
+#load "_common.csx"
+
+#nullable enable
+
+// CLS-02 — ranked classification: evaluates every stored template and returns top matches
+// sorted by effective confidence (ruleConfidence × extractionProbeScore, descending).
+// Uses ClassifyRankedAsync to open the PDF once and evaluate all templates without
+// redundant PDF parsing per template.
+// Args: --pdf <path> [--top N]
+// stdout: { matches: [ { templateId, confidence }, ... ] }
+
+using Docuoria.Contracts;
+using Docuoria.Storage;
+
+try
+{
+    Cli.Help(Args, "classify.csx", "Classify a PDF against stored templates (ranked by confidence)",
+        ("pdf", true, "Path to the source PDF", false),
+        ("top", false, "Maximum number of results to return (default: 5)", false),
+        ("store-path", false, "Local template store directory (default: ./templates)", false),
+        ("store-url", false, "API template store URL (mutually exclusive with --store-path)", false),
+        ("store-key", false, "Function key for API store authentication", false));
+
+    var pdfPath = Cli.Require(Args, "pdf");
+    var topN = int.TryParse(Cli.Get(Args, "top"), out var n) ? n : 5;
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: true);
+    var engine = ScriptHost.GetEngine(host);
+
+    using var pdf = LoadPdf(pdfPath);
+
+    // OPT: Single engine call opens the PDF once and evaluates all templates internally,
+    // replacing the previous per-template loop that re-parsed the PDF for each template.
+    var classifications = await engine.ClassifyRankedAsync(pdf, topN);
+
+    var ranked = classifications
+        .Select(c => new
+        {
+            templateId = c.TemplateIdentifier,
+            confidence = Math.Round(c.RuleConfidence * c.ExtractionProbeScore, 4),
+        })
+        .ToArray();
+
+    var opts = new System.Text.Json.JsonSerializerOptions(Docuoria.Serialization.DocuoriaJsonOptions.Default)
+    {
+        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never,
+    };
+    JsonOut.WriteRaw(System.Text.Json.JsonSerializer.Serialize(new { matches = ranked }, opts));
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/dry-run.csx

@@ -0,0 +1,85 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-05 — Wrapper over IDocuoriaEngine.DryRunAsync (extraction + transformation only).
+// Args: --pdf <path> --template <file.json> [--preview-as csv|json]
+// stdout: { kind, result } — discriminator + payload.
+// With --preview-as: { kind, result, preview } — adds formatted output string.
+
+using System.Text;
+using Docuoria.Configuration;
+using Docuoria.Contracts;
+using Docuoria.Models;
+using Docuoria.Output.Csv;
+using Docuoria.Output.Json;
+using Docuoria.Results;
+
+try
+{
+    Cli.Help(Args, "dry-run.csx", "Run extraction + transformation without output generation",
+        ("pdf", true, "Path to the source PDF", false),
+        ("template", true, "Path to the template JSON file", false),
+        ("preview-as", false, "Preview formatted output: csv or json (no file written)", false));
+
+    var pdfPath = Cli.Require(Args, "pdf");
+    var templatePath = Cli.Require(Args, "template");
+    var previewAs = Cli.Get(Args, "preview-as")?.Trim().ToLowerInvariant();
+
+    if (previewAs is not null && previewAs != "csv" && previewAs != "json")
+    {
+        JsonOut.Error("bad-format", "--preview-as must be csv or json", null, 2);
+    }
+
+    if (!File.Exists(templatePath))
+    {
+        JsonOut.Error("template-not-found", $"Template not found at '{templatePath}'", null, 1);
+    }
+
+    var template = Template.FromJson(File.ReadAllText(templatePath));
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: false);
+    var engine = ScriptHost.GetEngine(host);
+
+    using var pdf = LoadPdf(pdfPath);
+
+    if (previewAs is null)
+    {
+        // Standard dry-run: extraction + transformation only.
+        var result = await engine.DryRunAsync(pdf, template);
+        JsonOut.Write(new { kind = result.GetType().Name, result });
+    }
+    else
+    {
+        // Preview mode: full execute, but output goes to stdout preview instead of disk.
+        ProcessingResult result = previewAs switch
+        {
+            "csv" => await engine.ExecuteTemplateAsync<CsvOutputGenerator, CsvGeneratorOptions>(
+                pdf, template, new CsvGeneratorOptions()),
+            "json" => await engine.ExecuteTemplateAsync<JsonOutputGenerator, JsonGeneratorOptions>(
+                pdf, template, new JsonGeneratorOptions()),
+            _ => throw new InvalidOperationException("unreachable")
+        };
+
+        switch (result)
+        {
+            case SucceededResult ok:
+                var preview = Encoding.UTF8.GetString(ok.Output.Payload.Span);
+                JsonOut.Write(new { kind = "SucceededResult", format = previewAs, preview });
+                break;
+            case RejectedResult rej:
+                JsonOut.Error("rejected", $"Rejected ({rej.Reason}){(rej.Detail is not null ? $": {rej.Detail}" : "")}", null, 1);
+                break;
+            case FailedResult fail:
+                JsonOut.Error("failed", fail.ErrorMessage, fail.InnerDetail, 1);
+                break;
+            default:
+                JsonOut.Error("unknown-result", result.GetType().Name, null, 1);
+                break;
+        }
+    }
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/evaluate-match.csx

@@ -0,0 +1,72 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-07 + CLS-01 helper — wrapper over IDocuoriaEngine.EvaluateMatchAsync.
+// Args: --pdf <path> --template <id-or-file>
+// Auto-detects template source per Area-3: contains path sep OR ends .json OR File.Exists -> file;
+// otherwise loads from store via ITemplateStoreProvider.LoadAsync(value).
+// stdout: { confidence, matchedRules } JSON.
+
+using Docuoria.Contracts;
+using Docuoria.Models;
+using Docuoria.Storage;
+
+try
+{
+    Cli.Help(Args, "evaluate-match.csx", "Evaluate a template's match rule against a PDF",
+        ("pdf", true, "Path to the source PDF", false),
+        ("template", true, "Template ID or path to template JSON file", false),
+        ("store-path", false, "Local template store directory (default: ./templates)", false),
+        ("store-url", false, "API template store URL (mutually exclusive with --store-path)", false),
+        ("store-key", false, "Function key for API store authentication", false));
+
+    var pdfPath = Cli.Require(Args, "pdf");
+    var templateRef = Cli.Require(Args, "template");
+
+    bool looksLikeFile =
+        templateRef.IndexOfAny(new[] { '/', '\\' }) >= 0 ||
+        templateRef.EndsWith(".json", StringComparison.OrdinalIgnoreCase) ||
+        File.Exists(templateRef);
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: true);
+    var engine = ScriptHost.GetEngine(host);
+
+    Template? template;
+    if (looksLikeFile)
+    {
+        if (!File.Exists(templateRef))
+        {
+            JsonOut.Error("template-not-found", $"Template file not found at '{templateRef}'", null, 1);
+        }
+        template = Template.FromJson(File.ReadAllText(templateRef));
+    }
+    else
+    {
+        var store = ScriptHost.GetStore(host);
+        if (store is null)
+        {
+            JsonOut.Error("no-store", "ITemplateStoreProvider is not registered.", null, 1);
+        }
+        template = await store!.LoadAsync(templateRef);
+        if (template is null)
+        {
+            JsonOut.Error("not-found", $"template '{templateRef}' not found in store", null, 1);
+        }
+    }
+
+    using var pdf = LoadPdf(pdfPath);
+    var evaluation = await engine.EvaluateMatchAsync(template!, pdf);
+
+    // Project a clean LLM-facing response: single aggregated confidence + diagnostic rules.
+    // Confidence = ruleConfidence × extractionProbeScore (0.0 when either fails).
+    JsonOut.Write(new
+    {
+        confidence = Math.Round(evaluation.RuleConfidence * evaluation.ExtractionProbeScore, 4),
+        matchedRules = evaluation.MatchedRules,
+    });
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}