docs: add usage reports API documentation

[cassio-paesleme]

Summary

• Adds documentation for the Usage Reports API under Admin > Usage Reports
• Covers the ListReports and GetReportSchema ConnectRPC endpoints
• Includes column definitions for the usage_pulls report type, curl examples, schema versioning notes, data retention, and FAQ

Context

Enterprise customers (starting with Itau) need programmatic access to daily pull usage reports. The API is served by marlin-api and reads pre-computed CSV files from S3.

Related PRs

• docker/data-platform#817 — API implementation
• docker/data-contracts#299 — Proto definition
• docker/airflow#3827 — DAG that generates the reports
• docker/infra-terraform#12603 — IAM access

Notes

• Base URL (marlin-api.docker.com) is a placeholder pending final routing decisions
• Auth examples use a generic $TOKEN; will need to specify Org Access Token flow once that's documented
• The summary-bar shortcode reference may need updating depending on how the feature is gated

🤖 Generated with Claude Code

[netlify]

❌ Deploy Preview for docsdocker failed. Why did it fail? →

Name	Link
🔨 Latest commit	ac7c92c
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a2ab925ddc4e900081eb7b2

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

This PR adds new usage-reports.md documentation. The content is well-organized and technically accurate, but there are two issues that need fixing before merge, plus three style guide violations to clean up.

[docker-agent]

[HIGH] Bold used for non-UI terms in benefit list items

The list uses **Term**: Description format with bold on non-UI terms (Chargeback and cost allocation, Adoption tracking, Security and compliance, Self-service). Per the Docker style guide, bold must only be used for UI elements (buttons, menus, field labels) — never for emphasis or descriptive labels.

Replace with plain bullet text. For example:

- Track pull activity by user, repository, and IP address to attribute usage to internal teams (chargeback and cost allocation).
- Monitor which images and repositories your organization uses most.
- Audit who pulled what, when, and from where.
- Download reports directly through the API without contacting Docker support.

Or restructure as prose.

[docker-agent]

[HIGH] summary-bar shortcode references a feature not defined in data/summary.yaml

The {{< summary-bar feature_name="Usage reports" >}} shortcode requires a matching entry in data/summary.yaml. That entry does not currently exist — searching the file confirms no Usage reports key is present.

Add an entry to data/summary.yaml before merging. For example:

features:
  Usage reports:
    subscription: Business
    availability: GA

Without this, the shortcode will fail to render or display incorrectly on the published page.

[docker-agent]

[MEDIUM] Bold subsection label **Columns:** should be a heading or plain text

The style guide prohibits using **Bold:** format for subsection labels. Use a proper heading level instead:

#### Columns

Or simply remove the label and let the table follow the section prose directly. Bold is reserved for UI elements only.

[docker-agent]

[MEDIUM] Bold subsection labels (**Endpoint:**, **Request:**, **Response:**) should be headings or plain text

The style guide prohibits using bold for subsection labels. This pattern appears throughout the API reference section (lines 79, 82, 108, 133, 142, 153). Replace each with a fourth-level heading:

#### Endpoint

`POST /docker.marlin.query.v1.ReportService/ListReports`

#### Request

Or use plain text without bold. Bold is reserved for UI elements only (buttons, menus, field labels).

[docker-agent]

[MEDIUM] Use "for example" instead of "e.g."

The Docker style guide word list requires for example or such as instead of e.g.

| `reportType` | Yes | Report type (for example, `usage_pulls`) |