# Repository Guidelines

## Project Structure & Module Organization

This is a manifest-only Firefox WebExtension with npm-based development tooling.

- `manifest.json` defines the extension metadata and ChatGPT search provider.
- `icons/` contains size-specific PNG artwork named `powered-by-openai-icon-<size>x<size>.png`.
- `web-ext-config.mjs` controls linting, local execution, and ZIP packaging.
- `.gitea/workflows/firefox-extension.yml` validates pull requests and protected branches.
- `README.md`, `CHANGELOG.md`, and `LICENSE.txt` cover usage, releases, and licensing.

## Browser Scope

Firefox Desktop is the only current implementation and release target. Do not add Chrome, Brave, Chromium, or other browser packaging—or modify the sibling Chrome repository—unless a task explicitly requests it. Future ports remain desirable, so prefer standard WebExtension APIs where they preserve Firefox behavior and isolate unavoidable Firefox-specific code.

## Build, Test, and Development Commands

- `npm ci` installs the exact dependencies from `package-lock.json`; use Node.js 22 or newer.
- `npm run dev` launches a temporary Firefox profile with automatic extension reload.
- `npm run lint` runs strict Mozilla extension validation.
- `npm run build` creates the unsigned ZIP under `web-ext-artifacts/`.
- `npm test` runs lint and build checks together; run it before every pull request.

## Coding Style & Naming Conventions

Use two-space indentation in JSON, YAML, and JavaScript configuration. Preserve logical key grouping in `manifest.json`. Use lowercase, hyphenated filenames and include dimensions in icon names. Keep changes focused and avoid adding runtime dependencies without a concrete need.

## Testing Guidelines

Automated checks cover manifest validation and packaging, not browser behavior. After `npm test`, use `npm run dev` and confirm `gpt <query>` opens ChatGPT, the provider stays non-default, and Firefox search settings can configure it. Inspect ZIP contents whenever packaging rules or assets change.

Gitea Actions runs checks for every pull request and pushes to `develop` and `main`. Only successful `main` pushes upload an unsigned build artifact; CI does not publish to AMO.

## Commit & Pull Request Guidelines

Recent history uses short, lowercase prefixes such as `doc:` and `build:` (for example, `doc: fix git url`). Follow `<type>: <concise summary>` and keep each commit focused.

Pull requests should explain the user-visible effect, list manual Firefox checks, and link the relevant issue. Include screenshots for icons or browser-visible metadata. Explicitly call out permission, search URL, privacy, and packaging changes.

## Security & Privacy

Do not commit credentials or API keys. New permissions, telemetry, intermediary servers, or data collection require explicit justification and matching privacy documentation.