---
id: SCR-PFM-LLM-007
title: Rhythm HQ organization AI Usage card
route: '/hq/tenants/{id} (AI Usage card)'
surface: console
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
inference: []
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
purpose: Inspect an organization’s AI account and expose the implemented management placeholders.
supports:
  - JNY-PFM-LLM-002
  - JNY-PFM-LLM-003
  - CAP-PFM-LLM-011
  - CAP-PFM-LLM-013
  - CAP-PFM-LLM-014
  - CAP-PFM-LLM-015
permission: hq.llm-usage.read to see the card; hq.llm-usage.manage for the action menu
entry_from:
  - The hosted navigation or organization page.
  - SCR-PFM-LLM-003 (organizations table)
exits_to:
  - SCR-PFM-LLM-004
  - SCR-PFM-LLM-005
  - SCR-PFM-LLM-006
displays:
  - field: Current monthly capacity and warning or stop explanation
    source: getHqTenantLlmUsage
  - field: Recent period history and per-period breakdowns
    source: listHqTenantLlmUsagePeriods and getHqTenantLlmUsage
  - field: Configured and default limits with ceilings
    source: getHqTenantLlmUsageLimits
  - field: 'Grant history, windows and revocation metadata'
    source: listHqTenantLlmUsageOverrides
  - field: 'Recent task status, request counts and charges'
    source: listHqTenantLlmUsageExecutions
  - field: Problem requests and AI security-audit history
    source: getHqTenantLlmUsage and listHqTenantLlmUsageAudit
  - field: Unavailable agent and protocol activity placeholder
    source: none
actions:
  - label: 'Edit Limits (disabled, not available yet)'
    operation_id: previewHqTenantLlmUsageLimits and putHqTenantLlmUsageLimits (not wired)
    permission: hq.llm-usage.manage
    confirm: true
  - label: 'Grant Override (disabled, not available yet)'
    operation_id: previewHqTenantLlmUsageOverride and grantHqTenantLlmUsageOverride (not wired)
    permission: hq.llm-usage.manage
    confirm: true
  - label: Open request history / a request / a task
    operation_id: 'none: navigation'
    permission: hq.llm-usage.read
    confirm: false
states:
  - 'hidden: staff lack usage-read authority'
  - 'loading: organization sections fetch independently'
  - 'error: the affected section displays failure'
  - 'empty: history sections have no grants, tasks or problems'
  - 'read-only: management writes remain disabled'
validation:
  - BR-CAP-PFM-LLM-011-12
  - BR-CAP-PFM-LLM-013-11
  - BR-CAP-PFM-LLM-014-12
patterns:
  - HQ card on the organization page with sections
  - Action menu (more button) visible only with manage authority
  - Dollars with credits beside
component: 'components/console/hq/tenant-ai-usage-section.tsx, components/console/hq/tenant-ai-usage-card.tsx'
evidence:
  - >-
    react-console at baf6dae: components/console/hq/tenant-ai-usage-section.tsx, tenant-ai-usage-card.tsx,
    tenant-detail.tsx; lib/hq/use-hq-ai-usage.ts, ai-usage.ts, ai-usage-audit.ts, permissions.ts;
    e2e/mock/hq-ai-usage.mock.spec.ts.
controls: [TC-AI-006, TC-AI-007, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Rhythm HQ organization AI Usage card

## What the Screen Is For

The AI Usage card sits within the HQ organization page and combines its monthly position with history, capacity and investigation links.

## What It Shows and Lets People Do

The card presents overview, history, configuration, grants, task activity and problem/audit sections, plus an agent placeholder. Management authority reveals disabled Edit Limits and Grant Override actions. Revocation and charge correction have no menu action, and correction and crossing lists are not rendered despite backend support.

## States and Errors

Usage-read authority controls card visibility. Each section has loading and failure presentation. Support readers see no management menu; managers still cannot save through the disabled controls.

## Patterns It Must Respect

The hosted card follows the organization page’s HQ section pattern. Staff authority controls the action menu, while dollars and credits share monetary display. Future controls need their own concrete save, preview and confirmation behavior.