Teach the OpenUI skill to integrate and migrate to Cloud

[vishxrad]

Summary

This PR teaches the OpenUI skill two missing workflows:

• integrate OpenUI Cloud into an existing project without replacing the host application's routing, authentication, layout, package manager, or working behavior;
• migrate an existing open-source/self-hosted OpenUI application to Cloud using replacement or dual mode while preserving unsupported capabilities and historical data.

The scope is intentionally limited to the skill itself. CLI templates, runtime hardening, website documentation, AGENTS.md, and template tests are deferred to separate PRs.

Feedback addressed

The skill already handled open-source OpenUI integration well, but it did not model the managed Cloud architecture. It could not reliably:

• add the managed Cloud Agent Interface to an existing application in one pass;
• distinguish the generation proxy from the frontend-token/storage plane;
• migrate self-hosted OpenUI without conflating code migration with historical-data import;
• preserve custom tools, component libraries, attachments, artifacts, authentication, storage, and existing routes when Cloud does not have a verified equivalent.

Methodology

1. Audited the current first-party contract

The work started from the current repository rather than an isolated recipe:

• inspected the Cloud and self-hosted CLI templates and examples;
• traced the relevant exports from @openuidev/react-ui, @openuidev/react-headless, @openuidev/thesys, and @openuidev/thesys-server;
• verified the latest-message transport, Responses adapter/message-format pairing, Cloud storage token flow, managed artifact renderers, abort propagation, and SSE termination;
• compared the current Next.js rendering boundary and Cloud API usage with the proposed guidance;
• treated installed packages, generated templates, and current first-party sources as authoritative for version-sensitive details.

2. Used independent design and forward reviews

Grok and claude -p were used as independent subagents on realistic scenarios:

• Grok exercised adding Cloud to an existing authenticated Next.js AgentInterface application with restStorage and a custom shell.
• Claude exercised migrating a self-hosted application with custom tools, a custom component library, historical conversations, and production authentication.

Their reviews reinforced the same design:

• route Cloud work explicitly from the main skill;
• keep detailed Cloud procedures in lazy-loaded references;
• preserve self-hosted behavior through dual mode when Cloud parity is unverified;
• treat authentication, identity, conversation ownership, and server-key isolation as production boundaries;
• avoid inventing history-import, custom-tool, custom-library instruction, or conversation-membership APIs.

Additional scope and contract audits removed over-prescriptive or stale guidance: the Next.js recipe now follows the installed first-party template and uses ssr: false only as a reproduced fallback, and no undocumented conversation endpoint/header/pagination contract is presented as canonical.

3. Added progressive-disclosure routing

skills/openui/SKILL.md remains the compact dispatcher. It now:

• triggers explicitly for existing-project Cloud integration and self-hosted-to-Cloud migration;
• audits the host application's framework, server runtime, auth, transport, storage, tools, artifacts, and component library before editing;
• routes integration work to references/cloud-integration.md;
• routes migration work to both Cloud references;
• keeps code migration separate from historical-data migration;
• preserves the existing self-hosted path until replacement is explicitly intended and verified.

4. Defined the existing-project integration workflow

cloud-integration.md provides the complete Next.js App Router methodology and adaptable contracts for other server frameworks:

1. Audit the host and add only missing packages.
2. Preserve the existing server page, authentication, product shell, theme, slots, and route conventions.
3. Keep Cloud imports in a client component and match the installed template's dynamic-rendering boundary.
4. Keep the two Cloud planes separate:
   • ChatLLM posts the latest formatted message to the application's server-side generation proxy.
   • useOpenuiCloudStorage() uses a short-lived frontend token scoped to the authenticated user.
5. Keep THESYS_API_KEY server-side.
6. Validate and allowlist untrusted generation input, propagate aborts, and terminate the SSE stream correctly.
7. Treat threadId as untrusted. Authentication, bounded request parsing, and conversation ownership are explicit host-supplied boundaries—not assumed OpenUI exports.
8. Stop at a production blocker when the host cannot provide a trusted conversation binding or a documented Cloud membership check.
9. Verify security, adapter/format pairing, persistence, user isolation, and managed artifacts.

5. Defined the self-hosted-to-Cloud migration workflow

oss-to-cloud-migration.md separates the decisions that were previously being collapsed:

• replacement vs dual mode;
• application-code migration vs historical-data import;
• self-hosted AgentInterface, legacy chat, Renderer-only, custom-library, and tool-heavy starting points.

It maps the self-hosted transport, adapter, format, storage, library prompt, and artifact loop to the managed Cloud equivalents while preserving:

• historical conversations and artifacts when no import API is verified;
• custom tool execution when no complete Cloud continuation loop is documented;
• custom-library generation when managed instruction composition is unverified;
• attachment/media paths until the installed end-to-end Cloud contract is verified;
• the self-hosted mode whenever capability parity is incomplete.

6. Reduced the PR to the requested boundary

The PR head was rebuilt from current main and now changes exactly:

• skills/openui/SKILL.md
• skills/openui/references/cloud-integration.md
• skills/openui/references/oss-to-cloud-migration.md

The earlier CLI template, CLI tests, website docs, React UI comment, and AGENTS.md changes are intentionally not part of this PR.

Validation

Validation performed for this skill-only change:

• skill structure/frontmatter validation with quick_validate.py — passed;
• Prettier check for both new reference files — passed;
• relative skill-reference link check — passed;
• git diff --check — passed;
• source-contract review against current main — passed;
• GitHub changed-file verification — exactly the three skill files above;
• Grok and Claude scenario reviews — completed, with findings incorporated.

No CLI/template test suite, application build, or live Cloud-key smoke test is claimed because this PR no longer changes application or template code.

Deliberate boundaries

• Historical Cloud data import is not claimed without a verified first-party import API.
• Custom tool execution is not claimed without a documented Responses continuation loop.
• A client-side custom component library does not prove managed generation has matching instructions.
• Production conversation ownership remains a host capability or a documented version-specific Cloud contract; the skill does not invent one.
• The verified managed client path is React. Other clients require a current first-party runtime or remain on the open-source path.

Checklist

• Existing-project Cloud integration guidance
• Self-hosted-to-Cloud migration guidance
• Progressive-disclosure references
• Existing OSS/framework guidance preserved
• Unsupported capabilities preserved or reported
• Skill-only three-file scope
• No CLI, runtime, website-doc, test, or AGENTS.md churn

[zahlekhan]

why?

[vishxrad]

Dual mode is needed because moving to Cloud may not preserve every capability of the existing OSS application. For example:

• Custom tool execution may only work in the OSS backend.
• Cloud generation may not understand a custom component library.
• Historical conversations may not have a supported Cloud import path.
• Attachments or custom artifacts may lack verified Cloud parity.