docs/decisions/README.md

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; 0001 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: 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	Record architecture decisions	Accepted	Use Nygard-format ADRs in docs/decisions/; number sequentially, supersede never delete.
0002	AI-first price replies with a deterministic fallback	Accepted	Grounded LLM renders prices; deterministic formatters are the fallback; not-found skips the LLM.
0003	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	Firestore: target pricelystmeta1 via database_id=	Accepted	Fix 404s: use firebase-admin database_id=, default DB pricelystmeta1.
0005	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	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.