docs(concepts): add Adaptive Cards documentation#41908
docs(concepts): add Adaptive Cards documentation#41908VikrantSingh01 wants to merge 3 commits intoopenclaw:mainfrom
Conversation
openclaw-barnacle
bot
added
docs
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e37f7a0818
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Greptile SummaryThis PR adds a new documentation page at
These issues should be resolved before merging. Confidence Score: 1/5
Last reviewed commit: e37f7a0 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | **Memory** | ~2MB per card | ~30-50MB (WebView process) | | ||
| | **Use case** | Quick inline interactions | Rich dashboards, visualizations | | ||
| | **Persistence** | Lives in chat history | Ephemeral canvas session | | ||
|
|
||
| Use cards for lightweight, inline, disposable interactions. Use Canvas for complex, interactive, persistent visual experiences. | ||
|
|
||
| ## Card elements | ||
|
|
||
| The plugin supports all [Adaptive Cards v1.5](https://adaptivecards.io/explorer/) body elements: |
There was a problem hiding this comment.
Canvas persistence is incorrectly described as "Ephemeral".
The comparison table states Canvas has "Ephemeral canvas session" for persistence, but this contradicts the Canvas documentation. From docs/platforms/mac/canvas.md, Canvas state is stored under ~/Library/Application Support/OpenClaw/canvas/<session>/... and "Remembers size/position per session" with "Auto‑reloads when local canvas files change." Canvas files are written to disk and persist between sessions. The correct characterisation would be "Persists to disk per session" — the opposite of ephemeral.
| | **Memory** | ~2MB per card | ~30-50MB (WebView process) | | |
| | **Use case** | Quick inline interactions | Rich dashboards, visualizations | | |
| | **Persistence** | Lives in chat history | Ephemeral canvas session | | |
| Use cards for lightweight, inline, disposable interactions. Use Canvas for complex, interactive, persistent visual experiences. | |
| ## Card elements | |
| The plugin supports all [Adaptive Cards v1.5](https://adaptivecards.io/explorer/) body elements: | |
| | **Persistence** | Lives in chat history | Persists to disk per session | |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/concepts/adaptive-cards.md
Line: 62-70
Comment:
Canvas persistence is incorrectly described as "Ephemeral".
The comparison table states Canvas has "Ephemeral canvas session" for persistence, but this contradicts the Canvas documentation. From `docs/platforms/mac/canvas.md`, Canvas state is stored under `~/Library/Application Support/OpenClaw/canvas/<session>/...` and "Remembers size/position per session" with "Auto‑reloads when local canvas files change." Canvas files are written to disk and persist between sessions. The correct characterisation would be "Persists to disk per session" — the opposite of ephemeral.
```suggestion
| **Persistence** | Lives in chat history | Persists to disk per session |
```
How can I resolve this? If you propose a fix, please make it concise.There was a problem hiding this comment.
Fixed in 0111383. Changed Canvas persistence to "Persists to disk per session" — corrected the factual error.
- Move from docs/concepts/ to docs/plugins/ (community plugin, not core concept) - Fix frontmatter: use summary + read_when (repo convention), not description - Fix Canvas persistence: "Persists to disk per session" not "Ephemeral" - Lower memory: ~1-2MB per card (more accurate)
VikrantSingh01
force-pushed
the
docs/adaptive-cards-feature
branch
from
0111383 to
4f85e25
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4f85e25b35
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| ## How it works | ||
|
|
||
| When the agent decides that structured content is appropriate, it calls the `adaptive_card` tool. The tool assembles an [Adaptive Card v1.5](https://adaptivecards.io/explorer/) JSON payload and embeds it in the message text. Each client platform extracts the card and renders it natively: |
There was a problem hiding this comment.
The support matrix states that all clients extract adaptive_card payloads from message text and render native cards, but the repository does not implement that transport outside Teams: a repo-wide search for <!--adaptive-card--> only matches this new doc, and concrete Adaptive Card send logic appears only in the Teams path (extensions/msteams/src/send.ts:470). As written, users will expect iOS/Android/Web/Slack/Discord rendering behavior that OpenClaw currently cannot perform, so this section should be narrowed to implemented channels (or clearly marked as future/experimental).
Useful? React with 👍 / 👎.
…text - Fix all v1.5 references to v1.6 (matches adaptive-cards-mcp v2.3.0) - Add missing elements: CodeBlock, ActionSet, Carousel, Accordion, TabSet, Rating, ProgressBar, Badge, CompoundButton, Chart.*, Input.Time - Add missing actions: Action.Execute, Action.ToggleVisibility - Add validation/host-compat/a11y section (MCP bridge) - Add 21 layout patterns mention - Add template data markers to architecture section - Expand fallback text section with RichTextBlock, CodeBlock, Carousel, Rating - Link to adaptive-cards-mcp repo Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c1b9678309
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| openclaw plugins install @vikrantsingh01/openclaw-adaptive-cards | ||
| ``` | ||
|
|
||
| No configuration needed. The plugin is stateless. |
There was a problem hiding this comment.
The installation flow stops at openclaw plugins install ... and then says no configuration is needed, but it never tells users to restart the running gateway. In this repo, plugin install paths consistently instruct restart because the running process does not hot-load newly installed plugins (src/cli/plugins-cli.ts logs Restart the gateway to load plugins. at multiple install branches, e.g. around lines 339, 417, and 501). If someone installs while the gateway is already running, the documented /acard workflow will not be available until a restart.
Useful? React with 👍 / 👎.
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
BradGroux
left a comment
BradGroux
left a comment
There was a problem hiding this comment.
Review: Adaptive Cards Documentation
The doc has the right structure (YAML frontmatter with summary, read_when, title) and lives in the correct docs/plugins/ directory. Content is solid and the AC vs Canvas comparison table is genuinely useful. However, there are several issues that should be addressed before merge.
Issues
1. Element table overstates v1.6 spec coverage
The "Card elements" table lists Carousel, Accordion, TabSet, Chart.Donut, Chart.Gauge, Chart.HorizontalBar, and Chart.Line as supported elements. These are NOT part of the official Adaptive Cards v1.6 schema. They appear to be custom extensions or proposals. The table should clearly distinguish between standard v1.6 elements and custom/extended elements, or remove them entirely to avoid misleading consumers of this doc.
2. Performance claims lack evidence
The platform table lists specific render times (~50ms for iOS/Android, ~100ms for Web) as facts. These numbers are presented without benchmarks, test methodology, or hardware context. Either add a footnote explaining how these were measured, or soften the language to "typical" or "approximate" values.
3. Missing from docs.json navigation
The file is added to docs/plugins/ but is not registered in the Mintlify docs.json navigation structure. Without this, the page exists but is not reachable from the sidebar. Every other plugin doc is registered there.
4. No configuration section
Every other plugin doc in the repo shows the plugins.entries.<name>.config JSON block, even if it is minimal. This doc says "No configuration needed" which may be accurate, but should still show how the plugin appears in openclaw.json after install so users know what to expect.
5. Tone diverges from repo conventions
Existing plugin docs (e.g., voice-call.md) are dry, practical reference material. This doc reads more like a product page with marketing language ("Instead of walls of markdown text..."). Not a blocker, but worth aligning with the established tone.
6. No "Where it runs" section
Other plugin docs explain local vs remote Gateway behavior. This is missing here.
Summary
The content itself is good and comprehensive. The main concern is accuracy (v1.6 element claims) and alignment with the existing documentation conventions in the repo. Address items 1-4 and this is ready to merge.
2 participants
Summary
Adds documentation for the Adaptive Cards feature at
docs/concepts/adaptive-cards.md.Covers:
openclaw plugins install)/acardcommandThis is the docs companion for the standalone openclaw-adaptive-cards plugin.
Ecosystem Context
This PR is part of the Adaptive Cards feature set spanning three repos:
adaptive_cardtool, MCP bridge for validation/host-compat/a11y, HTML comment marker transport, channel-aware prompt guidance, fallback text generation, action routingRelated PRs