add more documentation

README.md

@@ -10,6 +10,19 @@ vCTP is a vSphere Chargeback Tracking Platform, designed for a specific customer
   - Snapshots/aggregations: `vctp_hourly_snapshots_total`, `vctp_hourly_snapshots_failed_total`, `vctp_hourly_snapshot_last_unix`, `vctp_hourly_snapshot_last_rows`, `vctp_daily_aggregations_total`, `vctp_daily_aggregations_failed_total`, `vctp_daily_aggregation_duration_seconds`, `vctp_monthly_aggregations_total`, `vctp_monthly_aggregations_failed_total`, `vctp_monthly_aggregation_duration_seconds`, `vctp_reports_available`
   - vCenter health/perf: `vctp_vcenter_connect_failures_total{vcenter}`, `vctp_vcenter_snapshot_duration_seconds{vcenter}`, `vctp_vcenter_inventory_size{vcenter}`
 
+## Prorating and Aggregation Logic
+Daily aggregation runs per VM using sample counts for the day:
+- `SamplesPresent`: count of snapshot samples in which the VM appears.
+- `TotalSamples`: count of unique snapshot timestamps for the vCenter in the day.
+- `AvgIsPresent`: `SamplesPresent / TotalSamples` (0 when `TotalSamples` is 0).
+- `AvgVcpuCount`, `AvgRamGB`, `AvgProvisionedDisk` (daily): `AvgIsPresent * last_observed_value` for the VM that day. This prorates partial-day VMs by presence ratio.
+- `PoolTinPct`, `PoolBronzePct`, `PoolSilverPct`, `PoolGoldPct` (daily): `(pool_hits / SamplesPresent) * 100`, so pool percentages reflect only the time the VM existed.
+
+Monthly aggregation builds on daily summaries (or the daily rollup cache):
+- For each VM, daily averages are converted to weighted sums: `daily_avg * daily_total_samples`.
+- Monthly averages are `sum(weighted_sums) / monthly_total_samples` (per vCenter).
+- Pool percentages are weighted the same way: `(daily_pool_pct / 100) * daily_total_samples`, summed, then divided by `monthly_total_samples` and multiplied by 100.
+
 ## RPM Layout (summary)
 The RPM installs the service and defaults under `/usr/bin`, config under `/etc/dtms`, and data under `/var/lib/vctp`:
 - Binary: `/usr/bin/vctp-linux-amd64`
@@ -19,7 +32,7 @@ The RPM installs the service and defaults under `/usr/bin`, config under `/etc/d
 - Data: SQLite DB and reports default to `/var/lib/vctp` (reports under `/var/lib/vctp/reports`)
 - Scripts: preinstall/postinstall handle directory creation and permissions.
 
-## Settings File
+# Settings File
 Configuration now lives in the YAML settings file. By default the service reads
 `/etc/dtms/vctp.yml`, or you can override it with the `-settings` flag.
 
@@ -34,7 +47,7 @@ exit (no scheduler/server), use:
 vctp -settings /path/to/vctp.yml -run-inventory
 ```
 
-### Database Configuration
+## Database Configuration
 By default the app uses SQLite and creates/opens `db.sqlite3`. You can opt into PostgreSQL
 by updating the settings file:
 
@@ -55,13 +68,13 @@ settings:
 PostgreSQL migrations live in `db/migrations_postgres`, while SQLite migrations remain in
 `db/migrations`.
 
-### Snapshot Retention
+## Snapshot Retention
 Hourly and daily snapshot table retention can be configured in the settings file:
 
 - `settings.hourly_snapshot_max_age_days` (default: 60)
 - `settings.daily_snapshot_max_age_months` (default: 12)
 
-### Settings Reference
+## Settings Reference
 All configuration lives under the top-level `settings:` key in `vctp.yml`.
 
 General: