feat(decisions): percentage-based skills scoring and AI improvements

AGENTS.md

@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Philosophy & Scope
+
+This repository is a Turborepo-driven Next.js monorepo focused purely on technical excellence—no community morale docs or Code of Conduct. Always build features with performance, maintainability, and developer experience in mind. When adding AI capabilities, standardize on Vercel AI SDK v5 (`ai` + `@ai-sdk/openai`) with streaming responses and tool calling.
+
+## Structure & Shared Modules
+
+Core apps live in `apps/`: the `registry` resume platform and the `homepage2` marketing site. Edge routes reside at `app/api`. Shared UI, linting rules, and utilities come from `packages/` (notably `packages/ui` and the `jsonresume-theme-*` packages). Supabase migrations and config live in `supabase/`, reference docs in `docs/`, helper scripts in `scripts/`, and sample resume data in `resume.yaml`. Keep feature logic, hooks, components, and `*.test.*` files co-located under the relevant app or package.
+
+## Build, Test & Tooling
+
+- `pnpm install` — install workspace deps (run from repo root).
+- `pnpm turbo dev` / `pnpm turbo dev --filter=registry` — start all or targeted apps.
+- `pnpm build` — execute all build pipelines before merging.
+- `pnpm lint` and `pnpm format` — enforce shared ESLint + Prettier rules.
+- `pnpm turbo test` or `pnpm --filter registry test -- --run` — run Vitest suites.
+- `pnpm test:e2e` — execute Playwright flows; boot registry locally first.
+- Supabase CLI (`supabase link`, `supabase db push`) manages the `registry` database schema.
+
+## Coding Style & Architecture
+
+Rely on Prettier (2-space indent, single quotes) and `@repo/eslint-config-custom`—avoid manual formatting tweaks. Prefer TypeScript, exporting shared types and avoiding `any`. Use `PascalCase` components, `useCamelCase` hooks, and `camelCase` utilities. Enforce line limits: ≤200 for production code, ≤500 for tests/stories/config. Apply single-responsibility structure by extracting hooks, utilities, and subcomponents, and ensure themes avoid runtime `fs` usage to remain serverless-compatible.
+
+## Testing Expectations
+
+Colocate deterministic Vitest specs (`*.test.(ts|js)`) with the code they cover, focusing on utilities, parsers, calculations, and API handlers over simple UI. Maintain snapshots intentionally and document any temporary gaps. Use the Playwright MCP server to exercise critical flows (login, resume publishing, exports) across desktop and mobile breakpoints. No coverage targets—test what matters and confirm all suites pass before pushing.
+
+## Commits & PR Workflow
+
+Use Conventional Commits (`type(scope): summary`), as in `fix(navigation): update docs links`. Perform local git commits—never rely on GitHub API file updates. PRs must outline changes, link issues, list executed commands (`pnpm lint`, `pnpm turbo test`, `pnpm build`, `pnpm test:e2e` when relevant), and attach screenshots for UI updates. Keep environment samples (`apps/registry/.env.example`) in sync, ensure CI is green, and request review only after validating builds and tests.

apps/docs/FAQ_COVERAGE.md

@@ -0,0 +1,309 @@
+# FAQ Coverage Summary
+
+## Comprehensive FAQ Created
+
+**File:** `apps/docs/app/faq/page.mdx`
+**Total Lines:** 7,602
+**Format:** MDX (Markdown + JSX)
+
+## Categories Covered (Questions 106-250)
+
+### ✅ Conversion & Compatibility (106-115)
+
+- LinkedIn profile conversion
+- Indeed/Monster imports
+- PDF resume conversion
+- Multiple format exports (Word, LaTeX, etc.)
+- Europass CV compatibility
+- ATS system compatibility
+- Migration from old formats
+- GitHub Pages hosting
+- JSON-LD integration
+
+### ✅ Examples & Templates (116-125)
+
+- Example resumes across industries
+- Industry-specific templates (Tech, Design, Academic, Business)
+- Preview before publishing
+- Theme color customization
+- Popular themes comparison
+- Custom sections
+- Profile pictures
+- Side projects/open source showcase
+- Minimalist/one-page templates
+- Creative/portfolio-style resumes
+
+### ✅ Validation & Troubleshooting (126-135)
+
+- Resume validation methods
+- Rendering issues debugging
+- Common schema validation errors
+- Theme rendering issues
+- Missing fields troubleshooting
+- JSON syntax error fixes
+- Pre-publishing testing
+- Cross-device compatibility
+- Lost/corrupted file recovery
+- Export vs preview differences
+
+### ✅ Conceptual & Design Questions (136-145)
+
+- Why JSON for resumes
+- JSON Resume vs LinkedIn comparison
+- Schema design philosophy
+- Replacing traditional resumes
+- Project inspiration and history
+- Non-traditional career paths support
+- JSON vs Markdown resumes
+- Team/company hiring at scale
+- Schema extensibility
+- Limitations of JSON format
+
+### ✅ Privacy & Security (146-155)
+
+- Resume data privacy
+- Published resume visibility
+- Personal info removal
+- Employer tracking
+- Registry security
+- Home address recommendations
+- Password protection options
+- Registry data collection
+- Confidential job searches
+- Government/security clearance jobs
+
+### ✅ API & Ecosystem (156-165)
+
+- JSON Resume API usage
+- LinkedIn integration
+- WordPress/Squarespace/Webflow plugins
+- LinkedIn format export
+- Third-party tools ecosystem
+- Community resources
+
+### ✅ Community & Governance (165-175)
+
+- Project governance model
+- Contribution guidelines
+- Community participation
+- Decision-making process
+- Open source development
+
+### ✅ Advanced / Power User Topics (176-190)
+
+- Programmatic resume generation
+- Auto-updating from GitHub
+- A/B testing resume versions
+- Custom automation scripts
+- Dynamic data sources
+- Performance optimization
+
+### ✅ Employers & Recruiters (191-200)
+
+- Candidate search strategies
+- ATS integration for companies
+- Bulk resume processing
+- Resume parsing
+- Hiring workflow integration
+
+### ✅ Future & Roadmap (201-210)
+
+- Planned features
+- Schema v2.0 considerations
+- Community feature requests
+- Technology evolution
+- Long-term vision
+
+### ✅ Miscellaneous / Fun (211-220)
+
+- CV vs resume usage
+- Creative use cases
+- Fun facts about JSON Resume
+- Unusual applications
+- Community stories
+
+### ✅ Technical & Schema Edge Cases (221-230)
+
+- International phone numbers
+- Complex date scenarios
+- Multiple roles at same company
+- Overlapping employment
+- Gap year handling
+- Freelance work representation
+- Special characters handling
+- Large file optimization
+
+### ✅ Internationalization (231-240)
+
+- Multilingual resumes
+- Translation strategies
+- RTL language support
+- Country-specific formats
+- Cultural considerations
+- Date/time localization
+- Currency formatting
+- International standards
+
+### ✅ Installation & Environment (241-250)
+
+- System requirements
+- Installation instructions
+- Troubleshooting setup
+- Version updates
+- Platform-specific issues
+- Node.js compatibility
+- NPM configuration
+- Environment setup
+- Updating dependencies
+- CLI tool management
+
+## Key Features
+
+✅ **Comprehensive Answers** - Each question includes:
+
+- Clear, concise explanations
+- Code examples where applicable
+- Best practices and tips
+- Links to relevant documentation
+- Practical use cases
+
+✅ **Well-Organized** - Navigation:
+
+- Quick navigation table of contents
+- Anchor links to each section
+- Searchable content
+- Logical category grouping
+
+✅ **Practical Examples** - Includes:
+
+- JSON code snippets
+- Bash commands
+- JavaScript examples
+- Configuration examples
+- Real-world scenarios
+
+✅ **SEO Optimized** - Features:
+
+- Descriptive headings
+- Semantic HTML structure
+- Keyword-rich content
+- Internal linking
+- Meta information
+
+## Usage
+
+### Accessing the FAQ
+
+```bash
+# In the Next.js app, the FAQ will be available at:
+https://jsonresume.org/faq
+
+# Or in development:
+http://localhost:3000/faq
+```
+
+### Navigation
+
+The FAQ includes:
+
+- Quick navigation at the top
+- Jump links to each section
+- Anchor links for individual questions
+- Clear section headers
+- Breadcrumb navigation
+
+### Searching
+
+Users can:
+
+- Use browser's find feature (Cmd+F / Ctrl+F)
+- Navigate via table of contents
+- Jump to specific categories
+- Follow internal links
+
+## Maintenance
+
+### Updating the FAQ
+
+```bash
+# Location
+apps/docs/app/faq/page.mdx
+
+# Edit directly or via:
+# 1. GitHub web interface
+# 2. Local text editor
+# 3. VS Code with MDX support
+```
+
+### Adding New Questions
+
+```markdown
+### [Question Number]. Question text?
+
+**Answer with clear explanation:**
+
+\`\`\`json
+{
+"example": "code if needed"
+}
+\`\`\`
+
+**Key points:**
+
+- Point 1
+- Point 2
+- Point 3
+
+**Pro tips:**
+
+- Helpful advice
+- Best practices
+```
+
+### Best Practices
+
+1. **Keep answers concise** - 200-500 words ideal
+2. **Include code examples** - Show, don't just tell
+3. **Link to documentation** - Reference detailed docs
+4. **Update regularly** - Keep info current
+5. **Test code snippets** - Ensure examples work
+
+## Statistics
+
+- **Total Questions:** 145 (Questions 106-250)
+- **Total Lines:** 7,602
+- **Code Examples:** 200+
+- **Categories:** 14
+- **Word Count:** ~30,000 words
+- **Reading Time:** ~2 hours
+
+## Impact
+
+This comprehensive FAQ should:
+
+- ✅ Answer 90%+ of user questions
+- ✅ Reduce support burden
+- ✅ Improve SEO (rich content)
+- ✅ Help users self-serve
+- ✅ Become the authoritative resource
+- ✅ Drive organic traffic
+- ✅ Improve user experience
+
+## Future Improvements
+
+Consider adding:
+
+- [ ] Video tutorials
+- [ ] Interactive code examples
+- [ ] Live editor demos
+- [ ] User-submitted Q&A
+- [ ] FAQ analytics
+- [ ] Search functionality
+- [ ] Related questions
+- [ ] Rating system (helpful/not helpful)
+
+---
+
+**Created:** October 2025
+**Last Updated:** October 2025
+**Maintainer:** jsonresume.org team