docs(skills): state that no channel verb creates an integration - #155
Merged
Conversation
The channel card documents `--plugin-ids` as "IDs of plugins (integrations) subscribed to this channel" without saying where those integrations come from. Read as a capability claim, it implies the CLI can set an integration up — so a "how do I connect my mailbox" question turns into an exhaustive walk of the command tree (`webhook --help`, `datasource --help`, `__dump-commands` plus several jq passes) that can only ever conclude the verb is absent. It is absent by design: creating an integration and reading its inbound address or token are console-side operations, outside the open API this CLI speaks. Say so on the card, next to the flag that suggests otherwise, and point such questions at the product documentation instead.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
reference/channel.mddocuments--plugin-idsas "IDs of plugins (integrations) subscribed to this channel" and says nothing about where those integrations come from. Read as a capability claim it implies the CLI can set one up, so a "how do I connect my mailbox / this alert source" question becomes an exhaustive search of the command tree —webhook --help,datasource --help,account --help, a full__dump-commandsdump and severaljqpasses over it — which can only ever conclude that the verb is not there.It is not there by design: creating or configuring an integration, and reading its inbound address/token, are console-side operations that the open API this CLI speaks does not expose. Absence is currently only discoverable by exhaustive search, which is the expensive way to learn a boundary.
What
One gotcha bullet on the channel card, placed next to the flag that implies the capability:
--plugin-idssubscribes integrations that already exist; no verb creates or configures one.channel inforeports the channel's own fields, not integration credentials.Verification
go build ./...cleango test ./internal/skilldoc/...passes