From 4c5c411a0fad3903e311b9dc3f93524c25405834 Mon Sep 17 00:00:00 2001
From: Jay Ravaliya <jayrav13@gmail.com>
Date: Fri, 1 May 2026 22:10:49 -0400
Subject: [PATCH 1/2] docs: add README for local developer setup

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c74cf69
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# Skywatch
+
+Aviation situational awareness toolkit. Real-time aviation weather, flight tracking, and situational awareness from public FAA/NWS/ADS-B data. For end-user documentation, visit https://jayrav13.github.io/skywatch (site coming soon).
+
+## Requirements
+
+- Ruby 3.2 or later (see `.ruby-version`)
+- Bundler
+
+## Setup
+
+```bash
+git clone git@github.com:jayrav13/skywatch.git
+cd skywatch
+bundle install
+```
+
+## Running Tests
+
+All tests use WebMock fixtures and never hit live APIs.
+
+```bash
+bundle exec rspec        # full test suite
+bundle exec rubocop      # lint
+bundle exec rake         # run both
+```
+
+## Running the CLI Locally
+
+```bash
+bundle exec exe/skywatch --help
+bundle exec exe/skywatch brief KCDW
+```
+
+Once installed via `gem install`, use `skywatch` directly without `bundle exec exe/`.
+
+## Project Structure
+
+- `lib/skywatch/` — source code root
+- `lib/skywatch/shared/` — HTTP client, cache, geometry, errors, Position utilities
+- `lib/skywatch/briefer/` — METAR, TAF, PIREP, winds, SIGMET, AIRMET, AFD sources and models
+- `lib/skywatch/brief/` — Skywatch.brief composition layer (AIM 7-1-5 weather brief)
+- `lib/skywatch/radar/` — flight tracking via OpenSky Network
+- `lib/skywatch/mayday/` — emergency squawk detection and alerting
+- `lib/skywatch/nimbus/` — convective outlooks, storm reports, smoke plumes, NEXRAD
+- `lib/skywatch/agent/` — Claude Code subagent install command
+- `agents/` — bundled subagent file (installed via `skywatch agent install`)
+- `spec/` — RSpec tests (mirrors `lib/` layout)
+- `spec/fixtures/` — WebMock JSON and XML fixtures
+- `exe/` — CLI binary entry point
+
+## Architecture
+
+Skywatch is organized into domain modules (briefer, brief, radar, mayday, nimbus, agent) with shared infrastructure under `Skywatch::Shared`. Each domain exports sources (data fetching) and models (data representation).
+
+For the full architecture overview, see `CLAUDE.md` in the repo root.
+
+## Contributing
+
+1. Run tests and lint before pushing:
+   ```bash
+   bundle exec rake
+   ```
+2. Push to a branch and open a PR against `main`.
+3. Ensure CI is green.
+4. Test against fixtures only — never commit changes that hit live APIs.
+
+## License
+
+MIT. See LICENSE.txt in the repo root.

From 7672b8982c6955ab3800e2447b96f55eea675c11 Mon Sep 17 00:00:00 2001
From: Jay Ravaliya <jayrav13@gmail.com>
Date: Fri, 1 May 2026 22:15:28 -0400
Subject: [PATCH 2/2] chore: add rake to dev dependencies so README's `bundle
 exec rake` works

The README in this PR documents `bundle exec rake` as the combined
spec+rubocop runner, but rake wasn't in the Gemfile.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Gemfile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Gemfile b/Gemfile
index 4d7d8a9..3122906 100644
--- a/Gemfile
+++ b/Gemfile
@@ -5,6 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'rake', '~> 13.0'
   gem 'rspec', '~> 3.0'
   gem 'rubocop', '~> 1.0'
   gem 'webmock', '~> 3.0'