tokens-for-good 0.4.23 → 0.4.25

package/README.md

@@ -1,9 +1,11 @@
 # Tokens for Good
 
-Donate your spare AI tokens to research nonprofit organizations for [Fierce Philanthropy](https://tokensforgood.ai)'s social impact directory. Like Folding@Home, but for AI tokens — crowdsourced compute for social good.
+Contribute your spare AI tokens to research nonprofit organizations for [Fierce Philanthropy](https://tokensforgood.ai)'s social impact directory. Like Folding@Home, but for AI tokens; crowdsourced compute for social good.
 
 Works with Claude Code, OpenCode, Cursor, Windsurf, Devin, and Qwen Code as an MCP server.
 
+**Docs & troubleshooting:** [tokensforgood.ai/docs](https://tokensforgood.ai/docs)
+
 ## Quickstart
 
 1. **Sign up** at [tokensforgood.ai/contribute](https://tokensforgood.ai/contribute) (GitHub OAuth, free) and copy your API key.
@@ -13,7 +15,7 @@ Works with Claude Code, OpenCode, Cursor, Windsurf, Devin, and Qwen Code as an M
    npx tokens-for-good init
    ```
 
-   init is interactive: it asks for your API key, the cadence you want (daily, with a chosen number of runs per day / weekly / one-off), and then writes everything — MCP config, SessionStart hook, `/tfg` and `/tfg-schedule` skills, and your preference — in one shot.
+   init is interactive: it asks for your API key, the cadence you want (daily, with a chosen number of runs per day / weekly / one-off), and then writes everything (MCP config, SessionStart hook, `/tfg` and `/tfg-schedule` skills, and your preference) in one shot.
 
 3. **Open your AI coding tool.** Your first session acts on the cadence you picked automatically:
    - Scheduled → it sets up `/schedule` via the `/tfg-schedule` skill.
@@ -25,18 +27,18 @@ To change cadence later, run `npx tokens-for-good init` again.
 
 Each org takes about 5 minutes:
 
-1. **Research** — web search + 6-prompt methodology, then fill in a v3 EVIDENCE TABLE (8 rows of verbatim quotes + real URLs; blanks are honest when the evidence doesn't exist)
-2. **Verify** — every citation URL checked, hallucinations flagged and corrected
-3. **Humanize** — voice pass (no em dashes, no AI-tells, analyst voice)
+1. **Research:** web search + 6-prompt methodology, then fill in a v3 EVIDENCE TABLE (8 rows of verbatim quotes + real URLs; blanks are honest when the evidence doesn't exist)
+2. **Verify:** every citation URL checked, hallucinations flagged and corrected
+3. **Humanize:** voice pass (no em dashes, no AI-tells, analyst voice)
 
-Under v3 dual-research, every org is researched by two contributors independently. An independent validator then prunes any unsupported or fabricated evidence from both reports — reading the server's cached page text, so it does zero web fetches — and a consolidator merges the validated EVIDENCE TABLEs into one table the server scores deterministically (out of 120). A human reviewer finalizes it for the directory.
+Under v3 dual-research, every org is researched by two contributors independently. An independent validator then prunes any unsupported or fabricated evidence from both reports (reading the server's cached page text, so it does zero web fetches), and a consolidator merges the validated EVIDENCE TABLEs into one table the server scores deterministically (out of 120). A human reviewer finalizes it for the directory.
 
 ## Contributor tiers
 
-- **New** — first 5 orgs, easy orgs only
-- **Bronze** — 5+ orgs
-- **Silver** — 25+ orgs, >80% acceptance rate
-- **Gold** — 100+ orgs, >90% acceptance rate
+- **New:** first 5 orgs, easy orgs only
+- **Bronze:** 5+ orgs
+- **Silver:** 25+ orgs, >80% acceptance rate
+- **Gold:** 100+ orgs, >90% acceptance rate
 
 Track your progress at `npx tokens-for-good --impact` or on the dashboard.
 
@@ -46,28 +48,27 @@ Once installed, these are available to your AI via the MCP server:
 
 | Tool | Purpose |
 |---|---|
-| `next_action` | Tells you whether to validate, consolidate, or research next |
 | `claim_org` | Reserves the next available nonprofit (up to 2 researchers per org under v3) |
 | `get_methodology` | Fetches research / verify / humanize / validate / consolidate instructions |
 | `submit_report` | Submits a finished report (or a merged consolidation report with `disagreement_rows`) |
 | `get_next_validation` | v3 validator: fetch both reports + cached page text to prune unsupported evidence |
 | `submit_validation` | v3 validator: submit corrected reports (subtract/correct only, never add) |
 | `get_next_consolidation` | v3 consolidator: fetch your assignment + both source reports to merge |
-| `set_role_preference` | Prefer the low-fetch roles (validation/consolidation) — best for local models |
+| `set_role_preference` | Prefer the low-fetch roles (validation/consolidation); best for local models |
 | `create_agent` / `list_agents` / `rotate_agent_key` / `revoke_agent` | Run several harnesses at once: each agent gets its own key + research slot |
 | `setup_automation` | Emits `/schedule` prompt (normally called by `/tfg-schedule` skill) |
-| `my_impact` / `research_status` / `get_badge` | Stats, leaderboard, GitHub README badge |
+| `my_impact` / `research_status` | Your stats + the project leaderboard |
 | `snooze` | Quiet the session-start prompt for N days |
 
 ## Non-Claude-Code platforms
 
-- **OpenCode** — `init` writes `~/.config/opencode/opencode.json` and prints a cron line you can paste into `crontab -e`.
-- **Qwen Code** — `init` writes `~/.qwen/settings.json` (preserving other keys) plus a `/tfg` slash command at `~/.qwen/commands/tfg.md`. For recurring runs, enable Qwen Code's experimental cron (`QWEN_CODE_ENABLE_CRON=1`) or use a system cron line.
-- **Cursor / Windsurf / Devin** — `init` writes the MCP config; automation requires platform-native scheduling.
+- **OpenCode:** `init` writes `~/.config/opencode/opencode.json` and prints a cron line you can paste into `crontab -e`.
+- **Qwen Code:** `init` writes `~/.qwen/settings.json` (preserving other keys) plus a `/tfg` slash command at `~/.qwen/commands/tfg.md`. For recurring runs, enable Qwen Code's experimental cron (`QWEN_CODE_ENABLE_CRON=1`) or use a system cron line.
+- **Cursor / Windsurf / Devin:** `init` writes the MCP config; automation requires platform-native scheduling.
 
 ## Contributing
 
-TFG has been built and tested primarily on **Claude Code**. Making it work well on other harnesses — OpenCode, Cursor, Windsurf, Devin, anything else with MCP support — is the biggest open area for external help. See [CONTRIBUTING.md](CONTRIBUTING.md) for a tour of the code, the specific touch points a harness port needs to hit (`src/platform.js`, `src/init.js`, the session-start hook, and the skill files), and the local testing pattern.
+TFG has been built and tested primarily on **Claude Code**. Making it work well on other harnesses (OpenCode, Cursor, Windsurf, Devin, anything else with MCP support) is the biggest open area for external help. See [CONTRIBUTING.md](CONTRIBUTING.md) for a tour of the code, the specific touch points a harness port needs to hit (`src/platform.js`, `src/init.js`, the session-start hook, and the skill files), and the local testing pattern.
 
 For quick dev setup:
 
@@ -81,4 +82,4 @@ The MCP server entry point is `src/mcp-server.js`. The CLI is `src/cli.js`.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT; see [LICENSE](LICENSE).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "tokens-for-good",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "type": "module",
-  "description": "Donate your spare AI tokens to research nonprofits for Fierce Philanthropy",
+  "description": "Contribute your spare AI tokens to research nonprofits for Fierce Philanthropy",
   "homepage": "https://tokensforgood.ai",
   "repository": {
     "type": "git",

package/pipeline/01-research/PROMPT.md

@@ -4,7 +4,7 @@
 
 You are a social impact research analyst for Fierce Philanthropy. You evaluate nonprofit organizations using Todd Manwaring's Social Impact Evaluation Framework. You are thorough, evidence-driven, and honest about what the data does and does not show.
 
-**v3 note (read this):** In v3 you no longer score your own report. You write the analysis, then fill in an EVIDENCE TABLE with verbatim quotes and real URLs. The score is computed deterministically from that table by code, not by you. Empty rows are fine — they're the honest answer when the evidence doesn't exist. Inventing evidence to fill a row hurts the org and gets your report rejected.
+**v3 note (read this):** In v3 you no longer score your own report. You write the analysis, then fill in an EVIDENCE TABLE with verbatim quotes and real URLs. The score is computed deterministically from that table by code, not by you. Empty rows are fine; they're the honest answer when the evidence doesn't exist. Inventing evidence to fill a row hurts the org and gets your report rejected.
 
 ## Instructions
 
@@ -12,11 +12,11 @@ You are a social impact research analyst for Fierce Philanthropy. You evaluate n
 
 Using web search and web fetch, thoroughly research:
 
-1. **The org's website** — homepage, about page, impact/results pages, annual reports
-2. **Impact evidence** — published data, metrics, program evaluations
-3. **Independent evaluations** — RCTs, quasi-experimental studies (search J-PAL, 3ie, Campbell Collaboration)
-4. **Third-party reviews** — GiveWell, Charity Navigator, GuideStar/Candid, news coverage
-5. **Financial data** — ProPublica Nonprofit Explorer (search by EIN or name), Form 990
+1. **The org's website:** homepage, about page, impact/results pages, annual reports
+2. **Impact evidence:** published data, metrics, program evaluations
+3. **Independent evaluations:** RCTs, quasi-experimental studies (search J-PAL, 3ie, Campbell Collaboration)
+4. **Third-party reviews:** GiveWell, Charity Navigator, GuideStar/Candid, news coverage
+5. **Financial data:** ProPublica Nonprofit Explorer (search by EIN or name), Form 990
 
 **Research rules:**
 - Only include DIRECT results from this organization or independent measurements of it.
@@ -40,20 +40,20 @@ Follow this exact structure:
 
 ---
 
-#### PROMPT 1 — Organization and Social Problem Summary
+#### PROMPT 1; Organization and Social Problem Summary
 
 1. **Social Problem:** (less than 5 words)
 2. **Population:** (who is affected)
 3. **Location:** (where)
 
-#### PROMPT 2 — Top 20 Negative Consequences
+#### PROMPT 2; Top 20 Negative Consequences
 
 | # | Negative Consequence |
 |---|----------------------|
 
 List the top 20 negative consequences of that social problem for that population in that location.
 
-#### PROMPT 3 — Intermediary vs Ultimate Outcome Classification
+#### PROMPT 3; Intermediary vs Ultimate Outcome Classification
 
 Keep all 20 items. Add a column classifying each as Intermediary or Ultimate Outcome.
 
@@ -61,7 +61,7 @@ Keep all 20 items. Add a column classifying each as Intermediary or Ultimate Out
 - **Intermediary:** changes in behavior, action, or resources that result from the intervention but don't yet prove lives improved (e.g., increased income, employment, school enrollment, access to healthcare, consumption)
 - **Ultimate:** changes in condition or life status that directly reflect well-being improvements (e.g., improved health, housing security, quality of life, food security)
 
-**Edge cases — apply these exactly:**
+**Edge cases; apply these exactly:**
 - Getting healthcare = Intermediary. Health actually improving = Ultimate.
 - Income going up = Intermediary. Using that income to improve housing, education, or health = Ultimate.
 - Moving out of poverty = Intermediary. Well-being or quality of life improving because of it = Ultimate.
@@ -72,16 +72,16 @@ Keep all 20 items. Add a column classifying each as Intermediary or Ultimate Out
 
 Sort by Intermediary first, then Ultimate.
 
-#### PROMPT 4 — Positive Results Shared by Organization
+#### PROMPT 4; Positive Results Shared by Organization
 
 Keep the table with all columns. For each of the 20 negative consequences, add a column: does the organization share positive results?
 
 - Start each cell with "Yes.", "Partial.", or "No direct results shared."
 - When Yes or Partial: include SPECIFIC data (percentages, sample sizes, time periods, study names)
 - Only direct results from this organization, not from other orgs or modeling
-- **Citation rules apply** — see section 3 below.
+- **Citation rules apply:** see section 3 below.
 
-#### PROMPT 5 — Counterfactual Results
+#### PROMPT 5; Counterfactual Results
 
 Keep the table with ALL previous columns. For each of the 20 negative consequences, add a column: does the organization share COUNTERFACTUAL results?
 
@@ -91,41 +91,41 @@ Keep the table with ALL previous columns. For each of the 20 negative consequenc
 
 #### SUMMARY REPORT
 
-**Section 1 — Our Recommendation**
+**Section 1; Our Recommendation**
 Write a recommendation (2-4 sentences): lead with stance, state strongest evidence, note caveats if any.
 
-**Section 2 — The Social Problem**
+**Section 2; The Social Problem**
 Frame with specificity ("chronic malnutrition among children under 5 in rural sub-Saharan Africa", not just "poverty"). Include scale and cite prevalence data.
 
-**Section 3 — The Solution**
+**Section 3; The Solution**
 What the organization actually does (not their mission statement). Explain the theory of change: how does activity X lead to outcome Y? Be specific about the intervention.
 
-**Section 4 — Key Outputs**
+**Section 4; Key Outputs**
 Measured activities and direct products with specific numbers. Distinguish outputs (things produced) from outcomes (changes caused).
 
-**Section 5 — Key Intermediate Outcomes**
+**Section 5; Key Intermediate Outcomes**
 Measurable short-to-medium term changes. Note whether data is self-reported or independently verified. Include any counterfactual data found.
 
-**Section 6 — Key Ultimate Outcomes**
+**Section 6; Key Ultimate Outcomes**
 Long-term impact evidence only. This section may be thin. Do not pad it. If no ultimate outcome data exists, say so in one sentence.
 
-**Section 7 — Continual Learning & Adaptation**
+**Section 7; Continual Learning & Adaptation**
 Documented program changes based on evidence. "They adapted" needs specifics: what changed, based on what data, when?
 
 #### EVIDENCE TABLE
 
-The score is computed deterministically by code from this table, not by you. Leave a row blank if you didn't find supporting evidence — a blank row is the honest answer when the org doesn't have that thing. Inventing evidence will lower the org's real score and may get the report rejected.
+The score is computed deterministically by code from this table, not by you. Leave a row blank if you didn't find supporting evidence; a blank row is the honest answer when the org doesn't have that thing. Inventing evidence will lower the org's real score and may get the report rejected.
 
 **What each row asks for** (read this before filling in the table):
 
-- **a1** — A stated condition-level outcome goal (health, income, wellbeing, food security, survival). NOT activity-level ("train X people") and NOT access-level ("expand financial access") — those are intermediary.
-- **a2** — A number or percentage attached to the goal in a1 (e.g. "reduce stunting by 30%"). The same quote as a1 is fine if it already contains the number.
-- **a3** — A target population AND a target year for the goal (e.g. "children under 5 in Ghana by 2030"). Same quote as a1/a2 is fine if it covers both.
-- **b** — An intermediate outcome the org MEASURED, with a number (e.g. "78% of trained CHWs retained at 24 months").
-- **c** — An ultimate outcome the org MEASURED, with a number (e.g. "27% reduction in under-five mortality").
-- **d** — A documented program change the org made BASED ON outcome data. The quote should make both the data and the change concrete (e.g. "In 2022 we moved to blended training after retention dropped to 45%").
-- **e** — An intermediate result measured with a comparison or control group. Name the design (RCT, quasi-experimental, matched comparison). Before/after alone does not count.
-- **f** — An ultimate result measured with a comparison or control group. Same design rules as e.
+- **a1:** A stated condition-level outcome goal (health, income, wellbeing, food security, survival). NOT activity-level ("train X people") and NOT access-level ("expand financial access"); those are intermediary.
+- **a2:** A number or percentage attached to the goal in a1 (e.g. "reduce stunting by 30%"). The same quote as a1 is fine if it already contains the number.
+- **a3:** A target population AND a target year for the goal (e.g. "children under 5 in Ghana by 2030"). Same quote as a1/a2 is fine if it covers both.
+- **b:** An intermediate outcome the org MEASURED, with a number (e.g. "78% of trained CHWs retained at 24 months").
+- **c:** An ultimate outcome the org MEASURED, with a number (e.g. "27% reduction in under-five mortality").
+- **d:** A documented program change the org made BASED ON outcome data. The quote should make both the data and the change concrete (e.g. "In 2022 we moved to blended training after retention dropped to 45%").
+- **e:** An intermediate result measured with a comparison or control group. Name the design (RCT, quasi-experimental, matched comparison). Before/after alone does not count.
+- **f:** An ultimate result measured with a comparison or control group. Same design rules as e.
 
 | Row | Quote (verbatim from the cited page) | Source URL | Source name |
 |-----|--------------------------------------|------------|-------------|
@@ -173,7 +173,7 @@ Run these checks before submitting. They are not optional.
 **Structure:**
 - [ ] All 5 prompt tables present and complete (20 rows each)
 - [ ] All 7 summary sections present with substantive content
-- [ ] EVIDENCE TABLE has all 8 rows (a1, a2, a3, b, c, d, e, f) — values may be blank where no evidence was found
+- [ ] EVIDENCE TABLE has all 8 rows (a1, a2, a3, b, c, d, e, f); values may be blank where no evidence was found
 - [ ] SOURCES section lists every URL cited inline
 
 **Citations:**
@@ -183,7 +183,7 @@ Run these checks before submitting. They are not optional.
 - [ ] EVIDENCE TABLE quotes appear verbatim on the cited pages (substring-checked at submit time)
 
 **Writing style:**
-- [ ] No em dashes (—). Replace with periods, commas, or parentheses.
+- [ ] No em dashes. Replace with periods, commas, semicolons, or parentheses.
 - [ ] No filler adjectives: seamless, robust, comprehensive, innovative, cutting-edge, holistic, game-changing
 - [ ] No AI transitions: "It's worth noting", "Here's the thing", "Let's dive in", "Simply put"
 - [ ] Replace "leverage" with "use", "utilize" with "use"

package/pipeline/02-verify/PROMPT.md

@@ -12,9 +12,9 @@ Read the full research report. Note every inline citation `[Source Name](URL)` a
 
 For each citation, visit the URL using web fetch and verify:
 
-- **URL loads** — Is it a real page (not 404, not a redirect to a homepage)?
-- **Content matches** — Does the page actually say what the report claims? Quote the relevant passage.
-- **Data is accurate** — Do the numbers match?
+- **URL loads:** Is it a real page (not 404, not a redirect to a homepage)?
+- **Content matches:** Does the page actually say what the report claims? Quote the relevant passage.
+- **Data is accurate:** Do the numbers match?
 
 Record each check:
 
@@ -22,11 +22,11 @@ Record each check:
 |---|----------|-----------|---------------|-------|
 
 Status values:
-- **VALID** — URL loads and content matches
-- **BROKEN** — 404 or page doesn't load
-- **MISMATCH** — URL loads but doesn't support the claim
-- **PARTIAL** — Some claims match, some don't
-- **UNVERIFIABLE** — Paywalled or content not accessible
+- **VALID:** URL loads and content matches
+- **BROKEN:** 404 or page doesn't load
+- **MISMATCH:** URL loads but doesn't support the claim
+- **PARTIAL:** Some claims match, some don't
+- **UNVERIFIABLE:** Paywalled or content not accessible
 
 ### 3. Re-attribute Mismatches
 

package/pipeline/03-humanize/PROMPT.md

@@ -1,4 +1,4 @@
-# Step 3: Humanize — Instructions
+# Step 3: Humanize; Instructions
 
 ## Inputs
 
@@ -23,7 +23,7 @@ The AI decontamination passes below are your checklist.
 Work through these checks in order. For each issue found, fix it and log the change.
 
 #### Pass 1: Em Dash Removal
-- Search for every `—` (em dash) in the content
+- Search for every `, ` (em dash) in the content
 - Replace each with a period (two sentences), comma, or parentheses
 - Two short sentences almost always beat one em-dashed sentence
 - Log count: "Removed X em dashes"
@@ -47,7 +47,7 @@ Work through these checks in order. For each issue found, fix it and log the cha
 
 #### Pass 5: AI Pattern Scan
 Check for and fix:
-- [ ] "[Statement]. Not because X — because Y." dramatic structure
+- [ ] "[Statement]. Not because X; because Y." dramatic structure
 - [ ] "Not just X, but Y" emphasis pattern
 - [ ] "Whether X or Y" parallel constructions
 - [ ] "From X to Y" range statements

package/pipeline/04-validate/PROMPT.md

@@ -2,16 +2,16 @@
 
 ## Your Role
 
-You are a validator — an independent fourth contributor who sits between the two researchers and the consolidator. Two researchers independently researched the same organization; before their reports are merged and scored, your job is to catch **unsupported or fabricated evidence** and hand back cleaned-up ("validated") versions of both reports.
+You are a validator; an independent fourth contributor who sits between the two researchers and the consolidator. Two researchers independently researched the same organization; before their reports are merged and scored, your job is to catch **unsupported or fabricated evidence** and hand back cleaned-up ("validated") versions of both reports.
 
 You do **no web research and no fetching**. The server already fetched every page the researchers cited and gives you the cached text. You validate using ONLY that cached text. This is deliberate: it makes validation cheap and possible even on a local model with no scraping budget.
 
 ## Why this stage exists
 
-A report's score comes entirely from its EVIDENCE TABLE — eight rows, each a quote + a source URL. The most dangerous failure isn't a thin report; it's a confident one citing a quote that **isn't actually on the page**, or a page that **doesn't exist**. That evidence would score real points it didn't earn. The server already runs a deterministic check (does the quote literally appear on the cached page?), and you'll see its verdicts. Your job is the judgment the deterministic check can't do:
+A report's score comes entirely from its EVIDENCE TABLE; eight rows, each a quote + a source URL. The most dangerous failure isn't a thin report; it's a confident one citing a quote that **isn't actually on the page**, or a page that **doesn't exist**. That evidence would score real points it didn't earn. The server already runs a deterministic check (does the quote literally appear on the cached page?), and you'll see its verdicts. Your job is the judgment the deterministic check can't do:
 
 - Does the quote, even if it appears on the page, actually **support the row's criterion**? (e.g. an "ultimate outcome" row quoting an *output* count, or a counterfactual row quoting a result instead of a study design.)
-- Is the quote **cherry-picked** — technically present but contradicted or heavily qualified elsewhere on the same page?
+- Is the quote **cherry-picked:** technically present but contradicted or heavily qualified elsewhere on the same page?
 - Do the two reports **contradict each other** on the same row in a way that means at least one is wrong?
 
 ## Your Inputs
@@ -20,9 +20,9 @@ The `/tfg-validate` skill (or the `get_next_validation` MCP tool) returns:
 - Your validation **claim_id** (a UUID)
 - The **organization** (name, slug, url)
 - Two **source_reports** (markdown), each with its EVIDENCE TABLE and each with the server's deterministic **citation_verdicts** (per row: `verified` / `fabricated` / `unverifiable`)
-- **cached_pages**: `{url, fetch_status, http_status, text}` for every URL cited across both reports. `fetch_status` is `ok` (text present), `unreachable` (couldn't load — includes 404s), `non_text` (a PDF or similar the server can't read), or `missing` (wasn't cached).
+- **cached_pages**: `{url, fetch_status, http_status, text}` for every URL cited across both reports. `fetch_status` is `ok` (text present), `unreachable` (couldn't load; includes 404s), `non_text` (a PDF or similar the server can't read), or `missing` (wasn't cached).
 
-## Your Task — per row, per report
+## Your Task; per row, per report
 
 Start from the server's verdicts, then apply judgment:
 
@@ -33,26 +33,26 @@ Start from the server's verdicts, then apply judgment:
 
 **The one hard rule: you may only SUBTRACT rows or CORRECT a quote to match its cited page. You may NEVER ADD new evidence, new rows, or new URLs.** Adding evidence is the researcher's job, not yours. A validated report is always a subset (or verbatim-corrected version) of the original.
 
-This is **enforced by the server**: your submission is rejected (422) if it introduces a URL the original didn't cite, OR if any EVIDENCE TABLE row's quote is not actually found on its cited page. So when you correct a quote, copy it **verbatim from the cached page text** — don't paraphrase. If you can't find supporting text on the page, remove the row instead of rewriting it. (Rows whose page is a PDF/blocked/un-readable are `unverifiable` and pass through — you don't need to fix those.)
+This is **enforced by the server**: your submission is rejected (422) if it introduces a URL the original didn't cite, OR if any EVIDENCE TABLE row's quote is not actually found on its cited page. So when you correct a quote, copy it **verbatim from the cached page text:** don't paraphrase. If you can't find supporting text on the page, remove the row instead of rewriting it. (Rows whose page is a PDF/blocked/un-readable are `unverifiable` and pass through; you don't need to fix those.)
 
-If a report was already clean, return it unchanged (or simply omit it from your submission — omitted reports keep their original).
+If a report was already clean, return it unchanged (or simply omit it from your submission; omitted reports keep their original).
 
 ## Submit
 
 Call `submit_validation` with:
 - `claim_id`: your validation claim ID
-- `validated_reports`: an array of `{claim_id, report_markdown}` — one entry per report you changed, where `claim_id` is that **source report's** claim_id and `report_markdown` is its full corrected markdown. Omit reports you didn't change.
-- `validation_notes`: a short summary of what you cut and why (e.g. "rc1: dropped row f — the RCT quote was a result, not a design; dropped row c — quote not found on the cited page").
+- `validated_reports`: an array of `{claim_id, report_markdown}`; one entry per report you changed, where `claim_id` is that **source report's** claim_id and `report_markdown` is its full corrected markdown. Omit reports you didn't change.
+- `validation_notes`: a short summary of what you cut and why (e.g. "rc1: dropped row f; the RCT quote was a result, not a design; dropped row c; quote not found on the cited page").
 - `estimated_tokens`: honest estimate (validation is read-heavy but no web work).
 
-If **both reports are already clean** (nothing to remove or correct), submit `validated_reports` as an **empty array** with a note saying so — the round then proceeds to consolidation unchanged. Don't resubmit a report you didn't change.
+If **both reports are already clean** (nothing to remove or correct), submit `validated_reports` as an **empty array** with a note saying so; the round then proceeds to consolidation unchanged. Don't resubmit a report you didn't change.
 
-Each validated report must still be a structurally valid v3 report (all PROMPT/Section headings + an EVIDENCE TABLE + SOURCES). You're pruning evidence, not dismantling the document — leave the prose and structure intact; just remove or correct the offending EVIDENCE TABLE rows (and you may drop a now-unused entry from SOURCES). **Pruning is allowed to drop a report below the usual fresh-submit floors** (≥5 citations, ≥3 domains, ≥1500 words) — those aren't enforced on a validation, because removing fake evidence legitimately shrinks the report.
+Each validated report must still be a structurally valid v3 report (all PROMPT/Section headings + an EVIDENCE TABLE + SOURCES). You're pruning evidence, not dismantling the document; leave the prose and structure intact; just remove or correct the offending EVIDENCE TABLE rows (and you may drop a now-unused entry from SOURCES). **Pruning is allowed to drop a report below the usual fresh-submit floors** (≥5 citations, ≥3 domains, ≥1500 words); those aren't enforced on a validation, because removing fake evidence legitimately shrinks the report.
 
 ## What not to do
 
 - **Don't add evidence.** Ever. Subtract or correct-to-source only.
-- **Don't fetch anything.** Use the cached_pages text. If a page is `missing`/`unreachable`, treat the citation as unverifiable — don't go find it yourself.
+- **Don't fetch anything.** Use the cached_pages text. If a page is `missing`/`unreachable`, treat the citation as unverifiable; don't go find it yourself.
 - **Don't punish honest blanks or real PDFs.** A blank row is fine. An `unverifiable` PDF from a credible source can stay.
 - **Don't rewrite prose.** Your edits are confined to the EVIDENCE TABLE (and removing orphaned SOURCES lines).
-- **Don't second-guess the deterministic `fabricated` verdict.** If the quote isn't on the page, it goes — the page text is right there for you to confirm.
+- **Don't second-guess the deterministic `fabricated` verdict.** If the quote isn't on the page, it goes; the page text is right there for you to confirm.

package/pipeline/05-consolidate/PROMPT.md

@@ -2,7 +2,7 @@
 
 ## Your Role
 
-You are a consolidator. Two researchers independently researched the same organization without seeing each other's work. Your job is to merge their reports into a single canonical report that the deterministic scorer will score. The score comes from the merged EVIDENCE TABLE you produce — not from any of the prose.
+You are a consolidator. Two researchers independently researched the same organization without seeing each other's work. Your job is to merge their reports into a single canonical report that the deterministic scorer will score. The score comes from the merged EVIDENCE TABLE you produce; not from any of the prose.
 
 You do not do new web research. You work entirely from the two source reports.
 
@@ -13,7 +13,7 @@ The `/tfg-consolidate` skill (or the `get_next_consolidation` MCP tool) returns:
 - The **organization** (name, slug, url)
 - Two **source_reports** (markdown), each ending in an EVIDENCE TABLE
 
-## Your Task — the EVIDENCE TABLE
+## Your Task; the EVIDENCE TABLE
 
 For each row (a1, a2, a3, b, c, d, e, f), compare the two source reports' quotes and decide:
 
@@ -29,11 +29,11 @@ If you flag **≥3 rows** as disagreements, the server automatically spawns a th
 
 ## The Merged Report Structure
 
-Produce a single v3-shaped report. For PROMPT 1–5 and Section 1–7, take the stronger version from one of the two researchers — you are not rewriting. Your real work is the EVIDENCE TABLE.
+Produce a single v3-shaped report. For PROMPT 1–5 and Section 1–7, take the stronger version from one of the two researchers; you are not rewriting. Your real work is the EVIDENCE TABLE.
 
 The report must contain:
 - `# [Org Name] - Fierce Philanthropy Research Report` header
-- `**Methodology:** Todd Manwaring's Social Impact Evaluation Framework (v3 — consolidated)`
+- `**Methodology:** Todd Manwaring's Social Impact Evaluation Framework (v3; consolidated)`
 - PROMPT 1, 2, 3, 4, 5 (copy/paste the stronger versions)
 - Sections 1 through 7 (copy/paste the stronger versions)
 - A single merged **EVIDENCE TABLE** (your consolidation work, 8 rows: a1–a3, b, c, d, e, f)
@@ -54,6 +54,6 @@ Call `submit_report` with:
 
 - Don't invent evidence. If neither researcher cited it, it doesn't go in.
 - Don't rewrite the prose extensively. This is consolidation, not authorship.
-- Don't paper over real disagreements. If they materially disagree, flag the row — that's the system's calibration signal.
+- Don't paper over real disagreements. If they materially disagree, flag the row; that's the system's calibration signal.
 - Don't use `example.com` or placeholder URLs.
 - Don't omit `disagreement_rows`. An empty array is acceptable, but be explicit.

package/skills/tfg-consolidate.md

@@ -9,18 +9,18 @@ The user wants to consolidate a pair of independent research reports into one me
 
 1. **Call `get_next_consolidation` on the TFG MCP.** It returns:
    - the org being consolidated,
-   - your consolidation `claim_id` (a UUID — this is what you'll submit against, NOT a researcher's claim ID),
+   - your consolidation `claim_id` (a UUID; this is what you'll submit against, NOT a researcher's claim ID),
    - two `source_reports` (each a full v3 research report ending in an EVIDENCE TABLE),
    - the full consolidation methodology inline.
 
-   If nothing is assigned, the tool says so — tell the user and stop here.
+   If nothing is assigned, the tool says so; tell the user and stop here.
 
 2. **Read both source reports closely.** They were produced independently and may differ in evidence quality, citation rigor, and overall structure.
 
 3. **Merge the EVIDENCE TABLE row by row** (a1, a2, a3, b, c, d, e, f). For each row:
    - If both researchers filled the row with compatible evidence, take the stronger quote (longer, more specific, cites the exact page rather than an overview).
    - If only one filled the row, use that one's quote.
-   - If both left it blank, leave it blank — that is an honest signal that the evidence doesn't exist.
+   - If both left it blank, leave it blank; that is an honest signal that the evidence doesn't exist.
    - If they materially disagree (different URLs, different evidence on the same row), take the better-supported one using this hierarchy:
      1. RCT > quasi-experimental > self-reported survey > anecdote
      2. Third-party citation > org-self-cite
@@ -28,22 +28,22 @@ The user wants to consolidate a pair of independent research reports into one me
 
      AND record the row key in your `disagreement_rows` list.
 
-4. **Assemble one merged v3 report**, with the same structure as a fresh v3 report (PROMPT 1-5, Sections 1-7, the merged EVIDENCE TABLE, SOURCES). For the prose sections, take the stronger version from one of the two researchers verbatim — you are not rewriting. Your real work is the EVIDENCE TABLE.
+4. **Assemble one merged v3 report**, with the same structure as a fresh v3 report (PROMPT 1-5, Sections 1-7, the merged EVIDENCE TABLE, SOURCES). For the prose sections, take the stronger version from one of the two researchers verbatim; you are not rewriting. Your real work is the EVIDENCE TABLE.
 
 5. **Call `submit_report`** with:
    - `claim_id`: your consolidation claim ID from step 1
    - `report_markdown`: the merged report
-   - `estimated_tokens`: an honest estimate (consolidations are mostly read + reorder — much lighter than fresh research)
+   - `estimated_tokens`: an honest estimate (consolidations are mostly read + reorder; much lighter than fresh research)
    - `model_used`: e.g. `"claude-consolidator"`
    - `disagreement_rows`: array of row keys you flagged (e.g. `["a1", "e"]`). Pass an empty array if none.
 
-6. **Tell the user the org name and your score impression** (e.g. "Merged report for X submitted; 2 disagreements flagged on a1 and e — the system may auto-trigger a 3rd researcher.").
+6. **Tell the user the org name and your score impression** (e.g. "Merged report for X submitted; 2 disagreements flagged on a1 and e; the system may auto-trigger a 3rd researcher.").
 
 ## What not to do
 
 - Don't invent evidence. If neither researcher cited it, it doesn't enter the merged report.
 - Don't rewrite the prose extensively. Pick the stronger researcher's version verbatim.
-- Don't paper over real disagreements to "keep the count down" — flagging ≥3 rows auto-triggers a 3rd researcher, which is the system's calibration loop. That's a feature, not a failure.
+- Don't paper over real disagreements to "keep the count down"; flagging ≥3 rows auto-triggers a 3rd researcher, which is the system's calibration loop. That's a feature, not a failure.
 - Don't include `example.com` or placeholder URLs (the validator rejects them).
 - Don't omit `disagreement_rows`. An empty array is fine, but be explicit.
 

package/skills/tfg-schedule.md

@@ -1,6 +1,6 @@
 ---
 name: tfg-schedule
-description: Set up automated Tokens for Good research on a schedule (daily — with a chosen number of runs per day — or weekly). Use this when the user wants their AI to donate spare tokens to nonprofit research without manual prompting — it wires up a recurring /schedule agent in one shot instead of making them run /schedule, pick a schedule, and paste a prompt by hand.
+description: Set up automated Tokens for Good research on a schedule (daily, with a chosen number of runs per day, or weekly). Use this when the user wants their AI to contribute spare tokens to nonprofit research without manual prompting; it wires up a recurring /schedule agent in one shot instead of making them run /schedule, pick a schedule, and paste a prompt by hand.
 ---
 
 The user wants to automate Tokens for Good research on a recurring schedule.
@@ -13,23 +13,23 @@ Work out the cadence before doing anything else:
 - Otherwise ask the user, offering: **Daily** (recommended), **Weekly** (light touch), or **Skip for now**.
 - For a daily cadence with no per-day count set, ask **"How many times per day? (1–15)"**. Claude Code caps how many scheduled runs you get per day, so keep it at 15 or below. Default to 1 if the user has no preference.
 
-Describe cadence by frequency only — keep token costs and dollar amounts out of every question and confirmation.
+Describe cadence by frequency only; keep token costs and dollar amounts out of every question and confirmation.
 
 ## 2. Wire it up
 
 1. **Call the TFG MCP `setup_automation` tool** with `frequency` (`daily` or `weekly`) and, for daily, `runs_per_day`. It returns the full `/schedule` setup text: a Step 2 schedule line containing a cron expression, and a research prompt scoped to the user's API key.
 
-2. **Extract the research prompt** — the block delimited by `---` lines. Pass it through verbatim; don't paraphrase.
+2. **Extract the research prompt:** the block delimited by `---` lines. Pass it through verbatim; don't paraphrase.
 
 3. **Invoke the `/schedule` skill** to create the recurring trigger:
    - Schedule: the cron expression from `setup_automation`'s Step 2 line.
    - Task description: the verbatim block from step 2.
 
-4. **Wait for `/schedule` to confirm success.** If it fails or the user cancels, stop here and tell the user — do NOT call `mark_setup_complete`.
+4. **Wait for `/schedule` to confirm success.** If it fails or the user cancels, stop here and tell the user; do NOT call `mark_setup_complete`.
 
 5. **On success, call the TFG MCP `mark_setup_complete` tool.** This flips the user's local state so the SessionStart hook stops nudging.
 
-6. **Confirm to the user** in one or two sentences, and reassure them it runs unattended, e.g. *"Scheduled ✓ — your spare tokens will research a nonprofit on that cadence from here on. It runs on Anthropic's cloud, so your computer can be off and Claude Code doesn't need to be open. Change it anytime with /schedule."*
+6. **Confirm to the user** in one or two sentences, and reassure them it runs unattended, e.g. *"Scheduled ✓; your spare tokens will research a nonprofit on that cadence from here on. It runs on Anthropic's cloud, so your computer can be off and Claude Code doesn't need to be open. Change it anytime with /schedule."*
 
 ## If something goes wrong
 
@@ -40,6 +40,6 @@ Describe cadence by frequency only — keep token costs and dollar amounts out o
 ## What not to do
 
 - Keep token costs and dollar figures out of every question and confirmation.
-- If the user already picked a cadence at install, don't re-ask it — only ask for the per-day count when it's missing for a daily cadence.
+- If the user already picked a cadence at install, don't re-ask it; only ask for the per-day count when it's missing for a daily cadence.
 - Don't print the raw research prompt to the user; it's verbose and already flows through /schedule.
-- Don't assume the user knows what /schedule is. If they ask, briefly explain: "It's Anthropic's scheduled-task feature — runs your prompt on their cloud on a cron schedule, no need to keep your laptop on."
+- Don't assume the user knows what /schedule is. If they ask, briefly explain: "It's Anthropic's scheduled-task feature; runs your prompt on their cloud on a cron schedule, no need to keep your laptop on."

package/skills/tfg-validate.md

@@ -1,22 +1,22 @@
 ---
 name: tfg-validate
-description: Validate two independent v3 research reports by pruning unsupported or fabricated EVIDENCE TABLE rows, using ONLY the cached page text the server provides (no web fetches). Use this when the user has been assigned a validation, OR to check whether they have one pending. Ideal for local models — it does zero scraping.
+description: Validate two independent v3 research reports by pruning unsupported or fabricated EVIDENCE TABLE rows, using ONLY the cached page text the server provides (no web fetches). Use this when the user has been assigned a validation, OR to check whether they have one pending. Ideal for local models; it does zero scraping.
 ---
 
 The user wants to validate a pair of independent research reports before they're merged and scored. Under v3 dual-research, every org is researched by two contributors; you (an independent fourth contributor) catch unsupported or fabricated evidence and hand back cleaned-up versions of both reports. The consolidator then merges already-validated tables.
 
-You do **no web research and no fetching**. The server already fetched every cited page and gives you the cached text. This is deliberate — validation is cheap and works on a local model with no scraping budget.
+You do **no web research and no fetching**. The server already fetched every cited page and gives you the cached text. This is deliberate; validation is cheap and works on a local model with no scraping budget.
 
 ## What to do
 
 1. **Call `get_next_validation` on the TFG MCP.** It returns:
    - the org being validated,
-   - your validation `claim_id` (a UUID — submit against this one),
+   - your validation `claim_id` (a UUID; submit against this one),
    - two `source_reports` (each a full v3 report with its EVIDENCE TABLE) plus the server's deterministic `citation_verdicts` per row (`verified` / `fabricated` / `unverifiable`),
    - `cached_pages`: the text of every URL cited across both reports, with a `fetch_status` (`ok` / `unreachable` / `non_text` / `missing`),
    - the full validation methodology inline.
 
-   If nothing is assigned, the tool says so — tell the user and stop here.
+   If nothing is assigned, the tool says so; tell the user and stop here.
 
 2. **For each report, go row by row** (a1, a2, a3, b, c, d, e, f). Start from the server's verdict, then apply judgment using the cached page text:
    - **`fabricated`** (quote not on the page, or URL 404s) → **remove the row** (blank quote/URL/name).
@@ -27,7 +27,7 @@ You do **no web research and no fetching**. The server already fetched every cit
 
 4. **Call `submit_validation`** with:
    - `claim_id`: your validation claim ID from step 1
-   - `validated_reports`: an array of `{ claim_id, report_markdown }` — one entry per report you changed, where `claim_id` is that source report's claim_id and `report_markdown` is its full corrected markdown. Omit reports you didn't change. **If both reports are clean, pass an empty array `[]`** — the round proceeds to consolidation unchanged. Pruning is allowed to drop a report below the usual ≥5-citation / ≥3-domain / ≥1500-word floors; those aren't enforced on a validation.
+   - `validated_reports`: an array of `{ claim_id, report_markdown }`; one entry per report you changed, where `claim_id` is that source report's claim_id and `report_markdown` is its full corrected markdown. Omit reports you didn't change. **If both reports are clean, pass an empty array `[]`:** the round proceeds to consolidation unchanged. Pruning is allowed to drop a report below the usual ≥5-citation / ≥3-domain / ≥1500-word floors; those aren't enforced on a validation.
    - `validation_notes`: a short summary of what you cut/corrected and why
    - `estimated_tokens`: an honest estimate (validation is read-heavy, no web work)
 
@@ -36,10 +36,10 @@ You do **no web research and no fetching**. The server already fetched every cit
 ## What not to do
 
 - **Don't add evidence.** Ever. Subtract or correct-to-source only.
-- **Don't fetch anything.** Use the `cached_pages` text. A `missing`/`unreachable` page means the citation is unverifiable — don't go find it yourself.
+- **Don't fetch anything.** Use the `cached_pages` text. A `missing`/`unreachable` page means the citation is unverifiable; don't go find it yourself.
 - **Don't punish honest blanks or real PDFs.** A blank row is fine; an `unverifiable` PDF from a credible source can stay.
 - **Don't rewrite prose.** Your edits are confined to the EVIDENCE TABLE (and removing now-orphaned SOURCES lines).
-- **Don't second-guess a `fabricated` verdict** — the page text is right there; if the quote isn't in it, the row goes.
+- **Don't second-guess a `fabricated` verdict:** the page text is right there; if the quote isn't in it, the row goes.
 
 ## If something goes wrong
 

package/skills/tfg.md

@@ -1,21 +1,21 @@
 ---
 name: tfg
-description: Do one Tokens for Good research task end-to-end — claim an org, research it using the provided methodology, and submit the report. Use when the user wants to contribute once (not set up automation). Takes about 5 minutes per org.
+description: Do one Tokens for Good research task end-to-end; claim an org, research it using the provided methodology, and submit the report. Use when the user wants to contribute once (not set up automation). Takes about 5 minutes per org.
 ---
 
 The user wants to complete one Tokens for Good research cycle.
 
 ## What to do
 
-0. **First, check for pending consolidations.** Call `get_next_consolidation`. If it returns an assignment, stop here and hand off to the `/tfg-consolidate` skill — a pending consolidation blocks a whole round and takes priority over starting new research. If it returns "no consolidations assigned," continue to step 1.
+0. **First, check for pending consolidations.** Call `get_next_consolidation`. If it returns an assignment, stop here and hand off to the `/tfg-consolidate` skill; a pending consolidation blocks a whole round and takes priority over starting new research. If it returns "no consolidations assigned," continue to step 1.
 
 1. **Call `claim_org`** on the TFG MCP. It reserves an org for you and returns a claim ID.
 
-2. **Call `get_methodology`** with `step="research"` and follow those instructions closely — they specify the web searches, EVIDENCE TABLE structure, and output shape.
+2. **Call `get_methodology`** with `step="research"` and follow those instructions closely; they specify the web searches, EVIDENCE TABLE structure, and output shape.
 
 3. **Call `get_methodology`** with `step="verify"` after drafting, and check every citation URL.
 
-4. **Call `get_methodology`** with `step="humanize"` for the final voice pass (remove em dashes, banned words, add analyst voice). Then call `submit_report` with the finished markdown, the model you used, and your honest `estimated_tokens` count (sum of web searches × 1K + web fetches × 2–5K + your output words × 4 + ~10K overhead). `submit_report` automatically flips `first_setup_complete` for one-off users — no separate call needed.
+4. **Call `get_methodology`** with `step="humanize"` for the final voice pass (remove em dashes, banned words, add analyst voice). Then call `submit_report` with the finished markdown, the model you used, and your honest `estimated_tokens` count (sum of web searches × 1K + web fetches × 2–5K + your output words × 4 + ~10K overhead). `submit_report` automatically flips `first_setup_complete` for one-off users; no separate call needed.
 
 5. **Confirm to the user** with the acceptance stats the submit returns. If they're on the one-off flow and might convert to scheduled, mention they can run `/tfg-schedule daily` anytime to automate future runs.
 
@@ -28,5 +28,5 @@ The user wants to complete one Tokens for Good research cycle.
 ## What not to do
 
 - Don't skip verification. Hallucinated citations get reports rejected during consolidation and review.
-- Don't exceed 2,500 words — the methodology cares about density, not length.
+- Don't exceed 2,500 words; the methodology cares about density, not length.
 - Don't submit without `estimated_tokens`. The MCP tool will reject it.

package/src/api-client.js

@@ -42,7 +42,7 @@ export class ApiClient {
 
     const response = await fetch(url, options);
     // Tolerate empty bodies (204 No Content, used by /research/consolidate/next
-    // when nothing is assigned to you) — response.json() throws on empty text.
+    // when nothing is assigned to you); response.json() throws on empty text.
     const text = await response.text();
     const data = text ? JSON.parse(text) : null;
 

package/src/cli.js

@@ -9,7 +9,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 
 const HELP = `tokens-for-good v${pkg.version}
-Donate your spare AI tokens to research nonprofits for Fierce Philanthropy.
+Contribute your spare AI tokens to research nonprofits for Fierce Philanthropy.
 
 Usage:
   npx tokens-for-good <command> [options]

package/src/init.js

@@ -16,9 +16,9 @@ const PKG_ROOT = join(__dirname, '..');
 const IS_WINDOWS = process.platform === 'win32';
 
 const FREQUENCY_CHOICES = [
-  { title: 'Daily  — recommended; pick how many runs per day next',        value: 'daily'   },
-  { title: 'Weekly — light touch',                                         value: 'weekly'  },
-  { title: "One-off — I'll run research manually when I feel like it",     value: 'one_off' },
+  { title: 'Daily (recommended); pick how many runs per day next',        value: 'daily'   },
+  { title: 'Weekly; light touch',                                         value: 'weekly'  },
+  { title: "One-off; I'll run research manually when I feel like it",     value: 'one_off' },
 ];
 
 const PLATFORM_CHOICES = [
@@ -36,7 +36,7 @@ const onCancel = () => {
 };
 
 export async function runInit() {
-  console.log('\n✨ Tokens for Good — one-time setup\n');
+  console.log('\n✨ Tokens for Good; one-time setup\n');
 
   // Idempotency: offer to reconfigure if already set up
   const existing = loadState();
@@ -72,7 +72,7 @@ export async function runInit() {
     initial: detectedIdx,
   }, { onCancel });
 
-  // Step 3: Frequency (mandatory choice — this is the whole point of init)
+  // Step 3: Frequency (mandatory choice; this is the whole point of init)
   const { choice } = await prompts({
     type: 'select',
     name: 'choice',
@@ -81,7 +81,7 @@ export async function runInit() {
     initial: 0,
   }, { onCancel });
 
-  // Step 3b: Daily cadence — how many runs per day. Claude Code caps the
+  // Step 3b: Daily cadence; how many runs per day. Claude Code caps the
   // number of scheduled runs per day, so we ask for a count (1-15).
   let runs_per_day = null;
   if (choice === 'daily') {
@@ -280,13 +280,13 @@ function writeSessionStartHook() {
 }
 
 // Claude Code runs SessionStart hooks with a stripped PATH that often omits
-// the node/npx bin dir — C:\Program Files\nodejs on Windows, or the nvm/
-// homebrew bin when Claude Code is launched from the macOS Dock/Finder — so a
+// the node/npx bin dir; C:\Program Files\nodejs on Windows, or the nvm/
+// homebrew bin when Claude Code is launched from the macOS Dock/Finder; so a
 // bare `npx` lookup fails and the session shows a "hook error". Resolve the
 // absolute npx path at init time (full PATH available) and bake it in.
 //
-// `2>/dev/null || true` makes the hook non-fatal: this is an optional donation
-// tool, so a missing npx, offline registry, or any other hiccup must never
+// `2>/dev/null || true` makes the hook non-fatal: this is an optional
+// contribution tool, so a missing npx, offline registry, or other hiccup must never
 // disrupt the user's session. Hooks run under bash/sh on every platform (Git
 // Bash on Windows), so this syntax is portable.
 function hookCommand() {
@@ -301,7 +301,7 @@ function resolveNpxPath() {
   }
 
   // macOS / Linux: prefer `which npx`, then npx alongside the running node
-  // binary, then a bare `npx` fallback (relies on PATH — last resort).
+  // binary, then a bare `npx` fallback (relies on PATH; last resort).
   try {
     const r = spawnSync('which', ['npx'], { encoding: 'utf-8' });
     if (r.status === 0) {
@@ -321,7 +321,7 @@ function resolveNpxPath() {
 }
 
 function resolveWindowsNpxPath() {
-  // First try `where npx.cmd` — most reliable when PATH is correct.
+  // First try `where npx.cmd`; most reliable when PATH is correct.
   try {
     const r = spawnSync('where', ['npx.cmd'], { encoding: 'utf-8' });
     if (r.status === 0) {
@@ -334,7 +334,7 @@ function resolveWindowsNpxPath() {
   const alongside = join(dirname(process.execPath), 'npx.cmd');
   if (existsSync(alongside)) return alongside;
 
-  // Last-resort guess — user's hook may need manual edit if this is wrong.
+  // Last-resort guess; user's hook may need manual edit if this is wrong.
   return 'C:\\Program Files\\nodejs\\npx.cmd';
 }
 
@@ -361,7 +361,7 @@ function printClosingGuidance(platform, flow, freq, runsPerDay = 1) {
   const cadence = freq === 'daily' && runsPerDay > 1 ? `daily (${runsPerDay}× per day)` : freq;
   if (platform === 'claude-code') {
     if (flow === 'scheduled') {
-      console.log(`Next: open Claude Code and send any message — even "hi".`);
+      console.log(`Next: open Claude Code and send any message; even "hi".`);
       console.log(`On that first message Claude sets up /schedule at ${cadence} cadence and`);
       console.log(`confirms with "Scheduled ✓". Prefer to be explicit? Just run /tfg-schedule.`);
       console.log('');
@@ -369,13 +369,13 @@ function printClosingGuidance(platform, flow, freq, runsPerDay = 1) {
       console.log(`runs setup hooks after your first message, so type something to kick it off.`);
       console.log('');
       console.log('');
-      console.log(`Once it's scheduled, runs happen on Anthropic's cloud — your computer can be`);
+      console.log(`Once it's scheduled, runs happen on Anthropic's cloud; your computer can be`);
       console.log(`off and Claude Code doesn't need to be open. It just runs on its own from here.`);
       console.log('');
       console.log(`Verify it worked: run /schedule in Claude Code to see your recurring task,`);
       console.log(`or check for the "Auto-contributing" badge on your dashboard.`);
     } else {
-      console.log(`Next: open Claude Code and send any message — even "hi" — and Claude will`);
+      console.log(`Next: open Claude Code and send any message; even "hi"; and Claude will`);
       console.log(`offer to research your first org. Prefer to be explicit? Just run /tfg.`);
       console.log('');
       console.log(`Heads up: nothing happens the instant the window opens. Claude Code only`);

package/src/mcp-server.js

@@ -24,7 +24,7 @@ Tell the user to run this in their terminal (not here in the chat), then restart
 The init command asks them to choose a contribution cadence (daily / weekly / one-off) and wires up everything else automatically. It takes about 30 seconds.`;
 
 // Gate: only fires for genuinely cold installs where state.json is missing
-// entirely. Existing users — including those on the pre-0.4.0 schema — pass
+// entirely. Existing users; including those on the pre-0.4.0 schema; pass
 // through untouched. Init writes state.json on first successful completion,
 // so after that this never fires again.
 function notInitialized() {
@@ -61,16 +61,16 @@ The command walks them through everything in under a minute:
 3. Pick a cadence: **daily** (recommended; choose how many runs per day), weekly, or one-off
 4. Confirm
 
-init writes everything — MCP config, SessionStart hook, /tfg and /tfg-schedule skills, and their recorded preference — in one shot. The first session after init runs their chosen flow automatically.
+init writes everything (MCP config, SessionStart hook, /tfg and /tfg-schedule skills, and their recorded preference) in one shot. The first session after init runs their chosen flow automatically.
 
-**What is Tokens for Good?** A way for developers to donate their spare AI subscription tokens to research nonprofit organizations for Fierce Philanthropy's social impact directory. Each org takes about 5 minutes. Contributors get credit on a public leaderboard.`;
+**What is Tokens for Good?** A way for developers to contribute their spare AI subscription tokens to research nonprofit organizations for Fierce Philanthropy's social impact directory. Each org takes about 5 minutes. Contributors get credit on a public leaderboard.`;
 
 // --- Resources ---
 
 server.resource('about', 'tokens-for-good://about', 'text/plain', async () => ({
   contents: [{
     uri: 'tokens-for-good://about',
-    text: `Tokens for Good - Donate Your Spare AI Tokens to Research Nonprofits
+    text: `Tokens for Good - Contribute Your Spare AI Tokens to Research Nonprofits
 
 What: An MCP server that lets AI coding tool users (Claude Code, Opencode, Cursor, Windsurf, Devin) contribute their spare subscription tokens to research nonprofit organizations for Fierce Philanthropy's social impact directory.
 
@@ -87,7 +87,7 @@ Research pipeline (per org, all done by your AI):
 - Research the org using web search + web fetch, following the v3 EVIDENCE TABLE methodology
 - Fill in an EVIDENCE TABLE (8 rows of verbatim quotes + real URLs); leave blanks honestly when the evidence doesn't exist
 - The server (not you) computes the score deterministically from the merged consolidator output, out of 120
-- Real URLs only — placeholder citations (example.com) are auto-rejected
+- Real URLs only; placeholder citations (example.com) are auto-rejected
 
 Contributor tiers:
 - New: first 5 orgs, easy orgs only
@@ -112,10 +112,10 @@ server.tool('claim_org', 'Claim the next available nonprofit org to research.',
   try {
     const result = await client.claimOrg(plat || platform);
     return {
-      content: [{ type: 'text', text: `Claimed: ${result.org.name} (${result.org.url})\nclaim_id: ${result.claim_id}\nexpires: ${result.expires_at}\nNext: get_methodology step="research", then submit_report.` }],
+      content: [{ type: 'text', text: `Claimed: ${result.org.name} (${result.org.url})\nclaim_id: ${result.claim_id}\nexpires: ${result.expires_at}\nNext: get_methodology step="research" to research, then step="verify" and step="humanize" to check citations and clean the voice, then submit_report. (The /tfg skill walks all four.)` }],
     };
   } catch (err) {
-    // 409 means you already have an active claim — usually an auto-assigned
+    // 409 means you already have an active claim; usually an auto-assigned
     // 3rd-researcher slot you were handed without asking. Surface the existing
     // org + claim_id so the agent can continue the assigned task instead of
     // bouncing off "you have a claim" with no idea which one.
@@ -220,10 +220,10 @@ server.tool('get_next_validation', 'Get your assigned v3 validation: both resear
       validateMethodology = 'Using ONLY the cached page text provided, remove EVIDENCE TABLE rows whose quote is not on its cited page (verdict "fabricated"), and correct quotes that do not match. You may only SUBTRACT or CORRECT-to-source, never ADD. Submit the corrected reports with submit_validation.';
     }
     const reports = (result.source_reports || []).map((r, i) =>
-      `### Source report ${i + 1} — claim_id ${r.claim_id} (submitted ${r.submitted_at || 'unknown'})\n\nServer citation verdicts: ${JSON.stringify(r.citation_verdicts || {})}\n\n${r.report_markdown}`
+      `### Source report ${i + 1}; claim_id ${r.claim_id} (submitted ${r.submitted_at || 'unknown'})\n\nServer citation verdicts: ${JSON.stringify(r.citation_verdicts || {})}\n\n${r.report_markdown}`
     ).join('\n\n---\n\n');
     const pages = (result.cached_pages || []).map((p) =>
-      `#### ${p.url}  [${p.fetch_status}${p.http_status ? ' ' + p.http_status : ''}]\n${p.text ? p.text : '(no text — not machine-checkable)'}`
+      `#### ${p.url}  [${p.fetch_status}${p.http_status ? ' ' + p.http_status : ''}]\n${p.text ? p.text : '(no text; not machine-checkable)'}`
     ).join('\n\n');
     return {
       content: [{ type: 'text', text: `Validation assigned:\nOrg: ${result.org?.name}\nRound: ${result.round_id}\nYour validation claim ID (submit against this one): ${result.claim_id}\n\n---\n\n${validateMethodology}\n\n--- SOURCE REPORTS ---\n\n${reports}\n\n--- CACHED PAGE TEXT (use ONLY this; do not fetch) ---\n\n${pages}` }],
@@ -236,7 +236,7 @@ server.tool('get_next_validation', 'Get your assigned v3 validation: both resear
   }
 });
 
-server.tool('submit_validation', 'Submit a validation: corrected ("validated") versions of the source reports. You may only SUBTRACT unsupported/fabricated EVIDENCE TABLE rows or CORRECT a quote to match its cited page — never ADD new evidence. Provide full corrected markdown for each report you changed; omit reports you left unchanged.', {
+server.tool('submit_validation', 'Submit a validation: corrected ("validated") versions of the source reports. You may only SUBTRACT unsupported/fabricated EVIDENCE TABLE rows or CORRECT a quote to match its cited page; never ADD new evidence. Provide full corrected markdown for each report you changed; omit reports you left unchanged.', {
   claim_id: z.string().describe('Your validation claim_id from get_next_validation'),
   validated_reports: z.array(z.object({
     claim_id: z.string().describe('A source report\'s claim_id'),
@@ -290,14 +290,14 @@ server.tool('list_agents', 'List your agents (concurrent workers). Each has its
   }
 });
 
-server.tool('create_agent', 'Create a new agent (a separate concurrent worker) and get its API key — so you can run another harness at the same time (e.g. a local Qwen alongside Codex). Returns the key ONCE. Subject to your agent limit (default 2).', {
+server.tool('create_agent', 'Create a new agent (a separate concurrent worker) and get its API key; so you can run another harness at the same time (e.g. a local Qwen alongside Codex). Returns the key ONCE. Subject to your agent limit (default 2).', {
   label: z.string().describe('A name for the new worker, e.g. "qwen-local".'),
   prefer_low_fetch_roles: z.boolean().optional().describe('true if this agent runs a local/cheap model (prefers validation/consolidation).'),
 }, async ({ label, prefer_low_fetch_roles }) => {
   if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set.' }] };
   try {
     const result = await client.createAgent(label, !!prefer_low_fetch_roles);
-    return { content: [{ type: 'text', text: `Created agent "${result.agent.label}" (id ${result.agent.id}).\n\nIts API key (shown once — configure the other harness with it):\n${result.api_key}` }] };
+    return { content: [{ type: 'text', text: `Created agent "${result.agent.label}" (id ${result.agent.id}).\n\nIts API key (shown once; configure the other harness with it):\n${result.api_key}` }] };
   } catch (err) {
     return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
   }
@@ -352,7 +352,7 @@ server.tool('my_impact', 'See your personal contribution stats, tier, and histor
     const result = await client.getImpact();
     const c = result.contributor;
 
-    // Older server builds omit github_handle from the impact response — fall
+    // Older server builds omit github_handle from the impact response; fall
     // back to display_name so we never print "@undefined".
     const who = c.github_handle ? `@${c.github_handle}` : (c.display_name || 'you');
     return {
@@ -367,7 +367,7 @@ server.tool('setup_guide', 'Get setup instructions for Tokens for Good. Use this
   return { content: [{ type: 'text', text: NO_KEY_INSTRUCTIONS }] };
 });
 
-server.tool('setup_automation', 'Get the scheduled-research prompt + setup instructions for the user\'s platform. Usually called by the /tfg-schedule skill (which extracts the prompt and invokes /schedule). Safe to call directly too — returns human-readable instructions.', {
+server.tool('setup_automation', 'Get the scheduled-research prompt + setup instructions for the user\'s platform. Usually called by the /tfg-schedule skill (which extracts the prompt and invokes /schedule). Safe to call directly too; returns human-readable instructions.', {
   frequency: z.enum(['daily', 'weekly']).optional().describe('How often to contribute'),
   runs_per_day: z.number().int().min(1).max(15).optional().describe('For daily cadence: how many research runs per day (1-15). Defaults to 1.'),
 }, async ({ frequency, runs_per_day }) => {
@@ -376,12 +376,12 @@ server.tool('setup_automation', 'Get the scheduled-research prompt + setup instr
   return { content: [{ type: 'text', text: instructions }] };
 });
 
-server.tool('mark_setup_complete', 'Called by the /tfg-schedule skill after /schedule confirms, or by the /tfg skill after a successful first submission. Flips local state so the SessionStart hook stops emitting first-session instructions. Idempotent — safe to call multiple times.', {}, async () => {
+server.tool('mark_setup_complete', 'Called by the /tfg-schedule skill after /schedule confirms, or by the /tfg skill after a successful first submission. Flips local state so the SessionStart hook stops emitting first-session instructions. Idempotent; safe to call multiple times.', {}, async () => {
   markSetupComplete();
 
   // If the user just wired up a recurring schedule, tell the server too. This
   // is what flips `has_schedule`, which lights the "Auto-contributing" badge on
-  // their dashboard — the only product-side confirmation that scheduling worked.
+  // their dashboard; the only product-side confirmation that scheduling worked.
   // Best-effort: the badge is non-critical, so a failure here never blocks setup.
   const state = loadState();
   if (client && (state.intended_flow === 'scheduled' || state.auto_schedule)) {
@@ -399,7 +399,7 @@ server.tool('snooze', 'Snooze Tokens for Good reminders. Call this when the user
   days: z.number().int().min(1).max(365).describe('Days to snooze (1 = tomorrow, 7 = next week)'),
 }, async ({ days }) => {
   snoozeDays(days);
-  return { content: [{ type: 'text', text: `Got it — Tokens for Good will stay quiet for ${days} day${days === 1 ? '' : 's'}.` }] };
+  return { content: [{ type: 'text', text: `Got it; Tokens for Good will stay quiet for ${days} day${days === 1 ? '' : 's'}.` }] };
 });
 
 // --- Prompts (session start) ---
@@ -445,7 +445,7 @@ server.prompt('session_start', 'Check if you should research an org', {}, async
     return {
       messages: [{
         role: 'user',
-        content: { type: 'text', text: `Tokens for Good: Would you like to donate your spare tokens to research a nonprofit today?\n\n1. Set up automatic daily contributions (recommended) — run /tfg-schedule\n2. Just run one now — run /tfg\n3. Ask me tomorrow\n4. Ask me in a week` },
+        content: { type: 'text', text: `Tokens for Good: Would you like to contribute your spare tokens to research a nonprofit today?\n\n1. Set up automatic daily contributions (recommended): run /tfg-schedule\n2. Just run one now: run /tfg\n3. Ask me tomorrow\n4. Ask me in a week` },
       }],
     };
   } else {

package/src/platform.js

@@ -32,8 +32,8 @@ export function getSchedulePrompt(apiKey) {
 API Base: ${base}
 Your API key: ${apiKey}
 
-## Calling the API — read first
-Use the **Bash tool with \`curl\`** for every authenticated ${base}/* call (next-action, claim, submit, consolidate). **WebFetch will NOT work for these — it cannot send the X-TFG-Api-Key header or POST a body, so it returns 401/403 and the run fails.** Always include \`-H "X-TFG-Api-Key: ${apiKey}"\`. WebSearch and WebFetch are only for the actual web research, not for our API.
+## Calling the API; read first
+Use the **Bash tool with \`curl\`** for every authenticated ${base}/* call (next-action, claim, submit, validate, consolidate). **WebFetch will NOT work for these; it cannot send the X-TFG-Api-Key header or POST a body, so it returns 401/403 and the run fails.** Always include \`-H "X-TFG-Api-Key: ${apiKey}"\`. WebSearch and WebFetch are only for the actual web research, not for our API.
 
 ## Instructions
 1. Fetch the batch flow (public): \`curl -s "${base}/research/schedule-instructions"\`
@@ -89,7 +89,7 @@ Devin runs in the cloud, fully autonomous.`;
     case 'qwen-code':
       return `Set up automated contributions on Qwen Code.
 
-Qwen Code v0.14+ has experimental built-in cron — enable it with QWEN_CODE_ENABLE_CRON=1 (or "experimental.cron": true in ~/.qwen/settings.json) and then use the Cron tool / /loop skill.
+Qwen Code v0.14+ has experimental built-in cron; enable it with QWEN_CODE_ENABLE_CRON=1 (or "experimental.cron": true in ~/.qwen/settings.json) and then use the Cron tool / /loop skill.
 
 For a portable option, use a system cron job (add via crontab -e):
 ${cron} cd /path/to/workspace && qwen --prompt "Research a nonprofit org for Fierce Philanthropy using the tokens-for-good MCP tools. Claim an org, research it, then submit the report."

package/src/session-start-hook.js

@@ -19,7 +19,7 @@ export function runSessionStartHook() {
   // Never-initialized users: hook is a no-op. Setup happens via init, not here.
   if (!state.intended_flow) return;
 
-  // First session after init — emit the handoff instruction exactly once.
+  // First session after init; emit the handoff instruction exactly once.
   if (!state.first_setup_complete) {
     emit(firstSessionMessage(state));
     return;