Skip to content

docs: present OpenTag as the flagship Channels SDK application - #32

Merged
jerelvelarde merged 1 commit into
mainfrom
jerel/opentag-flagship-pattern-match
Aug 5, 2026
Merged

docs: present OpenTag as the flagship Channels SDK application#32
jerelvelarde merged 1 commit into
mainfrom
jerel/opentag-flagship-pattern-match

Conversation

@jerelvelarde

Copy link
Copy Markdown
Collaborator

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

Pattern Adopted
Centered header: title, tagline, nav links, badges
Demo video immediately under the header, centered caption below ✅ (uses the video already in main)
Benefit-oriented section headings, not mechanical ones
Three-column capability table ✅ clone / customize / ship
Three-column platform/capability screenshot table assets/demo-*.png at 1600×900, matching their spec
"You run / CopilotKit Intelligence manages" split table
"Developer resources" — I want to… / Start here
AGENTS.md at root
## License[MIT](./LICENSE) © CopilotKit

And 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:

Still Frame Shows
demo-chart.png t=18s a .csv uploaded → native Slack line chart + written takeaway
demo-approval.png t=43s the Linear write pausing for approval, then reporting what it created
demo-research.png t=64s research returned as a table with cited sources

"Make it yours" — every thing a fork would change, mapped to the one file or
directory that owns it. The important row: AGENT_URL points at any
AG-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.md

Follows 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-channel skill is written for an
OpenTag checkout specifically.
Its description names app/channel.tsx,
app/env.ts, INTELLIGENCE_CHANNEL_NAME, and a local agent on port 8123. So it's
named here as the preferred path over a generic setup sequence — nothing in this
repo previously pointed at a skill built for it.

AGENTS.md also carries the repo map, the four verification commands, the gotchas
that cost the most time (no hot-reload, ready() resolving on setup_required,
the LOG_LEVEL default, the Channel-name claim race, slash commands unverified on
the managed path), and the convention that pinned versions live in
package.json and 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

pnpm check-types                            ✓
pnpm test                                   ✓ 162 passed
cd agent && uv run pytest                   ✓ 70 passed
node node_modules/railway/dist/iac/bin.js   ✓ "diagnostics": []

Every local link and image path in README.md and AGENTS.md resolves, and all
five 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.png equivalent) and an architecture image
(architecture.png equivalent). The video carries the top of the README and a
text 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 (brand
system, 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.

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.
@jerelvelarde
jerelvelarde merged commit a5e4856 into main Aug 5, 2026
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