Add CLAUDE.md

CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with this repository.
+Hello Computer and such!
+
+## WHY
+
+This is a published Ruby Gem (`oxford_dictionary` on RubyGems) that wraps the [Oxford Dictionary API](https://developer.oxforddictionaries.com/documentation). Changes should maintain backward compatibility and consider the gem's public API surface.
+
+## WHAT
+
+**Tech Stack**: Pure Ruby, no runtime dependencies. Uses Net::HTTP, URI, JSON (stdlib). RSpec + VCR for testing.
+
+**Core Architecture**: 
+- `Client` is the public entry point; delegates to endpoint modules
+- Each endpoint (Entries, Lemmas, Translations, etc.) inherits from `Endpoint` base class
+- `Request` handles HTTP; `Deserialize` converts JSON to OpenStruct
+- All responses are recursive OpenStruct objects
+
+**Key Files**:
+- `lib/oxford_dictionary/client.rb` — Public API
+- `lib/oxford_dictionary/endpoints/` — API endpoint implementations
+- `spec/` — Unit tests with VCR cassettes (production API)
+- `spec/integration/` — Live API integration tests (requires credentials)
+
+## HOW
+
+**Setup**:
+```bash
+bundle install
+```
+
+**Test & Lint**:
+```bash
+bundle exec rake          # Unit tests + linting
+bundle exec rspec         # Tests only
+bundle exec rubocop       # Lint only
+```
+
+**Integration Tests** (requires Oxford Dictionary credentials):
+```bash
+export APP_ID=<your-id> APP_KEY=<your-key>
+bundle exec rake integration
+```
+
+**Interactive Console**:
+```bash
+bin/console
+```
+
+## Notes
+
+- Unit tests use VCR cassettes (offline, recorded from production API)
+- Integration tests hit the live sandbox API with real credentials
+- API URL configurable via `OXFORD_DICT_API_URL` env var (defaults to sandbox)
+- RuboCop handles code style (see `.rubocop.yml`)
+
+See `CONTRIBUTING.md` for publishing and advanced development tasks.

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to oxford_dictionary
+
+## Adding a New API Endpoint
+
+1. Create `lib/oxford_dictionary/endpoints/new_endpoint.rb` inheriting from `Endpoint`
+2. Implement endpoint-specific methods following existing patterns (e.g., `Entries`)
+3. Add lazy-initialized accessor in `Client` class
+4. Create tests in `spec/endpoints/new_endpoint_spec.rb`
+5. Update README.md with usage examples
+6. Update CLAUDE.md if architecture changed
+
+## Recording New VCR Cassettes
+
+If you need to record new cassettes against the production API:
+1. Set `APP_ID` and `APP_KEY` environment variables with valid credentials
+2. Temporarily comment out VCR config to allow real requests, or use `VCR.turn_off!`
+3. Run the test
+4. VCR automatically scrubs credentials (`APP_ID` and `APP_KEY` replaced with placeholders)
+
+## Publishing a Release
+
+1. Update version in `lib/oxford_dictionary/version.rb`
+2. Update `CHANGELOG.md` with release notes
+3. Commit: `git commit -m "Bump version to X.Y.Z"`
+4. Tag: `git tag vX.Y.Z && git push --tags`
+5. Build and push: `gem build && gem push oxford_dictionary-X.Y.Z.gem`
+
+## Modifying Core Behavior
+
+**Response transformation**: Edit `Deserialize.deserialize()` to change how API responses are converted.
+
+**Authentication/headers**: Modify `Request` class initialization and `#get` method. Ensure backwards compatibility.
+
+**Keep CLAUDE.md up to date** when making changes to:
+- Dependencies (gemspec)
+- Build/test commands (Rakefile)
+- Code structure or public API
+- CI/CD configuration
+- Ruby version requirements