github-rep 0.1.1__tar.gz → 0.2.0__tar.gz

github_rep-0.2.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: github-rep
+Version: 0.2.0
+Summary: Analyze a GitHub profile and get honest, actionable advice for building real reputation
+Author-email: Basil Alshukaili <basilalshukaili@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/basilalshukaili/github-rep
+Project-URL: Bug Tracker, https://github.com/basilalshukaili/github-rep/issues
+Keywords: github,open-source,developer-tools,profile,reputation,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# github-rep
+
+[![PyPI version](https://img.shields.io/pypi/v/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![Python versions](https://img.shields.io/pypi/pyversions/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![CI](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml/badge.svg)](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Score any GitHub user's reputation across 11 honest signals and get a prioritized fix list — in under 30 seconds.**
+
+---
+
+## Why this exists
+
+GitHub profiles are the de-facto developer resume. Most advice on building GitHub reputation is either
+vague ("just contribute more") or gameable (spam-stars, low-effort PRs). This tool measures the signals
+that actually matter to recruiters, maintainers, and other developers — and tells you exactly what to
+fix first, ordered by impact.
+
+---
+
+## Install
+
+```bash
+pip install github-rep
+```
+
+Requires Python 3.9+. No configuration needed — works unauthenticated (60 req/hr) or with a GitHub
+token for 5000 req/hr.
+
+---
+
+## Quickstart
+
+```bash
+# Analyze any GitHub user
+github-rep analyze-profile torvalds
+
+# Use a token to avoid rate limits
+export GITHUB_TOKEN=ghp_yourtoken
+github-rep analyze-profile sindresorhus
+
+# Machine-readable JSON output
+github-rep analyze-profile gvanrossum --json
+
+# Show all findings, including low-priority ones
+github-rep analyze-profile octocat --verbose
+
+# Compare multiple profiles side by side
+github-rep compare torvalds gvanrossum sindresorhus
+
+# Check your API rate limit
+github-rep rate-limit
+```
+
+---
+
+## Sample output
+
+```
+$ github-rep analyze-profile torvalds
+
+╭──────────────────────────────── GitHub Profile ─────────────────────────────╮
+│ @torvalds  |  Linus Torvalds                                                │
+│                                                                              │
+│ Followers: 305,509  |  Public repos: 12  |  Stars earned: 246,028           │
+╰──────────────────────────────────────────────────────────────────────────────╯
+Grade: B  (78/100)
+Tier: Active developer
+
+                Score Breakdown
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
+┃ Dimension                ┃  Score ┃   Max ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
+│ Profile Completeness     │      4 │    10 │
+│ Readme Quality           │     12 │    15 │
+│ Star Signal              │     20 │    20 │
+│ Contribution Streak      │     15 │    15 │
+│ Repo Diversity           │      7 │    10 │
+│ Description Quality      │     10 │    10 │
+│ Topic Tags               │      0 │     5 │
+│ Fork Ratio               │      5 │     5 │
+│ Recent Activity          │      5 │    10 │
+│ Release Cadence          │      0 │     5 │
+│ Profile Readme           │      0 │     5 │
+└──────────────────────────┴────────┴───────┘
+
+Priority fixes:
+  [HIGH] Missing bio
+     Your bio is empty. It is the first thing visitors read.
+     Fix: Write 1-2 sentences: your focus, what you build, your superpower.
+
+What is working:
+  [GOOD] Strong star signal (246028 total, top repo: 235147)
+  [GOOD] Active recent commits (0d ago)
+  [GOOD] All repos have descriptions
+```
+
+Grades: **A** (≥80) · **B** (≥65) · **C** (≥50) · **D** (≥35) · **F**
+
+---
+
+## The 11 scored dimensions
+
+| # | Dimension | Max pts | What it measures |
+|---|-----------|--------:|------------------|
+| 1 | Profile Completeness | 10 | Name, bio, avatar, location, website / social link |
+| 2 | README Quality | 15 | Top repo README length, code examples, install instructions |
+| 3 | Star Signal | 20 | Total stars earned across all repos (log-scaled) |
+| 4 | Contribution Streak | 15 | Days since last profile activity |
+| 5 | Repo Diversity | 10 | Number of public repos and language breadth |
+| 6 | Description Quality | 10 | Fraction of repos with meaningful descriptions |
+| 7 | Topic Tags | 5 | Repos tagged with relevant GitHub topics |
+| 8 | Fork Ratio | 5 | Proportion of original work vs. forked repos |
+| 9 | Recent Activity | 10 | Repos with pushes in the last 90 days |
+| 10 | **Release Cadence** | 5 | Published GitHub Releases on top repos |
+| 11 | **Profile README** | 5 | Presence and quality of the username/username profile README |
+
+**Total: 100 points.**
+
+Dimensions 10 and 11 are new in v0.2.0 and measure signals that indicate a polished,
+production-ready presence — publishing versioned releases and curating a profile page.
+
+---
+
+## All flags
+
+```
+github-rep analyze-profile <username> [OPTIONS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output (all scores + findings) |
+| `--verbose` / `-v` | Show all findings including low-priority improvements |
+| `--token` / `-t` | GitHub PAT (also reads `GITHUB_TOKEN` env var) |
+| `--top N` | Number of top repos to deep-analyze (default: 10) |
+| `--help` | Show help and exit |
+
+---
+
+## JSON output
+
+```bash
+github-rep analyze-profile gvanrossum --json
+```
+
+```json
+{
+  "username": "gvanrossum",
+  "total": 72,
+  "grade": "B",
+  "tier": "Active developer",
+  "breakdown": {
+    "profile_completeness": 8,
+    "readme_quality": 12,
+    ...
+  },
+  "findings": [
+    {
+      "category": "topic_tags",
+      "severity": "medium",
+      "title": "Most repos have no topic tags",
+      "detail": "Missing from GitHub Explore category pages entirely.",
+      "fix": "Add topics to your top 3 repos today - GitHub UI, takes 2 minutes."
+    }
+  ]
+}
+```
+
+---
+
+## Caching
+
+Results are cached for 5 minutes under `~/.cache/github-rep/` to avoid hitting rate limits when
+running the tool multiple times. Delete the cache directory to force a fresh fetch.
+
+---
+
+## FAQ
+
+**Do I need a GitHub token?**
+No. Unauthenticated usage gets 60 API requests per hour — enough for a single profile analysis.
+Set `GITHUB_TOKEN` to get 5000 requests per hour and avoid hitting limits when comparing many profiles.
+
+**How is the score calculated?**
+Each dimension is scored independently against fixed max points (totalling 100). There is no
+machine learning or relative ranking — the score reflects the absolute presence or absence of
+each signal.
+
+**Can I game the score?**
+You could game every individual metric, but you would also genuinely improve your GitHub presence
+in the process. The signals are chosen because they correlate with real reputation value.
+
+**Why does a well-known developer score lower than expected?**
+Some high-reputation developers (including Linus Torvalds) score below 80 because they skip
+signals like topic tags, profile READMEs, or GitHub Releases. The tool measures profile
+hygiene signals, not absolute influence.
+
+**How often should I re-run this?**
+After each batch of improvements. Treat it like `npm audit` — run it, fix the findings, move on.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and improvements welcome — open an issue on
+[github.com/basilalshukaili/github-rep](https://github.com/basilalshukaili/github-rep/issues).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

github_rep-0.2.0/README.md

@@ -0,0 +1,213 @@
+# github-rep
+
+[![PyPI version](https://img.shields.io/pypi/v/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![Python versions](https://img.shields.io/pypi/pyversions/github-rep.svg)](https://pypi.org/project/github-rep/)
+[![CI](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml/badge.svg)](https://github.com/basilalshukaili/github-rep/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Score any GitHub user's reputation across 11 honest signals and get a prioritized fix list — in under 30 seconds.**
+
+---
+
+## Why this exists
+
+GitHub profiles are the de-facto developer resume. Most advice on building GitHub reputation is either
+vague ("just contribute more") or gameable (spam-stars, low-effort PRs). This tool measures the signals
+that actually matter to recruiters, maintainers, and other developers — and tells you exactly what to
+fix first, ordered by impact.
+
+---
+
+## Install
+
+```bash
+pip install github-rep
+```
+
+Requires Python 3.9+. No configuration needed — works unauthenticated (60 req/hr) or with a GitHub
+token for 5000 req/hr.
+
+---
+
+## Quickstart
+
+```bash
+# Analyze any GitHub user
+github-rep analyze-profile torvalds
+
+# Use a token to avoid rate limits
+export GITHUB_TOKEN=ghp_yourtoken
+github-rep analyze-profile sindresorhus
+
+# Machine-readable JSON output
+github-rep analyze-profile gvanrossum --json
+
+# Show all findings, including low-priority ones
+github-rep analyze-profile octocat --verbose
+
+# Compare multiple profiles side by side
+github-rep compare torvalds gvanrossum sindresorhus
+
+# Check your API rate limit
+github-rep rate-limit
+```
+
+---
+
+## Sample output
+
+```
+$ github-rep analyze-profile torvalds
+
+╭──────────────────────────────── GitHub Profile ─────────────────────────────╮
+│ @torvalds  |  Linus Torvalds                                                │
+│                                                                              │
+│ Followers: 305,509  |  Public repos: 12  |  Stars earned: 246,028           │
+╰──────────────────────────────────────────────────────────────────────────────╯
+Grade: B  (78/100)
+Tier: Active developer
+
+                Score Breakdown
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
+┃ Dimension                ┃  Score ┃   Max ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
+│ Profile Completeness     │      4 │    10 │
+│ Readme Quality           │     12 │    15 │
+│ Star Signal              │     20 │    20 │
+│ Contribution Streak      │     15 │    15 │
+│ Repo Diversity           │      7 │    10 │
+│ Description Quality      │     10 │    10 │
+│ Topic Tags               │      0 │     5 │
+│ Fork Ratio               │      5 │     5 │
+│ Recent Activity          │      5 │    10 │
+│ Release Cadence          │      0 │     5 │
+│ Profile Readme           │      0 │     5 │
+└──────────────────────────┴────────┴───────┘
+
+Priority fixes:
+  [HIGH] Missing bio
+     Your bio is empty. It is the first thing visitors read.
+     Fix: Write 1-2 sentences: your focus, what you build, your superpower.
+
+What is working:
+  [GOOD] Strong star signal (246028 total, top repo: 235147)
+  [GOOD] Active recent commits (0d ago)
+  [GOOD] All repos have descriptions
+```
+
+Grades: **A** (≥80) · **B** (≥65) · **C** (≥50) · **D** (≥35) · **F**
+
+---
+
+## The 11 scored dimensions
+
+| # | Dimension | Max pts | What it measures |
+|---|-----------|--------:|------------------|
+| 1 | Profile Completeness | 10 | Name, bio, avatar, location, website / social link |
+| 2 | README Quality | 15 | Top repo README length, code examples, install instructions |
+| 3 | Star Signal | 20 | Total stars earned across all repos (log-scaled) |
+| 4 | Contribution Streak | 15 | Days since last profile activity |
+| 5 | Repo Diversity | 10 | Number of public repos and language breadth |
+| 6 | Description Quality | 10 | Fraction of repos with meaningful descriptions |
+| 7 | Topic Tags | 5 | Repos tagged with relevant GitHub topics |
+| 8 | Fork Ratio | 5 | Proportion of original work vs. forked repos |
+| 9 | Recent Activity | 10 | Repos with pushes in the last 90 days |
+| 10 | **Release Cadence** | 5 | Published GitHub Releases on top repos |
+| 11 | **Profile README** | 5 | Presence and quality of the username/username profile README |
+
+**Total: 100 points.**
+
+Dimensions 10 and 11 are new in v0.2.0 and measure signals that indicate a polished,
+production-ready presence — publishing versioned releases and curating a profile page.
+
+---
+
+## All flags
+
+```
+github-rep analyze-profile <username> [OPTIONS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output (all scores + findings) |
+| `--verbose` / `-v` | Show all findings including low-priority improvements |
+| `--token` / `-t` | GitHub PAT (also reads `GITHUB_TOKEN` env var) |
+| `--top N` | Number of top repos to deep-analyze (default: 10) |
+| `--help` | Show help and exit |
+
+---
+
+## JSON output
+
+```bash
+github-rep analyze-profile gvanrossum --json
+```
+
+```json
+{
+  "username": "gvanrossum",
+  "total": 72,
+  "grade": "B",
+  "tier": "Active developer",
+  "breakdown": {
+    "profile_completeness": 8,
+    "readme_quality": 12,
+    ...
+  },
+  "findings": [
+    {
+      "category": "topic_tags",
+      "severity": "medium",
+      "title": "Most repos have no topic tags",
+      "detail": "Missing from GitHub Explore category pages entirely.",
+      "fix": "Add topics to your top 3 repos today - GitHub UI, takes 2 minutes."
+    }
+  ]
+}
+```
+
+---
+
+## Caching
+
+Results are cached for 5 minutes under `~/.cache/github-rep/` to avoid hitting rate limits when
+running the tool multiple times. Delete the cache directory to force a fresh fetch.
+
+---
+
+## FAQ
+
+**Do I need a GitHub token?**
+No. Unauthenticated usage gets 60 API requests per hour — enough for a single profile analysis.
+Set `GITHUB_TOKEN` to get 5000 requests per hour and avoid hitting limits when comparing many profiles.
+
+**How is the score calculated?**
+Each dimension is scored independently against fixed max points (totalling 100). There is no
+machine learning or relative ranking — the score reflects the absolute presence or absence of
+each signal.
+
+**Can I game the score?**
+You could game every individual metric, but you would also genuinely improve your GitHub presence
+in the process. The signals are chosen because they correlate with real reputation value.
+
+**Why does a well-known developer score lower than expected?**
+Some high-reputation developers (including Linus Torvalds) score below 80 because they skip
+signals like topic tags, profile READMEs, or GitHub Releases. The tool measures profile
+hygiene signals, not absolute influence.
+
+**How often should I re-run this?**
+After each batch of improvements. Treat it like `npm audit` — run it, fix the findings, move on.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and improvements welcome — open an issue on
+[github.com/basilalshukaili/github-rep](https://github.com/basilalshukaili/github-rep/issues).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{github_rep-0.1.1 → github_rep-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "github-rep"
-version = "0.1.1"
+version = "0.2.0"
 description = "Analyze a GitHub profile and get honest, actionable advice for building real reputation"
 readme = "README.md"
 license = { text = "MIT" }

github_rep-0.2.0/src/github_rep/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{github_rep-0.1.1 → github_rep-0.2.0}/src/github_rep/analyzer.py

@@ -1,4 +1,4 @@
-"""Profile analyzer: scores genuine reputation signals across 9 dimensions."""
+"""Profile analyzer: scores genuine reputation signals across 11 dimensions."""
 
 from __future__ import annotations
 
@@ -67,7 +67,7 @@ class ProfileScore:
         return "Just starting"
 
 
-# ── Helpers ───────────────────────────────────────────────────────────────────
+# -- Helpers -------------------------------------------------------------------
 
 def _days_since(dt_str: Optional[str]) -> Optional[int]:
     if not dt_str:
@@ -113,7 +113,6 @@ def _readme_score(readme_text: Optional[str]) -> Tuple[int, List[Finding]]:
     else:
         score += 12
 
-    # Code examples
     if "```" in readme_text or "`" in readme_text:
         score += 2
     else:
@@ -124,7 +123,6 @@ def _readme_score(readme_text: Optional[str]) -> Tuple[int, List[Finding]]:
             "Add a quick-start code block showing the most common use case.",
         ))
 
-    # Installation instructions
     has_install = any(
         kw in readme_text.lower()
         for kw in ["install", "pip install", "npm install", "brew install", "cargo add"]
@@ -142,14 +140,14 @@ def _readme_score(readme_text: Optional[str]) -> Tuple[int, List[Finding]]:
     return min(score, 15), findings
 
 
-# ── Main analyzer ─────────────────────────────────────────────────────────────
+# -- Main analyzer -------------------------------------------------------------
 
 def analyze(
     username: str,
     token: Optional[str] = None,
     top_n: int = 10,
 ) -> ProfileScore:
-    """Fetch GitHub data and compute a ProfileScore across 9 dimensions.
+    """Fetch GitHub data and compute a ProfileScore across 11 dimensions.
 
     Args:
         username:  GitHub username to analyze.
@@ -168,7 +166,7 @@ def analyze(
     breakdown: Dict[str, int] = {}
     findings: List[Finding] = []
 
-    # ── 1. Profile completeness (10 pts) ──────────────────────────────────────
+    # 1. Profile completeness (10 pts) ----------------------------------------
     pc = 0
     if user.get("bio"):
         pc += 3
@@ -213,7 +211,7 @@ def analyze(
         ))
     breakdown["profile_completeness"] = min(pc, 10)
 
-    # ── 2. README quality (15 pts) ────────────────────────────────────────────
+    # 2. README quality (15 pts) -----------------------------------------------
     readme_text: Optional[str] = None
     if top_repos:
         best = top_repos[0]
@@ -226,7 +224,7 @@ def analyze(
     breakdown["readme_quality"] = readme_pts
     findings.extend(readme_findings)
 
-    # ── 3. Star signal (20 pts) ───────────────────────────────────────────────
+    # 3. Star signal (20 pts) --------------------------------------------------
     total_stars = sum(r.get("stargazers_count", 0) for r in repos)
     max_stars = max((r.get("stargazers_count", 0) for r in repos), default=0)
     if total_stars == 0:
@@ -244,8 +242,7 @@ def analyze(
             "star_signal", "medium",
             f"Low star count ({total_stars} total)",
             "Genuine stars come from genuine visibility.",
-            "Share in community WHEN you have something useful to say "
-            "(build log, lesson learned, solved problem).",
+            "Share in community when you have something useful to say.",
         ))
     elif total_stars < 25:
         star_pts = 10
@@ -262,7 +259,7 @@ def analyze(
         ))
     breakdown["star_signal"] = star_pts
 
-    # ── 4. Contribution activity (15 pts) ─────────────────────────────────────
+    # 4. Contribution activity (15 pts) ----------------------------------------
     days = _days_since(user.get("updated_at"))
     if days is None or days > 180:
         streak_pts = 0
@@ -291,7 +288,7 @@ def analyze(
         ))
     breakdown["contribution_streak"] = streak_pts
 
-    # ── 5. Repo diversity (10 pts) ────────────────────────────────────────────
+    # 5. Repo diversity (10 pts) -----------------------------------------------
     n_repos = len(repos)
     if n_repos == 0:
         div_pts = 0
@@ -322,7 +319,7 @@ def analyze(
             ))
     breakdown["repo_diversity"] = div_pts
 
-    # ── 6. Description quality (10 pts) ───────────────────────────────────────
+    # 6. Description quality (10 pts) ------------------------------------------
     repos_missing_desc = [r for r in repos if not r.get("description")]
     if repos_missing_desc:
         pct = len(repos_missing_desc) / max(len(repos), 1)
@@ -343,7 +340,7 @@ def analyze(
         ))
     breakdown["description_quality"] = desc_pts
 
-    # ── 7. Topic tags (5 pts) ─────────────────────────────────────────────────
+    # 7. Topic tags (5 pts) ----------------------------------------------------
     repos_without_topics = [r for r in repos if not r.get("topics")]
     if not repos_without_topics:
         topic_pts = 5
@@ -370,7 +367,7 @@ def analyze(
         ))
     breakdown["topic_tags"] = topic_pts
 
-    # ── 8. Fork ratio (5 pts) ─────────────────────────────────────────────────
+    # 8. Fork ratio (5 pts) ----------------------------------------------------
     all_repos_with_forks = client.get_repos(username, include_forks=True)
     fork_count = sum(1 for r in all_repos_with_forks if r.get("fork"))
     total_count = len(all_repos_with_forks)
@@ -389,7 +386,7 @@ def analyze(
         fork_pts = 5
     breakdown["fork_ratio"] = fork_pts
 
-    # ── 9. Recent activity quality (10 pts) ───────────────────────────────────
+    # 9. Recent activity quality (10 pts) --------------------------------------
     recently_active = [
         r for r in repos
         if _days_since(r.get("pushed_at")) is not None
@@ -420,7 +417,82 @@ def analyze(
         ))
     breakdown["recent_activity"] = ra_pts
 
-    # ── Aggregate ─────────────────────────────────────────────────────────────
+    # 10. Release cadence (5 pts) -- NEW ---------------------------------------
+    # Published releases signal versioned, production-ready software that
+    # users can subscribe to and depend on.
+    release_pts = 0
+    total_releases = 0
+    for repo in top_repos[:5]:
+        try:
+            releases = client.get(f"/repos/{username}/{repo['name']}/releases",
+                                  params={"per_page": 5})
+            total_releases += len(releases)
+        except Exception:
+            pass
+    if total_releases == 0:
+        release_pts = 0
+        if top_repos:
+            findings.append(Finding(
+                "release_cadence", "low",
+                "No published releases",
+                "GitHub Releases make your project feel production-ready and "
+                "let users subscribe to new versions.",
+                "Tag your first release: git tag v0.1.0 && git push --tags, "
+                "then create a GitHub release with changelog notes.",
+            ))
+    elif total_releases < 3:
+        release_pts = 3
+        findings.append(Finding(
+            "release_cadence", "low",
+            f"Only {total_releases} published release(s)",
+            "A release cadence signals active maintenance.",
+            "Aim for a release whenever you ship a meaningful change.",
+        ))
+    else:
+        release_pts = 5
+        findings.append(Finding(
+            "release_cadence", "good",
+            f"{total_releases} published releases across top repos",
+            "Regular releases signal a maintained, production-quality project.",
+        ))
+    breakdown["release_cadence"] = release_pts
+
+    # 11. Profile README signal (5 pts) -- NEW ---------------------------------
+    # A profile README (special repo username/username) is displayed at the
+    # top of the GitHub profile page - the highest-visibility real estate.
+    profile_readme_pts = 0
+    try:
+        raw = client.get(f"/repos/{username}/{username}/readme")
+        profile_text = base64.b64decode(raw["content"]).decode("utf-8", errors="replace")
+        word_count = len(profile_text.split())
+        if word_count >= 100:
+            profile_readme_pts = 5
+            findings.append(Finding(
+                "profile_readme", "good",
+                f"Profile README exists and is substantial ({word_count} words)",
+                "A profile README is the highest-visibility real estate on GitHub.",
+            ))
+        else:
+            profile_readme_pts = 2
+            findings.append(Finding(
+                "profile_readme", "low",
+                f"Profile README is short ({word_count} words)",
+                "You have a profile README but it could work harder for you.",
+                "Add your current focus, top project links, and how to contact you.",
+            ))
+    except Exception:
+        profile_readme_pts = 0
+        findings.append(Finding(
+            "profile_readme", "medium",
+            "No profile README",
+            f"A profile README (create repo: {username}/{username}) is the first "
+            "thing visitors see. Prime real estate for your personal brand.",
+            f"Create a repo named exactly '{username}' with a README.md showing "
+            "your focus, skills, and top projects.",
+        ))
+    breakdown["profile_readme"] = profile_readme_pts
+
+    # Aggregate ----------------------------------------------------------------
     total = sum(breakdown.values())
     severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3, "good": 4}
     findings.sort(key=lambda f: severity_order.get(f.severity, 5))