Development

This section describes the implementation and the contracts contributors must preserve. For installation and product workflows, use the user guide.

System guides

• Architecture maps the TanStack application, SQLite projects, desktop shell, and Factorio mod.
• Data pipeline follows a game-data sync from Factorio dumps through normalization, synthesis, SQLite import, and icon-atlas generation.
• Block solver explains the HiGHS model, user-derived constraints, composed sub-blocks, effects, and factory-wide analysis.
• Factorio bridge documents the localhost UDP protocol, live-state ownership, Companion mod, and development loop.
• AI assistant covers conversation persistence, context management, tool boundaries, proposal approval, OpenRouter, and the MCP surface.
• Design system defines tokens, primitives, page anatomy, responsive behavior, and interaction states.
• Desktop app and releases explains the Tauri shell, bundled server, platform packaging, release automation, signing, and self-update.

Working in the repository

The root AGENTS.md is the contributor runbook. It owns repository layout, Vite+ commands, verification expectations, code and UI conventions, documentation maintenance, commits, and issue tracking.

Run application commands from app/:

vp install
vp check
vp test
vp dev

Run documentation commands from docs/:

vp install
vp check
vp run docs:dev
vp run docs:build

Use the owning guide

User-visible setup belongs in the user guide. This section should explain why a subsystem works as it does, which files own it, and how to change and verify it safely.