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.

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version).
 
+## [1.1.0] (2026-07-30)
+
+Adds an options panel and two new ways to reach ChatGPT.
+
+ * Options panel in `about:addons` with five settings: model (experimental),
+   temporary chat, web-search hint, where results open, and a prompt template.
+ * Right-click selected text and choose "Ask ChatGPT" to open ChatGPT with that
+   text filled in.
+ * Keyboard shortcut `Alt+Shift+G` does the same for the current selection, and
+   opens an empty chat when nothing is selected. Rebindable via Manage Extension
+   Shortcuts.
+ * Documented that ChatGPT no longer submits prompts passed in a URL, so a
+   second Enter is needed. This is an upstream change to chatgpt.com.
+ * `gpt <query>` address-bar search is unchanged.
+ * The options panel, right-click item, and keyboard shortcut require Firefox
+   112 or newer. Older versions keep the `gpt <query>` search unchanged.
+ * Permissions added: storage, menus, activeTab. None of them adds a line to
+   Firefox's install prompt.
+
 ## [1.0.0]) (2024-06-09)
 
 First release of software.

README.md

@@ -12,6 +12,46 @@ This is an unofficial extension provided by Zavage Software Inc.
 
 See `LICENSE.txt` for licensing terms.
 
+## Options
+
+Open `about:addons`, select this extension, and choose the **Options** tab
+(**Preferences** on macOS and Linux). Available settings:
+
+- **Model** *(experimental)* — a model slug such as `auto`. ChatGPT may ignore
+  it and use your account default; leave blank to always use the account
+  default.
+- **Request a temporary chat** — asks ChatGPT not to save the conversation.
+  ChatGPT may not honour this; check its own indicator before relying on it.
+- **Ask ChatGPT to use web search** — a hint to ChatGPT's interface, not a
+  guarantee.
+- **Open in** — a new tab, a new background tab, or a new window.
+- **Prompt template** — wraps your text, for example `Explain simply: {query}`.
+
+These settings apply to the new entry points: selecting text and choosing
+**Ask ChatGPT** from the right-click menu, or pressing
+<kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. Rebind the shortcut under
+**Manage Extension Shortcuts** in the Add-ons gear menu.
+
+The `gpt <query>` address-bar search is unchanged and does not read these
+settings.
+
+The options panel, the right-click item, and the keyboard shortcut require
+Firefox 112 or newer. On older versions the extension still installs and the
+`gpt <query>` address-bar search still works; only these newer features are
+inactive.
+
+## Why you press Enter twice
+
+ChatGPT no longer submits prompts that are passed to it in a URL — it fills them
+into the composer and waits. So `gpt <query>` opens ChatGPT with your query
+filled in, and you press Enter there to send it.
+
+This is a change OpenAI made to chatgpt.com, not a fault in this extension, and
+it is outside our control. It was a deliberate security measure: automatically
+running a prompt that arrived in a link let malicious links execute instructions
+in a signed-in ChatGPT session. The extra keypress is the checkpoint that
+prevents that. No API key, server, or intermediary is involved either way.
+
 ## Browser Support
 
 Firefox Desktop is the current development and release target. Chrome, Brave,
@@ -44,4 +84,14 @@ configured in Firefox search settings.
 
 ## Privacy Policy
 
-This extension collects zero user data.
+This extension has no server, no API key, and no intermediary. Nothing is
+reported to Zavage Software.
+
+- Your settings are stored in your own browser profile. If you use Firefox Sync
+  with **Add-ons** enabled, they sync end-to-end encrypted through your own
+  Mozilla account.
+- When you choose **Ask ChatGPT** or press the shortcut, the text you selected
+  is placed in the chatgpt.com URL the extension opens for you. It goes nowhere
+  else.
+- The extension reads a page's selected text only at the moment you invoke it,
+  and never reads page addresses or titles.