@talonic/docs 0.20.9 → 0.20.10

package/dist/content.js

@@ -1602,6 +1602,10 @@ var sections5 = [
           "**Add reference tables** \u2014 For code fields (e.g., country name → ISO code), upload key-value pairs.",
           "**Publish** \u2014 Create an immutable version snapshot ready for job execution."
         ]
+      },
+      {
+        type: "paragraph",
+        text: "Most teams start by importing an existing spreadsheet or CSV as a template baseline, then refine field types and add extraction instructions. Once you publish a version, it becomes immutable and available for job execution \u2014 any further changes happen in a new **Workshop** draft, keeping your production schema stable while you iterate."
       }
     ],
     related: [
@@ -1678,6 +1682,10 @@ var sections5 = [
           }
         ]
       },
+      {
+        type: "paragraph",
+        text: "When configuring a field, start with the basics \u2014 name, type, and registry mapping \u2014 then layer on advanced features as needed. For example, add a **format constraint** to enforce a date pattern, attach a **reference table** for code lookups, or define **capture submoves** to control the exact extraction sequence. Features compose independently, so you can mix and match without conflicts."
+      },
       {
         type: "callout",
         text: "For the complete JSON Schema specification with all features, see the [Full Schema Reference](/docs/platform/schema-features) in the Platform Guide."
@@ -1740,6 +1748,10 @@ var sections5 = [
             description: "No match found \u2014 needs manual extraction instructions."
           }
         ]
+      },
+      {
+        type: "paragraph",
+        text: "When you add a field to a template, the system automatically attempts to match it against the **Field Registry**. Exact name matches are applied instantly, while semantic and composite matches appear as suggestions for your confirmation. If no match is found, the field is marked **Unmapped** and you should provide a manual extraction instruction so the AI knows how to extract that value from your documents."
       }
     ],
     related: [
@@ -1791,6 +1803,10 @@ var sections5 = [
           }
         ]
       },
+      {
+        type: "paragraph",
+        text: "To set up a reference table, upload a CSV or manually enter key-value pairs where the **key** is the code you want in your output and the **value** is the human-readable label found in documents. During extraction, the system tries each tier in order \u2014 most values resolve instantly at Tier 1, so keeping your labels clean and consistent dramatically improves both speed and accuracy."
+      },
       {
         type: "callout",
         text: "Reference table quality directly determines lookup accuracy. A properly loaded table produces 90-100% accurate results within a single run."
@@ -1829,6 +1845,10 @@ var sections5 = [
       {
         type: "paragraph",
         text: "Templates support a workshop system: **Live** (current published version, read-only), **Workshop** (mutable draft for editing), and **Version History** (timeline with diff summaries). When promoting a draft, the system detects breaking changes (field removals, type changes) and warns you."
+      },
+      {
+        type: "paragraph",
+        text: "Start by editing fields in the **Workshop** draft, then use **Test Extraction** to compare draft results against the live version before publishing. The **Version History** timeline lets you review diff summaries between any two versions, making it easy to trace when a field was added, renamed, or removed and understand the impact on downstream jobs."
       }
     ],
     related: [
@@ -1858,6 +1878,10 @@ var sections5 = [
       {
         type: "paragraph",
         text: "Before publishing a draft, run a test extraction to compare draft vs. live results side-by-side. Select a few documents, run the test, and see exactly how your changes affect output."
+      },
+      {
+        type: "paragraph",
+        text: "After running a test, you will see a comparison grid highlighting cells that changed between the draft and live versions. Focus on fields you modified \u2014 new fields, updated instructions, or changed reference tables \u2014 to verify they produce the expected values. This workflow catches regressions before they reach production, so you can iterate on your schema with confidence."
       }
     ],
     related: [
@@ -1923,6 +1947,10 @@ var sections5 = [
             description: "Output file encoding: UTF-8 (default), UTF-8-BOM, ISO-8859-1, etc."
           }
         ]
+      },
+      {
+        type: "paragraph",
+        text: "When working with international data, configure the dialect to match your downstream system requirements. For example, set **number_locale** to `fr-FR` for European comma-decimal formatting, switch the **delimiter** to semicolon for CSV compatibility, and choose **UTF-8-BOM** encoding if your data will be opened in Excel. Creating a shared dialect and reusing it across schemas ensures consistent formatting across all your exports."
       }
     ],
     related: [
@@ -1986,6 +2014,10 @@ var sections5 = [
           }
         ]
       },
+      {
+        type: "paragraph",
+        text: 'Use bypass strategies for fields whose values are known ahead of time or can be derived without reading the document. For example, set a **constant** of `"USD"` for a currency field that is always the same, or use a **generator** to produce a deterministic ID for each row. Fields with bypass strategies skip the AI extraction phase entirely, reducing processing time and credit usage.'
+      },
       {
         type: "callout",
         text: "When a `generator` strategy fails to produce a value, the field falls through to LLM extraction as a safety net. Strategy values are normalized via generator mappings in Phase 4 of the pipeline."
@@ -2122,6 +2154,10 @@ var sections6 = [
         type: "paragraph",
         text: "Every job runs through four phases. Each fills more cells in the output grid, reducing the problem space for the next. Results are visible as each phase completes."
       },
+      {
+        type: "paragraph",
+        text: "Each phase builds on the previous one, progressively filling the output grid. **Phase 1** resolves ~30% of cells instantly using graph matches and lookups. **Phase 2** deploys an AI agent to fill remaining gaps. **Phase 3** runs cross-field validation checks, and **Phase 4** performs targeted re-reads for empty or low-confidence cells. You can monitor fill rate in real time as each phase completes."
+      },
       {
         type: "ui-excerpt",
         id: "job-detail-phase-timeline",
@@ -2228,6 +2264,10 @@ var sections6 = [
         type: "paragraph",
         text: "An AI agent reviews the grid's gap patterns and produces a typed strategy:"
       },
+      {
+        type: "paragraph",
+        text: "The agent analyzes which cells are still empty after Phase 1 and selects the most efficient action for each. Simple calculations like `Total = Unit Price x Quantity` use the **compute** strategy without any AI calls, while truly missing data triggers an **extract** that re-reads the source document with targeted instructions. You can inspect the agent's chosen strategy for every field on the **Strategy Panel** of the job detail page."
+      },
       {
         type: "ui-excerpt",
         id: "job-detail-agent-strategy",
@@ -2301,6 +2341,10 @@ var sections6 = [
         type: "paragraph",
         text: "Cross-field sanity checks. Flags are **informational only** \u2014 they never block output but help you prioritize review:"
       },
+      {
+        type: "paragraph",
+        text: "After Phase 3 completes, flagged cells appear with warning indicators in the results grid. Use the **Flagged** filter to see only rows that need attention \u2014 for example, an **amount_mismatch** flag suggests you double-check a total that does not align with its component values. Addressing flagged cells first is the most efficient way to review large extraction runs."
+      },
       {
         type: "param-table",
         title: "Validation flags",
@@ -2367,6 +2411,10 @@ var sections6 = [
         type: "paragraph",
         text: "Context-aware gap filling. For each empty cell or low-confidence value, AI re-reads the original document with the field instruction and full grid context. This focused approach often finds values missed in earlier phases."
       },
+      {
+        type: "paragraph",
+        text: "Because Phase 4 has access to the full grid context \u2014 all values already resolved in earlier phases \u2014 it can use surrounding data as clues. For example, if a contract start date was resolved in Phase 1 but the end date is still empty, Phase 4 re-reads the document knowing the start date, which helps the AI locate the corresponding end date more accurately."
+      },
       {
         type: "callout",
         text: "Phase 4 respects the **confidence gate**: it can only fill empty cells or upgrade cells below the confidence threshold. High-confidence values from Phase 1 are permanently protected."
@@ -2405,6 +2453,10 @@ var sections6 = [
       {
         type: "paragraph",
         text: "The job detail page provides: a **progress bar** with fill rate, a **phase timeline**, the **strategy panel** (agent actions), a **filter bar** (Show All / Clean / Flagged), and **CSV export** (clean or full with metadata)."
+      },
+      {
+        type: "paragraph",
+        text: "Start your review by switching to the **Flagged** filter to focus on cells that need attention \u2014 these are values with validation warnings, low confidence, or format mismatches. Click any cell to see its full provenance, including which phase produced it and the reasoning trace. Once you are satisfied, export via **CSV** \u2014 choose the clean export for downstream systems or the full export with metadata for auditing."
       }
     ],
     related: [
@@ -2441,6 +2493,10 @@ var sections6 = [
         type: "paragraph",
         text: "Every cell carries detailed provenance. Hover a cell for confidence; click for full detail."
       },
+      {
+        type: "paragraph",
+        text: "When reviewing results, hover over any cell to see its **confidence score** at a glance. Click the cell to expand the full provenance panel, which shows the **resolution type**, the **phase** that produced the value, and a human-readable **reasoning trace** explaining how the value was derived. Use this information to quickly identify which cells need manual review and which can be trusted as-is."
+      },
       {
         type: "param-table",
         title: "Cell provenance fields",
@@ -2511,6 +2567,10 @@ var sections6 = [
       {
         type: "paragraph",
         text: "Click any cell to edit its value. Corrections are logged with the original value, timestamp, and user. Choose a propagation scope: `this_document_only` or `all_similar` (same field + method + source field across all documents). Corrections feed back as training signals for future runs."
+      },
+      {
+        type: "paragraph",
+        text: "When correcting a value, consider using **all_similar** propagation if the same mistake appears across multiple documents \u2014 for example, a reference table code that was consistently mapped to the wrong label. This applies your fix to every document in the run that matched the same way, saving you from correcting each cell individually. The system learns from these corrections, so the same error is less likely to recur in future jobs."
       }
     ],
     related: [
@@ -7085,6 +7145,7 @@ var sections22 = [
   }
 }`
       },
+      { type: "paragraph", text: "Most integrations call `POST /v1/jobs` immediately after defining or updating a schema via the schemas API. Once created, poll `GET /v1/jobs/:id` every 2-5 seconds and watch for `status` transitioning to `complete`. Pair with `GET /v1/jobs/:id/results` to retrieve the structured output rows as soon as the job finishes." },
       { type: "heading", level: 2, id: "create-job-errors", text: "Errors" },
       {
         type: "param-table",
@@ -7172,6 +7233,7 @@ var sections22 = [
   }
 }`
       },
+      { type: "paragraph", text: "This endpoint is typically used in a polling loop after `POST /v1/jobs`. Watch `current_phase` to track pipeline progression through `phase_1_resolve`, `phase_2_execute`, `phase_3_resolve`, and `phase_4_transform`. The `grid_stats.fill_rate` value increases as each phase completes, giving you a real-time quality signal before the job reaches `complete` status." },
       { type: "heading", level: 2, id: "get-job-errors", text: "Errors" },
       {
         type: "param-table",
@@ -7250,6 +7312,7 @@ var sections22 = [
   }
 }`
       },
+      { type: "paragraph", text: "Pair this with `GET /v1/jobs/:id/results` to retrieve any rows that were processed before cancellation. The `completed_documents` field in the response tells you how many documents finished before the job was stopped, so you can decide whether the partial results are usable or if a new job is needed." },
       { type: "heading", level: 2, id: "cancel-job-errors", text: "Errors" },
       {
         type: "param-table",
@@ -7354,6 +7417,7 @@ var sections22 = [
   }
 }`
       },
+      { type: "paragraph", text: "Returns one row per document with field values keyed by the schema field names you defined. Rows with `validation_flags` containing entries like `missing_required_field:<name>` or `format_mismatch:<name>` indicate Phase 4 detected data quality issues. Use the `confidence` score to prioritize which rows need manual review -- values below 0.8 typically warrant inspection." },
       { type: "heading", level: 2, id: "get-job-results-errors", text: "Errors" },
       {
         type: "param-table",
@@ -8002,7 +8066,8 @@ var sections24 = [
           { name: "404", type: "not_found", description: "No field with the given fieldId exists for your workspace." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: 'Pair this endpoint with the **field autocomplete** endpoint to build a two-step filter UI: first let the user select a field via `GET /fields/autocomplete`, then populate a dropdown with that field\'s distinct values from this endpoint. The `totalDistinct` count is useful for showing "N of M values" pagination hints.' }
     ],
     related: [
       { label: "Field Autocomplete", slug: "field-autocomplete" },
@@ -8104,7 +8169,8 @@ var sections24 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Build conditions programmatically by first calling `GET /fields/autocomplete` to resolve field IDs, then `GET /fields/:fieldId/values` to populate value pickers. The response includes the full `fieldValues` map per document, so you can render result tables without additional per-document fetches." }
     ],
     related: [
       { label: "Field Autocomplete", slug: "field-autocomplete" },
@@ -8188,7 +8254,8 @@ var sections24 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Returns categorized results across **documents**, **fieldMatches**, **sources**, **schemas**, and **fields** in a single call, so a Cmd+K palette can render grouped sections without multiple requests. Use the `limit` parameter to cap results per category and keep response times fast for interactive search." }
     ],
     related: [
       { label: "Filter Documents", slug: "filter-documents" },
@@ -8336,7 +8403,8 @@ var sections24 = [
           { name: "404", type: "not_found", description: "No saved filter with this ID exists." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Saved filters work as reusable presets for `POST /v1/documents/filter`. Store a complex combination of conditions, search text, and sort order once, then load it by ID and pass the saved `conditions` array directly to the filter endpoint. All team members in the organization can list and use saved filters." }
     ],
     related: [
       { label: "Filter Documents", slug: "filter-documents" }
@@ -8354,7 +8422,8 @@ var sections24 = [
     seoTitle: "Document Counts \u2014 Talonic Docs",
     description: "Query document counts grouped by filter conditions and source connections. Useful for building faceted navigation and dashboard widgets.",
     content: [
-      { type: "paragraph", text: "The document counts endpoint returns aggregate counts of documents matching filter conditions, grouped by source connection. Use it to power faceted navigation UIs and dashboard summary widgets without fetching full document lists." }
+      { type: "paragraph", text: "The document counts endpoint returns aggregate counts of documents matching filter conditions, grouped by source connection. Use it to power faceted navigation UIs and dashboard summary widgets without fetching full document lists." },
+      { type: "paragraph", text: "Call this before `POST /v1/documents/filter` to preview how many documents match your conditions without fetching the full result set. The response groups counts by **source connection**, so you can render per-source facets in a sidebar alongside the main document list." }
     ],
     related: [
       { label: "Filter Documents", slug: "filter-documents" }
@@ -8405,7 +8474,8 @@ var sections24 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "In a typical bulk-ingestion workflow, call `POST /v1/extract` for each file, wait for all `document.extraction.completed` webhooks, then trigger `POST /filter/materialize` once. After the backfill completes, all filter and omnisearch endpoints will reflect the newly ingested data." }
     ],
     related: [
       { label: "Filter Documents", slug: "filter-documents" }
@@ -8423,7 +8493,8 @@ var sections24 = [
     seoTitle: "Materialized Index \u2014 Talonic Docs",
     description: "The materialized field value index powers fast filter queries. Rebuild it after bulk document ingestion using the materialize endpoint.",
     content: [
-      { type: "paragraph", text: "The materialized index pre-computes and stores extracted field values for every document, enabling sub-second filter queries even on large workspaces. After bulk ingestion or schema changes, trigger a rebuild via the materialize endpoint to ensure the index stays current." }
+      { type: "paragraph", text: "The materialized index pre-computes and stores extracted field values for every document, enabling sub-second filter queries even on large workspaces. After bulk ingestion or schema changes, trigger a rebuild via the materialize endpoint to ensure the index stays current." },
+      { type: "paragraph", text: "Both `POST /v1/documents/filter` and `GET /v1/search` read from this materialized index. If filter results appear stale or miss recently processed documents, call `POST /filter/materialize` to rebuild. For single-document uploads the index updates automatically, so manual rebuilds are only needed after bulk operations." }
     ],
     related: [
       { label: "Materialize", slug: "document-counts" }
@@ -8757,6 +8828,7 @@ var sections26 = [
   }
 }`
       },
+      { type: "paragraph", text: "After creating a resolution, call `POST /v1/resolutions/{id}/execute` to start the pipeline. The typical workflow is: create a job via `POST /v1/jobs`, wait for `complete` status, then create and execute a resolution against the job's `source_run_id`. Each resolution captures its own **policy and dialect snapshots**, so you can re-run with different configurations without affecting previous results." },
       { type: "heading", level: 2, id: "create-resolution-errors", text: "Errors" },
       {
         type: "param-table",
@@ -8830,6 +8902,7 @@ var sections26 = [
   }
 }`
       },
+      { type: "paragraph", text: "This endpoint is typically used in a polling loop after calling `POST /v1/resolutions/{id}/execute`. Watch for `status` transitioning from `running` to `completed` or `failed`. Once `completed`, use `GET /v1/resolutions/{id}/results` to inspect per-field resolved values and the `resolution_step` that produced each canonical mapping." },
       { type: "heading", level: 2, id: "get-resolution-errors", text: "Errors" },
       {
         type: "param-table",
@@ -8904,6 +8977,7 @@ var sections26 = [
   ]
 }`
       },
+      { type: "paragraph", text: "Use the `resolution_step` field to understand how each value was normalized: `lookup` indicates a direct reference table match, `transfer` means the value was carried from the field registry, and `compute` means a deterministic formula produced the result. Fields where `resolved_value` is `null` were not matched by any strategy and retain their raw extracted value -- consider adding those values to your lookup tables for future runs." },
       { type: "heading", level: 2, id: "get-resolution-results-errors", text: "Errors" },
       {
         type: "param-table",
@@ -8976,6 +9050,7 @@ var sections26 = [
   }
 }`
       },
+      { type: "paragraph", text: 'The standard workflow is `POST /v1/resolutions` to create, then `POST /v1/resolutions/{id}/execute` to start processing. The endpoint returns immediately with `status: "running"` -- poll `GET /v1/resolutions/{id}` to detect completion. Deterministic lookups complete in seconds; runs that trigger the LLM fallback for ambiguous values take 1-5 minutes depending on the number of unresolved fields.' },
       { type: "heading", level: 2, id: "execute-resolution-errors", text: "Errors" },
       {
         type: "param-table",
@@ -9029,6 +9104,7 @@ var sections26 = [
   "deleted": true
 }`
       },
+      { type: "paragraph", text: "Common usage is to delete `failed` resolution runs before retrying with a new `POST /v1/resolutions`. The source job run and its extracted data are completely unaffected by this operation, so you can safely clean up resolution experiments without losing upstream results." },
       { type: "heading", level: 2, id: "cancel-resolution-errors", text: "Errors" },
       {
         type: "param-table",
@@ -9856,6 +9932,7 @@ var sections28 = [
   ]
 }`
       },
+      { type: "paragraph", text: 'Most integrations start with `GET /v1/jobs/runs/{runId}/nshot/summary` to check the overall `agreement_rate`, then drill into this endpoint to find `status: "red"` and `status: "yellow"` comparisons that need attention. Use the `override` and `judgement` fields to track which comparisons have already been reviewed and which still need a decision.' },
       { type: "heading", level: 2, id: "nshot-list-shots-errors", text: "Errors" },
       {
         type: "param-table",
@@ -9953,6 +10030,7 @@ var sections28 = [
   }
 }`
       },
+      { type: "paragraph", text: "This endpoint is typically called after identifying a problematic comparison in the `GET /v1/jobs/runs/{runId}/nshot/comparisons` list. Inspect the `values` array to see what each shot extracted, then check the `judgement` object for the LLM's recommendation. If `judgement.accepted` is `null`, you can submit a decision via `POST /v1/jobs/runs/{runId}/nshot/judge-decision`." },
       { type: "heading", level: 2, id: "nshot-compare-errors", text: "Errors" },
       {
         type: "param-table",
@@ -10055,6 +10133,7 @@ var sections28 = [
   }
 }`
       },
+      { type: "paragraph", text: "Use this when the **majority value** from the shots is incorrect and a different shot produced the right extraction. The `override` record captures a full audit trail including `from_value`, `to_value`, and `overridden_at`. Pair with the judge decision endpoint when you want to accept LLM recommendations programmatically instead of selecting shots manually." },
       { type: "heading", level: 2, id: "nshot-select-errors", text: "Errors" },
       {
         type: "param-table",
@@ -10161,6 +10240,7 @@ var sections28 = [
   }
 }`
       },
+      { type: "paragraph", text: 'This endpoint fits into a review workflow where you batch-process LLM judge recommendations. Retrieve comparisons with `judgement.accepted: null` from the comparisons list, then iterate through them calling this endpoint with `accepted: true` or `false`. Accepted decisions automatically create an override with `actor_id: "judge"`, so no separate override call is needed.' },
       { type: "heading", level: 2, id: "nshot-judge-decision-errors", text: "Errors" },
       {
         type: "param-table",
@@ -10324,7 +10404,8 @@ var sections29 = [
           { name: "404", type: "not_found", description: "No schema class with this ID exists for your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Use this endpoint to inspect a class before reviewing its pending diffs via `GET /v1/schema-graph/diffs?schema_class_id={id}`. The `current_version_id` tells you which version is live; follow the `links.versions` URL to compare previous snapshots and understand how the class has evolved." }
     ],
     related: [
       { label: "List Classes", slug: "list-schema-graph-classes" },
@@ -10398,7 +10479,8 @@ var sections29 = [
           { name: "404", type: "not_found", description: "No schema class with this ID exists for your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Compare two versions by fetching them individually with `GET /v1/schema-graph/classes/{id}/versions/{version}` and diffing their `json_schema` and `field_ids` arrays. This is useful for auditing how a class evolved after a diff was approved, or for building a changelog UI that shows added and removed fields per version." }
     ],
     related: [
       { label: "Get Version", slug: "get-class-version" },
@@ -10466,7 +10548,8 @@ var sections29 = [
           { name: "404", type: "not_found", description: "No schema class with this ID exists for your organization, or the requested version number does not exist." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "The `json_schema` object is a valid JSON Schema you can use directly for client-side validation or code generation. The `field_ids` array maps each schema property back to its field registry entry, so you can cross-reference with `GET /v1/fields/{id}` for extraction instructions and occurrence statistics." }
     ],
     related: [
       { label: "List Versions", slug: "list-class-versions" }
@@ -10551,7 +10634,8 @@ var sections29 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Filter by `status=pending` to build a review queue for ontology changes. Inspect the `added_fields`, `removed_fields`, and `type_changes` arrays to assess impact, then call `POST /v1/schema-graph/diffs/{id}/approve` or `/reject` to action each diff. The `classification` field (`additive` vs `breaking`) helps prioritize which diffs need careful review." }
     ],
     related: [
       { label: "Approve Diff", slug: "approve-diff" },
@@ -10606,7 +10690,8 @@ var sections29 = [
           { name: "404", type: "not_found", description: "No diff with this ID exists for your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Approval is synchronous -- the new version is created and `current_version_id` is updated in the same request. After approving, call `GET /v1/schema-graph/classes/{id}/versions` to verify the new version appeared, or fetch the updated class via `GET /v1/schema-graph/classes/{id}` to confirm `current_version_id` advanced." }
     ],
     related: [
       { label: "List Diffs", slug: "list-schema-graph-diffs" },
@@ -10660,7 +10745,8 @@ var sections29 = [
           { name: "404", type: "not_found", description: "No diff with this ID exists for your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: 'Rejected diffs are retained for audit and appear with `review_status: "rejected"` when listing diffs. If the same field changes are needed later, the platform generates a new diff automatically during the next extraction cycle. Use rejection to discard noisy or incorrect field discoveries without advancing the class version.' }
     ],
     related: [
       { label: "List Diffs", slug: "list-schema-graph-diffs" },
@@ -10735,7 +10821,8 @@ var sections29 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Pair this with `GET /v1/schema-graph/classes` to build relationship maps between document types. High-weight edges (e.g. `weight > 0.7`) indicate strong field overlap -- useful for identifying document types that should share user schema fields or be linked in cases. Feed the results directly into `GET /v1/schema-graph/visualize` for a D3-ready graph payload." }
     ],
     related: [
       { label: "List Classes", slug: "list-schema-graph-classes" },
@@ -10799,7 +10886,8 @@ var sections29 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: 'Use this endpoint to audit how variant document type labels resolve to canonical classes. For example, if documents labelled "Bill" and "Tax Invoice" both map to the **Invoice** class, they will share the same `schema_class_id`. This is useful for understanding classification behavior and debugging misclassified documents.' }
     ],
     related: [
       { label: "List Classes", slug: "list-schema-graph-classes" }
@@ -10882,7 +10970,8 @@ var sections29 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "The response is structured for direct consumption by D3.js force simulations, Cytoscape, or vis.js -- edge `source` and `target` fields reference node `id` values. Filter nodes client-side by `status` to exclude archived classes, and use edge `weight` to control link distance or opacity in your graph layout." }
     ],
     related: [
       { label: "Edges", slug: "list-schema-graph-edges" },
@@ -11088,7 +11177,8 @@ var sections30 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Newly created checks are automatically **active** and evaluate against all future structuring results. Pair this with `POST /v1/structuring/gates` and `POST /v1/structuring/gates/{id}/rules` to wire checks into an approval gate -- checks flag individual fields, while gate rules aggregate check outcomes to decide whether a result needs manual approval." }
     ],
     related: [
       { label: "List Checks", slug: "list-structuring-checks" },
@@ -11172,7 +11262,8 @@ var sections30 = [
           { name: "404", type: "not_found", description: "Validation check not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Use **PUT** to adjust thresholds (e.g. widening a `value_range` config) or to deactivate a check by setting `is_active` to `false` without deleting it. Historical check outcomes referencing this check are preserved regardless of updates or soft-deletion, so audit trails remain intact." }
     ],
     related: [
       { label: "List Checks", slug: "list-structuring-checks" },
@@ -11275,7 +11366,8 @@ var sections30 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Each gate embeds its active `rules` array, so you can inspect thresholds without a separate fetch. Use the `schema_id` query parameter to find which gates apply to a specific schema, then follow the `links.rules` URL to manage individual rules via `POST /v1/structuring/gates/{id}/rules`." }
     ],
     related: [
       { label: "Create Gate", slug: "create-structuring-gate" },
@@ -11367,7 +11459,8 @@ var sections30 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "A gate starts with an empty `rules` array, which means all results auto-approve until you add rules. The typical setup sequence is: create the gate, then immediately call `POST /v1/structuring/gates/{id}/rules` to add a `min_confidence` rule with your desired threshold. Optionally set `destination_id` to route approved results directly to a delivery destination." }
     ],
     related: [
       { label: "List Gates", slug: "list-structuring-gates" },
@@ -11459,7 +11552,8 @@ var sections30 = [
           { name: "404", type: "not_found", description: "Approval gate not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "The `rules` array is only populated on **GET** responses. After a **PUT** update, re-fetch with GET to confirm the current rule set. **DELETE** soft-deletes the gate by setting `is_active` to `false` -- pending approval items already queued by this gate remain in the queue and can still be actioned manually." }
     ],
     related: [
       { label: "List Gates", slug: "list-structuring-gates" },
@@ -11584,7 +11678,8 @@ var sections30 = [
           { name: "404", type: "not_found", description: "Approval gate or rule not found, or gate does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Rules are evaluated in `sort_order` ascending -- if any rule fails, the result is flagged for manual approval via `GET /v1/structuring/approvals/pending`. A common setup is a `min_confidence` rule at `sort_order: 0` followed by a `validation_pass_rate` rule at `sort_order: 1`, so confidence is checked before validation pass rate." }
     ],
     related: [
       { label: "Create Gate", slug: "create-structuring-gate" },
@@ -11658,7 +11753,8 @@ var sections30 = [
           { name: "404", type: "not_found", description: "Structuring result not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: 'Check outcomes are computed automatically when a structuring result is produced -- no manual trigger is needed. Use the embedded `check.name` and `check.severity` fields to render pass/fail badges in a review UI. Failed checks with `severity: "error"` are the ones that cause results to appear in `GET /v1/structuring/approvals/pending`.' }
     ],
     related: [
       { label: "List Checks", slug: "list-structuring-checks" },
@@ -11729,7 +11825,8 @@ var sections30 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Each item links a structuring result to the specific check that failed, so a single result can appear multiple times if it failed multiple checks. Use the `result_id` to group items by result, then call `POST /v1/structuring/approvals/{id}/approve` or `/reject` to action each one. Approving a result clears all its pending items and triggers the gate's `on_approve` action." }
     ],
     related: [
       { label: "Approve / Reject", slug: "approve-reject-result" },
@@ -11796,7 +11893,8 @@ var sections30 = [
           { name: "404", type: "not_found", description: "Structuring result or approval gate not found, or they do not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "After approving, the gate's `on_approve` action fires -- typically emitting a delivery signal. To batch-approve an entire run's results at once, iterate the pending approvals from `GET /v1/structuring/approvals/pending`, approve each individually, then call `POST /v1/structuring/delivery/{runId}` to trigger delivery for the full run." }
     ],
     related: [
       { label: "Pending Approvals", slug: "pending-approvals" },
@@ -11853,7 +11951,8 @@ var sections30 = [
           { name: "404", type: "not_found", description: "Job run not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "This endpoint is idempotent per result -- each approved result generates a deterministic idempotency key, so calling it multiple times on the same run does not produce duplicate deliveries. The typical workflow is: approve results individually via `POST /v1/structuring/approvals/{id}/approve`, then trigger delivery for the entire run once all reviews are complete." }
     ],
     related: [
       { label: "Approve / Reject", slug: "approve-reject-result" }
@@ -16644,7 +16743,8 @@ var sections39 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Most integrations poll this endpoint on a schedule to detect new items, then call `GET /v1/review/:id` to fetch full detail before rendering a review UI. Pair with `GET /v1/review/stats` to monitor queue depth and set alerting thresholds on the **pending** count." }
     ],
     related: [
       { label: "Review Stats", slug: "review-stats" },
@@ -16701,7 +16801,8 @@ var sections39 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "This endpoint is typically called on a dashboard polling loop to drive queue-depth indicators. Pair it with `GET /v1/review` filtered by `status=pending` to fetch the actual items once the **pending** count crosses your alerting threshold." }
     ],
     related: [
       { label: "List Review Items", slug: "list-review-items" },
@@ -16782,7 +16883,8 @@ var sections39 = [
           { name: "404", type: "not_found", description: "Review record not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Use the `low_confidence_fields` array to highlight problematic cells in your review UI before calling `POST /v1/review/:id/action`. The `field_decisions` object persists per-field overrides, so you can build interfaces where reviewers correct individual values and submit the decision in one step." }
     ],
     related: [
       { label: "Review Action", slug: "review-action" },
@@ -16866,7 +16968,8 @@ var sections39 = [
           { name: "404", type: "not_found", description: "Review record not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "After approval, the record's `status` changes to `approved` and a delivery signal is emitted into the outbox. Pair this with `POST /v1/review/batch` when you need to clear multiple items sharing similar characteristics, or call `GET /v1/review/stats` afterward to verify the **pending** count dropped as expected." }
     ],
     related: [
       { label: "Get Review Item", slug: "get-review-item" },
@@ -16936,7 +17039,8 @@ var sections39 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "A common pattern is to first call `GET /v1/review?status=pending` to collect IDs, filter client-side by `overall_confidence` above a safe threshold, then batch-approve those IDs here. Check the `results` array for per-item outcomes -- items that were already actioned return an error status but do not block the rest of the batch." }
     ],
     related: [
       { label: "Review Action", slug: "review-action" },
@@ -17018,7 +17122,8 @@ var sections39 = [
           { name: "404", type: "not_found", description: "Review record not found or does not belong to your organization." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Assignments are typically made after listing pending items via `GET /v1/review` and distributing them across team members. The `assigned_to` field appears in list and detail responses, so downstream tools can filter by assignee to build per-reviewer queues. Pass `null` as `user_id` to return an item to the unassigned pool." }
     ],
     related: [
       { label: "Get Review Item", slug: "get-review-item" },
@@ -18658,7 +18763,8 @@ var sections43 = [
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
         ]
-      }
+      },
+      { type: "paragraph", text: "Most integrations use registry query as a lookup layer after ingestion is complete. Call `POST /v1/extract` to ingest documents, wait for the `document.extraction.completed` webhook, then query the registry by field values to retrieve structured data across your entire corpus. Pair with `GET /v1/fields` to discover available canonical field names before building `where` conditions." }
     ],
     related: [
       { label: "Field Registry", slug: "field-registry" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talonic/docs",
-  "version": "0.20.9",
+  "version": "0.20.10",
   "description": "Talonic documentation components — API Reference & Platform Guide",
   "license": "UNLICENSED",
   "private": false,