doc: document options panel, entry points, and the ChatGPT prefill limitation

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -2,11 +2,19 @@
 
 ## Project Structure & Module Organization
 
-This is a manifest-only Firefox WebExtension with npm-based development tooling.
+This is a Firefox WebExtension (Manifest V2) with npm-based development tooling.
 
-- `manifest.json` defines the extension metadata and ChatGPT search provider.
+- `manifest.json` defines the extension metadata, the ChatGPT search provider,
+  the background script, the options panel, and the keyboard command.
+- `lib/` holds pure logic with no browser dependencies: `defaults.js`,
+  `build-url.js`, and `settings.js`. This is the unit-tested core.
+- `background/background.js` is an ES-module background script that registers
+  the context menu and the keyboard command.
+- `options/` is the options panel rendered inline in `about:addons`.
+- `test/` holds `node:test` unit tests. Excluded from the packaged ZIP.
 - `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.
+- `docs/superpowers/` holds specs and plans. Excluded from the packaged ZIP.
 - `.gitea/workflows/firefox-extension.yml` validates pull requests and protected branches.
 - `README.md`, `CHANGELOG.md`, and `LICENSE.txt` cover usage, releases, and licensing.
 
@@ -19,8 +27,9 @@ Firefox Desktop is the only current implementation and release target. Do not ad
 - `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 test:unit` runs the `node:test` unit tests over `test/`.
 - `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.
+- `npm test` runs lint, unit tests, and build together; run it before every pull request.
 
 ## Coding Style & Naming Conventions
 
@@ -28,9 +37,30 @@ Use two-space indentation in JSON, YAML, and JavaScript configuration. Preserve
 
 ## 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.
+Unit tests cover the pure logic in `lib/` via `node:test`; automated checks
+otherwise cover manifest validation and packaging, not browser behaviour. Note
+`node --test` exits 0 when it discovers no test files, so confirm a non-zero
+test count rather than trusting the exit code alone.
 
-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.
+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.
+- The Options/Preferences tab renders all five settings plus Restore defaults,
+  in both light and dark themes and at a narrow window width, and values
+  persist across a restart.
+- The right-click **Ask ChatGPT** item appears only when text is selected.
+- `Alt+Shift+G` acts on the selection, including a selection inside an iframe,
+  and opens a blank chat when nothing is selected or on a restricted page such
+  as `about:config`. Press the key to test this — `commands.getAll()` reports a
+  shortcut as registered even when Firefox has silently overridden it.
+
+Inspect ZIP contents whenever packaging rules or assets change; `test/` and
+`docs/` must never appear, not even as empty directory entries.
+
+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
 
@@ -41,3 +71,11 @@ Pull requests should explain the user-visible effect, list manual Firefox checks
 ## Security & Privacy
 
 Do not commit credentials or API keys. New permissions, telemetry, intermediary servers, or data collection require explicit justification and matching privacy documentation.
+
+Permissions are deliberately limited to `storage`, `menus`, and `activeTab`,
+which add no line to Firefox's install prompt. Do not add `tabs`,
+`notifications`, `webNavigation`, or any host permission without re-reading
+`docs/superpowers/specs/2026-07-29-extension-options-design.md` — each was
+considered and rejected there, and Appendix B records a feature rejected on
+security grounds that must not be revived without clearing the bar documented
+with it.