feat/sites-v2

Ephemeral session path referenced in committed document

docs/development/sites-devices-demo/savings-parity-objective.md

The document references 'this session's tool-results/' — a transient path that exists only during the authoring conversation and will not exist for any reader after the session ends. Committed documentation should only reference stable, repo-resident paths. Either move the referenced artifacts into the repo under a stable path, or remove the reference entirely.

Planning/spec document committed without clear living-document owner

docs/development/sites-devices-demo/savings-parity-objective.md

CLAUDE.md knowledge architecture places implementation specs in skills (Tier 4) or directory CLAUDE.md files (Tier 3). This parity-objective document reads as a planning artifact that may go stale once the feature ships. If meant to be durable reference, distil into .claude/rules/ (site-metrics-seam.md already covers the savings seam) or mark explicitly as a time-boxed working document.

Document location broadly consistent with existing docs/ conventions

docs/development/sites-devices-demo/savings-parity-objective.md

The project uses docs/loops/, docs/ADRs/ (historical), etc. for development-scoped documents. docs/development/sites-devices-demo/ is a reasonable home. No structural violation.

'base' term undefined before use in money identity

docs/development/sites-devices-demo/savings-parity-objective.md

The money identity `net = base − cfe − ppa` uses 'base' without a prior definition. An implementer needs to know: is 'base' the pre-solar bill (what CFE would charge without generation), the contracted demand component, or a tariff floor? Define it immediately beside the identity or in a glossary.

Energy identity uses '≈' with no tolerance or discrepancy source explained

docs/development/sites-devices-demo/savings-parity-objective.md

'consumed ≈ CFE-billed + generated' — the approximation is load-bearing for data-quality decisions. Implementers need to know the expected discrepancy source (losses, meter lag, partial-interval coverage) and what tolerance triggers a quality flag. Without this, two implementers will make different choices.

Track C/U interaction and priority not specified

docs/development/sites-devices-demo/savings-parity-objective.md

Tracks C (calendar) and U (utility-bill) are defined independently but the doc doesn't state: which is authoritative when both are available, what happens on sites with no bill uploaded (pure-C), or whether parity validation runs against C, U, or both. A future implementer wiring the UI toggle will guess.

Energy-bank ledger fields lack units and sign convention

docs/development/sites-devices-demo/savings-parity-objective.md

offset, inflow, redeem, closing are listed without units (kWh assumed but not stated) or sign convention (is 'closing' allowed negative?). The Niko dashboard has concrete semantics — document them so parity is testable, not subjective.

Huentitán reference numbers are unversioned snapshots that will silently go stale

docs/development/sites-devices-demo/savings-parity-objective.md

base/cfe/ppa/net for 2026-07 are embedded inline. When the real bill is re-processed these numbers will be wrong with no indication. Mark clearly as 'as-of Niko legacy run 2026-08-11' or link to a living artifact.

Resolution ceiling note mixes sites and cadences without stating which variable applies

docs/development/sites-devices-demo/savings-parity-objective.md

'1d on most sites, 1h/5m on Panteón, ~1d on Bonfil' — resolution of what? Generation? Consumption? Both? An implementer building the granularity selector needs to know per-variable vs per-site scope. '~1d on Bonfil' should clarify actual cadence (1M monthly-native or truly daily).

'No fabrication' non-negotiable lacks a definition of fabrication in context

docs/development/sites-devices-demo/savings-parity-objective.md

Ambiguous: does it prohibit interpolation across data gaps, using design-expected generation as a fallback, or only synthetic baseline construction? Cross-reference site-metrics-seam.md (which already prohibits interpolation) so implementers find the authoritative source.

Document does not cross-reference SiteMetrics seam type

docs/development/sites-devices-demo/savings-parity-objective.md

The ledger fields and money identities will presumably surface via SiteMetrics or a new savings-layer type. Linking to domains/metrics/src/site-metrics/site-metrics.type.ts and site-metrics-seam.md would let an implementer trace from objective to implementation contract without a separate search.