@sidub-inc/docuoria.cli 1.0.15

package/payload/examples/03-diagnose-failed-result.md

@@ -0,0 +1,68 @@
+# Example 3 — Diagnose a FailedResult
+
+## Scenario
+
+`dotnet script scripts/execute.csx -- --pdf <pdf> --template <template.json> --format csv --output out.csv` exits non-zero and emits `{ "error": { "code": "failed", "message": "FieldPath ... could not be coerced to System.Decimal", "detail": "..." } }` on stderr. The underlying `FailedResult` has `Step = StepIdentifier.Transformation` — a field expected to be a `decimal` could not be coerced from the captured text.
+
+## Example: before (broken template)
+
+The template maps a currency amount as `fieldType: 1` (Number), but the regex captures the dollar sign:
+
+```json
+{
+  "$kind": "FieldMapping",
+  "fieldName": "totalAmount",
+  "fieldType": 1,
+  "source": {
+    "$kind": "TextPatternExtractionSource",
+    "mode": "Pattern",
+    "regexPattern": "Total:?\\s*(?<value>\\$[\\d,.]+)"
+  }
+}
+```
+
+This captures `"$1,234.56"`, which cannot be parsed as a decimal → `FailedResult`.
+
+## Example: after (fixed template)
+
+Exclude the dollar sign from the capture group:
+
+```json
+{
+  "$kind": "FieldMapping",
+  "fieldName": "totalAmount",
+  "fieldType": 1,
+  "source": {
+    "$kind": "TextPatternExtractionSource",
+    "mode": "Pattern",
+    "regexPattern": "Total:?\\s*\\$?(?<value>[\\d,]+\\.\\d{2})"
+  }
+}
+```
+
+Now captures `"1,234.56"` → coerces to `1234.56` successfully.
+
+## Steps
+
+1. **Map the stderr `error.code` to a branch first.** `execute.csx` emitted `{ "error": { "code": "failed", "message": "...", "detail": "Step: Transformation, FieldPath: ..." } }` on stderr with exit ≥ 1. Look up `failed` in [`../references/failure-tree.md` § Stderr error.code → Branch routing](../references/failure-tree.md#stderr-errorcode--branch-routing) → **Branch B**, then read the `StepIdentifier` in `detail` (`Transformation`) to land on the right remediation row.
+2. Read the structured fields on `FailedResult` (parse from stderr `detail` or re-run dry-run with diagnostics):
+   - `Step` — here `StepIdentifier.Transformation`.
+   - `FieldPath` — e.g. `"DataModel.Fields.Total"`.
+   - `SourceText` — the raw captured substring, capped at 256 characters with a trailing ellipsis when truncated.
+   - `TargetTypeName` — e.g. `"System.Decimal"` or the engine-friendly name.
+   - `InnerDetail` — short description of the inner exception.
+3. Confirm with diagnostics: `dotnet script scripts/dry-run.csx -- --pdf <pdf> --template <template.json>`. Dry-run defaults `Diagnostics = true`. Read the same fields off the returned `DryRunFailed` and inspect the per-mapping match trace.
+4. Inspect `SourceText`. If it contains a currency symbol, a thousands separator, or surrounding whitespace, the pattern is capturing too much for the target type — tighten the pattern (see [`../references/patterns.md`](../references/patterns.md) patterns 3 vs. 4, or pattern 6 for decimals) or change the target type to `string` with a downstream transform.
+5. Re-run `dotnet script scripts/dry-run.csx -- --pdf <pdf> --template <template.json>` until `DryRunSucceeded`.
+6. Re-run `dotnet script scripts/execute.csx -- --pdf <pdf> --template <template.json> --format csv --output output.csv` for the real CSV.
+
+## Expected outcome
+
+`ProcessingResult` becomes `SucceededResult`; the previously-failing field carries the coerced value.
+
+## See also
+
+- [`../references/failure-tree.md` § Stderr error.code → Branch routing](../references/failure-tree.md#stderr-errorcode--branch-routing) — always start here when a script exits non-zero.
+- [`../references/failure-tree.md`](../references/failure-tree.md) Branch B `Step = Transformation` — the canonical remediation matrix.
+- [`../references/patterns.md`](../references/patterns.md) — illustrative patterns, especially 3–7 for numeric coercion.
+- [`../references/pattern-authoring.md`](../references/pattern-authoring.md) — the iteration loop for shrinking an over-broad capture.

package/payload/references/classification.md

@@ -0,0 +1,363 @@
+# Classification rule design
+
+The `rootMatchRule` determines whether a template is eligible for a given PDF. A weak rule produces false positives — the template classifies documents it cannot extract from, causing silent failures (empty collections, wrong data). This guide teaches how to design discriminating rules that match ONLY the documents the template can actually handle.
+
+## How classification scoring works
+
+Understanding the scoring model prevents accidental over-matching.
+
+### Rule-level confidence
+
+Each match rule returns a **confidence** ∈ [0, 1] and compares it to its **threshold** ∈ [0, 1]:
+
+| Rule type | Confidence formula |
+|---|---|
+| `TextPatternMatchRule` (regex) | Binary: 1.0 if match, 0.0 if not |
+| `TextPatternMatchRule` (AnyToken) | **Proportional:** `matched_tokens / total_tokens` |
+| `TextPatternMatchRule` (AllTokens) | Binary: 1.0 if ALL match, 0.0 if not |
+| `TextAnchorMatchRule` | Binary: 1.0 if text found in region |
+| `TableMatchRule` | Proportional: `satisfied_criteria / specified_criteria` |
+| `PageGeometryMatchRule` | Proportional: `met_criteria / specified_criteria` |
+| `MetadataMatchRule` | Proportional: `matched_fields / expected_fields` |
+| `CompositeMatchRule` (And) | Weighted average: `Σ(confidence × weight) / Σ(weight)` |
+| `CompositeMatchRule` (Or) | Max weighted: `max(confidence × weight) / max(weight)` |
+| `CompositeMatchRule` (Not) | Inverted: `1 - child_confidence` |
+
+A rule **matches** when `confidence >= threshold`. Default threshold is `0.5`.
+
+### Classification output
+
+The engine evaluates each template and produces a single aggregated **confidence** score:
+
+- **`confidence`** — `ruleConfidence × extractionProbeScore`. This is the signal the agent acts on. A template is a functional match only when the root rule passes AND at least one collection extraction pattern matches (probe > 0).
+
+The `classify.csx` script evaluates every stored template against a PDF and returns them ranked by confidence (descending), giving the agent a gradient rather than a single binary winner.
+
+### Interpreting the gradient
+
+| confidence | Meaning | Agent action |
+|---|---|---|
+| ≥ 0.8 | Strong match — rules pass and extraction patterns match | Extract directly |
+| 0.4 – 0.8 | Partial match — some discriminating tokens present | Try extraction with this template. If results are incomplete, iterate on this template rather than authoring from scratch |
+| 0.1 – 0.4 | Weak match — only baseline signals present | Use as structural reference (field layout, extraction sources) when authoring a new template |
+| ~0 | No overlap | New document type — author from scratch |
+
+**Key insight:** two templates from the same vendor may both score 0.3–0.5 for a new variant that neither fully covers. The ranked list surfaces this — pick the closest match as a starting point for refinement.
+
+### The proportional confidence trap
+
+With `TextPatternMatchRule` in `AnyToken` mode (integer `0`):
+- 4 tokens + threshold 0.5 → only **2 tokens** need to match
+- 6 tokens + threshold 0.5 → only **3 tokens** need to match
+
+Generic vendor tokens like `["Microsoft", "Invoice"]` will match many unrelated documents from the same vendor. This is the #1 cause of misclassification.
+
+## Principles
+
+When designing a `rootMatchRule`, follow these three imperatives:
+
+1. **Match the document TYPE, not just the vendor.** Author one template per document type (invoice, credit note, statement, usage report) with type-specific markers — never let a single template cover multiple document types from the same vendor.
+2. **Give every template at least one token or feature that no other template shares.** If two templates can match the same PDF, treat classification as broken and tighten the discriminators before iterating on extraction quality.
+3. **Validate every template against negative examples.** A template that matches its target PDF is necessary but not sufficient — confirm with `evaluate-match.csx` that the template *rejects* same-vendor PDFs with different layouts before saving it.
+
+## Token selection strategy
+
+### Bad tokens (vendor-level — too broad)
+
+```json
+{
+  "tokens": ["Microsoft", "Invoice", "Bill To", "Total"],
+  "mode": 0,
+  "threshold": 0.5
+}
+```
+
+Every Microsoft invoice, credit note, and statement contains these tokens. This matches everything.
+
+### Good tokens (document-type-level — discriminating)
+
+```json
+{
+  "tokens": ["Microsoft", "Invoice", "Subscription", "Office 365", "License Qty"],
+  "mode": 0,
+  "threshold": 0.8
+}
+```
+
+The tokens `"Subscription"`, `"Office 365"`, `"License Qty"` are specific to subscription invoices. A consumption/usage invoice won't contain them.
+
+### Best approach — AllTokens with discriminators
+
+```json
+{
+  "tokens": ["Microsoft", "Invoice", "Subscription"],
+  "mode": 1,
+  "threshold": 0.5
+}
+```
+
+`AllTokens` (mode `1`) requires **every** token to be present (binary 1.0 or 0.0). Add tokens that are unique to the document type. If even one discriminating token is absent, the rule fails entirely.
+
+### How to find discriminating tokens
+
+1. Run `inspect.csx` on the target PDF — note distinctive section headers, product names, column headers, and billing terminology.
+2. Run `inspect.csx` on other PDFs from the same vendor — identify tokens that appear ONLY in your target.
+3. Good discriminators: section headers (`"Usage Charges"`, `"Subscription Details"`), product identifiers, unique column headers, regulatory text specific to one document type.
+4. Bad discriminators: vendor name, generic labels (`"Amount"`, `"Date"`, `"Page"`), boilerplate legal text shared across document types.
+
+## Composite rule architecture
+
+For maximum discrimination, compose multiple rule types with appropriate weights:
+
+```json
+{
+  "$kind": "CompositeMatchRule",
+  "operator": 0,
+  "threshold": 0.85,
+  "children": [
+    {
+      "rule": {
+        "$kind": "TextPatternMatchRule",
+        "tokens": ["Microsoft", "Invoice"],
+        "mode": 1,
+        "threshold": 0.5
+      },
+      "weight": 1.0
+    },
+    {
+      "rule": {
+        "$kind": "TextPatternMatchRule",
+        "tokens": ["Subscription", "License Qty", "Seats"],
+        "mode": 0,
+        "threshold": 0.6
+      },
+      "weight": 2.0
+    },
+    {
+      "rule": {
+        "$kind": "PageGeometryMatchRule",
+        "expectedOrientation": 0,
+        "expectedPageCount": 2,
+        "threshold": 0.5
+      },
+      "weight": 0.5
+    }
+  ]
+}
+```
+
+**Architecture breakdown:**
+
+| Child | Purpose | Weight | Rationale |
+|---|---|---|---|
+| TextPattern (AllTokens) | Vendor gate — broad necessary condition | 1.0 | Baseline: must be a Microsoft Invoice |
+| TextPattern (AnyToken, high threshold) | Type discriminator — narrows to subscription invoices | **2.0** | Emphasized: these tokens distinguish this layout from usage invoices |
+| PageGeometry | Structural hint | 0.5 | De-emphasized: helpful but not definitive alone |
+
+**Weighting strategy:**
+- Weight `1.0` — baseline signals (necessary but not sufficient)
+- Weight `> 1.0` — discriminators (these separate your template from siblings)
+- Weight `< 1.0` — supporting hints (adds confidence but shouldn't gate alone)
+
+The composite `And` calculates: `Σ(confidence × weight) / Σ(weight)`. With the example above: if the discriminator fails, the weighted average drops below the composite threshold of 0.85 even if other rules pass.
+
+## Structural discriminators
+
+Text tokens alone are often insufficient for same-vendor discrimination. Use structural rules:
+
+### TableMatchRule — for documents with distinctive table layout
+
+```json
+{
+  "$kind": "TableMatchRule",
+  "minRows": 5,
+  "minColumns": 4,
+  "requiredHeaderTokens": ["Service Name", "Quantity", "Unit Price"],
+  "threshold": 0.75
+}
+```
+
+Use when: the target document has a table with specific headers that sibling documents do not share. Verify with `inspect.csx` — check `Tables[*].Headers` and `Tables[*].TotalRowCount`.
+
+### PageGeometryMatchRule — for documents with distinctive page structure
+
+```json
+{
+  "$kind": "PageGeometryMatchRule",
+  "expectedPageCount": 4,
+  "expectedOrientation": 1,
+  "threshold": 0.5
+}
+```
+
+Use when: the target document has a consistent page count or orientation that distinguishes it. Landscape-only reports vs. portrait invoices are easy to discriminate.
+
+### TextAnchorMatchRule — for documents with distinctive spatial layout
+
+```json
+{
+  "$kind": "TextAnchorMatchRule",
+  "expectedContent": "Azure Usage Detail",
+  "region": { "x": 50, "y": 30, "width": 300, "height": 40 },
+  "pageNumber": 1,
+  "threshold": 0.5
+}
+```
+
+Use when: a specific text appears in a known location on the page. This is stronger than plain token matching because it validates both content AND position. Obtain coordinates from `inspect.csx` → `TextBlocks[*].Bounds`.
+
+## Threshold strategy
+
+| Scenario | Recommended approach |
+|---|---|
+| Single document type from a vendor | `AllTokens` mode, threshold `0.5` — binary pass/fail is sufficient |
+| Multiple document types from same vendor | Composite with discriminator weight `≥ 2.0`, composite threshold `≥ 0.8` |
+| Documents with variable content (optional sections) | `AnyToken` mode with enough tokens that threshold still requires the discriminating ones |
+| Filename-gated workflows | Add `FileNameMatchRule` child with low weight (`0.3`) as a tiebreaker, never as sole gate |
+
+**Key rule:** Raise the composite threshold when siblings are close. The composite threshold gates the entire root rule — if your weighted average can reach 0.85 even without the discriminator matching, your threshold is too low.
+
+## Validation checklist
+
+Before storing a template, validate classification quality:
+
+1. **Positive validation** — run `evaluate-match.csx` against the target PDF:
+   ```
+   dotnet script scripts/evaluate-match.csx -- --pdf <target.pdf> --template <template.json>
+   ```
+   Must return a high `confidence` (≥ 0.8 ideally).
+
+2. **Negative validation** — run against PDFs from the same vendor that should NOT match:
+   ```
+   dotnet script scripts/evaluate-match.csx -- --pdf <sibling.pdf> --template <template.json>
+   ```
+   Must return `confidence: 0` or near-zero. If confidence is moderate (0.4–0.7), the rules are not discriminating enough.
+
+3. **Ranked classification** — if multiple templates are stored, verify correct ranking:
+   ```
+   dotnet script scripts/classify.csx -- --pdf <target.pdf> --store-path <templates-dir>
+   ```
+   The correct template must appear at the top of the ranked list with the highest `confidence`. Check the gap between the top match and the next — a wide gap indicates strong discrimination, a narrow gap indicates ambiguity.
+
+4. **Boundary cases** — test with the most similar document from another vendor/type to ensure the discriminators are doing their job.
+
+If negative validation fails, strengthen the discriminator child (add more type-specific tokens, increase its weight, or add a structural rule like `TableMatchRule`).
+
+## Common mistakes
+
+| Mistake | Consequence | Fix |
+|---|---|---|
+| Vendor tokens only | Every document from that vendor classifies at 1.0 | Add document-type-specific tokens |
+| AnyToken with low threshold | Too few tokens needed to pass | Use AllTokens for critical gates, or raise threshold |
+| No negative validation | Template matches sibling documents | Always test against same-vendor PDFs that should NOT match |
+| Equal weights on all children | Discriminator failure doesn't drop below threshold | Weight discriminators at 2.0+ |
+| Single TextPatternMatchRule as root | No layered defense against similar documents | Use CompositeMatchRule with multiple signal types |
+| Testing only the target PDF | False confidence in rule quality | Test against 2-3 negative examples from same vendor |
+
+## Worked example: splitting Microsoft invoices
+
+**Problem:** One template uses `["Microsoft", "Invoice", "Bill To"]` in `AllTokens` mode. Both a subscription invoice and an Azure usage invoice contain all three tokens. Both classify at 1.0.
+
+**Solution — two templates with mutual exclusivity:**
+
+Template A (subscription):
+```json
+{
+  "rootMatchRule": {
+    "$kind": "CompositeMatchRule",
+    "operator": 0,
+    "threshold": 0.8,
+    "children": [
+      {
+        "rule": {
+          "$kind": "TextPatternMatchRule",
+          "tokens": ["Microsoft", "Invoice"],
+          "mode": 1,
+          "threshold": 0.5
+        },
+        "weight": 1.0
+      },
+      {
+        "rule": {
+          "$kind": "TextPatternMatchRule",
+          "tokens": ["Subscription", "License", "Seats", "Renewal"],
+          "mode": 0,
+          "threshold": 0.5
+        },
+        "weight": 2.0
+      }
+    ]
+  }
+}
+```
+
+Template B (Azure usage):
+```json
+{
+  "rootMatchRule": {
+    "$kind": "CompositeMatchRule",
+    "operator": 0,
+    "threshold": 0.8,
+    "children": [
+      {
+        "rule": {
+          "$kind": "TextPatternMatchRule",
+          "tokens": ["Microsoft", "Invoice"],
+          "mode": 1,
+          "threshold": 0.5
+        },
+        "weight": 1.0
+      },
+      {
+        "rule": {
+          "$kind": "TextPatternMatchRule",
+          "tokens": ["Azure", "Usage", "Consumption", "Resource Group"],
+          "mode": 0,
+          "threshold": 0.5
+        },
+        "weight": 2.0
+      }
+    ]
+  }
+}
+```
+
+**Why this works:**
+- Both require "Microsoft" + "Invoice" (baseline gate, weight 1.0)
+- Template A requires subscription-specific tokens (weight 2.0) — these are absent in Azure usage invoices
+- Template B requires Azure-specific tokens (weight 2.0) — these are absent in subscription invoices
+- With weights [1.0, 2.0] and composite threshold 0.8: if the discriminator (weight 2.0) scores 0.0, the weighted average is `(1.0×1 + 0.0×2) / (1+2) = 0.33` — well below 0.8
+
+**Validation:**
+- Subscription PDF against Template A → passes (both children match)
+- Subscription PDF against Template B → fails (Azure tokens absent, avg drops below 0.8)
+- Usage PDF against Template A → fails (subscription tokens absent)
+- Usage PDF against Template B → passes (both children match)
+
+## Diagnosing classification with per-rule scores
+
+When `evaluate-match.csx` returns the result, the `matchedRules` array includes a summary for every rule in the tree — not just the root. Each summary carries the individual rule's `confidence` score.
+
+For a composite root with two children, the output looks like:
+
+```json
+{
+  "confidence": 0.89,
+  "matchedRules": [
+    { "ruleType": "CompositeMatchRule",    "matched": true,  "confidence": 0.89, "detail": null },
+    { "ruleType": "TextPatternMatchRule",  "matched": true,  "confidence": 1.0,  "detail": null },
+    { "ruleType": "TextPatternMatchRule",  "matched": true,  "confidence": 0.75, "detail": null }
+  ]
+}
+```
+
+### How to read the diagnostic
+
+1. **Root `confidence` = 1.0 for both templates?** The individual children will reveal the issue — look for children where confidence is 1.0 on BOTH invoice types. Those rules are not discriminating.
+2. **Child has `confidence: 1.0`?** That rule matches fully — all tokens/criteria are present. It provides no differentiation signal.
+3. **Child has `confidence: 0.0`?** That rule found nothing — either the tokens are absent or the structural criteria (table, geometry) don't match. This is the child that creates differentiation.
+4. **Child has fractional confidence?** Some but not all criteria matched. This is the gradient at work — the rule is partially relevant.
+
+### Troubleshooting 1.0 across sibling documents
+
+If two templates both return `confidence: 1.0` against the same PDF, every child rule scored 1.0. The fix is to add a discriminator child with type-specific tokens or structural criteria that would score < 1.0 (or 0.0) for the wrong document type. Use the per-child breakdown to verify the new discriminator actually creates separation.

package/payload/references/decision-tree.md

@@ -0,0 +1,43 @@
+# Extraction-source decision tree
+
+Pick the extraction source by the *shape* of the data on the page, not by the field name. The subtypes below are mutually exclusive per field; if more than one seems to fit, the lower bullet wins.
+
+## `$kind` reference table
+
+Every extraction source uses the `$kind` JSON discriminator to identify the SDK type. You **must** use these exact values in template JSON — any other value causes silent deserialization failure.
+
+| `$kind` value | Mode / variant | Use case |
+|---|---|---|
+| `TextPatternExtractionSource` | `mode: "Token"` | Literal token match (one value) |
+| `TextPatternExtractionSource` | `mode: "Pattern"` | Regex match (one value, first match) |
+| `TextPatternExtractionSource` | `mode: "AllMatches"` | Regex match (all matches → collection) |
+| `TextAnchorExtractionSource` | — | Value next to a spatially-anchored label |
+| `TableCellExtractionSource` | — | Single cell by row/column coordinate |
+| `TableRowsExtractionSource` | — | All data rows from a real PDF table |
+| `MetadataFieldExtractionSource` | — | PDF metadata (Title, Author, etc.) |
+| `FallbackExtractionSource` | — | Composite: try primary, fall back to fallback |
+
+## The decision questions, in order
+
+1. **Is there exactly one value on the page** (e.g. a reference number, a single date)? → use `TextPatternExtractionSource` with `mode: "Pattern"`. Why: it returns the first regex match against the flattened haystack and projects a single named capture group. In JSON: `{ "$kind": "TextPatternExtractionSource", "mode": "Pattern", "regexPattern": "..." }`.
+2. **Is the value a *list of similar values* on one page** (e.g. repeating line items, multiple reference numbers)? → use `TextPatternExtractionSource` with `mode: "AllMatches"`. Why: it returns every regex match, preserving order, as collection rows. In JSON: `{ "$kind": "TextPatternExtractionSource", "mode": "AllMatches", "regexPattern": "..." }`.
+3. **Is the value inside a *visually tabular* block** (rows and columns, bordered or unbordered)? → run `inspect.csx` and check `Tables[*].TotalRowCount`. If any table has `TotalRowCount > 1` with correct `RowPreviews`, use `TableRowsExtractionSource` for whole rows or `TableCellExtractionSource` for a single cell coordinate. Why: the engine detects both bordered (lattice) and unbordered (stream/spacing-based) tables via Tabula. Even without visible grid lines, consistent text spacing is often enough for detection.
+4. **Does the value live *next to a label* whose position varies** (e.g. `Total: 123.45` floating between header and footer)? → use `TextAnchorExtractionSource`. Why: it anchors on the label text and reads the adjacent run, so layout drift between PDFs is absorbed by the anchor.
+5. **Does the value's location vary by layout *version*** (same vendor, two PDF templates over time)? → wrap the primary source in a `FallbackExtractionSource` with `primary` and `fallback` properties. Why: the engine tries `primary` first and falls back to `fallback` if no value is produced.
+6. **Is the value in the PDF metadata** (author, title, creation date)? → use `MetadataFieldExtractionSource`. Why: it reads from the PDF's metadata dictionary, not from page text.
+
+## Anti-patterns
+
+- Do not use `TextPatternExtractionSource` (mode `"Pattern"`) for repeating data; it will silently take only the first match. Use mode `"AllMatches"` instead.
+- Do not assume `TableRowsExtractionSource` is unusable just because the PDF "looks tabular but isn't bordered." The engine uses both Tabula lattice (bordered) AND stream (unbordered, spacing-based) table detection. **Always run `inspect.csx` and check `Tables[*].TotalRowCount`** — if any table has `TotalRowCount > 1` with meaningful `RowPreviews`, `TableRowsExtractionSource` will work even without visible borders.
+- If `inspect.csx` shows tables with only 1 row (header-only) or no tables at all for a visually tabular section, fall back to `TextPatternExtractionSource` with `mode: "AllMatches"`. Before writing the regex, read the actual `FlattenedText` from `inspect.csx` — it may differ significantly from the visual PDF layout due to column-grouped block ordering.
+- Do not chain more than three `FallbackExtractionSource` layers; that is a sign the document is fundamentally different and warrants a separate `Template`.
+- Do not use `PatternExtractionSource` or `AllMatchesExtractionSource` — these are conceptual names that do **not** exist in the SDK. The actual type is always `TextPatternExtractionSource` with a `mode` property.
+
+## Layout variants and template splitting
+
+If `DryRunSucceeded` returns an empty collection for a field that should have data and `inspect.csx` reveals a different page structure than the PDF used during authoring, you are facing a layout variant. The canonical splitting procedure (choosing discriminators, tightening the original `rootMatchRule`, validating mutual exclusivity with `evaluate-match.csx`) lives in [`classification.md` § Worked example: splitting Microsoft invoices](classification.md#worked-example-splitting-microsoft-invoices). Follow that procedure, then return here to confirm the `ExtractionSource` choice survives the split.
+
+## After picking
+
+Confirm the choice by running `dotnet script scripts/dry-run.csx -- <pdf> <template.json>` and inspecting the field's `ExtractionDiagnostics` trace — if the wrong source was picked, the trace shows which match path was attempted and why it produced no value. Then go to `workflow.md` Step 6.

package/payload/references/failure-tree.md

@@ -0,0 +1,169 @@
+# Failure-mode decision tree
+
+Every PDF run produces one of three outcomes: `SucceededResult` (done), `RejectedResult` (the engine refused before completing — see `RejectionReason`), or `FailedResult` (the engine ran a step and it threw — see `StepIdentifier`). Classification can additionally produce "no template matched". Use the matching subsection below.
+
+## Stderr `error.code` → Branch routing
+
+Every script emits errors as `{ "error": { "code": "<code>", "message": "...", "detail": "..." } }` on stderr with non-zero exit. Map the stderr `error.code` to a branch below before reading the prose narrative:
+
+| `error.code` | Emitted by | Meaning | Go to |
+| --- | --- | --- | --- |
+| `pdf-not-found` | every script that takes `--pdf` | The path passed to `--pdf` does not resolve to a file | Fix the path (relative paths resolve from the cwd); re-run. No branch — this is an input error, not an SDK outcome. |
+| `template-not-found` | `load-template.csx`, `evaluate-match.csx`, `dry-run.csx`, `execute.csx` | Template ID does not exist in the store, or the `--template` path does not resolve | Run `list-templates.csx` to confirm the ID, or correct the path. No branch. |
+| `no-store` | `classify.csx`, `list-templates.csx`, `load-template.csx`, `save-template.csx` | No `--store-path` or `--store-url` was provided and the default `./templates` directory was not found | Pass `--store-path <dir>` to specify a local template store directory; see `references/scripts.md` § Common Store Parameters. No branch. |
+| `bad-format` | `validate-template.csx`, `dry-run.csx`, `execute.csx`, `save-template.csx` | Template JSON is malformed or fails schema validation (parse error, missing required property, invalid enum value) | **Branch A** — `RejectionReason.MalformedTemplate`. Run `validate-template.csx` for the schema error list. |
+| `rejected` | `dry-run.csx`, `execute.csx` | Engine returned `RejectedResult` — see `RejectionReason` in stderr `detail` | **Branch A** — match on the `RejectionReason` enum value. |
+| `failed` | `dry-run.csx`, `execute.csx` | Engine returned `FailedResult` — see `StepIdentifier` in stderr `detail` | **Branch B** — match on the `StepIdentifier` enum value. |
+| `empty-result` / silent `DryRunSucceeded` with empty collections | `dry-run.csx`, `execute.csx` | The engine succeeded but a `RepeatingFieldMapping` returned `[]` or a scalar returned `null` unexpectedly | **Branch D** — silent extraction failure (no stderr; detect by inspecting stdout). |
+| Wrong template ranked first, or no template ranked | `classify.csx` | Classification produced unexpected ordering — diagnose via the ranked confidence gradient | **Branch C** — see also [`classification.md` § Interpreting the gradient](classification.md#interpreting-the-gradient). |
+| `already-exists` | `save-template.csx` | Template with the same ID already exists in the store | Pass `--overwrite` if intentional, or pick a different ID. No branch. |
+| `unhandled` | any script | Unexpected exception inside the script (not an SDK outcome) — the `detail` field contains the stack | File a bug; this is an SDK or script defect, not a template/PDF problem. No branch. |
+
+## Branch A — RejectedResult
+
+### RejectionReason.InvalidPdf
+
+- **Meaning:** the PDF stream could not be parsed.
+- **Diagnose:** run `dotnet script scripts/inspect.csx -- <pdf>`. If `PdfInspection.PageCount` is `0`, the file is unparseable.
+- **Remediation:** confirm the file is a real PDF (magic bytes `%PDF-`), not a renamed image or HTML. If the source is a scan, the engine cannot extract from rasterised content; OCR upstream first.
+
+### RejectionReason.MalformedTemplate
+
+- **Meaning:** the `Template` JSON is structurally invalid (schema violations, missing required fields, unknown discriminators).
+- **Diagnose:** run `dotnet script scripts/validate-template.csx -- <template.json>`.
+- **Remediation:** fix every validation error reported. Never bypass validation by editing past it — the runtime check is the same check.
+
+### RejectionReason.UnknownOutputGenerator
+
+- **Meaning:** the generic `TGenerator` passed to `IDocuoriaEngine.ExecuteTemplateAsync<TGenerator, TOptions>` is not registered in DI.
+- **Diagnose:** search host startup for `AddOutputGenerator<TGenerator, TOptions>` (or convenience helpers such as `AddCsvOutputGenerator`).
+- **Remediation:** register the generator before calling execute, or pick an already-registered generator.
+
+### RejectionReason.GeneratorRejected
+
+- **Meaning:** the generator refused the extracted data (e.g. multiple collections handed to a CSV generator).
+- **Diagnose:** run `dotnet script scripts/dry-run.csx -- <pdf> <template.json>` — `DryRunSucceeded` shows what the generator would have received.
+- **Remediation:** reshape the template (split into multiple templates, or pick a richer generator that accepts the shape).
+
+## Branch B — FailedResult
+
+Read `FailedResult.Step` (enum-typed `StepIdentifier`) first; everything else is diagnostic context.
+
+### Step = Retrieval
+
+- **Meaning:** a retrieval provider threw.
+- **Diagnose:** read `FailedResult.ErrorMessage` and `FailedResult.Exception`. For HTTP retrieval check connectivity and 4xx/5xx status.
+- **Remediation:** fix the retrieval source; rerun.
+
+### Step = Extraction
+
+- **Meaning:** a pattern, table, or anchor extraction step threw or could not produce a value.
+- **Diagnose:** rerun via `dotnet script scripts/dry-run.csx -- <pdf> <template.json>` (diagnostics on by default). Read `FailedResult.FieldPath` to identify the field, then `dotnet script scripts/test-pattern.csx` (for `TextPatternExtractionSource` mode `"Pattern"` / `"AllMatches"`) or `dotnet script scripts/inspect.csx` (for `TableRowsExtractionSource` / `TableCellExtractionSource`).
+- **Remediation:** see `pattern-authoring.md` or revisit `decision-tree.md`.
+
+### Step = Transformation
+
+- **Meaning:** a field coercion failed (string → `DateOnly`, `decimal`, etc.).
+- **Diagnose:** read the structured fields on `FailedResult`: `FieldPath` (which field), `SourceText` (the raw captured substring, capped at 256 chars with a trailing ellipsis), `TargetTypeName` (the destination type), `InnerDetail` (the coercion exception detail).
+- **Remediation:** either tighten the regex to capture a coercible substring (see `patterns.md` patterns 4 vs. 3), or change the field type, or add a transform step.
+
+### Step = Publish
+
+- **Meaning:** the output generator threw mid-write (vs. cleanly rejecting, which would yield `RejectionReason.GeneratorRejected`).
+- **Diagnose:** read `FailedResult.Exception`.
+- **Remediation:** typical causes are I/O (path not writable, file locked) or generator bugs — fix infrastructure first, then file a generator issue.
+
+### Step = Unknown
+
+- **Meaning:** legacy/default value (assigned `0`). Observed when the legacy three-arg `FailedResult` constructor was used and no `Step` was set.
+- **Diagnose:** treat as `Extraction` until proven otherwise; read `FailedResult.ErrorMessage` and `FailedResult.Exception`.
+- **Remediation:** proceed as for the inferred step.
+
+## Branch C — Classification failure
+
+Classification issues come in three forms: no template matched, the wrong template matched, or no template is confident enough. Use `classify.csx` to get a ranked view of all templates with their `confidence` scores — this replaces the binary match/no-match model with a confidence gradient.
+
+### First step: get the ranked classification
+
+```
+dotnet script scripts/classify.csx -- --pdf <pdf> --store-path <templates-dir>
+```
+
+This returns the top-N templates sorted by `confidence` (descending). For the canonical confidence-to-action table, see [`classification.md` § Interpreting the gradient](classification.md#interpreting-the-gradient). If the matches array is empty, no templates are stored at all — author from scratch (`workflow.md` Step 3).
+
+### Scenario: Wrong template matched (misclassification)
+
+- **Meaning:** the top-ranked template with high `confidence` produces empty or incorrect data because the PDF belongs to a different document type from the same vendor.
+- **How to detect:** `DryRunSucceeded` with empty collections or null scalars where data should exist (→ Branch D), OR extracted values are nonsensical (wrong field mapped to wrong content).
+- **Diagnose:**
+  1. Run `classify.csx` — check if the correct template appears lower in the ranked list. If so, the correct template's rules are weaker than expected.
+  2. Run `dotnet script scripts/inspect.csx -- --pdf <pdf>` — compare the page structure against the PDF used when authoring the matched template.
+  3. Check the `confidence` gap between the wrong match and the correct template — a narrow gap means the rules lack discrimination.
+- **Remediation:**
+  1. The matched template's `rootMatchRule` is too broad — it matches documents it cannot extract from. See `classification.md` for how to tighten.
+  2. Strengthen the correct template's discriminating rules to boost its `confidence` above the wrong match.
+  3. Validate with `classify.csx` — the correct template must rank #1 with a clear gap over sibling templates.
+
+### Scenario: No match at all
+
+- **Meaning:** all templates score near zero `confidence`.
+- **Remediation:** author a new template (back to `workflow.md` Step 3). If any template scores moderately (0.3+), use `load-template.csx` to retrieve it as a structural starting point — its field layout and extraction sources may transfer even if its match rules don't fit.
+
+### Root cause patterns for classification failures
+
+| Pattern | Symptom | Fix |
+|---|---|---|
+| Vendor-only tokens | Multiple document types from same vendor score similarly | Add document-type-specific discriminators (see `classification.md`) |
+| AnyToken with low threshold | Template matches when only generic tokens are present | Switch to AllTokens for critical gates, or raise threshold |
+| No structural rules | Two documents share text tokens but have different layouts | Add `TableMatchRule`, `PageGeometryMatchRule`, or `TextAnchorMatchRule` |
+| Single rule (no composite) | No layered defense | Use `CompositeMatchRule` with weighted discriminators |
+| Never tested negative examples | Rule seems fine against target but matches siblings too | Always validate against same-vendor PDFs that should NOT match |
+| Narrow confidence gap | Top two templates score within 0.1 of each other | Strengthen discriminators on both to widen the gap |
+
+## Branch D — DryRunSucceeded but data is empty or incomplete
+
+This is the *silent failure* mode — the pipeline reports success but one or more fields (typically a `RepeatingFieldMapping`) returned `null` or an empty collection. The dry-run does not flag this as an error because the engine has no expectation about how many rows should be extracted.
+
+### Symptom: RepeatingFieldMapping returns `[]` (empty collection)
+
+- **Diagnose:**
+  1. Run `dotnet script scripts/dry-run.csx -- <pdf> <template.json>` — confirm the collection field is present but empty.
+  2. Run `dotnet script scripts/inspect.csx -- <pdf> --page <N>` — examine `FlattenedText` and `Tables` for the page containing the expected data.
+  3. If `Tables` shows entries with `TotalRowCount > 1` and meaningful `RowPreviews`, the data IS detectable as a table → switch to `TableRowsExtractionSource`.
+  4. If `Tables` shows only header-like entries (1 row) or no entries, read `FlattenedText` carefully. The block flattening order may differ from the visual PDF layout.
+  5. Run `dotnet script scripts/test-pattern.csx -- <pdf> "<your-regex>"` against the ACTUAL flattened text (not the text you see when viewing the PDF).
+
+- **Root causes (in likelihood order):**
+
+| Cause | How to confirm | Remediation |
+|---|---|---|
+| **Layout variant** — The template was designed for a different document layout from the same vendor | Compare the PDF's page 2+ structure against the one used during authoring. Look for differences in section headers, column layout, or whether data appears per-product vs. in a single table. | **Split into separate templates** with narrower match rules. See [`classification.md` § Worked example: splitting Microsoft invoices](classification.md#worked-example-splitting-microsoft-invoices) for the canonical procedure. |
+| **Block order differs from visual order** — The PDF's internal text blocks are column-grouped (all labels in one block, all values in another) rather than row-grouped | Run `inspect.csx` and read the `Blocks` array with coordinates. If all row labels share one block and values are in separate column-aligned blocks, the flattened haystack destroys row associations. | If `Tables` detection finds the structure → use `TableRowsExtractionSource`. Otherwise, this layout may not be extractable with the current SDK; document as a known limitation. |
+| **Pattern mismatch** — The AllMatches regex was written for a different text structure | Run `test-pattern.csx` — if `HasMatches` is `false`, the pattern doesn't match the actual haystack. | Rewrite the regex against the actual `FlattenedText` from `inspect.csx`. See `pattern-authoring.md`. |
+| **Page targeting** — The extraction source targets the wrong page | Check `pageNumber` in the extraction source config vs. where the data actually appears. | Correct the page number or remove it to search all pages. |
+
+### Layout variant splitting
+
+When a single template classifies multiple document layouts correctly (same vendor, same match tokens) but extraction works for only one layout, follow [`classification.md` § Worked example: splitting Microsoft invoices](classification.md#worked-example-splitting-microsoft-invoices) — the canonical step-by-step procedure for splitting templates, choosing discriminators, and validating mutual exclusivity.
+
+### Symptom: Scalar field returns `null` unexpectedly
+
+- **Diagnose:** run `dotnet script scripts/test-pattern.csx -- <pdf> "<regex>"` with the field's regex. If no match, inspect the haystack for the actual text surrounding the expected value.
+- **Remediation:** adjust the regex. If the field genuinely doesn't exist in this document variant, consider making it non-required (`"isRequired": false`) or splitting templates.
+
+## Quick reference
+
+| Outcome | Enum value | Script | Remediation pointer |
+| --- | --- | --- | --- |
+| `RejectedResult` | `RejectionReason.InvalidPdf` | `inspect.csx` | check magic bytes / OCR upstream |
+| `RejectedResult` | `RejectionReason.MalformedTemplate` | `validate-template.csx` | fix schema errors |
+| `RejectedResult` | `RejectionReason.UnknownOutputGenerator` | (host startup) | register generator in DI |
+| `RejectedResult` | `RejectionReason.GeneratorRejected` | `dry-run.csx` | reshape template or change generator |
+| `FailedResult` | `Step = Retrieval` | (inspect retrieval) | fix retrieval source |
+| `FailedResult` | `Step = Extraction` | `dry-run.csx`, `test-pattern.csx`, `inspect.csx` | `pattern-authoring.md`, `decision-tree.md` |
+| `FailedResult` | `Step = Transformation` | `dry-run.csx` | tighten pattern or change field type |
+| `FailedResult` | `Step = Publish` | (inspect I/O) | fix infrastructure |
+| `FailedResult` | `Step = Unknown` | `dry-run.csx` | treat as Extraction |
+| `DryRunSucceeded` | empty collection | `dry-run.csx`, `inspect.csx`, `test-pattern.csx` | Branch D above — layout variant or block-order mismatch |
+| Classification | no match | `classify.csx`, `evaluate-match.csx` | Branch C — examine ranked results, author or refine template |
+| Classification | wrong match | `classify.csx`, `inspect.csx` | Branch C — tighten rules, strengthen discriminators (see `classification.md`) |