Ic Leaderboard

You help an agent's human join the IC commits leaderboard at https://www.immersivecommons.com/floor10/commits. The leaderboard counts weekly commits across the linked GitHub account and renders on the FT10 kiosk TV. Three steps: confirm the user can grant the scopes, link their GitHub, opt them in.

AI-assisted onboarding (end-to-end, what to do AND what to say)

This is the whole arc an agent runs on its human's behalf. Each step lists the tool call AND the one thing to communicate to the human — the detailed request/response handling lives in the sections below.

1. Link GitHub. Call ic_leaderboard_connect_github with a PAT the human pastes (discarded after username verification), OR have the human link via the Clerk OAuth browser flow. Both end at the same linked-username state. → Say: "I linked your GitHub as <login>. I only stored your username — the token is discarded and IC never gets write access to your account."

2. Opt in. Call ic_leaderboard_set_optin with optIn: true. Requires a linked GitHub identity (step 1). → Say: "You're opted in. Your row shows up on the next leaderboard refresh (~20 min)."

3. (Optional) Count private work. By default only PUBLIC commits count. To fold in private/restricted contributions, the human enables one GitHub setting — web-only, one click, no API, no deep-link: open their GitHub profile → click "Contribution settings" above the contribution graph → enable "Private contributions". IC reads only the COUNT, never repo names or content. → Say: "If you want your private work counted too, flip one GitHub toggle: profile → 'Contribution settings' above your contribution graph → enable 'Private contributions'. IC only ever sees the number, never your repos. I can't flip it for you — there's no API for it — so it's a quick click on your end."

4. Verify. Call ic_leaderboard_get_status. Confirm optIn: true, the linked github_username, and (if they did step 3) private_counting: "on". → Say: "Confirmed: you're on the board as <username>, rank <rank>" — and if they enabled private: "and your private contributions are now counted (private_counting: on)." If private_counting still reads "off" right after they toggled, tell them the cron just needs a refresh cycle.

Pre-flight (always)

1. Token check. Need FLOOR10_AGENT_TOKEN (or equivalent) with scopes github:link AND leaderboard:manage. If missing either, the user's tier is below ft-member or they minted a narrower token. Either way: stop and tell them.

   Smoke probe:

   curl -H "Authorization: Bearer $FLOOR10_AGENT_TOKEN" \
     https://www.immersivecommons.com/api/leaderboard/me
   

   A 401 means no token. A 403 means wrong scope. A 200 with optIn: false is the starting state for the rest of this flow.

2. GitHub PAT. You'll need a GitHub Personal Access Token from the user. Tell them:

   Make a PAT at https://github.com/settings/tokens — fine-grained is fine, no scopes required (the /user endpoint is open to any valid PAT). Paste it back here. The IC server discards it after verification; only your GitHub username gets stored.

   They paste. You read once into a runtime variable; do not log it, do not echo it back, do not write it to a file.

The pipeline (always this order)

1. Connect GitHub

curl -X POST https://www.immersivecommons.com/api/leaderboard/connect-github \
  -H "Authorization: Bearer $FLOOR10_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"pat\": \"$GITHUB_PAT\"}"

Possible responses:

• 200 { ok: true, github: { login, id, name?, avatarUrl? } } — linked. Tell the user "linked GitHub as <login>."
• 422 — GitHub rejected the PAT. Ask the user to mint a fresh one (their existing PAT may be expired or wrong-scoped). Don't auto-retry.
• 400 — PAT was missing/empty/oversized. Validation issue on our side.
• 403 — your token doesn't have github:link, OR your tier was demoted. Stop.
• 502 — GitHub had a transient. Retry once after 10s; if it fails again, abort and tell the user.
• 500 — Clerk write failed. Tell the user; offer to retry.

If your client speaks MCP, use the tool form instead:

{
  "name": "ic_leaderboard_connect_github",
  "arguments": { "pat": "<value>" }
}

After this call returns, drop the PAT variable. Don't keep it in memory.

2. Opt in

curl -X POST https://www.immersivecommons.com/api/leaderboard/optin \
  -H "Authorization: Bearer $FLOOR10_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"optIn": true}'

Possible responses:

• 200 { ok: true, optIn: true, github_username } — you're on. Next rendered snapshot (weekly cron) will include them.
• 409 { error_kind: "no_github_link" } — opt-in refused because there's no linked GitHub. Step 1 didn't complete OR was never run. Tell the user; go back to step 1.
• 403 — wrong scope or demoted. Stop.

MCP form:

{
  "name": "ic_leaderboard_set_optin",
  "arguments": { "optIn": true }
}

3. Verify status

curl -H "Authorization: Bearer $FLOOR10_AGENT_TOKEN" \
  https://www.immersivecommons.com/api/leaderboard/me

Response shape:

{
  "ok": true,
  "optIn": true,
  "github_username": "vmihalis",
  "github_link_source": "agent_pat",
  "github_verified_at": "2026-05-12T18:30:00.000Z",
  "private_counting": "on",
  "this_week": {
    "count": 47,
    "rank": 3,
    "total": 12,
    "generated_at": "2026-05-12T09:00:00.000Z"
  }
}

private_counting reports whether the member's private-contribution COUNT is being folded into their total: "on" once GitHub's private-contributions toggle is detected on the last cron, otherwise "off". Use it to confirm the toggle landed — if it still reads "off" after the member says they enabled it, the cron hasn't refreshed yet (give it a cycle) or the toggle didn't save on GitHub's side. See Counting private commits below for the exact toggle path.

If this_week is missing, the user is opted in but the refresh cron hasn't run since they joined. Tell them: "you're on; your rank populates at the next refresh (~20 min)." Don't poll tightly — the cron fires about every 20 minutes (running totals for the current Mon–Sun PT week).

MCP form:

{
  "name": "ic_leaderboard_get_status",
  "arguments": {}
}

4. Read the full board (optional)

ic_leaderboard_get_status returns only the caller's own row. To show the whole ranked board (e.g. "who's top 10 this week?") without scraping the /floor10/commits kiosk HTML, use ic_leaderboard_get_board. Read-only, scope membership:read (no extra grant beyond what status already needs).

MCP form:

{
  "name": "ic_leaderboard_get_board",
  "arguments": { "limit": 200 }   // limit optional; default 200, max 200
}

Response shape:

{
  "ok": true,
  "generated_at": "2026-06-30T09:00:00.000Z",
  "week": { "from": "...", "to": "..." },
  "total": 12,
  "stale": false,
  "age_min": 4,
  "members": [
    { "rank": 1, "handle": "vmihalis", "name": "Michalis", "commits": 91, "private": 12 },
    { "rank": 2, "handle": "rayyanzahid", "name": "Rayyan", "commits": 47 }
  ]
}

members is already rank-sorted (rank is 1-based). commits is the ranking total. private is present only for members who enabled GitHub's private- contributions toggle (see below). Honor stale / age_min: if stale is true the snapshot is older than the ~5min refresh window — tell the human the numbers may be behind rather than quoting them as live.

Counting private commits

By default the leaderboard counts only public commit contributions. A member who wants their private/restricted work folded into their total enables one GitHub setting. It is WEB-ONLY — there is NO GitHub API for this toggle, so neither IC nor any agent can flip it; the human has to click it themselves.

Exact path (no deep-link exists — don't try to construct one, walk the human through the clicks):

Open your GitHub profile (github.com/<your-username>) → above the green contribution graph, click "Contribution settings" → enable "Private contributions".

Once enabled, the weekly cron folds that member's private-contribution count into their commits total, and ic_leaderboard_get_board exposes it as the optional private field (a "+N private" badge on the kiosk). The change takes effect at the next refresh, not instantly.

Two ways the private count gets picked up:

• Browser OAuth link — if the member linked GitHub via the Clerk OAuth browser flow, the toggle is honored automatically on the next cron.
• Headless PAT link — if the member linked via ic_leaderboard_connect_github (PAT path), the toggle still works the same way; the toggle is what unlocks the count, independent of how the username was linked.

Guarantee — count, not content. IC only ever reads the number of private contributions. It never reads, stores, or displays private repo names, commit messages, diffs, or any repo content. IC has no write access to anyone's GitHub (a deliberate security boundary). The PAT the member supplies in step 1 is discarded after username verification; the cron's server-side query returns only aggregate counts.

What you DON'T do

• Don't store the PAT. Read it once, send it once, drop the variable.
• Don't log the PAT in any form (no console.log(pat), no console.log(body) if body includes it, no error message that echoes it).
• Don't echo the PAT back to the user — they already have it.
• Don't ask for the PAT before tier-checking. If the user is below ft-member, getting their PAT first is wasted trust. Smoke-probe /api/leaderboard/me first; only ask if you get past the 403 gate.
• Don't auto-opt-out without asking. "Hide me from the leaderboard" should be an explicit user request.
• Don't retry a 422 (PAT rejected) silently. Bad PATs reflect on the user's GitHub account state, not a transient — they need to fix it on GitHub's side.

Edge cases

"I already linked via the Clerk OAuth browser flow." No problem. connect-github is idempotent — re-running it overwrites the publicMetadata field. The OAuth link stays put. /api/leaderboard/me shows github_link_source: "agent_pat" after a successful PAT flow.

"I'm an ic-member but my tier just got demoted to public." The Layer-3 live-tier check will refuse both connect-github and set_optin with 403. Tell the user; point them at /membership to re-request ft-member (or higher).

"My PAT works for me but the cron says 'GITHUB_LEADERBOARD_PAT not configured'." That's a server-side ops problem (Ray hasn't set the env var yet). The link is recorded, but the weekly cron can't fetch your commits. Surface this to the user with the caveat that their rank won't populate until Ray fixes the env.

"My GitHub username changed on GitHub.com." The link stores the old username. Re-run connect-github with a fresh PAT for the renamed account — publicMetadata.github_username overwrites.

"Can I be on the leaderboard with multiple GitHub accounts?" No. The PAT path stores ONE username. If you want to track commits across multiple accounts, link your "main" one and ask Ray about adding a multi-account model (Phase 5+).

Useful reference

• Endpoint base: https://www.immersivecommons.com
• Leaderboard page (human-visible): /floor10/commits
• Cron cadence: every ~20 min (running totals for the current Mon–Sun PT week)
• Required scopes: github:link (write), leaderboard:manage (write + read)
• Tier minimum: ft-member
• Sister skills: floor10-submit (highlights), ic-onboarding (sign-up via device-code), ic-events (Phase 4)