- A community-governed Bluesky feed where subscribers vote on the ranking algorithm.
+ Community-shaped Bluesky ranking with inspectable policy and receipts.
- Corgi is a community-governed feed for Bluesky. Members vote on how much each ranking signal
- matters, the feed reranks accordingly, and every post carries a receipt showing exactly why it landed where it
- did. Bluesky renders the ordered posts; Corgi shows the math.
+ Corgi is a community-shaped feed for Bluesky. During the limited pilot, approved participants
+ can vote on ranking signals, topic priorities, and content rules. Approved policy changes are applied before
+ the feed is rescored. Bluesky renders the ordered posts; Corgi shows the policy and available ranking receipts.
),
@@ -53,10 +53,12 @@ const SECTIONS = [
<>
The governance loop is deliberately simple and auditable:
-
Propose & vote — during an open round, members set weights for five signals: recency, engagement, bridging, source diversity, and topic relevance.
-
Aggregate — votes are combined with a trimmed mean (outliers on each end are dropped) so no single voter can swing the feed.
-
Apply — when the round closes, the aggregated weights become the next epoch, and the live feed reranks.
-
Record — every weight change and operator action is written to an append-only audit log that anyone can inspect.
+
Open a round — a vote can be scheduled or opened manually, with a configurable response window.
+
Vote — approved participants can submit five global signal weights, topic priorities that shape relevance, and include or exclude content rules.
+
Aggregate — fewer than 10 ballots use an arithmetic mean; 10 or more use a 10% trimmed mean. Content rules require at least 30% support among content-rule ballots.
+
Review & approve — closed-round results are reviewed before an operator approves or rejects the complete proposed policy.
+
Apply & rescore — approval applies signals, topics, and adopted rules together to the active epoch, returns it to running, and queues a durable feed rescore.
+
Record — policy changes and operator actions are written to the governance audit trail.
You can watch this happen on the how-it-works page, or inspect the
@@ -71,7 +73,7 @@ const SECTIONS = [
body: (
<>
-
Inspectable by default — the ranking weights, the per-post score breakdowns, and the audit log are always public.
+
Inspectable by default — active ranking policy, available per-post score breakdowns, and governance history are exposed on Corgi.
Your vote is private, the outcome is public — individual votes are never exposed; only the aggregated result is.
Open source — the implementation is public so the community can verify, fork, and improve it.
No dark patterns — no ads, no engagement bait, no selling data.
@@ -89,8 +91,8 @@ const SECTIONS = [
We never receive your main password, and you can revoke access at any time from your Bluesky settings.
- We collect only what’s needed to run governance: your Bluesky handle/DID, your vote preferences, and your
- research-consent status. Full details are in the{" "}
+ Governance access is currently an approved waitlist pilot. For participants, we collect only what is needed to
+ operate the pilot: your Bluesky handle/DID, ballot preferences, and research-consent status. Full details are in the{" "}
Privacy Policy.
- Five signals decide the feed order. This is the mix the community’s votes have settled on.
+ Five global signals contribute to the ranking score. This is the active, approved production mix.
@@ -209,7 +209,7 @@ export default function DashboardPage() {
Get involved
- The weights are set entirely by community votes. Cast or change yours before the round closes.
+ During the approved pilot, your ballot contributes to a proposed policy. Closed results are reviewed before any production change is applied.
@@ -261,7 +261,7 @@ export default function DashboardPage() {
-
members voted · each vote counts equally
+
ballots submitted · mean below 10, 10% trim at 10+
)}
{participation != null && }
diff --git a/web-next/app/demo/__tests__/demo-copy.test.ts b/web-next/app/demo/__tests__/demo-copy.test.ts
index 8cfa3375..c525a8e6 100644
--- a/web-next/app/demo/__tests__/demo-copy.test.ts
+++ b/web-next/app/demo/__tests__/demo-copy.test.ts
@@ -54,7 +54,7 @@ describe("demo copy — honest boundaries", () => {
it("keeps pre-session copy accurate when the corpus falls back", () => {
expect(HERO.subtitle).not.toMatch(/live public posts/i)
expect(STEP_PANELS.community.body).not.toMatch(/live public posts/i)
- expect(DISCLOSURE.posts).toMatch(/snapshot of posts published in corgi's live community governed feed/i)
+ expect(DISCLOSURE.posts).toMatch(/snapshot of live public posts published in corgi commons/i)
expect(DISCLOSURE.posts).toMatch(/mechanics fixture appears only if snapshot loading degrades/i)
})
diff --git a/web-next/app/demo/__tests__/frontend-release-blockers.test.tsx b/web-next/app/demo/__tests__/frontend-release-blockers.test.tsx
index ec9322c7..b2712466 100644
--- a/web-next/app/demo/__tests__/frontend-release-blockers.test.tsx
+++ b/web-next/app/demo/__tests__/frontend-release-blockers.test.tsx
@@ -120,7 +120,7 @@ describe("demo v4 frontend release blockers", () => {
it("keeps the fixture live-proof panel separate and omits the fixture timestamp", () => {
const presentation = getLiveProofPresentation(snapshotProvenance, true)
- expect(presentation.feedName).toBe("Contract-backed feed name")
+ expect(presentation.feedName).toBe("Corgi Commons")
expect(presentation.sourceTimestamp).toBeNull()
expect(presentation.description).toContain("mechanics fixture")
expect(COMMUNITY_GOV_FEED_URL).toBe("https://bsky.app/profile/corgi-network.bsky.social/feed/community-gov")
@@ -131,7 +131,7 @@ describe("demo v4 frontend release blockers", () => {
const presentation = getLiveProofPresentation(snapshotProvenance, false)
expect(presentation.eyebrow).toBe("Snapshot source live on Bluesky")
- expect(presentation.feedName).toBe("Contract-backed feed name")
+ expect(presentation.feedName).toBe("Corgi Commons")
expect(presentation.description).toMatch(/published-feed comparison corpus/i)
expect(presentation.sourceTimestamp).toMatch(/Jul 11, 2026.*UTC/i)
expect(presentation.description).not.toMatch(/reviewed snapshot/i)
diff --git a/web-next/app/demo/__tests__/http-client.test.ts b/web-next/app/demo/__tests__/http-client.test.ts
index ea8471c9..c9d200eb 100644
--- a/web-next/app/demo/__tests__/http-client.test.ts
+++ b/web-next/app/demo/__tests__/http-client.test.ts
@@ -291,7 +291,7 @@ describe("HTTP shadow demo client", () => {
new AbortController().signal,
)
- expect(response.payload.community.name).toBe("Community Governed Feed")
+ expect(response.payload.community.name).toBe("Corgi Commons")
expect(response.payload.community.publicBlueskyFeedUrl).toContain("community-gov")
expect(response.payload.session.capabilities.canOpenNativeBlueskyFeed).toBe(true)
expect(response.payload.session.capabilities.canAdvanceEpoch).toBe(false)
@@ -310,6 +310,70 @@ describe("HTTP shadow demo client", () => {
expect(fetchMock).toHaveBeenCalledTimes(2)
})
+ it("rejects malformed community, provenance, topic, and session identity fields", () => {
+ const invalidPayloads: unknown[] = []
+ const emptyCommunity = structuredClone(sessionPayload("created", "epoch-1", [epoch("epoch-1", 1, BASE_WEIGHTS, 0)])) as {
+ session: { community: Record }
+ }
+ emptyCommunity.session.community.name = ""
+ invalidPayloads.push(emptyCommunity)
+
+ const nullCommunity = structuredClone(sessionPayload("created", "epoch-1", [epoch("epoch-1", 1, BASE_WEIGHTS, 0)])) as {
+ session: { community: Record }
+ }
+ nullCommunity.session.community.id = null
+ invalidPayloads.push(nullCommunity)
+
+ const missingProvenance = structuredClone(sessionPayload("created", "epoch-1", [epoch("epoch-1", 1, BASE_WEIGHTS, 0)])) as {
+ session: Record
+ }
+ delete missingProvenance.session.corpusProvenance
+ invalidPayloads.push(missingProvenance)
+
+ const staleShapeProvenance = structuredClone(sessionPayload("created", "epoch-1", [epoch("epoch-1", 1, BASE_WEIGHTS, 0)])) as {
+ session: { corpusProvenance: Record }
+ }
+ staleShapeProvenance.session.corpusProvenance.sourceUpdatedAt = "not-a-timestamp"
+ invalidPayloads.push(staleShapeProvenance)
+
+ const duplicateTopics = structuredClone(sessionPayload("created", "epoch-1", [epoch("epoch-1", 1, BASE_WEIGHTS, 0)])) as {
+ session: { topicCatalog: Array> }
+ }
+ duplicateTopics.session.topicCatalog[1].slug = duplicateTopics.session.topicCatalog[0].slug
+ invalidPayloads.push(duplicateTopics)
+
+ const nullEpoch = structuredClone(sessionPayload("created", "epoch-1", [epoch("epoch-1", 1, BASE_WEIGHTS, 0)])) as {
+ session: Record
+ }
+ nullEpoch.session.currentEpochId = null
+ invalidPayloads.push(nullEpoch)
+
+ for (const payload of invalidPayloads) {
+ expect(apiSessionPayloadSchema.safeParse(payload).success).toBe(false)
+ }
+ })
+
+ it("preserves a structured non-2xx conflict message without retrying the mutation", async () => {
+ const fetchMock = vi.fn(async () => new Response(JSON.stringify({
+ error: "StaleEpoch",
+ message: "The shadow epoch changed before this ballot was accepted.",
+ }), { status: 409, headers: { "content-type": "application/json" } }))
+ vi.stubGlobal("fetch", fetchMock)
+
+ await expect(createHttpShadowDemoClient().castVote(
+ SESSION_ID,
+ {
+ idempotencyKey: "stale-vote",
+ baseEpochId: "epoch-1",
+ voterLabel: "Reviewer",
+ weights: BASE_WEIGHTS,
+ topicIntent: PRODUCTION_TOPIC_INTENT,
+ },
+ new AbortController().signal,
+ )).rejects.toThrow("The shadow epoch changed before this ballot was accepted.")
+ expect(fetchMock).toHaveBeenCalledTimes(1)
+ })
+
it("maps withheld posts with their adopted rule and support", async () => {
const feed = feedPayload("epoch-2", [1, 2]) as { posts: Array> } & Record
const withheldPost = { ...(feed.posts[0].post as Record), uri: "at://did:plc:test/app.bsky.feed.post/withheld" }
@@ -664,7 +728,7 @@ function sessionPayload(
sessionId: SESSION_ID,
community: {
id: "community_gov",
- name: "Community Governed Feed",
+ name: "Corgi Commons",
status: "live_shadow",
description: "Research, data, software, and open-source methods.",
liveFeedReady: true,
@@ -751,7 +815,7 @@ function corpusProvenance(): Record {
topicScoreThreshold: 0.5,
eligiblePostCount: 80,
sourceFeedUri: "at://did:plc:amzyknmm4auxijvykyfgznw2/app.bsky.feed.generator/community-gov",
- sourceFeedName: "Community Governed Feed",
+ sourceFeedName: "Corgi Commons",
sourceSnapshotDigest: "7".repeat(64),
sourceRunId: "run-community-gov",
sourceUpdatedAt: NOW,
diff --git a/web-next/app/demo/layout.tsx b/web-next/app/demo/layout.tsx
index f20992f6..81bd1d16 100644
--- a/web-next/app/demo/layout.tsx
+++ b/web-next/app/demo/layout.tsx
@@ -1,9 +1,9 @@
import type { Metadata } from "next"
export const metadata: Metadata = {
- title: "Live demo — re-rank a Community Governed Feed snapshot | Corgi",
+ title: "Governance demo — re-rank a Corgi Commons snapshot | Corgi",
description:
- "Propose a ranking policy, combine it with 24 scripted ballots, and watch a frozen snapshot of Corgi's live Bluesky feed reorder — every move explained by a receipt.",
+ "Propose a ranking policy, combine it with 24 scripted deterministic voter archetypes, and inspect how a frozen Corgi Commons comparison corpus reorders.",
alternates: { canonical: "/demo/" },
}
diff --git a/web-next/app/demo/page.tsx b/web-next/app/demo/page.tsx
index c994b10b..b9985ccc 100644
--- a/web-next/app/demo/page.tsx
+++ b/web-next/app/demo/page.tsx
@@ -466,7 +466,7 @@ export default function DemoPage() {
) : null}
- {busy ? "Updating the shadow demo." : session === null ? "Start a Community Governed Feed demo session." : `Demo phase: ${phase}.`}
+ {busy ? "Updating the shadow demo." : session === null ? "Start a Corgi Commons demo session." : `Demo phase: ${phase}.`}
{receiptAnnouncement}
@@ -519,7 +519,7 @@ export default function DemoPage() {
-
{community.name}
+
Corgi Commons
{corpusPresentation?.provenanceLine}
@@ -537,7 +537,7 @@ export default function DemoPage() {
) : null}
new Set(catalog.map((topic) => topic.slug)).size === 26,
- { message: "Community Governed Feed topic catalog must contain 26 unique active topics." },
+ { message: "Corgi Commons topic catalog must contain 26 unique active topics." },
),
sourceFeedUri: z.string().startsWith("at://"),
voterProfiles: z.array(voterProfileSchema),
diff --git a/web-next/app/demo/shadow-demo-copy.ts b/web-next/app/demo/shadow-demo-copy.ts
index 88defefc..68d69db1 100644
--- a/web-next/app/demo/shadow-demo-copy.ts
+++ b/web-next/app/demo/shadow-demo-copy.ts
@@ -7,9 +7,9 @@
export const HERO = {
eyebrow: "Interactive demo",
- title: "Re-rank a frozen Community Governed Feed snapshot.",
+ title: "Re-rank a frozen Corgi Commons snapshot.",
subtitle:
- "Start with a reviewer-safe published snapshot, propose a policy, combine it with 24 scripted ballots, and inspect how the same posts move.",
+ "Start with a reviewer-safe snapshot of the public feed, propose a policy, combine it with 24 scripted deterministic voter archetypes, and inspect how the same posts move.",
} as const
export interface FlowStepCopy {
@@ -22,15 +22,15 @@ export const FLOW_STEPS: readonly FlowStepCopy[] = [
{ key: "session", label: "Session", hint: "Freeze a comparison corpus" },
{ key: "vote", label: "Your vote", hint: "Pick a policy" },
{ key: "agents", label: "Community", hint: "24 voters weigh in" },
- { key: "epoch", label: "Advance epoch", hint: "Apply the policy" },
+ { key: "epoch", label: "Advance epoch", hint: "Publish the shadow policy" },
{ key: "reorder", label: "Reordered", hint: "Same posts, new order" },
{ key: "receipt", label: "Receipt", hint: "Why it ranked" },
]
export const STEP_PANELS = {
community: {
- heading: "Start from the published feed",
- body: "Corgi freezes an objectively filtered snapshot of its live Community Governed Feed. Your shadow session can change the ranking policy without changing the public feed.",
+ heading: "Start from Corgi Commons",
+ body: "Corgi Commons serves open-network building, research, software, data, and the conversations connecting them. This demo freezes a reviewer-safe comparison corpus from the public feed so your shadow session can change the ranking policy without changing what anyone sees on Bluesky.",
cta: "Start a demo session",
},
vote: {
@@ -40,14 +40,14 @@ export const STEP_PANELS = {
},
agents: {
heading: "Let the community weigh in",
- body: "Twenty-four scripted deterministic voter archetypes represent five stakeholder blocs. Their preferences carry history, respond within bounds to your proposal, and replay exactly from the same inputs.",
+ body: "Twenty-four scripted deterministic voter archetypes represent five preference blocs. Their preferences carry history, respond within bounds to your proposal, and replay exactly from the same inputs. They demonstrate governance mechanics; they are not validated models of human behavior.",
readyHeading: "Twenty-four community voters are ready",
readyBody: "Five scripted blocs balance stable preferences, prior-policy inertia, and a bounded response to your proposal. The run is deterministic and replayable.",
cta: "Simulate 24 voters",
},
epoch: {
- heading: "Advance the epoch",
- body: "Close voting and apply the community-aggregated policy to the frozen corpus.",
+ heading: "Advance the shadow epoch",
+ body: "Close this demo round and publish the aggregated policy inside the isolated shadow session. Production rounds require results review and operator approval before application.",
cta: "Advance epoch",
},
reorder: {
@@ -57,7 +57,7 @@ export const STEP_PANELS = {
},
receipt: {
heading: "Why it ranked here",
- body: "Every position has a receipt: raw signal scores times the community's weights, plus counterfactuals.",
+ body: "Inspect the selected post's raw signal scores, community weights, publication adjustment, provenance, and counterfactuals.",
cta: "Pick another post",
},
} as const
@@ -67,7 +67,7 @@ export const DISCLOSURE = {
production:
"Demo votes and epochs run in an isolated shadow governance namespace. They never enter production governance, audit logs, research exports, or the public Corgi feed.",
posts:
- "The primary path uses an objectively filtered snapshot of posts published in Corgi's live Community Governed Feed. The comparison corpus is frozen for the session so policy changes remain attributable. A labeled mechanics fixture appears only if snapshot loading degrades.",
+ "The primary path uses an objectively filtered snapshot of live public posts published in Corgi Commons. The comparison corpus is frozen for the session so policy changes remain attributable. A labeled mechanics fixture appears only if snapshot loading degrades.",
// Keeps the Bluesky-vs-Corgi boundary honest without claiming native rendering.
annotations:
"Rank badges, scores, and receipts are Corgi annotations shown on Corgi's site, not native Bluesky UI. Bluesky renders the ordered posts; Corgi shows why.",
@@ -75,7 +75,7 @@ export const DISCLOSURE = {
export const LABELS = {
previewBadge: "Coming soon",
- corpusFrozen: "Published feed snapshot · frozen comparison corpus",
+ corpusFrozen: "Corgi Commons snapshot · frozen comparison corpus",
corpusFallback: "Mechanics fixture · frozen comparison corpus",
reset: "Start over",
reviewerVoter: "You (reviewer)",
diff --git a/web-next/app/demo/shadow-demo-fixtures.ts b/web-next/app/demo/shadow-demo-fixtures.ts
index 15df8f14..08b46b97 100644
--- a/web-next/app/demo/shadow-demo-fixtures.ts
+++ b/web-next/app/demo/shadow-demo-fixtures.ts
@@ -241,7 +241,7 @@ export const DEMO_COMMUNITIES: Readonly
- Corgi is a community-governed custom feed for Bluesky. It ingests candidate posts, scores each one against five
- signals, applies the community’s current weights, and serves the ordered result back to Bluesky. Every
- post keeps a receipt so the order is fully inspectable.
+ 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{" "}
@@ -36,10 +36,10 @@ const SECTIONS = [
Each post gets a raw score (0–1) on five signals:
Recency — how recently the post appeared.
-
Engagement — replies, reposts, and likes relative to the author’s reach.
-
Bridging — how well the post connects otherwise-separate subgroups in the community.
-
Source diversity — whether the feed is hearing from a wider set of authors and sources.
-
Relevance — how well the post matches the community’s topics.
+
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.
),
@@ -51,7 +51,7 @@ const SECTIONS = [
<>
A post’s total score is a weighted sum: total = Σ (raw signal score × community weight).
- The raw signal scores describe the post; the weights are set by the community and always sum to 100%. Change
+ 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.
+ 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 relevance
+ signal; 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 full set of weights from a governance round. During an
- open round, members vote on the weights. When the round closes, votes are combined with a{" "}
- trimmed mean (a fixed share of outliers on each end is dropped) and the result becomes the
- next epoch. Every epoch is retained, so you can always see how policy changed over time.
+ 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) and the total.
+
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.
- Operator actions and weight changes are also written to an append-only audit
- log. Individual votes are never exposed — only aggregated outcomes.
+ Governance actions and policy changes also appear in the history.
+ Individual ballots are not exposed on public transparency surfaces; only aggregate outcomes are shown.
- Every weight change, keyword rule, and governance event — in full, forever. Select a round to inspect it.
+ Inspect recorded signal, topic, content-rule, and operator changes by policy round.
Corgi is in its pilot phase: the early rounds below were run with a small group of voters to
diff --git a/web-next/app/how-it-works/page.tsx b/web-next/app/how-it-works/page.tsx
index 5417e13d..a37480d3 100644
--- a/web-next/app/how-it-works/page.tsx
+++ b/web-next/app/how-it-works/page.tsx
@@ -2,7 +2,6 @@ import type { Metadata } from "next"
import { Header } from "@/components/header"
import { FooterSection } from "@/components/footer-section"
import { HowItWorksReplay } from "@/components/how-it-works-replay"
-import { ModalityPreview } from "@/components/modality-preview"
import { DemoCTA, WaitlistCTA } from "@/components/landing-ctas"
import { Container, Section } from "@/components/ui/layout"
import { PageHero, HeroGlow, HERO_TOP } from "@/components/ui/page-hero"
@@ -32,6 +31,21 @@ const surfaceBoundaries = [
},
] as const
+const rankingJourney = [
+ { label: "Candidate posts", body: "Corgi ingests public Bluesky posts and computes reusable post signals." },
+ { label: "Ballot", body: "Approved participants can vote on signals, topic priorities, and content rules." },
+ { label: "Aggregation", body: "Corgi aggregates complete ballots after the configurable voting window closes." },
+ { label: "Review and approval", body: "Results are reviewed before an operator approves or rejects the proposed policy." },
+ { label: "Render in Bluesky", body: "After approval and rescoring, Corgi serves the ordered feed for Bluesky clients to render." },
+ { label: "Inspect in Corgi", body: "Corgi shows the policy, score components, publication adjustments, and receipts." },
+] as const
+
+const communityExamples = [
+ "Neighborhood mutual aid can prioritize urgent, well-sourced local updates.",
+ "Open-source maintainers can lift patches, docs, and release notes over generic project chatter.",
+ "Tabletop creators can favor indie releases, safety tools, and useful play resources.",
+] as const
+
export default function HowItWorksPage() {
return (
@@ -49,12 +63,27 @@ export default function HowItWorksPage() {
align="left"
eyebrow="Replay a policy change"
title="Watch the same posts become a different feed."
- subtitle="Corgi scores candidate posts once, then applies the active community policy. Change the epoch and the feed order changes with it."
+ subtitle="Follow a post from candidate set to community ballot, approved policy, Bluesky feed, and inspectable Corgi receipt."
/>
+
+
+ {rankingJourney.map((step, index) => (
+
+
{String(index + 1).padStart(2, "0")}
+
{step.label}
+
{step.body}
+
+ ))}
+
+
+
@@ -69,12 +98,6 @@ export default function HowItWorksPage() {
This separation is intentional: people get a normal Bluesky feed, and the explanation layer stays inspectable on Corgi.
-
-
-
-
-
-
{surfaceBoundaries.map((boundary) => (
+
+
+
+
Any community
+
+ The mechanism is general. The policy is local.
+
+
+
+ {communityExamples.map((example) => (
+
{example}
+ ))}
+
+
+
+
@@ -101,7 +140,7 @@ export default function HowItWorksPage() {
Inspect the live receipt path.
- The walkthrough above is illustrative. The public demo is where live ranking claims use Corgi receipts and snapshot data.
+ The walkthrough above is illustrative. The public demo starts from a frozen comparison corpus sourced from Corgi Commons and keeps every shadow vote isolated from production.
@@ -110,7 +149,7 @@ export default function HowItWorksPage() {
- Demo posts are illustrative; live ranking claims use Corgi receipts and snapshot data.
+ Demo posts on this page are illustrative. The reviewer demo identifies its frozen live-public snapshot and links back to source posts.
diff --git a/web-next/app/not-found.tsx b/web-next/app/not-found.tsx
index 07a40084..4d815421 100644
--- a/web-next/app/not-found.tsx
+++ b/web-next/app/not-found.tsx
@@ -27,7 +27,7 @@ export default function NotFound() {
href="/demo"
className="rounded-full px-5 py-3 text-base font-medium text-foreground/70 hover:text-foreground transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-background"
>
- Explore the live demo →
+ Try the governance demo →
diff --git a/web-next/app/page.tsx b/web-next/app/page.tsx
index 7d85632b..ef6061ee 100644
--- a/web-next/app/page.tsx
+++ b/web-next/app/page.tsx
@@ -1,6 +1,5 @@
"use client"
-import Link from "next/link"
import { Header } from "@/components/header"
import { HeroSection } from "@/components/hero-section"
import { ReplayTeaser } from "@/components/replay-teaser"
@@ -28,20 +27,18 @@ export default function LandingPage() {
-
- Interactive preview
+
+ Corgi Commons preview
- See a community reshape its own feed.
+ One feed. A policy the community can inspect.
- Meet Birders Who Code, a sample community of
- developers who bird. Choose how they rank posts and watch this illustrative preview reorder here, with
- the Corgi score behind every move. Then use the{" "}
-
- live shadow demo
- {" "}
- to verify the full flow.
+ Corgi Commons brings together open-network building, research, software, data, and the conversations
+ connecting them. Change the illustrative policy below to see how the same posts reorder.
+
+
+ Bluesky shows the ordered posts. Corgi shows the policy and receipts.
diff --git a/web-next/app/post/page.tsx b/web-next/app/post/page.tsx
index a1a79444..5d20d72f 100644
--- a/web-next/app/post/page.tsx
+++ b/web-next/app/post/page.tsx
@@ -586,7 +586,7 @@ function PostExplanationInner() {
))}
- Topic scores reflect how strongly this post matches each community-weighted topic.
+ Topic scores show how the post’s sparse topic vector combines with the approved topic-priority map inside the relevance signal.
) : (
@@ -604,7 +604,7 @@ function PostExplanationInner() {
- These are the community-voted weights applied at the time this post was scored.
+ These are the approved signal weights applied at the time this post was scored.
diff --git a/web-next/app/proposals/page.tsx b/web-next/app/proposals/page.tsx
index 243029f6..4e9a6a06 100644
--- a/web-next/app/proposals/page.tsx
+++ b/web-next/app/proposals/page.tsx
@@ -8,7 +8,7 @@ import { PolicyBar, PolicyLegend } from "@/components/ui/policy-bar"
import { ErrorCard, Skeleton } from "@/components/ui/state-kit"
import { SIGNAL_KEYS, SIGNAL_LABELS } from "@/lib/signals"
import { weightsApi, transparencyApi, type EpochResponse } from "@/lib/api/client"
-import { votingState, votingClosedDate } from "@/lib/governance-status"
+import { policyApplied, votingState, votingClosedDate } from "@/lib/governance-status"
function pct(value: number): string {
return `${Math.round(value * 100)}%`
@@ -27,8 +27,8 @@ function phaseLabel(epoch: EpochResponse): string {
return policyApplied(epoch) ? "Active policy" : "Closed"
}
-function policyApplied(epoch: EpochResponse): boolean {
- return epoch.status === "active" || epoch.closed_at == null
+function wasEnacted(epoch: EpochResponse): boolean {
+ return epoch.results_approved_at != null
}
/** The signal carrying the most weight in a policy — the round's headline. */
@@ -50,7 +50,7 @@ export default function ProposalsPage() {
})
const current = currentQuery.data
- const past = (historyQuery.data?.epochs ?? []).filter((epoch) => epoch.closed_at != null && epoch.id !== current?.id)
+ const past = (historyQuery.data?.epochs ?? []).filter((epoch) => wasEnacted(epoch) && epoch.id !== current?.id)
return (
@@ -59,9 +59,9 @@ export default function ProposalsPage() {
Governance
Proposals
- Every governance round is a proposal to reweight the feed. Members vote on the five ranking signals; when the
- round closes, the aggregated weights become the next epoch and the feed reranks. Each enacted proposal is
- recorded below and in the{" "}
+ Every governance round proposes a complete policy: five global signal weights, topic priorities, and content
+ rules. When the voting window closes, ballots are aggregated for results review. An operator approves or
+ rejects the proposal before the active policy is changed and rescored. Enacted proposals are recorded below and in the{" "}
) : past.length === 0 ? (
- No past rounds yet. When a round closes, the enacted policy will appear here.
+ No enacted proposals yet. An approved policy will appear here after results review.
) : (
@@ -161,7 +161,7 @@ export default function ProposalsPage() {
diff --git a/web-next/app/start/page.tsx b/web-next/app/start/page.tsx
index b07dfa78..473b709c 100644
--- a/web-next/app/start/page.tsx
+++ b/web-next/app/start/page.tsx
@@ -7,9 +7,9 @@ import { Container } from "@/components/ui/layout"
import { PageHero, HeroGlow, HERO_TOP } from "@/components/ui/page-hero"
export const metadata: Metadata = {
- title: "Get started — add the Corgi feed in Bluesky",
+ title: "Get started — Corgi Commons and the governance demo",
description:
- "Add the community-governed Corgi feed to your Bluesky app, explore it read-only, and connect an app password when you're ready to vote.",
+ "View Corgi Commons on Bluesky, try the anonymous governance demo, or request access to the limited voting pilot.",
alternates: { canonical: "/start/" },
}
@@ -18,28 +18,22 @@ const CORGI_FEED_URL = "https://bsky.app/profile/corgi-network.bsky.social/feed/
const steps = [
{
n: "01",
- title: "Open the Corgi feed on Bluesky",
+ title: "View and subscribe to Corgi Commons",
body: "Open the feed in your Bluesky app or on the web, then use Bluesky's feed controls to save it to your Home. No Corgi account is required to browse it.",
cta: { label: "Open the feed on Bluesky", href: CORGI_FEED_URL, external: true },
},
{
n: "02",
- title: "Explore it read-only",
- body: "Browse the ranked feed and open any post's receipt to see exactly why it ranked where it did. You can inspect everything without signing in.",
- cta: { label: "Open the live demo", href: "/demo", external: false },
+ title: "Try isolated shadow governance",
+ body: "Use the anonymous demo to propose a policy, combine it with 24 scripted deterministic voter archetypes, rerank a frozen comparison corpus, and inspect what moved. The session never changes the public feed.",
+ cta: { label: "Try the governance demo", href: "/demo", external: false },
},
{
n: "03",
- title: "Join the waitlist to vote",
- body: "Voting is in a limited pilot. Request access with your Bluesky handle; once you're approved, Corgi signs you in with a Bluesky app password — a scoped credential you can revoke anytime. Your real password never touches Corgi.",
+ title: "Request access to the voting pilot",
+ body: "Governance participation is currently limited to approved waitlist participants. If approved, Corgi signs you in with a Bluesky app password — a scoped credential you can revoke anytime. Your real password never touches Corgi.",
cta: { label: "Join the waitlist", href: "/sign-in", external: false },
},
- {
- n: "04",
- title: "Shape the feed with your community",
- body: "During an open round, set how much each ranking signal should matter. When the round closes, the community's aggregated weights become the feed's next policy.",
- cta: { label: "See the ballot", href: "/vote", external: false },
- },
] as const
export default function StartPage() {
@@ -54,8 +48,8 @@ export default function StartPage() {
size="md"
align="center"
eyebrow="Get started"
- title="Add the Corgi feed in Bluesky."
- subtitle="Corgi is a normal Bluesky custom feed — with one difference: your community governs how it ranks. Add it in a minute, explore it read-only, and vote when you’re ready."
+ title="Open Corgi Commons, try the demo, or join the pilot."
+ subtitle="Anyone can view the live Bluesky feed and use the anonymous shadow demo. Governance participation is currently available through an approved waitlist pilot."
actions={
<>
- Voting is closed for this round. Results are being tallied.
+ Voting is closed for this round. Aggregated results are awaiting review and operator approval.
) : state === "closed" ? (
- Voting for this round closed{closedOn ? ` on ${closedOn}` : ""}. The aggregated weights are the
- feed’s active policy until the next round opens.
+ Voting for this round closed{closedOn ? ` on ${closedOn}` : ""}. The approved policy is active until another proposal is approved.
) : epoch.voting_ends_at ? (
@@ -426,7 +425,7 @@ function VoteWorkbench({ epoch, myVote, topics, contentRules, isAuthenticated, o
Signal weights
Drag to allocate importance across the five signals. Adjusting one redistributes the rest — they
- always sum to 100%. The thin marker on each track is the community’s current average.
+ always sum to 100%. The thin marker on each track is the active approved policy.
@@ -471,7 +470,7 @@ function VoteWorkbench({ epoch, myVote, topics, contentRules, isAuthenticated, o
aggregation; the API `rules.threshold` is an absolute vote
count for that round, not a percentage, so it is not rendered here. */}
- Vote on which keywords to boost or suppress. Keywords take effect when backed by at least 30% of members voting on content rules.
+ Include keywords form an allowlist; exclude keywords take precedence. A keyword is proposed for adoption when at least 30% of ballots that submit content rules support it, and it is applied only after results review and approval.
@@ -532,7 +531,7 @@ function VoteWorkbench({ epoch, myVote, topics, contentRules, isAuthenticated, o
03 — Topic preferences
Topics
- Slide right to boost a topic, left to reduce it. The vertical marker shows the community average.
+ Slide right to boost a topic, left to reduce it. Topic preferences shape only the relevance signal. The vertical marker shows the active approved topic policy.
{touchedTopicCount > 0 && (
@@ -665,7 +664,7 @@ function VoteWorkbench({ epoch, myVote, topics, contentRules, isAuthenticated, o
{ballotCountText(epoch.vote_count)}
)}
- Each vote counts equally.
+ Fewer than 10 ballots use an arithmetic mean; 10 or more use a 10% trimmed mean.
diff --git a/web-next/components/bento-section.tsx b/web-next/components/bento-section.tsx
index 013fad4d..a8e22b8d 100644
--- a/web-next/components/bento-section.tsx
+++ b/web-next/components/bento-section.tsx
@@ -12,8 +12,8 @@ function SignalBlendUI() {
// arbitrary classes can't interpolate the constant — keep the hexes in sync.
const examples = [
{
- label: "Field note with context",
- detail: "A sighting post with location, correction, and source detail.",
+ label: "Research note with context",
+ detail: "A methods post with data, corrections, and source detail.",
outcome: "Ranks up",
signals: [
{ label: "Relevance", widthClass: "w-[92%]", colorClass: "bg-primary" },
@@ -33,7 +33,7 @@ function SignalBlendUI() {
},
{
label: "Bridge between interests",
- detail: "A post that connects the community topic to adjacent expertise.",
+ detail: "A post that connects open-network work to adjacent research or tooling.",
outcome: "Finds its people",
signals: [
{ label: "Relevance", widthClass: "w-[70%]", colorClass: "bg-primary" },
@@ -96,20 +96,24 @@ function CommunityVoteUI() {
text: "A ranking change is proposed before it affects the feed.",
},
{
- label: "Community vote",
- text: "Members choose which signals should matter more.",
+ label: "Voting window",
+ text: "Approved participants vote on signals, topic priorities, or content rules.",
},
{
- label: "Weights update",
- text: "The next epoch applies a visible set of weights.",
+ label: "Results review",
+ text: "Corgi aggregates the ballots and presents the proposed policy for review.",
},
{
- label: "Feed reorders",
- text: "Bluesky receives the same posts in a new order.",
+ label: "Operator approval",
+ text: "An operator approves or rejects the complete proposed policy.",
},
{
- label: "Receipt stays",
- text: "Corgi keeps the explanation tied to that epoch.",
+ label: "Rescore and publish",
+ text: "After approval, Corgi applies the policy, reranks, and publishes the ordered feed.",
+ },
+ {
+ label: "Inspect",
+ text: "Corgi keeps explanations tied to the policy epoch while Bluesky renders the posts.",
},
]
@@ -121,7 +125,7 @@ function CommunityVoteUI() {
auditable sequence
-
@@ -164,7 +168,7 @@ const features = [
id: "mixed-feed",
headline: "The feed is mixed, not topic-siloed.",
description:
- "A governed recommender has to reconcile recency, engagement, bridging, source diversity, and relevance in one ranking — and the demo shows the live receipts behind it.",
+ "A governed recommender reconciles recency, engagement, bridging, source diversity, and relevance in one ranking. Topic preferences shape relevance; content rules shape which posts are eligible.",
cta: "Explore the demo feed",
href: "/demo",
UI: SignalBlendUI,
@@ -173,7 +177,7 @@ const features = [
id: "epochs",
headline: "Epochs turn proposals into auditable changes.",
description:
- "Corgi's governance loop is proposal, vote, epoch transition, and receipt. The product story stays grounded in that loop instead of promising private communities or made-up vote totals.",
+ "Corgi's production loop is proposal, voting window, results review, operator approval, rescore, publication, and receipt. The shadow demo compresses that sequence without changing the public feed.",
cta: "See epoch history",
href: "/history",
UI: CommunityVoteUI,
diff --git a/web-next/components/community-examples-section.tsx b/web-next/components/community-examples-section.tsx
index 6b10f055..9eed3c98 100644
--- a/web-next/components/community-examples-section.tsx
+++ b/web-next/components/community-examples-section.tsx
@@ -4,13 +4,6 @@ import { SIGNAL_LABELS } from "@/lib/signals"
// Illustrative Bluesky-native community concepts, labeled only with Corgi's
// canonical ranking signals and the kind of feed noise each policy addresses.
const communityExamples = [
- {
- name: "Birders Who Code",
- initials: "BC",
- signal: SIGNAL_LABELS.bridging,
- description: "Field notes, scripts, and bird-call datasets stay balanced against generic tech jokes.",
- accentClass: "bg-[#CFE1D0] text-[#3E643F]",
- },
{
name: "Neighborhood Mutual Aid",
initials: "MA",
@@ -19,26 +12,12 @@ const communityExamples = [
accentClass: "bg-[#C8DDF2] text-[#284C6D]",
},
{
- name: "Open-Source Maintainers",
+ name: "Open-source Maintainers",
initials: "OS",
signal: SIGNAL_LABELS.relevance,
description: "Patches, docs, and release notes outrank memes and project drama.",
accentClass: "bg-[#F0D1A8] text-[#7A4A20]",
},
- {
- name: "Science & Research Feeds",
- initials: "SR",
- signal: SIGNAL_LABELS.source_diversity,
- description: "Papers, replications, and expert context beat hot takes and hype.",
- accentClass: "bg-[#C6E2EA] text-[#245A68]",
- },
- {
- name: "Local Newsroom & Civic Desk",
- initials: "LC",
- signal: `${SIGNAL_LABELS.recency} + ${SIGNAL_LABELS.source_diversity}`,
- description: "Council meetings, transit, housing, and weather stay findable during a news burst.",
- accentClass: "bg-[#D4DBE2] text-[#3A4A5C]",
- },
{
name: "Tabletop Creators",
initials: "TT",
@@ -67,7 +46,7 @@ export function CommunityExamplesSection() {
-
+
{communityExamples.map((community) => (
diff --git a/web-next/components/demo/community-picker.tsx b/web-next/components/demo/community-picker.tsx
index 8c1eb003..c5840065 100644
--- a/web-next/components/demo/community-picker.tsx
+++ b/web-next/components/demo/community-picker.tsx
@@ -27,9 +27,9 @@ export function CommunityPicker({
Public feed · isolated shadow session
-
Community Governed Feed
+
Corgi Commons
- Freeze a reviewer-safe comparison set from Corgi's published Bluesky feed, then run governance without changing what the public sees.
+ Open-network building, research, software, data, and the conversations connecting them. Freeze a reviewer-safe comparison set, then run governance without changing what the public sees.
@@ -374,7 +395,7 @@ export function HowItWorksReplay() {
/>
- The rank numbers and receipt panel are Corgi-site annotations for this product demo. Standard Bluesky clients render the ordered posts, not Corgi score panels.
+ Select a post to inspect its ranking. The rank numbers and receipt panel are Corgi-site annotations; standard Bluesky clients render the ordered posts, not Corgi score panels.
diff --git a/web-next/components/landing-ctas.tsx b/web-next/components/landing-ctas.tsx
index 7b3a0423..9c35e172 100644
--- a/web-next/components/landing-ctas.tsx
+++ b/web-next/components/landing-ctas.tsx
@@ -16,7 +16,7 @@ export function DemoCTA({ className }: LandingCTAProps) {
)}
>
- Explore the live demo
+ Try the governance demo
)
diff --git a/web-next/components/replay-teaser.tsx b/web-next/components/replay-teaser.tsx
index 8e181f7d..2c6dfad0 100644
--- a/web-next/components/replay-teaser.tsx
+++ b/web-next/components/replay-teaser.tsx
@@ -101,10 +101,10 @@ export function ReplayTeaser() {
- Tap Why on any post for its receipt. Rank badges and receipts are
- Corgi annotations, not native Bluesky chrome.
+ Select Inspect on any post for its score breakdown. Rank badges and receipts are Corgi annotations, not native Bluesky chrome.
- Illustrative demo — live ranking claims use Corgi receipts and snapshot data.
+ Illustrative preview — the governance demo uses a frozen snapshot sourced from Corgi Commons.
- See the full math and every receipt →
+ See the full policy and receipt walkthrough →