Documentation

Corgi Commons is a Bluesky custom feed with inspectable, community-shaped ranking. Corgi ingests candidate posts, computes five global signals, applies the approved policy, and serves an ordered feed for Bluesky clients to render. Corgi exposes policy metadata and ranking receipts when score provenance is available.

This page explains the ranking model. To see it move, use the interactive walkthrough; to inspect the live feed, use the demo.

Each post gets a raw score (0–1) on five signals:

• Recency — how recently the post appeared.
• Engagement — an observed, log-scaled combination of public likes, reposts, and replies; it is not predicted engagement.
• Bridging — Jaccard distance over engager follower sets, estimating whether a post connects otherwise-separate audiences.
• Source diversity — an author-repetition penalty within the ranked batch.
• Relevance — a weighted match between the post’s sparse topic vector and the approved topic-priority map.

A post’s total score is a weighted sum: total = Σ (raw signal score × community weight). The raw signal scores describe the post; the five global signal weights sum to 100%. Change the weights and the same posts reorder — without pretending the posts themselves changed.

The feed is re-scored on a short interval, so new posts and fresh engagement flow in continuously under the active weights.

Topic preferences are separate from the five global signal weights. Posts receive a sparse vector from a curated topic catalog during ingestion. The topic-priority map affects only the relevancesignal; it does not add another top-level scoring term.

Content rules determine eligibility. Adopted include keywords act as an allowlist, adopted excludes take precedence, and a keyword needs at least 30% support among ballots that submit content rules. Publication-time adjustments such as duplicate-link handling can also change final order after component scoring.

An epoch is one saved feed policy. A round can be scheduled or opened manually, and its voting window is configurable. Fewer than 10 ballots use an arithmetic mean; 10 or more use a 10% trimmed mean. Closing the window does not apply policy automatically: results are reviewed, an operator approves or rejects the complete proposal, and approval applies signal weights, topic priorities, and adopted content rules before rescoring. Approved policy versions and governance actions are retained so changes remain inspectable.

When score provenance is available, a Corgi-ranked post can show a receipt with:

• The per-signal breakdown (raw score × weight = contribution), component total, publication adjustment, and final ranking score.
• A counterfactual: where the post would rank under a pure-engagement policy versus the community policy.
• The epoch the score was computed under, and when.

Governance actions and policy changes also appear in the history. Individual ballots are not exposed on public transparency surfaces; only aggregate outcomes are shown.

Corgi is open source. The ranking engine, governance pipeline, and this site live on GitHub. The public read endpoints are documented in the OpenAPI specification.

The read paths are public and unauthenticated — for example the transparency stats, per-post explanations, and governance weights that power the demo. The feed itself is a standard Bluesky feed generator you can subscribe to like any other custom feed.