opencode-skills-collection 4.0.72 → 4.0.73

package/bundled-skills/weather-data-lifecycle-management/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: weather-data-lifecycle-management
+description: "Manage ownership, retention, and cleanup of downloaded weather data across one-shot jobs, interactive viewers, caches, failures, and cancellation."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-24"
+author: ShianMike
+tags: [weather, data-lifecycle, cleanup, caching, desktop-apps]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Weather Data Lifecycle Management
+
+## Overview
+
+Keep downloaded and derived weather data for exactly as long as its consumer
+needs it. Make ownership explicit so one-shot jobs clean promptly, interactive
+views retain their inputs until close, and shared caches are never deleted as
+request cleanup.
+
+This skill governs lifetime and ownership. It does not choose a provider,
+decode scientific data, or define a cache eviction policy by itself.
+
+## When to Use This Skill
+
+- A completed render leaves large temporary files behind.
+- An interactive view fails because its backing data was deleted too early.
+- Cancellation or exceptions leak partial downloads and derived files.
+- Request-owned files and a shared user cache are mixed together.
+- Background workers transfer ownership of data to a UI or later processing
+  stage.
+
+## Classify Every Path
+
+Assign each file or directory one owner and one lifetime:
+
+| Class | Owner | Delete when |
+| --- | --- | --- |
+| Request workspace | One operation | Operation finishes or fails after durable outputs are saved |
+| Interactive-session data | Viewer or session | Final consumer closes or display creation fails |
+| Shared cache | Cache manager | Explicit eviction policy permits it |
+| User export | User | Never as automatic request cleanup |
+| Partial file | Active writer | Failure, cancellation, or successful atomic promotion |
+
+If ownership cannot be stated, do not delete the path. Resolve ownership first.
+
+## One-Shot Workflow
+
+Use a request-specific temporary directory, keep all transient downloads and
+intermediate products inside it, and copy or atomically move only the requested
+artifact to its durable destination.
+
+```python
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+
+def render_once(destination):
+    destination = Path(destination)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    with TemporaryDirectory(prefix="weather-job-") as workspace:
+        workspace = Path(workspace)
+        source = fetch_into(workspace)
+        temporary_output = render(source, workspace / "result.png")
+        temporary_output.replace(destination)
+
+    return destination
+```
+
+The final artifact must live outside the temporary directory. If replacement
+across filesystems is not atomic, copy to a temporary file beside the final
+destination, verify it, then replace locally.
+
+## Interactive Workflow
+
+An interactive consumer outlives the worker that created its data. Transfer
+ownership only after the viewer or session is successfully created:
+
+1. The worker owns the request workspace during acquisition.
+2. If acquisition or display creation fails, the worker cleans it immediately.
+3. On successful display, attach one idempotent cleanup callback to the real
+   consumer close or destroyed event.
+4. The consumer becomes the owner; the worker must not also delete the data in
+   its ordinary `finally` path.
+5. If multiple consumers share the same data, release it only after the final
+   lease closes.
+
+Do not tie cleanup to a temporary dialog, local variable, or signal that can
+fire before the actual consumer is finished.
+
+## Failure and Cancellation Rules
+
+- Keep incomplete downloads under a distinct suffix or directory so they cannot
+  be mistaken for valid data.
+- Close datasets, file handles, and memory maps before removing their paths.
+- Put request-owned cleanup in `finally`, but exclude resources whose ownership
+  was successfully transferred.
+- Make cleanup idempotent; a cancellation signal and a close event may race.
+- Preserve a durable partial-result manifest when the user can retry remaining
+  work.
+- On cleanup failure, report the exact owned path without deleting broader
+  parent directories.
+
+## Shared Cache Boundary
+
+- A request may read or populate a shared cache but does not own the cache root.
+- Promote validated entries atomically; never expose a partial file as a hit.
+- Use cache identity and eviction metadata rather than deleting files by age or
+  filename guesswork inside request code.
+- Do not place user exports inside a directory that normal cache cleanup owns.
+- Test that two concurrent consumers do not remove data still leased by the
+  other.
+
+## Verification Checklist
+
+- Every created path has a named owner and deletion event.
+- One-shot operations retain only requested durable outputs.
+- Interactive data remains available until the final consumer closes.
+- Display-creation failure cleans immediately.
+- Exceptions and cancellation remove partial request-owned files.
+- Cleanup is idempotent and closes open handles first.
+- Shared caches and user exports are outside request cleanup scope.
+- Tests exercise success, failure, cancellation, and close-event paths.
+
+## Security & Safety Notes
+
+- Resolve and verify cleanup targets before recursive deletion.
+- Never delete a home directory, workspace root, shared cache root, or user-
+  selected directory as a computed fallback.
+- Avoid globs and unresolved environment variables for destructive cleanup.
+- Do not follow untrusted symlinks or junctions outside the owned workspace.
+- Keep sensitive temporary data in an access-controlled location and remove it
+  when its approved lifetime ends.
+- Report material cleanup failures instead of silently leaving private data.
+
+## Common Pitfalls
+
+- **The image renders but source data leaks:** Cleanup is absent from the
+  one-shot `finally` path or data was written outside the request workspace.
+- **The viewer opens and then breaks:** The worker deleted data immediately
+  after emitting the viewer. Transfer ownership to the viewer close event.
+- **Cancellation deletes useful completed work:** Durable artifacts and
+  request-owned intermediates share a directory. Separate them.
+- **A cache disappears:** Request cleanup treated a shared cache as owned data.
+  Delegate eviction to the cache manager.
+- **Windows refuses deletion:** A dataset or mapped file is still open. Close
+  every consumer before cleanup.
+
+## Limitations
+
+- Multi-process leases require coordination beyond an in-memory reference
+  count.
+- Some decoders create files outside their requested directory; configure or
+  inventory those outputs before promising complete cleanup.
+- Lifecycle correctness prevents leaks and premature deletion but does not
+  validate the scientific contents of retained data.

package/bundled-skills/weather-data-reproducibility/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: weather-data-reproducibility
+description: "Record and verify provenance manifests for weather-data inputs and derived artifacts, including object identity, selections, software versions, transformations, and hashes."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-24"
+author: ShianMike
+tags: [weather, reproducibility, provenance, checksums, grib2, netcdf]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Weather Data Reproducibility
+
+## Overview
+
+Create a compact provenance manifest that identifies the exact weather inputs,
+subsets, software, transformations, and output artifacts used by a run. Verify
+the manifest before claiming that a result can be replayed or reproduced.
+
+This skill records and checks lineage. It does not discover or download data by
+itself; pair it with the appropriate model, observation, radar, or satellite
+fetching skill.
+
+## When to Use This Skill
+
+- A map, sounding, time series, dataset, or benchmark must be auditable.
+- Weather inputs came from mutable URLs, mirrors, byte-range subsets, or caches.
+- A result must distinguish model initialization, forecast lead, and valid time.
+- Temporary GRIB2, NetCDF, radar, satellite, or observation files will be
+  deleted after processing.
+- Two outputs differ and their inputs or processing environment must be compared.
+- A publication or release needs machine-readable data and software provenance.
+
+Do not claim bit-for-bit reproducibility merely because a source URL and run
+time were logged.
+
+## Reproducibility Contract
+
+Decide which claim the workflow supports:
+
+- **Traceable:** The source and processing history can be audited.
+- **Replayable:** The same identified inputs can still be retrieved and the
+  recorded procedure can be rerun.
+- **Bitwise reproducible:** The rerun is expected to produce identical bytes in
+  a pinned environment.
+- **Scientifically reproducible:** Equivalent inputs and methods produce the
+  same scientific conclusion within a stated tolerance.
+
+Record the intended claim and its tolerance. Mutable remote objects, floating
+software versions, lossy images, parallel reductions, and platform-dependent
+code can make the stronger claims impossible.
+
+## Minimum Manifest
+
+Use a versioned JSON document. Keep request intent separate from the source that
+was actually resolved.
+
+```json
+{
+  "schema_version": 1,
+  "created_utc": "2026-09-18T09:00:00Z",
+  "claim": {"level": "replayable", "tolerance": null},
+  "request": {
+    "dataset": "hrrr",
+    "product": "prs",
+    "requested_valid_time": "2026-09-18T12:00:00Z",
+    "variables": ["temperature", "relative_humidity"]
+  },
+  "resolved": {
+    "initialization": "2026-09-18T06:00:00Z",
+    "forecast_hour": 6,
+    "valid_time": "2026-09-18T12:00:00Z",
+    "provider": "aws"
+  },
+  "inputs": [
+    {
+      "role": "pressure_fields",
+      "uri": "s3://bucket/exact-object-key",
+      "object_identity": {
+        "etag": "opaque-identity",
+        "last_modified": "2026-09-18T07:01:02Z",
+        "size_bytes": 987654321
+      },
+      "selection": {
+        "inventory_uri": "s3://bucket/exact-object-key.idx",
+        "inventory_sha256": "HEX_DIGEST",
+        "byte_ranges": [[1000, 1999], [5000, 6999]]
+      },
+      "materialized_sha256": "HEX_DIGEST"
+    }
+  ],
+  "processing": {
+    "software": {"application": "1.2.3", "python": "3.13.7"},
+    "parameters": {"point": [35.22, -97.44], "nearest_method": "model-aware"},
+    "transformations": ["decode GRIB2", "convert K to degC"]
+  },
+  "artifacts": [
+    {
+      "path": "sounding.png",
+      "media_type": "image/png",
+      "size_bytes": 123456,
+      "sha256": "HEX_DIGEST"
+    }
+  ]
+}
+```
+
+Use `null` for an intentionally absent value and omit fields whose meaning is
+unknown. Never fill a required-looking field with a guess.
+
+## Identify Every Input
+
+For each remote object or API response, record as available:
+
+- provider, dataset, endpoint, bucket, and exact key or immutable URL;
+- version ID, generation number, release, or dataset revision;
+- ETag as opaque object identity, `Last-Modified`, and content length;
+- provider-supplied checksum and checksum algorithm;
+- a locally computed SHA-256 for downloaded or materialized bytes;
+- response media type and content encoding;
+- retrieval time and successful fallback provider;
+- license or attribution identifier when required.
+
+An S3 ETag is not always an MD5 digest, particularly for multipart or encrypted
+objects. Store it for identity and compute a cryptographic content hash when
+the actual bytes must be verified.
+
+## Record the Selection
+
+The source object alone is insufficient when only part of it was used. Record:
+
+- GRIB2 inventory URI and inventory content hash;
+- exact inventory rows, search expression, and inclusive byte ranges;
+- Zarr group, array names, chunk keys, and coordinate slices;
+- API query parameters and a hash or retained copy of the raw response;
+- station identifier scheme and observation time interval;
+- radar site/product and scan interval;
+- satellite platform, product, sector, channel, and scan interval;
+- requested coordinates plus the actual selected grid point and distance.
+
+Preserve the order in which selected binary ranges were assembled. Hash the
+materialized subset separately from the full remote object's identity.
+
+## Record Weather Time Semantics
+
+Use explicit UTC timestamps and name their meaning:
+
+- models: initialization, forecast lead, and valid time;
+- station observations: observation, correction, and ingestion time;
+- radar: volume or product scan start and end;
+- satellite: scan start, scan end, and file creation time;
+- retrieval: when the client fetched the metadata and bytes.
+
+Do not replace these with one ambiguous `timestamp` field. Record the calendar
+and leap-second handling if the source or application requires it.
+
+## Record Processing and Environment
+
+Capture only details that can change the result:
+
+- application version and source commit, including dirty-tree status;
+- decoder and scientific library versions;
+- runtime and operating-system or architecture details when relevant;
+- command arguments or structured parameters;
+- unit conversions, QC decisions, interpolation, coordinate selection, and
+  aggregation rules;
+- deterministic random seed when randomness is present;
+- container image digest or environment lock-file hash when available.
+
+Do not dump an entire environment full of unrelated packages merely because it
+is easy. Prefer a lock file plus the versions of software that actually touched
+the data.
+
+## Hash and Write Atomically
+
+The Python standard library is sufficient for local artifact hashes and a
+canonical, atomically replaced JSON manifest:
+
+```python
+import hashlib
+import json
+import os
+from pathlib import Path
+
+
+def sha256_file(path, chunk_size=1024 * 1024):
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        for chunk in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_manifest(path, manifest):
+    path = Path(path)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    payload = json.dumps(
+        manifest, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ) + "\n"
+    temporary.write_text(payload, encoding="utf-8", newline="\n")
+    os.replace(temporary, path)
+```
+
+Hash artifacts only after their writers are closed. If the manifest itself must
+be signed, sign the canonical bytes using the project's established signing
+workflow rather than inventing a custom scheme.
+
+## Verify and Replay
+
+Before replay:
+
+1. Validate the manifest schema version and required fields.
+2. Re-resolve every immutable object identity. Fail if an object changed unless
+   the reproducibility contract explicitly permits an equivalent replacement.
+3. Download or locate inputs and compare size plus a real checksum.
+4. Reapply the recorded selection and confirm the materialized subset hash.
+5. Recreate the pinned processing environment and transformations.
+6. Produce artifacts in a new output directory.
+7. Compare artifact hashes for bitwise claims or documented scientific metrics
+   and tolerances for scientific claims.
+8. Write a new run manifest that references, but does not overwrite, the
+   original.
+
+Report the first mismatch with its role, expected value, and actual value.
+
+## Temporary Data Lifecycle
+
+- Write the final artifact and its manifest before deleting request-owned input
+  files.
+- Keep cleanup in `finally` so failures and cancellation do not leak large
+  GRIB2, NetCDF, radar, or observation files.
+- Never delete a shared user cache as request cleanup.
+- If raw inputs are deleted and the remote source is mutable or short-lived,
+  label the run traceable rather than replayable.
+- A manifest is small and should normally outlive transient downloads.
+
+## Verification Checklist
+
+- Request intent and resolved data identity are separate.
+- Every timestamp is UTC and has explicit semantics.
+- Every input has an exact locator, identity metadata, and content hash when
+  bytes were materialized.
+- Subset rules, inventory identity, byte ranges, and selected coordinates are
+  recorded.
+- Software versions and result-changing transformations are explicit.
+- Final artifacts have size, media type, and SHA-256.
+- The claimed reproducibility level matches what can actually be replayed.
+- The manifest contains no secrets or machine-specific private information.
+
+## Security & Safety Notes
+
+- Never record credentials, authorization headers, cookies, signed-query
+  strings, private bucket names, or secret environment variables.
+- Redact user names and unnecessary absolute local paths before sharing a
+  manifest.
+- Treat a hash as an integrity value, not proof that an untrusted input is safe.
+- Validate manifest paths before opening files; do not allow `..` traversal or
+  writes outside the intended output directory.
+- Keep TLS verification enabled when re-fetching inputs.
+- Preserve license, attribution, redistribution, and access restrictions.
+
+## Common Pitfalls
+
+- **ETag was labeled SHA-256 or MD5:** ETag semantics depend on the provider and
+  upload method. Store it as identity and compute a real local hash.
+- **A model result cannot be recreated:** Initialization and forecast lead were
+  collapsed into valid time. Record all three.
+- **The same URI returns different bytes:** The remote object was mutable and no
+  version or checksum was pinned. Downgrade the claim or retain the input.
+- **A GRIB subset differs:** The inventory version, selected rows, or inclusive
+  byte ranges were omitted.
+- **The artifact hash changes across systems:** The process is scientifically,
+  but not bitwise, reproducible. Define and test a numerical tolerance.
+
+## Limitations
+
+- A manifest cannot restore data that was deleted from a mutable source unless
+  the input bytes or an immutable archive were retained.
+- Exact replay may require licensed software, hardware, or provider access not
+  captured in a public manifest.
+- Provenance establishes lineage and integrity; it does not establish forecast
+  skill, observational truth, or scientific validity.
+
+## Additional Resources
+
+- [W3C PROV overview](https://www.w3.org/TR/prov-overview/)
+- [Amazon S3 object metadata](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)
+- [Amazon S3 checksum guidance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html)
+- [CF metadata conventions](https://cfconventions.org/)
+- [NetCDF Climate and Forecast conventions](https://www.ncei.noaa.gov/products/netcdf)

package/bundled-skills/weather-model-run-discovery/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: weather-model-run-discovery
+description: "Resolve the newest complete numerical weather prediction cycle and forecast objects across provider mirrors without downloading full payloads."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-24"
+author: ShianMike
+tags: [weather, nwp, model-cycle, aws-s3, nomads, herbie]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Weather Model Run Discovery
+
+## Overview
+
+Resolve a numerical weather prediction run before downloading model fields.
+Probe exact objects or narrow prefixes, verify a request-specific completion
+contract, and return the newest qualifying initialization with its source
+metadata.
+
+This skill decides *which run and objects exist*. Use
+`weather-model-data-fetching` afterward to transfer or subset the data.
+
+## When to Use This Skill
+
+- An application needs the newest usable GFS, GEFS, HRRR, RAP, NAM, or similar
+  model cycle.
+- The nominal latest cycle returns `404`, has only early forecast hours, or is
+  still changing.
+- Equivalent AWS, NOMADS, Google, Azure, or other mirrors must be compared
+  without silently mixing runs.
+- A scheduled job needs a bounded fallback to an older complete cycle.
+- The resolved run and provider must be recorded for later reproduction.
+
+Do not activate this skill when the initialization is already fixed or when the
+task is to download, decode, or interpret model variables.
+
+## Define Complete Before Probing
+
+Collect the following request contract:
+
+- model, domain, product, and ensemble member;
+- legal UTC cycle hours and cycle interval;
+- required forecast hours;
+- required companion objects, such as pressure and surface products;
+- required inventory or index sidecars;
+- provider priority and whether cross-provider fallback is allowed;
+- maximum lookback, maximum probes, and freshness requirement.
+
+A run is complete only when every sentinel required by the consumer exists.
+Examples include:
+
+- one product at one forecast hour for a single-image job;
+- both pressure-level and surface files for a sounding;
+- the terminal forecast hour needed by a time series;
+- every required member for an ensemble statistic.
+
+The presence of forecast hour zero does not prove that a run is complete.
+
+## Discovery Workflow
+
+1. Normalize the current time and all candidate initialization times to UTC.
+2. Enumerate only legal cycles, newest first, within the lookback bound.
+3. Build documented object keys for the exact model, product, member, and
+   forecast hour. Never recursively scan an entire bucket.
+4. Probe exact objects with `HeadObject`, HTTP `HEAD`, or a narrow paginated
+   prefix listing. A probe should retrieve metadata, not the model payload.
+5. Require every sentinel and sidecar in the completion contract. Reject zero-
+   length or obviously placeholder objects.
+6. For a live mirror that may expose objects before publication finishes,
+   repeat the metadata probe after a short bounded interval and require stable
+   size and object identity.
+7. Select the first complete candidate. A fallback provider must refer to the
+   same initialization, product, member, and forecast hour.
+8. Emit a resolution record before starting the download.
+
+Use a provider's documented cycle status page as supporting evidence, not as a
+substitute for probing the exact objects the consumer requires.
+
+## Minimal Resolver Example
+
+Keep provider-specific key construction separate from the selection rule. This
+example accepts a metadata-only `probe` callback so it can be used with S3,
+HTTP, or a test fixture.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+
+def candidate_cycles(now, cycle_hours, lookback):
+    now = now.astimezone(timezone.utc).replace(minute=0, second=0, microsecond=0)
+    allowed = sorted(set(cycle_hours), reverse=True)
+    candidates = []
+    for days_back in range((lookback // 24) + 2):
+        day = (now - timedelta(days=days_back)).date()
+        for hour in allowed:
+            cycle = datetime(day.year, day.month, day.day, hour, tzinfo=timezone.utc)
+            if cycle <= now and now - cycle <= timedelta(hours=lookback):
+                candidates.append(cycle)
+    return sorted(set(candidates), reverse=True)
+
+
+def resolve_latest(now, cycle_hours, lookback, required_objects, probe):
+    """Return one complete run; probe(uri) returns metadata or None."""
+    attempts = []
+    for cycle in candidate_cycles(now, cycle_hours, lookback):
+        requested = required_objects(cycle)
+        found = {name: probe(uri) for name, uri in requested.items()}
+        missing = [name for name, metadata in found.items() if not metadata]
+        attempts.append({"cycle": cycle.isoformat(), "missing": missing})
+        if not missing:
+            return {
+                "initialization": cycle.isoformat(),
+                "objects": [
+                    {"role": name, "uri": requested[name], **found[name]}
+                    for name in requested
+                ],
+                "attempts": attempts,
+            }
+    raise LookupError(f"no complete run within {lookback} hours: {attempts}")
+```
+
+The caller must make `required_objects` express the real completion contract;
+checking a single convenient file defeats the purpose of discovery.
+
+## Public S3 Diagnostics
+
+For public NOAA Open Data buckets, inspect exact objects without loading AWS
+credentials:
+
+```bash
+aws s3api head-object --no-sign-request \
+  --bucket BUCKET \
+  --key "EXACT/DOCUMENTED/OBJECT"
+
+aws s3api list-objects-v2 --no-sign-request \
+  --bucket BUCKET \
+  --prefix "MODEL.DATE/DOMAIN/PRECISE-RUN-PREFIX" \
+  --max-items 100
+```
+
+Paginate narrow listings. S3 returns at most one page at a time, and a
+successful listing still needs defensive response parsing. `403` and `404`
+from `HeadObject` can be intentionally nonspecific; distinguish a missing
+public object from a permission or endpoint error before falling back.
+
+## Resolution Record
+
+Return enough information for the fetcher and provenance layer to use the exact
+same objects:
+
+```json
+{
+  "requested_at_utc": "2026-09-18T08:45:00Z",
+  "model": "hrrr",
+  "product": "prs",
+  "initialization": "2026-09-18T06:00:00Z",
+  "required_forecast_hours": [0, 6, 18],
+  "provider": "aws",
+  "objects": [
+    {
+      "role": "pressure_f018",
+      "uri": "s3://bucket/exact-key",
+      "size_bytes": 123456,
+      "etag": "opaque-object-identity",
+      "last_modified": "2026-09-18T07:12:34Z"
+    }
+  ],
+  "fallback_cycles_rejected": []
+}
+```
+
+Keep ETags as opaque identity values. They are not guaranteed to be full-file
+MD5 checksums.
+
+## Reliability and Caching
+
+- Cache positive results only briefly enough for the model cadence and
+  publication latency. Cache negative probes for a shorter interval.
+- Retry timeouts, `408`, `429`, and transient `5xx` responses with bounded
+  exponential backoff and jitter; honor `Retry-After`.
+- Bound lookback and total probes so a provider outage cannot create an
+  unbounded bucket walk.
+- Do not treat one mirror's lag as proof that the run is absent everywhere.
+- Do not mix objects from different providers unless their run identity and
+  product semantics have been verified equivalent.
+- Record rejected cycles and missing sentinels so fallback is visible.
+
+## Verification Checklist
+
+- Candidate cycles are legal for the requested model and expressed in UTC.
+- Every required product, member, forecast hour, and sidecar is present.
+- Object sizes are nonzero and stable when a stabilization check is required.
+- The resolved provider and exact object identities are recorded.
+- The selected run satisfies the user's freshness and lookback bounds.
+- No model payload was downloaded merely to discover availability.
+- A failure reports which cycles were checked and which sentinels were absent.
+
+## Security & Safety Notes
+
+- Probe only public datasets or resources the user is authorized to access.
+- Never embed cloud credentials, signed URLs, session tokens, or private
+  endpoint details in a resolution record.
+- Keep TLS verification enabled. Unsigned public S3 access is not the same as
+  disabling certificate verification.
+- Bound prefix width, pagination, retries, and request rate before probing.
+- Treat provider object names and metadata as untrusted input when writing logs
+  or constructing local paths.
+
+## Common Pitfalls
+
+- **Newest cycle has `f000`:** Later required forecast hours are still
+  publishing. Test the actual terminal sentinels.
+- **A provider fallback changes the forecast:** The fallback changed a product,
+  member, or cycle as well as the mirror. Reject it.
+- **A listing found an object but the download changes:** The publisher was
+  still updating it. Require stable metadata or conditional reads.
+- **Discovery is slow and expensive:** The prefix is too broad or pagination is
+  unbounded. Construct exact keys wherever possible.
+- **Local time selected the wrong day:** Perform cycle arithmetic in UTC and
+  convert only for display.
+
+## Limitations
+
+- Publication schedules, provider retention, key layouts, and mirror status can
+  change; verify them against current provider documentation.
+- Metadata stability reduces the chance of a partial publication but does not
+  prove that the model contents are scientifically valid.
+- This skill does not fetch GRIB2 fields, decode model data, or assess forecast
+  quality.
+
+## Additional Resources
+
+- [NCEP NOMADS data availability](https://nomads.ncep.noaa.gov/)
+- [NCEP NOMADS status](https://nomads.ncep.noaa.gov/status.php)
+- [Herbie latest model run guidance](https://herbie.readthedocs.io/en/latest/user_guide/tutorial/latest.html)
+- [Amazon S3 `HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)
+- [Amazon S3 `ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html)
+- [Amazon S3 conditional requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-requests.html)