feat: release v0.3.0

Author: hsnice16

.claude/settings.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "printf '\\n📦 Agent Friendly Code — current release: 0.2.0\\n  • Read AGENTS.md for conventions, CONTRIBUTING.md for the PR workflow.\\n  • Roadmap: 0.3.0 (benchmark harness) → 0.4.0 (ecosystem integration) → 0.5.0 (alternatives) → 0.6.0 (registry overlay) → 0.7.0 (history-aware signals) → 1.0.0 (production stability) → 1.1.0 (at-scale GitHub indexing).\\n  • Changelog rule: user-facing capabilities only. Codebase hygiene (CI / linter / tests / CONTRIBUTING) does NOT go in lib/changelog.ts.\\n'"
+            "command": "printf '\\n📦 Agent Friendly Code — current release: 0.3.0\\n  • Read AGENTS.md for conventions, CONTRIBUTING.md for the PR workflow.\\n  • Roadmap: 0.4.0 (quick wins — history-aware signals + PR score-diff) → 0.5.0 (auto-refresh + smarter matching) → 0.6.0 (maintainer ownership + at-scale discovery) → 1.0.0 (production cut — Postgres + at-scale indexing + benchmark harness).\\n  • Changelog rule: user-facing capabilities only. Codebase hygiene (CI / linter / tests / CONTRIBUTING) does NOT go in lib/changelog.ts.\\n'"
           }
         ]
       }

AGENTS.md

@@ -29,7 +29,7 @@ See `README.md` for the full product narrative. See `tasks/` for per-version wor
 bun install
 bun run prepare-hooks  # once — installs lefthook git hooks (Biome + tsc + test + file-length on pre-commit)
 bun run init-db        # optional — auto-runs on first score
-bun run seed           # score the curated set (155 repos) across GH / GL / BB
+bun run seed           # score the curated set across GH / GL / BB
 bun run dev            # http://localhost:3000
 bun run score <url>    # score a single repo
 bun run test           # unit tests (node --test + tsx) — requires Node ≥20.9.0
@@ -49,6 +49,10 @@ app/
   sitemap.ts              # /sitemap.xml — static routes + every repo detail page
   api/repos/route.ts
   api/repo/[id]/route.ts
+  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
+  package/page.tsx                          # explainer + try-it examples
+  package/[registry]/[name]/page.tsx        # scored | not_scored | unresolved states
   globals.css             # Tailwind import + @theme tokens (no custom utilities)
 components/               # Tailwind-styled React components
   Panel.tsx, ScoreBar.tsx, ScoreNumber.tsx, ScoreCell.tsx,
@@ -70,7 +74,8 @@ lib/
     weights.ts            # per-model weight tables
     scorer.ts             # signals × weights, topImprovements
   clients/
-    git.ts, github.ts
+    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
   changelog.ts            # typed ChangelogEntry[]
@@ -87,13 +92,11 @@ tasks/
   README.md
   0.1.0/                  # released — shipped record
   0.2.0/                  # released — dogfood complete (tests, self-score, row-click)
-  0.3.0/                  # planned — real per-model weights (benchmark harness)
-  0.4.0/                  # planned — ecosystem integration (badge, PR diff, webhook, opt-out)
-  0.5.0/                  # planned — discovery (alternative recommender)
-  0.6.0/                  # planned — discovery (package-registry overlay)
-  0.7.0/                  # planned — history-aware signals (closes the shallow-clone gap)
-  1.0.0/                  # planned — production stability (Postgres + stable API)
-  1.1.0/                  # planned — at-scale GitHub indexing (crawl + rank, not seed-only)
+  0.3.0/                  # released — embeddable scores + broader coverage (badge, more agents, alternatives, package lookup)
+  0.4.0/                  # planned — quick wins (history-aware signals + PR score-diff action)
+  0.5.0/                  # planned — auto-refresh + smarter matching (webhook rescoring + alternatives v2)
+  0.6.0/                  # planned — maintainer ownership + at-scale discovery (OAuth opt-out + package overlay at scale)
+  1.0.0/                  # planned — production cut (Postgres + at-scale indexing + benchmark harness)
 .claude/
   settings.json           # SessionStart + Stop hooks (Stop → hooks/stop-guard.sh)
   hooks/
@@ -175,7 +178,7 @@ Hooks docs: <https://docs.claude.com/en/docs/claude-code/hooks.html>.
 - SQL: all queries parameterised. No interpolation.
 - HTML: React auto-escapes; no `dangerouslyInnerHTML` anywhere.
 - Local-path mode reads files; never writes outside `data/` and `tmp-clones/`.
-- No auth yet (read-only dashboard). When auth lands (`tasks/0.4.0/04-opt-out-claim-flow.md`), do it via OAuth and gate DB writes per user.
+- No auth yet (read-only dashboard). When auth lands (`tasks/0.6.0/01-opt-out-claim-flow.md`), do it via OAuth and gate DB writes per user.
 
 **Operational concerns** (not code-level security) worth flagging before public launch:
 
@@ -185,7 +188,7 @@ Hooks docs: <https://docs.claude.com/en/docs/claude-code/hooks.html>.
 
 ## Things to leave alone
 
-- Per-model weights are illustrative. Don't tune without `tasks/0.3.0/01-benchmark-harness.md`.
+- Per-model weights are illustrative. Don't tune without `tasks/1.0.0/03-benchmark-harness.md`.
 - SQLite schema is intentionally simple. Flag before restructuring.
 - The I/O boundary. Scoring stays pure; DB stays in `lib/db.ts`.
 - `APP_VERSION` — don't bump without a release.

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Read [AGENTS.md](./AGENTS.md) first — it's the source of truth for stack, conv
 ```bash
 bun install
 bun run prepare-hooks   # once — installs lefthook pre-commit (Biome + tsc + test + file-length)
-bun run seed            # optional: populate the DB with the curated set (155 public repos)
+bun run seed            # optional: populate the DB with the curated set
 bun run dev             # http://localhost:3000
 bun run test            # unit tests (node --test + tsx) — requires Node ≥20.9.0
 ```

README.md

@@ -1,13 +1,15 @@
 # Agent Friendly Code
 
-[![Release](https://img.shields.io/badge/release-0.2.0-blue?style=flat-square)](./lib/changelog.ts)
+[![Release](https://img.shields.io/badge/release-0.3.0-blue?style=flat-square)](./lib/changelog.ts)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)
 [![Next.js 16](https://img.shields.io/badge/Next.js-16-black?style=flat-square)](https://nextjs.org)
 [![Node ≥20.9](https://img.shields.io/badge/node-%E2%89%A520.9-43853d?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-db61a2?style=flat-square&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/hsnice16)
+[![Agent Friendly](https://www.agentfriendlycode.com/api/badge/github/hsnice16/agent-friendly-code.svg)](https://www.agentfriendlycode.com)
 
 **A public dashboard that ranks open-source repos by how friendly they are for AI coding agents — per model.**
 
-Next.js 16 + SQLite (`better-sqlite3`), styled with Tailwind CSS 4. Spans GitHub, GitLab, and Bitbucket out of the box. Current release: **0.2.0**.
+Next.js 16 + SQLite (`better-sqlite3`), styled with Tailwind CSS 4. Spans GitHub, GitLab, and Bitbucket out of the box. Current release: **0.3.0**.
 
 ![Agent Friendly Code — leaderboard](./public/demo/light.png)
 
@@ -58,9 +60,9 @@ Two audiences:
 
 Not pretending the idea is free of risk:
 
-- **Per-model scoring is the hardest part and the easiest to fake.** Today the weights are illustrative. Real "Claude ranks this higher than GPT-5" requires actually running each agent on each repo. That's `tasks/0.3.0/01-benchmark-harness.md`.
+- **Per-model scoring is the hardest part and the easiest to fake.** Today the weights are illustrative. Real "Claude ranks this higher than GPT-5" requires actually running each agent on each repo. That's `tasks/1.0.0/03-benchmark-harness.md`.
 - **Factory.ai is already in this space.** Differentiation has to stay sharp.
-- **Public-shaming risk.** Ranking #47,823 without consent invites angry maintainers. Planned via `tasks/0.4.0/04-opt-out-claim-flow.md`.
+- **Public-shaming risk.** Ranking #47,823 without consent invites angry maintainers. Planned via `tasks/0.6.0/01-opt-out-claim-flow.md`.
 - **Score gaming.** Once public, people add boilerplate `AGENTS.md` to pass the rubric without being useful. Dynamic (actually-run-an-agent) checks are the counter — see benchmark harness.
 - **Freshness.** Scores decay with every push. Webhook-driven rescoring is roadmap.
 
@@ -82,14 +84,14 @@ Short answer: **low risk**. The app:
 - Rate limiting the public API.
 - Sandbox the cloner in a container (future-proofing against hypothetical git CVEs).
 
-Auth and per-maintainer controls land with the opt-out / claim flow in v0.4.0.
+Auth and per-maintainer controls land with the opt-out / claim flow in v0.6.0.
 
 ## Quickstart
 
 ```bash
 bun install
 bun run prepare-hooks  # once — installs lefthook pre-commit (Biome + tsc + test + file-length)
-bun run seed           # score the curated set (155 repos) across GH / GL / BB
+bun run seed           # score the curated set across GH / GL / BB
 bun run dev            # http://localhost:3000
 ```
 
@@ -108,7 +110,7 @@ Run the unit tests with `bun run test` (uses `node --test` + `tsx`; requires Nod
 
 ## Versioning
 
-`lib/version.ts` and `package.json` carry the current release number (currently **0.2.0**). Bumps happen only when we actually cut a release — never when merging intermediate work. The version pill in the header surfaces the number directly; `/changelog` lists what each release shipped.
+`lib/version.ts` and `package.json` carry the current release number (currently **0.3.0**). Bumps happen only when we actually cut a release — never when merging intermediate work. The version pill in the header surfaces the number directly; `/changelog` lists what each release shipped.
 
 ## Stack & rationale
 
@@ -169,13 +171,12 @@ LICENSE       MIT
 
 See `/roadmap` in the running app or the per-version `tasks/` folders for the full picture.
 
-- **0.3.0 — real per-model weights**: benchmark harness actually runs agents on scoped tasks per repo; current illustrative weights get replaced with measured ones.
-- **0.4.0 — ecosystem integration**: badge endpoint for READMEs, GitHub Action that comments score delta on PRs, webhook-driven rescoring, OAuth-gated opt-out / claim flow for maintainers.
-- **0.5.0 — alternative recommender**: "repo Y does the same thing and ranks higher for your model."
-- **0.6.0 — package-registry overlay**: rank npm / PyPI / Cargo packages by source-repo friendliness.
-- **0.7.0 — history-aware signals**: extend the scorer with maintenance recency, commit velocity, and contributor activity — closing the gap that the shallow clone leaves today.
-- **1.0.0 — production stability**: Postgres migration for concurrent writers; from here on, breaking API changes require a MAJOR bump.
-- **1.1.0 — at-scale GitHub indexing**: flip from a curated seed list to an auto-discovered crawl (GitHub search + trending + submissions). Target 10k repos on first delivery.
+Versions are sequenced cheap-first so the highest-impact small additions don't get gated on heavy infra:
+
+- **0.4.0 — quick wins**: history-aware signals (maintenance recency, commit velocity, contributor activity) + a GitHub Action that comments the score delta on every PR. No new infra.
+- **0.5.0 — auto-refresh + smarter matching**: webhook-driven rescoring (keep scores fresh on every push) + alternatives via README embeddings (cross-language matches the v0.3.0 SQL heuristic misses).
+- **0.6.0 — maintainer ownership + at-scale discovery**: OAuth opt-out / claim flow for maintainers + at-scale package overlay (per-registry leaderboards + userscript that renders the badge inline on npmjs.com / PyPI / crates.io).
+- **1.0.0 — production cut**: Postgres migration for concurrent writers + auto-discovered crawl (target 10k repos) + benchmark harness that derives per-model weights from measured agent success. From here on, breaking API changes require a MAJOR bump.
 
 ## Defensibility
 
@@ -188,3 +189,7 @@ MIT — see [LICENSE](./LICENSE).
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, branch/commit style, the PR description template, and the changelog discipline.
+
+## Sponsor
+
+If this project is useful to you, consider sponsoring its development: [github.com/sponsors/hsnice16](https://github.com/sponsors/hsnice16).

app/api/badge/[host]/[owner]/[name]/route.ts

@@ -0,0 +1,39 @@
+import { getModelScores, getRepoByHostOwnerName } from "@/lib/db";
+import { MODEL_BY_ID, type ModelId } from "@/lib/scoring/weights";
+import { badgeSvg } from "@/lib/utils/badge";
+
+export const dynamic = "force-dynamic";
+
+const HEADERS = {
+  "Content-Type": "image/svg+xml; charset=utf-8",
+  "Cache-Control": "public, max-age=3600, s-maxage=3600",
+};
+
+export async function GET(req: Request, ctx: { params: Promise<{ host: string; owner: string; name: string }> }) {
+  const { host, owner, name: rawName } = await ctx.params;
+  const name = rawName.replace(/\.svg$/i, "");
+
+  const url = new URL(req.url);
+  const modelParam = url.searchParams.get("model");
+
+  const repo = getRepoByHostOwnerName(host, owner, name);
+  if (!repo) {
+    return new Response(badgeSvg("agent friendly", "not scored", null), {
+      headers: HEADERS,
+    });
+  }
+
+  let label = "agent friendly";
+  let score = repo.overall_score;
+
+  if (modelParam && modelParam in MODEL_BY_ID) {
+    const m = modelParam as ModelId;
+    const ms = getModelScores(repo.id).find((s) => s.modelId === m);
+
+    score = ms ? ms.score : null;
+    label = `agent friendly · ${MODEL_BY_ID[m].label.toLowerCase()}`;
+  }
+
+  const value = score == null ? "—" : score.toFixed(1);
+  return new Response(badgeSvg(label, value, score), { headers: HEADERS });
+}

app/api/package/[registry]/[name]/route.ts

@@ -0,0 +1,41 @@
+import { NextResponse } from "next/server";
+
+import { isRegistry } from "@/lib/clients/registries";
+import { lookupPackage } from "@/lib/package-lookup";
+import { APP_URL } from "@/lib/version";
+
+export const dynamic = "force-dynamic";
+
+const HEADERS = { "Cache-Control": "public, max-age=3600, s-maxage=3600" };
+
+export async function GET(_req: Request, ctx: { params: Promise<{ registry: string; name: string }> }) {
+  const { registry, name } = await ctx.params;
+
+  if (!isRegistry(registry)) {
+    return NextResponse.json({ error: "unsupported registry", supported: ["npm", "pypi", "cargo"] }, { status: 400 });
+  }
+
+  const result = await lookupPackage(registry, name);
+
+  if (result.status === "scored") {
+    return NextResponse.json(
+      {
+        status: result.status,
+        package: result.package,
+        registry: result.registry,
+        per_model: result.per_model,
+        overall: result.repo.overall_score,
+        repo: {
+          id: result.repo.id,
+          host: result.repo.host,
+          name: result.repo.name,
+          owner: result.repo.owner,
+        },
+        badge_url: `${APP_URL}/api/badge/${result.repo.host}/${result.repo.owner}/${result.repo.name}.svg`,
+      },
+      { headers: HEADERS },
+    );
+  }
+
+  return NextResponse.json(result, { headers: HEADERS });
+}

app/globals.css

@@ -67,10 +67,10 @@ html {
 html,
 body {
   margin: 0;
-  background: var(--color-bg);
+  line-height: 1.6;
   color: var(--color-ink);
+  background: var(--color-bg);
   font-family: var(--font-sans);
-  line-height: 1.6;
   -webkit-font-smoothing: antialiased;
 }
 
@@ -99,9 +99,9 @@ textarea,
 }
 
 *:focus-visible {
-  outline: 2px solid var(--color-accent);
-  outline-offset: 2px;
   border-radius: 4px;
+  outline-offset: 2px;
+  outline: 2px solid var(--color-accent);
 }
 
 input:focus,
@@ -118,10 +118,11 @@ select:focus-visible {
   html {
     scroll-behavior: auto;
   }
+
   *,
   *::before,
   *::after {
-    transition: none !important;
     animation: none !important;
+    transition: none !important;
   }
 }

app/layout.tsx

@@ -26,6 +26,10 @@ export const metadata: Metadata = {
     "Cursor",
     "Devin",
     "GPT-5 Codex",
+    "Gemini CLI",
+    "Aider",
+    "OpenHands",
+    "Pi",
     "AGENTS.md",
     "agent readiness",
     "open source",
@@ -53,6 +57,36 @@ export const metadata: Metadata = {
   robots: { index: true, follow: true },
 };
 
+const JSON_LD = {
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": `${APP_URL}/#org`,
+      url: APP_URL,
+      name: APP_NAME,
+      sameAs: [REPO_URL],
+      logo: `${APP_URL}/icon.svg`,
+    },
+    {
+      "@type": "WebSite",
+      "@id": `${APP_URL}/#site`,
+      url: APP_URL,
+      name: APP_NAME,
+      description: APP_DESCRIPTION,
+      publisher: { "@id": `${APP_URL}/#org` },
+      potentialAction: {
+        "@type": "SearchAction",
+        target: {
+          "@type": "EntryPoint",
+          urlTemplate: `${APP_URL}/?q={search_term_string}`,
+        },
+        "query-input": "required name=search_term_string",
+      },
+    },
+  ],
+};
+
 export const viewport: Viewport = {
   themeColor: [
     { media: "(prefers-color-scheme: light)", color: "#ffffff" },
@@ -67,10 +101,25 @@ const NAV_LINKS = [
   { href: "/changelog", label: "Changelog" },
 ];
 
+const FOOTER_LINKS = [
+  { href: "/", label: "Home" },
+  { href: "/methodology", label: "Methodology" },
+  { href: "/roadmap", label: "Roadmap" },
+  { href: "/changelog", label: "Changelog" },
+  { href: "/package", label: "Packages" },
+];
+
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
+        <script
+          type="application/ld+json"
+          // biome-ignore lint/security/noDangerouslySetInnerHtml: JSON-LD requires raw script content; payload is server-controlled and `<` is escaped
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify(JSON_LD).replace(/</g, "\\u003c"),
+          }}
+        />
         <GoogleAnalytics />
 
         <header className="sticky top-0 z-20 border-b border-line/80 bg-bg/60 backdrop-blur-md backdrop-saturate-150">
@@ -105,6 +154,13 @@ export default function RootLayout({ children }: { children: React.ReactNode })
         <div className="mx-auto max-w-[1080px] px-3 pb-20 pt-8 sm:px-6 sm:pt-10">
           <main id="main">{children}</main>
           <footer className="mt-12 border-t border-line pt-5 text-[13px] leading-[1.7] text-muted">
+            <nav aria-label="Secondary" className="mb-2 flex flex-wrap gap-x-4 gap-y-1">
+              {FOOTER_LINKS.map((l) => (
+                <Link key={l.href} href={l.href} className="text-ink-dim hover:text-ink-soft">
+                  {l.label}
+                </Link>
+              ))}
+            </nav>
             Signals are static heuristics — no agent is actually run. Per-model weights are illustrative, not yet
             empirically derived.
           </footer>