@telemetryos/cli 1.8.3 → 1.10.0

package/templates/vite-react-typescript/_claude/skills/tos-weather-api/SKILL.md

@@ -1,162 +1,61 @@
 ---
 name: tos-weather-api
-description: Integrate TelemetryOS Weather API for current conditions and forecasts. Use when building weather displays or any app that needs location-based weather data.
+description: Integrate TelemetryOS Weather API for current conditions, forecasts, and alerts. Use when building weather displays or apps needing location-based weather data.
 ---
 
 # TelemetryOS Weather API
 
-The Weather API provides current conditions, hourly forecasts, and daily forecasts for any location.
+Access weather data including current conditions, daily forecasts, hourly forecasts, and severe weather alerts. All responses include both metric and imperial units.
 
-## Quick Reference
-
-```typescript
-import { weather } from '@telemetryos/sdk'
-
-// Current conditions
-const conditions = await weather().getConditions({
-  city: 'New York',
-  units: 'imperial'
-})
-
-// Hourly forecast (next 24 hours)
-const hourly = await weather().getHourlyForecast({
-  city: 'New York',
-  units: 'imperial',
-  hours: 24
-})
-
-// Daily forecast (next 7 days)
-const daily = await weather().getDailyForecast({
-  city: 'New York',
-  units: 'imperial',
-  days: 7
-})
-```
-
-## Location Parameters
-
-Specify location using ONE of these methods:
-
-### By City Name
-
-```typescript
-// City only
-{ city: 'New York' }
-
-// City with country
-{ city: 'London, UK' }
+## Key Concepts
 
-// City with state (US)
-{ city: 'Portland, OR' }
-```
+- **City-based lookup**: Use `getCities()` to search for locations and obtain a `cityId`
+- **Dual-unit responses**: Every response includes both metric (Celsius, km/h) and imperial (Fahrenheit, mph)
+- **No units parameter**: You don't specify units - both are always returned
 
-### By Postal Code
-
-```typescript
-{ postalCode: '10001' }
-```
-
-### By Coordinates
+## Quick Reference
 
 ```typescript
-{ lat: '40.7128', lon: '-74.0060' }
-```
-
-## Units
+import { weather } from '@telemetryos/sdk'
 
-```typescript
-// Fahrenheit, miles, etc.
-{ units: 'imperial' }
+// 1. Search for cities (use in Settings)
+const cities = await weather.getCities({ search: 'Seattle' })
+const cityId = cities[0].cityId
 
-// Celsius, kilometers, etc.
-{ units: 'metric' }
-```
+// 2. Get current conditions
+const conditions = await weather.getConditions({ cityId })
 
-## Response Types
+// 3. Get daily forecast (up to 16 days)
+const daily = await weather.getDailyForecast({ cityId, days: 7 })
 
-### WeatherConditions (Current)
+// 4. Get hourly forecast (up to 120 hours)
+const hourly = await weather.getHourlyForecast({ cityId, hours: 24 })
 
-```typescript
-interface WeatherConditions {
-  EpochTime: number
-  WeatherText: string
-  WeatherIcon: number
-  HasPrecipitation: boolean
-  PrecipitationType: string | null
-  IsDayTime: boolean
-  Temperature: {
-    Metric: { Value: number; Unit: string }
-    Imperial: { Value: number; Unit: string }
-  }
-  RealFeelTemperature: {
-    Metric: { Value: number; Unit: string }
-    Imperial: { Value: number; Unit: string }
-  }
-  RelativeHumidity: number
-  Wind: {
-    Direction: { Degrees: number; English: string }
-    Speed: {
-      Metric: { Value: number; Unit: string }
-      Imperial: { Value: number; Unit: string }
-    }
-  }
-  UVIndex: number
-  UVIndexText: string
-  Visibility: {
-    Metric: { Value: number; Unit: string }
-    Imperial: { Value: number; Unit: string }
-  }
-  CloudCover: number
-  Pressure: {
-    Metric: { Value: number; Unit: string }
-    Imperial: { Value: number; Unit: string }
-  }
-}
+// 5. Get weather alerts
+const alerts = await weather.getAlerts({ cityId })
 ```
 
-### WeatherForecast (Hourly/Daily)
-
-```typescript
-interface WeatherForecast {
-  DateTime: string
-  EpochDateTime: number
-  WeatherIcon: number
-  IconPhrase: string
-  HasPrecipitation: boolean
-  PrecipitationType?: string
-  PrecipitationIntensity?: string
-  IsDaylight: boolean
-  Temperature: {
-    Value: number
-    Unit: string
-  }
-  RealFeelTemperature: {
-    Value: number
-    Unit: string
-  }
-  Wind: {
-    Speed: { Value: number; Unit: string }
-    Direction: { Degrees: number; English: string }
-  }
-  RelativeHumidity: number
-  PrecipitationProbability: number
-}
-```
+## City Selection Pattern
 
-## Complete Example
+Cities are selected in Settings, weather is displayed in Render. This is the standard workflow.
 
-### Settings (City + Units Selection)
+### Store Hook
 
 ```typescript
 // hooks/store.ts
 import { createUseInstanceStoreState } from '@telemetryos/sdk/react'
 
-export const useCityState = createUseInstanceStoreState<string>('city', '')
-export const useUnitsState = createUseInstanceStoreState<'imperial' | 'metric'>('units', 'imperial')
+// Store the cityId (number) - NOT the city name
+export const useCityIdState = createUseInstanceStoreState<number | null>('cityId', null)
+export const useCityNameState = createUseInstanceStoreState<string>('cityName', '')
 ```
 
+### Settings - City Search & Select
+
 ```typescript
 // views/Settings.tsx
+import { useState, useEffect } from 'react'
+import { weather, WeatherCity } from '@telemetryos/sdk'
 import {
   SettingsContainer,
   SettingsField,
@@ -164,86 +63,113 @@ import {
   SettingsInputFrame,
   SettingsSelectFrame,
 } from '@telemetryos/sdk/react'
-import { useCityState, useUnitsState } from '../hooks/store'
+import { useCityIdState, useCityNameState } from '../hooks/store'
 
 export default function Settings() {
-  const [isLoadingCity, city, setCity] = useCityState()
-  const [isLoadingUnits, units, setUnits] = useUnitsState()
+  const [isLoadingId, cityId, setCityId] = useCityIdState()
+  const [isLoadingName, cityName, setCityName] = useCityNameState()
+
+  const [searchQuery, setSearchQuery] = useState('')
+  const [searchResults, setSearchResults] = useState<WeatherCity[]>([])
+  const [isSearching, setIsSearching] = useState(false)
+
+  // Search for cities when query changes
+  useEffect(() => {
+    if (searchQuery.length < 2) {
+      setSearchResults([])
+      return
+    }
+
+    const searchCities = async () => {
+      setIsSearching(true)
+      try {
+        const cities = await weather.getCities({ search: searchQuery })
+        setSearchResults(cities.slice(0, 10)) // Limit results
+      } catch (err) {
+        console.error('City search failed:', err)
+      } finally {
+        setIsSearching(false)
+      }
+    }
+
+    // Debounce search
+    const timer = setTimeout(searchCities, 300)
+    return () => clearTimeout(timer)
+  }, [searchQuery])
+
+  const handleCitySelect = (city: WeatherCity) => {
+    setCityId(city.cityId)
+    // Store display name for UI
+    const displayName = city.stateName
+      ? `${city.cityName}, ${city.stateCode || city.stateName}`
+      : `${city.cityName}, ${city.countryCode}`
+    setCityName(displayName)
+    setSearchQuery('')
+    setSearchResults([])
+  }
 
   return (
     <SettingsContainer>
       <SettingsField>
         <SettingsLabel>City</SettingsLabel>
+        {cityName && <p style={{ margin: '4px 0 8px' }}>Selected: {cityName}</p>}
         <SettingsInputFrame>
           <input
             type="text"
-            placeholder="Enter city name..."
-            disabled={isLoadingCity}
-            value={city}
-            onChange={(e) => setCity(e.target.value)}
+            placeholder="Search for a city..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
           />
         </SettingsInputFrame>
-      </SettingsField>
-
-      <SettingsField>
-        <SettingsLabel>Temperature Units</SettingsLabel>
-        <SettingsSelectFrame>
-          <select
-            disabled={isLoadingUnits}
-            value={units}
-            onChange={(e) => setUnits(e.target.value as 'imperial' | 'metric')}
-          >
-            <option value="imperial">Fahrenheit</option>
-            <option value="metric">Celsius</option>
-          </select>
-        </SettingsSelectFrame>
+        {searchResults.length > 0 && (
+          <SettingsSelectFrame>
+            <select
+              size={Math.min(searchResults.length, 5)}
+              onChange={(e) => {
+                const city = searchResults.find(c => c.cityId === Number(e.target.value))
+                if (city) handleCitySelect(city)
+              }}
+            >
+              {searchResults.map(city => (
+                <option key={city.cityId} value={city.cityId}>
+                  {city.cityName}, {city.stateCode || city.stateName || city.countryCode}
+                </option>
+              ))}
+            </select>
+          </SettingsSelectFrame>
+        )}
       </SettingsField>
     </SettingsContainer>
   )
 }
 ```
 
-### Render (Weather Display)
+### Render - Weather Display
 
 ```typescript
 // views/Render.tsx
 import { useEffect, useState } from 'react'
-import { weather } from '@telemetryos/sdk'
-import { useCityState, useUnitsState } from '../hooks/store'
-
-interface WeatherData {
-  temperature: number
-  description: string
-  humidity: number
-  windSpeed: number
-}
+import { weather, WeatherConditions } from '@telemetryos/sdk'
+import { useCityIdState, useCityNameState } from '../hooks/store'
 
 export default function Render() {
-  const [isLoadingCity, city] = useCityState()
-  const [isLoadingUnits, units] = useUnitsState()
+  const [isLoadingId, cityId] = useCityIdState()
+  const [isLoadingName, cityName] = useCityNameState()
 
-  const [data, setData] = useState<WeatherData | null>(null)
+  const [conditions, setConditions] = useState<WeatherConditions | null>(null)
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<string | null>(null)
 
   useEffect(() => {
-    if (isLoadingCity || isLoadingUnits || !city) return
+    if (isLoadingId || !cityId) return
 
     const fetchWeather = async () => {
       setLoading(true)
       setError(null)
 
       try {
-        const conditions = await weather().getConditions({ city, units })
-
-        const tempKey = units === 'imperial' ? 'Imperial' : 'Metric'
-
-        setData({
-          temperature: conditions.Temperature[tempKey].Value,
-          description: conditions.WeatherText,
-          humidity: conditions.RelativeHumidity,
-          windSpeed: conditions.Wind.Speed[tempKey].Value,
-        })
+        const data = await weather.getConditions({ cityId })
+        setConditions(data)
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to fetch weather')
       } finally {
@@ -253,132 +179,380 @@ export default function Render() {
 
     fetchWeather()
 
-    // Refresh every 10 minutes
-    const interval = setInterval(fetchWeather, 10 * 60 * 1000)
+    // Refresh every 15 minutes
+    const interval = setInterval(fetchWeather, 15 * 60 * 1000)
     return () => clearInterval(interval)
-  }, [city, units, isLoadingCity, isLoadingUnits])
+  }, [cityId, isLoadingId])
 
   // Loading states
-  if (isLoadingCity || isLoadingUnits) return <div>Loading config...</div>
-  if (!city) return <div>Configure city in Settings</div>
-  if (loading && !data) return <div>Loading weather...</div>
-  if (error && !data) return <div>Error: {error}</div>
-
-  const unitSymbol = units === 'imperial' ? '°F' : '°C'
-  const speedUnit = units === 'imperial' ? 'mph' : 'km/h'
+  if (isLoadingId || isLoadingName) return <div>Loading config...</div>
+  if (!cityId) return <div>Configure city in Settings</div>
+  if (loading && !conditions) return <div>Loading weather...</div>
+  if (error && !conditions) return <div>Error: {error}</div>
+  if (!conditions) return null
 
   return (
     <div className="weather-display">
-      <h1>{city}</h1>
-      {data && (
-        <>
-          <div className="temperature">
-            {Math.round(data.temperature)}{unitSymbol}
-          </div>
-          <div className="description">{data.description}</div>
-          <div className="details">
-            <span>Humidity: {data.humidity}%</span>
-            <span>Wind: {data.windSpeed} {speedUnit}</span>
-          </div>
-        </>
-      )}
+      <h1>{cityName || conditions.cityName}</h1>
+      <div className="temperature">
+        {Math.round(conditions.temperatureC)}°C / {Math.round(conditions.temperatureF)}°F
+      </div>
+      <div className="description">{conditions.weatherDescription}</div>
+      <div className="details">
+        <span>Feels like: {Math.round(conditions.temperatureFeelsLikeC)}°C</span>
+        <span>Humidity: {conditions.humidity}%</span>
+        <span>Wind: {conditions.windSpeedKph} km/h {conditions.windDirectionShort}</span>
+      </div>
     </div>
   )
 }
 ```
 
-## Forecast Example
+## Methods
+
+### getCities()
+
+Search for cities by name or country code to obtain a `cityId`.
 
 ```typescript
-import { weather } from '@telemetryos/sdk'
+type CitiesSearchParams = {
+  countryCode?: string  // ISO country code (e.g., "US", "CA")
+  search?: string       // City name (case-insensitive prefix match)
+}
+
+const cities = await weather.getCities({ search: 'Vancouver' })
+const cities = await weather.getCities({ search: 'Portland', countryCode: 'US' })
+```
+
+### getConditions()
+
+Get current weather conditions for a city.
+
+```typescript
+type WeatherConditionsParams = {
+  cityId: number       // Required - from getCities()
+  language?: string    // Language code for localized descriptions
+}
+
+const conditions = await weather.getConditions({ cityId: 5128581 })
+```
+
+### getDailyForecast()
+
+Get daily forecast for up to 16 days.
+
+```typescript
+type DailyForecastParams = {
+  cityId: number
+  language?: string
+  days?: number        // Default: 5, Max: 16
+}
+
+const forecast = await weather.getDailyForecast({ cityId: 5128581, days: 7 })
 
-// Get 5-day forecast
-const forecast = await weather().getDailyForecast({
-  city: 'New York',
-  units: 'imperial',
-  days: 5
+forecast.data.forEach(day => {
+  console.log(`${day.forecastDate}: ${day.weatherDescription}`)
+  console.log(`  High: ${day.maxTemperatureC}°C / ${day.maxTemperatureF}°F`)
+  console.log(`  Low: ${day.minTemperatureC}°C / ${day.minTemperatureF}°F`)
+  console.log(`  Precip: ${day.precipitationProbability}%`)
 })
+```
+
+### getHourlyForecast()
+
+Get hourly forecast for up to 120 hours.
+
+```typescript
+type HourlyForecastParams = {
+  cityId: number
+  language?: string
+  hours?: number       // Default: 12, Max: 120
+}
+
+const forecast = await weather.getHourlyForecast({ cityId: 5128581, hours: 24 })
 
-forecast.forEach(day => {
-  console.log(`${day.DateTime}: ${day.Temperature.Value}° - ${day.IconPhrase}`)
+forecast.data.forEach(hour => {
+  console.log(`${hour.forecastTimeLocal}: ${hour.temperatureC}°C`)
+  console.log(`  ${hour.weatherDescription}`)
 })
 ```
 
-## Weather Icons
+### getAlerts()
+
+Get severe weather alerts and warnings.
+
+```typescript
+type WeatherAlertsParams = {
+  cityId: number
+  language?: string
+}
+
+const result = await weather.getAlerts({ cityId: 5128581 })
+
+if (result.alerts.length > 0) {
+  result.alerts.forEach(alert => {
+    console.log(`[${alert.severity}] ${alert.title}`)
+    console.log(`  Effective: ${alert.effectiveLocal}`)
+    console.log(`  Expires: ${alert.expiresLocal}`)
+  })
+}
+```
+
+## Response Types
+
+### WeatherCity
+
+```typescript
+type WeatherCity = {
+  cityId: number          // Use this for weather queries
+  cityName: string
+  stateName?: string      // Full state/province name
+  stateCode?: string      // US only: "WA", "CA", etc.
+  countryName: string
+  countryCode: string     // ISO code: "US", "CA", etc.
+  latitude: number
+  longitude: number
+}
+```
+
+### WeatherConditions
+
+```typescript
+type WeatherConditions = {
+  // Location
+  latitude: number
+  longitude: number
+  cityName: string
+  stateName?: string
+  stateCode?: string      // US only
+  countryName: string
+  countryCode: string
+  timezone: string        // IANA timezone
+
+  // Time
+  observedAtSec: number   // Unix timestamp
+  observedAtLocal: string // "2025-01-15T14:30:00-08:00"
+  sunrise: string         // "07:23"
+  sunset: string          // "17:45"
+  partOfDay: 'day' | 'night'
+
+  // Weather
+  weatherCode: number
+  weatherDescription: string
+  weatherIcon: string
+
+  // Temperature (dual-unit)
+  temperatureC: number
+  temperatureF: number
+  temperatureFeelsLikeC: number
+  temperatureFeelsLikeF: number
+  dewPointC: number
+  dewPointF: number
+
+  // Wind (dual-unit)
+  windSpeedKph: number
+  windSpeedMph: number
+  gustSpeedKph: number
+  gustSpeedMph: number
+  windDirectionDeg: number
+  windDirectionFull: string   // "North-Northwest"
+  windDirectionShort: string  // "NNW"
+
+  // Atmospheric (dual-unit)
+  pressureMb: number
+  pressureInHg: number
+  visibilityKm: number
+  visibilityMi: number
+  humidity: number        // Percentage
+  clouds: number          // Percentage
+
+  // Precipitation (dual-unit)
+  precipitationRateMmph: number
+  precipitationRateInph: number
+  snowfallRateMmph: number
+  snowfallRateInph: number
+
+  // Indices
+  uvIndex: number
+  airQualityIndex: number
+}
+```
+
+### DailyForecastData
+
+```typescript
+type DailyForecastData = {
+  forecastDate: string      // "2025-01-15"
+  forecastDateSec: number   // Unix timestamp
+
+  // Weather
+  weatherCode: number
+  weatherDescription: string
+  weatherIcon: string
+  precipitationProbability: number  // 0-100
+
+  // Temperature (dual-unit)
+  temperatureC: number      // Average
+  temperatureF: number
+  maxTemperatureC: number
+  maxTemperatureF: number
+  minTemperatureC: number
+  minTemperatureF: number
+  highTemperatureC: number  // Daytime high
+  highTemperatureF: number
+  lowTemperatureC: number   // Nighttime low
+  lowTemperatureF: number
+
+  // Wind, Atmospheric, Precipitation - same pattern as conditions
+
+  // Moon/Sun
+  sunrise: string
+  sunset: string
+  moonrise: string
+  moonset: string
+  moonIllumination: number  // 0-1 fraction
+  moonLunationPhase: number // 0=New, 0.5=Full
+}
+```
+
+### HourlyForecastData
+
+```typescript
+type HourlyForecastData = {
+  forecastTimeSec: number     // Unix timestamp
+  forecastTimeLocal: string   // "2025-01-15T15:00:00-08:00"
+  forecastTimeUtc: string     // "2025-01-15T23:00:00Z"
+  partOfDay: 'day' | 'night'
+
+  // Weather
+  weatherCode: number
+  weatherDescription: string
+  weatherIcon: string
+  precipitationProbability: number
+
+  // Temperature, Wind, Atmospheric, Precipitation - same pattern as conditions
+}
+```
 
-The API returns `WeatherIcon` as a number (1-44). Map to your icon set:
+### WeatherAlert
 
 ```typescript
-const iconMap: Record<number, string> = {
-  1: 'sunny',
-  2: 'mostly-sunny',
-  3: 'partly-sunny',
-  4: 'intermittent-clouds',
-  5: 'hazy-sunshine',
-  6: 'mostly-cloudy',
-  7: 'cloudy',
-  8: 'dreary',
-  11: 'fog',
-  12: 'showers',
-  13: 'mostly-cloudy-showers',
-  14: 'partly-sunny-showers',
-  15: 'thunderstorms',
-  16: 'mostly-cloudy-thunderstorms',
-  17: 'partly-sunny-thunderstorms',
-  18: 'rain',
-  19: 'flurries',
-  20: 'mostly-cloudy-flurries',
-  21: 'partly-sunny-flurries',
-  22: 'snow',
-  23: 'mostly-cloudy-snow',
-  24: 'ice',
-  25: 'sleet',
-  26: 'freezing-rain',
-  29: 'rain-and-snow',
-  30: 'hot',
-  31: 'cold',
-  32: 'windy',
-  33: 'clear-night',
-  34: 'mostly-clear-night',
-  35: 'partly-cloudy-night',
-  36: 'intermittent-clouds-night',
-  37: 'hazy-moonlight',
-  38: 'mostly-cloudy-night',
-  39: 'partly-cloudy-showers-night',
-  40: 'mostly-cloudy-showers-night',
-  41: 'partly-cloudy-thunderstorms-night',
-  42: 'mostly-cloudy-thunderstorms-night',
-  43: 'mostly-cloudy-flurries-night',
-  44: 'mostly-cloudy-snow-night',
+type WeatherAlertSeverity = 'Advisory' | 'Watch' | 'Warning'
+
+type WeatherAlert = {
+  title: string
+  description: string
+  severity: WeatherAlertSeverity
+
+  // Times
+  effectiveSec: number
+  effectiveUtc: string
+  effectiveLocal: string
+  expiresSec: number
+  expiresUtc: string
+  expiresLocal: string
+  onsetSec?: number       // When event starts (optional)
+  onsetLocal?: string
+  endsSec?: number        // When event ends (optional)
+  endsLocal?: string
+
+  uri: string             // Link for more info
+  regions: string[]       // Affected regions
 }
+```
+
+## Forecast Display Example
+
+```typescript
+// 5-Day Forecast Component
+import { useEffect, useState } from 'react'
+import { weather, DailyForecastData } from '@telemetryos/sdk'
+import { useCityIdState } from '../hooks/store'
 
-function getIconName(iconNumber: number): string {
-  return iconMap[iconNumber] || 'unknown'
+export default function FiveDayForecast() {
+  const [, cityId] = useCityIdState()
+  const [forecast, setForecast] = useState<DailyForecastData[]>([])
+
+  useEffect(() => {
+    if (!cityId) return
+    weather.getDailyForecast({ cityId, days: 5 })
+      .then(result => setForecast(result.data))
+  }, [cityId])
+
+  return (
+    <div className="forecast-row">
+      {forecast.map(day => (
+        <div key={day.forecastDate} className="forecast-day">
+          <div className="date">
+            {new Date(day.forecastDate).toLocaleDateString('en-US', { weekday: 'short' })}
+          </div>
+          <div className="high">{Math.round(day.maxTemperatureC)}°</div>
+          <div className="low">{Math.round(day.minTemperatureC)}°</div>
+          <div className="description">{day.weatherDescription}</div>
+        </div>
+      ))}
+    </div>
+  )
 }
 ```
 
-## Error Handling
+## Weather Alerts Example
 
 ```typescript
-try {
-  const conditions = await weather().getConditions({ city, units })
-} catch (err) {
-  if (err instanceof Error) {
-    if (err.message.includes('timeout')) {
-      // Request timed out (30 second limit)
-    } else if (err.message.includes('not found')) {
-      // City not found
-    } else {
-      // Other error
+// Alert Banner Component
+import { useEffect, useState } from 'react'
+import { weather, WeatherAlert } from '@telemetryos/sdk'
+import { useCityIdState } from '../hooks/store'
+
+export default function AlertBanner() {
+  const [, cityId] = useCityIdState()
+  const [alerts, setAlerts] = useState<WeatherAlert[]>([])
+
+  useEffect(() => {
+    if (!cityId) return
+
+    const fetchAlerts = async () => {
+      const result = await weather.getAlerts({ cityId })
+      setAlerts(result.alerts)
     }
-  }
+
+    fetchAlerts()
+    const interval = setInterval(fetchAlerts, 15 * 60 * 1000)
+    return () => clearInterval(interval)
+  }, [cityId])
+
+  if (alerts.length === 0) return null
+
+  // Show most severe alert
+  const severe = alerts.find(a => a.severity === 'Warning')
+    || alerts.find(a => a.severity === 'Watch')
+    || alerts[0]
+
+  return (
+    <div className={`alert-banner alert-${severe.severity.toLowerCase()}`}>
+      <strong>{severe.severity}:</strong> {severe.title}
+    </div>
+  )
 }
 ```
 
+## Weather Codes
+
+The `weatherCode` field uses WeatherBit condition codes. For the complete list, see: https://www.weatherbit.io/api/codes
+
+Common codes:
+- 800: Clear sky
+- 801-804: Clouds (few to overcast)
+- 500-531: Rain
+- 600-623: Snow
+- 200-233: Thunderstorm
+
 ## Tips
 
-1. **Cache results** - Weather doesn't change rapidly; refresh every 10-30 minutes
-2. **Handle loading** - Show skeleton or spinner while fetching
-3. **Show stale data** - Display last known data while refreshing
-4. **Validate city** - Weather API may fail for invalid city names
-5. **Use coordinates** - More reliable than city names for precise locations
+1. **Store cityId, not city name** - The cityId is required for all weather methods
+2. **Refresh appropriately** - Current conditions every 15 minutes, forecasts every 30-60 minutes
+3. **Show stale data while refreshing** - Don't clear the display during background updates
+4. **Handle no city selected** - Show a helpful message directing users to Settings
+5. **Use both units when helpful** - Digital signage often serves diverse audiences
+6. **Check for alerts** - Weather warnings are important for public displays
+7. **Use partOfDay** - Adjust UI styling for day vs night conditions