# Matrix Plugin Architecture

ZoneGaze Matrix is a lightweight shell first, but each installable plugin is a full product
package inside the Matrix repository. The shell owns Dashboard, Ports, Plugin, Settings, the
left rail, split panes, install state, and lifecycle. Users install Flow, Whispr, Chat, Joplin,
Code, Open Design, Exo, or future plugins from Plugin; installed plugin tabs then open the
plugin inside the Matrix window.

The shell is not the product implementation. It owns plugin discovery, install state,
activation, same-window composition, split panes, shared settings, and platform lifecycle. Each
plugin owns its app/runtime/UI source, assets, manifests, tests, docs, and product-specific
platform adapters inside `plugins/<product>/`.

## Product Boundary

Flow owns agent orchestration, task worktrees, terminal sessions, Git review, project context, and
the main local runtime.

Whispr owns voice capture, speech-to-text providers, dictation insertion, transcript history, notes,
recent activity, upload-audio transcription, saved-recording playback, personal dictionary cleanup,
and speech-related platform bridges. Matrix can adapt the desktop bridge, but completed dictations
must still pass through Whispr's normal completion pipeline before Matrix mirrors them.

Chat owns the same-window project conversation surface, local conversation persistence, runtime chat
service integration, settings, optional Flow context, and Whispr insertion. It should stay separate
from Whispr; Whispr does not own agent chat.

Joplin owns the notes and knowledge workspace surface for project docs, research, and handoff
context. The Matrix package owns notebooks, notes, local persistence, search, Whispr quick-note
handoff, Flow project context display, and joined settings while keeping upstream Joplin source
isolated.

Code owns the ZoneGaze-branded Code-OSS/code-server IDE surface. Android currently runs it through the
owned Zone Terminal code-server adapter, and the VS Code OSS upstream source mirror now lives under
`plugins/code/upstreams/vscode`. Mac discovery/opening bridges are adapters only; the ZoneGaze Code
product must be built as an in-Matrix plugin package, not treated as a separate external app. Do
not use Microsoft Visual Studio Code branding, icons, or extension-store assumptions for the ZoneGaze
Code plugin.

Open Design is tracked as a third-party upstream design workspace plugin from
`https://github.com/nexu-io/open-design`. The `plugins/open-design/` package starts or attaches
to the upstream daemon/web runtime and embeds the upstream web UI in Matrix. Keep upstream source
read-only except for intentional source refreshes and place product-specific adapters inside the
plugin boundary.

Shared Matrix code should stay in contracts, catalog metadata, design tokens, platform install/open
bridges, or small provider-neutral helpers. Do not move Flow task/session logic into Whispr, do not
move Whispr audio/transcription or Code IDE internals into Flow, and do not leave a product as only a
bridge point when its feature source belongs inside its plugin package.

## Starter Surfaces

- Product and module catalog: `flow/contracts/src/zonegaze-products.ts`.
- Matrix module rail: `flow/web/src/components/project-navigation-panel.tsx`.
- Module plugin panels: `flow/web/src/components/plugins/zonegaze-plugins-panel.tsx`.
- Matrix plugin install state: `flow/web/src/plugins/matrix-installed-plugins.ts`.
- Joined settings hub: `flow/web/src/components/settings/matrix-settings-panel.tsx`.
- Whispr plugin source: `plugins/whispr/`.
- Plugin import note: `plugins/whispr/MATRIX-IMPORT.md`.
- Code plugin note: `plugins/code/MATRIX-PLUGIN.md`.
- Code upstream import note: `plugins/code/UPSTREAMS.md`.
- Chat plugin note: `plugins/chat/README.md`.
- Joplin plugin note: `plugins/joplin/README.md`.
- Open Design plugin note: `plugins/open-design/README.md`.
- Open Design upstream import note: `plugins/open-design/UPSTREAMS.md`.

Installed plugin tabs appear in the user-controlled order. Dashboard, Ports, Plugin, and
Settings are Matrix shell surfaces; plugin tabs are full-bleed plugin surfaces and may collapse the
Matrix rail according to the user's saved per-tab preference.

## Plugin Runtime Lifecycle

Matrix must not start plugin runtimes just to show the shell. The desktop app can load the bundled
web UI as a static Matrix shell with `matrixShell=static`; that mode does not open the Flow runtime
websocket and must not imply that Flow, Whispr, Code, Open Design, Exo, or other runtimes are live.
Runtime status in Plugin and Ports comes from platform bridges or the ports snapshot, not from
installed plugin state.

Runtime-backed plugins start only from explicit user action. Flow starts through the managed
`zonegaze-flow` service, Code/Open Design/Exo start through their plugin adapters, and Whispr starts
only when the user begins dictation. Stopping a managed runtime belongs in the Matrix left rail when
the active plugin is running. If active work would be interrupted, the stop action must warn first;
if there is no active work or data-loss risk, it should stop immediately. Matrix must never show fake
stop controls for local-first plugins that do not own a background process.

On Android, the native plugin catalog must keep the plugin-owned host adapter separate from the
temporary Matrix web route renderer. For example, Open Design owns the `open-design` adapter and Exo
owns the `exo` endpoint adapter even when their Android panel is rendered by APK-bundled Matrix web
assets or an already running Matrix web host. Opening those plugins must not start `zonegaze-flow`
as a side effect. Flow-hosted plugin surfaces that still require runtime APIs, such as the current
Joplin adapter, may declare `zonegaze-flow` as their web route server until their Android-native
surface is split out.

## Embedded Plugin Navigation

Matrix owns the only app-level left sidebar. Embedded plugin surfaces must not render their
standalone desktop sidebars inside Matrix, because that creates nested primary navigation and makes
the shell feel like separate apps stitched together. Plugin-owned destinations such as Home,
Dictionary, History, Extensions, Quick notes, and Settings should appear as compact in-content tags
or tabs inside that plugin's content surface. Keep those tags on the same Signal system as the
Matrix dashboard: dark panels, hairline borders, restrained Signal-green active state, and no broad
green-tinted surfaces.

Joplin is the exception to the compact-tab pattern because its upstream product identity is the
notes app itself. The Matrix Joplin plugin should open directly into the Joplin-style notebook
sidebar, note list, and Markdown editor, with app actions in the Joplin toolbar. Do not place the
old Matrix Workspace/Search/Resources/Context/Settings tab strip before the notes app.

Matrix-embedded Whispr is the current reference for this pattern. It removes the standalone Whispr
top bar and standalone provenance/status labels, keeps Whispr-owned Home/Dictionary/History/
Extensions/Quick notes/Settings as in-content tags, shows three copyable recent transcripts on Home,
marks Snippets as coming soon, exposes Upload audio even when the current provider cannot handle file
transcription, and keeps saved-recording playback/progress controls in History.

## Common-Code Candidates

Bring these into Matrix-owned shared code only when a second product actively consumes them:

| Candidate | Current owners | Shared shape |
| --- | --- | --- |
| Product and module catalog metadata | Flow web, Flow contracts, plugin package metadata | `flow/contracts/src/zonegaze-products.ts` as the source of truth. |
| Signal design tokens | root Signal package, Flow web theme, Whispr `DESIGN.md` | Keep root Signal as canonical and map product themes to it. |
| Plugin install/open state | Flow desktop Whispr and Code bridges, plugin desktop apps, joined settings | Small platform bridge contracts for installed/running/open/download states. |
| Android package/download dashboard | Flow Android shell, Whispr mobile Android app, ZoneGaze Code Zone Terminal adapter | Shared install-state vocabulary before sharing implementation. |
| IDE branding and launch metadata | Android code-server adapter, Mac ZoneGaze Code app target, web open target | Keep ZoneGaze Code naming/logo separate from Microsoft Visual Studio Code assets. |
| Manifest signing and verification | Whispr extension scripts/runtime | Promote only after Matrix has a real plugin package registry. |
| Result/time/resource helpers | Whispr `packages/common/src/shared` | Promote only when Flow or another plugin imports equivalent logic. |

## Download Model

The website downloads hub remains the public distribution point. Matrix source includes multiple
full product packages, but users should receive the skeleton first and install only the plugins they
need:

- Matrix skeleton Mac app / Android app with Plugin only.
- Flow plugin for the project board and coding-agent dashboard.
- Whispr plugin for dictation.
- Chat plugin for same-window conversations.
- Joplin plugin for notes and knowledge.
- ZoneGaze Code plugin for the workspace IDE.
- Open Design plugin for agentic design workspace workflows.
- Future plugins can be added by extending the catalog and adding a sibling source boundary.

Agents must not upload installers to the website. Publishing is a manual release step.
