# Everything gitdebt can embed in a README

Canonical HTML: https://gitdebt.com/badges

> Star-history charts, a metrics badge, evidence-backed signal badges, repository and maintainer cards, eight repository-health charts, and a social preview. Every asset is a plain public image URL.

Replace `OWNER/REPO` with a lowercased `owner/repo` slug, and `LOGIN` with a GitHub account name. Nothing else needs to change: no account, no token, no build step, no GitHub Action.

## Embedding rules

- No account, token, or API key is involved. Every URL is a plain public image.
- Themes are baked into each asset because GitHub renders README images against the reader's OS preference, not the page. Publish both variants with an HTML `<picture>` element, or pick one explicitly with `theme=light` / `theme=dark`. There is no `theme=auto`.
- Published snippets are static. Motion is opt-in: add `animate=1` to an SVG URL, or use the `.gif` variant where one exists, because GitHub strips SVG animation from README images in several contexts.
- Keep the surrounding link and its `?ref=readme` parameter. Attribution lives on the link; the image URL stays plain so CDNs can cache it.
- Do not add cache-busting query parameters. Media is edge-cached for a few hours by design and refreshes on its own.
- Alt text is not optional. Say what the image shows, not "chart".
- A repository nobody has analyzed yet renders a placeholder frame and queues the work instead of failing. Load the page once, or wait a few minutes, and the real chart replaces it at the same URL.

## Repository assets

### Metrics badge

Stars and forks in one compact chip, served from gitdebt's cache.

Goes in the badge row directly under the project title, alongside CI and license badges.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?metrics=stars,forks&theme=dark" />
    <img alt="OWNER/REPO stars and forks" src="https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?metrics=stars,forks&theme=light" />
  </picture>
</a>
```

### Earned signal badge

One evidence-backed claim — actively maintained, community powered, star momentum, or contributor readiness.

Goes in the badge row, but only for signals the repository has actually earned.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?signal=active&theme=dark" />
    <img alt="OWNER/REPO actively maintained" src="https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?signal=active&theme=light" />
  </picture>
</a>
```

### Star history

The full cumulative star curve, served from Postgres.

Goes in a `## Star history` section near the bottom of the README, above License.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/chart.svg?theme=dark" />
    <img alt="OWNER/REPO star history" src="https://api.gitdebt.com/api/repos/OWNER/REPO/chart.svg?theme=light" />
  </picture>
</a>
```

### Repository card

Stars, forks, contributors, languages, and a 90-day sparkline in one panel.

Goes in an About or Project status section, or a docs-site sidebar.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/card.svg?theme=dark" />
    <img alt="OWNER/REPO repository statistics" src="https://api.gitdebt.com/api/repos/OWNER/REPO/card.svg?theme=light" />
  </picture>
</a>
```

### Stars versus downloads

Star growth against package-registry downloads, for projects that publish one.

Goes in next to the star-history chart, when the project ships a package.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/usage.svg?theme=dark" />
    <img alt="OWNER/REPO stars versus package downloads" src="https://api.gitdebt.com/api/repos/OWNER/REPO/usage.svg?theme=light" />
  </picture>
</a>
```

### Commit calendar

Daily commit density across the last 52 weeks.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/heatmap.svg?theme=dark" />
    <img alt="OWNER/REPO commit activity calendar" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/heatmap.svg?theme=light" />
  </picture>
</a>
```

### Maintenance pulse

Commit volume over time, so a slowdown is visible rather than implied.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/commit-trend.svg?theme=dark" />
    <img alt="OWNER/REPO commit trend" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/commit-trend.svg?theme=light" />
  </picture>
</a>
```

### Contributors

Who is actually landing commits, ranked, with avatars inlined.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/contributors.svg?theme=dark" />
    <img alt="OWNER/REPO contributors" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/contributors.svg?theme=light" />
  </picture>
</a>
```

### Ownership concentration

How few people write half the commits.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/bus-factor.svg?theme=dark" />
    <img alt="OWNER/REPO bus factor" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/bus-factor.svg?theme=light" />
  </picture>
</a>
```

### Language activity

Lines of code by language across the analyzed history.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/lines.svg?theme=dark" />
    <img alt="OWNER/REPO language activity" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/lines.svg?theme=light" />
  </picture>
</a>
```

### File change frequency

The files the most commits touch, dependency manifests excluded.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/top-files.svg?theme=dark" />
    <img alt="OWNER/REPO file change frequency" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/top-files.svg?theme=light" />
  </picture>
</a>
```

### Fix-labelled changes

Files most often touched by commits whose message reads like a fix.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/bug-magnets.svg?theme=dark" />
    <img alt="OWNER/REPO fix-labelled changes" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/bug-magnets.svg?theme=light" />
  </picture>
</a>
```

### TODO/FIXME movement

Whether known debt markers are being added or paid down.

Goes in a Project health or Contributing section, where a prospective contributor is already reading.

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/todo-trend.svg?theme=dark" />
    <img alt="OWNER/REPO recent TODO and FIXME movement" src="https://api.gitdebt.com/api/repos/OWNER/REPO/stats/todo-trend.svg?theme=light" />
  </picture>
</a>
```

### Social preview

A 1200x630 PNG for link unfurls on social platforms and chat apps.

Goes in a docs-site `og:image` meta tag — not the README, where it would be redundant.

```markdown
[![OWNER/REPO on gitdebt](https://api.gitdebt.com/api/repos/OWNER/REPO/og.png)](https://gitdebt.com/OWNER/REPO?ref=readme)
```

## Profile assets

### Maintainer card

Aggregate public-repository totals for the account in one compact panel.

Goes in the top of a profile README, under the introduction.

```html
<a href="https://gitdebt.com/LOGIN?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/users/LOGIN/card.svg?theme=dark" />
    <img alt="LOGIN maintainer statistics" src="https://api.gitdebt.com/api/users/LOGIN/card.svg?theme=light" />
  </picture>
</a>
```

### Aggregate star history

One curve summing star growth across every public repository owned.

Goes in a profile README, below the card.

```html
<a href="https://gitdebt.com/LOGIN?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/users/LOGIN/chart.svg?theme=dark" />
    <img alt="Aggregate star history across LOGIN's public repositories" src="https://api.gitdebt.com/api/users/LOGIN/chart.svg?theme=light" />
  </picture>
</a>
```

### Contribution footprint

Authored work in owned projects versus other people's projects.

Goes in a profile README, in place of a generic contribution-count widget.

```html
<a href="https://gitdebt.com/LOGIN?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/users/LOGIN/stats/contributions.svg?theme=dark" />
    <img alt="LOGIN contribution footprint" src="https://api.gitdebt.com/api/users/LOGIN/stats/contributions.svg?theme=light" />
  </picture>
</a>
```

### Language footprint

Lines of code by language across every analyzed owned repository.

Goes in a profile README, next to the contribution footprint.

```html
<a href="https://gitdebt.com/LOGIN?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/users/LOGIN/stats/languages.svg?theme=dark" />
    <img alt="LOGIN language footprint" src="https://api.gitdebt.com/api/users/LOGIN/stats/languages.svg?theme=light" />
  </picture>
</a>
```

### Commit activity

Every commit landed in the last 52 weeks, summed across owned repos.

Goes in a profile README, as the activity strip.

```html
<a href="https://gitdebt.com/LOGIN?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/users/LOGIN/stats/commit-activity.svg?theme=dark" />
    <img alt="LOGIN commit activity" src="https://api.gitdebt.com/api/users/LOGIN/stats/commit-activity.svg?theme=light" />
  </picture>
</a>
```

### Social preview

A 1200x630 PNG for link unfurls.

Goes in a personal site's `og:image` meta tag.

```markdown
[![LOGIN on gitdebt](https://api.gitdebt.com/api/users/LOGIN/og.png)](https://gitdebt.com/LOGIN?ref=readme)
```

## Multi-repository overlay

One chart, several series, for a comparison table or a docs page.

```markdown
![Star history comparison](https://api.gitdebt.com/api/chart.svg?repos=owner%2Frepo%2Cother%2Frepo&rebase=1&theme=dark)
```

## Query parameters

| Parameter | Applies to | Effect |
| --- | --- | --- |
| `theme=light\|dark` | every SVG and raster asset | Bakes that palette into the output. Default is light. |
| `animate=1` | SVG charts, cards, and badges | Opts into motion. Off by default; use the `.gif` variant where GitHub strips SVG animation. |
| `from=YYYY-MM-DD&to=YYYY-MM-DD` | star-history charts | Inclusive date window. An invalid or inverted range is a 400. |
| `rebase=1` | star-history charts | Starts every series at zero, so projects of different ages compare fairly. |
| `type=date\|timeline` | star-history charts | Calendar dates, or days-since-first-star. |
| `log=1` | star-history charts | Logarithmic y axis. |
| `repos=owner/repo,owner/repo` | /api/chart.svg | Overlays several repositories on one chart. |
| `metrics=stars,forks,downloads` | /badge.svg | Chooses the chips and their order. `downloads` needs a published package. |
| `signal=active\|community\|momentum\|contributor-ready` | /badge.svg | Renders one evidence-backed claim instead of raw metrics. |
| `hide_border=1, hide_title=1, card_width=N` | /card.svg | Trims the card for tight layouts. |

## Ready-made agent prompt

The `/badges` page and every repository report carry an *Ask an agent* button that copies this prompt, filled in for the repository being viewed. The generic form:

````markdown
# Add gitdebt analytics to the project's README

gitdebt (https://gitdebt.com) turns public GitHub data into plain image URLs: star history, a metrics badge, and repository-health charts. No account, token, build step, or GitHub Action is involved — the URLs below are already live and already pointed at this project.

## Step 0 — resolve the repository

Run `git remote get-url origin` and take the `owner/repo` slug from it. Replace every `OWNER/REPO` below with that slug, lowercased. If the remote is not a public GitHub repository, stop and say so: gitdebt only serves public repositories.

## Numbers

Do not write statistics into the README by hand — they go stale. The images below are regenerated from live data. If you need a figure for prose, read it from https://api.gitdebt.com/api/repos/OWNER/REPO/health.json.

## What to add

Paste these snippets as-is. They are complete, and they already carry light and dark variants plus alt text.

### 1. Metrics badge — the badge row directly under the project title, alongside CI and license badges

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?metrics=stars,forks&theme=dark" />
    <img alt="OWNER/REPO stars and forks" src="https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?metrics=stars,forks&theme=light" />
  </picture>
</a>
```

### 2. Star history — a `## Star history` section near the bottom of the README, above License

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/chart.svg?theme=dark" />
    <img alt="OWNER/REPO star history" src="https://api.gitdebt.com/api/repos/OWNER/REPO/chart.svg?theme=light" />
  </picture>
</a>
```

Give it a `## Star history` heading of its own if the README does not already have one.

### 3. Repository card (optional) — an About or Project status section, or a docs-site sidebar

```html
<a href="https://gitdebt.com/OWNER/REPO?ref=readme">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.gitdebt.com/api/repos/OWNER/REPO/card.svg?theme=dark" />
    <img alt="OWNER/REPO repository statistics" src="https://api.gitdebt.com/api/repos/OWNER/REPO/card.svg?theme=light" />
  </picture>
</a>
```

### 4. Repository-health charts (optional)

Each of these is the same `<picture>` shape as above, with a different path. Add at most two, and only where a reader would want them — typically a Project health or Contributing section. More than that reads as clutter and slows the page down.

- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/heatmap.svg` — Commit calendar: Daily commit density across the last 52 weeks.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/commit-trend.svg` — Maintenance pulse: Commit volume over time, so a slowdown is visible rather than implied.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/contributors.svg` — Contributors: Who is actually landing commits, ranked, with avatars inlined.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/bus-factor.svg` — Ownership concentration: How few people write half the commits.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/lines.svg` — Language activity: Lines of code by language across the analyzed history.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/top-files.svg` — File change frequency: The files the most commits touch, dependency manifests excluded.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/bug-magnets.svg` — Fix-labelled changes: Files most often touched by commits whose message reads like a fix.
- `https://api.gitdebt.com/api/repos/OWNER/REPO/stats/todo-trend.svg` — TODO/FIXME movement: Whether known debt markers are being added or paid down.

### 5. Earned signal badge (optional)

Fetch `https://api.gitdebt.com/api/repos/OWNER/REPO/earned-badges.json` first. It returns one entry per signal with an `earned` boolean. Publish only the signals where `earned` is `true` — an unearned signal renders greyed out and claims nothing.

Badge URL shape: `https://api.gitdebt.com/api/repos/OWNER/REPO/badge.svg?signal=SIGNAL&theme=dark`, where `SIGNAL` is `active`, `community`, `momentum`, or `contributor-ready`.

## Rules

- No account, token, or API key is involved. Every URL is a plain public image.
- Themes are baked into each asset because GitHub renders README images against the reader's OS preference, not the page. Publish both variants with an HTML `<picture>` element, or pick one explicitly with `theme=light` / `theme=dark`. There is no `theme=auto`.
- Published snippets are static. Motion is opt-in: add `animate=1` to an SVG URL, or use the `.gif` variant where one exists, because GitHub strips SVG animation from README images in several contexts.
- Keep the surrounding link and its `?ref=readme` parameter. Attribution lives on the link; the image URL stays plain so CDNs can cache it.
- Do not add cache-busting query parameters. Media is edge-cached for a few hours by design and refreshes on its own.
- Alt text is not optional. Say what the image shows, not "chart".
- A repository nobody has analyzed yet renders a placeholder frame and queues the work instead of failing. Load the page once, or wait a few minutes, and the real chart replaces it at the same URL.

## If the project already shows a star-history chart

Replace it in place. Keep the surrounding heading and prose; swap only the image and the link it wraps. Do not stack a second chart underneath. Search the repository for these markers:

- `star-history.com`
- `api.star-history.com`
- `starchart.cc`
- `stars.medv.io`
- `seladb/starhistory`

## Where else to look

- README.md at the repository root
- docs/index.md, docs/README.md, or a docs-site landing page
- website/ or site/ landing content, if the project publishes one
- CONTRIBUTING.md, where repository-health charts tell a contributor what they are joining
- .github/profile/README.md for an organization profile

Only touch a file where the addition genuinely belongs. An unrelated docs page does not need a commit calendar.

## Tuning

Query parameters, if the defaults do not fit:

- `theme=light|dark` (every SVG and raster asset) — Bakes that palette into the output. Default is light.
- `animate=1` (SVG charts, cards, and badges) — Opts into motion. Off by default; use the `.gif` variant where GitHub strips SVG animation.
- `from=YYYY-MM-DD&to=YYYY-MM-DD` (star-history charts) — Inclusive date window. An invalid or inverted range is a 400.
- `rebase=1` (star-history charts) — Starts every series at zero, so projects of different ages compare fairly.
- `type=date|timeline` (star-history charts) — Calendar dates, or days-since-first-star.
- `log=1` (star-history charts) — Logarithmic y axis.
- `repos=owner/repo,owner/repo` (/api/chart.svg) — Overlays several repositories on one chart.
- `metrics=stars,forks,downloads` (/badge.svg) — Chooses the chips and their order. `downloads` needs a published package.
- `signal=active|community|momentum|contributor-ready` (/badge.svg) — Renders one evidence-backed claim instead of raw metrics.
- `hide_border=1, hide_title=1, card_width=N` (/card.svg) — Trims the card for tight layouts.

## Finish

1. Request each URL you added and confirm it answers 200 with an image content type.
2. Confirm every image is wrapped in the link with `?ref=readme` and carries alt text.
3. Confirm you changed nothing else: no reformatting, no reflowed prose, no reordered badges beyond the one you inserted.
4. Report what you added and where, and link the full report: https://gitdebt.com/OWNER/REPO
````