evoflux: Instructions file for Codex

EvoFlux — Agent Instructions

EvoFlux is a local-first desktop workspace for Work and Coding agent teams. The production application is a Tauri shell embedding a React UI and supervising a local FastAPI sidecar.

Instruction precedence

This file applies to the whole repository. Before changing a file, also read the nearest nested AGENTS.md; nested instructions add to or override this root contract for their directory.

Scoped instruction files currently live under:

• app/, including app/agent/, app/api/, and app/services/;
• web/ and web/src/;
• desktop/ and desktop/src-tauri/;
• seed/;
• scripts/.

Repository map

app/          Python sidecar: API, agents, services, persistence, automation
web/          React/TypeScript interface embedded by Tauri
desktop/      Rust/Tauri shell and native packaging
seed/         First-install agent and configuration templates
scripts/      Development, build, validation, and release utilities
tests/        Python backend, integration, CLI, and packaging tests
documents/    Single documentation root for product and contributor docs

Start with:

• documents/README.md for documentation navigation;
• documents/features/README.md for implemented features and code ownership;
• documents/architecture/system-overview.md for process and trust boundaries;
• documents/reference/repository-map.md for the detailed source map.

Architecture boundaries

• Keep FastAPI routes thin. Durable behavior belongs in app/services/, app/agent/, app/scheduler/, or app/core/.
• Keep provider-specific payloads behind app/agent/providers/; generic API and team schemas must remain provider-neutral.
• Use TanStack Query for frontend server state, Zustand for live/client state, and shared shell/workbench primitives for application chrome.
• Tauri owns native lifecycle, capabilities, browser integration, and packaging; the Python sidecar owns agent policy, persistence, and workspace authorization.
• The application database stores product state. Repository source remains user-owned and must not be deleted by application cleanup.
• Work mode uses session workspaces. Coding mode is project-only: every Coding session belongs to a Coding project and may access only that project's repositories.
• Tools, MCP, plugins, browser content, imported documents, and remembered text remain subject to explicit trust, permission, sandbox, and untrusted-data boundaries.