jivamai 0.1.4-dev.edce8f4 → 0.2.0-dev.08fad0b

package/docs/architecture/ipc-contract.md

@@ -1,162 +0,0 @@
-# IPC Contract
-
-All communication between the renderer and the main process uses Electron's `ipcRenderer.invoke` / `ipcMain.handle` (request-response) or `ipcRenderer.on` / `webContents.send` (push events).
-
-The preload script (`electron/preload.ts`) exposes these as typed methods on `window.electron`. The full TypeScript interface is in `src/types/electron.d.ts`.
-
----
-
-## Setup
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `setup:check` | invoke | Pre-flight check: Node.js, jiva-core, config |
-
-**`setup:check` return:**
-```typescript
-{
-  nodejs:   { ok: boolean; version?: string }
-  jivaCore: { ok: boolean; version?: string }
-  config:   { ok: boolean; path: string }
-  platform: string   // 'win32' | 'darwin' | 'linux'
-}
-```
-
----
-
-## Jiva Server Lifecycle
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `jiva:server:start` | invoke | Initialize JivaRunner (load jiva-core, start DualAgent) |
-| `jiva:server:stop` | invoke | Cleanup agent and MCP servers |
-| `jiva:server:restart` | invoke | Stop then start |
-| `jiva:server:status` | invoke | Returns `{ status: ServerStatus; port: number }` |
-| `jiva:server:status-changed` | push | Renderer receives status updates from runner |
-| `jiva:phase-update` | push | Agent phase updates during inference (`thinking`, `calling-tool`, etc.) |
-
-**`ServerStatus`:** `'stopped' | 'starting' | 'running' | 'error'`
-
----
-
-## Chat / Messaging
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `jiva:send-message` | invoke | Send a prompt; returns full result when complete |
-| `jiva:reset-conversation` | invoke | Start a new conversation (clears agent memory) |
-| `jiva:load-conversation` | invoke | Load a saved conversation by ID into the agent |
-
-**`jiva:send-message` payload:** `(prompt: string, persona?: string)`
-**`jiva:send-message` return:** `{ success: boolean; result?: AgentResult; conversationId?: string; error?: string }`
-
----
-
-## Conversations
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `conversations:list` | invoke | List saved conversations from `~/.jiva/conversations/` |
-| `conversations:load` | invoke | Read a conversation JSON by ID |
-
-**`conversations:list` return:**
-```typescript
-Array<{
-  id: string
-  summary: string       // title from metadata, or first user message (truncated to 60 chars)
-  messageCount: number
-  lastModified: number  // ms timestamp
-}>
-```
-
----
-
-## Personas
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `personas:list` | invoke | List all persona directories from `~/.jiva/personas/` |
-| `personas:activate` | invoke | Activate a persona and switch the agent's context |
-| `personas:active` | invoke | Get the currently active persona name |
-
-**`personas:list` return:** `PersonaInfo[]` (see `electron/persona-manager.ts`)
-
----
-
-## Configuration
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `config:read` | invoke | Read `JivaConfig` from the platform-specific path |
-| `config:write` | invoke | Write `JivaConfig` to the platform-specific path |
-
-Config is read from / written to `getJivaConfigPath()` — see `electron/config-manager.ts`.
-
----
-
-## MCP Server Management
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `mcp:list-status` | invoke | List all MCP servers with runtime connection status |
-| `mcp:get-tools` | invoke | Get all tools exposed by connected MCP servers |
-| `mcp:add-server` | invoke | Add a new MCP server (stdio or HTTP) to config and runtime |
-| `mcp:remove-server` | invoke | Remove an MCP server from config and runtime |
-| `mcp:toggle-server` | invoke | Enable or disable an MCP server |
-| `mcp:reconnect-server` | invoke | Reconnect a specific MCP server |
-
-**`mcp:list-status` return item:**
-```typescript
-{
-  name: string
-  enabled: boolean
-  connected: boolean
-  toolCount: number
-  command: string        // stdio servers
-  args: string[]
-  env: Record<string, string>
-  url?: string           // HTTP servers
-  type: 'stdio' | 'http'
-  error?: string
-}
-```
-
----
-
-## Workspace / File Browser
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `workspace:get-dir` | invoke | Get the configured workspace directory |
-| `workspace:set-dir` | invoke | Set the workspace directory (persisted to config) |
-| `workspace:pick-dir` | invoke | Open native folder picker dialog |
-| `workspace:list-files` | invoke | List files in a directory (restricted to `$HOME`) |
-| `workspace:read-file` | invoke | Read a file's text content (max 500 KB) |
-| `workspace:open-external` | invoke | Reveal a file in the native file manager |
-
----
-
-## Window Controls
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `window:minimize` | invoke | Minimize the window |
-| `window:maximize` | invoke | Toggle maximize/restore |
-| `window:close` | invoke | Close the window |
-| `window:isMaximized` | invoke | Returns `boolean` |
-
----
-
-## System / Native Events
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `native-theme-changed` | push | System light/dark mode changed; payload: `isDark: boolean` |
-
----
-
-## Notes
-
-- All invoke handlers return `{ success: boolean; error?: string }` on failure unless otherwise specified.
-- Push events use `ipcRenderer.on` in the preload and are exposed as `onXxx(callback)` methods on `window.electron`.
-- The `persona` parameter on `jiva:send-message` is accepted but intentionally ignored to avoid destroying conversation history mid-chat. Use `personas:activate` for explicit persona switches.

package/docs/architecture/jiva-core-integration.md

@@ -1,147 +0,0 @@
-# jiva-core Integration
-
-Jivam does not bundle jiva-core. It dynamically loads the globally installed npm package at runtime. This means:
-
-- Users must have `npm install -g jiva-core` before Jivam can start
-- Updating jiva-core globally is sufficient — no Jivam rebuild needed
-- The integration layer is entirely in `electron/jiva-runner.ts`
-
----
-
-## Runtime Resolution
-
-### `augmentPath()`
-
-In a packaged Electron app, the OS launches the process with a minimal PATH that often excludes npm's global bin directory. `augmentPath()` fixes this by spawning the user's login shell:
-
-```typescript
-const loginPath = execSync(`${shell} -l -c 'echo $PATH'`).toString().trim()
-process.env.PATH = loginPath
-```
-
-This runs before any `execSync` or `import()` calls that depend on npm being on PATH.
-
-### `resolveJivaCoreEntryPath()`
-
-Finds the jiva-core ESM entry point:
-
-1. `npm root -g` → e.g. `/usr/local/lib/node_modules` → checks for `jiva-core/package.json`
-2. Fallback: `~/.npm-global/lib/node_modules/jiva-core/package.json` (common Linux setup)
-3. Fallback: `./node_modules/jiva-core/package.json` (development / local install)
-
-Reads `package.json` → follows the `"exports"` or `"main"` field to get the entry file path.
-
-### Dynamic ESM Import
-
-```typescript
-const { DualAgent, ConversationManager, MCPServerManager } = await import(entryPath)
-```
-
-This is a true ESM dynamic import — no CommonJS `require()`. jiva-core is an ESM-only package.
-
----
-
-## Configuration
-
-Config is read via `readConfig()` in `electron/config-manager.ts`, which reads from `getJivaConfigPath()` — the platform-specific location where jiva-core stores its `config.json`.
-
-The config shape relevant to jiva-core:
-
-```typescript
-{
-  models: {
-    reasoning: {
-      provider?: string     // e.g. 'anthropic', 'openai'
-      apiKey?: string
-      endpoint?: string
-      model?: string
-      useHarmonyFormat?: boolean
-    }
-  }
-  mcpServers?: Record<string, MCPServerConfig>
-  workspaceDir?: string
-}
-```
-
----
-
-## DualAgent
-
-`DualAgent` is jiva-core's primary agent class. JivaRunner wraps it:
-
-| JivaRunner method | DualAgent call | Notes |
-|-------------------|----------------|-------|
-| `initialize()` | `new DualAgent(config)` | Constructs with model config, persona, directive |
-| `chat(prompt, onPhase)` | `agent.chat(prompt)` | Streams phase events via callback |
-| `resetConversation()` | `agent.resetConversation()` | Clears in-memory conversation state |
-| `loadConversation(id)` | `agent.loadConversation(id)` | Loads from `~/.jiva/conversations/<id>.json` |
-| `saveConversation()` | `agent.saveConversation()` | Saves to `~/.jiva/conversations/` |
-| `switchPersona(name)` | `agent.cleanup()` + `new DualAgent(...)` | Full re-init with new persona dir |
-| `cleanup()` | `agent.cleanup()` | Closes MCP connections, frees resources |
-
----
-
-## Directive Injection
-
-Before each agent initialization, `electron/directive-manager.ts` writes a directive file to `~/.jiva/jiva-directive.md`. This file contains:
-
-- Today's date (so the agent always knows the current date)
-- Any custom user instructions configured for the active persona
-
-jiva-core reads this file as a system-level context injection, so the directive takes effect on every conversation without needing to be in the message history.
-
----
-
-## Persona System
-
-Personas live in `~/.jiva/personas/<name>/`. Each persona directory may contain:
-
-- `.jiva-plugin/plugin.json` — manifest with `name`, `description`, `tags`
-- `CLAUDE.md` or `SKILL.md` — persona instructions read by jiva-core
-- Custom tools, skills, or resource files
-
-`electron/persona-manager.ts` handles:
-- `listPersonas()` — scans `~/.jiva/personas/`, reads manifests, returns `PersonaInfo[]`
-- `activatePersona(name)` — writes `~/.jiva/active-persona.txt` (fallback if CLI unavailable)
-- `getActivePersona()` — reads from config's `activePersona` field, falls back to `active-persona.txt`
-
----
-
-## MCP Server Management
-
-MCP (Model Context Protocol) servers extend the agent with external tools. They are configured in `config.mcpServers`:
-
-**Stdio server** (local process):
-```json
-{
-  "myServer": {
-    "command": "node",
-    "args": ["/path/to/server.js"],
-    "env": { "API_KEY": "..." },
-    "enabled": true
-  }
-}
-```
-
-**HTTP server** (remote):
-```json
-{
-  "remoteServer": {
-    "url": "http://localhost:8080/mcp",
-    "enabled": true
-  }
-}
-```
-
-`MCPServerManager` (jiva-core) manages connections. JivaRunner exposes these live operations:
-
-| Method | Description |
-|--------|-------------|
-| `getMCPServerStatus()` | Current connection state + tool count for each server |
-| `getMCPTools()` | All tools grouped by server name |
-| `addMCPServer(name, config)` | Add and connect a new server at runtime |
-| `removeMCPServer(name)` | Disconnect and remove a server at runtime |
-| `toggleMCPServer(name, enabled)` | Enable/disable without removing |
-| `reconnectMCPServer(name)` | Force reconnect a failed server |
-
-Config changes are written to disk immediately via `writeConfig()` so they persist across restarts.

package/docs/architecture/overview.md

@@ -1,87 +0,0 @@
-# Architecture Overview
-
-## Three-Process Model
-
-Electron enforces strict process separation. Jivam uses all three Electron processes:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Main Process  (Node.js)                                    │
-│  electron/main.ts                                           │
-│  · Creates BrowserWindow                                    │
-│  · Loads jiva-core via dynamic import                       │
-│  · Registers IPC handlers (ipc-handlers.ts)                 │
-│  · Manages JivaRunner lifecycle                             │
-└──────────────────────┬──────────────────────────────────────┘
-                       │  contextBridge (context isolation ON)
-┌──────────────────────▼──────────────────────────────────────┐
-│  Preload Script  (Node.js, sandboxed)                       │
-│  electron/preload.ts                                        │
-│  · Exposes window.electron API to renderer                  │
-│  · Wraps ipcRenderer.invoke / ipcRenderer.on               │
-└──────────────────────┬──────────────────────────────────────┘
-                       │  window.electron.*
-┌──────────────────────▼──────────────────────────────────────┐
-│  Renderer Process  (Chromium, no Node access)               │
-│  src/  (React + TypeScript + Vite)                          │
-│  · All UI components and Zustand stores                     │
-│  · Calls window.electron.* for all system operations        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-Context isolation is **enabled** — the renderer has no direct Node.js or Electron API access. All privileged operations go through the preload bridge.
-
----
-
-## Key Directories
-
-| Directory | Process | Purpose |
-|-----------|---------|---------|
-| `electron/` | Main | IPC handlers, jiva-core runner, config, persona, directive managers |
-| `src/` | Renderer | React components, Zustand stores, types |
-| `src/components/` | Renderer | UI component tree |
-| `src/store/` | Renderer | Zustand state stores |
-| `src/types/` | Shared | TypeScript interfaces including `ElectronAPI` |
-
----
-
-## Data Persistence
-
-| Data | Location | Manager |
-|------|----------|---------|
-| AI model config / API keys | Platform-specific (see below) | `electron/config-manager.ts` |
-| Conversations | `~/.jiva/conversations/*.json` | jiva-core's ConversationManager |
-| Personas | `~/.jiva/personas/<name>/` | `electron/persona-manager.ts` |
-| Active persona | `~/.jiva/active-persona.txt` | `electron/persona-manager.ts` |
-| Directive | `~/.jiva/jiva-directive.md` | `electron/directive-manager.ts` |
-| Workspace dir preference | Inside config.json | `electron/config-manager.ts` |
-| UI preferences (theme) | `localStorage` | `src/store/settings.store.ts` |
-
-### Platform-Specific Config Paths
-
-jiva-core stores `config.json` at OS-appropriate locations, **not** `~/.jiva/config.json`. `getJivaConfigPath()` in `electron/config-manager.ts` returns the correct path:
-
-| Platform | Path |
-|----------|------|
-| Windows | `%APPDATA%\jiva-nodejs\Config\config.json` |
-| macOS | `~/Library/Preferences/jiva-nodejs/config.json` |
-| Linux | `$XDG_CONFIG_HOME/jiva-nodejs/config.json` (default: `~/.config/jiva-nodejs/config.json`) |
-
----
-
-## Build System
-
-| Tool | Role |
-|------|------|
-| `vite` | Bundles the renderer (React app) |
-| `vite-plugin-electron` | Co-builds main + preload alongside renderer |
-| `electron-builder` | Packages the app for distribution |
-| `build.sh` | Wrapper script: cleans, builds, packages all platforms |
-
-**Packaging targets:**
-
-| Platform | Formats |
-|----------|---------|
-| macOS | DMG (installer) + ZIP (portable) |
-| Windows | NSIS installer + portable EXE |
-| Linux | AppImage + `.deb` |

package/docs/architecture/startup-flow.md

@@ -1,108 +0,0 @@
-# Startup Flow
-
-This document traces the full boot sequence from process launch to a fully interactive UI.
-
----
-
-## Phase 1 — Electron Main Process Starts
-
-**File:** `electron/main.ts`
-
-1. Electron creates the `BrowserWindow` with `contextIsolation: true` and `nodeIntegration: false`.
-2. The preload script (`electron/preload.ts`) is loaded into the window context.
-3. The window loads the renderer: dev server URL in development, `dist/index.html` in production.
-4. `setupIpcHandlers(jivaRunner, getWindow)` is called, registering all `ipcMain.handle()` listeners.
-5. `JivaRunner` instance is created but **not yet initialized** — it waits for the renderer to request it.
-
----
-
-## Phase 2 — Renderer Mounts, Pre-flight Check
-
-**File:** `src/App.tsx`
-
-1. React mounts. `setupDone` state is initialized to `null` (pre-flight in progress).
-2. `window.electron.setup.check()` is invoked — this calls `setup:check` IPC.
-
-**Main process handles `setup:check`** (`electron/ipc-handlers.ts`):
-
-- Runs `npm --version` (ok flag) + `node --version` (display version)
-- Checks `npm root -g` for `jiva-core/package.json`
-- Checks `getJivaConfigPath()` for a config file with a non-empty `apiKey`
-- Returns `{ nodejs, jivaCore, config, platform }`
-
-3. If all three checks pass → `setupDone = true` → proceed to Phase 3.
-4. If any fail → `setupDone = false` → `<SetupScreen>` renders with the check results.
-   - SetupScreen auto-polls every 3 seconds until all checks pass.
-   - User can configure the AI model in-app via the Settings overlay.
-   - Once all pass, user clicks "Continue" → `setupDone = true`.
-
----
-
-## Phase 3 — Jiva Agent Initialization
-
-**File:** `src/store/jiva.store.ts` → `startServer()` → `window.electron.jiva.server.start()`
-
-**Main process handles `jiva:server:start`** (`electron/ipc-handlers.ts`):
-
-1. Calls `jivaRunner.initialize()`.
-
-**`JivaRunner.initialize()`** (`electron/jiva-runner.ts`):
-
-1. `augmentPath()` — spawns `$SHELL -l -c 'echo $PATH'` to capture the login shell's PATH (needed in packaged apps where the process PATH is minimal).
-2. `resolveJivaCoreEntryPath()` — runs `npm root -g` to locate the global `jiva-core` install. Falls back to `~/.npm-global` and local `node_modules`.
-3. Dynamic ESM import: `const { DualAgent, ConversationManager, MCPServerManager } = await import(entryPath)`
-4. Reads config via `readConfig()` → `getJivaConfigPath()`.
-5. `directive-manager.ts` writes a date-aware `~/.jiva/jiva-directive.md` (injected as system context).
-6. `persona-manager.ts` resolves the active persona directory.
-7. `DualAgent` is constructed with the config, persona, directive, and MCP server config.
-8. MCP servers from `config.mcpServers` are started via `MCPServerManager`.
-9. Runner emits `status-changed: 'ready'`.
-
----
-
-## Phase 4 — Status Events and UI Ready
-
-**File:** `electron/ipc-handlers.ts`
-
-The runner's `status-changed` event is forwarded to the renderer via `win.webContents.send('jiva:server:status-changed', ...)`.
-
-**File:** `src/store/jiva.store.ts`
-
-`initPhaseListener()` registers `window.electron.jiva.onStatusChange()` and `window.electron.jiva.onPhaseUpdate()`. Status updates flow:
-
-```
-JivaRunner emits 'status-changed'
-  → ipcMain forwards to renderer
-  → jiva.store sets serverStatus
-  → App.tsx reacts: setShowSplash(false)
-  → AppShell renders
-```
-
----
-
-## Phase 5 — App Shell Renders
-
-**File:** `src/components/layout/AppShell.tsx`
-
-- `loadPersonas()` is called from `App.tsx` once `showSplash` clears.
-- `AppShell` renders the sidebar, topbar, and active tab panel.
-- The user can now chat, switch personas, browse conversations, manage MCP servers, and browse files.
-
----
-
-## Sequence Summary
-
-```
-main.ts                    → BrowserWindow, setupIpcHandlers
-  preload.ts               → window.electron exposed
-    App.tsx mounts         → setup:check IPC
-      [SetupScreen if needed]
-      setupDone = true
-        jiva:server:start  → JivaRunner.initialize()
-          augmentPath → resolveJivaCoreEntryPath → import(jiva-core)
-          DualAgent created, MCP servers started
-          status-changed: 'ready'
-        showSplash = false
-          AppShell renders
-          loadPersonas()
-```

package/docs/architecture/state-management.md

@@ -1,153 +0,0 @@
-# State Management
-
-Jivam uses [Zustand](https://github.com/pmndrs/zustand) for all renderer-side state. There are six stores, each with a single responsibility.
-
----
-
-## Data Flow Pattern
-
-```
-User action
-  → Component calls store action
-    → Store action calls window.electron.*  (IPC invoke)
-      → Main process handler executes
-        → Returns result
-          → Store updates state
-            → Component re-renders
-```
-
-Push events (server status, phase updates) follow the reverse path: main process sends via `webContents.send` → preload forwards via `ipcRenderer.on` → store listener updates state.
-
----
-
-## Stores
-
-### `useJivaStore` — `src/store/jiva.store.ts`
-
-Manages the jiva-core agent lifecycle and runtime state.
-
-| State | Type | Description |
-|-------|------|-------------|
-| `serverStatus` | `'stopped' \| 'starting' \| 'running' \| 'error'` | Current agent status |
-| `currentPhase` | `string \| null` | Agent's current reasoning phase |
-| `isInitializing` | `boolean` | True while `startServer()` is in progress |
-
-| Action | Description |
-|--------|-------------|
-| `startServer()` | Invokes `jiva:server:start`, transitions status through `starting → running` |
-| `stopServer()` | Invokes `jiva:server:stop` |
-| `restartServer()` | Invokes `jiva:server:restart` |
-| `setServerStatus(status)` | Direct status setter (used by push event listener) |
-| `initPhaseListener()` | Registers listeners for `jiva:server:status-changed` and `jiva:phase-update` push events |
-
----
-
-### `useChatStore` — `src/store/chat.store.ts`
-
-Manages the chat message history and streaming state for the active session.
-
-| State | Type | Description |
-|-------|------|-------------|
-| `messages` | `ChatMessage[]` | Array of user and assistant messages |
-| `isStreaming` | `boolean` | True while awaiting agent response |
-| `streamError` | `string \| null` | Error from the last failed send |
-
-| Action | Description |
-|--------|-------------|
-| `sendMessage(prompt, persona?)` | Appends user message, invokes `jiva:send-message`, appends assistant response |
-| `clearMessages()` | Clears the message array (used when starting a new conversation) |
-| `setMessages(messages)` | Bulk-replaces messages (used when loading a saved conversation) |
-
-**`ChatMessage` shape:**
-```typescript
-{
-  id: string
-  role: 'user' | 'assistant'
-  content: string
-  timestamp: number
-  phase?: string       // reasoning phase tag, shown on assistant messages
-}
-```
-
----
-
-### `useConversationStore` — `src/store/conversation.store.ts`
-
-Manages the conversation list in the sidebar and the active conversation ID.
-
-| State | Type | Description |
-|-------|------|-------------|
-| `conversations` | `ConversationSummary[]` | Sidebar list, sorted newest-first |
-| `activeId` | `string \| null` | ID of the currently loaded conversation |
-| `isLoading` | `boolean` | True while fetching the list |
-
-| Action | Description |
-|--------|-------------|
-| `loadConversations()` | Invokes `conversations:list`, populates `conversations` |
-| `selectConversation(id)` | Invokes `conversations:load` + `jiva:load-conversation`, sets `activeId`, loads messages into `useChatStore` |
-| `newConversation()` | Invokes `jiva:reset-conversation`, clears messages, sets `activeId = null` |
-| `refreshConversations()` | Re-fetches the list (called after a chat completes to capture new titles) |
-
----
-
-### `usePersonaStore` — `src/store/persona.store.ts`
-
-Manages the persona list and active persona.
-
-| State | Type | Description |
-|-------|------|-------------|
-| `personas` | `PersonaInfo[]` | All discovered personas from `~/.jiva/personas/` |
-| `activePersona` | `string \| null` | Name of the currently active persona |
-| `isLoading` | `boolean` | True while fetching |
-
-| Action | Description |
-|--------|-------------|
-| `loadPersonas()` | Invokes `personas:list` and `personas:active`, populates state |
-| `activatePersona(name)` | Invokes `personas:activate`, updates `activePersona` |
-
----
-
-### `useSettingsStore` — `src/store/settings.store.ts`
-
-Manages UI preferences. Persisted to `localStorage` via Zustand's `persist` middleware.
-
-| State | Type | Description |
-|-------|------|-------------|
-| `theme` | `'light' \| 'dark' \| 'system'` | Active color theme |
-| `modelConfig` | `ModelConfig \| null` | Cached model configuration for the Settings UI |
-
-| Action | Description |
-|--------|-------------|
-| `setTheme(theme)` | Updates theme, persisted automatically |
-| `loadModelConfig()` | Invokes `config:read`, populates `modelConfig` |
-| `saveModelConfig(config)` | Invokes `config:write` with the updated config |
-
----
-
-### `useFilesStore` — `src/store/files.store.ts`
-
-Manages the workspace file browser state.
-
-| State | Type | Description |
-|-------|------|-------------|
-| `workspaceDir` | `string` | Current workspace root directory |
-| `entries` | `FileEntry[]` | Files and subdirectories in the current directory |
-| `selectedFile` | `FileEntry \| null` | File currently open in the preview panel |
-| `fileContent` | `string \| null` | Text content of the selected file |
-| `isLoading` | `boolean` | True while listing or reading |
-
-| Action | Description |
-|--------|-------------|
-| `loadWorkspaceDir()` | Invokes `workspace:get-dir`, sets `workspaceDir` |
-| `listFiles(dirPath)` | Invokes `workspace:list-files`, populates `entries` |
-| `selectFile(entry)` | Invokes `workspace:read-file`, sets `selectedFile` and `fileContent` |
-| `pickDirectory()` | Invokes `workspace:pick-dir` (native dialog), then `workspace:set-dir` |
-| `openExternal(path)` | Invokes `workspace:open-external` to reveal file in native file manager |
-
----
-
-## Store Composition Rules
-
-- Stores are independent — no cross-store imports. Components compose multiple stores.
-- `useChatStore` and `useConversationStore` are coupled by convention: `selectConversation()` in the conversation store calls `setMessages()` on the chat store internally via the `window.electron` conversation load.
-- `useSettingsStore` is the only store with persistence (localStorage). All others are session-only.