docs: add AGENTS.md and .aiignore

[jankapunkt]

Summary

This adds a minimal set of files, relevant for agents that aim to work on this repo. The AGENTS.md is intended to be compact and model agnostic. While many agents and harnesses respect .aiignore there is also an explicit hin to the file in AGENTS.md for those who ignore it.

Linked issue(s)

none

Involved parts of the project

dev

Added tests?

none

OAuth2 standard

none

Reproduction

run your agents :-)

[dhensby]

Thanks @jankapunkt, this is a really useful addition. I've checked it against the repo and it's accurate:

• the commands work, including npm test -- --grep … keeping the Biome pretest
• the coverage threshold and release-CI details are right
• the architecture notes match the handlers
• neither file ends up in the npm tarball

I especially like the security-sensitive sequencing bullet. That's exactly the kind of invariant an agent would happily "tidy up".

A few small suggestions inline. The main one is about keeping process rules in one place. #335 rewrites CONTRIBUTING.md:

• Conventional Commits, enforced by commitlint because releases will be generated from the commit history
• no issue references in commit messages
• master instead of development
• an npm 11 lockfile note

If AGENTS.md points at CONTRIBUTING for the commit convention instead of restating it, it stays correct whichever PR lands first. The two "CONTRIBUTING is outdated" overrides (L151 and the last sentence of L161) are right today but become stale once #335 merges. If #335 lands first we can just drop them here; if this lands first, I'll remove them in #335.

[dhensby]

Nit, take or leave: docs/guide/contributing.md is actually a committed symlink, and docs:setup just re-creates it. Same for AGENTS.md L149-150. "Generated" might send an agent looking for a build step.

[jankapunkt]

Actually, I didn't know that symlinks can be commited. In that case I would keep line 41 and rename line 40 to something that will not burn tokens by looking up any build steps when reading this file. However, I think the missing key element is, that /docs/guide/contributing.md should also go in .gitignore

[dhensby]

Yep, git can track symlinks (it stores the target path). Untracking it makes sense since docs:setup re-creates it anyway, but it'd need a bit more than the .gitignore entry: git rm --cached docs/guide/contributing.md to actually untrack it, and docs:dev running docs:setup first, otherwise a fresh clone gets a broken Contributing link in the sidebar (docs:build already does this). I'd do that as a separate small PR. For this one, just rewording line 40 is fine, e.g. # Symlink to /CONTRIBUTING.md (re-created by docs:setup); read the root file instead.

[dhensby]

Thanks for taking those on @jankapunkt, LGTM. If this goes in before #335, I'll drop the two CONTRIBUTING overrides (L153 and the end of L163) in #335 as mentioned.

[jankapunkt]

@dhensby to ease up agentic work in subsequent PRs I would merge this as is before #335 which I would target as the next PR before any other PRs so we can establish a development baseline and then continue with the other work.

[dhensby]

Sounds good to me