MosaicIQ: An Equity Research Workspace

A full-stack architecture specification for an AI-native equity research platform — local-first server/client sandboxing, portfolio dashboards, financial models, investment memos, and a 14-agent collaborative pipeline where every agent feels like a trusted co-analyst, with built-in research & validation cycles — built on an editorial design system.

1. Overview

MosaicIQ is a single-page application that provides buy-side analysts with a unified workspace for equity research. It combines portfolio monitoring, company fundamental data, financial modeling, investment memo authoring, and AI agent orchestration into one editorial-grade interface. The design language borrows from print magazine conventions — serif display type, monospaced data, generous whitespace, restrained accent — to make financial content legible and authoritative.

The platform targets desktop web users working on 1440p+ displays. It is not a mobile-first product. Information density is a feature: analysts need to see holdings, charts, and factor tilts simultaneously without switching tabs.

Naming convention v3

The product name is MosaicIQ — this is the canonical name used in all user-facing text, documentation, and brand materials. "Meridian" appears in the prototype as an internal codename for the shell component; it should be replaced with "MosaicIQ" in implementation. The profile editor, logo, and topbar should all read "MosaicIQ".

Core principles

1. Editorial posture. Serif display headings, monospace for all numerical data, sans-serif body. No rounded cards, no drop shadows, no gradients — borders and whitespace do the structural work.
2. Agent-native, agent-as-collaborator. AI agents are not a sidebar feature — they are the primary production pipeline, and they should feel like collaborators, not tools. Every agent interaction is designed to mirror working with a skilled co-analyst: they surface assumptions, flag uncertainty, ask clarifying questions, and present findings for review rather than delivering final answers unilaterally.
3. Local-first, sandboxed. The application is single-user and local-first. All data and the agent sandbox run locally with a clean server/client boundary — the client never reads storage directly, it goes through a typed RPC layer (§3.2). This architecture mirrors t3-code's approach and keeps the path open for future remote server support without changing the client.
4. Spreadsheet-grade data. Financial models use tabular monospace with hairline borders, sticky headers, and explicit distinction between actuals (solid type) and forecasts (italic, muted).
5. One accent, used twice. A single rust accent color appears on eyebrows and pull-quote rules. Green and red are reserved for directional meaning (positive/negative). All other color is from the near-greyscale palette.
6. Research + validation cycles. No agent output ships without a structured validation loop. Every pipeline stage ends with a review checkpoint: sources are verified, assumptions are stress-tested by the Red Team agent, and the analyst can accept, reject, or revise any finding before it propagates downstream.
7. Collapsible chrome. Left navigation panels collapse to 36px to give maximum space to content. The command bar persists across all screens as the agent control surface.

2. Design Tokens

All colors are specified in OKLch for perceptual uniformity. The palette is warm-neutral with a single saturated accent. No shadows, no gradients in production UI.

Typography

Spacing and radii

• All radii are 2px or 0. No rounded cards, no pill shapes except the avatar circle.
• Border weight is 1px solid var(--border) universally. Total rows and section dividers use 1px solid var(--fg).
• Content padding: 28px 36px in the center column. 16px in cards and metric cells.
• The topbar is 48px tall. The command bar is 52px minimum.

3. System Architecture

MosaicIQ is structured as a fixed chrome shell with swappable screen content. The shell consists of three persistent elements — topbar, main area, and command bar — that never unmount. Screen transitions swap the contents of .main.

Screen routing

Screens are CSS-toggled: only one .screen has .active at a time. The topbar tabs call switchScreen(id), which removes .active from all screens and applies it to the target. No router, no URL changes — this is a single-page state machine.

3.1 Data Layer

The application is local-first, single-user. All data and the agent sandbox run locally via SQLite through a typed server layer. The client never reads or writes storage directly — it communicates through the RPC interface defined in §3.2.

Key convention from t3-code

Settings split into ClientSettings (local UI prefs — theme, density, sidebar width) and ServerSettings (data-authoritative — agent configs, data sources, export pipelines). Client settings are a JSON file on disk; server settings live in SQLite. Both use schema-validated decode with defaults so missing keys never crash the app.

3.2 RPC Surface v3

The client communicates with the server exclusively through typed RPC methods. Transport is IPC in Electron, HTTP in browser. Every method has a typed request and response shape; the server validates inputs and returns structured errors. There are no REST endpoints — all calls go through a single /rpc entry point with a method name and JSON payload.

Company & Portfolio

Workspace & Research

Financial Model

Memo

Agents

Export & Settings

Error contract

Every RPC error returns a structured object: { code: string, message: string, detail?: any }. Standard error codes: NOT_FOUND, VALIDATION_ERROR, AGENT_FAILED, CONFLICT (e.g. trying to start an already-running agent), RATE_LIMITED.

3.3 Real-time Transport v3

Agent streaming and live updates use Server-Sent Events (SSE) over a single persistent connection. SSE was chosen over WebSockets because: the transport is server-to-client dominant (agent output streaming), it works over HTTP without special proxying, and it reconnects automatically with a Last-Event-ID header.

Event channel

The client opens one SSE connection at startup: GET /events?companyId={id}. The server pushes typed events:

Connection lifecycle

• Connect: On app startup, after the first portfolio.get. URL includes active company ID.
• Reconnect: Browser auto-reconnects on drop. Server replays missed events via Last-Event-ID.
• Company switch: Client closes the SSE connection and opens a new one with the new companyId.
• Client → server: All client-to-server messages go through RPC (§3.2), not through SSE. SSE is receive-only.

Agent chat streaming

The agent.chat RPC method returns an SSE stream (not a JSON response). The server opens a new ephemeral SSE stream scoped to that chat session. The client renders agent.output events in the chat column as they arrive. The stream closes when the agent finishes its response.

3.4 State Shape

The state is split into server-authoritative data (SQLite) and client-only UI state (React/localStorage).

Server-authoritative state (SQLite)

interface AppState {
  portfolio: {
    id: string;
    name: string;
    holdings: Holding[];
  };
  activeCompanyId: string | null;
  companies: {
    [companyId: string]: {
      workspace: WorkspaceState;
      model: ModelState;
      memo: MemoState;
      agents: AgentRunState[];
    };
  };
  settings: ServerSettings;
  exports: ExportRecord[];
}

Client-only state (React / localStorage)

interface ClientState {
  activeScreen: 'home' | 'workspace' | 'model' | 'memo' | 'agents';
  navCollapsed: Record<string, boolean>;
  activeModelTab: string;
  memoReviewMode: boolean;
  agentFullscreenOpen: boolean;
  agentCarouselIndex: number;
  settingsOverlayOpen: boolean;
  settingsPanel: SettingsPanel;
  searchQuery: string;
  searchOpen: boolean;
  clientSettings: ClientSettings;
}

settingsPanel enum v3

type SettingsPanel =
  | 'agents'
  | 'data-sources'
  | 'export'
  | 'display'
  | 'keybindings'
  | 'advanced';

Six panels. The Keybindings panel (missing from prototype) lets the analyst remap every shortcut listed in §9.1. Each shortcut is stored as a key binding entry in ClientSettings.keybindings.

Company selection is the root pivot. Choosing a holding refreshes the entire workspace — thesis, model, memo, agents all rebind to the new company. The client queries the server for the selected company's data on switch.

3.5 Persistence & Versioning

• Autosave: Debounced server writes — 2s after last keystroke for memo text, immediate for toggles, settings changes, and annotation actions. No explicit save button.
• Snapshots: The server stores a diff snapshot every 5 minutes during active editing sessions. Named checkpoints available via ⌘S. Snapshots listed in Settings → Advanced → Version History with timestamp and optional label.
• Undo/redo: Standard ⌘Z / ⌘⇧Z within the current session. Undo stack is session-scoped (cleared on page reload). For cross-session rollback, use version history.

Version History UI v3

Settings → Advanced → Version History shows a timeline of snapshots:

Layout

Left column: scrollable list of snapshot entries (auto-saved + manual). Right column: diff preview of the selected snapshot vs. current state.

Snapshot entry

Timestamp (mono), optional label (editable), type badge ("Auto" muted, "Manual" accent), number of changes. Click to preview.

Diff preview

Side-by-side or unified diff view. Additions highlighted with --green background tint, deletions with --red background tint. Memo sections shown as prose diffs; model cells shown as value changes.

Actions

"Restore this version" (primary button, confirmation dialog), "Branch from here" (creates a new checkpoint from that state without discarding current), "Download snapshot" (JSON export).

3.6 First-Run Experience

No onboarding wizard, no modals, no video. The first-run experience is:

1. Empty portfolio with a single centered card: "Add your first company" — a search/typeahead that queries a company database.
2. Once added, the workspace opens with all research sections in "loading" state (skeleton).
3. A 3-step tooltip sequence highlights: Thesis → Model → Memo.
4. The first agent pipeline auto-queues (SEC Filings → Company Research → Financial Modeling).
5. The agent carousel in the command bar pulses to draw attention to the first running agent.

4. Screen Specifications

4.1 Home Dashboard

The home screen is the analyst's morning briefing. It answers three questions at a glance: How is my portfolio doing? What needs my attention today? What are my agents working on?

Layout

Full-width center column with two stacked zones:

1. Portfolio dashboard — a 3-column grid (holdings list | performance chart + metrics | sector treemap + factor tilt). The grid uses gap: 1px with background: var(--border) to create hairline separators between sections.
2. Home grid — a 2-column CSS grid below the portfolio area containing: Earnings Calendar, Watchlist Alerts, Recent Reports & Exports (spans full width), Pending Reviews, Agent Status.

Portfolio dashboard components

Holdings List

Scrollable list (max-height 320px) with columns: ticker badge, price, change (green/red), weight percentage, actions menu (⋯). Ticker badges use inverted colors (bg: var(--fg); color: var(--surface)). The ⋯ button opens a dropdown with: Open workspace, Run full research, Export report, Set as active, Remove from portfolio.

Performance Chart

SVG area chart with 6-month price line, grid lines, labeled time axis, and a summary metrics grid (Total Value, Day P&L, Holdings count, Beta, Sharpe, Max Drawdown).

Sector Treemap

Nested flex rows sized by weight. Each cell shows sector name, percentage, and dollar value against a tinted background. Colors are categorical, not semantic.

Factor Tilt

Horizontal bar chart comparing portfolio factor exposure vs. S&P 500. Positive exposures tinted green, negative tinted red. Six factors: Value, Size, Momentum, Quality, Low Vol, Market Beta.

Home grid cards

Earnings Calendar

Grouped by date with BMO/AMC timing tags. Compact row layout: ticker badge + quarter label + timing + countdown.

Watchlist Alerts

Event feed with thesis impact tags (Thesis +/Thesis −/Filing). Click-through to relevant screen.

Reports Library

Full-width card grid (repeat(auto-fill, minmax(200px, 1fr))). Each report thumb shows type label, title, and status metadata.

Pending Reviews

Items awaiting human review with comment counts and unverified assumption flags.

Agent Status

Compact list of active agents with progress percentages and current actions. Links to full Agents screen.

4.2 Company Workspace

The workspace is a read-only research hub for a single company. It aggregates all structured data, reports, and source materials in one scrollable column with a collapsible section navigation sidebar.

Left navigation

240px wide, collapsible to 36px. Organized into four groups with dividers:

1. Research — Company Snapshot, Business Description, Segment / Revenue Build, Margin Build, Historical Financials, Three-Statement Model, Key KPIs, Management & Strategy.
2. Analysis — Competitive Landscape, Peer Comparison, Valuation Analysis, Investment Thesis, Risks & Mitigants, Catalyst Tracker (§4.6).
3. Monitoring — Earnings Monitor (§4.9), Filing Watch (§4.10), Thesis Alerts (§4.7).
4. Library — Source Library, Export Center (§4.11).

Active section indicated by a 3px accent bar on the left edge. Group headers use uppercase monospace at 10px.

Center content structure

Header

Category eyebrow (monospace, uppercase, accent color) + company display name + one-line summary (founded, HQ, locations, employees). Followed by a metric grid (12 cells in a 4-column auto-fill layout).

Metric Grid

repeat(auto-fill, minmax(140px, 1fr)) with 1px gap. Each cell: uppercase label (mono), display-font value, optional sub-text. Used for market cap, EV, price, P/E, margins, revenue, etc.

Body Sections

H2 headings with top border divider. Prose paragraphs, data tables (spreadsheet class), and nested metric grids.

Reports Grid

Same card grid as home. Click-through to Memo or Model screens.

Source Materials

Stacked source cards showing type, title, metadata (pages, usage count). Types: SEC Filing, Earnings Transcript, Investor Presentation, Press Release.

4.3 Financial Model

The model screen is a spreadsheet-grade financial analysis environment. It presents tabular data with monospace numerics, explicit actual-vs-forecast distinction, and a tabbed navigation system for different model views.

Toolbar

Top toolbar with a <select> dropdown for model tabs: Revenue Build, Income Statement, Balance Sheet, Cash Flow Statement, Margin Build, Tax Build, LIFO/FIFO Conversion, Scenario Analysis, Charts. Right-aligned actions: Import Excel, AI Assist, Export to Excel.

Spreadsheet specification

Font

12px/1.4 var(--font-mono) for all cells. Headers: 10px uppercase mono.

Layout

Full-width table. First column is text-aligned left with font-weight 500. All other columns right-aligned. Minimum column width 200px for row labels.

Actuals vs Forecasts

Actual periods use default var(--fg). Forecast columns get class .forecast: color: var(--muted); font-style: italic.

Hierarchy

Indent rows (growth percentages) use .indent with padding-left: 24px. Total rows use .total with a 1px solid var(--fg) top border and bold weight.

Hover

Row background shifts to oklch(96% 0.008 80) on hover.

Sticky headers

Table headers (<th>) are position: sticky; top: 0 with background: var(--surface).

Model sub-tabs content

All model tabs share the same spreadsheet specification above (monospace, hairline borders, sticky headers, actual vs. forecast distinction). Content per tab:

4.4 Memo Editor

The memo screen is a structured writing environment for investment memos, IC memos, and research reports. It combines a content-editable center column with an outline sidebar and a review tools panel.

Three-column layout

Memo block structure

Each memo block (.memo-block) contains: an uppercase eyebrow in accent color, an H3 heading, body prose with inline citations (.citation — accent-colored mono brackets), and optional AI edit suggestions (yellow-tinted sidebar with Accept/Reject/Revise buttons).

Memo sections (8 total) v3

The memo outline includes these sections, all following the same .memo-block structure (eyebrow + H3 + body + citations). The prototype currently shows 4 sections (Thesis, Key Drivers, Variant Perception, Valuation). The remaining 4 sections — Business Quality, Financial Summary, Risks & Mitigants, Catalysts — should be added:

Review mode

Toggling "Review Mode" activates an annotation system with four tools:

1. Highlight — wraps selected text in .highlight-annotation with a tinted background and accent bottom border. Hover shows tooltip with reviewer comment.
2. Comment — same as highlight but prompts for a comment string stored in data-comment.
3. Strikethrough — applies text-decoration: line-through with red color at 60% opacity.
4. Draw Box — enters crosshair mode to draw a red bounding box with a "Review needed" label over any content area.

The annotation toolbar is positioned absolutely relative to the center column and appears at the selection position on mouseup.

Citations

Inline citations use numbered brackets linked to source cards in the right panel. Each source card shows: type (SEC Filing, Earnings Transcript, Analyst Report), title, page reference, and verification status (Verified / Unverified).

The memo editor is not a general-purpose rich text editor. It is a structured document with defined sections, each mapped to an outline entry. This constraint enables the AI agents to write, review, and iterate on specific sections independently.

4.5 Agent Orchestration

The agents screen is the control center for MosaicIQ's 14-agent research pipeline. It visualizes dependencies, progress, and real-time output across all agents.

Layout

Four stacked zones:

1. Toolbar — agent count, running/queued status indicators, Pause All and Run Full Research buttons.
2. Dependency tree — an SVG diagram showing the full agent pipeline with color-coded status. Two main pipelines (Research, Competitive & Risk) plus cross-cutting agents (Source Verification, Model QA, Monitoring, Export).
3. Agent grid — repeat(auto-fill, minmax(210px, 1fr)) tiles. Each tile shows: icon badge, agent name, role description, status dot + label, progress bar. Hover reveals action buttons (Pause, Inspect, Start, Configure). Clicking opens the detail panel.
4. Activity feed — a scrollable log of timestamped agent events. Each entry: time, agent name (accent color), message.

Agent detail panel

A 360px slide-in panel on the right showing: agent name + status header, current task description, upstream inputs (dependency tags), downstream outputs, execution log (timestamped entries), and action buttons (Pause, Restart, Full Screen).

Fullscreen overlay

Clicking "Full Screen" opens a fixed overlay with: tab bar for switching between running agents, a live output column (rendered agent output — tables, text, charts), and an execution trace column (numbered steps with labels and detail text). A chat input at the bottom allows sending interrupts or instructions to the active agent.

Command bar

Persistent across all screens. Left section: agent carousel showing the currently active agent with a pulsing dot, name, current action, and prev/next navigation (320px). Right section: chat prompt with > icon and ⌘K keyboard hint. Clicking the carousel opens the agent fullscreen overlay.

4.6 Catalyst Tracker

A workspace sub-section under "Analysis". Lists upcoming catalysts for the active company. Data comes from the Monitoring agent (mn) and is validated by Source Verification (sv).

Layout

Full-width table with columns:

HTML structure v3

<table class="spreadsheet">
  <thead>
    <tr>
      <th>Date</th>
      <th>Event</th>
      <th>Impact</th>
      <th>Thesis</th>
      <th>Source</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="mono">Jun 5, 2026</td>
      <td>Q3 FY25 Earnings</td>
      <td><span class="tag red">High</span></td>
      <td><span style="color:var(--green)">supports</span></td>
      <td><span class="citation">[4]</span></td>
    </tr>
    <!-- more rows -->
  </tbody>
</table>

4.7 Thesis Alerts

A workspace sub-section under "Monitoring" + a card on the home dashboard. Generated by the Monitoring agent (mn), triggered by: new filings, price moves exceeding threshold, earnings results vs. expectations, peer events.

Layout

Event feed with: timestamp, event type icon (filing, price move, earnings surprise), description, and impact assessment. Each alert has:

• A thesis impact tag: [Thesis +] (green), [Thesis −] (red), [Neutral] (muted)
• "Review" button → navigates to the relevant memo section or workspace section
• Status: New (accent) → Reviewed (muted) after analyst clicks

HTML structure v3

<div class="alert-feed">
  <div class="card-row">
    <span class="row-meta">2h ago</span>
    <span class="row-name">Q2 FY25 earnings beat (+7.5% comp)</span>
    <span class="tag green">Thesis +</span>
    <button class="btn sm">Review</button>
    <span class="tag accent">New</span>
  </div>
</div>

4.8 Risk Register

A workspace sub-section under "Analysis". Structured list of identified risks. Populated by the Risk agent (rk) and stress-tested by Red Team (rt). Analysts can add manual risk entries via risk.add RPC.

Layout

Sorted by severity × likelihood. Top risks surface in the memo's "Risks & Mitigants" section automatically.

HTML structure v3

<table class="spreadsheet">
  <thead>
    <tr>
      <th style="min-width:200px">Risk</th>
      <th>Category</th>
      <th>Severity</th>
      <th>Likelihood</th>
      <th>Mitigation</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Amazon enters warehouse club segment</td>
      <td><span class="tag">Competitive</span></td>
      <td><span class="tag red">High</span></td>
      <td><span class="tag">Low</span></td>
      <td style="color:var(--muted)">Costco's 93% renewal rate creates switching cost</td>
      <td><span class="tag">Open</span></td>
    </tr>
  </tbody>
</table>

4.9 Earnings Monitor

A workspace sub-section under "Monitoring" + the home dashboard calendar card. Beyond the calendar on home, the workspace section shows:

• Next 4 quarters with expected report dates
• Last 4 quarters with actual vs. expected results
• Consensus estimates grid (revenue, EPS, EBITDA)
• Post-earnings analysis links (if Earnings Call agent has run)

HTML structure v3

<div class="earnings-monitor">
  <!-- Two stacked grids -->
  <div class="metric-grid" style="grid-template-columns:repeat(auto-fill,minmax(160px,1fr))">
    <div class="metric-cell">
      <div class="label">Next Report</div>
      <div class="value">Jun 5, 2026</div>
      <div class="sub">Q3 FY25 · BMO</div>
    </div>
    <!-- more cells -->
  </div>
  <h2 class="section">Consensus Estimates</h2>
  <table class="spreadsheet">
    <thead><tr><th>Metric</th><th>Q2 FY25A</th><th>Q3 FY25E</th><th>FY25E</th></tr></thead>
    <tbody>
      <tr><td>Revenue</td><td>$62.5B</td><td class="forecast">$63.8B</td><td class="forecast">$242.3B</td></tr>
      <tr><td>EPS</td><td>$4.28</td><td class="forecast">$4.35</td><td class="forecast">$16.82</td></tr>
    </tbody>
  </table>
</div>

4.10 Filing Watch

A workspace sub-section under "Monitoring". Tracks new SEC filings for the active company. Real-time monitoring via the Monitoring agent (mn), which checks for new filings and queues the SEC Filings agent (sf) automatically.

Layout

Feed of filing cards. Each card: form type (10-K, 10-Q, 8-K, etc.) as a tag, filing date, title, key changes summary (produced by SEC Filings agent), and "Review" button → opens the filing in the Source Library with agent annotations.

HTML structure v3

<div class="filing-feed">
  <div class="source-card">
    <div class="src-type">10-K Annual Report</div>
    <div class="src-title">Annual Report FY2024</div>
    <div class="src-meta">Filed Oct 2024 </div>
    <div style="font-size:11px;color:var(--fg);margin-top:4px">
      Key changes: Updated segment reporting, new warehouse commitments ($2.1B)
    </div>
    <button class="btn sm" style="margin-top:6px">Review</button>
  </div>
</div>

4.11 Export Center

A workspace sub-section under "Library" + accessible from memo/model toolbars. Export is handled by the Export agent (ex).

Layout

Grid of export records. Each record: type icon, title, format tag (PDF/Excel/PPT), timestamp, file size, status (processing/complete/failed), "Download" action.

Trigger points

• Memo toolbar → "Export PDF"
• Model toolbar → "Export to Excel"
• Agent orchestration → "Export full report" (comprehensive package)
• Any screen → ⌘E keyboard shortcut opens an export quick-action menu

HTML structure v3

<div class="report-grid">
  <div class="report-thumb">
    <div class="rt-type">Excel</div>
    <div class="rt-title">COST Model — Revenue Build FY25–FY27</div>
    <div class="rt-meta">2.4 MB · Complete</div>
    <button class="btn sm" style="margin-top:6px">Download</button>
  </div>
</div>

5. Component Library

Topbar

Tags

All tags use font: 500 10px var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; padding: 3px 8px.

Buttons

Base spec: font: 500 12px var(--font-body); padding: 7px 14px; border-radius: 2px.

Source cards

border: 1px solid var(--border); padding: 10px 12px; background: var(--surface). Three rows: type (9px uppercase mono, accent color), title (12px body), meta (10.5px muted).

Report thumbs

border: 1px solid var(--border); background: var(--bg); padding: 14px. Hover → border-color: var(--muted). Three rows: type label (accent mono), title (bold body), metadata (muted).

Left navigation

240px wide (220px for memo variant). Collapsible to 36px via .collapsed class which hides all content except a 28px expand button. Transition: width 0.2s ease, opacity 0.2s ease. Active items: 3px accent bar on left edge, bold text. Group headers: 10px uppercase mono, muted.

Overlays

Full-screen overlays for Settings, Agent fullscreen, and Profile editor. Fixed position, z-index: 500 (600 for profile modal). Agent overlay includes a tab bar for switching between agents, with colored status dots.

Dropdown / select

Implementation note v3: The prototype currently uses native <select> elements as an interim solution. The custom dropdown above is the target implementation. Both approaches should produce visually consistent results — the custom dropdown adds keyboard navigation, type-ahead filtering, and full visual control.

Tooltips

Actions menu on holdings

The ⋯ button on each holding row opens a dropdown menu (same dropdown component spec as above):

Annotation components v3

These classes are used by the review mode annotation system (§4.4) and in app.js but were previously undocumented in the component library:

Focus ring (reusable pattern) v3

All interactive elements (buttons, links, inputs, nav items) must show a visible focus ring for keyboard navigation:

:focus-visible {
  outline: 2px solid var(--accent);
  outline-offset: 2px;
}
:focus:not(:focus-visible) {
  outline: none;
}

This ensures keyboard users see the ring while mouse clicks do not produce a visible outline. The ring uses the accent color at 2px with a 2px offset from the element boundary.

Shimmer animation (skeleton loading) v3

@keyframes shimmer {
  0%   { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

.skeleton {
  background: linear-gradient(
    90deg,
    oklch(92% 0.008 80) 25%,
    oklch(96% 0.008 80) 50%,
    oklch(92% 0.008 80) 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s ease-in-out infinite;
  border-radius: 2px;
}

[data-theme="dark"] .skeleton {
  background: linear-gradient(
    90deg,
    oklch(28% 0.01 80) 25%,
    oklch(22% 0.01 80) 50%,
    oklch(28% 0.01 80) 75%
  );
  background-size: 200% 100%;
}

6. Agent System

MosaicIQ's agent system is the primary content production pipeline. Agents ingest raw data (SEC filings, transcripts, market data), process it into structured outputs (financial models, company profiles, memos), and coordinate through a dependency graph. Critically, every agent is designed to feel like a collaborator — not a black box — surfacing its reasoning, flagging uncertainty, and deferring to the analyst at decision points.

Agent roster (14 agents)

Dependency graph

Agents execute in a directed acyclic graph with two main pipelines and a cross-cutting layer:

Agent states

6.1 Agents as Collaborators

The agent system is built around a core interaction principle: agents should feel like skilled co-analysts sitting across the desk. This means they do not just produce outputs — they explain their reasoning, highlight where confidence is low, and actively invite the analyst into the loop.

Collaboration behaviours

• Assumption surfacing. Every agent output includes a visible "Assumptions" section listing the key premises behind its analysis.
• Confidence signals. Agents annotate their findings with confidence levels (High / Medium / Low), displayed as inline pills next to the relevant data.
• Proactive questions. When an agent encounters ambiguity, it pauses and surfaces a question to the analyst via the command bar.
• Transparent reasoning traces. The fullscreen agent overlay shows a step-by-step execution log.
• Iterative handoff. Agents never present a final answer without offering a revision cycle.

Carousel

The command bar carousel cycles through active agents (array activeAgents). It shows: pulsing dot, agent name, current action text, and a counter (1 / 3). Navigation via prev/next arrows or clicking the strip opens the fullscreen overlay.

6.2 Agent Interaction Model

All agent interaction flows through the command bar and fullscreen chat mode. The agent state is always visually clear in the supporting UI — the analyst should never wonder which agent they're interacting with or which part of the workspace is affected.

Agent chat layout spec v3

The chat interface renders in two contexts: the command bar (compact, single-line) and the fullscreen overlay (expanded, multi-line). Both use the same component structure:

Agent alert in the command bar

When an agent needs input, the command bar shows a persistent ! alert. The ! icon replaces the pulsing dot and turns amber, the agent name and a truncated question appear inline, and a "Respond" button opens the fullscreen overlay.

Visual clarity: which agent is being impacted

1. Command bar carousel — always shows the active agent name + current action.
2. Agent grid tiles — the active/interacting agent gets a 2px accent border + subtle glow.
3. Workspace sections — each section has a small agent attribution badge: [cr · Company Research] in 9px mono, muted.
4. Fullscreen overlay — tab bar with status dots. Active tab has accent underline.
5. Section flash — when an agent needs input, the relevant workspace section gets a subtle accent left-border flash (1s pulse, twice).

Confidence signals UI

6.3 Agent Configuration Panel

Clicking "Configure" on an agent tile opens a slide-in panel (360px, same as agent detail panel) with:

Config panel layout v3

7. Research & Validation Cycle

MosaicIQ enforces a structured research → validate → iterate cycle across the entire agent pipeline. No output reaches the analyst's desk without passing through at least one validation checkpoint.

Cycle stages

1. Research. Agents gather data, build models, and draft analysis. Each agent marks its output with confidence levels and assumptions.
2. Cross-verification. Source Verification (sv) checks citations. Model QA (qa) audits formulas and sanity thresholds. Both return pass/fail reports.
3. Adversarial stress-test. Red Team (rt) challenges the research — building bear cases, stress-testing assumptions, surfacing contradictions.
4. Analyst checkpoint. Reviewed output presented with: verified (green ✓), flagged (amber ⚑), unverified (grey —). Analyst accepts, revises, or rejects.
5. Propagation. Approved sections propagate downstream. Upstream changes auto re-trigger affected agents.

7.1 Validation Flow Diagram v3

Validation states in the UI

Validation on actual content

• Workspace sections: Badge cluster in section header showing aggregate state: ✓ 3 passed, ⚑ 1 flagged.
• Model cells: Failed QA cells get a subtle red left-border with tooltip.
• Memo paragraphs: Inline validation follows the citation — [12] ✓ or [12] ⚑.
• Accept/Reject/Revise: Right-click context menu on validated elements.

The validation cycle is the reason MosaicIQ's agents can be trusted: they do not just work fast, they work checked.

8. Interactive States

Every data-bound surface in MosaicIQ has defined rendering modes for loading, empty, error, and success states.

8.1 Loading & Skeleton States

Every data-bound surface has three rendering modes:

Skeleton (first load)

Grey placeholder blocks matching the layout shape of the real content. Uses the .skeleton class with the shimmer animation defined in §5. Skeleton shapes per surface:

Stale (background refresh)

Existing content shown at opacity: 0.7 with a thin accent bar at the top of the panel. No skeleton overlay.

Live (loaded)

Normal rendering. No visual treatment.

8.2 Empty States

Centered flex column with an icon/illustration, a title, a one-line description, and an optional action button:

8.3 Error States

A bordered panel with semantic coloring and an icon. The error alert replaces the content area of the failed section (not the whole screen). Dismissible via × in the corner.

8.4 Toast & Notifications

Stacked toasts anchored top-right, below topbar (top: 56px). Typed variants: success, error, warning, info, loading.

Toast HTML structure v3

<div class="toast-container">
  <div class="toast toast-success">
    <div class="toast-icon">✓</div>
    <div class="toast-body">
      <div class="toast-title">SEC Filings Agent completed</div>
      <div class="toast-desc">COST 10-K analysis ready</div>
    </div>
    <button class="toast-action">View output</button>
    <button class="toast-dismiss">×</button>
  </div>
</div>

Toast CSS v3

.toast-container {
  position: fixed; top: 56px; right: 16px; z-index: 1000;
  display: flex; flex-direction: column; gap: 8px;
  max-width: 380px; pointer-events: none;
}
.toast {
  display: flex; align-items: flex-start; gap: 10px;
  background: var(--surface); border: 1px solid var(--border);
  padding: 12px 14px; border-radius: 2px;
  box-shadow: 0 4px 12px oklch(20% 0.02 60 / 0.08);
  pointer-events: auto; animation: toast-in 200ms ease-out;
}
.toast.toast-success { border-left: 3px solid var(--green); }
.toast.toast-error   { border-left: 3px solid var(--red); }
.toast.toast-warning  { border-left: 3px solid var(--accent); }
.toast.toast-info     { border-left: 3px solid var(--muted); }
.toast-icon {
  font-size: 13px; flex-shrink: 0; margin-top: 1px;
}
.toast-success .toast-icon { color: var(--green); }
.toast-error .toast-icon   { color: var(--red); }
.toast-warning .toast-icon { color: var(--accent); }
.toast-body { flex: 1; }
.toast-title { font: 500 12px/1.3 var(--font-body); }
.toast-desc { font-size: 11px; color: var(--muted); margin-top: 2px; }
.toast-action {
  font: 500 10px var(--font-mono); color: var(--accent);
  background: none; border: none; cursor: pointer;
  text-transform: uppercase; letter-spacing: 0.04em;
  white-space: nowrap; flex-shrink: 0;
}
.toast-dismiss {
  background: none; border: none; color: var(--muted);
  cursor: pointer; font-size: 14px; flex-shrink: 0;
  padding: 0; line-height: 1;
}
@keyframes toast-in {
  from { opacity: 0; transform: translateX(20px); }
  to   { opacity: 1; transform: translateX(0); }
}

Toast types in MosaicIQ

8.5 Search Behavior

The search bar searches across four categories: companies, reports, files, and commands.

1. Click search or press ⌘F → search input expands, dropdown appears
2. Results stream in grouped by category
3. Each result row: type icon, title, secondary text, keyboard shortcut if applicable
4. Arrow keys navigate, Enter selects, Escape closes
5. ⌘K opens agent chat — separate from search

9. Interaction Patterns

9.1 Keyboard Shortcuts

All shortcuts configurable in Settings → Keybindings. The Keybindings panel (one of six settings tabs) shows every shortcut in an editable table: action name, current binding, "Record new shortcut" button. Bindings stored in ClientSettings.keybindings.

9.2 Dark Mode

Dark mode inverts the lightness axis while keeping hue/chroma relationships identical. Toggle via Settings → Display → Theme.

:root[data-theme="dark"] {
  --bg:      oklch(15% 0.012 80);
  --surface: oklch(18% 0.008 80);
  --fg:      oklch(92% 0.008 80);
  --muted:   oklch(60% 0.01 80);
  --border:  oklch(28% 0.01 80);
  --accent:  oklch(65% 0.16 35);
  --green:   oklch(60% 0.12 145);
  --red:     oklch(60% 0.14 25);
}

Dark mode component handling v3

• Typography stacks: Unchanged.
• Skeleton shimmer: Uses inverted lighter shade (see shimmer animation in §5).
• Charts: Grid lines use var(--border) (automatically darker). SVG area fills adjust opacity: reduce from 0.1 to 0.15 for visibility.
• Treemap cells: Reduce saturation by ~20% in dark mode to avoid vibrating against the dark background. Add a data-theme selector to override cell colors.
• Inverted elements: Ticker badges (bg: var(--fg); color: var(--surface)) auto-adapt through token swap — no component-level override needed.
• Shadows: In dark mode, shadows should use oklch(0% 0 0 / 0.3) instead of oklch(20% 0.02 60 / 0.08) for the same perceived depth.
• Toast borders: The left-border accent colors remain the same — they already have sufficient contrast on dark surfaces.
• Highlight annotations: Adjust to background: oklch(28% 0.03 80) so the tinted highlight is visible on the dark bg.

9.3 Screen Transitions

Screen transition CSS v3

/* Screen switch — add to .screen */
.screen {
  transition: opacity 150ms ease-out;
  opacity: 0;
}
.screen.active {
  opacity: 1;
}

/* Right panel slide-in */
.right-panel {
  transform: translateX(100%);
  transition: transform 200ms ease-out;
}
.right-panel.open {
  transform: translateX(0);
}

/* Overlay */
.overlay {
  opacity: 0;
  transition: opacity 150ms ease-out;
}
.overlay .overlay-body {
  transform: scale(0.98);
  transition: transform 150ms ease-out;
}
.overlay.open {
  opacity: 1;
}
.overlay.open .overlay-body {
  transform: scale(1);
}

9.4 Accessibility

• All interactive elements have role, aria-label, and tabindex attributes
• Screen switches announce via aria-live="polite" region
• Agent status changes announced via aria-live="assertive" for failures, polite for completions
• Focus management: screen switches move focus to the main content area; overlay opens trap focus within the overlay
• Color contrast: all text meets WCAG AA
• Keyboard-only navigation: all actions accessible without a mouse. Focus ring pattern defined in §5.

9.5 Responsive Behavior

Responsive floor implementation v3

@media (max-width: 1023px) {
  body > *:not(.floor-message) { display: none !important; }
  body::before {
    content: '';
    display: block;
    position: fixed; top: 0; left: 0; right: 0; bottom: 0;
    background: var(--bg);
  }
  body::after {
    content: 'MosaicIQ requires a desktop display of 1024px or wider.';
    display: flex;
    position: fixed; top: 0; left: 0; right: 0; bottom: 0;
    align-items: center; justify-content: center;
    font: 400 16px/1.5 var(--font-body);
    color: var(--muted); text-align: center;
    padding: 40px;
  }
}

9.6 Data Density Settings

Settings → Display → Data Density offers three options: