# Initiative Brief: Workspace Shell, Context Contract, and Conversational Runtime ## Desired outcome Establish the primary interaction model for Xyence Workspaces: a consistent platform-owned shell with a persistent, context-aware conversational interface that every workspace can participate in through explicit contracts. Workspaces should become more than a launcher for independent applications. It should provide the common human interface through which users select what kind of work they want to perform, see domain-specific information, converse naturally about that work, attach visual or file-based evidence, and invoke authorized domain capabilities without each workspace rebuilding its own navigation, conversation system, attachment handling, or AI integration. The platform shell should own: * the global header; * workspace selection; * organization/account context; * the hybrid navigation rail; * durable conversations and conversation history; * Composer; * file/image attachments; * direct screenshot capture; * context-change events; * responsive/mobile behavior; * shared confirmation/audit conventions for AI-initiated actions. Individual workspaces should own their primary domain UI while declaratively contributing navigation, context, capabilities, actions, and landing-page information to the shell. The Orchestrator workspace will be the first substantial consumer of this architecture, but this initiative must establish reusable platform contracts rather than embedding Orchestrator-specific assumptions. ## Motivation The current workspace-based applications already share portions of a common shell, including global workspace and organization selection, but the interaction model is not yet formalized strongly enough to support the platform's longer-term direction. The intended user experience is increasingly conversational. A user should be able to enter Workspaces and answer a simple question: **What do you want to work on?** Examples might include: * Software development * Websites * Sales * Marketing Selecting a workspace changes both the primary application UI and the context of the shared Composer. Within a workspace, selecting a particular object—such as a website, repository, initiative, lead, or campaign—should further refine the context available to the conversation without forcing the user into a new conversation. Without a shared platform architecture, each workspace is likely to independently implement: * navigation; * AI/chat UI; * conversation persistence; * context handling; * attachment uploads; * screenshot support; * action confirmation; * responsive behavior. That would recreate the fragmentation Workspaces is intended to eliminate. A platform-level contract is therefore needed before conversational features are added deeply to individual workspace applications. ## Product principles - Workspaces owns the shell — Workspace applications participate in the shell. They do not replace it. Conversation is a platform capability — Orchestrator, Web, Sales, Marketing, and future workspaces should not implement independent chat systems. Workspace selection establishes conversational scope — Entering a workspace determines: - the relevant conversation history; - the default domain; - available domain capabilities; - visible workspace navigation; - initial landing content. Navigation may refine conversation context without starting a new conversation — Selecting an object within a workspace should normally update the existing conversation context. A new conversation is an explicit user action, not a side effect of navigation. Context changes are visible — A conversation must never silently change semantic scope. When relevant context changes, the conversation should record a durable context event such as: > Context changed · stlouishighrises.com or: > Context changed · Xyence/workspaces repository Primary UI and conversation complement one another — Composer must not become a blank prompt that carries the full burden of teaching users what the product can do. Every workspace should provide meaningful structured landing content and suggested activities. The shell is declarative — Critical shell regions should consume workspace-defined metadata/contracts rather than arbitrary workspace-provided React UI. This preserves consistency, accessibility, security, mobile behavior, and future evolution. ## Rejected / deferred alternatives - Full Orchestrator ideation implementation. - Full Web workspace implementation. - Full voice mode. - General-purpose unrestricted consumer chat. - Cross-workspace conversation handoff in the first release. - Autonomous browser screenshotting by the AI. - Allowing workspaces arbitrary DOM/React control over platform shell regions. - Moving domain ownership into Workspaces. - Replacing domain service APIs with MCP solely for internal integration. ## Invariants - The platform owns the shell. - The platform owns conversation persistence and Composer. - Workspaces contribute shell behavior through declared contracts. - Primary domain UI remains workspace-owned. - Navigation does not silently create conversations. - Material context changes are visible and durable. - Historical messages retain the context under which they were sent. - User-provided context cannot bypass authorization. - Provider and service credentials remain server-side. - Conversation does not implicitly authorize mutating actions. - Screenshot and attachment access follows conversation authorization. - Critical shell regions are not arbitrary workspace-rendered JSX. - Domain systems remain authoritative for domain data and actions. ## Repository scope - `Xyence/workspaces` — Primary implementation. Likely includes: - shell architecture; - workspace contract; - navigation contract; - context contract; - capability/action contracts; - conversation persistence; - Composer; - attachment and screenshot UX; - conversation runtime integration; - landing page; - responsive behavior; - contract validation. `Xyence/outshine` — Only where platform authentication, organization/workspace identity, storage, or authorization boundaries require extension. Avoid making Outshine the owner of conversation semantics solely because it already provides platform APIs. `Xyence/orchestrator` — No substantial Orchestrator-domain implementation is required by this foundation initiative except where needed to keep the existing workspace functioning during shell migration. Full Orchestrator conversational integration belongs to the follow-on initiative. ## Expected behavior - A user can land in Workspaces and select a workspace from a meaningful task/domain-oriented landing experience. - The existing organization/workspace header behavior is retained or cleanly migrated. - The platform renders a consistent shell around at least one workspace. - A workspace can declaratively contribute navigation. - A workspace can publish active semantic context to the shell. - Composer is platform-owned and consistently available. - Durable conversations can be created, resumed, and archived. - Conversation history defaults to the active workspace. - Changing selected domain context does not automatically create a new conversation. - Material context changes appear in conversation history. - Composer supports image/file attachments. - Composer provides low-friction screenshot capture. - Screenshot messages retain useful current-page/workspace context. - The server-side conversation runtime can consume workspace-declared read capabilities. - Mutating capabilities may require deterministic confirmation outside model judgment. - All context and capability access is re-authorized server-side. - Long conversations use bounded context rather than unlimited transcript replay. - Conversation/action provenance is durably recorded. - The shell works at desktop and mobile viewport sizes. - The architecture is ready for later voice input without replacing the message model. - Workspace contracts are versionable and testable. - Conversational model/tool failures are observable without unsafe logging.