docs: document cog_balances() and correct stale CLAUDE.md claims (#25)

Adds the NEWS entry, a Financial data pkgdown reference section (none
existed for cog_spending/cog_revenue), and corrects CLAUDE.md's SQL-layer
claim, view count, test count and fixture-year description against
measured values. Also documents balance_caveats in
inst/schemas/provenance-v1.json (test-first: added a schema-documentation
test to test-balances.R, confirmed it failed, then fixed the schema) and
fleshes out cog_balances()'s @return roxygen to enumerate its conditional
columns, regenerating man/cog_balances.Rd.

man/cog_balances.Rd

@@ -46,8 +46,19 @@ and raw space are identical for holdings. Reported in
 wide era to the modern one.}
 }
 \value{
-A `tbl_df` with a `provenance` attribute. Amounts are full US
-  dollars.
+Tibble with columns `year`, `canonical_govid`, `gov_name`,
+  `balance_subtype`, `category`, `amt_nominal`, optional
+  `amt_per_capita_nominal` and `pop_source` (when `per_capita = TRUE`),
+  optional `amt_real` and `amt_per_capita_real` (when `adjust_to_year` is
+  set), `codes_included`, `aggregate_fallback`, `notes`. Amounts are full
+  US dollars.
+
+  Carries a `provenance` attribute matching
+  `inst/schemas/provenance-v1.json`, whose `balance_caveats` block reports
+  `not_gaap`, `not_gaap_note`, `coverage_window` (measured per-subtype year
+  extents) and `truncated` (subtypes whose coverage falls short of the
+  requested years). `expenditure_concept`/`revenue_concept` are `NA` --
+  holdings are a stock, not a flow, so neither concept vocabulary applies.
 }
 \description{
 Returns Census cash-and-security holdings (`category_type = "balance"`):