nexus/AGENTS.md

Nexus Agent Guide

Scope

These rules apply to the whole Nexus repository. Keep this file concise and update it when the build, architecture, or review workflow materially changes.

Product and architecture

• Nexus is the Noveria operations platform. OpenClaw is integrated through the backend runtime and bridge abstractions; frontend code must not depend on OpenClaw internals.
• frontend/ is a Vue 3, TypeScript, Pinia, Vue Router, Vite, and Tailwind 4 application.
• backend/ is an ASP.NET Core 10 API using Entity Framework Core and PostgreSQL.
• backend-tests/ contains the backend test project.
• frontend/src/api/ owns HTTP contracts, frontend/src/stores/ owns client state, and views/components should not duplicate transport logic.
• Backend changes should preserve the controller -> service -> repository boundaries and keep task mutations behind ITaskBridgeService where applicable.

Required local checks

Frontend:

Set-Location frontend
pnpm install --frozen-lockfile
pnpm test
pnpm build

Backend (requires .NET SDK 10):

dotnet test backend-tests/Nexus.Api.Tests.csproj --configuration Release

Use the versions in CI as the compatibility baseline: .NET 10, Node.js 24, and pnpm 10.12.1. Do not silently downgrade target frameworks to match an older local SDK.

Security and review rules

• Default API access to authenticated users or authenticated services. Public endpoints must be explicitly marked and justified.
• Never treat a caller-controlled identity header as proof of authentication unless a trusted proxy removes and re-establishes it after authenticating the caller.
• Keep credentials and environment values out of tracked files. Use .env.template only for documented placeholders.
• Changes to authentication, agent commands, task mutation, deployment, or database migrations require focused regression tests.
• Frontend work must verify the registered route, loading/empty/error states, keyboard semantics, and the 375, 768, 1024, 1440, and 1920 px breakpoints.
• Do not add navigation entries without a registered route and a working destination.

Documentation and evidence

• Keep canonical technical documentation in this repository.
• Put dated audit evidence in docs/audits/YYYY-MM-DD/.
• Update README.md when routes, supported versions, deployment behavior, or authentication contracts change.
• At semantic checkpoints, update the compact Obsidian mirror under Projects/OpenClaw Mission Control/ after the repository documentation is current. Do not copy large source files or detailed vulnerability mechanics into the Vault.