election-vibe 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "election-vibe",
+  "owner": { "name": "Arturo Garrido" },
+  "description": "election-vibe for Claude Code: the election-night results line and board from the installed election-vibe package. Unofficial results. Not an election authority. Not affiliated with any government, campaign, or party.",
+  "plugins": [
+    {
+      "name": "election-vibe",
+      "source": "./plugin",
+      "description": "The results line above the prompt and the results board in a pane (/elections), read from the installed election-vibe package's local snapshot. Unofficial results. Not an election authority. Not affiliated with any government, campaign, or party."
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arturo Garrido
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,323 @@
-# Temporary Holding Version
+# election-vibe: election night in your terminal and in Claude Code (Nov 3, 2026)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unofficial results for the US general election of November 3, 2026, in your terminal and in Claude Code (a results line above the prompt, the board in a pane), read from official free sources and a free public aggregator. Every governor, US Senate and US House race on the ballot nationwide (through civicAPI, and California's Secretary of State for California), with deep local coverage for eight California counties in the Bay Area and Los Angeles. It runs on your machine: one collector process reads the sources and keeps a local snapshot, and every command, the statusline and the plugin read that snapshot.
+
+> Unofficial results. Not an election authority. Not affiliated with any government, campaign, or party.
+
+## Get running for election night
+
+You need Node 22 or later.
+
+```bash
+npm i -g election-vibe     # installs the `elections` command (also as `election-vibe`)
+elections collect          # the collector: leave it running in its own terminal
+```
+
+Then pick how you want to watch:
+
+- **In a terminal:** `elections watch` in another terminal (your followed and hot contests, redrawn every 10 s; q or Ctrl-C quits).
+- **In Claude Code:** the plugin puts the results line above the prompt and the board in a pane (`/elections`); see [In Claude Code](#in-claude-code).
+
+Before Tuesday, follow what you care about: `elections find measure j palo alto`, then `elections follow <id>` (see [Find a contest and follow it](#find-a-contest-and-follow-it)).
+
+On Tuesday, after the polls close:
+
+- **Races outside California** (civicAPI: governors, Senate, House, the 13 statewide measures, Phoenix) need nothing from you. They appear once civicAPI marks a record as real data updated after its polls closed.
+- **California contests** read from the Secretary of State and the county offices need a one-time approval from you, per source, after polls close. Until then they show `awaiting production approval`. `elections admit --show` lists what is ready to approve: see the [election night checklist](#election-night-checklist-approving-the-california-sources) below.
+
+Without installing, put `npx election-vibe` where `elections` is (`npx election-vibe collect`, `npx election-vibe watch`). The statusline and the plugin need the global install.
+
+## What you will see
+
+Printed on Sunday, Nov 1, 2026, 9:39 PM PST, from real reads of the sources. Before the polls close, every contest looks like this: no counts yet, and the time its polls close.
+
+`elections prompt` (the statusline line, and the line above the prompt in Claude Code):
+
+```text
+🗳 32 hot races · first polls close Nov 3, 4:00 PM PST
+```
+
+`elections board --width 72 --limit 5` (what the `/elections` pane shows, cut to 5 contests here; without `--limit` the board and the pane show up to 100, and `elections watch` is the same board, redrawn with every contest):
+
+```text
+elections · snapshot 9:39 PM PST (0m ago)
+
+HOT
+  Alaska Ballot Measure 2 - Repeal Ranked-Choice Voting and Open Primar…
+    no source report dated after polls closed
+  Alaska US Senate
+    the source marks this as test data
+  Arizona Governor
+    the source marks this as test data
+  Arizona Proposition 144 - Citizenship and Voter ID Requirements
+    no source report dated after polls closed
+  Mayor - Oakland (RCV)
+    no source report dated after polls closed
+
++27 contests not shown: run `elections watch` in a terminal for all of
+them.
+```
+
+`elections race "palo alto, transactions"` (one contest):
+
+```text
+Nov 3, 2026 · production results
+Snapshot published Nov 1, 9:39 PM PST (0m ago)
+
+Measure J - City of Palo Alto, Transactions and Use Tax
+measure · no result yet
+Polls close: Nov 3, 8:00 PM PST
+▲ Santa Clara County Registrar of Voters: no source report dated after polls closed.
+
+No accepted result from this source yet.
+
+Santa Clara County Registrar of Voters · read 1h 31m ago
+2026-11-03.ca.santa-clara.measure-j-city-of-palo-alto-transactions-and-use-tax.regular
+Official results: https://vote.santaclaracounty.gov/view-election-results
+```
+
+"production results" in the race view's header names the store being read (results admitted after polls close), not a claim that any exist yet. A line starting with ▲ is a note about the source (here: nothing dated after polls close yet); ⚠ is a warning about the snapshot itself, and ✓ only a source's own call.
+
+"the source marks this as test data" is civicAPI flagging its own pre-election records as test data; they become results once civicAPI serves real data after the polls close. Once counts arrive, a board row names the leader with their share, marked "leading" (never a win), and `race` shows every candidate's votes and the source's own report time.
+
+## What it is, and what it is not
+
+- **It shows counts as each source publishes them**, with the source named and the source's own report time (or "report time not stated" when the source states none).
+- **It never calls a race.** "Leading" is computed from the counts and labeled as such. A contest shows "called by civicAPI" only when civicAPI itself flags a winner, and that is civicAPI's own call: not official, not certified. California's Secretary of State and the county sources publish no calls, so their contests show counts and leaders only.
+- **No projections, no expected-vote estimates.** Precincts reporting is shown as precincts, never as votes remaining.
+- **Bold and a check mark only for a source's own call.** Party colors (red Republican, blue Democratic) only on partisan contests, always beside the party letter; on a terminal only. Under `NO_COLOR`, or piped, the output is plain text with the same words.
+- **Corrections are shown, not hidden.** Totals can go down in a newer report; the contest says so.
+- **Late and stopped sources say so.** A contest whose source has not answered on its schedule is marked LATE, then NOT UPDATING; a source that refused access says so on its contests.
+- **civicAPI is never called official.** A race view names the official results page of its source; for a civicAPI contest it names the jurisdiction's own page where one is recorded (Phoenix), and otherwise says "Results source: civicAPI (not an official source)". The `--json` twin says the same: `source.official` is false for civicAPI, and `source.officialLink` is only a link the registry holds (null otherwise).
+- **Before results, the poll close.** A race view with no result yet prints when its polls close, in your display zone, with the contest's own zone beside it when they differ. The time is when the last polls in the state close (a state split across two zones closes with its later one), from a written table of each state's closing hours; civicAPI's own stated time is used only when it is later.
+
+## Commands
+
+```bash
+elections watch            # followed and hot contests, redrawn every 10 s; q or Ctrl-C quits
+elections list --preset hot
+elections list --county santa-clara
+elections race "palo alto unified"   # one contest; a query that matches several lists their ids
+elections follow <contest id>
+elections prompt           # one line for a statusline, from the local snapshot only
+elections board            # the watch board printed once, 100 contests at most (what the plugin's pane shows; --color for the watch's colors)
+elections sources          # each source's health, last revision and age
+elections admit --show     # election night: every California source's approval state (approves nothing)
+elections coverage         # what is covered and what is not
+```
+
+The collector prints one line per cycle (what it asked each source and what it kept); every other command reads the snapshot it wrote and never fetches. Before the polls close, contests read "no source report dated after polls closed" or "no result yet": that is expected. Everything served before then is test or zero-report data and goes to a separate test store, which `--store rehearsal` shows (every row marked TEST).
+
+`list`, `race`, `find`, `sources`, `coverage` and `admit --show` take `--json` for scripts, with the same facts. `watch` is a screen: it redraws from the local snapshot only, never the network, and needs a terminal (piped, it prints one frame and says so). `prompt` and `board` print text only (`list --json` is their twin for scripts). Closing a reader never stops collection.
+
+Times are shown in your computer's time zone; `--tz <IANA zone>` (for example `--tz America/New_York`) or `ELECTIONS_TZ` picks another.
+
+### Find a contest and follow it
+
+`find` searches the contest list on your machine (no network): every word must appear in a contest's title, county or id, and it prints each id. `race` takes its words as one phrase, punctuation included: it shows the one contest whose title or id contains that phrase (the comma in `"palo alto, transactions"` is part of it, as it is part of the title), or lists the ids when several match:
+
+```bash
+elections find measure j palo alto         # 1 match: its id and title
+elections find measure j                   # 4 matches: each id and title
+elections race "palo alto, transactions"   # one match: Palo Alto's Measure J, its race view
+elections follow 2026-11-03.ca.santa-clara.measure-j-city-of-palo-alto-transactions-and-use-tax.regular
+elections list --followed                  # what you follow; `watch` and `prompt` show it first
+elections race "proposition 40"            # a statewide proposition: Yes and No counts
+elections race "missouri amendment 3"      # a statewide measure outside California (civicAPI): Yes and No counts
+elections list --state CA --level measure  # every California measure, statewide and local
+```
+
+`unfollow <id>` removes one. Follows are kept on your machine, in the data directory. A search that finds nothing means only that this list holds no such contest; `elections coverage` says what the tool covers, and `find` names a county it does not cover (Napa, San Francisco) with that county's official results page, and Virginia's ballot questions as not covered, with Virginia's official results page.
+
+## In Claude Code
+
+Two ways, both reading the same local snapshot. Pick one: in a terminal, using both shows the same line twice (once in the statusline, once above the prompt). Both need the global install (`npm i -g election-vibe`); `npx` leaves nothing installed for them to run.
+
+### Option A: the statusline only
+
+`prompt` prints one line for a statusline: your followed contests (or, with none followed, the hot races), one shown and the rest counted (`+N`). A source call or a withdrawn call from the last five minutes is shown first. It reads the local snapshot only: it never fetches, never starts the collector, and never prints an error (with no snapshot it says `no results yet · run: elections collect`). Before any of those contests' polls close it says when the first one does; a snapshot more than 10 minutes old is called out first (`⚠ results 14m old`). Same words as the board: "leading" is never a win, and ✓ marks only a named source's call. `--width N` (default 80), `--color` for color, `--store rehearsal` for the test store.
+
+Add this `statusLine` key to `~/.claude/settings.json`, beside the settings already there; do not replace the file. A file has one `statusLine`: this replaces yours, if you have one.
+
+```json
+{
+  "statusLine": { "type": "command", "command": "elections prompt --color" }
+}
+```
+
+Keep a copy of your previous `statusLine` value: putting it back is the whole restore.
+
+### Option B: the plugin (line above the prompt, board in a pane)
+
+The package carries a Claude Code plugin: the same line above the prompt (in a terminal and in the desktop app's Code tab), and the results board in a pane with `/elections` (the `board` command's output in the watch's colors, monospaced, re-read every 10 seconds while the pane is open; `NO_COLOR` set where Claude Code runs keeps it plain). It needs no `settings.json` edit, and it installs nothing else: no statusline, no notifications. It runs the package's own `elections` from the installed package, reads the local snapshot only, and never starts the collector: start `elections collect` first, or the line says `no results yet · run: elections collect`. Install the package globally, then, in a terminal:
+
+```bash
+claude plugin marketplace add "$(npm root -g)/election-vibe"
+claude plugin install election-vibe@election-vibe --config store=production   # production is the default, shown so you know the option
+```
+
+Installed at the user scope, it also loads in the desktop app's Code tab. Tested with Claude Code 2.1.316. The plugin is read from the installed package's folder, so after `npm i -g election-vibe@latest` run `/reload-plugins` (or start a new session). Its one option, the results store, is `production` (the default) or `rehearsal` (the test store, every row marked TEST): `--config store=rehearsal` on the install, or `/plugin configure election-vibe@election-vibe` later. To remove it: `claude plugin uninstall election-vibe@election-vibe`, then `claude plugin marketplace remove election-vibe`.
+
+## Election night checklist: approving the California sources
+
+Before the polls close, everything the sources serve is test or zero-report data and stays in a separate rehearsal store. A source that carries its own test flag (civicAPI) is admitted by itself once its record says it is not test data and was updated after its contest's polls closed: **contests read from civicAPI need no approval.**
+
+The official sources carry no test flag, so each installation approves its first production report from each of them locally, once, after the polls close. These are the nine sources that need it (`elections sources` lists them with their state):
+
+| Source id | Source |
+|---|---|
+| `ca-sos` | California Secretary of State: the California Governor, US House, State Senate and Assembly contests, and the 14 statewide propositions |
+| `scc-clarity` | Santa Clara County |
+| `smc-csv` | San Mateo County |
+| `marin-clarity` | Marin County |
+| `contra-costa-clarity` | Contra Costa County |
+| `sonoma-clarity` | Sonoma County |
+| `la-json` | Los Angeles County |
+| `solano-html` | Solano County |
+| `alameda-html` | Alameda County |
+
+You only need the ones whose contests you watch: approve `ca-sos` for California's statewide and legislative contests, and a county for its local contests. For a California contest, civicAPI is only a cross-check: its numbers are not shown in place of an unapproved source.
+
+What you can do before Tuesday: install, start the collector, follow your contests, and run `elections sources` to see each source answering. `admit` refuses an approval before the source's polls close (California's close at 8:00 PM PST).
+
+On Tuesday, after 8:00 PM PST:
+
+1. **`elections admit --show`** (no source named) lists every source that needs an approval, with its state: polls still open, no report read yet, a zero report ("do not approve yet"), ready, or already approved. Under each source with a report it prints the latest report the collector read, its report time, whether it carries votes, two or three of its contests with their counts from the test store (where an unapproved post-close report is held until you approve it; only contests the admission rule holds for approval count as evidence or are shown), and the source's official results page. It approves nothing.
+2. For a source marked ready, open its official results page and check that the sample contests' counts match it (`elections race "<contest>" --store rehearsal` shows any other contest from the same report).
+3. Paste the approval line printed under that source: `elections admit <source> --revision <order> --hash <hash>`. The line is printed only for a source whose polls are closed and whose latest report is held for approval by the admission rule (a report the source dates before polls close never is; a county report that states no time of its own is judged by the polls' close alone), is in the test store exactly as read, and carries votes. Otherwise the source says why, with no line.
+4. A zero report is never approved: before counting starts, a source can serve a zero report stamped after polls close, and approving it proves nothing about the results to come. Wait for the collector's next read and run `elections admit --show` again.
+
+`elections admit --show --json` is the twin for scripts. `elections admit <source> --show` prints one source's latest report with its `--revision` and `--hash`, without the counts or the ready check.
+
+Approving one report admits it and every later report from that source: you do not approve again as the counts update. If a newer report arrives while you are checking, approve the one you checked; the newer one follows it. After approval, any older report (a rehearsal file arriving late) is rejected.
+
+Nothing is production while a contest's polls are open, whatever was approved. A clock passing a time never activates a source. Until a source is approved, its contests show "no source report dated after polls closed" before the polls close and "awaiting production approval" after. `elections admit <source> --revoke` withdraws an approval.
+
+## Coverage
+
+### National and state
+
+| Contests | Source |
+|---|---|
+| Outside California: 35 governors, 35 US Senate (including the Florida and Ohio specials), 383 US House | civicAPI |
+| Nevada: Nevada Governor and all four U.S. House contests (part of the row above) | civicAPI |
+| California Governor, 52 US House, 20 State Senate, 80 State Assembly | California Secretary of State (civicAPI as a cross-check) |
+| California's 14 statewide propositions (1 to 5 and 37 to 45): Yes and No counts only, never passed or failed | California Secretary of State |
+| 13 statewide ballot measures outside California: Alaska Ballot Measure 2, Arizona Proposition 144, Colorado Amendment 86, Idaho Proposition 1, Maryland Question 3, Massachusetts Question 3, Question 4 and Question 8, Missouri Amendment 3 and Proposition A, Nevada Question 6 and Question 7, Ohio Issue 3. Yes and No counts only, never passed or failed; each record checked one by one (its exact title, its state, Yes and No) | civicAPI (not an official source) |
+
+Nationwide that is all 36 governors, 35 US Senate and 435 US House contests on the ballot. California has no US Senate race this year. Nevada's own results come through civicAPI only: the state's site refuses automated requests, and its official election information is at https://nvsos.gov/sos/elections/election-information/2026-election-information (not a results feed this tool reads).
+
+Territorial governorships (Guam, the US Virgin Islands and the other territories) are out of scope by decision, not a coverage gap.
+
+### Counties (local contests)
+
+| County | Covered | Source | Official results |
+|---|---|---|---|
+| Santa Clara | Covered: 93 local contests | Santa Clara County Registrar of Voters | https://vote.santaclaracounty.gov/view-election-results |
+| San Mateo | Covered: 91 local contests | San Mateo County Elections Office | https://smcacre.gov/elections/november-3-2026-election-results |
+| Marin | Covered: 60 local contests | Marin County Elections Department | https://www.marincounty.gov/departments/elections/november-3-2026-general-election/election-results-110326 |
+| Contra Costa | Covered: 71 local contests | Contra Costa County Elections Division | https://www.contracostavote.gov/november-3-2026-election-results/ |
+| Sonoma | Covered: 49 local contests | Sonoma County Registrar of Voters | https://sonomacounty.gov/administrative-support-and-fiscal-services/registrar-of-voters |
+| Los Angeles | Covered: 316 local contests | Los Angeles County Registrar-Recorder/County Clerk | https://results.lavote.gov/#year=2026&election=4348 |
+| Solano | Covered: 38 local contests | Solano County Registrar of Voters | https://www.solanocounty.gov/unofficial-election-results |
+| Alameda | Covered: 112 local contests | Alameda County Registrar of Voters | https://acvote.alamedacountyca.gov/election-information/elections?id=260 |
+| Napa | Not covered: the county offers no automated results path | | https://www.napacounty.gov/402/Election-Results |
+| San Francisco | Not covered: the county offers no automated results path | | https://www.sfelections.org/results/20261103w/detail.html |
+
+| Other contests | Covered | Official results |
+|---|---|---|
+| Phoenix City Council districts 2, 4, 6, 8 | Covered: 4 contests (civicAPI, each record checked against the city's certified candidates; a majority wins outright, otherwise a March 9, 2027 runoff) | https://www.phoenix.gov/administration/departments/cityclerk/programs-services/elections/november-election-26.html |
+| DC Mayor; DC Board of Education wards 3 and 5 | Not covered: no qualified automated source | https://electionresults.dcboe.org/ |
+| Virginia ballot questions (Constitutional Amendment Questions 1, 2 and 3) | Not covered: the only automated source lists each question twice with nothing to tell the copies apart | https://results.elections.virginia.gov/ |
+
+What "covered" means: every contest listed for a county comes from that county's own results feed. Whether each county's list is its complete local ballot is not yet reconciled, and the tool never shows a county as "fully covered". Statewide and state legislative contests for every California county come from the Secretary of State. Run `coverage` for the current statement per county.
+
+How local results are shown:
+
+- **Partial results say so.** A district that spans counties shows "partial jurisdiction" when only one county's share is read. A ward or trustee area is called partial only when another county's file carries the same ward; otherwise it says "scope unconfirmed", because the ward may lie wholly in one county.
+- **Ranked-choice contests in Alameda County show first choices only**, as the county's results page publishes them; no rounds are computed.
+
+## Sources and attribution
+
+- **civicAPI** (https://civicapi.org): national contests outside California. Results data by civicAPI.
+- **California Secretary of State** (https://electionresults.sos.ca.gov/): California's statewide and legislative contests and its statewide propositions.
+- **County election offices** listed above: local contests.
+
+Requests are paced per installation: one collector, a few documents per source every 5 to 10 minutes, and civicAPI one request at a time with followed and preset contests first (about 0.6 requests per second with the default pacing). A source that throttles is backed off; a source that refuses access is stopped until you look into it, and `elections enable <source>` asks it again (a new refusal stops it again). Any source can be silenced locally with `disable <source>`.
+
+## Running the collector
+
+The collector is a foreground process: leave it in its own terminal, or run it in the background and read its log:
+
+```bash
+nohup elections collect > /dev/null 2>&1 &
+tail -f ~/.local/state/elections-companion/2026-11-03/collector.log
+```
+
+It writes one line per cycle to `collector.log` in the data directory, and the same line to its terminal.
+
+You can start it any time before Tuesday and leave it running. Until a source's first contest closes its polls, the collector reads that source about once every 6 hours (test and zero reports, kept in the test store); from then on it reads on its election-night pace. It never needs a restart for polls closing. `find`, `list` and `race` work even before the first collect: the contest list ships in the package (only the results need the collector).
+
+On a Mac, `caffeinate -i elections collect` keeps the machine from idle sleep while the collector runs (closing a laptop's lid still sleeps it). If your laptop sleeps, the collector sleeps with it and carries on when it wakes; while it sleeps nothing is read, and the readers say how old the snapshot is (`⚠ results 14m old`). Keep the machine awake on election night if you want current results.
+
+### Updating during election night
+
+A running collector does not update itself. To take a fix:
+
+1. Stop the collector: Ctrl-C in its terminal, or, for a background one, `kill <pid>` with the process id `pgrep -f "elections collect"` prints. It finishes the read in progress, publishes, and exits.
+2. Update: `npm i -g election-vibe@latest`, then `elections --version`.
+3. Start it again: `elections collect`. (With npx: `npx election-vibe@latest collect`.)
+4. With the plugin: `/reload-plugins` in Claude Code.
+
+Run one collector per data directory. The lock enforces it as far as a plain file can: a running collector renews it every 30 seconds, and a collector that finds another took over, or that another collector published since its cycle began, stops without publishing. What a file lock cannot rule out is two collectors claiming within the same few milliseconds.
+
+The snapshot survives a stop, a crash or a killed process: the restarted collector carries on from it. If the old process was killed rather than stopped, the restart takes over its lock at once; while another collector is still running on the same data directory, the start is refused and names that process.
+
+## Operating window
+
+Collection is supported through **Wednesday, November 4, 2026**. The collector does not stop itself on that day: stop it (Ctrl-C) when you are done. Once it stops, nothing claims to be current: every view shows the snapshot's age, contests go LATE and then NOT UPDATING as their sources' schedules pass, the statusline line warns once the snapshot is more than 10 minutes old, and nothing is ever labeled final. Counting continues for weeks (California certifies by December 11); for final results, use each source's official page.
+
+## Where it keeps its data, and removing it
+
+Everything lives in one data directory: `~/.local/state/elections-companion/2026-11-03/` (under `$XDG_STATE_HOME` when that is set; `--data-dir <dir>` or `ELECTIONS_DATA_DIR` picks another). It holds the snapshots, your follows and approvals, and the collector's log: a few megabytes, plus a line per cycle in the log.
+
+No account, no telemetry. The collector contacts only the sources listed above; every other command, the statusline line and the plugin read files on your machine and make no network request.
+
+To remove it all, in this order (the plugin lives inside the package's folder, so remove it first):
+
+1. Stop the collector.
+2. If you installed the plugin: `claude plugin uninstall election-vibe@election-vibe`, then `claude plugin marketplace remove election-vibe`. If you changed your statusline: put your previous `statusLine` back.
+3. `npm rm -g election-vibe`.
+4. Delete the data directory.
+
+## FAQ
+
+**What is civicAPI?** A free public aggregator of election results (https://civicapi.org). It is not an official source, and this tool never calls it one. Its winner flag is civicAPI's own call, shown as "called by civicAPI". The collector asks it one request at a time, at least 1.1 seconds apart.
+
+**What is `--preset hot`, and are there other presets?** `hot` is the only preset: 32 contests (Senate and governor races, the hot statewide measures and a few California contests), chosen by the package's author, each with a recorded reason and a public link. `elections list --preset hot` lists them. The collector reads them, and the contests you follow, first. `watch` and the pane show them after your followed contests; `prompt` shows them when you follow nothing.
+
+**Do I need `admit` if I only follow national races?** Only if one of them is in California. Contests read from civicAPI (every governor, Senate and House race outside California, the 13 statewide measures, Phoenix) need no approval: civicAPI's own test flag and post-close time admit them. California's own contests (its Governor, its 52 US House races, its legislature, its propositions, and the county contests) come from the California sources, which each need one approval; see the [checklist](#election-night-checklist-approving-the-california-sources).
+
+**Why are San Francisco and Napa linked instead of read?** Neither county offers an automated results path this tool can use, and it never works around a site's bot protections. Their rows link the official results pages.
+
+**Does collection stop on November 4?** No: the collector runs until you stop it. November 4 is how long the tool is supported; see [Operating window](#operating-window).
+
+**Does this run on Windows?** Not tested. This release was built and tested on macOS. The CLI uses only Node, but the plugin assumes a macOS or Linux shell path, and nothing here has been tried on Windows or Linux.
+
+**Does `race` treat the comma as part of the query?** Yes. `race` takes its words as one phrase, punctuation included, and looks for it in titles and ids: `"palo alto, transactions"` matches Palo Alto's Measure J because its title contains that phrase. `find` is the one that matches word by word.
+
+**Does `prompt` have a `--json` twin?** No. `prompt` and `board` print text; `list --json` (with `--followed` or `--preset hot`) carries the same facts for scripts.
+
+**Which Claude Code version?** The plugin was tested with Claude Code 2.1.316. To update: update the package, restart the collector, then `/reload-plugins`. To remove: the plugin before the package (see above).
+
+**Does it work behind a corporate proxy?** It connects to the sources directly and does not use a proxy (`HTTPS_PROXY` is not read). On a network that inspects HTTPS or blocks direct connections, the reads fail, and `elections sources` says why for each source (for example "the connection's certificate is not trusted").
+
+**How do I pick the display time zone?** `--tz <IANA zone>` on any command, or `ELECTIONS_TZ`. The default is your computer's zone.
+
+**How much disk does it use?** A few megabytes for the snapshots, plus one log line per collector cycle.
+
+**What license is it under?** MIT.
+
+## Problems and contact
+
+A broken source, a wrong display, a question: @arturogarrido on X (https://x.com/arturogarrido).