Operating manual for AI agents working on this repository. Read this before making any change.

1. README.md — what the project is.
2. ARCHITECTURE.md — how v1 is built. Source of truth for system design. Update it when a change touches design.
3. ROADMAP.md — phase-by-phase plan. Tells you which phase the project is in and what's blocking the next one.
4. IMPLEMENTATION.md — step-by-step handbook for Phases 2-4: locked decisions, code patterns, file paths, acceptance criteria. If you're a cheaper model picking up this work, this is your bible.
5. CHANGELOG.md — what shipped, when. Add an entry under [Unreleased] for any non-trivial change.
6. CONTRIBUTING.md — dev setup, conventions, PR rules.

These were settled with the maintainer during initial planning. Treat them as constraints, not preferences:

• No backend the maintainer operates. The whole project assumes $0 ops. Do not add a Flask/Node/Cloudflare-Worker server that we run. Boost mode is BYO API key, period.
• Click-to-scan UX, never auto-scan. No automatic scanning as you scroll. Every detection is initiated by an explicit user click, context-menu pick, or keyboard shortcut.
• In-browser ML by default via transformers.js (ONNX Runtime Web). Runs in an MV3 offscreen document, never the service worker.
• Model distribution = Hugging Face primary + GitHub Releases fallback. Pin to a specific revision hash.
• No <all_urls> host permission. activeTab + scripting are sufficient because the user always clicks first.
• No telemetry by default. Anything anonymous-stats-shaped must be opt-in in Options and clearly disclosed in the privacy policy.
• TypeScript everywhere in src/. No new .js files (the v0.1 plain-JS code is intentionally fenced into archive/).
• v1 ships images and text together — not separately. (Phase ordering is sequential but they release together.)
• No data leaves the user's machine in local mode. Image bytes / text only travel out of the browser when Boost mode is explicitly enabled, and only to the user-chosen provider — never to any maintainer-run server.
• Default local image model: Organika/sdxl-detector at q8 quantization. Don't swap without running the Phase 2.5 benchmark and getting maintainer approval.
• Default local text model: Hello-SimpleAI/chatgpt-detector-roberta at q8.
• Boost failure → local fallback with visible toast. Don't silently fall back; the user must see what happened and why.
• Click-to-scan UX never auto-scans on scroll — repeating because this is the most common decision agents try to relitigate.

• Exact local image model after Phase 2.5 benchmark — current default is Organika/sdxl-detector, may be replaced.
• Whether to add additional Boost providers beyond Gemini / OpenAI / HF.
• Whether to bring back a Sphinx docs site post-v1.
• Monetization (currently free, BYO-key for power users; could become freemium).
• Whether v1.1 should add in-page text highlights (currently toast-only).

If a request seems to conflict with a locked-in decision, stop and ask the maintainer rather than quietly violating the decision.

README.md
ARCHITECTURE.md       # design source of truth
ROADMAP.md            # phase plan
IMPLEMENTATION.md     # Phase 2-4 handbook (read before doing ML work)
CHANGELOG.md          # release notes
CONTRIBUTING.md       # dev guide
AGENTS.md             # this file
LICENSE
.gitignore
assets/icons/         # extension icons
site/                 # marketing + docs site (Netlify)
src/                  # v1 source (added in Phase 1)
  manifest.config.ts
  background/
  offscreen/          # transformers.js lives here ONLY
    ml-engine.ts      # ONNX session manager (added in Phase 2)
  content/
  popup/
  options/
  detectors/
    image/{local,gemini,openai,hf}.ts
    text/{local,gemini,openai,hf}.ts
    index.ts          # router
  shared/{types,storage,cache,rate-limit}.ts
tests/{unit,e2e}/
bench/                # local-model benchmark (Phase 2.5)
scripts/              # mirror-model.sh etc.
archive/              # v0.1 Python + docs + extension, frozen for reference

• Plan, then execute. Use the planning tool before non-trivial changes; ask the maintainer when assumptions are needed. Do not invent answers to product questions.
• Small, daily-ish commits. Maintainer prefers a push roughly once per "big chunk" of work — phase-level or larger sub-phase. Don't sit on a giant uncommitted diff for days.
• Honest commit messages. "Wire up offscreen doc + transformers.js (no model yet)" beats "Implement ML."
• Update docs in the same commit as the code. If a change makes ARCHITECTURE.md wrong, fix ARCHITECTURE.md in the same commit.
• Never push secrets. No API keys in code, fixtures, tests, or commits. .env* is gitignored; keep it that way.
• Do not delete files in archive/. They're frozen reference material.

• Solo project, currently for personal + friends use, intent to publish to Chrome Web Store.
• The maintainer has appointed the principal-engineer agent (the one that wrote this file) as the technical point of contact across sessions. Other agents may be spawned for specific sub-tasks but should align with the direction in ARCHITECTURE.md / ROADMAP.md and ask the principal-engineer agent (or maintainer) when in doubt.

• Default to plan mode for anything that's not a trivial fix.
• Ask 1–2 critical questions at a time, not a wall.
• Be honest about what's hard, what's flaky, and what's a bad idea — including ideas the maintainer suggested. The maintainer values pushback over agreement.