[Feature]: Add configurable cross-chat rich presentation profiles

[roomote-community]

Preflight

• I searched existing issues and docs before opening this.
• This proposal is grounded in a real Roomote use case, not a broad generated feature list.

Problem

Roomote agents primarily express narrative output as Markdown. The web task view also supports sandboxed presentational widgets and artifacts can hold images, GIFs, video, PDFs, and documents, but these are separate mechanisms rather than one user-configurable presentation workflow.

This breaks down for common cross-functional communication:

• a developer needs to explain a behavior change to a business analyst without leading with code
• a manager needs a concise feature report with outcomes, rollout, risks, and decisions
• a product owner needs a visual release recap
• a documentation author needs task-oriented instructions with screenshots or short clips
• a marketing user needs a polished, branded page or media package

Users cannot currently select a reusable audience/style/output preset. Rich results also do not have a provider-aware delivery contract. A generated image can be sent as an external image URL, but that does not guarantee that motion plays or that the result uses the best native media API in Discord, Slack, Teams, or Telegram.

The result is that a successful API post can be mistaken for a successful presentation even when the receiving client displays only a static preview.

Current workaround

Users describe presentation requirements repeatedly in prompts, open Roomote artifacts separately, manually turn output into slides or graphics, use external design tools, and post the result to chat themselves.

Roomote agents can currently combine Markdown, show_widget, screenshots, and uploaded media, but:

• there is no reusable presentation profile or deterministic configuration precedence
• widgets are richest in the Roomote web task view and degrade to text plus a link in chat
• media paths are treated primarily as generic images rather than typed image/animation/video/document assets
• Discord output uses external image embeds rather than native multipart GIF/video uploads
• Telegram output uses sendPhoto rather than sendAnimation or sendVideo
• Teams generic buttons degrade to links and callback buttons are dropped because there is no validated outbound card interaction path
• mock providers can verify transport but not proprietary-client rendering, autoplay, mobile layout, or CDN transformations

Proposed behavior

Add configurable Presentation Profiles that Roomote agents can recommend, apply, save, and deliver inline across supported interaction surfaces.

Keep four concerns separate

1. Skill defines how the source is analyzed, such as issue summary, BA explainer, feature report, architecture proposal, documentation, or marketing story.
2. Recipe defines the information hierarchy, such as before/after, KPI scorecard, timeline, four-slide recap, risk report, or annotated walkthrough.
3. Style defines allowlisted visual tokens such as brand, theme, tone, density, color, typography, illustration, and motion treatment.
4. Delivery defines PNG, GIF/video, widget, PDF/site, provider-native transport, and fallback behavior.

One source-analysis skill should be reusable with different recipes and styles rather than duplicating a skill for every audience and visual treatment.

Profile configuration

Support a versioned profile equivalent to:

id: manager-feature-update
name: Manager feature update
version: 1

skill: feature-report
audience: leadership
objective: decision-and-status

recipe:
  layout: outcome-scorecard
  sections:
    - outcome
    - user_value
    - metrics
    - rollout
    - risks
    - decisions
  density: concise

style:
  theme: roomote-dark
  tone: executive
  brandId: default
  accent: teal
  motion: subtle

output:
  preferred: [png, mp4]
  fallback: [png, text]
  aspectRatio: "16:9"

quality:
  requireSources: true
  requireStatusLabel: true
  requireAltText: true
  requireMotionTranscript: true

delivery:
  postInline: true
  includeSourceLinks: true

Profiles must not contain secrets, provider credentials, remote scripts, or unrestricted executable HTML/CSS. Organization profiles should be shareable and versioned; users should be able to clone a shared profile into a personal variant.

Selection methods

Support complementary selection paths:

• natural language: “Explain this to a BA as a minimal infographic.”
• named profile: “Use manager-feature-update for this PR.”
• command: /present audience:ba format:image style:minimal
• post-answer action: Present this
• Roomote web composer with profile, audience, recipe, style, output, preview, Use once, and Save as preset

The Present this action should offer a compact first choice:

• Explain to BA
• Manager report
• Release recap
• Documentation
• Marketing
• Custom

Render immediately when the selected profile is sufficient. Ask one focused follow-up only when the answer materially changes the deliverable, for example Static image, Motion, or Website.

Use deterministic precedence:

1. explicit settings in the current message
2. current button or composer selection
3. thread/task override
4. user default profile
5. organization default profile
6. Roomote automatic recommendation

Show the applied profile and version in the result and offer actions such as Change audience, Change style, Make static, Add motion, Publish as docs, Build as site, and Save this preset.

Cross-chat presentation package

Generate one semantic package containing:

• concise text takeaway
• source links and a proposal/in-progress/shipped status label
• PNG poster as the universal visual fallback
• optional GIF, MP4, and WebM variants
• alt text
• motion transcript when applicable
• optional sandboxed web widget or durable document/site output

Provider adapters should choose native delivery:

Provider	Selection	Static	Motion
Discord	components/buttons	native image attachment	native GIF or MP4 attachment
Slack	action blocks	image file/block	GIF or video file
Teams	Adaptive Card or conversational fallback	image attachment	supported card/video or static fallback
Telegram	inline keyboard	sendPhoto	sendAnimation / sendVideo
Roomote web	composer	media viewer/widget	GIF/video/widget

If native motion fails or is unsupported, automatically degrade through motion -> PNG -> text without losing the answer or citation.

Built-in profiles

Start with a small set tied to real workflows:

• BA explainer: problem, before/after behavior, user flow, acceptance criteria, annotated UI state
• Manager feature update: outcome, user value, metrics/status, rollout, risks, decisions
• Release recap: feature cards, visual proof, rollout state, docs/source links
• Documentation walkthrough: prerequisites, steps, expected result, troubleshooting, screenshots/controlled clip
• Marketing story: benefit-led narrative, proof points, polished media, CTA, publishable site option

Quality, accessibility, and source accuracy

• require a readable static equivalent for every motion result
• generate alt text and a motion transcript
• use captions and controls for video
• respect reduced-motion preferences in HTML/widget output
• keep text readable at mobile chat-preview size
• do not rely on color alone for status or sequence
• verify every material claim against cited sources
• clearly distinguish proposed, in-progress, and shipped functionality
• prevent secrets, private repository data, and raw transcripts from entering generated public media

Validation

Use a layered test strategy:

1. validate dimensions, frame count, duration, MIME type, and byte budgets
2. inspect the PNG and representative motion frames for legibility
3. test outbound payloads, threading, retries, media methods, and fallbacks with the checked-in Discord, Slack, and Telegram mocks plus Teams provider tests
4. visually verify Roomote-controlled web rendering in the sandbox browser
5. run a golden-media smoke suite in dedicated real Discord, Slack, Teams, and Telegram test conversations

Mock servers must not be treated as proof of proprietary-client rendering. Real-client smoke checks are required for playback, mobile layout, autoplay/reduced-motion behavior, and provider CDN transformations.

Observability

Record:

• selected profile and version
• explicit user overrides and automatic recommendation
• generated media variants and validation result
• provider delivery method and response
• fallback used
• rendering/playback failure reports
• open/share actions where provider capabilities permit

Delivery phases

P0: reliable contract and selection

• define the Presentation Profile schema, versioning, and precedence
• support profile selection through natural language and quick actions
• add typed image, animation, video, and document media contracts
• implement native provider delivery and motion -> PNG -> text fallback
• add real-platform golden-media smoke coverage

P1: reusable intelligence and customization

• add the five built-in profiles
• create reusable recipes and visual templates
• add the web Present composer
• add organization/user profile storage, cloning, defaults, and versioning
• add accessibility and source-accuracy quality gates

P2: publishing and ecosystem

• add reusable brand kits and branded exports
• support publishable docs and sites
• add interactive report components where safe
• support profile import/export and sharing
• let custom skills declare compatible recipes and outputs

Completion criteria

• Users can select a profile through natural language, button, command, or the web composer.
• Skill, recipe, style, and delivery remain independently configurable.
• The applied profile and version are visible in the result.
• Explicit user choices override thread, user, organization, and automatic defaults.
• Results render inline in the originating chat using provider-native media methods.
• Discord motion uses native GIF/video attachment delivery rather than external-image embeds only.
• Telegram supports sendAnimation and sendVideo.
• Teams supports an Adaptive Card selection path or an equivalent conversational fallback.
• Every motion result has PNG and text equivalents, alt text, and a transcript.
• Built-in BA, manager, release, docs, and marketing profiles are available.
• Organization profiles are shareable and users can clone personal variants.
• Mock tests validate transport and real-client smoke tests validate visible effects.
• Delivery and fallback outcomes are observable.

Affected surfaces

• Web dashboard
• Roomote agents and standard task workflows
• Slack
• Teams
• Telegram
• Discord
• MCP/runtime tools
• API
• Docs

Self-hosting implications

This likely adds persisted presentation-profile configuration and version metadata, generated media artifacts, and background media rendering/transcoding. Self-hosted deployments need documented storage retention, byte/format limits, cleanup behavior, optional rendering dependencies, and resource budgets.

The initial implementation should reuse existing artifact storage and provider credentials. It should not require a new external hosted rendering service. Any optional font/brand asset storage and media tooling must work in the documented self-hosted environment.

Alternatives considered

• Keep Markdown only: portable and searchable, but insufficient for visual explanation, reporting, and marketing workflows.
• Allow unrestricted HTML/JavaScript: expressive but unsafe, difficult to project across chat providers, and incompatible with current sandbox boundaries.
• Generate artifacts only: durable but requires users to leave the originating conversation and does not solve provider-native delivery.
• Use one universal GIF: inconsistent playback, inefficient for longer motion, inaccessible without a static/text equivalent, and not uniformly supported by provider APIs.
• Make every presentation a custom skill: duplicates audience, recipe, style, and delivery logic instead of composing reusable concerns.

Documentation impact

Add public documentation for:

• built-in Presentation Profiles and selection methods
• organization and personal profile configuration
• profile schema, precedence, cloning, and versioning
• provider media support and fallback behavior
• accessibility and source-citation guarantees
• self-hosted media dependencies, storage, limits, retention, and troubleshooting

[roomote-community]

I've analyzed this issue and here's my proposed implementation plan:

1. Define a provider-neutral presentation contract first. Add versioned Zod/TypeScript schemas under packages/types/src/ for the four independent concerns (skill, recipe, allowlisted style, and delivery) plus a resolved PresentationPackage containing the text takeaway, status/source metadata, typed media variants, alt text, motion transcript, and fallback order. Keep executable HTML/CSS/scripts and credentials out of the schema. Replace the current narrow images/unknown[] attachments boundary in packages/communication/src/provider.ts with typed image, animation, video, and document assets and explicit provider capability/delivery results.

2. Resolve configuration once and snapshot the result into the task run. Implement the stated precedence in one shared resolver: message overrides -> current UI/action selection -> task/thread override -> user default -> deployment default -> built-in recommendation. Resolve it in the API/SDK task-creation path, then pass the effective profile ID, immutable version, overrides, and provider capability snapshot through the task-run payload in packages/types/src/task-runs.ts and packages/cloud-agents/src/server/cloud-agent-workflow.ts. Workers should consume this snapshot rather than query mutable database settings directly.

3. Add persistence as immutable revisions. Add profile, profile-version, and default-selection tables in packages/db/src/schema.ts, modeled on environmentConfigVersions and createEnvironmentConfigVersionSnapshot() in packages/db/src/lib/environment-config-versions.ts. Support deployment-shared profiles, user-owned clones, active/default revision pointers, creator/audit metadata, and safe deletion rules while preserving the repository's N-1 rollback guarantee. Start with the five built-in profiles as validated seeded definitions rather than separate agent identities or duplicated skills.

4. Expose validated management and selection APIs. Add server-owned DB helpers and tRPC procedures for listing, previewing, creating a revision, cloning, selecting defaults, and resolving an effective profile. Enforce admin authorization for deployment profiles and member ownership for personal variants. Return validation errors at the schema boundary and never persist remote scripts, secrets, or unrestricted markup.

5. Introduce a renderer/lowering layer before changing each provider. Convert the semantic package into a validated media manifest with byte, MIME, dimension, duration, frame-count, accessibility, and source/status checks. Store generated variants through the existing artifact flow in apps/api/src/handlers/artifacts/ and record which variant was selected. Then lower the package according to provider capabilities with a deterministic native motion -> native/static image -> text plus artifact link fallback, retaining citations and the answer at every level.

6. Implement native provider transports behind that contract. Update packages/slack/src/communication-provider.ts, packages/communication/src/discord-provider.ts, telegram-provider.ts, and teams-provider.ts: Slack should use native blocks/files where supported; Discord should use multipart attachments instead of image embeds for GIF/video; Telegram should select sendPhoto, sendAnimation, or sendVideo by typed media kind; Teams should emit a validated Adaptive Card/attachment where supported and otherwise use the existing conversational/link fallback. Preserve current chunking, threading, nonce/retry behavior, and provider limits, and emit a structured delivery result naming the attempted method and fallback used.

7. Integrate profile selection into agent and web interaction surfaces. Add the resolved profile and capability contract to standard workflow prompt assembly in packages/cloud-agents/src/server/workflows/ and extend the Roomote reply/post tools to accept a presentation package or named profile without duplicating policy across channel prompts. In apps/web/, add constrained profile/default management using the existing settings shell and tRPC form patterns, then add a compact Present this action and composer for profile, audience, recipe, style, output, preview, Use once, and Save as preset. The result should display the applied profile/version and accessible change/save actions. Natural-language selection should map to the same resolver; provider slash-command syntax can be added only where the provider already has a command entry surface.

8. Add layered validation, observability, and documentation. Cover schema allowlists, revision concurrency/deduplication, ownership, precedence, and task-run snapshotting with unit/database tests. Extend the checked-in Slack, Discord, and Telegram mocks plus Teams provider tests to assert native methods, multipart payloads, retries, threading, and each fallback; keep real-client playback/mobile/CDN checks as a separately documented golden-media smoke suite because mocks cannot prove rendering. Add bounded telemetry for profile/version, selection source, generated variants, validation result, delivery method, and fallback (never generated content). Update apps/docs/communications.mdx, each provider communication page, artifact/file guidance, and self-hosting documentation with media dependencies, limits, retention, cleanup, and fallback behavior.

I recommend delivering this as three reviewable milestones: P0 contract/resolver/native transport/fallback, P1 persistence/built-ins/web management and selection, and P2 richer rendering, brand kits, publishing, and ecosystem hooks. The key maintainer-owned scope decision is whether the first milestone should include only built-in plus one-off profiles or persisted deployment/user profiles; my recommendation is to keep persistence in P1 so P0 can establish and validate the cross-provider contract without coupling it to the settings UX.

This approach reuses the existing artifact pipeline, immutable configuration-version pattern, task payload boundary, communication adapters, and provider mocks while keeping analysis skill, information recipe, visual style, and delivery policy independently composable.

Please tag @roomote if you'd like me to implement this, or reply with feedback on the plan.

[easonLiangWorldedtech]

@roomote create sub-issues foreach phase. this issue is the main

[roomote-community]

I'm on it. I started a task for this issue, and I'll keep updates here.

See task

[roomote-community]

Created and linked one sub-issue for each delivery phase:

• P0: [Feature]: P0 presentation profile contract, selection, and native delivery #1060 - contract, selection, native delivery, fallbacks, and smoke coverage
• P1: [Feature]: P1 reusable presentation profiles and customization #1062 - built-in profiles, persistence, customization, web composer, and quality gates
• P2: [Feature]: P2 presentation publishing, brand kits, and ecosystem #1061 - brand kits, publishing, interactive reports, sharing, and ecosystem hooks

#1058 remains the main tracking issue. Each sub-issue includes scoped acceptance criteria and phase dependencies.