userscripts/AGENTS.md

Userscripts

A flat collection of standalone browser userscripts (Tampermonkey / Violentmonkey / Greasemonkey).

Core Rule: One Self-Contained File Per Script

Each userscript is a single *.user.js file in scripts/. A script owns everything it needs - metadata header, styles, and logic - in that one file. Repo plumbing (flake, lint config, package files) stays at the root.

• No shared modules, no build step, no bundler. A file must install and run as-is by pasting it into a userscript manager.
• New script → new name.user.js file. Do not factor common code into helpers across files; duplication across scripts is acceptable and expected here.
• Every file starts with a complete ==UserScript== metadata block (@name, @namespace, @version, @description, @match, @run-at, and any @grant/@connect).
• Keep scripts ASCII-only (use -, ", ..., plain text labels). Some userscript managers decode files as latin-1, turning UTF-8 punctuation/emoji into mojibake (e.g. — → —).

Linting

oxlint lints all scripts. It's a pnpm devDependency (pinned in package.json / pnpm-lock.yaml), not a Nix package. Config: .oxlintrc.json (browser + greasemonkey env, GM globals declared, _scratch/ ignored).

pnpm lint         # lint every *.user.js

Keep scripts warning-clean.

Dev Environment

direnv (.envrc → use flake) auto-loads the Nix flake, which provides nodejs + pnpm and runs pnpm install via its shellHook, so oxlint is on PATH automatically.