diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 0000000..e21b9ef
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# Contributing
+
+## Adding an Agent
+
+Edit [`data/agents.yml`](../data/agents.yml) and add an entry:
+
+```yaml
+agents:
+  - owner: github-username-or-org
+    repo: repository-name
+    category: cli
+```
+
+Required fields: `owner`, `repo`, `category`
+
+Optional fields: `notes` (for clarifications or caveats)
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `owner` | string | Yes | GitHub user or organization that owns the repo |
+| `repo` | string | Yes | Repository name on GitHub |
+| `category` | string | Yes | One of the values listed below |
+| `notes` | string | No | Additional context or disclaimers |
+
+## Valid Categories
+
+- **cli** — Command-line tools and CLI wrappers
+- **ide** — Standalone editors and IDEs
+- **extension** — Editor extensions (VS Code, Neovim, etc.)
+- **library** — Libraries and SDKs
+- **research** — Research papers and proof-of-concept projects
+- **web** — Web-based tools and online IDEs
+
+## Handling Duplicates and Changes
+
+**Duplicate repos:** If a repo appears twice (same owner/repo), the second entry is ignored in the next daily run.
+
+**Renamed repos:** If a GitHub repo is renamed after being tracked, update the `repo` field in `data/agents.yml`. The updater will fetch fresh metadata under the new name. Historical data in `data/history.jsonl` remains under the old key and is not migrated.
+
+**Deprecation:** To remove an agent, delete its entry from `data/agents.yml`. The next run will drop it from the README; historical data is preserved.
+
+## PR Review
+
+- Keep PRs to changes in `data/agents.yml` only (do not edit `README.md` or `data/history.jsonl`)
+- The daily GitHub Actions workflow (runs at 00:00 UTC) picks up merged PRs automatically
+- No manual review required; the updater regenerates the README after your PR merges
+
+For local testing before opening a PR, see [LOCAL_DEV.md](./LOCAL_DEV.md).
diff --git a/docs/LOCAL_DEV.md b/docs/LOCAL_DEV.md
new file mode 100644
index 0000000..a3f42fb
--- /dev/null
+++ b/docs/LOCAL_DEV.md
@@ -0,0 +1,50 @@
+# Local Development
+
+## Prerequisites
+
+- Go 1.23 or later
+- A GitHub personal access token (PAT)
+
+## 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-coding-agents")
+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.
+
+## Running Locally
+
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+go run .
+```
+
+The tool will:
+- Read `data/agents.yml`
+- Fetch live metadata from GitHub GraphQL API
+- Append star counts to `data/history.jsonl`
+- Regenerate `README.md` from `templates/readme.tmpl`
+
+## 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).
diff --git a/templates/readme.tmpl b/templates/readme.tmpl
index 1f1c2d3..ed26b73 100644
--- a/templates/readme.tmpl
+++ b/templates/readme.tmpl
@@ -21,6 +21,8 @@
 4. Star counts are appended to `data/history.jsonl` for 7-day delta computation.
 5. This `README.md` is regenerated from `templates/readme.tmpl` and committed back to the repo.
 
+**Δ7d:** Change in stars over the past 7 days; `—` means fewer than 7 days of history.
+
 ## Contributing
 
 Add an agent to [`data/agents.yml`](data/agents.yml):