docs: add CONTRIBUTING.md and align README structure with repo

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to BLT-Leaf
+
+Thanks for helping improve **BLT-Leaf**, the OWASP BLT PR readiness checker.
+
+## Before you start
+
+- Read the [README](README.md) for features and architecture.
+- Optional deep dives: [docs/OAUTH_SETUP.md](docs/OAUTH_SETUP.md), [docs/DATABASE.md](docs/DATABASE.md).
+
+## Local development
+
+1. **Node.js** — Use **Node 22+** where possible (matches [CI](.github/workflows/ci.yml)).
+2. **Install dependencies:**
+   ```bash
+   npm ci
+   ```
+3. **Environment** — Copy `.env.example` to `.env` and configure secrets as documented in the README and OAuth guide.
+4. **D1 database** — Create `pr_tracker` and apply migrations (see README **Setup** — bash or Windows PowerShell sections).
+5. **Run the worker locally:**
+   ```bash
+   npm run dev
+   ```
+   Open [http://localhost:8787](http://localhost:8787).
+
+## Python (worker) sanity check
+
+Backend code lives under `src/`. Quick syntax check:
+
+```bash
+python -m compileall src
+```
+
+(Use Python 3.11+ to align with typical Cloudflare Python Workers tooling.)
+
+## Tests
+
+Same checks CI expects before opening a PR:
+
+```bash
+npm test
+```
+
+Additional script in the repo:
+
+```bash
+node test-sorting-security.js
+```
+
+## Pull request workflow
+
+1. **Fork** [OWASP-BLT/BLT-Leaf](https://github.com/OWASP-BLT/BLT-Leaf) and **clone your fork**.
+2. Create a branch, e.g. `docs/...`, `fix/...`, or `feat/...`.
+3. Keep commits focused; update docs when behavior or setup changes.
+4. Open a PR against **`main`**. CI runs `npm run lint`, `npm run format:check`, `npm test`, and `npm audit`.
+
+## Getting help
+
+- **OWASP Slack:** `#project-blt`
+- **Issues:** [GitHub Issues](https://github.com/OWASP-BLT/BLT-Leaf/issues)
+
+## License
+
+By contributing, you agree your contributions are licensed under the same terms as this project (see [LICENSE](LICENSE)).

README.md

@@ -2,6 +2,8 @@
 
 A simple one-page application to track and monitor GitHub Pull Request readiness status.
 
+**Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, tests, and PR workflow.
+
 ## Quick Deploy
 
 Deploy this application to Cloudflare Workers with one click:
@@ -21,23 +23,28 @@ No manual configuration required!
 ```
 BLT-Leaf/
 ├── public/              # Static assets served by Cloudflare Workers
-│   └── index.html      # Main frontend application
-├── src/                # Backend Python code (modular structure)
-│   ├── index.py        # Main entry point and routing
-│   ├── handlers.py     # API endpoint handlers
-│   ├── utils.py        # Utility functions for PR analysis
-│   ├── github_api.py   # GitHub API interactions
-│   ├── database.py     # Database operations
-│   └── cache.py        # Caching and rate limiting
-├── migrations/         # Database migrations for D1
+│   ├── index.html       # Main frontend application
+│   └── ...              # Additional HTML/JS assets
+├── src/                 # Backend Python code (modular structure)
+│   ├── index.py         # Main entry point and routing
+│   ├── handlers.py      # API endpoint handlers
+│   ├── utils.py         # Utility functions for PR analysis
+│   ├── github_api.py    # GitHub API interactions
+│   ├── database.py      # Database operations
+│   ├── cache.py         # Caching and rate limiting
+│   └── ...              # Auth, Slack notifier, etc.
+├── docs/                # Extra documentation (OAuth, database)
+├── migrations/          # Database migrations for D1
 │   ├── 0001_create_prs_table.sql
 │   ├── 0002_create_timeline_cache.sql
 │   └── 0003_create_indexes.sql
-├── wrangler.toml       # Cloudflare Workers configuration
-├── package.json        # npm scripts for deployment
-├── DEPLOYMENT.md       # Detailed deployment instructions
-├── CODE_SPLITTING_SUMMARY.md  # Documentation on code organization
-└── README.md          # This file
+├── scripts/             # Helper scripts (e.g. migrations)
+├── wrangler.toml        # Cloudflare Workers configuration
+├── package.json         # npm scripts for deployment and CI
+├── test-data-display.js # Primary automated checks (used by npm test)
+├── test-sorting-security.js
+├── CONTRIBUTING.md      # Contributor setup and PR guidelines
+└── README.md            # This file
 ```
 
 ## Features
@@ -198,19 +205,11 @@ This test suite verifies:
 - ✅ Configuration files (wrangler.toml, package.json)
 - ✅ API routing and CORS configuration
 
-**Quick Local Test** (watch wrangler console for logs):
+**Sorting / security checks** (additional script in repo):
 ```bash
-node test-simple.js
+node test-sorting-security.js
 ```
 
-**Full Production Test** (requires deployment):
-```bash
-npm run deploy
-node test-production.js https://your-worker.workers.dev
-```
-
-For detailed testing instructions and expected behavior, see [TESTING.md](TESTING.md).
-
 **Note**: Local development (`wrangler dev`) may not preserve worker state between requests. For accurate rate limiting and caching tests, deploy to production.
 
 ### Continuous Integration