# Architecture Decision Records

This directory records the **why** behind notable choices in this codebase, so
future developers and Claude Code sessions don't re-litigate settled questions or
undo hard-won fixes. We use the [Michael Nygard ADR format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions);
[0001](0001-record-architecture-decisions.md) is the template and the rules.

**New to the project? Read this index first**, then open the ADRs relevant to
what you're touching before exploring the code.

## How to add one
- Copy the section layout of [0001](0001-record-architecture-decisions.md):
  Context / Decision / Consequences / Rejected alternatives.
- Name it `000N-short-title.md`, the next number in sequence. Never reuse or
  renumber. Never delete — supersede instead (mark the old one
  `Superseded by [000M]` and link forward).
- Add a one-line row to the table below.
- Write one whenever you make a non-trivial architectural/design decision, debug
  something worth remembering, or rule out an approach after real investigation —
  don't wait to be asked.

## Index
| # | Title | Status | Summary |
|---|-------|--------|---------|
| [0001](0001-record-architecture-decisions.md) | Record architecture decisions | Accepted | Use Nygard-format ADRs in `docs/decisions/`; number sequentially, supersede never delete. |
| [0002](0002-ai-first-rendering-with-deterministic-fallback.md) | AI-first price replies with a deterministic fallback | Accepted | Grounded LLM renders prices; deterministic formatters are the fallback; not-found skips the LLM. |
| [0003](0003-lexical-search-with-fuzzy-and-abstention.md) | Hand-tuned lexical search with fuzzy matching and an abstention floor | Accepted | Weighted lexical signals + difflib fuzzy + relevance cutoff + score floor (abstain), not embeddings yet. |
| [0004](0004-firestore-database-id-pricelystmeta1.md) | Firestore: target `pricelystmeta1` via `database_id=` | Accepted | Fix 404s: use firebase-admin `database_id=`, default DB `pricelystmeta1`. |
| [0005](0005-conversation-transcript-and-distillation-store.md) | Capture transcript at transport chokepoints; separate distillation store | Accepted | Log every msg via webhook + wrapped senders into `chat_logs`; grounded pairs go to `training_examples`. |
| [0006](0006-promotions-source-and-dynamic-retailers.md) | Promotions from `/api/v1/promotions`; dynamic retailer buttons | Accepted | Use the open promotions feed (`pivot.promo_price`); build retailer buttons from `retailer_id`; deals feed is auth-gated. |