docs: update ADRs

Author: udmada

docs/adr/001-scanevantrepository-integration-tests-only.md

@@ -1,4 +1,4 @@
-# ADR 001: ScanEventRepository — Integration Tests Only, No IDbConnection Factory
+# ADR 001: ScanEventRepository - Integration Tests Only, No IDbConnection Factory
 
 **Status:** Accepted
 **Date:** 2026-02-21
@@ -17,15 +17,15 @@ Do not introduce an `IDbConnection` factory. Accept that `ScanEventRepository` a
 
 ### The meaningful abstraction already exists
 
-`IScanEventRepository` means every consumer — `ApiPollerWorker`, `EventProcessorWorker`, and `ScanEventProcessor` — can be fully tested with NSubstitute mocks without touching a database. The repository implementation being untestable without a DB is a much smaller problem than the workers being untestable.
+`IScanEventRepository` means every consumer - `ApiPollerWorker`, `EventProcessorWorker`, and `ScanEventProcessor` - can be fully tested with NSubstitute mocks without touching a database. The repository implementation being untestable without a DB is a much smaller problem than the workers being untestable.
 
 ### Mocking IDbConnection is unsafe under Dapper.AOT
 
-Dapper.AOT generates source-level interceptors that target specific `SqlConnection` call sites at compile time. A mock `IDbConnection` would not trigger those interceptors — tests would execute different code paths than production, making them unreliable and potentially misleading.
+Dapper.AOT generates source-level interceptors that target specific `SqlConnection` call sites at compile time. A mock `IDbConnection` would not trigger those interceptors - tests would execute different code paths than production, making them unreliable and potentially misleading.
 
 ### The SQL is the logic
 
-The interesting correctness properties of `ScanEventRepository` — the MERGE semantics, the idempotency guard, the PICKUP/DELIVERY timestamp invariant — live in the SQL strings. No amount of `IDbConnection` mocking verifies that the SQL is correct. This is genuine integration-test territory.
+The interesting correctness properties of `ScanEventRepository` - the MERGE semantics, the idempotency guard, the PICKUP/DELIVERY timestamp invariant - live in the SQL strings. No amount of `IDbConnection` mocking verifies that the SQL is correct. This is genuine integration-test territory.
 
 ### Deadline and risk
 
@@ -41,7 +41,7 @@ Introducing a new abstraction layer less than two days before the deadline risks
 
 ## Consequences
 
-- `ScanEventRepository` and `DatabaseInitializer` are covered by integration tests only (requiring a running SQL Server — see Docker Compose setup in README).
+- `ScanEventRepository` and `DatabaseInitializer` are covered by integration tests only (requiring a running SQL Server - see Docker Compose setup in README).
 - All higher-level components (`ScanEventProcessor`, workers) remain fully unit-testable via `IScanEventRepository`.
 - The README documents the integration-test gap.
 

docs/adr/002-no-saga-pattern.md

@@ -18,16 +18,16 @@ Don't use it. The design already handles failures correctly without a coordinato
 
 ## Why
 
-If `SendToSqs` fails, `LastEventId` doesn't advance — the next poll re-covers those events.
-If `MergeToDb` fails, the message isn't deleted — SQS redelivers via visibility timeout.
+If `SendToSqs` fails, `LastEventId` doesn't advance - the next poll re-covers those events.
+If `MergeToDb` fails, the message isn't deleted - SQS redelivers via visibility timeout.
 
 Both chains self-recover because the MERGE is idempotent:
 
 ```sql
 incoming.EventId > stored.LatestEventId
 ```
 
-Replaying the same event is a no-op. Saga exists to handle cases where replay is *not* safe. That case doesn't exist here.
+Replaying the same event is a no-op. Saga exists to handle cases where replay is _not_ safe. That case doesn't exist here.
 
 ## What Saga Would Have Cost
 
@@ -41,12 +41,12 @@ All of that is already implicit in `LastEventId` + SQS visibility timeout. Addin
 
 This decision is specific to the current poll-based design. In an event-driven model the calculus changes.
 
-Each scan event arriving could naturally produce side-effects across multiple systems — a row written to DynamoDB for real-time lookup, a record appended to S3 for compliance archiving, a downstream notification, an audit trail. Each of those writes is a discrete step with its own failure mode. That's exactly the problem Saga is designed for: coordinating a sequence of steps across systems where partial failure needs explicit handling.
+Each scan event arriving could naturally produce side-effects across multiple systems - a row written to DynamoDB for real-time lookup, a record appended to S3 for compliance archiving, a downstream notification, an audit trail. Each of those writes is a discrete step with its own failure mode. That's exactly the problem Saga is designed for: coordinating a sequence of steps across systems where partial failure needs explicit handling.
 
-AWS Step Functions would carry most of the weight here — the state machine, retry policies, compensation routing, and execution history are all provided out of the box. The idempotency invariant still applies and still protects against duplicate executions, but Saga would earn its complexity cost in that design.
+AWS Step Functions would carry most of the weight here - the state machine, retry policies, compensation routing, and execution history are all provided out of the box. The idempotency invariant still applies and still protects against duplicate executions, but Saga would earn its complexity cost in that design.
 
 The current poll-based single-DB design doesn't have that fan-out problem, so Saga adds nothing today.
 
 ## Note on Test Cancellation
 
-The `CancellationToken` complexity in the worker tests is a test harness concern — how to drive a `BackgroundService` loop one iteration at a time. It's unrelated to this decision.
+The `CancellationToken` complexity in the worker tests is a test harness concern - how to drive a `BackgroundService` loop one iteration at a time. It's unrelated to this decision.

docs/local-setup.md

@@ -28,24 +28,16 @@ This starts:
 - **Azure SQL Edge** on `localhost:1433` (ARM64-compatible SQL Server)
 - **LocalStack** on `localhost:4566` (local SQS emulator - queues auto-created via `scripts/init-localstack.sh`)
 
-### 3. Create the database
+The `ScanEvents` database and schema tables are auto-created by `DatabaseInitialiser` on first worker startup — no manual `sqlcmd` step required.
 
-```bash
-docker exec -it $(docker ps -q -f ancestor=mcr.microsoft.com/azure-sql-edge) \
-  /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'YourStr0ngPassw0rd!' \
-  -Q "CREATE DATABASE ScanEvents"
-```
-
-The worker auto-creates the `ProcessingState` and `ParcelSummary` tables on startup via `DatabaseInitialiser`.
-
-### 4. Set dummy AWS credentials (LocalStack doesn't validate them)
+### 3. Set dummy AWS credentials (LocalStack doesn't validate them)
 
 ```bash
 export AWS_ACCESS_KEY_ID=test
 export AWS_SECRET_ACCESS_KEY=test
 ```
 
-### 5. Configure the API base URL (required)
+### 4. Configure the API base URL (required)
 
 The worker cannot connect without this. Set it via user-secrets:
 
@@ -56,13 +48,13 @@ dotnet user-secrets set "ScanEventApi:BaseUrl" "https://your-api-host" \
 
 Or edit `ScanEventApi:BaseUrl` directly in `src/ScanEventWorker/appsettings.json`.
 
-### 6. Run the worker
+### 5. Run the worker
 
 ```bash
 dotnet run --project src/ScanEventWorker/ScanEventWorker.csproj
 ```
 
-### 7. Verify resumability
+### 6. Verify resumability
 
 Stop the worker (`Ctrl+C`) and restart it. The log will show: