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 at the repo root. A script owns everything it needs — metadata header, styles, and logic — in that one file.

• 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).

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

Warnings on third-party/imported scripts are acceptable signal, not blockers. Keep your own scripts warning-clean.

Dev Environment

The Nix flake provides nodejs + pnpm; its shellHook runs pnpm install and puts node_modules/.bin on PATH, so oxlint is ready automatically.

nix develop       # or: direnv allow  (uses .envrc → `use flake`)