resuml 1.18.1 → 1.19.1

package/README.md

@@ -1,5 +1,5 @@
-<h1 align="center">✨ Resuml</h1>
-<p align="center"><strong>Write your resume in YAML. Render it beautifully.</strong></p>
+<h1 align="center">✨ resuml</h1>
+<p align="center"><strong>Resume as code. YAML in, beautiful resume out.</strong></p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/resuml"><img src="https://img.shields.io/npm/v/resuml.svg" alt="npm version"></a>
@@ -9,305 +9,40 @@
 </p>
 
 <p align="center">
-   <a href="https://www.buymeacoffee.com/leekbeds55j">
-      <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" width="150" />
-   </a>
+  <a href="https://resuml.app"><strong>👉 Try it in your browser at resuml.app</strong></a>
 </p>
 
 ---
 
-### YAML in → Beautiful resume out
+## Two ways to use it
 
-```yaml
-# resume.yaml
-basics:
-  name: Jane Smith
-  label: Senior Software Engineer
-  email: jane@example.com
-  summary: >-
-    Passionate engineer with 8+ years
-    building scalable distributed systems.
-work:
-  - name: Acme Corp
-    position: Lead Engineer
-    startDate: 2020-01-15
-    highlights:
-      - Reduced deploy time by 60%
-      - Led team of 12 engineers
-```
-
-```bash
-resuml render --resume resume.yaml --theme stackoverflow --output resume.html
-```
-
-Your YAML becomes a polished, professional resume — ready to share, print, or export to PDF.
-
----
-
-## Why YAML?
-
-| | YAML | JSON |
-|---|---|---|
-| **Comments** | ✅ `# explain your choices` | ❌ Not supported |
-| **Multi-line strings** | ✅ `summary: >-` block syntax | ❌ Escape everything |
-| **Readability** | ✅ Clean, minimal syntax | ⚠️ Brackets & quotes everywhere |
-| **Diffing** | ✅ Clean git diffs | ⚠️ Noisy diffs |
-| **Compatibility** | ✅ Valid JSON Resume schema | ✅ Native |
+### 🌐 [resuml.app](https://resuml.app) — the web app
 
-YAML is a superset of JSON — your resume stays fully compatible with the [JSON Resume](https://jsonresume.org/) ecosystem while being far more pleasant to write and maintain.
+Free, open source, no signup. Your resume data stays in your browser — we don't store or track anything. Write in YAML or use the form editor, pick from 300+ themes, check your ATS match against a job description, and export to PDF.
 
-## Prerequisites
+### 🤖 With Claude Code / AI agents (MCP)
 
-- Node.js >= 20.0.0
-- npm >= 10.0.0
+resuml ships with a built-in [MCP server](https://modelcontextprotocol.io/) so Claude Code can read your resume, tailor it to a job description, check the ATS score, and render it — all from a chat.
 
-## Installation
+**One-command setup (recommended):**
 
 ```bash
-npm install -g resuml
+claude mcp add resuml -- npx resuml mcp
 ```
 
-## Quick Start
-
-1. Create a YAML file for your resume (e.g., `resume.yaml`)
-2. Validate your resume data:
-   ```bash
-   resuml validate --resume resume.yaml
-   ```
-3. Convert to JSON:
-   ```bash
-   resuml tojson --resume resume.yaml --output resume.json
-   ```
-4. Render with a theme:
-   ```bash
-   resuml render --resume resume.yaml --theme stackoverflow --output resume.html
-   ```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `validate` | Validate resume data against the JSON Resume schema |
-| `validate --ats` | Run ATS (Applicant Tracking System) compatibility analysis |
-| `tojson` | Convert YAML resume data to JSON format |
-| `render` | Render the resume using a specified theme |
-| `dev` | Start a development server with hot-reload |
-
-## Options
-
-| Option | Alias | Description |
-|--------|-------|-------------|
-| `--resume` | `-r` | Input YAML file(s) or directory |
-| `--output` | `-o` | Output file path |
-| `--theme` | `-t` | Theme to use for rendering |
-| `--port` | `-p` | Port for dev server (default: 3000) |
-| `--language` | | Language code for localization (default: `en`) |
-| `--debug` | | Enable debug mode for detailed errors |
-| `--ats` | | Run ATS compatibility analysis (with `validate`) |
-| `--jd` | | Path to job description file for keyword matching (with `--ats`) |
-| `--ats-threshold` | | Minimum ATS score (0-100); exits with code 1 if below |
-
-## ATS Analysis
-
-Resumls built-in ATS (Applicant Tracking System) analysis helps ensure your resume passes automated screening. Fully offline and deterministic — no API keys or LLMs required.
-
-### Quick Start
+That registers resuml for the current project. Add `--scope user` to make it available across all projects:
 
 ```bash
-# Basic ATS score
-resuml validate --resume resume.yaml --ats
-
-# Match against a specific job description
-resuml validate --resume resume.yaml --ats --jd job-description.txt
-
-# CI/CD gate: fail if score is below threshold
-resuml validate --resume resume.yaml --ats --ats-threshold 75
-
-# Machine-readable JSON output
-resuml validate --resume resume.yaml --ats --format json
-```
-
-### What It Checks
-
-The ATS engine runs 11 deterministic checks across 3 categories:
-
-**Contact Information**
-- Complete contact details (name, email, phone, city)
-- LinkedIn profile present
-
-**Content Quality**
-- Professional summary (length and presence)
-- Work highlights (minimum 2 per entry)
-- Action verbs (highlights start with strong verbs)
-- Quantified impact (numbers, percentages, metrics in highlights)
-- No first-person pronouns
-
-**Resume Structure**
-- Date consistency (no unexplained gaps > 6 months)
-- Skills populated (≥ 3 categories with keywords)
-- Education completeness
-- Essential sections present (basics, work, education, skills)
-
-### Job Description Matching
-
-Provide a job description file to get keyword matching:
-
-```bash
-resuml validate --resume resume.yaml --ats --jd job.txt
+claude mcp add --scope user resuml -- npx resuml mcp
 ```
 
-The engine extracts keywords from the job description using TF-based ranking with stem matching, then compares them against your resume. You get:
-- **Match percentage** — how many JD keywords appear in your resume
-- **Matched keywords** — what you already cover
-- **Missing keywords** — what to consider adding
-
-### Scoring
-
-| Score | Rating | Meaning |
-|-------|--------|-------------|
-| 90-100 | Excellent | Resume is well-optimized for ATS |
-| 75-89 | Good | Minor improvements possible |
-| 60-74 | Needs Work | Several issues to address |
-| 0-59 | Poor | Significant improvements needed |
-
-When a job description is provided, the final score is 60% generic checks + 40% keyword match.
-
-### Multi-Language Support
-
-ATS checks support English and German, with language-specific action verb lists and pronoun detection. Use the `--language` flag:
-
-```bash
-resuml validate --resume lebenslauf.yaml --ats --language de
-```
-
-## Compatible Themes
-
-Resuml supports themes from the JSON Resume ecosystem. Install a theme, then pass its name to `--theme`:
+Verify it's wired up:
 
 ```bash
-npm install jsonresume-theme-stackoverflow
-resuml render --resume resume.yaml --theme stackoverflow
+claude mcp list
 ```
 
-| Theme | Install | Style |
-|-------|---------|-------|
-| [stackoverflow](https://github.com/francoislaberge/jsonresume-theme-stackoverflow) | `npm i jsonresume-theme-stackoverflow` | Clean, professional |
-| [elegant](https://github.com/mudassir0909/jsonresume-theme-elegant) | `npm i jsonresume-theme-elegant` | Modern, elegant |
-| [kendall](https://github.com/LinuxBozo/jsonresume-theme-kendall) | `npm i jsonresume-theme-kendall` | Minimal, classic |
-| [flat](https://github.com/erming/jsonresume-theme-flat) | `npm i jsonresume-theme-flat` | Flat design |
-| [onepage](https://github.com/aonemd/jsonresume-theme-onepage) | `npm i jsonresume-theme-onepage` | Single page |
-
-> Browse all themes at [jsonresume.org/themes](https://jsonresume.org/themes/) — any `jsonresume-theme-*` package works with resuml.
-
-## Examples
-
-For detailed examples and usage instructions, see the [examples/README.md](examples/README.md) file.
-
-## Example YAML Structure
-
-```yaml
-basics:
-  name: John Doe
-  label: Software Engineer
-  email: john@example.com
-  summary: Experienced software engineer...
-  location:
-    city: San Francisco
-    countryCode: US
-  profiles:
-    - network: GitHub
-      url: https://github.com/johndoe
-
-work:
-  - company: Tech Corp
-    position: Senior Engineer
-    startDate: 2020-01
-    endDate: Present
-    summary: Led development of...
-```
-
-## CI/CD: Auto-build on Push
-
-Use GitHub Actions to automatically rebuild your resume when you push changes:
-
-```yaml
-# .github/workflows/resume.yml
-name: Build Resume
-
-on:
-  push:
-    paths: ['resume.yaml', 'resume/*.yaml']
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - run: npm install -g resuml
-      - run: npm install jsonresume-theme-stackoverflow
-
-      # Validate and check ATS score (fails if below 75)
-      - run: resuml validate --resume resume.yaml --ats --ats-threshold 75
-
-      - run: resuml render --resume resume.yaml --theme stackoverflow --output resume.html
-      - run: resuml tojson --resume resume.yaml --output resume.json
-
-      - uses: actions/upload-artifact@v4
-        with:
-          name: resume
-          path: |
-            resume.html
-            resume.json
-```
-
-## Node.js API Usage
-
-You can use resuml programmatically from Node.js:
-
-```js
-import {
-  processResumeData,
-  loadResumeFiles,
-  loadTheme,
-  themeRender,
-  analyzeAts
-} from 'resuml';
-
-// Load YAML files
-const { yamlContents } = await loadResumeFiles('resume.yaml');
-// Validate and merge
-const resume = await processResumeData(yamlContents);
-// Load a theme
-const theme = await loadTheme('stackoverflow');
-// Render HTML
-const html = await theme.render(resume, { locale: 'en' });
-
-// ATS analysis
-const atsResult = analyzeAts(resume, { language: 'en' });
-console.log(`ATS Score: ${atsResult.score}/100`);
-
-// With job description matching
-const jdResult = analyzeAts(resume, {
-  language: 'en',
-  jobDescription: 'Looking for a senior TypeScript developer...'
-});
-console.log(`Matched keywords: ${jdResult.keywords?.matched.join(', ')}`);
-```
-
-See the CLI and API for more details.
-
-## AI Agent Integration (MCP)
-
-Resuml includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server, making it the first resume tool with native AI agent support. Use it with Claude, GitHub Copilot, Cursor, or any MCP-compatible client.
-
-### Setup
-
-Add to your Claude Desktop or MCP client config:
+**Or, for teams sharing the config via git**, create `.mcp.json` at the repo root:
 
 ```json
 {
@@ -320,79 +55,55 @@ Add to your Claude Desktop or MCP client config:
 }
 ```
 
-Or run directly:
-
-```bash
-resuml mcp
-```
-
-### Available Tools
+Then ask Claude Code things like:
 
-| Tool | Purpose |
-|------|---------|
-| `resuml_init_resume` | Generate a starter YAML template |
-| `resuml_validate` | Validate resume YAML against JSON Resume schema |
-| `resuml_ats_check` | ATS analysis + job description keyword matching |
-| `resuml_render` | Render resume to HTML using a theme |
-| `resuml_list_themes` | List available themes and install status |
-| `resuml_export_pdf` | Export resume as PDF (requires Playwright) |
+> "Tailor my resume at `resume.yaml` to this job description, hit ATS score ≥ 80, and render it with the stackoverflow theme."
 
-### Resources
+Claude will generate the YAML, validate it, iterate until the score clears, and render the final HTML. See **[DOCS.md](DOCS.md#ai-agent-integration-mcp)** for all tools, resources, and prompts.
 
-The MCP server exposes structured data agents can read:
-
-| Resource | URI | Description |
-|----------|-----|-------------|
-| JSON Resume Schema | `resuml://schema/json-resume` | Full schema reference with all sections and field types |
-| ATS Scoring Rubric | `resuml://docs/ats-scoring` | Scoring system, checks performed, and optimization tips |
-| Theme Catalog | `resuml://themes/catalog` | Available themes with descriptions and install status |
-
-### Prompts
-
-Pre-built workflows for common tasks:
-
-| Prompt | Description |
-|--------|-------------|
-| `tailor-resume-to-jd` | Generate a tailored resume optimized for a specific job description |
-| `optimize-ats-score` | Analyze and improve an existing resume to maximize ATS score |
-| `review-resume` | Comprehensive review with ATS analysis and improvement suggestions |
+---
 
-### Example Workflow
+## Or use the CLI
 
-Ask your AI assistant:
+```bash
+npm install -g resuml
 
-> "Use the tailor-resume-to-jd prompt to create a resume for this job posting: [paste JD]. My name is Jane Smith, jane@example.com. I have 5 years of experience in TypeScript and React."
+resuml validate --resume resume.yaml --ats --jd job.txt
+resuml render   --resume resume.yaml --theme stackoverflow --output resume.html
+resuml pdf      --resume resume.yaml --theme stackoverflow --output resume.pdf
+```
 
-The agent will:
-1. Generate tailored resume YAML matching the job description keywords
-2. Validate it against the JSON Resume schema
-3. Run ATS analysis targeting score ≥ 75
-4. Iterate until the score meets the target
-5. Render the final result with a professional theme
+**Minimal `resume.yaml`:**
 
-## Troubleshooting
+```yaml
+basics:
+  name: Jane Smith
+  label: Senior Software Engineer
+  email: jane@example.com
+  summary: >-
+    Engineer with 8+ years building scalable distributed systems.
+work:
+  - name: Acme Corp
+    position: Lead Engineer
+    startDate: 2020-01-15
+    highlights:
+      - Reduced deploy time by 60%
+      - Led team of 12 engineers
+```
 
-### Common Issues
+Full CLI reference, Node.js API, ATS rubric, CI/CD setup, and every MCP tool live in **[DOCS.md](DOCS.md)**.
 
-1. **Validation Errors**
-   - Ensure your YAML follows the JSON Resume schema
-   - Check for proper indentation in your YAML file
-   - Verify all required fields are present
+---
 
-2. **Theme Rendering Issues**
-   - Make sure the theme is properly installed
-   - Check if all required theme dependencies are installed
-   - Try running with `--debug` flag for more information
+## Requirements
 
-3. **Development Server Issues**
-   - Ensure the specified port is available
-   - Check if you have proper permissions to access the port
-   - Try a different port if the default is blocked
+- Node.js ≥ 20, npm ≥ 10
+- Nothing else — validation, ATS, rendering, and PDF all run locally
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+PRs welcome. See [DOCS.md](DOCS.md) for architecture and dev setup.
 
 ## License
 
-ISC
+ISC. Support the project: <a href="https://www.buymeacoffee.com/leekbeds55j">☕ Buy me a coffee</a>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resuml",
-  "version": "1.18.1",
+  "version": "1.19.1",
   "description": "Generate JSON resumes from YAML with theme support",
   "type": "module",
   "main": "./dist/api.js",