Implement LLM-WP-0007: Kimi K3 default and EUR spend reporting

Add moonshotai/kimi-k3 as OpenRouter basemodel default after live smoke,
USD→EUR cost conversion, append-only usage ledger, and CLI run/cost/spend
week commands with token and euro reporting.

contracts/functional/costs.md

@@ -1,7 +1,8 @@
 # Cost Estimates
 
 `llm_connect.costs` converts token estimates or observed token counts into
-USD estimates using `ModelRateRegistry`.
+USD estimates using `ModelRateRegistry`, and optionally into EUR via
+`llm_connect.fx`.
 
 ## Contract
 
@@ -9,6 +10,7 @@ USD estimates using `ModelRateRegistry`.
 from llm_connect import estimate_cost
 
 estimate = estimate_cost("openai/gpt-4o-mini", 28_000, 7_500)
+estimate = estimate_cost("moonshotai/kimi-k3", 1_000, 500, fx=0.92)
 ```
 
 For known models the result is:
@@ -17,9 +19,16 @@ For known models the result is:
 - `prompt_cost_usd`: prompt-token component.
 - `completion_cost_usd`: completion-token component.
 - `cost_source`: `rate_table:<model_id>`.
+- `cost_eur` / `prompt_cost_eur` / `completion_cost_eur`: EUR display amounts
+  when FX is available (default: bundled snapshot, override with `fx=` or
+  env `LLM_CONNECT_EUR_PER_USD` as euros-per-USD).
+- `fx_source`: how EUR was derived (`explicit`, `env:…`, `snapshot:…`).
 
-Unknown models return `CostEstimate(cost_usd=None, cost_source="unknown")`.
-Missing rates are never silently treated as zero cost.
+Unknown models return `CostEstimate(cost_usd=None, cost_source="unknown")`
+with EUR fields also `None`. Missing rates or FX are never silently treated
+as zero cost.
 
-The module also exposes `CostModel(registry=...)` for callers that prefer to
-carry a registry object and call `model.estimate_cost(...)`.
+Pass `apply_fx=False` to skip EUR conversion.
+
+The module also exposes `CostModel(registry=..., fx=...)` for callers that
+prefer to carry a registry object and call `model.estimate_cost(...)`.

contracts/functional/rates.md

@@ -8,7 +8,8 @@ post-hoc estimates.
 - `ModelRate` records `model_id`, prompt and completion rates in USD per
   1,000 tokens, `currency`, `source_url`, and `captured_at`.
 - `ModelRateRegistry.default()` returns the bundled OpenRouter snapshot
-  captured on `2026-05-17`.
+  (base rates captured `2026-05-17`; `moonshotai/kimi-k3` captured
+  `2026-08-03` at `$0.003` / `$0.015` per 1k prompt/completion).
 - `ModelRateRegistry.from_yaml(path)` accepts the package/consumer override
   shape:
 
@@ -21,10 +22,14 @@ rates:
   openai/gpt-4o-mini:
     prompt_per_1k: 0.00015
     completion_per_1k: 0.00060
+  moonshotai/kimi-k3:
+    prompt_per_1k: 0.003
+    completion_per_1k: 0.015
 ```
 
 - `merged_with(override)` returns a new registry where matching override
   entries replace default entries by `model_id`.
 
 Rates are a static snapshot. Consumers decide whether `captured_at` is fresh
-enough for their workflow.
+enough for their workflow. List prices remain USD; EUR display conversion is
+handled by `llm_connect.fx` / `estimate_cost`.

contracts/functional/usage-ledger.md

@@ -0,0 +1,33 @@
+# Usage Ledger and Spend Windows
+
+`llm_connect.usage` stores append-only spend events for operator cost reporting.
+It is separate from `QualityLedger` (adaptive routing quality signals).
+
+## UsageEvent
+
+Each event records provider, model, token counts, estimated `cost_usd` /
+`cost_eur`, cost/FX sources, call `source` (`cli` | `server` | `library`),
+and `recorded_at` (UTC).
+
+## Paths
+
+1. Explicit `--ledger` / constructor path
+2. Env `LLM_CONNECT_USAGE_LEDGER`
+3. `$XDG_DATA_HOME/llm-connect/usage.jsonl`
+4. `~/.local/share/llm-connect/usage.jsonl`
+
+Library and server auto-recording only runs when `LLM_CONNECT_USAGE_LEDGER` is
+set (opt-in). CLI `run` records by default to the resolved path unless
+`--no-ledger`.
+
+## Week windows
+
+`week_window("current"|"last", tz=...)` returns Monday-based half-open ranges
+in local time (default `Europe/Berlin`, override with `LLM_CONNECT_TZ` or
+`--tz`):
+
+- **current**: Monday 00:00 → now
+- **last**: previous Monday 00:00 → this Monday 00:00 (full Mon–Sun week)
+
+`UsageLedger.sum_range(start, end)` aggregates tokens and costs for
+`[start, end)`.