@sidub-inc/docuoria.cli 1.0.15

package/payload/assets/schemas/template-schema.json

@@ -0,0 +1,413 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sidub.net/docuoria/template-schema.json",
+  "title": "Sidub PDF Pipeline Template",
+  "description": "JSON Schema (Draft 2020-12) for the Sidub Docuoria Template document. Polymorphic nodes carry a `$kind` discriminator whose value matches the corresponding CLR simple type name. This schema constrains structure only; deeper semantic checks (field references, regex validity, record cycles) are enforced by Template.Validate() at runtime.",
+  "type": "object",
+  "required": ["identifier", "rootMatchRule", "dataModel", "extractionStep", "publishStep"],
+  "properties": {
+    "identifier": { "type": "string", "minLength": 1 },
+    "rootMatchRule": { "$ref": "#/$defs/MatchRuleConfigurationBase" },
+    "dataModel": { "$ref": "#/$defs/DataModel" },
+    "extractionStep": { "$ref": "#/$defs/ExtractionStep" },
+    "intermediateSteps": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "publishStep": { "$ref": "#/$defs/PublishStep" }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "MatchRuleConfigurationBase": {
+      "oneOf": [
+        { "$ref": "#/$defs/FileNameMatchRule" },
+        { "$ref": "#/$defs/TextPatternMatchRule" },
+        { "$ref": "#/$defs/TextAnchorMatchRule" },
+        { "$ref": "#/$defs/MetadataMatchRule" },
+        { "$ref": "#/$defs/PageGeometryMatchRule" },
+        { "$ref": "#/$defs/TableMatchRule" },
+        { "$ref": "#/$defs/CompositeMatchRule" }
+      ]
+    },
+    "FileNameMatchRule": {
+      "type": "object",
+      "required": ["$kind", "pattern"],
+      "properties": {
+        "$kind": { "const": "FileNameMatchRule" },
+        "pattern": { "type": "string" },
+        "mode": { "type": "integer", "minimum": 0, "maximum": 1, "description": "0=Glob, 1=Regex" },
+        "caseSensitive": { "type": "boolean" },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "TextPatternMatchRule": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": {
+        "$kind": { "const": "TextPatternMatchRule" },
+        "tokens": { "type": "array", "items": { "type": "string" } },
+        "regexPattern": { "type": "string" },
+        "mode": { "type": "integer", "minimum": 0, "maximum": 1, "description": "0=AnyToken, 1=AllTokens" },
+        "caseSensitive": { "type": "boolean" },
+        "pageNumber": { "type": "integer", "minimum": 1 },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "TextAnchorMatchRule": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": {
+        "$kind": { "const": "TextAnchorMatchRule" },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "MetadataMatchRule": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": {
+        "$kind": { "const": "MetadataMatchRule" },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "PageGeometryMatchRule": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": {
+        "$kind": { "const": "PageGeometryMatchRule" },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "TableMatchRule": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": {
+        "$kind": { "const": "TableMatchRule" },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "CompositeMatchRule": {
+      "type": "object",
+      "required": ["$kind", "children"],
+      "properties": {
+        "$kind": { "const": "CompositeMatchRule" },
+        "operator": { "type": "integer", "minimum": 0, "maximum": 2, "description": "0=And, 1=Or, 2=Not" },
+        "children": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CompositeChildEntry" },
+          "minItems": 1
+        },
+        "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "CompositeChildEntry": {
+      "type": "object",
+      "required": ["rule"],
+      "properties": {
+        "rule": { "$ref": "#/$defs/MatchRuleConfigurationBase" },
+        "weight": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "DataModel": {
+      "type": "object",
+      "required": ["schema"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/RecordDefinition" }
+      },
+      "additionalProperties": true
+    },
+    "RecordDefinition": {
+      "type": "object",
+      "required": ["name", "fields"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "fields": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/FieldDefinition" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "FieldDefinition": {
+      "oneOf": [
+        { "$ref": "#/$defs/PrimitiveFieldDefinition" },
+        { "$ref": "#/$defs/RecordFieldDefinition" }
+      ]
+    },
+    "PrimitiveFieldDefinition": {
+      "type": "object",
+      "required": ["$kind", "name"],
+      "properties": {
+        "$kind": { "const": "PrimitiveFieldDefinition" },
+        "name": { "type": "string", "minLength": 1 },
+        "fieldType": { "type": "integer", "minimum": 0, "maximum": 5, "description": "0=String, 1=Number, 2=Integer, 3=Boolean, 4=Date, 5=Timestamp" },
+        "isRequired": { "type": "boolean" },
+        "isCollection": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "RecordFieldDefinition": {
+      "type": "object",
+      "required": ["$kind", "name"],
+      "properties": {
+        "$kind": { "const": "RecordFieldDefinition" },
+        "name": { "type": "string", "minLength": 1 },
+        "isRequired": { "type": "boolean" },
+        "isCollection": { "type": "boolean" },
+        "record": { "$ref": "#/$defs/RecordDefinition" }
+      },
+      "additionalProperties": true
+    },
+    "ExtractionStep": {
+      "type": "object",
+      "properties": {
+        "configuration": { "type": "object" },
+        "mappings": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/FieldMapping" },
+              { "$ref": "#/$defs/RepeatingFieldMapping" }
+            ]
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "FieldMapping": {
+      "type": "object",
+      "required": ["$kind", "fieldName", "fieldType", "source"],
+      "properties": {
+        "$kind": { "const": "FieldMapping" },
+        "fieldName": { "type": "string", "minLength": 1 },
+        "fieldType": { "type": "integer", "minimum": 0, "maximum": 5, "description": "0=String, 1=Number, 2=Integer, 3=Boolean, 4=Date, 5=Timestamp" },
+        "source": { "$ref": "#/$defs/ExtractionSource" },
+        "parseFormat": { "type": ["string", "null"] },
+        "cultureName": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "RepeatingFieldMapping": {
+      "type": "object",
+      "required": ["$kind", "collectionFieldName", "elementDefinition", "source", "subFields"],
+      "properties": {
+        "$kind": { "const": "RepeatingFieldMapping" },
+        "collectionFieldName": { "type": "string", "minLength": 1 },
+        "elementDefinition": { "$ref": "#/$defs/RecordDefinition" },
+        "source": { "$ref": "#/$defs/ExtractionSource" },
+        "subFields": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SubFieldMapping" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "ExtractionSource": {
+      "oneOf": [
+        { "$ref": "#/$defs/TextPatternExtractionSource" },
+        { "$ref": "#/$defs/TextAnchorExtractionSource" },
+        { "$ref": "#/$defs/TableCellExtractionSource" },
+        { "$ref": "#/$defs/TableRowsExtractionSource" },
+        { "$ref": "#/$defs/MetadataFieldExtractionSource" },
+        { "$ref": "#/$defs/FallbackExtractionSource" }
+      ]
+    },
+    "TextPatternExtractionSource": {
+      "type": "object",
+      "required": ["$kind", "mode"],
+      "properties": {
+        "$kind": { "const": "TextPatternExtractionSource" },
+        "mode": { "type": "string", "enum": ["Token", "Pattern", "AllMatches"] },
+        "literalToken": { "type": "string" },
+        "regexPattern": { "type": "string" },
+        "pageNumber": { "type": "integer", "minimum": 1 },
+        "caseSensitive": { "type": "boolean" },
+        "blockSeparator": { "type": "string" },
+        "startAnchorPattern": { "type": ["string", "null"] },
+        "endAnchorPattern": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "TextAnchorExtractionSource": {
+      "type": "object",
+      "required": ["$kind", "region"],
+      "properties": {
+        "$kind": { "const": "TextAnchorExtractionSource" },
+        "region": { "$ref": "#/$defs/PdfBounds" },
+        "literalToken": { "type": "string" },
+        "regexPattern": { "type": "string" },
+        "pageNumber": { "type": "integer", "minimum": 1 },
+        "caseSensitive": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "PdfBounds": {
+      "type": "object",
+      "required": ["left", "top", "width", "height"],
+      "properties": {
+        "left": { "type": "number" },
+        "top": { "type": "number" },
+        "width": { "type": "number" },
+        "height": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "TableCellExtractionSource": {
+      "type": "object",
+      "required": ["$kind", "rowIndex"],
+      "properties": {
+        "$kind": { "const": "TableCellExtractionSource" },
+        "rowIndex": { "type": "integer", "minimum": 0 },
+        "columnIndex": { "type": "integer", "minimum": 0 },
+        "headerToken": { "type": "string" },
+        "pageNumber": { "type": "integer", "minimum": 1 },
+        "tableIndex": { "type": "integer", "minimum": 0 },
+        "caseSensitiveHeader": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "TableRowsExtractionSource": {
+      "type": "object",
+      "required": ["$kind", "mode"],
+      "properties": {
+        "$kind": { "const": "TableRowsExtractionSource" },
+        "mode": { "type": "string", "enum": ["ByHeader", "Ordinal"] },
+        "pageNumber": { "type": "integer", "minimum": 1 },
+        "tableIndex": { "type": "integer", "minimum": 0 },
+        "headerRowIndex": { "type": "integer", "minimum": 0 },
+        "skipRows": { "type": "integer", "minimum": 0 },
+        "caseSensitiveHeader": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "MetadataFieldExtractionSource": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": {
+        "$kind": { "const": "MetadataFieldExtractionSource" },
+        "standardField": { "type": "string", "enum": ["Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate", "ModifiedDate"] },
+        "rawKey": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "FallbackExtractionSource": {
+      "type": "object",
+      "required": ["$kind", "primary", "fallback"],
+      "properties": {
+        "$kind": { "const": "FallbackExtractionSource" },
+        "primary": { "$ref": "#/$defs/ExtractionSource" },
+        "fallback": { "$ref": "#/$defs/ExtractionSource" }
+      },
+      "additionalProperties": true
+    },
+    "SubFieldMapping": {
+      "oneOf": [
+        { "$ref": "#/$defs/HeaderSubFieldMapping" },
+        { "$ref": "#/$defs/OrdinalSubFieldMapping" },
+        { "$ref": "#/$defs/RegexGroupSubFieldMapping" },
+        { "$ref": "#/$defs/NamedGroupSubFieldMapping" }
+      ]
+    },
+    "HeaderSubFieldMapping": {
+      "type": "object",
+      "required": ["$kind", "fieldName"],
+      "properties": {
+        "$kind": { "const": "HeaderSubFieldMapping" },
+        "fieldName": { "type": "string", "minLength": 1 },
+        "headerToken": { "type": "string" },
+        "caseSensitive": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "OrdinalSubFieldMapping": {
+      "type": "object",
+      "required": ["$kind", "fieldName"],
+      "properties": {
+        "$kind": { "const": "OrdinalSubFieldMapping" },
+        "fieldName": { "type": "string", "minLength": 1 },
+        "columnIndex": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "RegexGroupSubFieldMapping": {
+      "type": "object",
+      "required": ["$kind", "fieldName"],
+      "properties": {
+        "$kind": { "const": "RegexGroupSubFieldMapping" },
+        "fieldName": { "type": "string", "minLength": 1 },
+        "groupIndex": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "NamedGroupSubFieldMapping": {
+      "type": "object",
+      "required": ["$kind", "fieldName"],
+      "properties": {
+        "$kind": { "const": "NamedGroupSubFieldMapping" },
+        "fieldName": { "type": "string", "minLength": 1 },
+        "groupName": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "FieldTransform": {
+      "oneOf": [
+        { "$ref": "#/$defs/TrimTransform" },
+        { "$ref": "#/$defs/CastTransform" },
+        { "$ref": "#/$defs/FormatTransform" },
+        { "$ref": "#/$defs/RenameTransform" },
+        { "$ref": "#/$defs/ComputeTransform" },
+        { "$ref": "#/$defs/CollectionElementTransform" }
+      ]
+    },
+    "TrimTransform": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": { "$kind": { "const": "TrimTransform" } },
+      "additionalProperties": true
+    },
+    "CastTransform": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": { "$kind": { "const": "CastTransform" } },
+      "additionalProperties": true
+    },
+    "FormatTransform": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": { "$kind": { "const": "FormatTransform" } },
+      "additionalProperties": true
+    },
+    "RenameTransform": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": { "$kind": { "const": "RenameTransform" } },
+      "additionalProperties": true
+    },
+    "ComputeTransform": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": { "$kind": { "const": "ComputeTransform" } },
+      "additionalProperties": true
+    },
+    "CollectionElementTransform": {
+      "type": "object",
+      "required": ["$kind"],
+      "properties": { "$kind": { "const": "CollectionElementTransform" } },
+      "additionalProperties": true
+    },
+    "PublishStep": {
+      "type": "object",
+      "properties": {
+        "configuration": { "type": "object" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/payload/commands/classify.md

@@ -0,0 +1,11 @@
+# Docuoria -- Classify
+
+Match a PDF against all templates in the store and report which template applies.
+
+## Invocation
+
+```bash
+dotnet script scripts/classify.csx -- --help
+```
+
+Refer to `SKILL.md` for the full argument reference and worked examples.

package/payload/commands/diagnose.md

@@ -0,0 +1,11 @@
+# Docuoria -- Diagnose
+
+Run a template end-to-end without producing output; surface extraction warnings and mismatches.
+
+## Invocation
+
+```bash
+dotnet script scripts/dry-run.csx -- --help
+```
+
+Refer to `SKILL.md` for the full argument reference and worked examples.

package/payload/commands/extract.md

@@ -0,0 +1,11 @@
+# Docuoria -- Extract
+
+Execute a template against a PDF and produce structured output (CSV or JSON).
+
+## Invocation
+
+```bash
+dotnet script scripts/execute.csx -- --help
+```
+
+Refer to `SKILL.md` for the full argument reference and worked examples.

package/payload/commands/inspect.md

@@ -0,0 +1,11 @@
+# Docuoria -- Inspect
+
+Read and display the text extraction a PDF yields so you can author or debug patterns.
+
+## Invocation
+
+```bash
+dotnet script scripts/inspect.csx -- --help
+```
+
+Refer to `SKILL.md` for the full argument reference and worked examples.

package/payload/commands/validate-template.md

@@ -0,0 +1,11 @@
+# Docuoria -- Validate Template
+
+Validate a template JSON file against the schema and report structural errors.
+
+## Invocation
+
+```bash
+dotnet script scripts/validate-template.csx -- --help
+```
+
+Refer to `SKILL.md` for the full argument reference and worked examples.

package/payload/examples/01-extract-to-csv.md

@@ -0,0 +1,49 @@
+# Example 1 — Extract to CSV (known template)
+
+## Scenario
+
+A PDF document with a header (a date and a reference number) and a repeating list of line items. A `Template` already exists in the local template store (a `templates/` directory at the workspace root); the goal is to produce a CSV from this PDF without authoring anything new.
+
+## Template excerpt
+
+The full template shape for this scenario (`PrimitiveFieldDefinition` for `refNumber` + `invoiceDate`, `RecordFieldDefinition` with `isCollection: true` for `lineItems`, three `FieldMapping`/`RepeatingFieldMapping` extraction mappings) is documented in [`../references/template-reference.md` § Complex template](../references/template-reference.md#complex-template-scalar-fields--repeating-collection). The single mapping that drives the repeating CSV rows looks like:
+
+```json
+{
+  "$kind": "RepeatingFieldMapping",
+  "collectionFieldName": "lineItems",
+  "source": {
+    "$kind": "TextPatternExtractionSource",
+    "mode": "AllMatches",
+    "regexPattern": "(?<description>[A-Za-z ]+?)\\s+\\$(?<amount>[\\d,.]+)"
+  },
+  "subFields": [
+    { "$kind": "NamedGroupSubFieldMapping", "fieldName": "description", "fieldType": 0, "groupName": "description" },
+    { "$kind": "NamedGroupSubFieldMapping", "fieldName": "amount", "fieldType": 1, "groupName": "amount" }
+  ]
+}
+```
+
+Note: `fieldType` is an **integer** (0 = String, 1 = Number, 4 = Date). See the template reference for the canonical enum table.
+
+## Steps
+
+1. `dotnet script scripts/list-templates.csx -- --store-path ./templates` — find the template ID that should apply.
+2. `dotnet script scripts/load-template.csx -- --id <id> --store-path ./templates` — confirm the template loaded and inspect its fields. Add `--output <path>` to write the JSON to a file.
+3. `dotnet script scripts/dry-run.csx -- --pdf <pdf> --template <template.json>` — confirm a `DryRunSucceeded` outcome. Inspect the extracted fields and (if needed) the `ExtractionDiagnostics` snapshot before publishing.
+4. `dotnet script scripts/execute.csx -- --pdf <pdf> --template <template.json> --format csv --output output.csv` — runs the full pipeline through the registered CSV generator. Engine API used: `IDocuoriaEngine.ExecuteTemplateAsync<CsvOutputGenerator, CsvGeneratorOptions>`.
+
+## Expected outcome
+
+`ProcessingResult` is `SucceededResult`; `output.csv` exists with rows matching the document's line items, in document order, with the header columns implied by the template's schema.
+
+## If it fails
+
+Go to [`../references/failure-tree.md`](../references/failure-tree.md). Map the script's stderr `error.code` to a branch via [§ Stderr error.code → Branch routing](../references/failure-tree.md#stderr-errorcode--branch-routing): `rejected` → Branch A (read `RejectionReason` in `detail`); `failed` → Branch B (read `StepIdentifier` in `detail`). If `dry-run.csx` already returned `DryRunSucceeded` but `execute.csx` then returned `rejected` with `RejectionReason.GeneratorRejected`, the generator is rejecting the shape — Branch A's `GeneratorRejected` row covers the remediation.
+
+## See also
+
+- [`../references/template-reference.md` § Complex template](../references/template-reference.md#complex-template-scalar-fields--repeating-collection) — full template JSON shape used in this example.
+- [`../references/workflow.md`](../references/workflow.md) Steps 5–7 — this example exercises dry-run, execute, and the store lookup at the start.
+- [`../references/scripts.md`](../references/scripts.md) — full flag list and output envelope for every script invoked here.
+

package/payload/examples/02-classify-unknown-pdf.md

@@ -0,0 +1,102 @@
+# Example 2 — Classify an unknown PDF
+
+## Scenario
+
+A PDF document arrives. You do not know whether any stored template matches it. The templates are in a local store directory (`./templates`). The goal is to route the PDF to a matching template, identify a partial match to refine, or recognise it needs a new template authored.
+
+## How classification works
+
+The `classify.csx` script evaluates every stored template's `rootMatchRule` against the PDF and returns the top-N templates ranked by `confidence` — an aggregated score (`ruleConfidence × extractionProbeScore`) that reflects both rule match strength and extraction viability. This gradient lets you distinguish between strong matches, partial matches worth refining, and complete misses.
+
+## Example match rules — weak vs. strong
+
+### Weak — vendor tokens only (poor discrimination)
+
+```json
+{
+  "rootMatchRule": {
+    "$kind": "TextPatternMatchRule",
+    "tokens": ["Microsoft", "Invoice", "Bill To"],
+    "mode": 1,
+    "threshold": 0.5
+  }
+}
+```
+
+Every Microsoft invoice (subscription, Azure, support) contains these tokens. All would score `confidence: 1.0` — no discrimination.
+
+### Strong — composite with discriminator (produces meaningful gradients)
+
+```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 Qty", "Seats"],
+          "mode": 0,
+          "threshold": 0.6
+        },
+        "weight": 2.0
+      }
+    ]
+  }
+}
+```
+
+The first child is a broad gate (must be a Microsoft Invoice). The second child — weighted at 2.0 — is the **discriminator** that targets subscription invoices specifically. A subscription invoice scores `confidence: 1.0`. An Azure usage invoice scores `confidence: 0.33` (discriminator fails: `(1.0×1 + 0.0×2) / 3`). The gradient clearly separates the two.
+
+## Steps
+
+1. **Classify:** `dotnet script scripts/classify.csx -- --pdf <pdf> --store-path ./templates`
+
+   Example output:
+   ```json
+   {
+     "matches": [
+       { "templateId": "ms-subscription-invoice", "confidence": 0.92 },
+       { "templateId": "ms-azure-invoice", "confidence": 0.35 },
+       { "templateId": "generic-invoice", "confidence": 0.12 }
+     ]
+   }
+   ```
+
+2. **Interpret the results:** map the top match's `confidence` to an action using the canonical gradient table in [`../references/classification.md` § Interpreting the gradient](../references/classification.md#interpreting-the-gradient). An empty `matches` array means no templates are stored — author from scratch.
+
+3. **For a strong match** — verify correctness:
+   - Run `dotnet script scripts/dry-run.csx -- --pdf <pdf> --template <matched-id-or-path>`
+   - If extraction produces expected data → done.
+   - If extraction produces empty collections or nonsensical data → **misclassification**. See [`../references/failure-tree.md`](../references/failure-tree.md) Branch C.
+
+4. **For a partial match** — try extraction, then iterate:
+   - Run dry-run with the top-scoring template. Even if some fields are incomplete, others may transfer.
+   - Load the template (`load-template.csx -- --id <matched-id> --store-path ./templates`), adjust the match rules and extraction sources for the new document type.
+   - Validate the updated template with positive + negative testing before storing.
+
+5. **When authoring a new template** — validate classification before storing:
+   - **Positive:** `dotnet script scripts/evaluate-match.csx -- --pdf <target.pdf> --template <new-template.json>` → high `confidence`.
+   - **Negative:** repeat with PDFs from the same vendor that should NOT match → low `confidence`.
+   - **Ranked:** `dotnet script scripts/classify.csx -- --pdf <target.pdf> --store-path ./templates` → new template must rank #1 with a clear gap over siblings.
+
+## Expected outcome
+
+Either: a high-confidence match → proceed to extraction. Or: a partial match → refine an existing template. Or: no meaningful match → author a new template with clear diagnostic insight into why existing templates scored low.
+
+## See also
+
+- [`../references/classification.md`](../references/classification.md) — full guide to designing discriminating match rules and interpreting the confidence gradient.
+- [`../references/workflow.md`](../references/workflow.md) Step 1 — classify is the entry point; confidence routing determines the next step.
+- [`../references/failure-tree.md`](../references/failure-tree.md) Branch C — diagnosing classification issues with ranked output.