landlord overrides

CONTEXT.md

@@ -31,6 +31,20 @@ _Avoid_: aggregator, merger
 The terminal action that reads the combiner output, inserts rows as Properties on the Portfolio, and decides whether the BulkUpload needs further review.
 _Avoid_: import, commit, ingest
 
+### Landlord overrides
+
+**Landlord**:
+The housing association supplying a Portfolio's BulkUploads. A Landlord knows facts about their properties that EPC data doesn't (e.g. that a cavity has been filled), and those facts take precedence when computing an assessment.
+_Avoid_: customer, client, owner, organisation (Organisation is a separate, broader entity)
+
+**Landlord override**:
+A landlord-supplied fact about a property that takes precedence over EPC-derived defaults when computing an assessment. The end-to-end Landlord override journey has two layers — a **VocabularyMapping** layer (this glossary entry below) and a per-Property fact layer (not yet modelled).
+_Avoid_: customer data, manual override, landlord data
+
+**VocabularyMapping**:
+The translation from a Landlord's free-text description in a BulkUpload column (e.g. `"cavity: filledcavity"`) to a canonical domain enum value (e.g. `WallType.CAVITY`). Produced by a `ColumnClassifier` (today an LLM, tomorrow possibly a lookup table or rules engine) in the Model service. Stored per-Portfolio, one row per `(category, description)`. A row carries provenance (`classifier` or `user`) so user overrides survive re-classification.
+_Avoid_: column mapping (that's a separate concept — see `ColumnMapping` above), classification, dictionary
+
 ## Lifecycle
 
 A **BulkUpload** moves through these statuses:
@@ -58,6 +72,7 @@ See [ADR-0001](./docs/adr/0001-bulk-upload-state-machine.md) for the deliberate
 - A **Portfolio** has many **BulkUploads**.
 - A **BulkUpload** produces zero or more **Properties** when finalised.
 - A **BulkUpload** has at most one **Task** (the orchestration handle for the FastAPI pipeline run); a Task has many **SubTasks** (one per pipeline stage: address matching, combiner).
+- A **Portfolio** has many **VocabularyMappings** — one row per `(category, description)` it has ever encountered across all its BulkUploads. See [ADR-0002](./docs/adr/0002-landlord-override-vocabulary.md).
 
 ## Example dialogue