Skip to content

docs(skills): state that no channel verb creates an integration - #155

Merged
ysyneu merged 1 commit into
mainfrom
docs/channel-integration-boundary
Aug 20, 2026
Merged

docs(skills): state that no channel verb creates an integration#155
ysyneu merged 1 commit into
mainfrom
docs/channel-integration-boundary

Conversation

@ysyneu

@ysyneu ysyneu commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Why

reference/channel.md documents --plugin-ids as "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-commands dump and several jq passes 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-ids subscribes integrations that already exist; no verb creates or configures one.
  • Integration creation and its inbound address/token are console-only, outside this CLI's API surface — so they are absent from the command tree by design.
  • Answer "how do I connect X" from the product documentation and point at the console; don't grep the command tree for a verb that cannot exist.
  • channel info reports the channel's own fields, not integration credentials.

Verification

  • go build ./... clean
  • go test ./internal/skilldoc/... passes
  • Docs-only; no command surface or generated fence touched.

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.
@ysyneu
ysyneu merged commit 28073d3 into main Aug 20, 2026
12 checks passed
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