# Local Development

## Prerequisites

- Go 1.23 or later
- `make` (optional — every target is a one-line wrapper you can run by hand)
- A GitHub personal access token (PAT), for the update step only

Run `make` with no arguments to list the available targets.

## Getting a GitHub Token

1. Go to [https://github.com/settings/tokens](https://github.com/settings/tokens)
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a name (e.g., "awesome-ai-dev-tools")
4. Select scope: **`public_repo`** (needed to read public repo metadata)
5. Click "Generate token" and copy the value

The updater reads public repos only; `public_repo` scope is sufficient and safe.

## The two steps

The tool separates fetching data from rendering the site, so only the fetch
needs a token. See [DEPLOY.md](./DEPLOY.md) for why.

### Update (needs a token, hits the network)

```bash
export GITHUB_TOKEN=ghp_your_token_here
make update          # or: go run .
```

This will:
- Read `data/agents.yml`
- Fetch live metadata from the GitHub GraphQL API
- Append star counts to `data/history.jsonl`
- Write the fetched fields to `data/metadata.json`
- Regenerate `README.md` from `templates/readme.tmpl`

### Build (offline, no token)

```bash
make build           # or: go run . -build
```

This joins `data/agents.yml` (tags and notes) with `data/metadata.json` (stars
and repo metadata) and renders `dist/` — a copy of `site/` plus the generated
`dist/data.json`. This is exactly what Cloudflare Pages runs.

Preview it at <http://localhost:8080>:

```bash
make serve           # builds first; override the port with PORT=3000
```

If you only touched `site/index.html` or the tags in `data/agents.yml`, the
build step alone is enough — no token required.

### Validate (offline, no token)

```bash
make check           # or: go run . -check
```

### Before pushing

`make test` runs what CI runs — vet, tests, `-check` and `-build`:

```bash
make test
```

## Reverting Local Changes

Before opening a PR, undo local modifications:

```bash
git restore data/history.jsonl README.md
```

This removes the snapshot files generated by your local run, leaving only your edits to `data/agents.yml`.

## Rate Limits

- **With GITHUB_TOKEN:** 5,000 requests/hour
- **Without token:** 60 requests/hour

Always set `GITHUB_TOKEN` when testing locally to avoid hitting the unauthenticated limit.

## Next Steps

To add agents, see [CONTRIBUTING.md](./CONTRIBUTING.md).
To publish the site, see [DEPLOY.md](./DEPLOY.md).