feat: saving mode — the meter tells the model which tariff it is standing in

[lroolle]

What

Off by default, the meter stays the readout it has always been — no model surface (the repo's own rule, now amended to "empty by default"). Flip savingMode: true in the plugin config and the meter contributes one system-prompt section, meter:tariff, evaluated at every assembly, telling the model which tariff the next request will be dispatched under.

Why this design

• Same clock as the bill. The section's tariff comes from tariffAt(Date.now()) at assembly time — the same function and clock the billing fold uses, so the nudge and the bill cannot disagree about which side of a boundary the next request lands on.
• Cache-safe by construction. The section text is byte-identical inside a tariff window. A countdown would change every minute and roll the session's prompt-prefix cache — the most expensive way to save money a cost plugin can think of. It flips only at the four daily boundaries.
• Silence is free. Outside peak windows the section renders savingOffPeakPrompt, empty by default, and renderPrompt drops empty sections — zero prompt tokens when there is nothing to warn about.
• Nudge, not throttle. Nothing is enforced at the request layer; that stays a different plugin.

Config

Key	Default	Meaning
savingMode	false	Contribute the system-prompt section
savingPeakPrompt	built-in nudge	Text injected inside a peak window (names the peak hours, asks for economical behavior)
savingOffPeakPrompt	''	Text injected off-peak; empty = silence

Tests / docs

• New tests/prompt.spec.mjs — 6 tests: silence when off, built-in nudge inside both peak windows, verbatim custom text, silence off-peak by default, silence under the retired flat tariff, text stability inside a window. 56 tests, CI green locally.
• lib/client.js and docs/index.html regenerated (bundle/site sync checks pass).
• README + README.zh (new "Saving mode" section, config table, Model Experience / KV-cache sections), CHANGELOG 0.3.0, CONTRIBUTING model-surface rule, llms.txt.

Verification

Live composition probe against the real harness SystemPrompt service (off-peak clock): sections harness:identity, deployment:persona, meter:tariff; text "" off-peak; custom savingOffPeakPrompt flows through verbatim.

[lroolle]

Housekeeping sweep, 2026-08-21: this branch is what npm serves as latest,
and it has never been merged.

npm  @dshworks/dsh-meter  latest = 0.3.0   published 2026-08-17T10:27:08Z
main package.json          version = 0.2.4  (0.2.4 published 10:01, 26 min earlier)

Unpacking the 0.3.0 tarball and diffing it against main:

file	difference
lib/core.js	DEFAULT_PEAK_PROMPT + savingPrompt() — absent from main
lib/client.js	same, client copy
lib/index.js	"Three contributions ... the only model-visible contribution"
scripts/build-site.mjs	0.3.0 is older: no GENERATED banner (#8)

So the two diverged in both directions. main still documents the plugin as
"Two contributions, both pull-driven ... nothing model-visible", which is
what the README, the site, and llms.txt all say — while the package a reader
actually installs injects a system-prompt section. That is the one claim about
this plugin that has to be exactly right, because it is the reason it can be
trusted in a session at all.

What is not wrong, checked rather than assumed: RATES is byte-identical
between 0.3.0 and main. Nobody is being mis-billed. 0.3.0 predates the pricing
feed, the self-updating card and the live hero (#4, #6, #8), but those are repo
and site machinery, not the runtime card.

This branch is also 10 commits behind main, so it needs a rebase before it can
merge either way.

Not touching npm from here — republishing is yours to call. The two coherent
endings:

1. Keep saving mode. Rebase onto main, merge this, and cut 0.3.1 from main
   so the tag and the tree agree again.
2. Drop it. npm dist-tag add @dshworks/dsh-meter@0.2.4 latest puts
   latest back on a version that matches the repo, and this PR closes.

Either is fine. latest pointing at an open PR is not.

Worth a guard afterwards either way: publish from CI on a tag, so a version can
only reach npm through main.