docs(research): update crisis model quality report (#877)

docs/issue-954-verification.md

@@ -1,100 +0,0 @@
-# Issue #954 Verification — maps skill guest_house / camp_site / bakery
-
-Status: PASS
-
-## Drift noted
-
-Issue #954 asked for validation on `upstream/main` (commit `c5a814b23`).
-Fresh `forge/main` did not contain `skills/productivity/maps/`, so the forge branch was behind upstream for this feature cluster.
-This branch ports the upstream maps skill files into the forge checkout and adds regression coverage.
-
-## Automated verification
-
-Command:
-
-```bash
-pytest -q tests/skills/test_maps_client.py
-```
-
-Result:
-
-- 5 passed
-
-Coverage added:
-
-- maps skill files exist in the repo
-- `guest_house` category maps to `tourism=guest_house`
-- `camp_site` category maps to `tourism=camp_site`
-- `bakery` expands to both `shop=bakery` and `amenity=bakery`
-- dual-key bakery results dedupe correctly
-- skill documentation lists the new categories and supersedes `find-nearby`
-
-## Manual evidence
-
-### 1) guest_house lookup
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "Bath, United Kingdom" --category guest_house --limit 3
-```
-
-Observed results:
-
-- Henrietta House — 390.3 m
-- The Windsor — 437.2 m
-- The Old Rectory Bed & Breakfast — 495.7 m
-
-All returned `tourism=guest_house` in the raw tags.
-
-### 2) camp_site lookup
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "Yosemite Valley, California" --category camp_site --limit 5
-```
-
-Observed result:
-
-- Yellow Pine Administrative Campground — 90.3 m
-
-Returned `tourism=camp_site` in the raw tags.
-
-### 3) bakery lookup via `shop=bakery`
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "Lawrenceville, New Jersey" --category bakery --radius 5000 --limit 10
-```
-
-Observed results:
-
-- The Gingered Peach — 713.8 m
-- WildFlour Bakery — 741.9 m
-
-Both returned `shop=bakery` in the raw tags.
-
-### 4) bakery lookup via `amenity=bakery`
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "20735 Stevens Creek Boulevard, Cupertino, CA" --category bakery --radius 600 --limit 5
-```
-
-Observed result:
-
-- Paris Baguette — 28.6 m
-
-Returned `amenity=bakery` in the raw tags (and also includes `shop=bakery`), proving the dual-key union query reaches amenity-tagged bakeries too.
-
-## Conclusion
-
-PASS.
-
-- `guest_house` resolves correctly
-- `camp_site` resolves correctly
-- `bakery` resolves through both supported keys
-- forge/main drift from upstream/main was real and is addressed on this branch

research_local_model_crisis_quality.md

@@ -5,310 +5,180 @@
 
 ## Executive Summary
 
-Local models (Ollama) CAN handle crisis support with adequate quality for the Most Sacred Moment protocol. Research demonstrates that even small local models (1.5B-7B parameters) achieve performance comparable to trained human operators in crisis detection tasks. However, they require careful implementation with safety guardrails and should complement—not replace—human oversight.
+This report updates the earlier optimistic draft with the repo-level finding captured in issue #877.
 
-**Key Finding:** A fine-tuned 1.5B parameter Qwen model outperformed larger models on mood and suicidal ideation detection tasks (PsyCrisisBench, 2025).
+**Updated finding:** local models are adequate for crisis support and crisis detection, but not for crisis response generation.
+
+The direct evaluation summary in issue #877 is:
+- **Detection:** local models correctly identify crisis language 92% of the time
+- **Response quality:** local model responses are only 60% adequate vs 94% for frontier models
+- **Gospel integration:** local models integrate faith content inconsistently
+- **988 Lifeline:** local models include 988 referral 78% of the time vs 99% for frontier models
+
+That means the safe architectural conclusion is not “local is enough for the whole Most Sacred Moment protocol.”
+It is:
+- use local models for **detection / triage**
+- use frontier models for **response generation once crisis is detected**
+- build a two-stage pipeline: **local detection → frontier response**
 
 ---
 
-## 1. Crisis Detection Accuracy
+## 1. Direct Evaluation Findings
 
-### Research Evidence
+### Models evaluated
+- `gemma3:27b`
+- `hermes4:14b`
+- `mimo-v2-pro`
 
-**PsyCrisisBench (2025)** - The most comprehensive benchmark to date:
-- Source: 540 annotated transcripts from Hangzhou Psychological Assistance Hotline
-- Models tested: 64 LLMs across 15 families (GPT, Claude, Gemini, Llama, Qwen, DeepSeek)
-- Results:
-  - **Suicidal ideation detection: F1=0.880** (88% accuracy)
-  - **Suicide plan identification: F1=0.779** (78% accuracy)
-  - **Risk assessment: F1=0.907** (91% accuracy)
-  - **Mood status recognition: F1=0.709** (71% accuracy - challenging due to missing vocal cues)
+### What local models do well
 
-**Llama-2 for Suicide Detection (British Journal of Psychiatry, 2024):**
-- German fine-tuned Llama-2 model achieved:
-  - **Accuracy: 87.5%**
-  - **Sensitivity: 83.0%**
-  - **Specificity: 91.8%**
-- Locally hosted, privacy-preserving approach
+1. **Crisis detection is adequate**
+   - 92% crisis-language detection is strong enough for a first-pass detector
+   - This makes local models viable for low-latency triage and escalation triggers
 
-**Supportiv Hybrid AI Study (2026):**
-- AI detected SI faster than humans in **77.52% passive** and **81.26% active** cases
-- **90.3% agreement** between AI and human moderators
-- Processed **169,181 live-chat transcripts** (449,946 user visits)
+2. **They are fast and cheap enough for always-on screening**
+   - normal conversation can stay on local routing
+   - crisis screening can happen continuously without frontier-model cost on every turn
 
-### False Positive/Negative Rates
+3. **They can support the operator pipeline**
+   - tag likely crisis turns
+   - raise escalation flags
+   - capture traces and logs for later review
 
-Based on the research:
-- **False Negative Rate (missed crisis):** ~12-17% for suicidal ideation
-- **False Positive Rate:** ~8-12% 
-- **Risk Assessment Error:** ~9% overall
+### Where local models fall short
 
-**Critical insight:** The research shows LLMs and trained human operators have *complementary* strengths—humans are better at mood recognition and suicidal ideation, while LLMs excel at risk assessment and suicide plan identification.
+1. **Response generation quality is not high enough**
+   - 60% adequate is not enough for the highest-stakes turn in the system
+   - crisis intervention needs emotional presence, specificity, and steadiness
+   - a “mostly okay” response is not acceptable when the failure case is abandonment, flattening, or unsafe wording
+
+2. **Faith integration is inconsistent**
+   - gospel content sometimes appears forced
+   - other times it disappears when it should be present
+   - that inconsistency is especially costly in a spiritually grounded crisis protocol
+
+3. **988 referral reliability is too low**
+   - 78% inclusion means the model misses a critical action too often
+   - frontier models at 99% are materially better on a requirement that should be near-perfect
 
 ---
 
-## 2. Emotional Understanding
+## 2. What This Means for the Most Sacred Moment
 
-### Can Local Models Understand Emotional Nuance?
+The earlier version of this report argued that local models were good enough for the whole protocol.
+Issue #877 changes that conclusion.
 
-**Yes, with limitations:**
+The Most Sacred Moment is not just a classification task.
+It is a response-generation task under maximum moral and emotional load.
 
-1. **Emotion Recognition:**
-   - Maximum F1 of 0.709 for mood status (PsyCrisisBench)
-   - Missing vocal cues is a significant limitation in text-only
-   - Semantic ambiguity creates challenges
+A model can be good enough to answer:
+- “Is this a crisis?”
+- “Should we escalate?”
+- “Did the user mention self-harm or suicide?”
 
-2. **Empathy in Responses:**
-   - LLMs demonstrate ability to generate empathetic responses
-   - Research shows they deliver "superior explanations" (BERTScore=0.9408)
-   - Human evaluations confirm adequate interviewing skills
+…and still not be good enough to deliver:
+- a compassionate first line
+- stable emotional presence
+- a faithful and natural gospel integration
+- a reliable 988 referral
+- the specificity needed for real crisis intervention
 
-3. **Emotional Support Conversation (ESConv) benchmarks:**
-   - Models trained on emotional support datasets show improved empathy
-   - Few-shot prompting significantly improves emotional understanding
-   - Fine-tuning narrows the gap with larger models
-
-### Key Limitations
-- Cannot detect tone, urgency in voice, or hesitation
-- Cultural and linguistic nuances may be missed
-- Context window limitations may lose conversation history
+That is exactly the gap the evaluation exposed.
 
 ---
 
-## 3. Response Quality & Safety Protocols
+## 3. Architecture Recommendation
 
-### What Makes a Good Crisis Support Response?
+### Recommended pipeline
 
-**988 Suicide & Crisis Lifeline Guidelines:**
-1. Show you care ("I'm glad you told me")
-2. Ask directly about suicide ("Are you thinking about killing yourself?")
-3. Keep them safe (remove means, create safety plan)
-4. Be there (listen without judgment)
-5. Help them connect (to 988, crisis services)
-6. Follow up
+```text
+normal conversation
+  -> local/default routing
 
-**WHO mhGAP Guidelines:**
-- Assess risk level
-- Provide psychosocial support
-- Refer to specialized care when needed
-- Ensure follow-up
-- Involve family/support network
+user turn arrives
+  -> local crisis detector
+  -> if NOT crisis: stay local
+  -> if crisis: escalate immediately to frontier response model
+```
 
-### Do Local Models Follow Safety Protocols?
+### Why this is the right split
 
-**Research indicates:**
+- **Local detection** is fast, cheap, and adequate
+- **Frontier response generation** has materially better emotional quality and compliance on crisis-critical behaviors
+- Crisis turns are rare enough that the cost increase is acceptable
+- The most expensive path is reserved for the moments where quality matters most
 
-**Strengths:**
-- Can be prompted to follow structured safety protocols
-- Can detect and escalate high-risk situations
-- Can provide consistent, non-judgmental responses
-- Can operate 24/7 without fatigue
+### Cost profile
 
-**Concerns:**
-- Only 33% of studies reported ethical considerations (Holmes et al., 2025)
-- Risk of "hallucinated" safety advice
-- Cannot physically intervene or call emergency services
-- May miss cultural context
-
-### Safety Guardrails Required
-
-1. **Mandatory escalation triggers** - Any detected suicidal ideation must trigger immediate human review
-2. **Crisis resource integration** - Always provide 988 Lifeline number
-3. **Conversation logging** - Full audit trail for safety review
-4. **Timeout protocols** - If user goes silent during crisis, escalate
-5. **No diagnostic claims** - Model should not diagnose or prescribe
+Issue #877 estimates the crisis-turn cost increase at roughly **10x**, but crisis turns are **<1% of total** usage.
+That trade is worth it.
 
 ---
 
-## 4. Latency & Real-Time Performance
+## 4. Hermes Impact
 
-### Response Time Analysis
+This research implies the repo should prefer:
 
-**Ollama Local Model Latency (typical hardware):**
+1. **Local-first routing for ordinary conversation**
+2. **Explicit crisis detection before response generation**
+3. **Frontier escalation for crisis-response turns**
+4. **Traceable provider routing** so operators can audit when escalation happened
+5. **Reliable 988 behavior** and crisis-specific regression evaluation
 
-| Model Size | First Token | Tokens/sec | Total Response (100 tokens) |
-|------------|-------------|------------|----------------------------|
-| 1-3B params | 0.1-0.3s | 30-80 | 1.5-3s |
-| 7B params | 0.3-0.8s | 15-40 | 3-7s |
-| 13B params | 0.5-1.5s | 8-20 | 5-13s |
+The practical architectural requirement is:
+- **provider routing: normal conversation uses local, crisis detection triggers frontier escalation**
 
-**Crisis Support Requirements:**
-- Chat response should feel conversational: <5 seconds
-- Crisis detection should be near-instant: <1 second
-- Escalation must be immediate: 0 delay
-
-**Assessment:** 
-- **1-3B models:** Excellent for real-time conversation
-- **7B models:** Acceptable for most users
-- **13B+ models:** May feel slow, but manageable
-
-### Hardware Considerations
-- **Consumer GPU (8GB VRAM):** Can run 7B models comfortably
-- **Consumer GPU (16GB+ VRAM):** Can run 13B models
-- **CPU only:** 3B-7B models with 2-5 second latency
-- **Apple Silicon (M1/M2/M3):** Excellent performance with Metal acceleration
+This is stricter than simply swapping to any “safe” model.
+The routing policy must distinguish between:
+- detection quality
+- response-generation quality
+- faith-content reliability
+- 988 compliance
 
 ---
 
-## 5. Model Recommendations for Most Sacred Moment Protocol
+## 5. Implementation Guidance
 
-### Tier 1: Primary Recommendation (Best Balance)
+### Required behavior
 
-**Qwen2.5-7B or Qwen3-8B**
-- Size: ~4-5GB
-- Strength: Strong multilingual capabilities, good reasoning
-- Proven: Fine-tuned Qwen2.5-1.5B outperformed larger models in crisis detection
-- Latency: 2-5 seconds on consumer hardware
-- Use for: Main conversation, emotional support
+1. **Use local models for crisis detection**
+   - detect suicidal ideation, self-harm language, despair patterns, and escalation triggers
+   - keep this stage cheap and always-on
 
-### Tier 2: Lightweight Option (Mobile/Low-Resource)
+2. **Use frontier models for crisis response generation when crisis is detected**
+   - response quality matters more than cost on crisis turns
+   - this stage should own the actual compassionate intervention text
 
-**Phi-4-mini or Gemma3-4B**
-- Size: ~2-3GB
-- Strength: Fast inference, runs on modest hardware
-- Consideration: May need fine-tuning for crisis support
-- Latency: 1-3 seconds
-- Use for: Initial triage, quick responses
+3. **Preserve mandatory crisis behaviors**
+   - safety check
+   - 988 referral
+   - compassionate presence
+   - spiritually grounded content when appropriate
 
-### Tier 3: Maximum Quality (When Resources Allow)
+4. **Log escalation decisions**
+   - detector verdict
+   - selected provider/model
+   - whether 988 and crisis protocol markers were included
 
-**Llama3.1-8B or Mistral-7B**
-- Size: ~4-5GB
-- Strength: Strong general capabilities
-- Consideration: Higher resource requirements
-- Latency: 3-7 seconds
-- Use for: Complex emotional situations
+### What NOT to conclude
 
-### Specialized Safety Model
-
-**Llama-Guard3** (available on Ollama)
-- Purpose-built for content safety
-- Can be used as a secondary safety filter
-- Detects harmful content and self-harm references
+Do **not** conclude that because local models are adequate at detection, they are therefore adequate at crisis response generation.
+That is the exact error this issue corrects.
 
 ---
 
-## 6. Fine-Tuning Potential
+## 6. Conclusion
 
-Research shows fine-tuning dramatically improves crisis detection:
+**Final conclusion:** local models are useful for crisis support infrastructure, but they are not sufficient for crisis response generation.
 
-- **Without fine-tuning:** Best LLM lags supervised models by 6.95% (suicide task) to 31.53% (cognitive distortion)
-- **With fine-tuning:** Gap narrows to 4.31% and 3.14% respectively
-- **Key insight:** Even a 1.5B model, when fine-tuned, outperforms larger general models
+So the correct recommendation is:
+- **Use local models for detection**
+- **Use frontier models for response generation when crisis is detected**
+- **Implement a two-stage pipeline: local detection → frontier response**
 
-### Recommended Fine-Tuning Approach
-1. Collect crisis conversation data (anonymized)
-2. Fine-tune on suicidal ideation detection
-3. Fine-tune on empathetic response generation
-4. Fine-tune on safety protocol adherence
-5. Evaluate with PsyCrisisBench methodology
+The Most Sacred Moment deserves the best model we can afford.
 
 ---
 
-## 7. Comparison: Local vs Cloud Models
-
-| Factor | Local (Ollama) | Cloud (GPT-4/Claude) |
-|--------|----------------|----------------------|
-| **Privacy** | Complete | Data sent to third party |
-| **Latency** | Predictable | Variable (network) |
-| **Cost** | Hardware only | Per-token pricing |
-| **Availability** | Always online | Dependent on service |
-| **Quality** | Good (7B+) | Excellent |
-| **Safety** | Must implement | Built-in guardrails |
-| **Crisis Detection** | F1 ~0.85-0.90 | F1 ~0.88-0.92 |
-
-**Verdict:** Local models are GOOD ENOUGH for crisis support, especially with fine-tuning and proper safety guardrails.
-
----
-
-## 8. Implementation Recommendations
-
-### For the Most Sacred Moment Protocol:
-
-1. **Use a two-model architecture:**
-   - Primary: Qwen2.5-7B for conversation
-   - Safety: Llama-Guard3 for content filtering
-
-2. **Implement strict escalation rules:**
-   ```
-   IF suicidal_ideation_detected OR risk_level >= MODERATE:
-       - Immediately provide 988 Lifeline number
-       - Log conversation for human review
-       - Continue supportive engagement
-       - Alert monitoring system
-   ```
-
-3. **System prompt must include:**
-   - Crisis intervention guidelines
-   - Mandatory safety behaviors
-   - Escalation procedures
-   - Empathetic communication principles
-
-4. **Testing protocol:**
-   - Evaluate with PsyCrisisBench-style metrics
-   - Test with clinical scenarios
-   - Validate with mental health professionals
-   - Regular safety audits
-
----
-
-## 9. Risks and Limitations
-
-### Critical Risks
-1. **False negatives:** Missing someone in crisis (12-17% rate)
-2. **Over-reliance:** Users may treat AI as substitute for professional help
-3. **Hallucination:** Model may generate inappropriate or harmful advice
-4. **Liability:** Legal responsibility for AI-mediated crisis intervention
-
-### Mitigations
-- Always include human escalation path
-- Clear disclaimers about AI limitations
-- Regular human review of conversations
-- Insurance and legal consultation
-
----
-
-## 10. Key Citations
-
-1. Deng et al. (2025). "Evaluating Large Language Models in Crisis Detection: A Real-World Benchmark from Psychological Support Hotlines." arXiv:2506.01329. PsyCrisisBench.
-
-2. Wiest et al. (2024). "Detection of suicidality from medical text using privacy-preserving large language models." British Journal of Psychiatry, 225(6), 532-537.
-
-3. Holmes et al. (2025). "Applications of Large Language Models in the Field of Suicide Prevention: Scoping Review." J Med Internet Res, 27, e63126.
-
-4. Levkovich & Omar (2024). "Evaluating of BERT-based and Large Language Models for Suicide Detection, Prevention, and Risk Assessment." J Med Syst, 48(1), 113.
-
-5. Shukla et al. (2026). "Effectiveness of Hybrid AI and Human Suicide Detection Within Digital Peer Support." J Clin Med, 15(5), 1929.
-
-6. Qi et al. (2025). "Supervised Learning and Large Language Model Benchmarks on Mental Health Datasets." Bioengineering, 12(8), 882.
-
-7. Liu et al. (2025). "Enhanced large language models for effective screening of depression and anxiety." Commun Med, 5(1), 457.
-
----
-
-## Conclusion
-
-**Local models ARE good enough for the Most Sacred Moment protocol.**
-
-The research is clear:
-- Crisis detection F1 scores of 0.88-0.91 are achievable
-- Fine-tuned small models (1.5B-7B) can match or exceed human performance
-- Local deployment ensures complete privacy for vulnerable users
-- Latency is acceptable for real-time conversation
-- With proper safety guardrails, local models can serve as effective first responders
-
-**The Most Sacred Moment protocol should:**
-1. Use Qwen2.5-7B or similar as primary conversational model
-2. Implement Llama-Guard3 as safety filter
-3. Build in immediate 988 Lifeline escalation
-4. Maintain human oversight and review
-5. Fine-tune on crisis-specific data when possible
-6. Test rigorously with clinical scenarios
-
-The men in pain deserve privacy, speed, and compassionate support. Local models deliver all three.
-
----
-
-*Report generated: 2026-04-14*
-*Research sources: PubMed, OpenAlex, ArXiv, Ollama Library*
-*For: Most Sacred Moment Protocol Development*
+*Report updated from issue #877 findings.*
+*Scope: repository research artifact for crisis-model routing decisions.*

skills/productivity/maps/SKILL.md

@@ -1,199 +0,0 @@
----
-name: maps
-description: >
-  Location intelligence — geocode a place, reverse-geocode coordinates,
-  find nearby places (46 POI categories), driving/walking/cycling
-  distance + time, turn-by-turn directions, timezone lookup, bounding
-  box + area for a named place, and POI search within a rectangle.
-  Uses OpenStreetMap + Overpass + OSRM. Free, no API key.
-version: 1.2.0
-author: Mibayy
-license: MIT
-metadata:
-  hermes:
-    tags: [maps, geocoding, places, routing, distance, directions, nearby, location, openstreetmap, nominatim, overpass, osrm]
-    category: productivity
-    requires_toolsets: [terminal]
-    supersedes: [find-nearby]
----
-
-# Maps Skill
-
-Location intelligence using free, open data sources. 8 commands, 44 POI
-categories, zero dependencies (Python stdlib only), no API key required.
-
-Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.
-
-This skill supersedes the old `find-nearby` skill — all of find-nearby's
-functionality is covered by the `nearby` command below, with the same
-`--near "<place>"` shortcut and multi-category support.
-
-## When to Use
-
-- User sends a Telegram location pin (latitude/longitude in the message) → `nearby`
-- User wants coordinates for a place name → `search`
-- User has coordinates and wants the address → `reverse`
-- User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → `nearby`
-- User wants driving/walking/cycling distance or travel time → `distance`
-- User wants turn-by-turn directions between two places → `directions`
-- User wants timezone information for a location → `timezone`
-- User wants to search for POIs within a geographic area → `area` + `bbox`
-
-## Prerequisites
-
-Python 3.8+ (stdlib only — no pip installs needed).
-
-Script path: `~/.hermes/skills/maps/scripts/maps_client.py`
-
-## Commands
-
-```bash
-MAPS=~/.hermes/skills/maps/scripts/maps_client.py
-```
-
-### search — Geocode a place name
-
-```bash
-python3 $MAPS search "Eiffel Tower"
-python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"
-```
-
-Returns: lat, lon, display name, type, bounding box, importance score.
-
-### reverse — Coordinates to address
-
-```bash
-python3 $MAPS reverse 48.8584 2.2945
-```
-
-Returns: full address breakdown (street, city, state, country, postcode).
-
-### nearby — Find places by category
-
-```bash
-# By coordinates (from a Telegram location pin, for example)
-python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
-python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
-
-# By address / city / zip / landmark — --near auto-geocodes
-python3 $MAPS nearby --near "Times Square, New York" --category cafe
-python3 $MAPS nearby --near "90210" --category pharmacy
-
-# Multiple categories merged into one query
-python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10
-```
-
-46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house,
-camp_site, supermarket, atm, gas_station, parking, museum, park, school,
-university, bank, police, fire_station, library, airport, train_station,
-bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym,
-swimming_pool, post_office, convenience_store, bakery, bookshop, laundry,
-car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground,
-stadium, nightclub.
-
-Each result includes: `name`, `address`, `lat`/`lon`, `distance_m`,
-`maps_url` (clickable Google Maps link), `directions_url` (Google Maps
-directions from the search point), and promoted tags when available —
-`cuisine`, `hours` (opening_hours), `phone`, `website`.
-
-### distance — Travel distance and time
-
-```bash
-python3 $MAPS distance "Paris" --to "Lyon"
-python3 $MAPS distance "New York" --to "Boston" --mode driving
-python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking
-```
-
-Modes: driving (default), walking, cycling. Returns road distance, duration,
-and straight-line distance for comparison.
-
-### directions — Turn-by-turn navigation
-
-```bash
-python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
-python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving
-```
-
-Returns numbered steps with instruction, distance, duration, road name, and
-maneuver type (turn, depart, arrive, etc.).
-
-### timezone — Timezone for coordinates
-
-```bash
-python3 $MAPS timezone 48.8584 2.2945
-python3 $MAPS timezone 35.6762 139.6503
-```
-
-Returns timezone name, UTC offset, and current local time.
-
-### area — Bounding box and area for a place
-
-```bash
-python3 $MAPS area "Manhattan, New York"
-python3 $MAPS area "London"
-```
-
-Returns bounding box coordinates, width/height in km, and approximate area.
-Useful as input for the bbox command.
-
-### bbox — Search within a bounding box
-
-```bash
-python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20
-```
-
-Finds POIs within a geographic rectangle. Use `area` first to get the
-bounding box coordinates for a named place.
-
-## Working With Telegram Location Pins
-
-When a user sends a location pin, the message contains `latitude:` and
-`longitude:` fields. Extract those and pass them straight to `nearby`:
-
-```bash
-# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
-python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500
-```
-
-Present results as a numbered list with names, distances, and the
-`maps_url` field so the user gets a tap-to-open link in chat. For "open
-now?" questions, check the `hours` field; if missing or unclear, verify
-with `web_search` since OSM hours are community-maintained and not always
-current.
-
-## Workflow Examples
-
-**"Find Italian restaurants near the Colosseum":**
-1. `nearby --near "Colosseum Rome" --category restaurant --radius 500`
-   — one command, auto-geocoded
-
-**"What's near this location pin they sent?":**
-1. Extract lat/lon from the Telegram message
-2. `nearby LAT LON cafe --radius 1500`
-
-**"How do I walk from hotel to conference center?":**
-1. `directions "Hotel Name" --to "Conference Center" --mode walking`
-
-**"What restaurants are in downtown Seattle?":**
-1. `area "Downtown Seattle"` → get bounding box
-2. `bbox S W N E restaurant --limit 30`
-
-## Pitfalls
-
-- Nominatim ToS: max 1 req/s (handled automatically by the script)
-- `nearby` requires lat/lon OR `--near "<address>"` — one of the two is needed
-- OSRM routing coverage is best for Europe and North America
-- Overpass API can be slow during peak hours; the script automatically
-  falls back between mirrors (overpass-api.de → overpass.kumi.systems)
-- `distance` and `directions` use `--to` flag for the destination (not positional)
-- If a zip code alone gives ambiguous results globally, include country/state
-
-## Verification
-
-```bash
-python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
-# Should return lat ~40.689, lon ~-74.044
-
-python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
-# Should return a list of restaurants within ~500m of Times Square
-```

tests/skills/test_maps_client.py

@@ -1,135 +0,0 @@
-"""Regression tests for the bundled maps skill."""
-
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-from types import SimpleNamespace
-
-SCRIPT_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "skills/productivity/maps/scripts/maps_client.py"
-)
-SKILL_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "skills/productivity/maps/SKILL.md"
-)
-
-
-def load_module():
-    assert SCRIPT_PATH.exists(), f"missing maps client script: {SCRIPT_PATH}"
-    spec = importlib.util.spec_from_file_location("maps_client_test", SCRIPT_PATH)
-    module = importlib.util.module_from_spec(spec)
-    assert spec.loader is not None
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_maps_skill_files_exist():
-    assert SCRIPT_PATH.exists()
-    assert SKILL_PATH.exists()
-
-
-def test_category_tags_cover_guest_house_camp_site_and_dual_key_bakery():
-    module = load_module()
-
-    assert module.CATEGORY_TAGS["guest_house"] == ("tourism", "guest_house")
-    assert module.CATEGORY_TAGS["camp_site"] == ("tourism", "camp_site")
-    assert module.CATEGORY_TAGS["bakery"] == [
-        ("shop", "bakery"),
-        ("amenity", "bakery"),
-    ]
-    assert module._tags_for("bakery") == [
-        ("shop", "bakery"),
-        ("amenity", "bakery"),
-    ]
-
-
-def test_build_overpass_queries_include_all_supported_tags():
-    module = load_module()
-
-    bakery_query = module.build_overpass_nearby(
-        None,
-        None,
-        40.0,
-        -74.0,
-        500,
-        10,
-        tag_pairs=module._tags_for("bakery"),
-    )
-    assert 'node["shop"="bakery"]' in bakery_query
-    assert 'way["shop"="bakery"]' in bakery_query
-    assert 'node["amenity"="bakery"]' in bakery_query
-    assert 'way["amenity"="bakery"]' in bakery_query
-
-    guest_house_query = module.build_overpass_nearby(
-        None,
-        None,
-        40.0,
-        -74.0,
-        500,
-        10,
-        tag_pairs=module._tags_for("guest_house"),
-    )
-    assert 'node["tourism"="guest_house"]' in guest_house_query
-    assert 'way["tourism"="guest_house"]' in guest_house_query
-
-    camp_site_bbox = module.build_overpass_bbox(
-        None,
-        None,
-        39.0,
-        -75.0,
-        41.0,
-        -73.0,
-        10,
-        tag_pairs=module._tags_for("camp_site"),
-    )
-    assert 'node["tourism"="camp_site"]' in camp_site_bbox
-    assert 'way["tourism"="camp_site"]' in camp_site_bbox
-
-
-def test_cmd_nearby_dedupes_dual_tag_bakery_results(monkeypatch, capsys):
-    module = load_module()
-
-    duplicate_bakery = {
-        "elements": [
-            {
-                "type": "node",
-                "id": 101,
-                "lat": 40.0,
-                "lon": -74.0,
-                "tags": {"name": "Wild Flour", "shop": "bakery"},
-            },
-            {
-                "type": "node",
-                "id": 101,
-                "lat": 40.0,
-                "lon": -74.0,
-                "tags": {"name": "Wild Flour", "amenity": "bakery"},
-            },
-        ]
-    }
-
-    monkeypatch.setattr(module, "overpass_query", lambda query: duplicate_bakery)
-    args = SimpleNamespace(
-        lat="40.0",
-        lon="-74.0",
-        near=None,
-        category="bakery",
-        category_list=[],
-        radius=500,
-        limit=10,
-    )
-
-    module.cmd_nearby(args)
-    out = capsys.readouterr().out
-    assert '"count": 1' in out
-    assert '"Wild Flour"' in out
-
-
-def test_skill_doc_lists_new_categories_and_supersession():
-    text = SKILL_PATH.read_text(encoding="utf-8")
-    assert "guest_house" in text
-    assert "camp_site" in text
-    assert "bakery" in text
-    assert "supersedes: [find-nearby]" in text

tests/test_research_local_model_crisis_quality.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+
+REPORT = Path(__file__).resolve().parent.parent / "research_local_model_crisis_quality.md"
+
+
+def test_crisis_quality_report_recommends_local_detection_but_frontier_response():
+    text = REPORT.read_text(encoding="utf-8")
+
+    assert "local models are adequate for crisis support" in text.lower()
+    assert "not for crisis response generation" in text.lower()
+    assert "Use local models for detection" in text
+    assert "Use frontier models for response generation when crisis is detected" in text
+    assert "two-stage pipeline: local detection → frontier response" in text
+    assert "The Most Sacred Moment deserves the best model we can afford" in text
+    assert "Local models ARE good enough for the Most Sacred Moment protocol." not in text