launch prep: PyPI packaging, README, CI, bug fixes

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Test
+        run: uv run pytest tests/ -x -q

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to DevCard
+
+Thanks for your interest in contributing! Here are some ways to get involved.
+
+## Getting Started
+
+```bash
+git clone https://github.com/chiruu12/devcard.git
+cd devcard
+uv sync --dev
+uv run pytest tests/ -x -q
+```
+
+## Low-Barrier Contributions
+
+### Add dependency mappings
+
+`mappings/dependencies.yaml` maps package names to technologies. If your favorite framework is missing, add it:
+
+```yaml
+python:
+  fastapi:
+    name: FastAPI
+    category: Web Framework
+```
+
+### Add advisor rules
+
+`mappings/advisor_rules.yaml` defines profile improvement rules. Add a rule with a condition, severity, and message.
+
+### Add SVG themes
+
+Themes live in `src/devcard/renderers/themes/`. Copy an existing theme and modify colors. Register it in `cli.py:THEMES`.
+
+## Development
+
+```bash
+uv run pytest tests/ -x -q     # Run tests
+uv run ruff check src/ tests/   # Lint
+uv run devcard generate <user>  # Test CLI
+```
+
+## Pull Requests
+
+- One logical change per PR
+- Include tests for new functionality
+- Run `uv run pytest` and `uv run ruff check src/ tests/` before submitting
+- Keep commit messages short and descriptive

README.md

@@ -1,49 +1,53 @@
 # DevCard
 
-**Auto-generate beautiful, agent-readable developer identity cards from GitHub.**
-
-No sign-up. No scraping. Paste a GitHub username -- get a visual card, structured JSON, AI-powered insights, and terminal output in seconds.
+<p align="center">
+  <img src="gallery/karpathy-dark.svg" alt="DevCard for Andrej Karpathy" width="495">
+</p>
 
-![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
-![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)
-![Schema](https://img.shields.io/badge/schema-v1.0-orange.svg)
+<p align="center">
+  <strong>Auto-generate beautiful, agent-readable developer identity cards from GitHub.</strong>
+</p>
 
 <p align="center">
-  <img src="gallery/karpathy-dark.svg" alt="DevCard for Andrej Karpathy" width="495">
+  <a href="https://pypi.org/project/devcard/"><img src="https://img.shields.io/pypi/v/devcard.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-green.svg" alt="License">
+  <img src="https://img.shields.io/badge/schema-v1.0-orange.svg" alt="Schema">
 </p>
 
+No sign-up. No scraping. Paste a GitHub username -- get a visual card, structured JSON, AI-powered insights, and terminal output in seconds.
+
+## Why DevCard?
+
+We optimize GitHub profiles for humans -- clean READMEs, pinned repos, contribution graphs. But AI agents are already evaluating developer capabilities, and they're scraping GitHub the same ad-hoc way we scraped resumes 10 years ago.
+
+DevCard creates a **structured protocol for developer identity**. A `devcard.json` that says "I'm an ML engineer who ships production PyTorch, with 95% test coverage across my repos" -- readable by both humans and machines.
+
+- **14+ signals** extracted from public GitHub data (languages, stack, activity, code quality, collaboration style)
+- **Dual scoring** -- Human Visibility (recruiters) + Agent Readiness (AI tools)
+- **MCP server** -- AI agents query developer profiles as structured data, not scraped HTML
+
 ## Quick Start
 
 ```bash
-# Clone the repo
-git clone https://github.com/chiruu12/devcard.git
-cd devcard
-
-# Install dependencies (requires uv — https://docs.astral.sh/uv/)
-uv sync
+pip install devcard
 
 # (Recommended) Set your GitHub token for 5000 req/hr instead of 60
-export GITHUB_TOKEN=$(gh auth token)   # or: export GITHUB_TOKEN=ghp_your_token
+export GITHUB_TOKEN=$(gh auth token)
 
 # Generate your card
-uv run devcard generate YOUR_USERNAME
+devcard generate YOUR_USERNAME
 
 # Get an SVG for your GitHub README
-uv run devcard generate YOUR_USERNAME --format svg --theme dark
+devcard generate YOUR_USERNAME --format svg --theme dark
 
 # Get actionable profile advice
-uv run devcard advise YOUR_USERNAME
+devcard advise YOUR_USERNAME
 
 # Compare two developers
-uv run devcard compare karpathy torvalds
-
-# AI-powered insights (requires Fireworks API key)
-export FIREWORKS_API_KEY=your-key
-uv run devcard generate YOUR_USERNAME --enrich
+devcard compare karpathy torvalds
 ```
 
-> **Note:** DevCard is not yet published to PyPI. Install from source as shown above.
-
 ## What It Extracts
 
 DevCard analyzes public GitHub data to build a structured developer profile with 14+ signals:
@@ -69,29 +73,29 @@ All signals are extracted from public GitHub API data.
 
 ## Commands
 
-### `uv run devcard generate <username>`
+### `devcard generate <username>`
 
 Generate a DevCard for any public GitHub user.
 
 ```bash
-uv run devcard generate torvalds                              # Terminal output (default)
-uv run devcard generate torvalds --format svg --theme dark    # Dark SVG card
-uv run devcard generate torvalds --format json -o out.json    # Save JSON to file
-uv run devcard generate torvalds --token ghp_xxx              # Explicit token
-uv run devcard generate torvalds --enrich                     # AI-powered insights
-uv run devcard generate torvalds --no-cache                   # Fresh data
-uv run devcard generate torvalds --verbose                    # Debug logging
+devcard generate torvalds                              # Terminal output (default)
+devcard generate torvalds --format svg --theme dark    # Dark SVG card
+devcard generate torvalds --format json -o out.json    # Save JSON to file
+devcard generate torvalds --token ghp_xxx              # Explicit token
+devcard generate torvalds --enrich                     # AI-powered insights
+devcard generate torvalds --no-cache                   # Fresh data
+devcard generate torvalds --verbose                    # Debug logging
 ```
 
-### `uv run devcard advise <username>`
+### `devcard advise <username>`
 
 Get actionable profile advice with scores, praise, and critiques.
 
 ```bash
-uv run devcard advise chiruu12                    # Rules-based advice (no LLM needed)
-uv run devcard advise chiruu12 --enrich           # Add LLM-generated summary
-uv run devcard advise chiruu12 --format json      # Machine-readable advice
-uv run devcard advise chiruu12 --format markdown  # GFM output
+devcard advise chiruu12                    # Rules-based advice (no LLM needed)
+devcard advise chiruu12 --enrich           # Add LLM-generated summary
+devcard advise chiruu12 --format json      # Machine-readable advice
+devcard advise chiruu12 --format markdown  # GFM output
 ```
 
 Outputs:
@@ -100,44 +104,64 @@ Outputs:
 - **Verdicts** -- praise (what's good), critiques (what to fix), suggestions (nice-to-have)
 - Each critique includes a specific **action** to fix it
 
-### `uv run devcard compare <user1> <user2>`
+### `devcard compare <user1> <user2>`
 
 Compare two developers side by side.
 
 ```bash
-uv run devcard compare karpathy torvalds             # Terminal comparison
-uv run devcard compare karpathy torvalds --format json   # JSON with both cards
+devcard compare karpathy torvalds             # Terminal comparison
+devcard compare karpathy torvalds --format json   # JSON with both cards
 ```
 
-### `uv run devcard validate <file>`
+### `devcard validate <file>`
 
 Validate a `devcard.json` against the schema.
 
 ```bash
-uv run devcard validate my-devcard.json
+devcard validate my-devcard.json
 ```
 
-### `uv run devcard me`
+### `devcard me`
 
 Generate a DevCard for your own GitHub account (detected via `gh` CLI).
 
 ```bash
-uv run devcard me --format svg --theme neon
+devcard me --format svg --theme neon
 ```
 
 ## Output Formats
 
 ```bash
-uv run devcard generate <username> --format terminal   # Rich terminal panels (default)
-uv run devcard generate <username> --format json        # Structured devcard.json
-uv run devcard generate <username> --format yaml        # Human-friendly YAML
-uv run devcard generate <username> --format svg         # Embeddable SVG card
-uv run devcard generate <username> --format markdown    # GitHub Flavored Markdown
-uv run devcard generate <username> --format agent       # Machine-readable key:value
-uv run devcard generate <username> --format llms-txt    # llms.txt spec for AI agents
-uv run devcard generate <username> --format all         # Everything at once
+devcard generate <username> --format terminal   # Rich terminal panels (default)
+devcard generate <username> --format json        # Structured devcard.json
+devcard generate <username> --format yaml        # Human-friendly YAML
+devcard generate <username> --format svg         # Embeddable SVG card
+devcard generate <username> --format markdown    # GitHub Flavored Markdown
+devcard generate <username> --format agent       # Machine-readable key:value
+devcard generate <username> --format llms-txt    # llms.txt spec for AI agents
+devcard generate <username> --format all         # Everything at once
+```
+
+## Made for AI Agents
+
+DevCard outputs are designed for machine consumption, not just human eyes.
+
+```bash
+devcard generate torvalds --format agent      # Key:value pairs for AI tools
+devcard generate torvalds --format llms-txt   # llms.txt protocol spec
+devcard generate torvalds --format json       # Structured devcard.json
+```
+
+DevCard ships as an **MCP server**, so AI agents like Claude can query developer profiles directly:
+
+```python
+# An AI agent calls:
+get_devcard("torvalds")  # Returns typed fields for every signal
+compare("karpathy", "torvalds")  # Side-by-side structured comparison
 ```
 
+See [devcard-mcp/README.md](devcard-mcp/README.md) for MCP setup.
+
 ## AI Enrichment (Optional)
 
 With a Fireworks API key, `--enrich` adds LLM-powered analysis:
@@ -150,9 +174,9 @@ With a Fireworks API key, `--enrich` adds LLM-powered analysis:
 
 ```bash
 export FIREWORKS_API_KEY=your-key
-uv sync --extra enrich                                   # Install AI dependencies
-uv run devcard generate karpathy --enrich                # Generate with AI insights
-uv run devcard advise chiruu12 --enrich                  # Advice with AI summary
+pip install devcard[enrich]                            # Install AI dependencies
+devcard generate karpathy --enrich                     # Generate with AI insights
+devcard advise chiruu12 --enrich                       # Advice with AI summary
 ```
 
 ## Themes
@@ -186,7 +210,7 @@ uv run devcard advise chiruu12 --enrich                  # Advice with AI summar
 
 1. Generate your SVG:
    ```bash
-   uv run devcard generate YOUR_USERNAME --format svg --theme dark -o devcard.svg
+   devcard generate YOUR_USERNAME --format svg --theme dark -o devcard.svg
    ```
 
 2. Add `devcard.svg` to your profile repo (`YOUR_USERNAME/YOUR_USERNAME`)
@@ -211,10 +235,6 @@ DevCard ships with 4 skills for Claude Code users. Add them to your Claude Code
 
 Skills are in `skills/claude-code/`. To use them, point your Claude Code skill path to this directory.
 
-## MCP Server
-
-DevCard includes an MCP server for AI agents (Claude Desktop, Cursor, etc.). See [devcard-mcp/README.md](devcard-mcp/README.md) for setup.
-
 ## The devcard.json Schema
 
 Every DevCard produces a `devcard.json` -- a structured, agent-readable profile:
@@ -261,46 +281,16 @@ CLI (typer) --> Pipeline
 ## Development
 
 ```bash
-uv sync                             # Install dependencies
-uv run pytest                       # Run tests (357 tests)
+git clone https://github.com/chiruu12/devcard.git
+cd devcard
+uv sync --dev                       # Install dependencies
+uv run pytest                       # Run tests (361 tests)
 uv run ruff check src/ tests/       # Lint
-uv run devcard generate chiruu12    # Test locally
-uv run devcard advise chiruu12      # Test advisor
-```
-
-## Contributing
-
-Contributions are welcome! Here are the easiest ways to help:
-
-### Add dependency mappings
-
-Know a popular package we're missing? Edit [`mappings/dependencies.yaml`](mappings/dependencies.yaml):
-
-```yaml
-python:
-  my-package: { category: "framework", name: "My Package" }
+devcard generate chiruu12            # Test locally
+devcard advise chiruu12              # Test advisor
 ```
 
-### Add advisor rules
-
-Want to improve the profile advice? Edit [`mappings/advisor_rules.yaml`](mappings/advisor_rules.yaml). Each rule has a condition, message, and optional fix action.
-
-### Add a theme
-
-Create a new file in `src/devcard/renderers/themes/`:
-
-```python
-from devcard.renderers.themes.base import Theme
-
-THEME = Theme(
-    name="my-theme",
-    background="#...",
-    foreground="#...",
-    secondary="#...",
-    accent="#...",
-    border="#...",
-)
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
 ## Roadmap
 
@@ -313,10 +303,10 @@ THEME = Theme(
 - [x] Notable contributions detection
 - [x] MCP server (10 tools)
 - [x] Claude Code skills (4 skills)
-- [ ] Web app -- connect GitHub, generate your card, share a link
+- [x] PyPI publishing -- `pip install devcard`
 - [ ] GitHub Action -- auto-update your DevCard SVG on push
 - [ ] PNG export -- for social sharing
-- [ ] PyPI publishing -- `pip install devcard`
+- [ ] Web app -- connect GitHub, generate your card, share a link
 
 ## License