vellium AGENTS.md

AGENTS.md — Vellium contributor and coding-agent guide

This file applies to the entire repository. It is the first technical map an agent should read before changing Vellium. More specific documentation under docs/ explains user-facing behavior; this file focuses on implementation boundaries, invariants, safe workflows, and verification.

1. Product and runtime model

Vellium is a local-first AI workbench for:

• character chat and multi-character roleplay;
• branching conversations, personas, LoreBooks, RAG, attachments, tool calls, reasoning traces, translation, TTS, and chat export;
• long-form writing with projects, chapters, scenes, summaries, and DOCX/Markdown;
• OpenAI-compatible, KoboldCpp, local, and custom provider adapters;
• plugins, MCP tools, endpoint extensions, and an optional desktop pet;
• a deprecated Agents workspace that remains available through Settings > Legacy.

The application has four cooperating runtimes:

1. React + TypeScript renderer in src/.
2. Express API in server/.
3. SQLite persistence through better-sqlite3.
4. Electron desktop shell in electron/.

The browser development topology is:

React/Vite http://127.0.0.1:1420
        │ /api proxy
        ▼
Express   http://127.0.0.1:3002
        │
        ▼
SQLite + providers + MCP + local files

In packaged Electron and headless static mode, Express serves both dist/ and /api, normally from http://127.0.0.1:3001. Electron loads that HTTP URL; it does not normally load the production UI directly from file://.

2. Start every task safely

Before editing:

1. Run git status --short and preserve unrelated user changes.
2. Identify the smallest owning subsystem and read its route, service/repository, client, contract, UI, and existing tests before introducing a second path.
3. Search with rg; do not assume a feature is absent from a large screen.
4. Treat data/, output/, release/, dist/, dist-electron/, generated bundles, and user-imported assets as user or generated state. Do not modify, delete, or commit them unless the task explicitly requires it.
5. Do not create commits, tags, releases, or pushes unless explicitly requested.
6. If asked to checkpoint before risky work, make the checkpoint first and keep the later hardening/refactor in a separate commit.