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

AGENTS.md

@@ -1,49 +1,89 @@
-# Repository Guidelines
+# Contributor Guide & Philosophy
 
-## Project Structure & Module Organization
+This add-on helps you collect and filter links from archive.org `https://archive.org/download/*` pages, then copy them or send them to an aria2 RPC server. The project is Firefox-first, docs-first, and aims to stay lean and privacy‑respecting.
 
-- Root: `manifest.json`, `package.json` (when added), config files.
-- `src/`: extension code.
-  - `background/`: RPC, messaging, and long‑lived tasks.
-  - `content/`: archive.org DOM parsing on `/download/*` pages.
-  - `popup/` and `options/`: UI, settings, and actions.
-  - `lib/`: shared utils (filters, size/date parsing, aria2 client).
-- `assets/`: icons and static resources.
-- `tests/`: unit (`tests/unit`) and e2e (`tests/e2e`).
-- Note: initial repo is docs-first; scaffolding will create these paths.
+## Architecture Overview
 
-## Build, Test, and Development Commands
+- Manifest: Firefox Manifest V2 (for stability and background script support).
+- Background (MV2, non-module): `src/background/index.js` handles messaging, context menu, on-demand content script injection, and delegates aria2 calls to globals from `src/lib/aria2-bg.js`.
+- Content script: `src/content/collect.js` scrapes the download listing DOM and returns items `{ url, name, type, sizeText?, dateText? }`.
+- Popup UI: `src/popup/*` lets users filter by name/type (string or regex), size, and date, preview matches, copy links, or send to aria2.
+- Options page: `src/options/*` manages aria2 endpoint/secret, “Default Action” (download vs copy), and an “Include metadata in All” toggle; includes a connection test for aria2 with HTTPS‑Only hints.
+- Shared utils: `src/lib/filters.js` (matchers, size/date parsing) and `src/lib/aria2.js` (JSON‑RPC helpers). `src/lib/aria2-bg.js` exposes background‑safe helpers on `globalThis`.
 
-- Install: `npm install` (after `package.json` lands).
-- Dev (Firefox): `npx web-ext run --source-dir .` or `npm run dev`.
-- Build: `npx web-ext build -o -a dist` or `npm run build` → `dist/`.
-- Lint/Format: `npm run lint` and `npm run format`.
-- Tests: `npm test` (Jest). E2E via Playwright: `npm run test:e2e`.
+### Messaging and Flow
 
-## Coding Style & Naming Conventions
+- Popup → Content: try `collectLinks` first; if no receiver exists, Popup → Background → inject content → retry collect.
+- Popup → Background: `aria2.send` wraps `aria2.addUri` calls (batch) and keeps secrets out of page context.
+- Context menu: parent "Collect links…" with a dynamic submenu built per page ("Download/Copy All" and top file types).
 
-- Language: JavaScript (ES2020+) or TypeScript (preferred for new modules).
-- Indentation: 2 spaces; max line length 100; use semicolons.
-- Filenames: kebab-case (`filters-utils.ts`, `aria2-client.ts`). UI components: PascalCase.
-- Identifiers: camelCase; UPPER_SNAKE_CASE for constants; verbs for functions.
-- Tools: ESLint + Prettier. Run `npm run lint` before pushing.
+### Storage Keys
 
-## Testing Guidelines
+- `aria2`: `{ endpoint, secret }` in `browser.storage.local`.
+- `prefs`: `{ defaultAction: 'download'|'copy', allIncludeMeta: boolean }`.
+- `lastCollected`/`lastItems`: background stores the last collection stats and items to support quick actions and badges.
 
-- Framework: Jest for unit tests; Playwright for e2e (popup/content behaviors).
-- Location: unit under `tests/unit/**/*.spec.(js|ts)`; e2e under `tests/e2e/**`.
-- Coverage: target ≥ 80% lines for core filters and RPC client.
-- Focus: filename/type regex, size/date filters, clipboard, and `aria2.addUri` payloads.
+## Design Principles
 
-## Commit & Pull Request Guidelines
+- Firefox-first: target Firefox with MV2; revisit MV3 later if appropriate.
+- Minimal footprint: no heavy frameworks; keep UI simple and dependency‑light.
+- Privacy by default: no analytics; tokens stored in `storage.local`; users own their data.
+- Robust UX: inject content on demand; show actionable error messages (e.g., HTTPS‑Only hints).
+- Clear boundaries: background mediates network and privileged actions; content stays read‑only.
+- Docs-first: keep README and this guide authoritative; code mirrors described behaviors.
 
-- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`). Use imperative mood.
-- PRs: concise description, motivation, screenshots/GIFs for UI, test plan, and linked issues.
-- Scope: keep PRs small and focused; update docs when behavior changes.
+## Repository Layout (current)
 
-## Security & Configuration Tips
+- Root: `manifest.json`, `package.json`, `LICENSE`, `README.md`, `.env.example`, `releases/`, `scripts/`.
+- `src/`
+  - `background/index.js`
+  - `content/collect.js`
+  - `popup/` (`index.html`, `index.js`, `styles.css`)
+  - `options/` (`index.html`, `index.js`, `styles.css`)
+  - `lib/` (`filters.js`, `aria2.js`, `aria2-bg.js`)
 
-- Do not commit secrets. Store aria2 RPC token in `browser.storage.local`.
-- Prefer HTTPS for remote RPC; if self-signed, document trust steps locally only.
-- Provide examples as `config.example.json`; ignore local overrides in `.gitignore`.
+Note: There is no `tests/` directory yet. See “Testing” below for priorities.
+
+## Development
+
+- Install: `npm install`
+- Dev (Firefox): `npm run dev` (starts Firefox with `web-ext run`)
+- Build: `npm run build` → artifacts in `dist/`
+- Lint (AMO): `npm run lint:fx`
+- Local release: see “Release & Signing”
+
+## Coding Style
+
+- Language: JavaScript (ES2020+). TypeScript may be introduced later; keep modules TS‑friendly.
+- Conventions: 2 spaces; max line length ~100; semicolons; kebab-case filenames; camelCase identifiers; UPPER_SNAKE_CASE for constants; verbs for functions.
+- Dependencies: keep minimal; prefer DOM APIs and small modules in `src/lib`.
+- Structure: small functions, early returns for clarity; avoid incidental coupling between popup/background/content.
+
+## Testing
+
+Tests are not yet implemented. Priorities when adding tests:
+
+- Unit (Jest): `src/lib/filters.js` (matchers, size/date parsing) and `src/lib/aria2.js` (payloads, token handling).
+- Integration (web‑ext + Playwright): popup filtering behavior on a fixture page; content collector DOM parsing; context menu quick actions update and badge counts.
+- Coverage targets: ≥80% for filters and aria2 client.
+
+Suggested scripts (future): `npm test`, `npm run test:e2e` with Playwright.
+
+## Security & Permissions
+
+- Do not commit secrets; use `.env` only for local signing. The aria2 secret is stored in `browser.storage.local`.
+- Prefer HTTPS for remote aria2 RPC. For self‑signed certs, document local trust steps only.
+- Manifest host permissions include `archive.org` and wildcard entries to allow non‑local RPC endpoints. If repackaging, scope these down to intended hosts.
+- Firefox HTTPS‑Only Mode can upgrade `http://` to `https://` for non‑local hosts; the options page surfaces guidance.
+
+## Release & Signing
+
+- Add‑on ID and updates: `applications.gecko.id = "archive-org-link-grabber@jordanwages.com"` and `applications.gecko.update_url` points to the self‑hosted updates JSON.
+- Scripts: `release:prepare:*` (syncs `manifest.json`), `release:sign` (creates XPI under `releases/<version>/`).
+- Secrets: set `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` locally (see `.env.example`); never commit them.
+
+## Commit & PR Guidelines
+
+- Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`.
+- Keep PRs small and focused; include motivation, UX screenshots for UI changes, test plan, and linked issues.