# Contributing to Openshelf

Thanks for wanting to add something. There are two ways to do it.

## Option A — the form (no GitHub account needed)

Go to the **Suggest a tool** page on the live site and fill in the form.
It arrives by email to a maintainer, who reviews it and adds it if it's a
good fit. This is the easiest path if you're not familiar with GitHub.

## Option B — a pull request

1. Fork this repository.
2. Open `tools.json`.
3. Add a new entry to the array, following this shape exactly:

```json
{
  "name": "Tool Name",
  "url": "https://example.com",
  "category": "Dev Tools",
  "code": "DEV-003",
  "license": "MIT",
  "description": "One or two plain sentences describing what it does and why it's worth listing."
}
```

- `category` should match one of the existing categories where possible
  (Dev Tools, Design, Productivity, AI & Data, Media, Learning,
  Privacy & Security, Writing) so filtering keeps working cleanly. Propose
  a new category only if none of these fit.
- `code` is the catalog number: the category's 3-letter prefix (e.g. `DEV`,
  `DSN`, `PRD`, `AID`, `MED`, `LRN`, `SEC`) plus the next unused number in
  that category, zero-padded to 3 digits.
- `license` should reflect reality: an actual open-source license
  (`MIT`, `GPL-3.0`, `AGPL-3.0`, etc.) or, if it's closed-source but free
  to use, say so plainly (`Freeware`, `Free tier`).
- `description` stays factual — no marketing language, no unverified claims.

4. Open a pull request. A maintainer will review for:
   - the tool is actually free (or has a genuinely usable free tier)
   - the link works and isn't a redirect/affiliate wrapper
   - it isn't a duplicate of an existing entry
   - the description is accurate and neutral

## What doesn't belong here

- Paid tools with no meaningful free tier
- Tools that require handing over payment details for a "free trial"
- Anything that redistributes copyrighted or pirated content
- Affiliate links or promotional listings

## Code changes

Openshelf is plain HTML/CSS/JS on purpose — no build step, no framework,
so anyone can read and modify it. If you want to improve the design,
search, or filtering logic, open a PR against `style.css` or `script.js`
directly and describe what changed and why.