AI-Studio/AGENTS.md

# AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Incremental implementation workflow

When the developer asks to implement a plan step by step, complete exactly one coherent plan item at
a time. After each item:

1. Run the relevant Rider or RustRover build through MCP and perform any other appropriate checks.
2. Summarize the diff and any remaining problems.
3. Suggest a short, concise commit title in US English.
4. Stop and wait until the developer has reviewed and committed the changes before continuing.
5. Never push the changes; the developer performs all pushes.

## Project Overview

MindWork AI Studio is a cross-platform desktop application for interacting with Large Language Models (LLMs). The app uses a hybrid architecture combining a Rust Tauri runtime (for the native desktop shell) with a .NET Blazor Server web application (for the UI and business logic).

**Key Architecture Points:**
- **Runtime:** Rust-based Tauri v2 application providing the native window, system integration, and IPC layer
- **App:** .NET 9 Blazor Server application providing the UI and core functionality
- **Communication:** The Rust runtime and .NET app communicate via HTTPS with TLS certificates generated at startup
- **Providers:** Multi-provider architecture supporting OpenAI, Anthropic, Google, Mistral, Perplexity, self-hosted models, and others
- **Plugin System:** Lua-based plugin system for language packs, configuration, and future assistant plugins

## Building

### Prerequisites
- .NET 9 SDK
- Rust toolchain (stable)
- Tauri v2 CLI
- Tauri prerequisites (platform-specific dependencies)
- **Note:** Development on Linux is discouraged due to complex Tauri dependencies that vary by distribution

### Build
```bash
cd app/Build
dotnet run build
```
This builds the .NET app as a Tauri "sidecar" binary, which is required even for development.

### Running builds from an agent
Agents must not start builds through their own shell: agent shells run sandboxed, and `.NET` builds
hit a known sandbox issue there, typically surfacing as `CSSM_ModuleLoad()` or other sandbox-related
failures (for reference: https://github.com/openai/codex/issues/4915). This applies to `dotnet run build`,
`dotnet build`, `cargo build`, and similar commands.

Instead, use the JetBrains IDE MCP servers. They execute in the IDE process, which runs outside the
agent sandbox:

- `rider` for the .NET solution at `app/MindWork AI Studio.sln`
- `rustrover` for the Rust runtime at `runtime/`

Pass the `rootFolder` parameter on every call, e.g. the absolute path of the `app` directory for Rider
and of `runtime` for RustRover. It avoids ambiguous calls when several IDE windows are open.

**Compile check of the .NET code:** start `mcp__rider__build_solution_start`, then poll
`mcp__rider__build_solution_state` until its state is `Completed` and read `buildIsSuccess` plus the
collected problems. `mcp__rider__get_project_problems` reports the current Problems View without
triggering a new build.

**Build script commands** such as the canonical build or the I18N collection run through the IDE
terminal, because they are more than a solution build:

```
mcp__rider__execute_terminal_command  command: "cd app/Build && dotnet run build"
mcp__rider__execute_terminal_command  command: "cd app/Build && dotnet run collect-i18n"
```

**Rust builds** work the same way through the matching `rustrover` tools.

Notes:
- The IDE may ask the user to confirm a terminal command. Wait for the result instead of retrying the
  command in the agent shell.
- When the IDE is not running or its MCP server is unavailable, fall back to asking the user to run
  `cd app/Build && dotnet run build` locally, and wait for their feedback before diagnosing issues or
  making follow-up changes.
- Treat the build output, error messages, or success confirmation as the source of truth for further
  troubleshooting, no matter whether it came from the MCP server or from the user.

### Running Tests
Currently, no automated test suite exists in the repository.

## Architecture Details

### Rust Runtime (`runtime/`)
**Entry point:** `runtime/src/main.rs`

Key modules:
- `app_window.rs` - Tauri window management, updater integration
- `dotnet.rs` - Launches and manages the .NET sidecar process
- `runtime_api.rs` - Axum-based HTTPS API for .NET ↔ Rust communication
- `certificate.rs` - Generates self-signed TLS certificates for secure IPC
- `secret.rs` - Secure secret storage using OS keyring (Keychain/Credential Manager)
- `clipboard.rs` - Cross-platform clipboard operations
- `file_data.rs` - File processing for RAG (extracts text from PDF, DOCX, XLSX, PPTX, etc.)
- `encryption.rs` - AES-256-CBC encryption for sensitive data
- `pandoc.rs` - Integration with Pandoc for document conversion
- `log.rs` - Logging infrastructure using `flexi_logger`

### .NET App (`app/MindWork AI Studio/`)
**Entry point:** `app/MindWork AI Studio/Program.cs`

Key structure:
- **Program.cs** - Bootstraps Blazor Server, configures Kestrel, initializes encryption and Rust service
- **Provider/** - LLM provider implementations (OpenAI, Anthropic, Google, Mistral, etc.)
  - `BaseProvider.cs` - Abstract base for all providers with streaming support
  - `IProvider.cs` - Provider interface defining capabilities and streaming methods
- **Chat/** - Chat functionality and message handling
- **Assistants/** - Pre-configured assistants (translation, summarization, coding, etc.)
  - `AssistantBase.razor` - Base component for all assistants
- **Agents/** - contains all agents, e.g., for data source selection, context validation, etc.
  - `AgentDataSourceSelection.cs` - Selects appropriate data sources for queries
  - `AgentRetrievalContextValidation.cs` - Validates retrieved context relevance
- **Tools/PluginSystem/** - Lua-based plugin system
- **Tools/Services/** - Core background services (settings, message bus, data sources, updates)
- **Tools/Rust/** - .NET wrapper for Rust API calls
- **Settings/** - Application settings and data models
- **Components/** - Reusable Blazor components
- **Pages/** - Top-level page components

### IPC Communication Flow
1. Rust runtime starts and generates TLS certificate
2. Rust starts internal HTTPS API on random port
3. Rust launches .NET sidecar, passing: API port, certificate fingerprint, API token, secret key
4. .NET reads environment variables and establishes secure HTTPS connection to Rust
5. .NET requests an app port from Rust, starts Blazor Server on that port
6. Rust opens Tauri webview pointing to localhost:app_port
7. Bi-directional communication: .NET ↔ Rust via HTTPS API

### Configuration and Metadata
- `metadata.txt` - Build metadata (version, build time, component versions) read by both Rust and .NET
- `startup.env` - Development environment variables (generated by build script)
- `.NET project` reads metadata.txt at build time and injects as assembly attributes

## Plugin System

**Location:** `app/MindWork AI Studio/Plugins/`

Plugins are written in Lua and provide:
- **Language plugins** - I18N translations (e.g., German language pack)
- **Configuration plugins** - Enterprise IT configurations for centrally managed providers, settings
- **Future:** Assistant plugins for custom assistants

**Example configuration plugin:** `app/MindWork AI Studio/Plugins/configuration/plugin.lua`

Plugins can configure:
- Self-hosted LLM providers
- Update behavior
- Preview features visibility
- Preselected profiles
- Chat templates
- etc.

Configuration plugins provide three kinds of values:
- **Managed settings:** simple values such as booleans, numbers, strings, enums, lists, or sets handled through `ManagedConfiguration`. These values may be locked or used as organization defaults. Which configuration plugin owns a locked setting is persisted in `Data.ManagedLockedConfigurations`, and organization defaults are tracked in `Data.ManagedEditableDefaults`. Both are cleaned up generically by `ManagedConfiguration.CleanupLeftOverManagedConfigurations(...)` when the owning plugin is gone. The value a setting had before a configuration plugin took it over is kept in `Data.ManagedUserValueSnapshots` and restored by that same clean-up, so removing a plugin hands the user's own value back instead of the app default.
- **Managed configuration objects:** complex Lua tables that are persisted into `SettingsManager.ConfigurationData`, implement `IConfigurationObject`, and are cleaned up through `PluginConfigurationObject.CleanLeftOverConfigurationObjects(...)`. Examples include providers, profiles, chat templates, data sources, and document analysis policies.
- **Live plugin content:** complex Lua tables that implement `ILivePluginContent` and are read live from running plugins instead of being persisted to `ConfigurationData`. Examples include `MANDATORY_INFOS` and `INTRODUCTIONS`. If live plugin content creates persistent side data, add a dedicated cleanup path for that side data, like mandatory-info acceptances.

When adding configuration plugin capabilities:
- For managed settings, update the corresponding data class in `app/MindWork AI Studio/Settings/DataModel/` to call `ManagedConfiguration.Register(...)` and process the setting in `PluginConfiguration.TryProcessConfiguration`. Cleaning up the setting when its configuration plugin was removed needs no extra step: `ManagedConfiguration.CleanupLeftOverManagedConfigurations(...)` iterates all registered settings. Do not add per-setting cleanup calls to `PluginFactory.Loading.LoadAll`.
- For managed configuration objects, update `PluginConfigurationObject.cs` and `PluginConfigurationObjectType.cs`, persist them in the appropriate `ConfigurationData` collection, and add cleanup via `PluginConfigurationObject.CleanLeftOverConfigurationObjects(...)`.
- For live plugin content, add a data type implementing `ILivePluginContent`, parse it in `PluginConfiguration`, expose it through `PluginFactory`, and add any required cleanup only for persistent side data.
- Always document the new capability in `app/MindWork AI Studio/Plugins/configuration/plugin.lua`.

## RAG (Retrieval-Augmented Generation)

RAG integration is currently in development (preview feature). Architecture:
- **External Retrieval Interface (ERI)** - Contract for integrating external data sources
- **Data Sources** - Local files and external data via ERI servers
- **Agents** - AI agents select data sources and validate retrieval quality
- **Embedding providers** - Support for various embedding models
- **Vector database** - Planned integration with Qdrant for vector storage
- **File processing** - Extracts text from PDF, DOCX, XLSX via Rust runtime

## Enterprise IT Support

AI Studio supports centralized configuration for enterprise environments:
- **Registry (Windows)** or **environment variables** (all platforms) specify configuration server URL and ID
- Configuration downloaded as ZIP containing Lua plugin
- Checks for updates every ~16 minutes via ETag
- Allows IT departments to pre-configure providers, settings, and chat templates

**Documentation:** `documentation/Enterprise IT.md`

## Provider Confidence System

Multi-level confidence scheme allows users to control which providers see which data:
- Confidence levels: e.g. `NONE`, `LOW`, `MEDIUM`, `HIGH`, and some more granular levels
- Each assistant/feature can require a minimum confidence level
- Users assign confidence levels to providers based on trust

**Implementation:** `app/MindWork AI Studio/Provider/Confidence.cs`

## Dependencies and Frameworks

**Rust:**
- Tauri 2 - Desktop application framework
- Axum - HTTPS API server
- tokio - Async runtime
- keyring - OS keyring integration
- pdfium-render - PDF text extraction
- calamine - Excel file parsing

**.NET:**
- Blazor Server - UI framework
- MudBlazor - Component library
- LuaCSharp - Lua scripting engine
- HtmlAgilityPack - HTML parsing
- ReverseMarkdown - HTML to Markdown conversion

## Security

- **Encryption:** AES-256-CBC with PBKDF2 key derivation for sensitive data
- **IPC:** TLS-secured communication with random ports and API tokens
- **Secrets:** OS keyring for persistent secret storage (API keys, etc.)
- **Sandboxing:** Tauri provides OS-level sandboxing

## Release Process

1. Create changelog file: `app/MindWork AI Studio/wwwroot/changelog/vX.Y.Z.md`
2. Commit changelog
3. Run from `app/Build`: `dotnet run release --action <build|month|year>`
4. Create PR with version bump and changes
5. After PR merge, maintainer creates git tag: `vX.Y.Z`
6. GitHub Actions builds release binaries for all platforms
7. Binaries uploaded to GitHub Releases

## Important Development Notes

- **File changes require Write/Edit tools** - Never use bash commands like `cat <<EOF` or `echo >`
- **End of file formatting** - Do not append an extra empty line at the end of files.
- **No automated formatting for Rust or .NET files** - Never run automated formatters on Rust files (`.rs`) or .NET files (`.cs`, `.razor`, `.csproj`, etc.). Only make the minimal manual formatting changes required for the specific edit.
- **I18N resources are generated** - Do not manually edit `app/MindWork AI Studio/Assistants/I18N/allTexts.lua`, `app/MindWork AI Studio/Plugins/languages/en-us-97dfb1ba-50c4-4440-8dfa-6575daf543c8/plugin.lua`, or `app/MindWork AI Studio/Plugins/languages/de-de-43065dbc-78d0-45b7-92be-f14c2926e2dc/plugin.lua`. These files are updated automatically by the I18N process.
- **Spaces in paths** - Always quote paths with spaces in bash commands
- **Agent-run builds** - Never start `.NET` or Rust builds in the agent's own shell; it is sandboxed. Use the `rider` and `rustrover` MCP servers instead, which build in the IDE outside that sandbox. See "Running builds from an agent" above.
- **Debug environment** - Reads `startup.env` file with IPC credentials
- **Production environment** - Runtime launches .NET sidecar with environment variables
- **MudBlazor** - Component library requires DI setup in Program.cs
- **Encryption** - Initialized before Rust service is marked ready
- **Message Bus** - Singleton event bus for cross-component communication inside the .NET app
- **Naming conventions** - Constants, enum members, and `static readonly` fields use `UPPER_SNAKE_CASE` such as `MY_CONSTANT`.
- **Compatibility shims** - Temporary fallback or read-repair code must be documented in `documentation/compatibility-shims/` with an introduced date, remove-after date, code references, and removal checklist. Add a short code comment near the shim that references the document and remove-after date. Check this folder before adding similar fallback logic, and do not extend expired shims without explicit maintainer direction. Do not use this process for permanent settings schema migrations; those belong in `app/MindWork AI Studio/Settings/SettingsMigrations.cs`.
- **Empty lines** - Avoid adding extra empty lines at the end of files.

## Changelogs
Changelogs are located in `app/MindWork AI Studio/wwwroot/changelog/` with filenames `vX.Y.Z.md`. These changelogs are meant to be for normal end-users
and should be written in a non-technical way, focusing on user-facing changes and improvements. Additionally, changes made regarding the plugin system
should be included in the changelog, especially if they affect how users can configure the app or if they introduce new capabilities for plugins. Plugin
developers should also be informed about these changes, as they might need to update their plugins accordingly. When adding entries to the changelog,
please ensure they are clear and concise, avoiding technical jargon where possible. Each entry starts with a dash and a space (`- `) and one of the
following words:

- Added
- Released
- Improved
- Changed
- Fixed
- Updated
- Removed
- Downgraded
- Upgraded

The entire changelog is sorted by these categories in the order shown above. The language used for the changelog is US English.