AGENTS.md

1# extension — "Caveman Mode" browser extension (MV3, no bundler)
2 
3The consumer top-of-funnel: a toggle that, on ChatGPT / Claude / Gemini, prepends the **caveman
4skill directive** to each message you send and re-fires the send, so the AI replies in a compact,
5high-density style intended to preserve technical substance. It only ever adds text to your *outgoing*
6message; it never reads replies, never touches network requests. Savings are `inferred`. (This is
7the directive-injector product; an earlier revision shipped a local WASM compress button — EXT
8removed it after Chrome Web Store review couldn't reproduce "compress prompt locally".)
9 
10## Layout
11- `manifest.json` — MV3. `storage` permission only. Content scripts load `src/directive.js` **then** `src/caveman.js` (order matters). Only the fonts are web-accessible — no WASM, no special CSP.
12- `src/directive.js` — the **pure** caveman directive text: `buildPrimer`/`buildReminder`/`isPrefixed`/`normLevel`. No chrome/DOM/network. Loaded first (exposes `self.CavemanDirective`) and required directly by the test suite.
13- `src/caveman.js` — content script: per-site composer adapter + capture-phase send interception. Prepends the directive (full primer on the first message, short reminder after) and re-fires send. Resilient selectors; safe `setText` (never `textContent=`, which desyncs ProseMirror/Quill); polls for the enabled send button before clicking.
14- `src/background.js` — service worker: just reflects the on/off state on the toolbar badge.
15- `popup.{html,js,css}` — the on/off toggle, intensity (lite/full/ultra), per-site switches, and a **Leave-a-review** CTA (links to this install's Chrome Web Store reviews via `chrome.runtime.id`).
16- `test/` — pure directive/service-worker tests plus real Chromium
17  content-script and popup/storage journeys against `harness.html`.
18 
19## Conventions & honesty
20- **Edits your outgoing message only.** Prepends a visible directive; never reads model replies, never touches network requests, never automates anything beyond submitting the message you sent.
21- **Local-only.** No network requests, no analytics. Stores only `enabled` / `level` / `sites` in `chrome.storage.sync`.
22- **Honest about injection.** The directive is plainly visible in the chat — the extension doesn't hide what it adds.
23- **inferred-only.** Token savings are an effect of the model's terser replies; never labeled `verified`.
24 
25## Conventions
26- Build/test: `npm test` for pure tests; `npm run test:browser` for Chromium send interception, popup storage,
27  per-site controls, and review-link behavior. There is no
28  build step — MV3 loads the source directly.
29- Package: `npm run package` runs both suites, then writes `dist/caveman-browser-<version>.zip`. Staged set uses explicit allowlist in `scripts/verify-extension-stage.mjs`, cross-checked against manifest/CSS/HTML references.
30- Composer + send selectors live in the `SITES` map in `src/caveman.js`; a site redesign means updating it (each entry keeps aria-label fallbacks so one rename doesn't break it).
31 
32See ../../CLAUDE.md (root)
33