docs: record why the listing keeps "powered by OpenAI" and its own icon

OpenAI's brand guidelines forbid its logo on unofficial software and list the phrases allowed, of which the name uses "powered by OpenAI".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitignore

@@ -2,3 +2,5 @@
 node_modules/
 web-ext-artifacts/
 npm-debug.log*
+# Listing images are generated; see docs/amo/README.md.
+docs/amo/screenshots/

docs/amo/README.md

@@ -0,0 +1,116 @@
+# Add-ons listing
+
+Paste-ready text and images for the
+[addons.mozilla.org listing](https://addons.mozilla.org/en-US/firefox/addon/search-with-chatgpt/).
+Edit them in the AMO Developer Hub under the add-on's listing details.
+
+Listing copy follows the copy rule in the
+[options design](../superpowers/specs/2026-07-29-extension-options-design.md):
+ChatGPT opens with the text *filled in*. Never say the text is sent, searched,
+or asked. Keep "private", "incognito", and "secure" away from temporary chat,
+and call temporary chat and web search hints.
+
+## Branding
+
+The name's "powered by OpenAI" and the extension's own icon follow OpenAI's
+brand guidelines on purpose:
+- OpenAI's logo would make unofficial software look official, so it isn't
+  used.
+- "Powered by OpenAI" is one of the phrases the guidelines allow.
+
+Keep both, along with the description's "unofficial" line.
+
+## Summary
+
+Plain text, 250 characters at most. The summary isn't Markdown, and AMO escapes
+`<` and `>` in it, so `<Alt>` would show as `&lt;Alt&gt;`. The summary is the one
+place that writes the shortcut without angle brackets:
+
+```text
+Ask ChatGPT from anywhere in Firefox. Type gpt in the address bar, right-click selected text, press Alt+Shift+G, or click the toolbar button. ChatGPT opens with your text filled in. Tiny, fast, no API key.
+```
+
+## Description
+
+Since March 2025, AMO formats descriptions as
+[Markdown](https://blog.mozilla.org/addons/2025/03/03/markdown/) and shows any
+HTML as plain text. Plain `<Ctrl>` therefore shows as typed. Check the preview
+after saving.
+
+```markdown
+Ask ChatGPT from anywhere in Firefox.
+
+**Four ways to use it**
+
+- **Address bar:** press <Ctrl>+L, type `gpt` and your question, like `gpt why does my cat knock things over?`, and press <Enter>.
+- **Right-click:** select text on any page and choose Ask ChatGPT.
+- **Keyboard:** select text and press <Alt>+<Shift>+G. With nothing selected, it opens a blank chat.
+- **Toolbar:** click the Ask ChatGPT button.
+
+ChatGPT opens with your text filled in. You may need to sign in to ChatGPT.
+
+**Small on purpose**
+
+The whole extension is about 56 KB, with no libraries, no server, no API key and no intermediary, and nothing is reported to us. Firefox opens chatgpt.com directly, and it never makes ChatGPT your default search engine unless you choose to.
+
+**Make it yours**
+
+- A simple right-click menu, or an advanced one with Explain, Summarize, Debug code and Translate.
+- Your own prompt template, like `Explain simply: {query}`.
+- Open ChatGPT in a new tab, a background tab or a new window.
+- Ask for a temporary chat or a web search. These are hints, and ChatGPT decides whether to honour them.
+- Add your own search keyword or change the shortcut in Firefox's settings.
+
+Search with ChatGPT is an unofficial extension by Zavage Software and isn't affiliated with OpenAI.
+
+[Source code](https://git-repos.zavage.net/zavage-software/search-with-chatgpt-powered-by-openai-extension) · [Project website](https://zavage-software.com/portfolio/search-with-ChatGPT) · [Feedback or report a bug](https://zavage-software.com/contact-us)
+```
+
+Update "about 56 KB" when the package size changes noticeably. `npm run build`
+prints the ZIP's path.
+
+## Screenshots
+
+Upload in this order, with these captions. Each image is 1280×800, the size AMO
+recommends, and carries no added text, as Mozilla's listing guide advises.
+
+The images are not committed. Generate them as described under
+[Regenerating the images](#regenerating-the-images); they land in
+`docs/amo/screenshots/`, which git ignores, so the links below work once you
+have.
+
+| Image | Caption |
+|---|---|
+| [1-address-bar.png](screenshots/1-address-bar.png) | Type gpt and your question in the address bar. ChatGPT opens with it filled in. |
+| [2-right-click.png](screenshots/2-right-click.png) | Select text on any page, right-click, and choose Ask ChatGPT. |
+| [3-keyboard.png](screenshots/3-keyboard.png) | Or select text and press <Alt>+<Shift>+G. |
+| [4-toolbar.png](screenshots/4-toolbar.png) | Or click the Ask ChatGPT button in the toolbar. |
+| [5-advanced-menu.png](screenshots/5-advanced-menu.png) | Switch to the Advanced menu for Explain, Summarize, Debug code and Translate. |
+
+A real screenshot of the options page in `about:addons` makes a good sixth
+image: one genuine screenshot next to the drawings helps people trust them.
+Suggested caption: "Every setting on one simple page."
+
+## Regenerating the images
+
+The images are the options page's drawings, enlarged by
+[`screenshots.html`](screenshots.html), which reuses `options/options.css`. They
+are generated rather than committed, like the build ZIP. When a drawing in
+`options/options.html` changes, copy the change into `screenshots.html`. Then,
+to produce the images, run these from the repository root:
+
+```sh
+python3 -m http.server 8766 --bind 127.0.0.1 &
+profile=$(mktemp -d)
+echo 'user_pref("layout.css.prefers-color-scheme.content-override", 1);' > "$profile/user.js"
+for shot in 1-address-bar 2-right-click 3-keyboard 4-toolbar 5-advanced-menu; do
+  firefox --headless -no-remote -profile "$profile" --window-size=1280,800 \
+    --screenshot "$PWD/docs/amo/screenshots/$shot.png" \
+    "http://127.0.0.1:8766/docs/amo/screenshots.html#$shot"
+done
+kill %1
+```
+
+The output path must be absolute. The throwaway profile forces the light theme,
+and a fresh one avoids Firefox serving an old copy of the page from its cache.
+Opening `screenshots.html` without a `#fragment` shows every image in order.

docs/amo/screenshots.html

@@ -0,0 +1,130 @@
+<!doctype html>
+<!-- Renders the options page drawings as 1280x800 images for the
+     addons.mozilla.org listing. Open with a #fragment (#1-address-bar) to
+     show one image; without one, every image is shown in order.
+     README.md in this folder explains how to regenerate them. Keep the
+     markup in step with the drawings in options/options.html. -->
+<meta charset="utf-8" />
+<title>Add-ons listing images</title>
+<link rel="stylesheet" href="../../options/options.css" />
+<style>
+  body {
+    max-width: none;
+    margin: 0;
+    padding: 0;
+    background: #ffffff;
+  }
+
+  .shot {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 1280px;
+    height: 800px;
+  }
+
+  body:has(.shot:target) .shot:not(:target) {
+    display: none;
+  }
+
+  /* zoom re-lays the drawing out at the larger size, so text stays sharp. */
+  .stage {
+    width: 24rem;
+    zoom: 2.6;
+  }
+
+  .stage-wide {
+    width: 26rem;
+    zoom: 2.4;
+  }
+
+  .stage .drawing {
+    margin: 0;
+    max-width: none;
+  }
+
+  .stage .drawing-keycaps {
+    padding-top: 0.5rem;
+  }
+</style>
+
+<section class="shot" id="1-address-bar">
+  <div class="stage stage-wide">
+    <div class="drawing">
+      <div class="drawing-urlbar">
+        <span class="drawing-chip"><img src="../../icons/powered-by-openai-icon-128x128.png" alt="" />ChatGPT</span>
+        <span class="drawing-typed">why does my cat knock things over?</span>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section class="shot" id="2-right-click">
+  <div class="stage">
+    <div class="drawing">
+      <p class="drawing-page">Nobody knows <mark>why cats knock things over</mark>…</p>
+      <div class="drawing-menu">
+        <div>Copy</div>
+        <div>Select All</div>
+        <hr />
+        <div class="drawing-menu-active"><img src="../../icons/powered-by-openai-icon-128x128.png" alt="" />Ask ChatGPT</div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section class="shot" id="3-keyboard">
+  <div class="stage">
+    <div class="drawing">
+      <p class="drawing-page">Cats sleep for <mark>sixteen hours a day</mark>.</p>
+      <div class="drawing-keycaps">
+        <kbd class="drawing-key">Alt</kbd>+<kbd class="drawing-key">Shift</kbd>+<kbd class="drawing-key">G</kbd>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section class="shot" id="4-toolbar">
+  <div class="stage">
+    <div class="drawing">
+      <div class="drawing-toolbar">
+        <span class="drawing-address">example.com</span>
+        <span class="drawing-button">
+          <svg viewBox="0 0 16 16"><path d="M2 5.5h3a2 2 0 1 1 3.2 0h3.3v2.8a2 2 0 1 1 0 3.2v3H2z" /></svg>
+        </span>
+        <span class="drawing-button drawing-button-hover">
+          <img src="../../icons/powered-by-openai-icon-128x128.png" alt="" />
+          <svg class="drawing-pointer" viewBox="0 0 12 18"><path d="M1 1v14.5l3.6-3.4 2.6 5.6 2.2-1-2.6-5.5H11z" /></svg>
+        </span>
+        <span class="drawing-button">
+          <svg viewBox="0 0 16 16"><path d="M3 4.5h10M3 8h10M3 11.5h10" /></svg>
+        </span>
+        <span class="drawing-tooltip">Ask ChatGPT</span>
+      </div>
+      <p class="drawing-content"><mark>Why cats sit in every box</mark></p>
+    </div>
+  </div>
+</section>
+
+<section class="shot" id="5-advanced-menu">
+  <div class="stage">
+    <div class="drawing">
+      <div class="drawing-menus">
+        <div class="drawing-menu">
+          <div>Copy</div>
+          <div>Select All</div>
+          <hr />
+          <div class="drawing-menu-active"><img src="../../icons/powered-by-openai-icon-128x128.png" alt="" />Ask ChatGPT<span class="drawing-submenu-arrow">›</span></div>
+        </div>
+        <div class="drawing-menu drawing-submenu">
+          <div>Ask normally</div>
+          <hr />
+          <div class="drawing-menu-active">Explain</div>
+          <div>Summarize</div>
+          <div>Debug code</div>
+          <div>Translate…</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>

docs/superpowers/specs/2026-10-18-amo-listing-design.md

@@ -0,0 +1,59 @@
+# Add-ons listing for 1.3
+
+Status: implemented on `docs/24-amo-listing-add-screenshots-and-a` (#24). The
+paste-ready text and captions are in [`docs/amo/`](../../amo/README.md), along
+with the page that renders the images.
+
+## Problem
+
+The AMO listing had no screenshots, and its description covered only the `gpt`
+keyword. It never mentioned right-click, the keyboard shortcut, or the toolbar
+button. The listing is where newcomers decide to install and first learn how to
+use the extension.
+
+## Decisions
+
+- **Tone: clear, with one joke.** The copy gives plain steps for newcomers. A
+  general cat joke ("gpt why does my cat knock things over?") replaces the old
+  programmer joke ("sudo make me a sammich"), and the images share the cat
+  theme.
+- **Say it is small.** Customization without bloat is what sets this extension
+  apart, so the description has a "Small on purpose" section: about 56 KB, no
+  libraries, no server, no API key, no intermediary, and nothing reported to
+  us. These are the README's privacy claims; nothing new is claimed.
+- **Drawings as screenshots.** The images are the options page's drawings,
+  enlarged and rendered by headless Firefox:
+  - They are part of the extension's own UI.
+  - They stay sharp and on brand.
+  - They can be regenerated after UI changes.
+
+  Real screenshots would show OS-specific menus and go stale. A real
+  screenshot of the options page is suggested as a sixth image, taken by the
+  maintainer, because one genuine screenshot builds trust in the rest.
+- **AMO's guidance.** Images are 1280×800, the size AMO recommends and its
+  largest display size, and carry no added text. Explanations go in each image's
+  caption.
+- **The copy rule holds.** ChatGPT opens with the text filled in; it is never
+  sent, searched, or asked. Temporary chat and web search are described as
+  hints, and "private", "incognito", and "secure" appear nowhere near temporary
+  chat.
+- **Branding stays.** The name's "powered by OpenAI" and the extension's own
+  icon follow OpenAI's brand guidelines: no OpenAI logo on unofficial software,
+  and only the phrases the guidelines allow. The description's "unofficial"
+  line complements them.
+- **Correction from the draft.** The description does not say ChatGPT opens "in
+  a new tab": `gpt` searches open in the current tab, and the other ways follow
+  the Open ChatGPT in setting.
+
+## Files
+
+- `docs/amo/README.md`: summary, description (Markdown, which AMO has used
+  instead of HTML since March 2025), captions in
+  upload order, and how to regenerate the images.
+- `docs/amo/screenshots.html`: the drawing markup at 1280×800, one image per
+  `#fragment`, styled by `options/options.css`.
+- `docs/amo/screenshots/*.png`: the five rendered images. They are generated
+  and git-ignored rather than committed, so the repository carries no binaries
+  and needs no Git LFS. The command to produce them is in the README.
+
+`docs/` is excluded from the extension package, so none of this ships to users.