> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winnerr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Locker — Obligations & Search

> Deadlines extracted from executed documents, a command-center obligations feed, and semantic document search.

Locker turns every completed document into an active part of your workflow. Deadlines are extracted from the document's data and surfaced as obligations in the command center; the full document repository is searchable with natural-language queries.

## Obligations

An obligation is a deadline or financial commitment derived from a document's canonical data. For typed OREA/TRREB packs, obligations are derived **deterministically**—no AI is involved, and the result is exact.

### Obligation types

| Type               | Source                       | Example                                            |
| ------------------ | ---------------------------- | -------------------------------------------------- |
| `closing`          | `dates.completionDate`       | Closing on March 15, 2027                          |
| `condition_waiver` | Each condition's waiver date | Financing condition waiver due March 1, 2027       |
| `deposit_due`      | `money.deposit` timing       | Deposit due within 24 hours of acceptance          |
| `expiry`           | Irrevocability date          | Offer irrevocable until March 10, 2027 at 11:59 PM |
| `renewal`          | Lease term expiry            | Lease renewal decision due June 30, 2027           |

When a document is generated, obligations are written to the `DocumentObligation` table and linked to the document's deal (if one is set). When a document is signed (`DOCUMENT_SIGNED` event), the obligations are re-synced to reflect the executed state.

### Urgency

Each obligation carries an urgency level computed from its due date relative to today:

| Urgency    | Meaning                                      |
| ---------- | -------------------------------------------- |
| `pending`  | Due date is in the future and not yet urgent |
| `due_soon` | Due within the next few days                 |
| `overdue`  | Due date has passed                          |

### The obligations feed

The obligations feed (`GET /api/documents/obligations`) returns upcoming and overdue obligations across your organization's documents, sorted soonest first. By default it looks ahead 30 days; pass `?withinDays=N` to adjust the window (maximum 365).

```json theme={null}
{
  "obligations": [
    {
      "id": "obl_abc123",
      "documentId": "doc_def456",
      "dealId": "deal_ghi789",
      "type": "condition_waiver",
      "description": "Financing condition waiver",
      "dueDate": "2027-03-01T00:00:00.000Z",
      "amountCents": null,
      "urgency": "due_soon"
    }
  ]
}
```

## Semantic search

Locker indexes every document's content as a vector embedding, enabling natural-language search over your document repository.

Example queries:

* "leases expiring this summer with rent over \$3,000"
* "condo purchase agreements for Harbour Street"
* "rental applications with pets clause"

Search returns a ranked list of document IDs with similarity scores. Your application or the in-app search bar can then fetch the matched documents for display.

<Warning>
  Semantic search requires the AI gateway to be configured (`@repo/ai`, including an embedding model accessible via the `AI_EMBEDDING_MODEL` environment variable). Without it, documents are still stored and their obligations are tracked, but natural-language search will return no results.
</Warning>

Embeddings are generated automatically when a document is rendered (generated). They are also regenerated when a signed document is re-indexed. The embedding model defaults to `text-embedding-3-small` and is configurable via the `AI_EMBEDDING_MODEL` environment variable.

### What is indexed

The embedding is built from the document's canonical data (all string values, traversed up to six levels deep) prefixed with the form key. For a typed OREA pack this includes parties, addresses, dates, amounts, conditions, and schedules. For uploaded generic templates it includes whatever text is in the fill data.

## Obligation extraction from uploaded documents

For uploaded (generic) PDF templates and completed documents imported from external providers (such as DocuSign Connect), Locker can extract obligations using the AI gateway. The extraction is Zod-validated—the model's output is checked against the obligation schema and rejected if it does not conform.

AI-extracted obligations are flagged with `extractedByAi: true` so you can distinguish them from the deterministic OREA-pack derivation.

<Warning>
  AI extraction requires the AI gateway to be configured. Typed OREA/TRREB packs never use AI extraction for obligations—their deadlines are derived exactly from the canonical data.
</Warning>

## CRM wiring

Obligations link to deals via `dealId`. The morning command center reads the obligations feed and displays upcoming deadlines in urgency order.

<Note>
  A signed document does not automatically advance the deal stage or create a [closing checklist](/crm/closing-checklist) on the deal — those are separate, manual steps today. The closing checklist has its own closing date and milestones; it is not generated from a document's obligations.
</Note>

## Related

* [Generate](/documents/generate) — obligations are written at generate time for typed OREA packs.
* [Sign](/documents/sign) — signing re-syncs obligations to the executed state.
* [Closing Checklist](/crm/closing-checklist) — a separate, deal-level milestone tracker with its own closing date.
* [Documents API — obligations endpoint](/api-reference/documents#obligations) — the raw feed.
* [Documents API — search endpoint](/api-reference/documents#search) — semantic search.