Civic Climate Action: refocus on a Porto Alegre "one real move" + funder view

.gitignore

@@ -9,3 +9,7 @@ __pycache__/
 dist/
 .DS_Store
 *.log
+
+*.tsbuildinfo
+
+.data/

events/2026-06-11-unlock-the-money/civic-climate-action/DEMO_SCRIPT.md

@@ -0,0 +1,79 @@
+# Civic Climate Action — Demo Script
+
+**What it is (one line):** A citizen-facing companion to CityCatalyst that turns top-down city climate data into one real, doable civic action — and turns that participation into a measurable, fundable engagement signal. Pilot: **Porto Alegre**.
+
+---
+
+## 1. Problem & who feels the pain (30s)
+
+CityCatalyst tells **city governments** what to do about climate. But two groups are stuck:
+
+- **Residents** can see their city is at risk but have no idea how to actually act. Generic advice ("join a group", "contact the council") stops exactly where the hard part — *where do I start, what do I say?* — begins.
+- **Funders** (MDBs, the IDB, philanthropy) need proof a city's community is engaged before they release money. Today that proof is anecdotal, so good projects stall.
+
+Same gap, both sides: civic engagement is real but **invisible and unusable**.
+
+---
+
+## 2. Demo — show, don't tell (≈3 min)
+
+> Live at `localhost:3001`. Pilot city: Porto Alegre.
+
+1. **Home → "What's at stake"** (~20s): Porto Alegre's real risk, straight from CityCatalyst — **Floods & Landslides: Very High**, transport = 77% of emissions. This is the city's own data, in plain language.
+2. **"Your move" → pick *Flooding* → *Quick & online*** (~30s): Instead of vague advice, **one concrete move**: *"Report a flooding or drainage problem on your street to Defesa Civil"* — the **real channel** (working link), a time estimate (~10 min), **Why this helps**, and **What happens next**.
+3. **The AI toolkit — two tabs** (~45s):
+   - **✉️ Ready-to-send message:** an AI-written, copy-ready message in PT (toggle EN), grounded in the real channel — no filler, no lecturing the recipient.
+   - **🧭 Guide me:** a civic-coach **chat** that builds a *toolkit* from all the available next steps + partner orgs — **what to do, how, and why** — and answers follow-ups ("how do I run a block meeting?", "what if I get no reply?"). It's constrained to the real local channels/orgs only — it won't invent contacts.
+   - Point at the **carbon figure** (~0.01–0.03 g CO₂e per reply) — see the green-AI note below.
+4. **"Team up with people already doing this"** (~15s): real Porto Alegre / RS organizations — **Parceiros Voluntários, BrazilFoundation, AGAPAN, Bike Anjo** — with concrete plug-ins: **Volunteer / Attend / Back a campaign / Donate**. Not just a contact link.
+5. **"I care about this"** (~30s): add name + neighborhood (email optional). The message **auto-fills with your details** (it's now genuinely yours), and you get a **tracker** — *Committed → Sent → Got a response* — plus a dated **receipt**. A signature, not a throwaway click.
+6. **"On the record"** (~25s): a **map of Porto Alegre** with engagement by neighborhood, a **"Most-backed actions" ranking** (Flooding 33 · Heat 19 · Landslides 15…), and a live **commitment wall** of named residents.
+7. **"For funders" page** (~30s): the punchline — the **live readout**: total signed commitments, **follow-through rate**, demand **by climate priority** (mapped to the CCRA risk levels) and **by neighborhood**, the local orgs who can **deliver**, and **what each theme could unlock**.
+
+### Under the hood — green AI, measured (≈15s aside)
+
+- **Model choice:** an **open-weight ~24B model (Mistral Small)** — small and capable enough for grounded, templated writing; we don't need a frontier model. Provider is swappable by env (Scaleway / GreenPT / Mistral / Salamandra).
+- **Hosting:** served on **Scaleway's low-carbon EU grid** (~52 gCO₂e/kWh) — green by default, not as an afterthought.
+- **Carbon tracking:** every call is measured with **EcoLogits** (by the GenAI Impact non-profit) — energy (Wh) + emissions (gCO₂e) shown **per reply** and totalled in the session **carbon counter**. Honest caveats: figures are estimates (it falls back to a token-based estimate for models outside EcoLogits' registry), and if the model is offline the app serves a **graceful templated fallback** so the demo never breaks.
+
+---
+
+## 3. Business value — who pays / premium feature / funder trust / 💰
+
+**The unlock:** civic participation is a co-benefit funders **already score** (CityCatalyst's HIAP rates *stakeholder engagement* −2..+2). We make it **visible, sourced, and continuous** — which is exactly what moves money:
+
+- **Raises the co-benefit score** → a more fundable project.
+- **De-risks disbursement** → named, located demand + follow-through answers a credit committee's "will the community actually use this?"
+- **Satisfies the readiness/consultation gate** → produces the stakeholder-engagement record many funds *require*, continuously instead of as a one-off survey.
+
+**Who pays / how it makes money:**
+
+- **Premium CityCatalyst add-on:** free public citizen view; **paid white-label civic dashboards** for cities & consultancies.
+- **Grant-funded pilots:** 3–5 cities already on CityCatalyst (Brazil-first).
+- **MDB / IDB co-financing:** sold as the **"community-engagement component"** inside climate project-preparation programs.
+- **Differentiation:** most city-climate tools serve governments only — this serves **citizens**, differentiating CityCatalyst across the **IDB Cities Network (300+ LAC cities)**.
+
+---
+
+## 4. What's left to reach prod (honest)
+
+- **Data (the real cost):** local channels + partner orgs are **hand-curated for Porto Alegre only**. Scaling = per-city research + link verification + neighborhood geocoding. Some themes (e.g. energy) have thin org coverage today.
+- **Integration:** swap baked-in CityCatalyst figures for **live API fetch**; replace the file-backed pledge store with a **real database**; add **identity/auth + anti-abuse** so the tally is trustworthy; wire **email follow-up**; ideally connect to real consultation platforms (Participe+, Orçamento Participativo).
+- **Trust/verification:** follow-through is currently **self-reported** (a proxy MRV) and demo numbers include a clearly-labelled seeded baseline — production needs verified signals.
+- **Effort:** ~weeks to harden one city end-to-end; the multi-city onboarding pipeline is the larger lift.
+
+---
+
+## 5. The ask — what we need to keep going
+
+- **One pilot city** already on CityCatalyst (Porto Alegre or another BR municipality) as a design partner.
+- **An intro to an MDB / IDB contact** to validate the co-benefit-as-fundable-evidence framing with a real appraisal process.
+- **Eng time** to wire live CityCatalyst data + a real datastore + auth.
+- **A small grant / owner** for local-org curation across the first 3–5 cities.
+- **A decision:** does this become a supported **CityCatalyst module**?
+
+---
+
+## 6. The hardest part of this hackday for me
+
+<!-- (to fill in) -->

events/2026-06-11-unlock-the-money/civic-climate-action/IMPLEMENTATION_PLAN.md

@@ -25,12 +25,14 @@ app/src/app/
     CityMap.tsx         Leaflet map, circle markers, fly-to selection (client, dynamic import, ssr:false)
     CitySnapshot.tsx    emissions bars + risk hazards + provenance badge
     StoriesGallery.tsx  success-story cards with images + category filter (client)
-    TakeAction.tsx      civic action pathways + cause filter + CTA (client)
+    TakeAction.tsx      universal civic action pathways + cause filter + CTA (client)
+    LocalEngagementPanel.tsx contextual Porto Alegre local-source panel in Explore
   data/
     types.ts            City, Story, Emissions, Risk, Hazard, StoryImage, Category, ActionPathway
     cities.ts           15 cities: coords, LOCODE, summary, highlights, emissions, risk, provenance
     stories.ts          15 sourced success stories + images
     actions.ts          7 universal civic action pathways, tagged by cause
+    localEngagement.ts  Porto Alegre-specific civic recommendations and source links for the demo
 ```
 
 ## 3. Data model (the important part)
@@ -42,6 +44,9 @@ app/src/app/
 - **`Risk`** — `topHazards[]` (`hazard`, `keyImpact?`, `level`, `score?`), `summary?`, `source`, `sourceUrl`.
 - **`Story`** — city, coords, `title`, `category`, `whatCitizensDid`, `outcome`, `year`,
   `sourceName/Url`, `image?` (`url`, `credit`, `license`, `sourcePageUrl`).
+- **`LocalEngagementRecommendation`** — Porto Alegre demo cards with `title`, `priority`, `theme`,
+  `whyItMatters`, `firstActions[]`, and `sources[]`. This is the bridge from CityCatalyst risk /
+  emissions data to actual civic pathways and source links.
 
 The provenance badge keys off `dataProvenance`; the UI renders sector **bars** when `sectors`
 exist, else a "largest source" line. Honest caveats live in `emissions.note`.
@@ -69,14 +74,16 @@ Base: `https://api.citycatalyst.io`. Cities are keyed by UN/LOCODE (e.g. `BR SAO
 - All 4 sections built and verified; production build clean; 15 story images load and are licensed.
 - Live CityCatalyst emissions + CCRA risk baked in for São Paulo, Rio, Curitiba, Porto Alegre.
 - Verified external inventories + risk for the 11 other cities, each with a source link.
+- Porto Alegre local-source panel added to the selected-city Explore view with official/community engagement sources.
 
 **Next (in priority order)**
 1. **Widen emissions coverage** — sum more GPC sectors / add scope-2 so the breakdown stops being
    transport-dominated; or pivot to a per-capita / sector-relative view.
 2. **"My city" entry** — geolocation or a typeahead over the live CCRA city list (5,570 BR cities).
 3. **Live fetch at runtime** — replace baked-in numbers with on-demand API calls + caching, so
    data refreshes without a rebuild (add a small route handler or server action).
-4. **Real local "Act" data** — per-hero-city community groups, public-comment windows, council agendas.
+4. **Real local "Act" data** — expand the Porto Alegre model to the other hero cities:
+   community groups, public-comment windows, council agendas.
 5. **Participation loop** — let residents log an action → produce the measurable co-benefit metric.
 
 ## 6. Gotchas

events/2026-06-11-unlock-the-money/civic-climate-action/SPEC.md

@@ -9,7 +9,7 @@
 ## 0. Open product questions — investigate before building more
 
 - **Localization & "my city" entry point.** A citizen should land on *their* city, not a global list. Is the right next move geolocation + a typeahead over the full CityCatalyst city catalogue, or staying with a curated, high-quality seed set? What breaks (data coverage, map clutter) if we go to thousands of cities?
-- **The "Act" gap.** The Take Action step is currently *generic* (universal pathways). The real value is **local** next steps — the actual community group, the actual open public-comment window, the actual council agenda. Where does that data come from, and can any of it be sourced reliably per-city rather than hand-curated?
+- **The "Act" gap.** The Explore step now has a Porto Alegre-specific local-source panel, but the pattern is still hand-curated. The real value is scaling this to actual community groups, open public-comment windows, and council agendas for every supported city. Where can that data be sourced reliably per-city rather than maintained manually?
 - **Emissions honesty.** The Brazilian inventories pulled live are *partial* (no scope-2 grid electricity yet), which overstates transport's share. Should we (a) sum more datasources for fuller coverage, (b) show a clear "partial" framing (current approach), or (c) switch to a per-capita / sector-relative view that's less sensitive to coverage gaps?
 - **Citizen feedback loop.** Should residents be able to *report back* (pledged an action, joined a group) so the module produces the participation metrics funders want — closing the loop from engagement to measurable co-benefit?
 

events/2026-06-11-unlock-the-money/civic-climate-action/app/README.md

@@ -28,6 +28,9 @@ The interface is deliberately minimalist and plain-language:
    there are shaping local climate action, and what you could do in your own.
 3. **Inspiration** — a gallery of **real, independently sourced** success stories where
    citizens changed their cities, filterable by action type. Every card links to its source.
+4. **Take Action** — universal civic pathways. Porto Alegre also gets a contextual local-source
+   panel inside Explore, with real sources such as Defesa Civil, Orçamento Participativo,
+   municipal councils, POA+Drena Resiliente, AGAPAN, MobiRio, and Bike Anjo.
 
 ## Revenue Connection
 
@@ -47,22 +50,41 @@ visible, measurable participation metrics — the kind MDBs, the IDB, and philan
 ```bash
 cd events/2026-06-11-unlock-the-money/civic-climate-action/app
 npm install
-npm run dev
+npm run build && npm start      # stable; dev (--turbopack) can 500 on stale state
 # Open http://localhost:3000
 ```
 
+The **AI localizer** (the "Make this concrete for my city" button) calls an optional
+green-LLM sidecar; if it isn't running, the app's route handler falls back to a built-in
+localizer, so the demo works either way. To run the real sidecar (mock mode, no key):
+
+```bash
+cd ../llm-service
+python -m venv .venv && source .venv/bin/activate
+pip install fastapi "uvicorn[standard]" pydantic python-dotenv
+uvicorn main:app --port 8000     # see llm-service/README.md for live/green providers
+```
+
+To refresh the baked HIAP action library: `npm run data:actions`.
+
 ## Demo Script (5 min)
 
 1. **The gap** — CityCatalyst is powerful but government-only. Citizens are locked out of
    their own city's climate plan.
-2. **How it works** — the diagram: city planning data → plain language → *Understand, Connect,
-   Act*. No dashboards to decode.
-3. **Explore** — search a city, or click the map. Pick Medellín / Bogotá / a Brazilian city
-   and read, in everyday language, what residents there did and what you could do.
-4. **The "aha"** — the Inspiration gallery: real, sourced stories of citizens who cooled their
-   streets, bought their power grid, rewrote climate law. Filter by action type; every claim
-   links to its source.
-5. **Who pays** — civic engagement is a co-benefit funders already score; this makes it
+2. **Explore** — search a city, or click the map. Pick a pilot city (São Paulo / Porto Alegre):
+   a one-line plain-language profile (top risks + where emissions come from), then recommended
+   climate actions ranked for *this* city, each with a "why this matters here" trace.
+3. **The workspace** — pick an action and open the AI workspace. It's not one suggestion: tabs for
+   **Next steps · Draft a proposal · Back it with data · Pathways (short→long) · Examples · Future
+   vision**. A cheap, green open-weight model (Mistral Small on a low-carbon EU grid) drafts each,
+   grounded in the city's real numbers and real local channels (Orçamento Participativo, CADES…).
+   **Refine** any output ("shorter", "more formal", "focus on flooding"), **Copy** the draft. The
+   **CO₂ counter** (bottom right) shows each call's EcoLogits footprint.
+4. **Future vision** — the Futures-Design lens paints a short, hopeful "day in the life" of the
+   city once the action takes hold — vision, not just guides.
+5. **Inspiration** — real, sourced stories of citizens who cooled their streets, bought their
+   power grid, rewrote climate law. Every claim links to its source.
+6. **Who pays** — civic engagement is a co-benefit funders already score; this makes it
    visible and measurable. B2G, IDB, philanthropy.
 
 ## Built With
@@ -72,7 +94,16 @@ npm run dev
 - [Leaflet](https://leafletjs.com/) + react-leaflet, with free OpenStreetMap / CARTO basemap tiles
 - Cities keyed by **UN/LOCODE** — the same key the
   [CityCatalyst Global API](https://github.com/Open-Earth-Foundation/CityCatalyst/tree/develop/global-api)
-  uses — so they can connect to live GHGI / CCRA / HIAP data (`api.citycatalyst.io`)
+  uses — so they connect to live emissions-inventory, climate-risk, and recommended-action data
+  (`api.citycatalyst.io`)
+- **Recommended climate actions** baked from `GET /api/v0/climate_actions` (155 actions, EN/ES/PT),
+  prioritized per city in `src/app/lib/prioritize.ts`
+- **AI workspace**: a Python/FastAPI sidecar (`../llm-service`) with a `/generate` task API
+  (next-steps · draft proposal · evidence · pathways · future vision · refine), calling an
+  open-weight model (Mistral Small) via an OpenAI-compatible API on a low-carbon EU provider
+  (Scaleway), instrumented with [EcoLogits](https://ecologits.ai/) for per-call carbon. Model and
+  provider are an env-only swap. The "Future vision" lens uses an Experiential-Futures prompt.
+- AI output rendered with `react-markdown` (no raw HTML — safe by default)
 
 ## Data & Sources
 
@@ -92,12 +123,23 @@ npm run dev
   uncertain figures are described qualitatively. Each card links its source.
 - **Story images** are from Wikimedia Commons under reuse-permitting licenses (CC0 / CC BY /
   CC BY-SA); photographer credit + license are shown on each image and link to the file page.
+- **Climate actions** (`src/app/data/climateActions.generated.ts`) are CityCatalyst's HIAP
+  library, fetched once and committed (EN/ES/PT). We compute per-city prioritization ourselves
+  because the per-city ranking endpoints aren't populated in prod yet.
+- **Engagement opportunities** (`src/app/data/engagement.ts`) are curated, LATAM-first, and
+  flagged `needs_local_validation` until a local partner confirms them.
 - **Cities** are the 15 places featured in the success stories, each tagged with its UN/LOCODE.
+- **Porto Alegre local engagement source** (`src/app/data/localEngagement.ts`) turns the
+  data-mapping track into contextual Explore content: flood resilience, landslide prevention,
+  heat and green infrastructure, residential energy, and active mobility. Each item has first
+  moves and source links; community sources are included with validation caveats where needed.
 
 ## If This Survives the Hackday
 
 - [ ] Wire cities by LOCODE to live CityCatalyst Global API data (GHGI / CCRA / HIAP)
 - [ ] Expand from the seed set to the full CityCatalyst city catalogue + geolocation
-- [ ] Real engagement directory per city: community groups, public-comment calendars, council agendas
+- [x] Add a Porto Alegre-specific engagement source for the demo
+- [ ] Generalize the local engagement source into a real directory per city: community groups,
+  public-comment calendars, council agendas
 - [ ] Extend Climate Advisor (AI) to answer "how do I influence my city's climate plan?"
 - [ ] Participation metrics dashboard for cities/funders (the revenue surface)