Add Claude Code GitHub Workflow

.github/workflows/claude-code-review.yml

@@ -0,0 +1,58 @@
+name: Claude Code Review
+
+on:
+  workflow_dispatch:
+  # pull_request:
+  #   types: [opened, synchronize]
+  #   # Optional: Only run on specific file changes
+  #   # paths:
+  #   #   - "src/**/*.ts"
+  #   #   - "src/**/*.tsx"
+  #   #   - "src/**/*.js"
+  #   #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

CLAUDE.md

@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the BetterNow API Developer Documentation site (`developers.betternow.org`), a static documentation site that uses **schema-driven documentation generation**. API documentation is automatically generated from YAML schema definitions using PRMD, then combined with custom content and built into a static site using Middleman.
+
+## Development Commands
+
+### Local Development
+```bash
+# Start local development server with live reload
+docker compose up
+
+# Access at http://localhost:4567 or http://bndocs.test (if puma-dev configured)
+
+# Build inside running container
+docker compose exec web bin/build
+```
+
+### Build Process
+```bash
+# Full build (schema compilation → docs generation → static site)
+bin/build
+
+# Or step by step:
+bundle exec rake schema:combine    # Combine YAML schemas → source/schema.json
+bundle exec rake schema:verify     # Validate compiled schema
+bundle exec rake schema:doc        # Generate source/includes/resources.md
+bundle exec middleman build        # Build static site → build/
+```
+
+### Rake Tasks
+```bash
+rake                              # Default: combine, verify, doc
+rake schema:combine               # Combine schema YAML files into source/schema.json
+rake schema:verify                # Validate the compiled schema
+rake schema:doc                   # Generate Markdown docs from schema
+```
+
+### Deployment
+- Automatic deployment via GitHub Actions on push to master branch
+- Deploys to AWS S3 using OIDC authentication (no hardcoded credentials)
+- Manual deploy: `bin/deploy` (requires AWS credentials)
+
+## Architecture
+
+### Schema-Driven Documentation Flow
+```
+schema/schemata/*.yml → [rake schema:combine] → source/schema.json
+                                                      ↓
+                                        [rake schema:doc]
+                                                      ↓
+source/index.html.md + source/includes/resources.md → [middleman build] → build/
+```
+
+### Key Directories
+
+- **`schema/schemata/`** - YAML schema definitions for each API resource (16 total resources)
+  - `common.yml` - Shared field definitions referenced by other schemas
+  - Individual resource schemas: `fundraiser.yml`, `donation.yml`, `person.yml`, etc.
+- **`schema/meta.json`** - Schema metadata (API title, URL, description)
+- **`schema/preface.md`** - Content prepended to generated API docs
+- **`source/index.html.md`** - Main landing page (YAML frontmatter + Markdown)
+- **`source/includes/`** - Markdown sections included in final docs
+  - `resources.md` - Generated API reference (DO NOT EDIT DIRECTLY)
+  - `webhooks.md` - Webhook documentation (manually maintained)
+- **`source/schema.json`** - Compiled schema (generated, DO NOT EDIT)
+
+### Important Build Patterns
+
+1. **Generated Files** - These are auto-generated and should NOT be edited directly:
+   - `source/schema.json` (from `rake schema:combine`)
+   - `source/includes/resources.md` (from `rake schema:doc`)
+
+2. **To Modify API Documentation**:
+   - Edit YAML files in `schema/schemata/`
+   - Run `bin/build` to regenerate docs
+   - The build process validates schemas automatically
+
+3. **To Modify Landing Page or Static Content**:
+   - Edit `source/index.html.md` for main page
+   - Edit `source/includes/webhooks.md` for webhook docs
+   - Run `middleman build` or full `bin/build`
+
+4. **Schema References**:
+   - Common fields defined in `schema/schemata/common.yml` are referenced via `$ref`
+   - PRMD automatically resolves these references during `schema:combine`
+
+## Technology Stack
+
+- **Ruby 2.7.6** - Runtime (managed via Docker)
+- **Middleman** - Static site generator
+- **PRMD v0.12.0** - JSON Schema to Markdown converter for API docs
+- **Redcarpet** - Markdown processor with table/code block support
+- **Rouge** - Syntax highlighting (via `middleman-syntax`)
+- **Docker/Docker Compose** - Local development environment
+
+## API Specifications
+
+- **Base URL**: `https://api.betternow.org`
+- **HTTP Header**: `Accept: application/vnd.betternow+json; version=1`
+- **Authentication**: Publishable (read-only) and Secret (write) API keys
+
+## CI/CD
+
+GitHub Actions workflow (`.github/workflows/publish.yml`) automatically:
+1. Builds the site on push to master
+2. Deploys to AWS S3 bucket
+3. Uses AWS OIDC for secure authentication