Stellarhound — stargazing forecasts, dark-sky sites & aurora

Recommend dark-sky sites near a location, ranked by whether the drive is worth it. Use for "where should I drive to stargaze near X". Sites are grouped by drivability (how far), then ranked by a drive-worth score combining the best weather window over the next 7 nights, how much darker the site is than the user's location, and drive time. Drive times are approximate (straight-line x 1.3), not routed. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). limit: Max sites to return, 1-12 (default 5). Returns {ranking (methodology note), tiers:[{tier, label, hint, sites:[...]}], nearest_km, uncertainty_note, attribution} — sites grouped into drivability tiers. Include the methodology note when presenting — it explains the ordering honestly.

Get the aurora (northern/southern lights) outlook for a location. Use for "any chance of aurora tonight near X". Combines the Kp-index forecast with the location's geomagnetic latitude to say whether aurora could be visible there, and when. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). Returns {kp_forecast:[{time, kp, flag: observed|estimated|predicted}, ...], visibility assessment fields, attribution}. Kp entries are flagged by how firm they are — keep those labels when presenting.

Estimate light pollution at any point: approximate Bortle class and what's visible there. Use for "how dark is the sky at X" / "can I see the Milky Way from X". Returns the zenith-brightness-derived estimate (mpsas, approximate Bortle class) and a plain-language ceiling: what the Milky Way, naked-eye and telescope views are like under that sky. This is a satellite-data estimate, not a field measurement — say so. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). Returns {light_pollution:{bortle_approx, mpsas, ceiling:{label, milky_way, naked_eye, telescope}, note}, attribution}.

Score the next nights for stargazing at a location (0-100 per night). Use for "when should I stargaze this week near X", "is Saturday any good for the Milky Way", trip planning. Each night combines the three-layer cloud-cover forecast, moon illumination and up-fraction, and the astronomical-darkness window; `best_window` names the best upcoming night. Also returns the location's light-pollution estimate (approximate Bortle class + what's visible at that darkness). Args: lat: Latitude in decimal degrees (-90..90). You know city coordinates — pass them. lon: Longitude in decimal degrees (-180..180). nights: How many nights ahead to score, 1-16 (default 7; forecasts beyond ~7 nights are increasingly uncertain). Returns {timezone, light_pollution, nights:[{date, darkness, moon, cloud, score:{value, band, summary}}], best_window, uncertainty_note, attribution}. Present scores/verdicts verbatim; skies beyond ~7 days are provisional.

Get tonight's stargazing plan for a location: score, darkness window, and what to observe. Use when the user asks "what can I see tonight" / "is tonight worth going out". Returns tonight's sky score and darkness window plus a ranked agenda of observing targets appropriate for the location's sky darkness. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). Returns {timezone, light_pollution, tonight:{date, darkness, weather,...}, targets/agenda entries, attribution}. Report as returned.