# MosaicIQ - Claude Code Instructions

This is the primary instruction file for Claude Code working on the MosaicIQ project.

## Quick Start

**Required:**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
# or another supported provider:
# export OPENAI_API_KEY=sk-...
# export DEEPSEEK_API_KEY=...
# export GOOGLE_API_KEY=...
# export ZAI_API_KEY=...
```

See **[agent.md](./agent.md)** for complete project documentation, including:
- Full LLM Client Reference with all Pi API functions
- Monorepo structure and key files
- Agent behavior guidelines
- Implementation priorities
- Coding style and architecture rules

## Project Overview

**MosaicIQ** is an AI-native equity research workspace built as a local-first desktop application.

- **Stack**: TypeScript, React, Electron, SQLite
- **Architecture**: t3-code-style with typed RPC layer
- **LLM**: Pi API (Inflection AI) for all AI operations
- **Monorepo**: PNPM workspace with apps (desktop, web) and shared packages

## Dev Server Rules

**NEVER start, stop, restart, or manage the dev server.** The user runs the app independently. Your job is to write/edit code and run verification commands (typecheck, lint, tests, build).

## File Structure

```
local_research_app/
├── apps/
│   ├── desktop/      # Electron main (RPC server, file I/O, DB, agents)
│   └── web/          # React UI (client)
├── packages/
│   ├── contracts/    # Shared TypeScript types
│   └── shared/       # Shared utilities, LLM client, agents, DB, export
├── agent.md          # Complete project documentation
└── CLAUDE.md         # This file
```

## Key Links

| Topic | File |
|-------|------|
| Full Documentation | [agent.md](./agent.md) |
| LLM Client Reference | [agent.md # LLM Client Reference](./agent.md#llm-client-reference) |
| Architecture | [docs/architecture.md](./docs/architecture.md) |
| RPC Contracts | [`packages/contracts/src/rpc.ts`](./packages/contracts/src/rpc.ts) |
| LLM Client | [`packages/shared/src/llm/piSdk.ts`](./packages/shared/src/llm/piSdk.ts) |

## Coding Style

- TypeScript throughout
- Small, readable components
- Explicit state and typed contracts
- No unnecessary abstractions
- Follow design tokens from design doc
- Intentional empty/loading/error states

## When Unsure

Default to **[agent.md](./agent.md)** or the MosaicIQ Design Document v3 (attached separately).