Add AGENTS.md with progressive disclosure documentation

- Minimal root AGENTS.md with essential commands and constraints
- docs/testing.md: Test patterns, shared contexts, issue regression specs
- docs/contributing.md: PR requirements, CHANGELOG format, danger checks
- docs/architecture.md: Component overview and data flow

Author: numbata

AGENTS.md

@@ -0,0 +1,24 @@
+# grape-swagger-entity
+
+Adapter for grape-swagger that parses Grape::Entity classes into OpenAPI schema definitions.
+
+## Quick Reference
+
+```bash
+bundle install          # Install dependencies
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Run linter
+bundle exec rubocop -a  # Auto-fix linter issues
+```
+
+## Key Constraints
+
+- Ruby >= 3.0
+- All files must start with `# frozen_string_literal: true`
+- CHANGELOG.md entry required for every PR (danger enforces this)
+
+## Documentation
+
+- [Testing Patterns](docs/testing.md)
+- [Contributing Guidelines](docs/contributing.md)
+- [Architecture Overview](docs/architecture.md)

docs/architecture.md

@@ -0,0 +1,71 @@
+# Architecture Overview
+
+## Purpose
+
+This gem registers a model parser with grape-swagger that converts `Grape::Entity` classes into OpenAPI schema definitions.
+
+## Core Components
+
+```
+lib/grape-swagger/entity/
+├── parser.rb           # Main parser - converts Entity to OpenAPI schema
+├── attribute_parser.rb # Parses individual exposure attributes
+├── helper.rb           # Utility methods for model naming, discriminators
+└── version.rb          # Gem version
+```
+
+### Parser (`parser.rb`)
+
+Entry point for entity parsing. Responsibilities:
+- Extract exposures from Grape::Entity
+- Handle nested entities and `using:` references
+- Process `merge: true` exposures
+- Handle inheritance with `allOf` and discriminators
+- Determine required fields
+
+### AttributeParser (`attribute_parser.rb`)
+
+Converts individual exposure options to OpenAPI property schema:
+- Maps Ruby types to OpenAPI types
+- Handles arrays (`is_array: true`)
+- Processes enums (`values:`)
+- Adds constraints (min/max, minLength/maxLength)
+
+### Helper (`helper.rb`)
+
+Utilities for:
+- Model name resolution (strips Entity/Entities suffix)
+- Discriminator detection for inheritance
+- Root exposure extraction
+
+## Data Flow
+
+```
+Grape::Entity class
+       │
+       ▼
+   Parser.call
+       │
+       ├── extract_params (get exposures)
+       │
+       ├── parse_grape_entity_params
+       │         │
+       │         ├── AttributeParser (per exposure)
+       │         │
+       │         └── parse_nested (for nested blocks)
+       │
+       └── handle_discriminator (inheritance)
+       │
+       ▼
+[properties_hash, required_array]
+```
+
+## Integration Point
+
+Registered with grape-swagger in `lib/grape-swagger-entity.rb`:
+
+```ruby
+GrapeSwagger.model_parsers.register(GrapeSwagger::Entity::Parser, Grape::Entity)
+```
+
+grape-swagger calls `Parser.new(model, endpoint).call` when it encounters a `Grape::Entity` subclass.

docs/contributing.md

@@ -0,0 +1,57 @@
+# Contributing Guidelines
+
+## PR Requirements
+
+Every PR must include:
+
+1. **CHANGELOG.md entry** - Add under `### X.X.X (Next)` in the appropriate section:
+   ```markdown
+   #### Fixes
+   * [#123](https://github.com/ruby-grape/grape-swagger-entity/pull/123): Brief description - [@username](https://github.com/username).
+   ```
+
+2. **Passing CI** - RuboCop + RSpec must pass
+
+3. **Tests** - New functionality needs specs; bug fixes need regression tests
+
+## CHANGELOG Format
+
+```markdown
+### 0.7.1 (Next)
+
+#### Features
+
+* Your contribution here.
+
+#### Fixes
+
+* [#PR](URL): Description - [@author](URL).
+```
+
+- Use `Features` for new functionality
+- Use `Fixes` for bug fixes and maintenance
+
+## Commit Messages
+
+Follow conventional style:
+- `Fix #123: description` for bug fixes
+- `Add feature description` for features
+- `Update dependency/docs` for maintenance
+
+## Code Style
+
+RuboCop enforces style. Key rules:
+- `frozen_string_literal: true` pragma required
+- Consistent hash indentation
+- No trailing whitespace
+
+```bash
+bundle exec rubocop -a  # Auto-fix most issues
+```
+
+## Danger Checks
+
+CI runs danger which enforces:
+- CHANGELOG entry present
+- Table of Contents in README is current
+- PR has description

docs/testing.md

@@ -0,0 +1,63 @@
+# Testing Patterns
+
+## Running Tests
+
+```bash
+bundle exec rspec                    # Run all tests
+bundle exec rspec spec/path/file.rb  # Run specific file
+bundle exec rspec -e "description"   # Run matching examples
+```
+
+## Test Structure
+
+```
+spec/
+├── grape-swagger/
+│   ├── entity_spec.rb              # Main module specs
+│   ├── entity/
+│   │   ├── parser_spec.rb          # Parser unit tests
+│   │   └── attribute_parser_spec.rb
+│   └── entities/
+│       └── response_model_spec.rb  # Integration tests
+├── issues/                          # Regression tests for GitHub issues
+│   └── 962_polymorphic_entity_...   # Named by issue number
+└── support/
+    └── shared_contexts/             # Reusable test setup
+```
+
+## Shared Contexts
+
+Use shared contexts for common API setups:
+
+```ruby
+require 'spec_helper'
+require_relative '../../support/shared_contexts/this_api'
+
+describe SomeClass do
+  include_context 'this api'
+  # ...
+end
+```
+
+## Issue Regression Tests
+
+When fixing a bug, create a spec in `spec/issues/` named `{issue_number}_{brief_description}_spec.rb`:
+
+```ruby
+# spec/issues/123_some_bug_spec.rb
+require 'spec_helper'
+
+describe '#123 brief description of the issue' do
+  # Test that reproduces and verifies the fix
+end
+```
+
+## Testing with Different Gem Versions
+
+Environment variables control dependency versions:
+
+```bash
+GRAPE_VERSION=2.0.0 bundle update grape
+GRAPE_SWAGGER_VERSION=HEAD bundle update grape-swagger
+GRAPE_ENTITY_VERSION=1.0.1 bundle update grape-entity
+```