# Agent Instructions

You are helping implement **MosaicIQ**, an AI-native equity research workspace.

Use the attached **MosaicIQ Design Document v3** as the primary reference for product intent, UX direction, architecture, screen specs, agent behavior, and implementation details. This file is intentionally light; the design doc contains the fuller guidance.

## Core Direction

Build a clean, fast, local-first equity research application with a **t3-code-style architecture**:

- Clear client/server boundary
- Typed RPC layer for all client/server communication
- Local-first persistence
- Simple, composable React components
- Minimal magic, strong types, predictable state
- Practical implementation over over-engineering

## Product Identity

The product name is **MosaicIQ**.

Do not use old/internal names like “Meridian” in user-facing UI unless the design doc explicitly says it is internal.

## Design Feel

Follow the design doc’s editorial research-workstation style:

- Serif display typography for headings
- Monospace for tickers, numbers, metadata, financial tables, and code-like labels
- Sans-serif for body/UI text
- Warm neutral palette with one restrained rust accent
- Hairline borders and whitespace instead of heavy cards, shadows, or gradients
- Dense but calm layout for analysts working on desktop screens

Keep the UI serious, analytical, and professional.

## Architecture Rules

Prefer the structure described in the design doc:

- Client never reads or writes storage directly
- Client talks to the server through typed RPC methods
- Server owns SQLite persistence, agent orchestration, file I/O, and export logic
- Client owns UI state such as active screen, panels, collapsed nav, search, and display preferences
- Use schema validation and safe defaults for settings
- Keep the path open for future remote/server deployment

## Agent Behavior

Agents should feel like collaborative research analysts, not black-box tools.

They should:

- Surface assumptions
- Cite or reference source material when possible
- Flag uncertainty
- Ask for clarification only when needed
- Support review, acceptance, rejection, and revision workflows
- Avoid pushing unvalidated conclusions directly into final outputs

Use the design doc’s agent system, validation loop, and screen guidance for details.

## Implementation Priorities

Start simple and build in layers:

1. App shell and navigation
2. Portfolio/company workspace
3. Financial model table UI
4. Memo editor
5. Agent orchestration UI
6. RPC/server persistence
7. Export flows
8. Validation/review loops

Do not try to implement everything at once. Favor small, working vertical slices.

## Coding Style

- Use TypeScript throughout
- Keep components small and readable
- Prefer explicit state and typed data contracts
- Avoid unnecessary abstractions
- Avoid large monolithic files
- Keep styling consistent with the design tokens in the design doc
- Make empty, loading, error, and disabled states feel intentional

## Dev Server

**NEVER start, stop, restart, or manage the app/dev server.** Do not run `npm run dev`, `pnpm dev`, `yarn dev`, `vite`, `vite preview`, Electron launch commands, or equivalent server/app-start commands.

The user runs the app independently. Your job is to write/edit code and run non-server verification commands such as typecheck, lint, tests, or production build when requested or appropriate.

Do not open or navigate a browser to the local app unless the user explicitly asks for browser inspection and confirms that they already have the app running.

## When Unsure

Refer back to the MosaicIQ Design Document v3. It contains additional helpful information on:

- Design tokens
- Screen specifications
- Component behavior
- RPC methods
- SSE events
- Data/state shape
- Persistence/versioning
- Agent workflows
- Export center
- Accessibility and keyboard shortcuts

Default to the design doc unless it conflicts with a newer explicit instruction.