docs: update README and AGENTS to reflect MV2 architecture, context menu quick actions, options, and release workflow

README.md

@@ -1,6 +1,6 @@
 # Archive.org Link Grabber (Firefox WebExtension)
 
-Add-on for Firefox that enhances archive.org download pages (https://archive.org/download/*) so you can filter file links (by type, name, size, or date), copy them to the clipboard (one URL per line), or send them directly to an aria2 RPC server.
+Add-on for Firefox that enhances archive.org download pages (https://archive.org/download/*) so you can filter file links (by type, name, size, or date), copy them to the clipboard (one URL per line), or send them directly to an aria2 RPC server. It also adds context‑menu quick actions on archive.org pages.
 
 > Status: README/spec first. Implementation details below describe the intended behavior and structure.
 
@@ -14,6 +14,7 @@ Add-on for Firefox that enhances archive.org download pages (https://archive.org
 - Send to aria2: forward links to a configured aria2 JSON-RPC endpoint using a secret token.
 - Per-site parsing: targets archive.org collection download listings under `/download/*`.
 - Persistent settings: stores filter presets and aria2 config in extension storage.
+- Context menu: "Collect links…" with dynamic quick actions on archive.org pages. It offers "Download/Copy All" and type‑specific actions for the most common file types on the page.
 
 ## Demo Workflow
 
@@ -27,6 +28,9 @@ Add-on for Firefox that enhances archive.org download pages (https://archive.org
 5. Choose an action:
    - Copy: copies selected URLs to the clipboard, one per line.
    - Send to aria2: pushes to your configured aria2 RPC server using `aria2.addUri`.
+   - Or use the page’s context menu: right‑click → "Collect links…" for quick "All" or top‑type actions.
+
+Tip: The browser action badge shows counts when collecting/sending via context menu quick actions.
 
 ## Regex and Matching
 
@@ -74,7 +78,7 @@ The extension will require:
 - `https://archive.org/*` host permission to read and parse download pages.
 - `storage` to persist settings and presets.
 - `clipboardWrite` to copy links.
-- Host permission for your aria2 endpoint (e.g., `http://localhost:6800/*` or your remote URL). Optional permissions may be requested at runtime.
+- Host permission for your aria2 endpoint (e.g., `http://localhost:6800/*` or your remote URL). The manifest currently includes wildcard entries to support non‑local RPC during development; when repackaging, consider scoping to intended hosts.
 
 ## Parsing Strategy
 
@@ -82,7 +86,17 @@ The extension will require:
 - It scrapes the file listing table/DOM and builds a dataset with name, URL, size, and date.
 - Type is derived from filename extension (and may use content-type hints if available on the page).
 - The popup UI queries this dataset, applies filters, and displays the results.
-- A background script handles aria2 RPC calls to avoid CORS issues and keep secrets out of content scope.
+- The background script handles aria2 RPC calls to avoid CORS issues and keep secrets out of content scope.
+- If the content script isn’t present yet, the background injects it on demand and retries collection.
+
+## Options
+
+Open the Options page (from the popup link or `about:addons`):
+
+- Default Action: choose whether quick actions Download via aria2 or Copy to clipboard.
+- Include metadata in “All”: include archive.org’s metadata files in the “All” quick action.
+- aria2 endpoint and secret: persisted to `browser.storage.local`.
+- Test Connection: calls `aria2.getVersion` and surfaces guidance for Firefox HTTPS‑Only Mode when using non‑local HTTP endpoints.
 
 ## Installation (Temporary in Firefox)
 
@@ -119,10 +133,16 @@ For development, make changes and click “Reload” in `about:debugging` to pic
 
 ## Development Notes
 
-- Tech stack: Standard WebExtension (manifest v3 when supported in Firefox; otherwise v2), with content script + background/service worker + popup UI.
+- Tech stack: Standard WebExtension. Currently Manifest V2 in Firefox, with content script + background script + popup UI.
 - Storage: `browser.storage.local` for settings and aria2 configs; no analytics.
 - Code style: keep dependencies minimal; prefer modern, framework-light UI for the popup.
 
+### Architecture specifics
+
+- Background is a non‑module MV2 script. `src/lib/aria2-bg.js` exposes `addUri`, `addUrisBatch`, and `getVersion` on `globalThis` for background use.
+- Context menu parent: "Collect links…" appears on archive.org `/download/*` pages; submenu is rebuilt dynamically for top file types per page.
+- BrowserAction badges show counts and state after collecting, copying, or sending.
+
 ## Contributing
 
 Issues and PRs are welcome. If proposing new filters or aria2 options, please include example pages and expected behaviors.
@@ -146,4 +166,4 @@ This project is not affiliated with archive.org or aria2. Use responsibly and re
   - Artifacts land in `releases/<version>/`
 - Self-hosted updates: `releases/updates.json` is tracked; update with the new version and `update_link` like `https://add-ons.jordanwages.com/archive-org-link-grabber/releases/<version>/archive-org-link-grabber-<version>.xpi`.
 
-Notes: Keep AMO secrets local. CI is optional. You can tag releases with `git tag vX.Y.Z` and push tags if desired.
+Notes: Keep AMO secrets local (see `.env.example`). CI is optional. You can tag releases with `git tag vX.Y.Z` and push tags if desired.