# Contributing to PocketResume

Thanks for your interest in contributing! PocketResume is an open-source Chrome extension and welcomes issues, bug fixes, features, docs improvements, and prompt tuning.

## Code of Conduct

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating, you agree to its terms.

## Reporting Issues

- **Bugs:** use the [Bug Report](../../issues/new?template=bug_report.md) template. Include Chrome version, extension version, reproduction steps, and console output.
- **Features:** use the [Feature Request](../../issues/new?template=feature_request.md) template. Describe the user problem first, then the proposed solution.
- **Security vulnerabilities:** see [SECURITY.md](SECURITY.md). **Do not** file a public issue.

## Development Setup

### Prerequisites

- Node.js 18+ and npm
- Chrome / Chromium / Edge / Brave
- (Optional) API keys for at least one AI provider: Google Gemini, OpenAI, Anthropic, or OpenRouter
- (Optional) Clerk + Convex accounts if you want to work on cloud sync

### Install

```sh
git clone https://github.com/Isaac-1555/pocket-resume.git
cd pocket-resume
npm ci
```

### Load unpacked

1. Open `chrome://extensions`
2. Enable **Developer mode**
3. Click **Load unpacked** and select the repo root
4. After edits, click **Reload** on the extension card

See [AGENTS.md](AGENTS.md) for the full architecture map, runtime entrypoints, and debug recipes.

## Project Structure

```
PocketResume/
├── manifest.json            # Manifest V3 entrypoint wiring
├── background.js            # Service worker: pipeline orchestration + AI calls
├── content.js               # Content script: page text extraction
├── popup.html / popup.js    # Popup UI + PDF generation
├── options.html / options.js# Settings: API keys, resumes, toggles
├── resume-renderers.js      # Jake / Deedy / Academic CV PDF layouts
├── src/cloud-sync.js        # Cloud sync source (bundled → cloud-sync.js)
├── cloud-sync.js            # [generated] esbuild bundle of src/cloud-sync.js
├── convex/                  # Convex backend (auth, resumes schema/functions)
├── libs/jspdf.umd.min.js    # Vendored jsPDF build
├── AGENTS.md                # AI agent + contributor guide
└── package.json             # Build scripts only (no runtime deps)
```

## Pull Requests

1. Fork the repo and create a branch: `git checkout -b fix/short-description`
2. Make focused commits. Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`).
3. Run through the [PR template](../../pulls) checklist.
4. Push and open a pull request against `main`.
5. Address review feedback with follow-up commits (do not force-push during review).

## Coding Style

- Vanilla ES2022 JS, no TypeScript, no bundler for app code.
- 4-space indentation (matches existing `background.js`).
- Match the style of the file you're editing. Read surrounding context first.
- **No new comments in source files** unless behavior is non-obvious. The codebase intentionally ships minimal comments.
- Use `chrome.storage.local` for persistence; do not introduce new global state.

## AI Provider Changes

If you change a prompt, model, or JSON schema, update both:
- The matching `callGemini*` / `callOpenAI*` / `callAnthropic*` / `callOpenRouter*` function in `background.js`
- The style config table in `AGENTS.md` if the schema or layout mapping changed

Test with a real API key before opening a PR. JSON-only outputs (no markdown fences) are a hard requirement — the popup parser will fail otherwise.

## Cloud Sync Changes

Cloud sync requires Clerk + Convex credentials. These are **not** checked into the repo.

1. Copy `.env.example` to `.env.local` and fill in your own values
2. Run `npm run build:clerk` to bundle `src/cloud-sync.js` → `cloud-sync.js` with your env vars injected
3. For Convex backend work: `npx convex dev` from the repo root

**Never** commit:
- Real `pk_live_*` or `sk_*` keys
- Convex deployment URLs from your production account
- `cloud-sync.js` (it's a build artifact — see `.gitignore`)
- `convex/_generated/` (regenerated by Convex CLI)

## Vendored jsPDF

`libs/jspdf.umd.min.js` is committed. To update:

```sh
npm install jspdf@latest
cp node_modules/jspdf/dist/jspdf.umd.min.js libs/jspdf.umd.min.js
```

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).