polish repo documentation and project structure

- Rewrite README to reflect the real product (Next.js 15, real fonts,
  accurate folder structure, full API table, available scripts).
- Rename package to commitmentissues, add full metadata, add
  typecheck script, align eslint-config-next with Next 15.3.9,
  drop unused @vercel/kv dependency.
- Tighten CONTRIBUTING / SECURITY / PR template with concrete steps.
- Refresh docs/repository-conventions.md as table-form.
- Add /legal to sitemap; expand public/llms.txt with full endpoint
  list and source link.
- Add root CHANGELOG.md (Keep-a-Changelog) folding ROADMAP and
  docs/releases content.
- Add .env.example documenting all optional env vars.
- Dedupe .gitignore.
- Remove stray Group 128.png Figma export, unused .gitkeep, and
  superseded ROADMAP.md / docs/releases/v1.0.0.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dotsystemsdevs

.env.example

@@ -0,0 +1,28 @@
+# =============================================================================
+#  Commitment Issues — environment variables
+# -----------------------------------------------------------------------------
+#  Copy this file to `.env.local` and fill in the values you want to use.
+#  Every variable below is OPTIONAL — the app boots and works without any of
+#  them. With nothing set, you get GitHub's anonymous rate limits (60 req/hr)
+#  and the live counters / "recently buried" feed are disabled.
+# =============================================================================
+
+# Public site URL — used in metadata, OG images, and badge URLs.
+NEXT_PUBLIC_BASE_URL=http://localhost:3000
+
+# -----------------------------------------------------------------------------
+# GitHub API
+# -----------------------------------------------------------------------------
+# Personal access token for GitHub. Raises the rate limit from 60 to 5000
+# req/hr. Public-repo data only — no scopes required.
+# Generate at: https://github.com/settings/tokens
+GITHUB_TOKEN=
+
+# -----------------------------------------------------------------------------
+# Upstash Redis (used for rate limiting, recent burials, candle counts, stats)
+# -----------------------------------------------------------------------------
+# Create a free Redis database at https://console.upstash.com and paste the
+# REST URL + token. Without these, the live counter stays at the historical
+# baseline and the "recently buried" feed falls back to the Hall of Shame.
+KV_REST_API_URL=
+KV_REST_API_TOKEN=

.github/CONTRIBUTING.md

@@ -1,67 +1,78 @@
 # Contributing
 
-Thanks for helping improve `commitmentissues.dev`.
+Thanks for taking the time. The bar is "small, focused, and consistent with what's already there."
 
 ## Ground rules
 
-- Keep PRs small and focused.
-- One concern per PR (bugfix, feature, docs, or refactor).
-- Preserve the existing product tone and UI style.
-- Do not introduce heavy dependencies unless clearly justified.
+- One concern per PR — bugfix, feature, docs, or refactor.
+- Match the existing tone, design system, and file conventions (see below).
+- No heavyweight dependencies unless clearly justified in the PR description.
+- No telemetry, accounts, or anything that requires the user to log in.
 
 ## Local setup
 
 ```bash
+git clone https://github.com/dotsystemsdevs/commitmentissues.git
+cd commitmentissues
 npm install
 npm run dev
 ```
 
-Optional for higher GitHub API limits:
-
-```env
-GITHUB_TOKEN=ghp_yourtoken
-```
+Open [http://localhost:3000](http://localhost:3000). Every environment variable is optional — see [`.env.example`](../.env.example).
 
 ## Before opening a PR
 
-Run:
-
 ```bash
 npm run lint
+npm run typecheck
 npm test
 ```
 
-If you changed runtime behavior, also run:
+If you changed runtime behaviour (anything outside docs / tests), also run:
 
 ```bash
 npm run build
 ```
 
+CI runs the same three commands plus `build` on every push and PR to `main`.
+
 ## Branch and PR flow
 
-1. Fork repo
-2. Create feature branch (`feat/...`, `fix/...`, `docs/...`, `chore/...`)
-3. Commit with clear message
-4. Open PR to `main`
+1. Fork the repo.
+2. Create a branch named `feat/...`, `fix/...`, `docs/...`, or `chore/...`.
+3. Keep commits small. Conventional Commit prefixes are appreciated but not required.
+4. Open the PR against `main`. Fill in the PR template — what changed, why, and screenshots if anything visual moved.
 
-## Issue hygiene
+## File and folder conventions
 
-- Use issue templates when available.
-- Include reproduction steps for bugs.
-- Include acceptance criteria for feature requests.
+- React components: `PascalCase.tsx` in `src/components/`.
+- Hooks: `useCamelCase.ts` — co-located with the component if scoped to one feature, otherwise in `src/hooks/`.
+- Library / pure logic: `camelCase.ts` in `src/lib/`. Keep this layer free of React imports.
+- API routes follow the App Router convention: `src/app/api/<name>/route.ts`.
+- Docs and config: `kebab-case.md`.
+- Folders: lowercase.
 
 ## Scope expectations
 
 Good first contributions:
 
-- UI polish and micro-interactions
-- Small bug fixes
-- Docs improvements
-- Tests around `src/lib/scoring.ts`
+- UI polish, micro-interactions, accessibility fixes.
+- Small bug fixes with a clear repro.
+- New rules in [`scoring.ts`](../src/lib/scoring.ts) — with a test case.
+- Docs and screenshot updates.
+
+Please check in before opening:
+
+- Larger refactors or architecture changes.
+- New runtime dependencies.
+- Anything that adds backend state (we already lean heavily on Redis).
 
 Avoid in first PRs:
 
-- Large rewrites
-- Broad architecture refactors
-- Unrelated cleanup mixed into feature work
+- Sweeping rewrites mixed into a feature.
+- Unrelated cleanup bundled into a fix.
+- Style-only changes that fight the design tokens in [`globals.css`](../src/app/globals.css).
+
+## Reporting bugs and requesting features
 
+Use the issue templates in [`.github/ISSUE_TEMPLATE/`](ISSUE_TEMPLATE). Include a reproduction for bugs and acceptance criteria for features.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,19 +1,21 @@
 ## What changed
 
-- 
+<!-- One or two sentences. -->
 
 ## Why
 
-- 
+<!-- Link the issue, or explain the user-facing reason. -->
 
 ## Checklist
 
-- [ ] I tested my change locally (`npm run lint` and `npm test`)
-- [ ] I kept the scope focused and avoided unrelated refactors
-- [ ] I updated docs/screenshots if behavior or UI changed
-- [ ] I confirmed no secrets are added
+- [ ] `npm run lint` passes
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes
+- [ ] Tested locally (`npm run dev`)
+- [ ] Scope is focused — no unrelated refactors bundled in
+- [ ] Docs / screenshots updated if behaviour or UI changed
+- [ ] No secrets, API keys, or `.env*.local` files added
 
-## Screenshots (if UI change)
-
-<!-- Add before/after images or a short clip -->
+## Screenshots
 
+<!-- Before / after, or short clip, if any UI moved. Delete the section if not applicable. -->

.github/SECURITY.md

@@ -1,18 +1,35 @@
 # Security Policy
 
-If you discover a security issue, please do **not** open a public issue.
+If you find a security issue, please **do not open a public issue or PR**. Reports are read and acted on quickly.
 
-## Report privately
+## Reporting
 
-- Use GitHub security advisories for this repository, or
+Use one of the following:
+
+- [GitHub security advisories](https://github.com/dotsystemsdevs/commitmentissues/security/advisories/new) — preferred.
 - Email: `dot.systems@proton.me`
 
-Please include:
+Include:
+
+- A clear description of the issue.
+- Steps to reproduce, or a proof-of-concept.
+- Affected version or commit SHA.
+- Potential impact, and a suggested fix if you have one.
+
+## What we treat as in scope
+
+- Server-side bugs in any route under `src/app/api/`.
+- Input handling on the public surface — repo URLs, usernames, badge / certificate parameters.
+- CSP / header regressions in [`next.config.mjs`](../next.config.mjs).
+- Anything that could leak server-side environment variables, exfiltrate stored data, or impersonate the service.
+
+## Out of scope
 
-- A clear description of the issue
-- Steps to reproduce
-- Potential impact
-- Suggested fix (if available)
+- Vulnerabilities in upstream dependencies that don't affect our usage.
+- Social-engineering or physical-access attacks.
+- Anything requiring already-compromised end-user devices.
 
-We will acknowledge reports as quickly as possible and work on a fix.
+## Response
 
+We aim to acknowledge reports within 72 hours and to ship a fix or mitigation as soon as practical.
+Coordinated disclosure is appreciated.

.gitignore

@@ -1,44 +1,39 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
-# dependencies
+# Dependencies
 /node_modules
 /.pnp
 .pnp.js
 .yarn/install-state.gz
 
-# testing
+# Testing
 /coverage
 
-# next.js
+# Next.js
 /.next/
-/.next-dev/
 /out/
 
-# production
+# Production
 /build
 
-# misc
+# Misc
 .DS_Store
 *.pem
 
-# local agent / IDE worktrees (do not commit)
+# Local agent / IDE worktrees
 .claude/
 
-# debug
+# Debug
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-# local env files
+# Local env files
 .env*.local
 
-# vercel
+# Vercel
 .vercel
 
-# typescript
+# TypeScript
 *.tsbuildinfo
 next-env.d.ts
-
-.vercel
-
-.env*.local

CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Planned
+
+- Upgrade Next.js 15.x → 16.x (deferred CVEs).
+- Optional Redis cache layer in front of `/api/certificate-image`.
+- Repo comparison — bury two repos side by side.
+- Chrome extension — tombstone badge injected on GitHub repo pages.
+- Language-specific causes of death ("Died of PHP fatigue", "Last seen in CoffeeScript").
+
+### Out of scope by design
+
+- Private repo support — public data only.
+- Accounts / login — the funeral is anonymous.
+- Paywalls — coffee button stays, monetization doesn't.
+
+## [1.0.0] — 2026-04-24
+
+First public open-source release of `commitmentissues.dev`.
+
+### Added
+
+- Certificate of Death generator — A4 layout with cause of death, last words, repo age, and derived stats.
+- Profile graveyard scanner — Dead / Struggling / Alive grouping with one-click certificate links.
+- Live README badge — `/api/badge?username=…` SVG with dead / struggling / alive counts.
+- Hall of Fame marquee — curated list of famously abandoned repos with click-to-light wreath counters.
+- Multi-format export — A4, Instagram (4:5, 1:1), X (16:9), Facebook (1.91:1), Story (9:16).
+- Mobile native share sheet (Web Share API) and desktop fallback (X intent + copy link + downloads).
+- Live counters — buried + profiles scanned, persisted in Upstash Redis.
+- Top-of-page burial ticker — falls back to Hall of Shame when Redis is empty.
+- Random dead repo button (powered by GitHub search).
+- `/about` and `/legal` pages with consistent typography and back navigation.
+- Algorithmic scoring with curated overrides for famously abandoned repos.
+- `next/og` certificate renderer at `/api/certificate-image/[owner]/[repo]` for README embeds.
+- Hardened security headers via `next.config.mjs` (CSP, frame ancestors, referrer policy, etc.).
+- GitHub issue templates, PR template, CI (`lint`, `test`, `build`), `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`.
+- Unit tests for the scoring algorithm.
+
+### Fixed
+
+- Audited the 28 Hall of Fame entries against live GitHub — fixed transferred / renamed orgs (`angular/angular.js`, `facebook/flux`, `joyent/node`, `yahoo/mojito`, `mikeal/request`).
+- Removed entries pointing to repos that no longer exist (`nicowillis/ratchet`, `microsoft/winjs`, `adobe/phonegap`).
+- Synced curated `KNOWN_REPO_CAUSES` keys in `scoring.ts` to the corrected paths.
+- Reset-to-form behavior on the error screen (no longer retries the broken URL).
+
+### Migrated
+
+- Live data backend moved from `@vercel/kv` to `@upstash/redis`.
+- Legacy routes (`/pricing`, `/faq`, `/privacy`, `/terms`) redirect to `/` or `/about`.
+
+[Unreleased]: https://github.com/dotsystemsdevs/commitmentissues/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/dotsystemsdevs/commitmentissues/releases/tag/v1.0.0