Metadata Budget Guidance

The User Manual's authoritative metadata table owns the complete field inventory and exact support-asset applicability. This document retains the deeper token-budget decision semantics and examples.

Renma intentionally keeps asset frontmatter small. Frontmatter should work as a deterministic index for cataloging, graph checks, readiness checks, and security diagnostics. It should not become a second copy of the asset body.

Use frontmatter for concise fields such as id, owner, status, tags, when_to_use, when_not_to_use, and declared context relationships. Put detailed guidance, examples, procedures, policy rationale, and long routing prose in the markdown body or in referenced context assets.

Contexts, references, profiles, and examples also support these top-level human-decision fields:

token_budget_override: 6000
token_budget_rationale: "This is a single ordered workflow and splitting it would break execution order."
token_budget_reviewed_at: "2026-07-12"

token_budget_override must be a positive safe integer greater than the asset kind's stable compatibility validation baseline (Context 4,000, Reference 5,000, Profile 2,000, Example 2,500), and token_budget_rationale must be a non-empty string. These baselines validate declaration compatibility; they are not the current repository warning defaults. token_budget_reviewed_at is optional and must be a real YYYY-MM-DD date when present. Invalid metadata does not change repository policy. The three fields form one decision bundle: rationale and review-date fields are invalid without an override. Duplicate fields, relevant YAML errors, and an override declared while the full file remains within its compatibility validation baseline also produce QUAL-INVALID-TOKEN-BUDGET-OVERRIDE. Renma selects no value from an ambiguous or invalid bundle, and catalog output omits all three normalized fields.

These fields record a declared human decision; Renma never inserts them. When the default is exceeded, first ask whether the asset can be split along meaningful semantic boundaries without harming coherence or execution order. Split only after the user agrees. Use an override only when the user confirms the asset should remain intentionally long, and never recommend one merely to make diagnostics pass.

Token-budget counts are deterministic estimates, not exact model-token counts. Exceeded-budget findings report the measured estimate, repository and effective warning/High thresholds, the triggered threshold, severity, absolute overage, and a rounded overage percentage. Repository defaults are Context 6,400/8,000, Reference 7,200/9,000, Profile 3,200/4,000, and Example 4,800/6,000. A result above warning through High is Medium; a result above High is High.

With a valid declared override, Renma keeps the compatibility validation baseline, current Renma default, declared override, repository policy, and final effective thresholds visible. The effective warning threshold is the greater of the repository warning and override; the effective High threshold is the greater of the repository High threshold and effective warning. An active override is an explicit declared floor, not a suppression: an asset above its effective thresholds still produces QUAL-SUPPORT-ASSET-TOKEN-BUDGET. A valid override below the repository warning is a no-op, remains compatible, and never lowers repository policy, while an asset at or below its effective warning threshold does not.

For Markdown assets, the finding also lists at most three of the largest heading-based sections as review candidates. Renma measures each selected section from its heading through the next heading at the same or a shallower depth, ranks by estimated tokens, and breaks ties by source line. Nested headings stay inside their selected parent, so they are not double-counted as independent top candidates. This section review is separate from the canonical support-asset measurement, which remains the full file. A candidate is not an automatic split point or destination assignment. Semantic ownership determines whether reviewed material stays in SKILL.md, moves to Skill-local references/, becomes deterministic implementation in scripts/, supplies output resources in assets/, or belongs in independently owned contexts/. If no useful headings exist, review the asset manually rather than adding or splitting headings by token count alone.

Renma records and validates this declaration; it cannot prove that a human actually reviewed the asset. token_budget_reviewed_at is declared provenance, not independently verified evidence.

Current metadata budget diagnostics:

Finding	Meaning	Typical fix
META-FRONTMATTER-TOO-LARGE	Frontmatter has grown beyond the compact index budget.	Move long prose, examples, procedures, or rationale into the body or referenced context assets.
META-LIST-ITEM-TOO-LONG	A block-list metadata item is too long to serve as concise routing/index metadata.	Keep the list item short and move detailed conditions into body sections.
QUAL-INVALID-TOKEN-BUDGET-OVERRIDE	Support-asset token-budget decision metadata is invalid or ambiguous.	Correct or remove it after an explicit user decision; invalid metadata leaves the repository warning/High policy active.

These diagnostics are intentionally advisory. They should help reduce LLM-facing catalog noise and token usage without deleting substantive knowledge.