Skip to content

docs(acp): add a Subscription Scope section to the configuration reference - #5710

Open
EmminiX wants to merge 1 commit into
block:mainfrom
EmminiX:docs/acp-subscription-and-mention-filter
Open

docs(acp): add a Subscription Scope section to the configuration reference#5710
EmminiX wants to merge 1 commit into
block:mainfrom
EmminiX:docs/acp-subscription-and-mention-filter

Conversation

@EmminiX

@EmminiX EmminiX commented Aug 12, 2026

Copy link
Copy Markdown

Summary

Adds a "Subscription Scope" section to the buzz-acp configuration reference, covering five flags
that had no entry there: BUZZ_ACP_SUBSCRIBE, BUZZ_ACP_CHANNELS, BUZZ_ACP_KINDS,
BUZZ_ACP_NO_MENTION_FILTER and BUZZ_ACP_CONTEXT_MESSAGE_LIMIT. None of those env var names
appear anywhere in the README today, while every other group of flags has a table.

It sits after the Inbound Author Gate on purpose: that section decides whose events arrive,
this one decides which channels are watched and what opens a turn.

The Forum Channels section already uses --no-mention-filter and explains what it enables, so this
is not introducing the flag. What is missing there is its scope, which is the part that bites:
the harness subscribes to every channel the identity belongs to and the membership notification
subscription adds more over time, so in mentions mode the flag applies across all of them at
once. With several agents in one workspace and the author gate widened, one message can open a turn
on several agents.

The callout says that and points at the two things that bound it, --channels and the author gate.
I lost a day to this, which is why it seemed worth writing down.

Duplicate search

No open PR documents these flags. #4922 touches BUZZ_ACP_NO_MENTION_FILTER but is a code fix for
boolean parsing rather than documentation. Five open PRs touch this file; none edits the
configuration tables.

Testing

Documentation only, no code paths changed. Every flag name, default and behaviour statement was
checked against crates/buzz-acp/src/config.rs, specifically resolve_channel_filters
(require_mention = !no_mention_filter, applied per channel) and resolve_dynamic_channel_filter
(channels_override filters discovery rather than replacing it, and is ignored in config mode).

Rebased on current main.

Logging

No logging changes.

…rence

BUZZ_ACP_SUBSCRIBE, BUZZ_ACP_CHANNELS, BUZZ_ACP_KINDS,
BUZZ_ACP_NO_MENTION_FILTER and BUZZ_ACP_CONTEXT_MESSAGE_LIMIT are real
flags in config.rs, and none of these env var names appear anywhere in
this README. The Configuration section documents every other group of
flags in a table; these five had no entry.

The Forum Channels section does use --no-mention-filter and explains
what it enables (forum posts stop being invisible). It does not say
what its scope is, which is the part that bites: the harness subscribes
to every channel the identity belongs to, and the membership
notification subscription adds more over time, so in mentions mode the
flag applies across all of them at once. The new callout says that and
points at the two things that bound it, --channels and the author gate.

Defaults and behaviour checked against config.rs: resolve_channel_filters
(require_mention = !no_mention_filter per channel) and
resolve_dynamic_channel_filter (channels_override filters discovery
rather than replacing it, and is ignored in config mode).

Signed-off-by: Emanuel Covasa <e.covasa@gmail.com>
@EmminiX
EmminiX requested a review from a team as a code owner August 12, 2026 22:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant