# 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:

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

Backend (requires .NET SDK 10):

```powershell
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.