Quill Radio -- Product Requirements

Version 2.0

1. Product statement

Quill Radio is QUILL's internet radio, shipped as its own small Windows app for people who want the radio on without loading a full writing environment. It is screen-reader-first, keyboard-complete, and deliberately small -- and by 1.0 it is a complete radio product: organization, recording resilience, timers, and appliance-grade startup.

2. Architecture requirement: not a fork

3. Scope (all reused from upstream; all shipped in 1.0)

Listening

Organization

Recording

Timers

Shell

Out of scope by decision: QUILL's editor, AI, speech transcription, braille, and TTS stacks (not installed); a custom update engine beyond download-and-run.

4. Accessibility requirements

5. Packaging requirements

6. Network requirements

7. Non-goals

macOS/Linux standalone builds (upstream QUILL covers macOS; the tray pattern does not exist there), auto-updating in place, telemetry. A full DSP effects rack (reverb, tempo/pitch, spatial audio) -- Sound Enhancements (§8) is a small, purpose-built three-band EQ and compressor, not a general effects rack.

8. Since 1.0

See CHANGELOG.md for the full, versioned history.

9. QUILL Weather -- full product requirements

The following is the complete QUILL Weather product-requirements document. The Weather menu shipped in 2.1.0 implements its text-only first slice; the sections below describe the full roadmap.

QUILL Weather

Product Requirements Document

Working title: QUILL Weather
Ecosystem: QUILL / QuillVille
Document status: Product definition and implementation-ready working draft
Version: 1.0
Date: July 19, 2026
Primary platforms: Windows first; macOS next; iOS considered in later phases
Product posture: Accessibility-first, screen-reader-first, keyboard-first, local-first, provider-based, safety-conscious

1. Executive Summary

QUILL Weather transforms official weather data into an immediate, understandable, highly configurable, and delightfully accessible weather experience.

It is not merely a weather screen. It is a persistent Weather Guardian, an accessible Weather Center, a flexible audio weather channel generator, a location-aware Alert Center, and a deeply configurable Voice Studio built on the QUILL speech framework.

A user should be able to:

  1. Add a home, work, family, travel, event, or temporary location in seconds.
  2. Hear current conditions immediately.
  3. Receive watches, warnings, advisories, updates, and cancellations as soon as QUILL receives them.
  4. Continue receiving alerts while the main QUILL window is closed, provided QUILL Weather Guardian is running.
  5. Assign different voices, engines, rates, volumes, earcons, verbosity levels, and interruption rules to different weather feeds and alert scenarios.
  6. Build continuous generated audio channels from authoritative weather data.
  7. Listen to a live community NOAA Weather Radio stream when one is available.
  8. Understand where every piece of weather information came from, when it was issued, when it was last checked, and whether it may be stale.
  9. Use every major feature without sight, without a mouse, and without needing to interpret a visual map.

The initial primary data provider will be the United States National Weather Service at api.weather.gov. The NWS API provides forecasts, hourly forecasts, observations, alerts, zones, stations, and grid data as open government data. It is cache-aware, supports conditional requests, and requires an identifying User-Agent. NWS recommends requesting alert updates no more frequently than every 30 seconds.

For faster alerts, a later QUILL Alert Relay can subscribe to the NOAA Weather Wire Service Open Interface. NWS describes NWWS as its fastest method for receiving text alerts and weather products, generally within 10 seconds of issuance. The relay will reconcile those pushed products with the public NWS alerts API and deliver normalized updates to subscribed QUILL clients.

QUILL Weather must never imply that it replaces Wireless Emergency Alerts, a physical NOAA Weather Radio, local emergency instructions, or other official safety channels. It is an additional accessible delivery and interpretation tool.

2. Product Vision

2.1 Vision statement

Weather should never be hidden behind a map, buried in a dashboard, delayed by an inaccessible workflow, or spoken in a voice the user cannot understand.

QUILL Weather meets people where they are. It provides as much or as little weather information as the user wants, in the voice they choose, for the places and people they care about.

2.2 Product promise

QUILL Weather makes five promises:

Everything can be reached

Every location, alert, forecast period, setting, history item, source status, and audio control is keyboard accessible and represented through native or predictably accessible controls.

Important state is never hidden

An alert’s status, severity, urgency, certainty, effective time, expiration, affected area, source, update history, and delivery state are available as text and speech. Color, icon, animation, and screen position are never the only means of conveying meaning.

Official information remains official

QUILL preserves the source alert, its identifiers, its lifecycle, and its authoritative text. QUILL may organize or deterministically summarize information, but it will not silently rewrite emergency instructions.

The user controls the voice

Different weather content can use different QUILL speech providers, voices, rates, pitches, volumes, pronunciation dictionaries, earcons, and interruption behaviors.

Fast does not mean careless

QUILL prioritizes alert speed while using deduplication, update reconciliation, source freshness, delivery logging, and transparent fallback behavior.

3. Goals

3.1 Primary goals

  1. Provide fast access to official current conditions, forecasts, and alerts.
  2. Keep monitoring selected locations while QUILL Weather Guardian is running.
  3. Deliver new, updated, escalated, downgraded, extended, and cancelled alerts without forcing the user to open the main window.
  4. Allow unlimited saved locations, subject only to practical local storage and service limits.
  5. Support location groups and multi-location weather feeds.
  6. Generate highly configurable spoken weather channels from structured data.
  7. Provide per-feed, per-content, per-location, and per-alert speech scenarios.
  8. Integrate naturally with the existing QUILL speech provider and voice framework.
  9. Preserve raw provider data and normalize it into a stable internal weather model.
  10. Work without a QUILL account in local mode.
  11. Use QuilleSync optionally for encrypted synchronization of saved locations, feed definitions, voice mappings, alert rules, and preferences.
  12. Support live NOAA Weather Radio stream catalog entries without making live audio a prerequisite for weather or alert availability.
  13. Provide strong diagnostics and a human-readable event history.

3.2 Success measures

QUILL Weather will be considered successful when:

4. Non-Goals

The initial product will not:

  1. Claim to be a certified emergency warning receiver.
  2. Replace Wireless Emergency Alerts, local emergency management, a physical NOAA Weather Radio, or instructions from public safety officials.
  3. Activate the Emergency Alert System.
  4. Generate meteorological predictions independent of official providers.
  5. Use generative AI to rewrite life-safety instructions as the only presented version.
  6. Promise a live NOAA audio stream for every city or transmitter.
  7. Require an account, subscription, or cloud relay for basic weather access.
  8. Require visual map interaction.
  9. Attempt to provide global forecast coverage in the first release.
  10. Store continuous precise-location history by default.
  11. Treat all provider values as equally current or equally reliable.
  12. Infer missing observations or alert instructions and present the inference as source data.

5. Product Components

5.1 QUILL Weather Center

The main accessible weather workspace.

Primary sections:

The Weather Center will use a simple semantic structure with predictable headings, lists, property views, and command menus. Users can choose a compact view or detailed view.

5.2 Weather Guardian

A lightweight background process responsible for:

Weather Guardian starts with the user only when explicitly enabled. It does not require administrator privileges.

Closing the Weather Center does not close Weather Guardian. Exiting Weather Guardian requires an explicit Exit Monitoring command.

5.3 Weather Channels

A Weather Channel is a generated audio feed assembled from selected structured content.

Example channel:

  1. Channel identification
  2. Active critical alerts
  3. Current conditions
  4. Next six hours
  5. Today and tonight
  6. Extended forecast
  7. Hazardous weather outlook
  8. NOAA Weather Radio transmitter information
  9. Last-update status
  10. Repeat after a configured interval

Channels can be played on demand or continuously. New alerts can interrupt or queue according to the channel’s alert policy.

5.4 Alert Center

A complete, searchable history and current-state view for all monitored locations.

It distinguishes:

The Alert Center preserves alert revisions and clearly identifies what changed.

5.5 Voice Studio

The configuration surface for weather speech scenarios.

Voice Studio allows the user to assign voices and behaviors by:

5.6 NOAA Weather Radio Explorer

A searchable transmitter and stream catalog containing:

QUILL must clearly differentiate:

6. Core User Experiences

6.1 First launch

On first launch, QUILL Weather asks one accessible question:

Which location would you like to use first?

Available methods:

The user reviews resolved choices before saving. QUILL announces ambiguities such as multiple cities with the same name.

After selection, QUILL immediately presents:

The user is then offered an optional, clearly explained choice to enable Weather Guardian at sign-in.

6.2 Quick Weather

A configurable global command speaks:

Example:

Phoenix. 108 degrees, feels like 112. Mostly sunny. Southwest wind 8 miles per hour. One Excessive Heat Warning is active. Conditions were updated 6 minutes ago.

The quick response must be deterministic and configurable.

6.3 Active alert arrival

When a new alert arrives:

  1. Weather Guardian validates and normalizes it.
  2. The alert is matched against monitored locations and alert rules.
  3. QUILL deduplicates it against existing revisions.
  4. QUILL determines its priority scenario.
  5. The configured earcon plays.
  6. The configured voice announces the headline.
  7. An accessible OS notification appears when enabled.
  8. The system tray state changes.
  9. The Alert Center records receipt and delivery.
  10. The user can open details, repeat, acknowledge, snooze allowed repeats, or move directly to instructions.

Example spoken sequence:

Weather Warning. Tornado Warning for Pima County, including the Tucson area, until 4:45 PM. Take shelter now. Press the configured Alert Details command for the complete official message.

For warnings where the official message contains instructions, the user must be able to hear those instructions immediately without navigating through unrelated details.

6.4 Alert update

An update must not be treated as a duplicate merely because the event name is unchanged.

QUILL compares:

The announcement can say:

Update to the Tornado Warning for Pima County. The warning now expires at 5:15 PM. The affected area has expanded eastward. Instructions remain unchanged.

A user can choose:

6.5 All-clear behavior

When an alert is cancelled or expires:

The Severe Thunderstorm Warning for Maricopa County has expired. Two other advisories remain active.

6.6 Continuous weather channel

A user starts “Home Weather Radio.”

QUILL generates a continuous audio experience using a selected program clock. Routine content repeats at user-defined intervals, but only changed content needs to be spoken on every cycle.

A new warning can:

Critical alerts default to immediate interruption, but the user retains control.

6.7 Multi-location monitoring

A user creates a group named “Family” containing:

The group can use:

Example:

Family Weather Scan. Phoenix has one warning. Tucson has no active alerts. Austin has a Heat Advisory.

6.8 Travel mode

Travel mode can monitor:

Current location is sampled only with permission. Precise location history is not retained unless the user explicitly enables it.

7. Location Model

7.1 Location types

QUILL supports:

7.2 Location record

Each saved location includes:

{
  "id": "loc_uuid",
  "display_name": "Home",
  "resolved_name": "Phoenix, Arizona",
  "latitude": 33.4484,
  "longitude": -112.0740,
  "timezone": "America/Phoenix",
  "country": "US",
  "state": "AZ",
  "county_name": "Maricopa",
  "county_zone": "AZC013",
  "forecast_zone": "AZZ543",
  "fire_zone": null,
  "marine_zone": null,
  "nws_office": "PSR",
  "grid_x": 159,
  "grid_y": 57,
  "forecast_url": "...",
  "hourly_forecast_url": "...",
  "grid_data_url": "...",
  "observation_station_ids": [],
  "nwr_transmitters": [],
  "source_resolved_at": "2026-07-19T17:00:00Z",
  "privacy_classification": "precise",
  "sync_enabled": false
}

Actual provider URLs are stored as provider-owned metadata and can be refreshed.

7.3 Location resolution

The NWS API requires latitude and longitude for point metadata and does not provide general address geocoding. QUILL therefore uses a pluggable Geocoder Provider interface.

Resolution sequence:

  1. Use exact coordinates when supplied.
  2. Use OS location services when requested.
  3. Use the configured geocoder for addresses, cities, and ZIP codes.
  4. Present ambiguous results for user selection.
  5. Resolve coordinates through the NWS /points/{lat},{lon} endpoint.
  6. Cache point-to-grid metadata because it changes infrequently.
  7. Discover forecast URLs, zones, office, grid, and nearby stations.
  8. Resolve NWR transmitter coverage separately.

7.4 Location privacy

8. Weather Feed Model

8.1 Feed definition

A feed is a named weather experience containing one or more locations and one or more content segments.

Example feed types:

8.2 Feed record

{
  "id": "feed_uuid",
  "name": "Home Weather Radio",
  "locations": ["loc_home"],
  "segments": [
    "identity",
    "critical_alerts",
    "current_conditions",
    "next_six_hours",
    "today_tonight",
    "extended_forecast",
    "hazardous_outlook",
    "source_status"
  ],
  "repeat_interval_minutes": 15,
  "speak_only_changes_after_first_cycle": true,
  "alert_interruption_policy": "critical_immediate",
  "voice_profile_id": "voice_home_radio",
  "output_device_id": "default",
  "live_stream_fallback_policy": "generated_audio",
  "enabled": true
}

8.3 Content segments

Supported segment types include:

Every segment exposes:

9. Voice and Speech Scenario Framework

9.1 Design principle

The QUILL speech framework is not merely a text-to-speech output switch. For QUILL Weather it becomes a scenario router.

A scenario answers:

9.2 Speech scopes

Rules can be assigned at these levels, from broadest to most specific:

  1. Global QUILL default
  2. QUILL Weather default
  3. Output device
  4. Feed
  5. Location group
  6. Location
  7. Content type
  8. Alert priority
  9. Alert event type
  10. Alert lifecycle event
  11. Language
  12. Temporary session override

The most specific enabled rule wins. The resolved rule is inspectable.

9.3 Voice scenario record

{
  "id": "scenario_uuid",
  "name": "Critical Warning Voice",
  "match": {
    "content_domain": "alert",
    "severity": ["Extreme", "Severe"],
    "urgency": ["Immediate", "Expected"],
    "event_types": ["Tornado Warning", "Flash Flood Warning"],
    "feed_ids": ["*"],
    "location_ids": ["*"]
  },
  "speech": {
    "provider_id": "sapi5",
    "voice_id": "Microsoft David Desktop",
    "rate": -1,
    "pitch": 0,
    "volume": 100,
    "language": "en-US",
    "pronunciation_dictionary_id": "weather_terms",
    "number_style": "natural",
    "time_style": "local_explicit",
    "units_style": "spoken_full"
  },
  "presentation": {
    "earcon_id": "warning_critical",
    "earcon_before": true,
    "earcon_after": false,
    "priority": "critical",
    "interruption": "immediate",
    "duck_other_audio_percent": 80,
    "repeat_policy": "until_acknowledged_or_changed",
    "repeat_interval_minutes": 5,
    "maximum_repeats": 3
  },
  "fallbacks": [
    "weather_default_voice",
    "system_default_voice",
    "screen_reader_announcement"
  ]
}

QUILL ships with editable defaults:

9.5 Per-feed voices

A user can make each generated feed sound distinct.

Example:

A feed may also use multiple voices internally:

9.6 Speech rendering rules

The renderer must correctly handle:

Examples:

9.7 Pronunciation dictionaries

Weather Voice Studio supports:

Users can correct local names without modifying source text.

9.8 Voice failure behavior

If a selected voice or engine fails:

  1. Try the configured fallback voice.
  2. Try the QUILL Weather default voice.
  3. Try the system default voice.
  4. Send an accessible screen-reader or OS notification.
  5. Log the failure.
  6. Never silently discard a critical alert.

10. Alert Architecture

10.1 Alert sources

Initial source: NWS Alerts API

Default endpoint patterns include:

The default local polling interval is 30 seconds, matching NWS guidance not to request alert updates more frequently.

Optional fast source: QUILL Alert Relay

The relay can receive NOAA Weather Wire Service products through NWWS-OI, which requires NWS-issued credentials and an XMPP client. The relay:

Future source: FEMA IPAWS

A future provider may add FEMA IPAWS for non-weather and broader all-hazards alerts, subject to access requirements, agreements, testing, and explicit provenance.

10.2 Local-first and relay modes

Local mode

Relay-assisted mode

Hybrid mode

Recommended default after the relay is production ready:

10.3 Alert normalization

The normalized alert model must preserve at least:

{
  "provider": "nws",
  "source_id": "official-alert-id",
  "status": "Actual",
  "message_type": "Alert",
  "scope": "Public",
  "sent": "...",
  "effective": "...",
  "onset": "...",
  "expires": "...",
  "ends": "...",
  "event": "Flash Flood Warning",
  "sender": "...",
  "sender_name": "...",
  "headline": "...",
  "description": "...",
  "instruction": "...",
  "response": "Shelter",
  "urgency": "Immediate",
  "severity": "Severe",
  "certainty": "Observed",
  "area_description": "...",
  "geometry": {},
  "geocodes": {},
  "affected_zones": [],
  "references": [],
  "parameters": {},
  "language": "en-US",
  "raw_payload_hash": "...",
  "received_at": "...",
  "normalized_at": "..."
}

Raw payloads are retained according to the user’s history setting so developers and users can verify interpretation.

10.4 Alert matching

An alert can match a location through:

Where geometry and zone matching disagree, QUILL records the discrepancy and follows a configurable conservative policy. Default behavior favors notifying the user rather than suppressing a potentially relevant warning.

10.5 Alert lifecycle and deduplication

QUILL uses:

A revision graph links all related alert versions.

A repeated provider response with no meaningful change is not reannounced unless the user selected periodic reminders.

10.6 Alert priority model

QUILL does not reduce urgency, severity, and certainty to a single hidden number. It preserves all three.

For delivery, QUILL computes a transparent priority tier:

Users can inspect why a tier was selected.

The default mapping considers:

10.7 Notification actions

An accessible notification can offer:

10.8 Quiet hours and interruption safety

Users can configure:

Default behavior:

A “Silence all critical alerts” action requires explicit confirmation, states the consequence, and can be time-limited.

10.9 Authoritative text and summaries

For life-safety alerts:

  1. The official headline and instructions are always available.
  2. QUILL can create a deterministic “changes only” summary.
  3. Optional plain-language assistance must be labeled as a QUILL interpretation.
  4. Generative AI may not replace, suppress, or alter official instructions.
  5. The user can always access the raw source message.

11. Weather Data Architecture

11.1 Primary NWS data flow

For each point location:

  1. Resolve latitude and longitude.
  2. Request NWS point metadata.
  3. Cache office, grid, zones, and provider URLs.
  4. Retrieve forecast periods.
  5. Retrieve hourly forecast periods.
  6. Retrieve gridpoint data for detailed time-series values.
  7. Retrieve nearby stations.
  8. Select observations using freshness and availability rules.
  9. Retrieve active alerts.
  10. Retrieve optional text products.
  11. Normalize all values.
  12. store source time, receipt time, and freshness.
  13. Render views and speech.

11.2 Provider interfaces

WeatherProvider
  get_capabilities()
  resolve_point_metadata()
  get_forecast()
  get_hourly_forecast()
  get_grid_data()
  get_observation_stations()
  get_latest_observations()
  get_alerts()
  get_alert()
  get_zones()
  get_text_products()
  get_source_status()

GeocoderProvider
  search()
  reverse_geocode()
  normalize_result()

AlertPushProvider
  connect()
  subscribe()
  unsubscribe()
  receive()
  acknowledge_cursor()
  get_status()

NwrMetadataProvider
  search_transmitters()
  get_county_coverage()
  get_transmitter_status()
  get_same_codes()

WeatherAudioStreamProvider
  search_streams()
  resolve_stream()
  verify_health()
  get_provenance()

Providers register capabilities through stable contribution points. Provider provenance is available in text and speech.

11.3 Normalized weather model

QUILL stores:

11.4 Time-series understanding

NWS gridpoint data may represent values across ISO 8601 time intervals rather than one record per hour. QUILL’s interval engine must:

11.5 Units

QUILL supports:

The user can set units globally, by feed, or by content type.

The source value is never destroyed when converted.

11.6 Observations

Observation station selection considers:

QUILL states the observation source and age.

It must distinguish:

11.7 Freshness and staleness

Every view and speech response can expose:

Default stale thresholds are content-specific.

Example:

Current conditions were last observed 47 minutes ago and may be stale. The forecast was updated 18 minutes ago.

QUILL must not hide stale data behind a generic “updated” label.

11.8 Caching

QUILL honors:

The client avoids cache-busting query parameters.

Point-to-grid mapping is cached long-term and refreshed on provider errors, source changes, or a scheduled maintenance interval.

11.9 Failure and fallback

When a request fails:

  1. Keep the last successful data.
  2. Mark it stale.
  3. Attempt a bounded retry with exponential backoff and jitter.
  4. Use a secondary provider only when configured.
  5. Announce source changes when they affect meaning.
  6. Never merge conflicting provider values without attribution.
  7. Keep alert monitoring prioritized over routine refreshes.
  8. Record errors in diagnostics.

12. System Tray and Background Experience

12.1 Tray states

The tray item has an accessible name reflecting state:

Visual icons may differ, but text state is authoritative.

12.2 Tray menu

Keyboard-accessible commands:

Destructive or safety-relevant commands include confirmation and a clear status announcement.

12.3 Accessible notifications

Notifications must:

12.4 Global commands

Global commands are opt-in and configurable.

Suggested defaults:

QUILL checks for conflicts and allows reassignment.

12.5 Startup and shutdown

Settings include:

13. Settings

13.1 General

13.2 Location

Per location:

13.3 Alerts

13.4 Speech

13.5 Feeds

13.6 Privacy and sync

13.7 Advanced

14. Accessibility Requirements

14.1 Foundational requirements

14.2 Screen-reader behavior

14.3 Keyboard behavior

Every context menu is reachable through keyboard commands and Shift+F10 where applicable.

List items support:

14.4 Audio accessibility

14.5 Cognitive accessibility

15. Safety, Trust, and Integrity

15.1 Safety notice

QUILL Weather displays a concise notice during onboarding and in About:

QUILL Weather is an additional accessible weather information tool. Delivery can be delayed or interrupted by network, device, provider, or software failures. Do not rely on QUILL Weather as your only source of emergency information.

15.2 Source attribution

Every weather object has:

Generated audio identifies itself as QUILL-generated weather using official data.

15.3 No silent transformation

QUILL does not silently:

15.4 Test and exercise alerts

Test alerts are clearly identified through:

Users can choose to announce, log, or ignore provider-designated tests, but development simulation mode cannot impersonate an actual alert without a persistent simulation label.

16. Data Storage

16.1 Local database

SQLite is recommended for:

16.2 Suggested entities

16.3 Retention

Defaults:

All are configurable within safe storage limits.

17. QUILL Alert Relay

17.1 Purpose

The relay exists to improve speed, scalability, and resilience—not to make local weather dependent on the cloud.

17.2 Responsibilities

17.3 Subscription privacy

Clients preferably subscribe using:

Exact addresses are not sent.

For point-specific polygon matching, options are:

  1. Match locally after receiving relevant coarse-zone alerts.
  2. Send a short-lived encrypted or coarse point token.
  3. Use privacy-preserving regional subscriptions.

The first option is the preferred initial design.

17.4 Client connection

Recommended protocol:

17.5 Reliability

The client continuously knows:

A relay failure automatically activates local polling if enabled.

18. NOAA Weather Radio and Community Audio

18.1 Metadata

QUILL imports and normalizes official transmitter information:

18.2 Stream catalog

A stream record includes:

{
  "id": "stream_uuid",
  "call_sign": "WXL30",
  "transmitter_name": "Phoenix",
  "stream_url": "...",
  "provider_name": "Community Receiver Operator",
  "provider_type": "community",
  "official_noaa_stream": false,
  "codec": "MP3",
  "bitrate": 32,
  "last_verified": "...",
  "health": "online",
  "terms": "...",
  "redistribution_allowed": true
}

18.3 Stream rules

18.4 Receiver network

A later QUILL Community Receiver program may provide:

18.5 Delivered implementation: WeatherIndex integration (Quill Radio 2.1.1)

The NWR directory-and-streams portion of this section shipped in Quill Radio 2.1.1, powered by the WeatherIndex API (https://api.wxindex.org) -- a curated, no-auth JSON directory of NWR transmitters plus internet re-stream URLs, organized by state, county/SAME, and NWS Weather Forecast Office.

18.6 Radio Reading Services (delivered in Quill Radio 2.1.1)

Radio reading services -- the audio information services affiliated with IAAIS (the International Association of Audio Information Services) that read newspapers, magazines, and local print aloud for people who are blind or print-disabled -- are a natural companion to community NWR audio and shipped alongside it:

18.7 Reading-service discovery methodology and rights review

The bundled list was built with a discovery pass, kept here as the method for future refreshes of the curated set:

19. User Interface Information Architecture

19.1 Weather Now

Recommended reading order:

  1. Location
  2. Active alert summary
  3. Temperature and condition
  4. Feels-like condition
  5. Wind
  6. Observation age and station
  7. Next meaningful forecast
  8. Quick actions

19.2 Active Alerts list

Default sort:

  1. Critical priority
  2. Urgency
  3. Severity
  4. Most recently updated
  5. Location

Each item speaks:

Tornado Warning. Pima County. Immediate, extreme, observed. Updated 2 minutes ago. Expires at 4:45 PM.

19.3 Alert details

Headings:

19.4 Forecast timeline

Accessible list alternatives:

A visual chart may be included but never replaces the list.

All settings are searchable by plain language.

Example search terms:

Search results explain the setting path and current value.

20. Commands and Extensibility

Suggested command IDs:

weather.openCenter
weather.speakQuick
weather.openAlerts
weather.repeatLastMessage
weather.stopSpeech
weather.startFeed
weather.stopFeed
weather.switchLocation
weather.addLocation
weather.openAlertInstructions
weather.acknowledgeAlert
weather.openVoiceStudio
weather.openSourceStatus
weather.refresh
weather.pauseMonitoring
weather.resumeMonitoring

Extension-contributed commands use the QUILL extension naming convention, such as:

ext.vendor.weatherCommand

Extensions may contribute:

An extension cannot silently suppress critical alerts. Any suppression capability requires explicit user authorization and is visible in diagnostics.

21. Diagnostics and Supportability

21.1 User-facing status

Source Status answers:

21.2 Diagnostic package

The user can create a privacy-reviewed support bundle containing:

Precise coordinates, addresses, alert text, and account identifiers are excluded by default and require explicit inclusion.

21.3 Raw data inspector

Expert users and developers can inspect:

The inspector is fully accessible and supports copying selected sections.

22. Performance Requirements

23. Security Requirements

24. Testing Strategy

24.1 Unit tests

24.2 Contract tests

Saved fixtures for:

24.3 Alert simulation laboratory

A built-in developer and QA laboratory can simulate:

Every simulation is unmistakably marked as a simulation.

24.4 Accessibility tests

Test with:

24.5 Real-world tests

25. Acceptance Criteria

25.1 Location and forecast

25.2 Background monitoring

25.3 Alerts

25.4 Speech

25.5 Accessibility

26. Delivery Phases

Phase 0: Architecture and prototypes

Phase 1: Windows minimum lovable product

Phase 2: Weather Channels and Voice Studio

Phase 3: QUILL Alert Relay

Phase 4: NWR Explorer and community audio

Phase 5: QuilleSync and macOS

Phase 6: Expanded services

Potential future additions:

Each addition must preserve provider provenance and accessibility.

27. Product Risks and Mitigations

Risk: Users assume QUILL is guaranteed life-safety delivery

Mitigation: Clear safety notice, source-status visibility, failure announcements, no claims of certification, and encouragement to use multiple official channels.

Risk: Duplicate or noisy alerts

Mitigation: Revision graph, deterministic change comparison, acknowledgment, changes-only announcements, and configurable repeat rules.

Risk: Over-customization suppresses important warnings

Mitigation: Transparent rule trace, critical-silence confirmation, safety review, reset-to-safe-defaults command, and diagnostics showing suppressed events.

Risk: NWS API outage or rate limiting

Mitigation: Conditional requests, centralized relay for scale, backoff, cache, local fallback, stale-state communication, and provider abstraction.

Risk: Voice provider failure

Mitigation: Multi-step fallback chain, screen-reader/OS notification fallback, and delivery logging.

Risk: Incorrect location matching

Mitigation: Combine point, geometry, and zone methods; conservative default; match explanation; testing near boundaries; user-selected county/zone override.

Risk: Community stream disappears

Mitigation: Health checks, multiple streams, generated audio fallback, and independent structured alert monitoring.

Risk: Generative summaries change meaning

Mitigation: No generative rewrite as the authoritative alert; official text always primary; deterministic summaries; explicit labels.

Risk: Precise location privacy

Mitigation: local-first storage, no default history, optional coarse subscriptions, encrypted sync, redacted diagnostics, and explicit permissions.

28.1 Client modules

quill_weather/
  providers/
    nws/
    geocoding/
    nwr/
    streams/
  domain/
    locations/
    forecasts/
    observations/
    alerts/
    feeds/
    speech/
  services/
    weather_guardian/
    alert_monitor/
    feed_engine/
    cache/
    sync/
    notifications/
  ui/
    weather_center/
    alert_center/
    location_manager/
    feed_builder/
    voice_studio/
    settings/
    diagnostics/
  platform/
    windows/
    macos/
  storage/
  tests/

28.2 Threading and process model

28.3 Speech dispatcher priorities

  1. Emergency stop and user control
  2. Critical alert
  3. Urgent alert update
  4. User-requested speech
  5. Watch or important alert
  6. Advisory
  7. Routine weather feed
  8. Background status

The user can modify the mapping, but the dispatcher always exposes the active queue and allows immediate stop.

29. Example Built-In Profiles

29.1 Calm and complete

29.2 Minimal

29.3 Weather radio

29.4 Family guardian

29.5 Screen-reader integrated

30. Example Spoken Output

Quick Weather

Home, Phoenix. 108 degrees and mostly sunny. It feels like 112. Southwest wind at 8 miles per hour. An Excessive Heat Warning is active until 8 PM Monday. The observation is 6 minutes old.

New warning

Critical weather alert for Home. Flash Flood Warning. Immediate, severe, and observed. In effect until 6:30 PM. Move to higher ground now. Do not drive through flooded roadways. Press the Alert Details command to hear the complete official message.

Update

Update for Home. The Flash Flood Warning has been extended until 7:15 PM. The affected area now includes northern Maricopa County. Official instructions are unchanged.

Stale data

Weather data for Travel Location may be stale. QUILL last reached the National Weather Service 38 minutes ago. Alert monitoring is retrying.

Relay fallback

QUILL Alert Relay is unavailable. Direct National Weather Service alert monitoring remains active and checks every 30 seconds.

31. Research Basis and Official Sources

The initial design is grounded in these official NWS capabilities and constraints:

  1. The NWS API provides forecasts, alerts, observations, and other weather data as open data without usage fees, subject to reasonable rate limits.
    https://www.weather.gov/documentation/services-web-api

  2. NWS forecast lookup begins with latitude and longitude through /points/{lat},{lon}, which returns forecast, hourly forecast, and gridpoint metadata. The point mapping can be cached.
    https://weather-gov.github.io/api/general-faqs

  3. The NWS alerts service supports JSON-LD, CAP v1.2, and Atom. NWS recommends requesting new alerts no more frequently than every 30 seconds.
    https://www.weather.gov/documentation/services-web-alerts

  4. NWS CAP fields such as urgency, severity, and certainty are specifically intended to support decision tools and synthesized voice applications.
    https://www.weather.gov/documentation/services-web-alerts

  5. NOAA Weather Wire Service is described by NWS as its fastest method of receiving text alerts and weather information, within approximately 10 seconds of issuance. NWWS-OI requires NWS-issued credentials and an XMPP client.
    https://www.weather.gov/nwws/faq

  6. NOAA Weather Radio is a nationwide network of more than 1,000 transmitters broadcasting continuous official information on seven VHF frequencies. It is fundamentally a radio transmitter service and requires a compatible receiver.
    https://www.weather.gov/nwr

  7. Official NWR station search and county coverage information includes call signs, frequencies, SAME codes, and transmitter coverage.
    https://www.weather.gov/nwr/station_search
    https://www.weather.gov/nwr/county_coverage

32. Final Product Statement

QUILL Weather should feel like a trusted weather desk that belongs to the user.

It should be fast without being frantic, detailed without being overwhelming, configurable without becoming inaccessible, and powerful without hiding what it is doing.

The product’s defining achievement will not simply be that it speaks the weather. It will be that it understands the structure, timing, source, priority, location, and lifecycle of weather information—and then gives every user direct control over how that information reaches them.

QUILL Weather will turn official data into an accessible living service: