git:20261017.16ba3f9 to git:20261105.fdab958

49 added, 85 removed. Audit A to A.

---

name: nws-weather

- description: Fetch National Weather Service forecast evidence through the governed HTTP front, producing a sealed provider packet for downstream weather planning.

+ description: Read the actual National Weather Service forecast for a US geographic point, or reuse an already selected NWS grid through the existing provider phases.

---

# NWS Weather

- Fetch public National Weather Service forecast evidence through runx HTTP.

- It uses the governed HTTP front, not an ad hoc client: the receipt records the NWS

- endpoint, response status, graph step receipts, and the exact authority surface.

- No API key is required. The default runner fetches the actual NWS gridpoint

- forecast; the `locate` runner discovers the gridpoint for a latitude/longitude.

- ## What this skill does

- `nws-weather` makes read-only calls to `api.weather.gov`. The `locate`

- runner calls `/points/{lat},{lon}` to discover `gridId`, `gridX`, `gridY`, and

- forecast URLs. The default `forecast` runner calls

- `/gridpoints/{office}/{grid_x},{grid_y}/forecast` to fetch forecast periods and

- shapes them into the forecast it returns.

- ## When to use this skill

- - You need real public weather evidence with no credentials.

- - A graph needs to prove a weather data read went through runx's governed HTTP

- path.

- - You have an NWS office/gridpoint and need the current public forecast.

- - You have latitude and longitude in the United States and need the NWS gridpoint

- before running the forecast path.

- ## When not to use this skill

+ Fetch the National Weather Service forecast for an intended US location through

+ the selected NWS connector. The default `at-point` runner accepts numeric

+ `latitude` and `longitude`, reads the provider's point-to-grid mapping and then

+ fetches that grid's forecast. No API key, office-code lookup or hand-built

+ grid request is needed for this route.

- - For locations outside NWS coverage. Return `needs_input` with the coverage

- limitation.

- - For emergency, medical, aviation, maritime, evacuation, or life-safety

- decisions.

- - To notify users, reschedule events, deploy changes, or mutate operations based

- on weather. Those actions need their own authority gate.

- - To call private networks, untrusted hosts, or non-NWS endpoints.

+ Use this for read-only forecast evidence. Global place-name discovery and

+ Open-Meteo data belong to `open-meteo-weather`; resolve the intended place first

+ when coordinates are unknown. Do not guess a city or assume that a US place

+ shares a grid with a nearby point. Notification, scheduling and operational

+ actions need their own skill and authority.

- ## Procedure

+ ## How it works

- 1. If the caller has only coordinates, run `locate` with `lat` and `lon`.

- 2. Extract `gridId`, `gridX`, and `gridY` from the sealed locate output.

- 3. Run the default `forecast` runner with `office`, `grid_x`, and `grid_y`.

- 4. Confirm the HTTP status is 2xx and the response contains forecast periods.

- 5. Preserve the NWS source URL, generated timestamp, gridpoint, and receipt refs.

- 6. Return the shaped forecast; planning prose belongs to the agent that uses

- it. Do not invent guidance inside this provider fetch.

- 7. Return `needs_input` for malformed coordinates or gridpoints; return

- `needs_more_evidence` for NWS outages, missing periods, or stale data.

+ 1. Supply the intended latitude and longitude. The NWS request uses four

+ decimal places, matching the existing points contract.

+ 2. `points.read` returns the provider's `gridId`, `gridX` and `gridY`. A

+ bounded domain function admits those exact fields and keeps the point,

+ timezone, forecast URL and native readback binding in `location`. It never

+ derives a grid from geography or follows an arbitrary returned URL.

+ 3. Only a usable mapping proceeds through the existing `forecast.read`

+ operation. Its original provider packet retains forecast periods, units,

+ generated/update times and native evidence.

+ 4. Return the observed data. The calling agent interprets the forecast and

+ its coverage; this reader does not invent planning advice or publication.

- ## Edge cases and stop conditions

+ The [NWS API documentation](https://www.weather.gov/documentation/services-web-api)

+ explains point-to-grid discovery. Mappings can change, so reuse a saved grid

+ only while its freshness is appropriate to the caller's job. The default reads

+ the current mapping; it does not maintain a cache or background loop.

- - **Invalid coordinates:** return `needs_input`; NWS point lookup requires

- decimal latitude and longitude.

- - **Unsupported location:** return `needs_input`; NWS coverage is not global.

- - **Provider outage or non-2xx response:** return `needs_more_evidence` and

- preserve the HTTP status in the receipt.

- - **Missing forecast periods:** return `needs_more_evidence`; do not summarize a

- forecast that is not present.

- - **Life-safety use:** return `refused` and direct the user to official weather

- or emergency channels.

- - **Action requested from weather:** stop at provider evidence and require the

- downstream action skill with its own gate and receipt.

+ ## Reuse in graphs

- ## Output schema

+ `forecast` still accepts `office`, `grid_x` and `grid_y` as strings and reads

+ that exact grid once. It never calls points or geocodes again. `locate` still

+ accepts string `lat` and `lon` for a points-only read. Preserve the native

+ provider packet and readback when handing either result downstream.

- ```yaml

- decision: ready | needs_input | needs_more_evidence | refused

- runtime_path: http

- provider: national-weather-service

- provider_evidence:

- endpoint: string

- http_status: string

- gridpoint:

- office: string

- grid_x: string

- grid_y: string

- generated_at: string

- forecast_periods: array

- receipt_refs: array

- stop_conditions: array

- ```

+ For the Washington Monument, the direct call is

+ `{latitude: 38.8894, longitude: -77.0352}`. A parent graph that already has the

+ NWS mapping can instead call `forecast` with its current office/grid values.

- ## Worked example

+ ## Results and failure

- 1. Run `locate` for `38.8894,-77.0352`.

- 2. The sealed NWS points response returns `gridId: LWX`, `gridX: 97`,

- `gridY: 71`, and a forecast URL.

- 3. Run the default `forecast` runner with `office: LWX`, `grid_x: "97"`,

- `grid_y: "71"`.

- 4. Hand the sealed forecast JSON to the downstream agent that plans with it.

+ The actual result is the existing `runx.provider.operation.v1` evidence packet.

+ The default also returns `location`, with the admitted mapping and its readback.

+ A missing/malformed mapping returns `needs_more_evidence` in that location

+ result and makes no forecast call. It does not mean there is no weather.

- ## Inputs

+ Provider refusal, non-success status, timeout and uncertain outcome retain the

+ native failure or pending-call envelope and receipt state. This skill does not

+ replace them with a fictional normalized forecast or automatically retry a

+ possibly charged request. Unsupported NWS coverage is distinct from a forecast

+ containing no rain. Missing periods, stale timestamps or incomplete data must

+ remain evidence gaps when the calling agent summarizes the result.

- - `office` (default runner, required): NWS office id such as `LWX`.

- - `grid_x` (default runner, required): NWS grid X coordinate.

- - `grid_y` (default runner, required): NWS grid Y coordinate.

- - `lat` (`locate` runner, required): decimal latitude for point lookup.

- - `lon` (`locate` runner, required): decimal longitude for point lookup.

+ This is not an emergency, aviation, maritime or medical decision service. Use

+ the relevant official operational channel for such decisions. A successful read

+ is evidence of the returned forecast, not authority to change an operation.