## Summary Follow-up to: - #3586337+s - #3586348+s Implement the subscription-limit UX decisions from the Emma+Aidan review on #3586337. Persist each context item's estimated token count at save time, base token badges on percentage of the configured token budget, and add budget summary messaging on the agent subscription settings page. This issue implements the indicator behavior. It does not add new warning components beyond text, badges, and tooltips agreed in the design review. ## Problem Token counts on the context item listing are calculated on the fly from item content. That makes listing performance and budget calculations harder to reuse elsewhere, such as agent subscription settings. Current token badges also use fixed absolute tiers (under 1K, 1K–3K, over 3K). Those tiers do not reflect whether an item is a large share of the site's configured token budget. Site builders cannot easily tell from the listing or agent settings whether subscribed context may exceed the budget and therefore may not all be included in a prompt. ## Goal A site builder should be able to see: - How large each context item is relative to the configured token budget. - Approximately how much context an agent has subscribed to. - When subscribed context may exceed the budget, so not all applicable context will be included. ## Proposed solution ### 1. Persist token count on context item save Add a stored token count on `ai_context_item` entities (for example `field_token_count` or equivalent base field). - Calculate the value on save using `AiContextTokenEstimator`. - Include parent content plus applicable subcontext token totals where the listing currently shows a low–high range. - Backfill existing items via update hook or equivalent batch process. The listing and subscription summary should read stored values rather than re-estimating from raw content on every request. ### 2. Base token badges on percentage of `max_tokens` Replace absolute tier thresholds with budget-relative thresholds: - **Gray:** under 10% of `max_tokens` - **Yellow:** 10% through 19.99% - **Red:** 20% or higher Percentage formula: `item tokens ÷ max_tokens × 100` When an item shows a token range because of conditional subcontext, base the badge on the high end of the range. ### 3. Update token badge tooltip on the context item listing Include the percentage in the tooltip, for example: > 400 tokens — 20% of the 2,000-token context budget. When a range is shown, the tooltip should explain the range and use the high-end percentage for the badge state. ### 4. Add budget summary text to agent subscription settings Add summary text at the top of the agent/consumer subscription settings form showing how much context the agent has subscribed to relative to `max_tokens`. Suggested states: **Within budget** > **Context budget:** This agent subscribes to approximately 1,500 of 2,000 > available tokens (75%). The context included in an individual request > depends on which items apply. **Range (conditional subcontext)** > **Context budget:** This agent may use between 800 and 1,600 of 2,000 > available tokens, depending on which context applies to the request. **Over budget** > **Context budget exceeded:** This agent subscribes to as many as 2,500 > tokens, but the context budget is 2,000 tokens (125%). Not all applicable > context may be included in a request. Review this agent's subscriptions > and context conditions, or increase the maximum token budget in General > settings. Link **General settings** to the existing settings route where practical. ## Non-goals This issue does not: - Add new warning banners, modals, or dashboard widgets beyond the agreed text and badge treatment. - Change selection, ranking, or subscription scoring logic. - Change how tokens are estimated beyond persisting the existing estimator result at save time. ## Affected areas Expected areas include: - `ai_context_item` entity definition and save hooks - `AiContextItemListBuilder` token badge rendering - `AiContextTokenEstimator` tier/format helpers - `AiContextAgentForm` (or successor consumer settings form) - Token badge theme/template and CSS - Relevant functional, kernel, and accessibility tests ## Acceptance criteria - [ ] Context items store an estimated token count after save. - [ ] Existing context items receive token counts via update/backfill. - [ ] Context item listing badges use budget-relative gray/yellow/red thresholds based on `max_tokens`. - [ ] Token badge tooltips include the percentage of budget. - [ ] Agent subscription settings show a budget summary at the top of the form. - [ ] Over-budget messaging explains that not all applicable context may be included. - [ ] Conditional subcontext is reflected as a range where applicable. - [ ] Listing and form output remain accessible (tooltip text available to assistive tech; color is not the only indicator). - [ ] Tests cover persistence, tier thresholds, tooltip content, and subscription summary states. - [ ] `./lint.sh` passes. ## Manual test plan 1. Edit and save a context item. Confirm stored token count updates. 2. Open the context item listing with `max_tokens` set to 2,000. 3. Confirm badge colors at approximately 5%, 15%, and 25% of budget. 4. Hover or focus a token badge and confirm tooltip shows count and percentage. 5. Open agent subscription settings for an agent within budget, over budget, and with conditional subcontext range. 6. Confirm summary text matches the three states above. 7. Follow the General settings link from over-budget messaging. 8. Run accessibility checks on the listing and agent settings form. ## Related issues - #3586337+s — subscription-limit indicator design - #3586348+s — help text and documentation for limits and selection ## AI usage - [x] AI assisted issue