Method

Sources and keys

ZIP vintage ZCTA→119th Congressional District crosswalk from OpenSourceActivismTech/us-zipcodes-congress (zccd.csv), built from 2020 Census block equivalency files updated for the 119th Congress (Census, July 30, 2024) and ZCTA relationship files. A ZCTA is not always a USPS ZIP; about 15% of ZIPs span more than one district — we list every district the file records. Street-address and geolocation lookups use the Census Geocoder (Public_AR_Current / Current_Current, 119th CDs) and override the ZCTA table when they match.. Keys are optional unless marked required. This table never prints secret values — only whether a named env var is present on this host.

How effects are written

Every roll call gets a What this was, What it does / did, and Who it touches block — or an honest empty state: “no machine-readable summary yet.” Effects never enter score_overall.

• From the official roll — question, description, result, and the stored impact line copied from Clerk / Senate XML. Source link required.
• Inferred from bill text / CRS summary — only when a named classification rule fired (direction_rule). The rule id is printed. This is not a CRS extract; we do not invent CRS language. Open Congress.gov for official summaries.
• We refuse to invent constituent quotes, dollar effects, or “what this means for you” without a source. Blank over guessed.

Offices we cover

Congress and OpenStates legislators remain the core directory. The executive branch (president, VP, cabinet chairs) is listed from office titles plus sourced names when a public file attaches them. We also list judges, school boards, superintendents, mayors, councils, and elected prosecutors when a public source answers: CourtListener sitting positions (optional COURT_LISTENER_TOKEN), Google Civic on a full address, or a curated data/fixtures/local-officials.csv. Ballotpedia is a citation, not a datastore — we do not scrape it. If a source is silent, that office type stays empty. score_overall is still only congressional machine-readable roll calls.

Executive branch and federal agencies

The president, vice president, cabinet secretaries, and a seed set of federal agencies (ICE, FEMA, DOJ, HHS, EPA, IRS, CBP — the set expands) get the same sunlight rules as Congress: sourced records or an honest blank. There is no invented AV index for the cabinet. Executive orders and agency actions never enter score_overall.

• Dual ledger. Every /agency/:slug page always shows Assisting and Complicating / harming. Language is tied to documented outcomes or standing public functions with a source URL. If a side has no structured public items yet, that column says so. We never ship a page that only dunks or only praises.
• Standing functions come from the agency's own program pages (Stafford Act assistance, ERO detention, IRS refunds and liens, and so on). OpenFEMA declarations append to FEMA assisting when the API answers. Federal Register rules stay on the timeline — we do not vibe-classify a rule onto a ledger side.
• President and VP names come from unitedstates/congress-legislators executive.yaml (fetched on a /executive cache miss so we do not wait for the ingest job) or a Federal Register president field. Cabinet / cabinet-rank names and official portraits attach from the White House /administration/cabinet/ page onto existing exec-* chairs — same cache-miss fetch on /executive, not only the ingest job. Official presidential and vice-presidential portraits are taken from that page when the filename identifies them, even if img alt is empty. If that page is down or a chair is missing, the chair stays a title-only shield. Named people without a sourced photo get a silhouette labeled “no official portrait on file.” We do not invent faces or secretaries. Agency ledger rows stay shields — no portraits there.
• Optional USASPENDING_ENABLED=1 pulls toptier obligations. ICE/FEMA/CBP/IRS figures are labeled as parent-department totals. No secret key.

Judicial record and follow-up alerts

A judge profile has retention/election text and CourtListener opinion links when those fields exist. There is no fake attendance score and no computed “soft on crime” label. A public-record follow-up on /alerts needs two primary-source URLs (disposition + later charge or conviction of the same named person) inside 90, 180, or 365 days (default 180). Rows start as pending review. Published alerts never enter the index. If we cannot obtain a reliable open recidivism feed, the list stays empty — we do not invent cases.

Marketplace is not the index

Outreach and cause CTAs live on /marketplace and in labeled slots on district and official pages. Every outreach row says Paid by … and the FEC committee ID when given. Causes say “Nonprofit / cause — not the official record.” Pending $0 drafts appear on /money-trail only. Ads, donations, trades, news, and outreach never enter the leaderboard.

Influencer disclosure

Influencer posts are context / marketplace speech. They never enter score_overall. Every post must choose paid or unpaid — there is no publish path without it. Paid shows Paid by … (FEC / brand optional). Unpaid shows Not paid — independent. American Voices does not endorse influencer speech. False disclosure is a public integrity violation: reprimand → mute → ban. Banned accounts keep old posts with an audit marker. Influencers may wire an external Shopify, Etsy, WooCommerce, Square, or other storefront. American Voices does not sell those items or take payment — checkout stays on the merchant. Product cards are fetched only when an env-referenced token is present; we never invent merch. Storefronts never enter score_overall.

Civic digest and install

The record isn't a feed. Home leads with Your district. The record. What changed. When a ZIP is saved (cookie, localStorage, or account profile), / and /digest show votes by your officials, new filings, published safety follow-ups, and national executive items. Civic-feed opinions and influencer posts are never on that digest. We notify rarely, and only with sources. Default notification categories are roll calls, safety follow-ups, and major executive orders — never influencer posts or topic chatter. Web Push is opt-in and requires VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY. Without both keys the UI says pushes are coming and tells you to use the digest. We do not fake delivery.

Accounts, thoughts, and anti-bot

Identified profiles live at /join and /u/:handle. Roles are Citizen, Creator, or Candidate — one primary. Thoughts on /topics and the district-first civic feed at /feed are opinion. They never enter score_overall. Email must be verified to post. A candidate without a matching FEC committee shows Self-attested — not verified against FEC. We do not invent verified politicians. Creator profiles reuse the influencer disclosure and sanction ladder. Anti-bot is a public ladder on /integrity — not a paid blue check, not a silent shadowban. Production should add Google/Apple OAuth later; MVP is a hashed email one-time code.

Civic feed ranking (v0)

Phase A social skeleton. Posts live inside American Voices, district-first. The civic record is never for sale and never rewritten by posts, opinions, or ads. Ranking is AV-sized honesty — chronological recency, district relevance, and public mute/report hooks. This is not an import of xai-org/x-algorithm.

Free tier: a labeled marketplace ad occupies every third feed slot. Subscribers skip ads and keep posting privilege after moderation strikes. Non-subscribers cool down or lose posting privilege when muted for spam. Candidates and influencers stay in the labeled marketplace lane — they are not mixed as organic reach in the free feed.

Context is not the index

X posts, news, bill actions, filings, filed trades, state-chamber vote rows, executive orders, agency actions, and topic thoughts never enter score_overall. Attendance, decisiveness, committee workload, optional keyword pillars, and capped verdicts are the only inputs. Context is labeled on the home feed, district “what changed” list, and the official Context tab. Executive / agency items are labeled Executive or Agency — not the congressional record.

Known gaps

• Default npm run ingest pulls the complete 119th House (2025+2026) and Senate (sessions 1–2). A 2026-09-04 run stored 1,547 rolls after retrying four Senate session-1 files that dropped on the first pass. Leftovers, if any, are named in the ingest table above. Earlier Congresses are not ingested. --recent is the short window.
• FEC weball26 matched 535 of 539 sitting members. Four seats stay blank (no invented dollars).
• State legislatures: OpenStates directory (CSV, plus API people enrich when keyed; 7,287 people; 0 state files missing). Empty scores. Machine-readable OpenStates votes are context only.
• House financial-disclosure timeliness is linked, not ingested.
• In-state vs out-of-state itemized receipts stay blank unless FEC returns a usable split.
• Statements and floor speeches are not a feed. We do not invent them.
• Most school boards and local offices have no national machine-readable people file we can legally bulk-import. Civic-on-address and a curated CSV are the honest paths. Ballotpedia dumps are unused (license).
• CourtListener ingest is a sampled sitting-position pull, not every U.S. judge. Opinion counts stay blank if the API does not answer.
• No live recidivism warehouse is wired. Follow-up alerts are a sourced, moderated model with an empty published list until real records are filed.
• Agency seed set is seven components. IG reports, GAO findings, and adverse court rows stay empty until a machine-readable sourced item is ingested — we do not invent scandals.
• Cabinet chairs stay title-only if the White House cabinet page fails or omits that office. Congress.gov nominations are not auto-attached (wrong-person risk).

Privacy

How this host treats accounts, cookies, ZIP personalization, marketplace ads, and the civic index is written in plain English on /privacy. The record is never for sale. That page is an operational policy, not a compliance certificate — counsel should review it before anyone leans on it.