Add AGENTS.md for AI-agent contributors

[mcfnord]

🤖 AI: Short description of changes
Adds a top-level AGENTS.md, mirroring the pattern already in progress for the main jamulus repo (see jamulussoftware/jamulus#3793 / #3789). It points agents at the existing README workflow and Style-and-Tone guide, and adds one rule that isn't covered by either: no smart/curly quotes or apostrophes.

Rationale for that rule: a curly ’/“” pasted into a shell single-quoted string, JSON, a regex, or a code span is not the character the parser expects, and corrupts it silently — this is a real, machine-readable-content risk (unlike e.g. em-dash-vs-hyphen debates, which are purely a human-rendered typography/taste question with no parsing consequence in this repo's kramdown/GFM setup, so deliberately left out).

Context: Fixes an issue? Related issues
No related issue.

Status of this Pull Request
Ready for review. Every review thread opened so far has been addressed in the branch: @ann0see's two suggestion blocks are applied (9259b3cc) and his branch-clarification ask is at AGENTS.md:23; @pljones's Style-and-Tone comments are answered at c3359a2c and de3df071.

What is missing until this pull request can be merged?
A re-review. The PR carries CHANGES_REQUESTED from a review whose asks are now applied, and that state clears only on a new review.

Does this need translation?
NO — agent-facing repo doc, not user-facing site content (same category as README.md).

Checklist

• I've verified that this Pull Request follows the general code principles
• I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
• I'm sure that this Pull Request goes to the correct branch

---

🤖 This message was written by AI and reviewed by @mcfnord.

[pljones]

I'll moan about LLM-generated unnecessary extended characters whenever I see ’em 😁... For source code — and the content of this repo is source code — the ASCII character set is complete enough to represent the entire extended display content used. We support translations via Weblate for languages that require extended character support for accurate and natural representation of text content. For structural and English content, standard ASCII should be preferred with HTML character entities where essential.

I'll moan about LLM-generated unnecessary extended characters whenever I see ’em 😁...  For source
code — and the content of this repo _is_ source code — the ASCII character set is complete enough to
represent the entire extended display content used.  We support translations via Weblate for languages that _require_
extended character support for accurate and natural representation of text content.  For structural and English content,
standard ASCII should be preferred with HTML character entities where _essential_.

[ann0see]

Unfortunately somethimes this is not true. We probably need to clarify how it actually works...

[mcfnord]

Any way to detect when to use one or the other?

[ann0see]

Hard to say as it's a case by case basis. Everything on release gets published immediately and merged to next-release. Everything on next release will only get released once we open a PR, tag a release and squash it to release. Maybe let your LLM analyze the issues/PRs to find the correct pattern.

[pljones]

Much better.

[ann0see]

Suggested change

	These guidelines apply to every contribution, including work drafted with AI assistance. The `AGENTS.md` file in the website repository points automated contributors here rather than repeating them, so this page stays the single source of truth.
	These guidelines apply to every contribution, including work drafted with AI assistance.
	Note: The `AGENTS.md` file in the website repository points automated contributors here, so this page stays the single source of truth.

[ann0see]

Please apply this suggestion - the two-sentence version with the "Note:" lead-in reads better and keeps the AGENTS.md reference separate from the applicability statement.

🤖 Used AI: opencode, deepseek-v4-flash-free

[ann0see]

Do we really need this destinction?

[pljones]

I don't think "Keep the two apart." is necessarily correct. I think telling people and AI tools here who the audiences are is useful - by why under "Punctuation" - it's a non sequeteur. That appropriate punctuation and layout can enable and improve reading by both audiences is probably also worth mentioning.

So maybe

Suggested change

	Content here is written for people, but parts of it are read by tools as well. Keep the two apart.
	Use of text layout, for example lists and punctuation, should aid the reader, whether a person or a tool.

[mcfnord]

I'm not sure our audience wants to wrap its head around machines as readers. I think we agree that the gist of this concern is that SOMETIMES we're writing for a machine, and sometimes it's a human. When I write some code that will be pasted, that's for a machine, and it has real concerns about ASCII compliance. When we're writing for an HTML publication, we need to "code switch" and make sure the paste blocks are paste-ready. And the prose around them is for humans, and I will continue advocating for their richness as compared to machine-ready content.

Notice I didn't mention AI. I'm not sure this is about AI, here. AI can handle itself on the humanist of for-humans HTML.

Content here is written for people, and sometimes those people feed parts of it into machines. I think that's the central thrust intended here. Put that way, we should hit upon the ease of doing that with aides like click-to-copy, rather than select-and-copy, along with code width concerns (which need to work for both audiences).

I also believe this depth and nuance is better said to an agent, so maybe this guidance belongs in the repo AGENTS.md. I think perhaps we can let people submit PRs that are as sloppy as they want, and then just ask an agent to clean it up by these standards. Why educate people in this dead art? (And I have 25 years of professional experience in this particular dead art!)

[pljones]

I think perhaps we can let people submit PRs that are as sloppy as they want, and then just ask an agent to clean it up by these standards.

Because humans will be reviewing, this needs to happen before submission. I'm happy to bounce non-compliant PRs immediately back to "needs work", though.

[mcfnord]

Because humans will be reviewing, this needs to happen before submission.

Put an LLM in the CI.

[ann0see]

Put an LLM in the CI.

Better use a specialized tool for AI reviews unless we go "local" on the CI.

[pljones]

The Github token allowance for open source projects is limited. It's better to keep responsibility on the submitter directly. However, that doesn't mean we shouldn't supply a required set of rules that need complying with -- which is what the AGENTS.md is meant to guide towards.

Github seems to have an agent that happily butts in already, anyway - I don't think we should be developing and maintaining anything additional ourselves. (With any luck, it'll also read the AGENTS.md.)

[mcfnord]

I think those are authentication tokens.

The cost of an LLM varies substantially based on the size of the LLM. This kind of task would suit an affordable model, or even an open-weight one. I presume there are limits on what CI is willing to do for free. But CI need not do anything here. If someone submits a PR, I can review it against AGENTS.md and push fixes in a minute or two. Our documentation pipeline has always seemed unusually tricky. AGENTS.md in this repo should change that.

[pljones]

I think those are authentication tokens.

Uh, no. They're what I pay $10 a month for to get some extra models over and above the free tier, plus extended usage. Free tier usage runs out very quickly.

[ann0see]

Thanks for this, mcfnord. I would like to get this merged soon. Happy for it to be updated based on any findings from the current discussions.

🤖 Used AI: opencode, deepseek-v4-flash-free

[ann0see]

I think we should add the AI disclaimer similar to what I have here:

🤖 Used AI: opencode, deepseek-v4-flash-free

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: QUIET

Plan: Advanced

Run ID: 01556f1e-a9e4-4219-af27-c862467e0147

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pljones]

The audio signal as part of a mix.

OK...

"Group channels together"

The grouping is a UI feature for the UI widgets, nothing to do with the audio signal, except that - once grouped - the UI widget for one affects all the grouped channel's audio signals.

[pljones]

We also need terminology for the rest of the mixer UI widgets that people can relate to consistently.

And see how "Group channels together" and "Group faders together" are both stated? Does "Fader" here mean "Channel"? Or vice versa? Or something else? How's an AI Agent going to work this out?

[mcfnord]

🤖 AI: "Group channels together" is gone from the Channel entry; grouping now sits under Fader alone, with a clause naming what moves. The split follows the code: iGroupID is a member of the widget class CChannelFader, a grouped move calls SetFaderLevel on each peer, and each peer derives its own gain from its own level. The mix changes because every fader changed, not because the group reached the audio path. The same ambiguity sits in the app, for the terminology list rather than this PR: the Grp checkbox's What's This text reads "a group of audio channels can be defined ... All channel faders in a group are moved".

[pljones]

So I thought I'd take a fresh read through the S&T guide to see how helpful it was going to be to an AI Agent sent there. Hm. Left a few comments.