docs(discovery): add earnings ledger coverage, fix competition drift

[biwasxyz]

Found while updating #815 (the trading-competition rules reference). Auditing the discovery chain against the code turned up one gap and several statements that had gone wrong.

The gap: earnings ledger is invisible to agents

The earnings ledger (#978) shipped /api/agents/{address}/earnings and /api/stats/earnings, but "earnings" appeared zero times across llms.txt, llms-full.txt, openapi.json, agent.json, and the /docs index. An agent following the discovery chain could not find either endpoint, and nothing explained what the Club tier chips on profiles mean. CLAUDE.md requires discovery docs to be updated alongside endpoints; that did not happen for #978.

The drift: competition statements that mislead

Where	Said	Actually
llms.txt	aibtc.com/leaderboard has Trades / Volume / Unrealized P&L chips, default Trades desc	That page is the earnings board; chips are Earnings / Payers / Latest
llms.txt	P&L is mark-to-current, "both legs re-price on every render"	Scoring runs against a per-round frozen price snapshot
llms.txt, llms-full.txt	catch-up sweep runs every 15 min	Once a day (COMPETITION_INTERVAL_MS, lib/scheduler/cron-runner.ts:72)
llms.txt	no mention of /api/competition/rounds*	Standings live there; an agent stopping at the quick-start cannot find its placement
llms.txt Pages list	/leaderboard is "Ranked agents by level (API: /api/leaderboard)"	Two unrelated systems; CLAUDE.md flags this exact confusion

The cadence one matters most in practice: at a 24h lag, telling agents that self-submitting a txid "just gets you scored sooner" understates it. The docs now say submitting is the reliable path.

Also indexed the competition-finalize topic doc, which existed in TOPICS and in the 404 hint but was missing from /docs.

Changes

• llms.txt — new Earnings section (what counts, what is excluded as self-dealing, pricing, Club tiers); rounds endpoints; corrected ranking, P&L methodology, sweep cadence, and both leaderboard references.
• llms-full.txt — new Earnings Ledger reference section with response shapes, the classification table, anti-gaming rules, and pricing; cadence corrections; disambiguated the directory leaderboard.
• openapi.json — added both earnings paths with full response schemas.
• agent.json — new earnings skill; rounds + cadence in the trading-comp skill; renamed the leaderboard skill to Agent Directory Ranking.
• docs — indexed competition-finalize and the earnings endpoints.

Docs only. No runtime behavior changes.

Verification

• npm run test — 100 files, 1535 passed, 5 skipped
• npm run build — clean
• npm run lint — only pre-existing no-img-element warnings in untouched files
• Response shapes cross-checked against lib/earnings/reads.ts, lib/earnings/types.ts, and both route handlers rather than transcribed from CLAUDE.md

Not included

"leaderboard bonus" originates in lib/levels.ts:58 and propagates to 9 call sites across llms.txt, llms-full.txt, agent.json, skill.md, layout.tsx, and /api/register. No implementation backs it, and an earnings-ranked board cannot be level-bonused. Same class as 634e401 fix(claims): remove Genesis/viral reward promise copy, but it touches API response bodies, so it belongs in its own change.

Refs #978, #822, #815

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	landing-page	e61c90f	Commit Preview URL Branch Preview URL	Jul 29 2026, 08:54 AM

[arc0btc]

Docs-only PR that closes the earnings ledger discovery gap (issue #978's endpoints were live but invisible to agents) and fixes five drifted statements in the competition docs. Verified two of the highest-stakes factual corrections directly against the code before approving:

• lib/scheduler/cron-runner.ts:72 — COMPETITION_INTERVAL_MS = 24 * 60 * 60 * 1000, confirming the sweep really is once-daily, not the 15-min cadence the old docs claimed. This is the correction that matters most operationally — at a 24h lag, "submitting your own txid is the reliable path" is the right guidance, not "just gets you scored sooner."
• lib/earnings/types.ts — SourceClass, ExcludedReason, PriceSource, and the rollup/line-item shapes all match what's documented in llms-full.txt and openapi.json (asset enum sbtc|stx|aeusdc, self_funded/ring/excluded_manual exclusions, tenero/stablecoin/none price sources).

What works well:

• The llms.txt diff clearly disambiguates the two "leaderboard" systems (agent-directory-by-level vs. earnings-by-verified-payment) at every place they were previously conflated — this exact confusion is called out as a known gap in CLAUDE.md, and the fix threads it through agent.json, llms.txt, and llms-full.txt consistently.
• P&L methodology correction (mark-to-current → frozen per-round snapshot) is a real behavioral clarification for any agent trying to reconcile its own math against the leaderboard, not just wording polish.
• Good scope discipline: the PR explicitly separates out the unrelated "leaderboard bonus" dead-copy cleanup into a future change rather than scope-creeping this one.

[nit] openapi.json's new /api/agents/{address}/earnings only documents 200, 404, and 503 responses. Given limit/offset have explicit bounds (1–100, ≥0) in the schema, a 400 for out-of-range values would round out the contract — not blocking since this is a doc mirror of existing route behavior, not a new one.

[question] ExcludedReason in lib/earnings/types.ts includes an "external" variant that doesn't appear in the docs' classification/anti-gaming tables (only self_funded, ring, excluded_manual are documented). Is external currently unused/reserved, or is there a live exclusion path the docs should also cover?

Nothing blocking. Docs-only change, no runtime paths touched, and the two corrections I spot-checked against source both confirm the PR's claims rather than contradicting them.