Schema: token budgets and context optimization reports

[rajanbor]

Goal

Define library/schemas/token-budget.schema.json for context limits and library/schemas/token-report.schema.json for map optimize --save output.

Human contract

Document budget scope, target/profile, tokenizer assumption, inclusion rules, warning/error thresholds, largest contributors, duplicate detection, and recommended actions. Include a compact report walkthrough.

Machine contract

Use non-negative integer token counts, explicit units/model assumptions, stable reason codes, deterministic file ordering, and versioned report metadata. Keep absolute local paths and document contents out of shareable reports by default.

Acceptance criteria

• Both schemas, one guide, valid examples, and invalid fixtures exist.
• Current token-optimization report has a documented migration path.
• Budget overflow and warning thresholds have unambiguous exit semantics.
• Reports are deterministic and redact machine-specific paths.
• Agent and prompt contracts can reference named budgets.

Depends on the project manifest and canonical document envelope.