Look Up

Use when a Look Up user asks about comets ("any comets?"), eclipses ("next eclipse?", "will I see the eclipse?"), meteor showers ("when are the Perseids?", "best time for the Geminids?"), or what their binoculars or telescope can show tonight. Also the reference for viewing-gear limits. Comets come from MPC orbital elements, and there's a 2026-2030 eclipse table with local visibility.

Look Up's vetted fact library for satellites, stations, planets, the Moon and its phases, the Sun, comets, aurora, eclipses and launches, with the rotation that gives every Look Up message exactly one fact and avoids repeats for about 14 days. Use when a Look Up user asks for "another fact" or whether a fact is true.

Use FIRST on any message (even "hi", a question, or a photo) when Look Up isn't set up yet, meaning /workspace/look-up/config.json is missing, has no home, or onboarded is false. Also use for "set me up" or "start over". Starts onboarding on its own, with no setup command needed. Steps: a sky photo for location (installs the engine in the background), a real "From your yard tonight" preview, three tap-to-answer widgets (what to watch, viewing gear, outside hours), then the routines and tonight's sky map.

Use when a Look Up user asks "what's the best thing to see this week?", "anything big coming up?", or "what should I not miss?". It also powers the "Your first big one" line that ends every onboarding and home-reset preview. It picks the single best sight in the next 7 to 14 days by a wow ranking, checks the weather, and returns the one-shot reminder for it.

Use when a Look Up user permanently changes their home sky: "reset my location", "new home", "I moved", "we moved to <place>", or a new photo sent with "this is my new spot". Also use for "show settings" and "where am I set to?". Replaces home, re-checks obstructions, reschedules the routines if the time zone changed, and confirms with a fresh tonight preview. Travel is separate (look-up-settings).

Use when a Look Up routine fires (the daily sky check, a "Look Up one-shot" reminder or look-now, or the nightly moon note), or when the user asks "anything tonight?", "what's up tonight?", "remind me", or "when's the next ISS pass?". Computes tonight's sky for their location and viewing gear (passes, moon, planets, meteors, aurora, bright comets, eclipses, daytime moon and Venus), labels each moment daytime/twilight/night, stays quiet when it's cloudy or nothing's worth it, sends at most one heads-up, and schedules short-lived reminders.

Use when a Look Up user changes settings: "pause alerts", "resume", "only ISS", "all alerts", "moon off", "moon on", "moon at 9:15", "change my hours", "telescope on", "binoculars", "naked eye only", "trees block the east", "help", "test mode", or temporary travel ("I'm at <place> this week", a dropped map pin, "back home"). A permanent move or "show settings" goes to look-up-home.

Look Up's vetted facts for the 21 constellations of the week, their bright stars, and the 12 annual meteor showers (engine file facts_sky.py, used by look-up-facts). Use when a Look Up user asks about a constellation, a bright star, or a meteor shower.

Use when a Look Up user asks for a sky map, a card, or a picture of where to look (for a pass, tonight's main event, or the constellation of the week), or when another Look Up skill attaches a card.

Look Up's message wording: the engine's words.py writes every heads-up, reminder, look-now, moon note, weekly rundown and preview in Look Up's planetarium-guide voice. Use when a Look Up user asks to change how messages are worded.

Use when the Look Up Sunday rundown routine fires, or when the user asks "what's up this week?", "this week's sky", or for the constellation of the week. Sends one message: the week's best passes, moon phases, planets, constellation of the week with a sky map, meteor, comet, eclipse and aurora outlook, binocular or telescope sights for their gear, and a weather caveat.

Use when a Look Up user asks what a light in the sky is ("what's that bright light in the west?", "is that a planet?", "what am I looking at?"), optionally with a direction, height, brightness, whether it is moving or blinking, or a photo of the sky.