docs: add agent guidance and threat model

AGENTS.md

@@ -0,0 +1,70 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents working with this repository.
+
+## Project map
+
+- validator.js is a single-package npm project for string validation and sanitization.
+- `src/index.js` defines the public exports, and `src/lib` contains validators, sanitizers, normalizers, converters, static format data, and shared utilities.
+- `test/validators.test.js` contains most API tests; additional test files cover browser builds and individual utilities.
+- `README.md` is the primary public API reference. Update it when documented API behavior or options change.
+- `build-browser.js` creates the browser bundle. Babel creates the Node and ES module distributions.
+- `index.js`, `lib/`, `es/`, `validator.js`, and `validator.min.js` are generated. Do not edit or commit them manually.
+- The published package contains only the generated distributions, `README.md`, `LICENSE`, and package metadata listed in the `files` field of `package.json`.
+- validator.js has no runtime dependencies. The packages in `devDependencies` are used only to build, lint, and test the project.
+
+## Branching and pull requests
+
+- Normal changes target `master`.
+- Keep changes focused on the reported behavior. Avoid unrelated API, formatting, generated-file, or data-table changes.
+- Bug fixes should include a focused regression test that fails before the fix and passes afterward.
+- Follow the style of recent commit and pull-request titles; the repository does not define a separate title convention in `CONTRIBUTING.md`.
+
+## Install and build
+
+- Use npm for the official build and test path.
+- Install development dependencies with `npm install --legacy-peer-deps`, as documented in `CONTRIBUTING.md` and used by CI.
+- Prefer Node.js 24 for local work. CI also tests Node.js 8, 10, 12, 14, 16, 18, 20, and 22, so avoid syntax or runtime APIs unsupported by the intended compatibility range.
+- Run `npm run build` to generate the Node, ES module, and browser distributions.
+- Do not infer a source change from generated output alone; inspect the corresponding file under `src/`.
+
+## Test
+
+- `npm test` is the broad local check. Its `pretest` lifecycle builds every distribution and runs ESLint before the Mocha suite.
+- `npm run lint` checks `src/` and `test/`.
+- `npm run build` builds all published forms without running the tests.
+- For a focused Mocha run, use `npm test -- --grep '<test name>'`; retain the broad `npm test` run before considering a code change complete.
+- Tests use Mocha, Babel, and nyc. Coverage output under `coverage/` and `.nyc_output/` is generated and should not be committed.
+- When changing a shared helper, identify and test its public callers. A helper-level test alone does not establish public API behavior.
+- When changing behavior represented in multiple distributions, verify the source implementation and the relevant generated form rather than editing generated files.
+- If a command fails during setup, distinguish dependency, Node-version, filesystem, and tooling failures from product-code failures before changing source.
+
+## Change discipline
+
+- Preserve documented behavior and compatibility outside the stated scope of a change.
+- Prefer the smallest root-cause fix over special-casing a reported input.
+- Keep static locale and format data changes separate from algorithm changes when practical.
+- Do not update generated distributions manually; building and publishing generate them from `src/`.
+- Do not commit, push, publish a package or advisory, open an issue or pull request, or disclose private security material unless explicitly authorized.
+
+## Documentation and threat model
+
+- Update `README.md` when a public API, option, return contract, or documented limitation changes.
+- Read `SECURITY.md` for the supported-version and vulnerability-reporting policy.
+- Read `THREAT_MODEL.md` before triaging a suspected vulnerability.
+- Do not place private advisories, unpublished findings, reporter information, or private bug-hunt results in public documentation.
+
+## Security analysis
+
+- Before describing a finding as novel, check open and closed issues, pull requests, published advisories, available approved private advisory material, tests, documentation, changelog entries, and relevant source history.
+- Prefer rejecting speculative candidates over presenting unsupported security conclusions.
+
+## Security reproduction standards
+
+- Start from a documented or reasonably supported public API invocation. An internal-helper test alone does not demonstrate public behavior unless that helper is itself public.
+- State the exact arguments, options, environment, expected documented behavior, observed behavior, independent security effect, and relevant preconditions.
+- Add a focused regression test that expresses the expected correct behavior rather than an incidental implementation detail.
+- Run the test against the unchanged implementation and confirm that it fails for the stated reason. If the behavior does not reproduce, stop and report the evidence instead of modifying source.
+- After a fix, confirm that the focused test passes and run `npm test` to check the generated builds, lint, and existing test suite.
+- Keep reproductions safe, local, bounded, self-contained, and readable. Do not contact external targets or run unbounded denial-of-service payloads.
+- Report the root cause, files changed, before-and-after results, compatibility effects, assumptions, and remaining limitations.