docs: present OpenTag as the flagship Channels SDK application - #32
Merged
Conversation
channels-sdk calls OpenTag "the flagship application built on Channels SDK" and vendors it as a submodule at examples/OpenTag. OpenTag never said so back, and never framed itself as something to take rather than read. Pattern-match its presentation to channels-sdk and make the clone-and-customize path explicit. Adopt the channels-sdk README shape: centered header with tagline, nav links and badges; the demo video directly beneath it; benefit-oriented section headings; a "You run / CopilotKit Intelligence manages" split table; and a "Developer resources" table. Add the reciprocal link that was missing in both the header and the resources table. New sections: - "The complete Channels SDK application" — clone / customize / ship, stating the relationship channels-sdk already documents from its side. - "See it work" — three 1600x900 stills in the three-column layout channels-sdk uses. These are real frames from the committed demo video (t=18s a CSV becoming a native Slack chart, t=43s the Linear approval gate, t=64s research with cited sources), not mockups, so they cannot drift from what the code does. - "Make it yours" — a table mapping each thing a fork would change to the one file or directory that owns it, including that AGENT_URL points at any AG-UI agent, so swapping frameworks needs no Channel changes. Add AGENTS.md, following channels-sdk's convention and its lesson: name the authority, install skills rather than vendoring them. Registry `setup-slack-channel` turns out to be written for an OpenTag checkout specifically — it assumes app/channel.tsx, app/env.ts, INTELLIGENCE_CHANNEL_NAME and an agent on 8123 — so it is named as the preferred path here over a generic sequence. Carries the repo map, the four verification commands, the gotchas that cost the most time, and the convention that pinned versions live in package.json and nowhere else. The quick start, prove-it-works checks, and diagnostics from #31 are unchanged. Verified: check-types clean, 162 TS tests, 70 Python tests, Railway IaC diagnostics empty, and every local link and image path in README.md and AGENTS.md resolves.
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
channels-sdk already calls OpenTag
"the flagship application built on Channels SDK" and vendors it as a git
submodule at
examples/OpenTag. That relationship was entirely one-directional:OpenTag's README never mentioned Channels SDK, and never framed itself as
something to take rather than read.
The vision — a flagship product example of Channels SDK and managed Intelligence
that people clone, customize, and get started with — needed the README to say so
and to show the seams where a fork would cut.
Pattern-matched to channels-sdk
main)assets/demo-*.pngat 1600×900, matching their specAGENTS.mdat root## License→[MIT](./LICENSE) © CopilotKitAnd the link back, which was missing from both the header and the resources table.
New sections
"The complete Channels SDK application" — channels-sdk shows you the pieces;
OpenTag is those pieces assembled into something you'd deploy. Clone it /
customize it / ship it.
"See it work" — three stills in channels-sdk's three-column layout. These are
real frames from the demo video, not mockups, so they can't drift from what
the code does:
demo-chart.png.csvuploaded → native Slack line chart + written takeawaydemo-approval.pngdemo-research.png"Make it yours" — every thing a fork would change, mapped to the one file or
directory that owns it. The important row:
AGENT_URLpoints at anyAG-UI-compatible agent, so swapping frameworks needs no Channel changes at all.
That's the strongest argument for cloning this repo rather than starting over, and
it wasn't stated anywhere.
AGENTS.mdFollows channels-sdk's convention and its hard-won lesson — name the authority,
and install skills rather than vendoring them (they vendored
setup-slack-channel,it fell ~16 KB behind across eight files, and ended up asserting the opposite of
the truth about Slack interactivity).
Worth flagging: the registry's
setup-slack-channelskill is written for anOpenTag checkout specifically. Its description names
app/channel.tsx,app/env.ts,INTELLIGENCE_CHANNEL_NAME, and a local agent on port 8123. So it'snamed here as the preferred path over a generic setup sequence — nothing in this
repo previously pointed at a skill built for it.
AGENTS.mdalso carries the repo map, the four verification commands, the gotchasthat cost the most time (no hot-reload,
ready()resolving onsetup_required,the
LOG_LEVELdefault, the Channel-name claim race, slash commands unverified onthe managed path), and the convention that pinned versions live in
package.jsonand nowhere else — with the three-copies-drifted incident from#31 as the reason.
Unchanged
The quick start, the three prove-it-works checks, and the diagnostics from #31 are
untouched. This is presentation and framing on top of that correctness work, not a
rewrite of it.
Verification
Every local link and image path in
README.mdandAGENTS.mdresolves, and allfive in-page anchors match a heading.
Follow-ups, not in this PR
Two asset slots are still empty relative to the channels-sdk pattern — a hero
graphic (
hero-any-agent-any-channel.pngequivalent) and an architecture image(
architecture.pngequivalent). The video carries the top of the README and atext diagram carries "How it works" in the meantime, which is honest but not
matched.
The Remotion project that produces channels-sdk's assets has been copied to
~/Movies/gtm-os/opentag-assets/with a README explaining what's reusable (brandsystem, motion, primitives, render pipeline) versus what still tells the Channels
SDK story and would need rewriting for OpenTag's narrower one. Rendering those two
assets is its own piece of work.