feat: prepare ARR for controlled public deployment

monthly_reports/README.md

@@ -0,0 +1,27 @@
+# Database monthly reports
+
+`monthly_reports` is an ordinary deterministic program. It does not call an Agent/Skill and does not read a prior monthly workbook.
+
+Flow:
+
+1. Open one `REPEATABLE READ READ ONLY` snapshot of `finance.v_active_daily_facts`, current daily-version pins and current channel metrics.
+2. Build the channel worksheets and the 20-column monthly rows from those facts.
+3. Reserve a deterministic generation identity and recheck that all daily pins are still current.
+4. Generate a typed, formula-free XLSX; reopen and validate it.
+5. Recheck current pins before publishing the file to the controlled output/OSS layer.
+
+Monthly rows and report versions are intentionally not persisted in PostgreSQL. The database remains the source of truth; generated XLSX/result files can be retained as artifacts outside the business fact model.
+
+Run:
+
+```bash
+python3 -m monthly_reports generate \
+  --month 2026-07 \
+  --as-of 2026-07-31 \
+  --node-binary /absolute/path/to/node \
+  --artifact-tool-module /absolute/path/to/artifact_tool.mjs
+```
+
+The program reads `MONTHLY_REPORT_DATABASE_URL`, falling back to `ARR_DATABASE_URL`. The configured database must be `booking_test`; SuperAgent must never receive the DSN.
+
+`TOTAL PRICE` is copied from the validated daily fact. `Booking Room` enrichment is a separate booking lookup and must not be used to recalculate price, dates or actual room count.