Validate ids and token counts, add required items, hygiene for 0.2.0

[JeremySNR]

Summary

• Validation: duplicate item ids now throw; tokens and tokenizer output must be finite and >= 0 (negative and NaN values previously corrupted tokensUsed).
• New required?: boolean on Item. A required item or pair group that cannot fit throws with the shortfall instead of silently vanishing.
• README: documents required and every validation error; corrects the tokenizer section (tiktoken does not count Anthropic tokens).
• npm run demo now works: examples/demo.ts added and un-ignored.
• Hygiene: CI workflow, CHANGELOG, package metadata, version 0.2.0.

Test plan

• npm test: 42 passed (24 before)
• npm run build
• npm run demo

Publish this before the three companion packages.

🤖 Generated with Claude Code

---

Note

Medium Risk
Core fit() behavior changes: new throws for bad inputs and required items that do not fit may break callers that relied on silent exclusion or duplicate ids. Required-item semantics are intentional but callers must set priorities correctly.

Overview
0.2.0 tightens fit() input handling and adds required items, plus release hygiene (CI, changelog, demo).

required?: boolean on Item means a required item or pair group throws with item id, shortfall, budget, and reserve when it cannot be included—instead of being silently excluded. Placement still follows priority; the flag only changes the failure mode. Pair groups must agree on required, like priority.

Validation now rejects duplicate ids and invalid token counts on tokens or tokenizer output (negative, NaN, Infinity, non-number), which previously could corrupt tokensUsed / tokensRemaining.

Docs and tooling: README covers required, validation errors, and corrected Anthropic vs tiktoken guidance; examples/demo.ts and npm run demo (tsx); examples/ un-gitignored; GitHub Actions runs test + build on Node 20; package metadata and version bump to 0.2.0.

^{Reviewed by Cursor Bugbot for commit 33b2bfe. Bugbot is set up for automated code reviews on this repo. Configure here.}

[JeremySNR]

Reviewed the full diff locally. Duplicate id and token count validation both throw with clear messages (verified with the original failing inputs). The required flag is placed by priority and only changes the failure mode, which is the right semantics, and pair groups are required to agree on it. Demo now runs. 42 tests pass locally. CI green. Merging.