docs: cover --from/--to, avgCostPerSession, and semgrep guard (#99)

README gains a --from/--to example in the Usage block, a dedicated
'Date range filtering' subsection, and a note that JSON projects[]
now includes avgCostPerSession.

CHANGELOG opens an Unreleased section crediting @lfl1337 for PRs #78
and #80. Flags the projects.csv column-order shift (Avg/Session now
between Cost and Share) so consumers parsing by position read by
header instead.

Co-authored-by: AgentSeal <hello@agentseal.org>

Author: AgentSeal

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+### Added
+- **`codeburn report --from/--to`.** Filter sessions to an exact `YYYY-MM-DD` date range (local time). Either flag alone is valid: `--from` alone runs from the given date through end-of-today, `--to` alone runs from the earliest data through the given date. Inverted ranges or malformed dates exit with a clear error. In the TUI, pressing `1`-`5` still switches to the predefined periods. Credit: @lfl1337 (PR #80).
+- **`avgCostPerSession` in reports.** JSON `projects[]` entries gain an `avgCostPerSession` field and `export -f csv` adds an `Avg/Session (USD)` column to `projects.csv`. Column order in `projects.csv` is now `Project, Cost, Avg/Session, Share, API Calls, Sessions` -- scripts parsing by column position should read by header instead. Credit: @lfl1337 (PR #80).
+
+### Security
+- **Semgrep CI guard against prototype pollution regressions.** New `.github/workflows/ci.yml` runs a bracket-assign guard on `src/providers/` and `src/parser.ts` on every push to main and every PR. Blocks re-introducing `$MAP[$KEY] = $MAP[$KEY] ?? $INIT` patterns on `{}`-initialized maps. `categoryBreakdown` in `parser.ts` switched to `Object.create(null)` for consistency with its sibling breakdown maps. Credit: @lfl1337 (PR #78).
+
 ## 0.7.3 - 2026-04-18
 
 ### Changed

README.md

@@ -49,6 +49,7 @@ codeburn today                  # today's usage
 codeburn month                  # this month's usage
 codeburn report -p 30days       # rolling 30-day window
 codeburn report -p all          # every recorded session
+codeburn report --from 2026-04-01 --to 2026-04-10  # exact date range
 codeburn report --format json   # full dashboard data as JSON
 codeburn report --refresh 60    # auto-refresh every 60 seconds
 codeburn status                 # compact one-liner (today + month)
@@ -72,7 +73,7 @@ codeburn month --format json              # this month as JSON
 codeburn report -p 30days --format json   # 30-day window
 ```
 
-The JSON includes all dashboard panels: overview (cost, calls, sessions, cache hit %), daily breakdown, projects, models with token counts, activities with one-shot rates, core tools, MCP servers, and shell commands. Pipe to `jq` for filtering:
+The JSON includes all dashboard panels: overview (cost, calls, sessions, cache hit %), daily breakdown, projects (with `avgCostPerSession`), models with token counts, activities with one-shot rates, core tools, MCP servers, and shell commands. Pipe to `jq` for filtering:
 
 ```bash
 codeburn report --format json | jq '.projects'
@@ -113,6 +114,19 @@ codeburn export --project inventory              # export only "inventory" proje
 
 The `--project` and `--exclude` flags work on all commands and can be combined with `--provider`.
 
+### Date range filtering
+
+Beyond the preset periods, specify an exact window with `--from` and `--to` (`YYYY-MM-DD`, local time):
+
+```bash
+codeburn report --from 2026-04-01 --to 2026-04-10   # explicit window
+codeburn report --from 2026-04-01                    # this date through today
+codeburn report --to 2026-04-10                      # earliest data through this date
+codeburn report --from 2026-04-01 --to 2026-04-10 --format json
+```
+
+Either flag alone is valid. Inverted or malformed dates exit with a clear error. In the TUI, the custom range sets the initial load only -- pressing `1`-`5` switches back to predefined periods.
+
 ### Supported providers
 
 | Provider | Data location | Status |