feat: 0.5.0 task 02 - GitHub Action for score (#3)

Author: hsnice16

.claude/skills/code-review/SKILL.md

@@ -54,7 +54,7 @@ Only `@phosphor-icons/react`. Block Lucide, Heroicons, React Icons, inline SVG,
 ## Security
 
 - Parameterised SQL only.
-- `dangerouslySetInnerHTML` is allowed only for the existing server-built JSON-LD scripts (`app/layout.tsx`, `app/page.tsx`, `app/methodology/page.tsx`, `app/repo/[id]/page.tsx`, `app/package/[registry]/[name]/page.tsx`) with the `<` → `<` escape preserved. Reject any new use.
+- `dangerouslySetInnerHTML` is allowed only for the existing server-built JSON-LD scripts (`app/layout.tsx`, `app/page.tsx`, `app/action/page.tsx`, `app/methodology/page.tsx`, `app/repo/[id]/page.tsx`, `app/package/[registry]/[name]/page.tsx`) with the `<` → `<` escape preserved. Reject any new use.
 - External links include `rel="noopener noreferrer"`.
 - Never execute code from a cloned repo.
 

.claude/skills/quality-check/SKILL.md

@@ -39,7 +39,7 @@ Run the four checks below on any diff affecting UI or I/O. Report findings group
 ## Security
 
 - **SQL parameterisation**: every query uses `?` placeholders. No string concatenation.
-- **`dangerouslySetInnerHTML`** is allowed only for server-built JSON-LD (`app/layout.tsx`, `app/page.tsx`, `app/methodology/page.tsx`, `app/repo/[id]/page.tsx`, `app/package/[registry]/[name]/page.tsx`) and must keep the `<` → `<` escape. Any other use must be rejected.
+- **`dangerouslySetInnerHTML`** is allowed only for server-built JSON-LD (`app/layout.tsx`, `app/page.tsx`, `app/action/page.tsx`, `app/methodology/page.tsx`, `app/repo/[id]/page.tsx`, `app/package/[registry]/[name]/page.tsx`) and must keep the `<` → `<` escape. Any other use must be rejected.
 - **External URLs** in `<a target="_blank">` always include `rel="noopener noreferrer"`.
 - **User input at every boundary** is validated: `parseRepoUrl` for repo URLs, `Number.isFinite` for numeric params, length caps on search strings.
 - **Clone safety**: `git clone --depth 1 --single-branch`; never execute code from a clone (no `bun install`, no `npm install`, no post-clone scripts).

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: The dashboard showed something wrong, an API returned the wrong shape, scoring looks off, or `bun run dev` broke locally.
+title: "bug: <one-line summary>"
+labels: bug
+---
+
+## What happened
+
+_The behaviour you observed._
+
+## What you expected
+
+_What you thought would happen._
+
+## Where
+
+_Tick whichever applies:_
+
+- [ ] Dashboard (visitor-facing — leaderboard, repo page, methodology, about, etc.)
+- [ ] API route (`/api/repo/:id`, `/api/repos`, `/api/score`, `/api/badge/...`, `/api/package/...`, `/llms.txt`)
+- [ ] Score / signal output (the score itself looks wrong for a specific repo)
+- [ ] Local dev (`bun run dev`, `bun run seed`, `bun run score <url>`, `bun run test`)
+- [ ] Other — please describe.
+
+## Reproduction
+
+- **URL or repo affected (if any)**: _e.g. `https://<deploy-host>/repo/123` or the repo being scored, like `vercel/next.js`._
+- **Browser / OS** (for UI bugs): _e.g. Chrome 130 on macOS 15._
+- **`bun --version` / Node version** (for local-dev bugs): _e.g. `bun 1.1.x`, `node 20.9.0`._
+- **Steps**:
+  1. _…_
+  2. _…_
+  3. _…_
+
+### Logs / screenshots
+
+_Console output, server logs, or screenshots. Use a `<details>` block for long logs._
+
+## Anything else
+
+_Anything that might be relevant — recent re-score, specific signal, model selection, fresh install vs upgrade, etc._

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,36 @@
+---
+name: Feature request
+about: Suggest a new signal, model, host, page, API field, or other capability.
+title: "feat: <one-line summary>"
+labels: enhancement
+---
+
+## What you want
+
+_The capability you'd like. Be concrete._
+
+## Why
+
+_The problem this solves. Who benefits — dashboard visitor, API caller, maintainer of a listed repo, contributor — and when._
+
+## Alternatives considered
+
+_What you've tried, or why a workaround on top of the existing surface isn't enough._
+
+## Roadmap status
+
+_Tick whichever applies:_
+
+- [ ] On the roadmap already — version `0.X.0`, task file `tasks/0.X.0/NN-*.md`. (Linking the task file is enough; no further design needed here.)
+- [ ] Not on the roadmap. Proposing it for inclusion. (Maintainer call: add it to `lib/roadmap.ts` first, then a PR can land.)
+
+## Scope check
+
+_Tick whichever applies:_
+
+- [ ] **New signal** — see "Adding a signal" in [AGENTS.md](../../AGENTS.md). Mirrors to the sibling `agent-friendly-action` repo.
+- [ ] **New model** — see "Adding a model" in [AGENTS.md](../../AGENTS.md). Mirrors to the sibling repo.
+- [ ] **New host** — see "Adding a host" in [AGENTS.md](../../AGENTS.md).
+- [ ] **New / changed API route** — `/api/...`. Note breaking-change implications for action + agent-skill consumers.
+- [ ] **New page or UI surface**.
+- [ ] **Other** — please describe.

.github/workflows/agent-friendly.yml

@@ -0,0 +1,20 @@
+name: Agent-friendly score diff
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  score-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: hsnice16/agent-friendly-action@v0
+        with:
+          agents-badge-token: ${{ secrets.AGENTS_BADGE_TOKEN }}

AGENTS.md

@@ -51,18 +51,21 @@ app/
   llms.txt/route.ts       # /llms.txt — markdown manifest for LLM crawlers (Perplexity, Claude, ChatGPT search)
   api/repos/route.ts
   api/repo/[id]/route.ts
+  api/score/route.ts                        # /api/score?host=&repo=owner/name — public lookup (powers the action + agent skill)
   api/badge/[host]/[owner]/[name]/route.ts  # SVG badge for README embeds (?model=<id> for per-model)
   api/package/[registry]/[name]/route.ts    # npm/PyPI/Cargo lookup → source-repo score
   repo/[id]/opengraph-image.tsx             # next/og convention — per-repo OG image (auto-wired)
   package/page.tsx                          # explainer + try-it examples
   package/[registry]/[name]/page.tsx        # scored | not_scored | unresolved states
+  action/page.tsx                           # PR-diff GitHub Action explainer + install snippet (SEO landing for the sibling action repo)
   globals.css             # Tailwind import + @theme tokens (no custom utilities)
 components/               # Tailwind-styled React components
   Panel.tsx, ScoreBar.tsx, ScoreNumber.tsx, ScoreCell.tsx,
   HostPill.tsx, HostSelect.tsx, Medal.tsx, ModelPills.tsx,
   MobileNav.tsx, Pagination.tsx, SearchBar.tsx, SelectMenu.tsx, SortSelect.tsx,
   SignalRow.tsx, SuggestionItem.tsx, VersionPill.tsx,
   RepoHero.tsx, SignalListCard.tsx, ModelSuggestions.tsx, PerModelScores.tsx,
+  BadgeEmbed.tsx, ActionEmbed.tsx, CopySnippet.tsx, PackageLookupForm.tsx,
   BackToTop.tsx, GoogleAnalytics.tsx
 lib/
   constants/
@@ -80,7 +83,7 @@ lib/
     git.ts, github.ts, registries.ts  # registries.ts: npm/PyPI/Cargo package → source-repo URL
   package-lookup.ts                   # shared registry → repo lookup (used by /api/package + /package page)
   db.ts                   # better-sqlite3 schema + queries
-  version.ts              # APP_NAME, APP_VERSION, IS_PRE_RELEASE, APP_URL, APP_DESCRIPTION, REPO_URL
+  version.ts              # APP_NAME, APP_VERSION, IS_PRE_RELEASE, APP_URL, APP_DESCRIPTION, REPO_URL, ACTION_REPO_URL, ACTION_USES
   changelog.ts            # typed ChangelogEntry[]
   roadmap.ts              # typed RoadmapVersion[]
 scripts/
@@ -130,17 +133,31 @@ Keep it that way when adding features. If a component needs data, fetch in the p
 - **Versioning + changelog**: bumps on `lib/version.ts` + `package.json` `version` happen only on a real release, coordinated with a new bucket in `lib/changelog.ts`. The changelog is a **user-facing capability log** — every bullet describes something a dashboard visitor or API caller can see, click, or call. Codebase hygiene (CI, linters, pre-commit, tests), pure internal refactors, dep bumps, and contributor-facing docs (CONTRIBUTING, PR templates) do **not** earn a changelog line — they stay in `tasks/` and the PR description. When a roadmap item ships, remove it from `lib/roadmap.ts` in the same PR — moved, not duplicated.
 - **File length**: `.ts` / `.tsx` under `app/`, `components/`, `lib/` stay ≤ 300 lines — enforced by the `file-length` pre-commit job in `lefthook.yml`. Near the cap, split into subcomponents or extract helpers to `lib/utils/`. `scripts/` is exempt (seed data lists).
 
+## Sibling repos
+
+The PR-diff GitHub Action lives in a sibling directory: `../agent-friendly-action/`. It **vendors** the scorer (`lib/scoring/` from this repo) into its own bundle so it can run inside maintainer CI with no network call to this app. Extracting `agent-friendly-scorer` as a standalone npm package is deferred to `tasks/1.0.0/03-benchmark-harness.md`, when a second sibling consumer (the benchmark harness) appears. Until then, the two copies of the scorer must stay in sync by hand.
+
+**Whenever you change `lib/scoring/`** — adding a signal, tweaking a weight, refactoring `scorer.ts`, anything — also:
+
+1. Re-vendor the changed file(s) into `../agent-friendly-action/src/scoring/` (mirror the directory layout).
+2. Append a line under "Unreleased" in `../agent-friendly-action/CHANGELOG.md` describing what changed, so action consumers can read what shipped in each tagged release.
+3. The action's CI verifies its `dist/` bundle is in sync with `src/` on every push, but it can't catch upstream-source drift — that's on the agent doing the change.
+
+If `../agent-friendly-action/` isn't present locally, flag it; never silently skip the propagation. Both repos are siblings under the same `personal/` workspace.
+
 ## Adding a signal
 
 1. New file at `lib/scoring/signals/<kebab-id>.ts` implementing `Signal` (including `improveSuggestion`).
 2. Import and add to the `SIGNALS` array in `lib/scoring/signals/index.ts`.
 3. Add a weight entry to **every** model in `lib/scoring/weights.ts` — missing weights default to 0, decide deliberately.
 4. Re-score: `bun run seed` is idempotent.
+5. **Mirror to the action** (per "Sibling repos" above): copy the new signal file into `../agent-friendly-action/src/scoring/signals/`, add the import + array entry to its `signals/index.ts`, copy the weights changes to its `weights.ts`, and log the addition in `../agent-friendly-action/CHANGELOG.md` under "Unreleased".
 
 ## Adding a model
 
 1. Add a `ModelProfile` to `MODELS` in `lib/scoring/weights.ts` — weights for every signal.
 2. Appears automatically in the leaderboard model pills and repo-page suggestions.
+3. **Mirror to the action**: copy the weights change into `../agent-friendly-action/src/scoring/weights.ts` and log under "Unreleased" in its `CHANGELOG.md`.
 
 ## Adding a host
 
@@ -180,7 +197,7 @@ Hooks docs: <https://docs.claude.com/en/docs/claude-code/hooks.html>.
 
 - We `git clone --depth 1 --single-branch` arbitrary URLs — safe by default. We never run post-clone scripts, never `npm install`, never execute code from the clone.
 - SQL: all queries parameterised. No interpolation.
-- HTML: React auto-escapes. The only `dangerouslySetInnerHTML` is server-built JSON-LD with `<` escaped to `<` (`app/layout.tsx`, `app/page.tsx`, `app/methodology/page.tsx`, `app/repo/[id]/page.tsx`, `app/package/[registry]/[name]/page.tsx`); never feed user-controlled strings into it.
+- HTML: React auto-escapes. The only `dangerouslySetInnerHTML` is server-built JSON-LD with `<` escaped to `<` (`app/layout.tsx`, `app/page.tsx`, `app/action/page.tsx`, `app/methodology/page.tsx`, `app/repo/[id]/page.tsx`, `app/package/[registry]/[name]/page.tsx`); never feed user-controlled strings into it.
 - Local-path mode reads files; never writes outside `data/` and the clone workspace passed to `shallowClone`.
 - No auth yet (read-only dashboard). When auth lands (`tasks/0.7.0/01-opt-out-claim-flow.md`), do it via OAuth and gate DB writes per user.
 

README.md

@@ -166,6 +166,10 @@ CLAUDE.md     Pointer → AGENTS.md
 LICENSE       MIT
 ```
 
+## Companion: PR-diff GitHub Action
+
+[`hsnice16/agent-friendly-action`](https://github.com/hsnice16/agent-friendly-action) runs the same scorer inside your CI and posts a per-PR score-delta comment — _"this PR drops your Claude Code score by 4.1 points because it removed CI config."_ Opt-in via an `AGENTS_BADGE_TOKEN` secret; falls through silently when unset. Each repo detail page on the dashboard ships a copy-paste workflow snippet under "Catch score regressions on every PR".
+
 ## Roadmap (high-level)
 
 See `/roadmap` in the running app or the per-version `tasks/` folders for the full picture.

app/about/page.tsx

@@ -1,6 +1,6 @@
+import { ArrowUpRight } from "@phosphor-icons/react/dist/ssr";
 import type { Metadata } from "next";
 import Link from "next/link";
-
 import { Panel, PanelHeading } from "@/components/Panel";
 import { APP_NAME, REPO_URL } from "@/lib/version";
 
@@ -30,9 +30,9 @@ export default function AboutPage() {
             target="_blank"
             rel="noopener noreferrer"
             href="https://github.com/hsnice16"
-            className="border-b border-dotted border-ink-dim/60 text-ink-dim hover:border-ink-soft hover:text-ink-soft"
+            className="inline-flex items-center gap-0.5 border-b border-dotted border-ink-dim/60 text-ink-dim hover:border-ink-soft hover:text-ink-soft"
           >
-            Himanshu Singh
+            Himanshu Singh <ArrowUpRight size={11} weight="bold" aria-hidden="true" />
           </a>
           . Independent project — no affiliation with Anthropic, OpenAI, Google, Cognition, Anysphere, or any of the
           agent vendors ranked here.
@@ -83,9 +83,9 @@ export default function AboutPage() {
               href={REPO_URL}
               target="_blank"
               rel="noopener noreferrer"
-              className="border-b border-dotted border-ink-dim/60 text-ink-dim hover:border-ink-soft hover:text-ink-soft"
+              className="inline-flex items-center gap-0.5 border-b border-dotted border-ink-dim/60 text-ink-dim hover:border-ink-soft hover:text-ink-soft"
             >
-              source repository
+              source repository <ArrowUpRight size={11} weight="bold" aria-hidden="true" />
             </a>
             . If a repo&apos;s score looks wrong, file an issue with a link and the rubric to revisit; if a signal is
             missing, propose one.
@@ -103,9 +103,9 @@ export default function AboutPage() {
               target="_blank"
               rel="noopener noreferrer"
               href={`${REPO_URL}/issues`}
-              className="border-b border-dotted border-ink-dim/60 text-ink-dim hover:border-ink-soft hover:text-ink-soft"
+              className="inline-flex items-center gap-0.5 border-b border-dotted border-ink-dim/60 text-ink-dim hover:border-ink-soft hover:text-ink-soft"
             >
-              GitHub
+              GitHub <ArrowUpRight size={11} weight="bold" aria-hidden="true" />
             </a>
             .
           </p>