# Agent Map

This file is a short map for coding agents. Keep detailed guidance in `docs/`
and keep this file small enough to fit into every task context.

## First Reads

- `DEVELOPMENT.md` - project commands, coding rules, test rules, and PR shape.
- `ARCHITECTURE.md` - package boundaries, data ownership, and runtime flow.
- `docs/harness/README.md` - how this repository is prepared for agent work.
- `docs/harness/validation.md` - which checks to run for each change type.
- `docs/harness/worktree-runbook.md` - isolated local dev and test setup.
- `docs/harness/pr-review.md` - self-review checklist before pushing.

## Common Commands

```bash
npm ci --ignore-scripts
npm run harness:check
npm run test
npm run test:e2e
npm run build
```

Use the smallest relevant check while iterating. Before a broad PR, run
`npm run harness:check`, `npm run test:coverage`, `npm run test:e2e`, and
`npm run build`.

## Code Ownership Map

- `electron/` - Electron window, preload, local service process and native packaging.
- `packages/client/src` - Vue 3 client, stores, routes, i18n, API helpers.
- `packages/server/src` - Koa API, Socket.IO, persistence, Hermes integration.
- `packages/skills` - built-in skills injected into the Hermes skills directory.
- `tests/client`, `tests/server`, `tests/shared` - Vitest coverage.
- `tests/e2e` - Playwright browser coverage with mocked backend services.
- `.github/workflows` - CI, release, and Docker packaging automation.

## Hard Rules

- Keep routes thin: put request handling in controllers and reusable behavior in services.
- Keep Web UI state under `HERMES_WEB_UI_HOME` or `HERMES_WEBUI_STATE_DIR`.
- Keep Hermes Agent state separate from Web UI state.
- Register local API routes before proxy catch-all routes.
- Use structured APIs and argument arrays instead of shell string construction.
- Add user-facing strings to every locale file.
- Do not mix unrelated refactors into a bug fix.

## Red Lines

- `packages/server/src/services/hermes/agent-bridge/python/` is read-only vendored code.
- The `/chat-run` Socket.IO event contract must not change event names, field names,
  field types, or emission timing. Adding optional fields is allowed.
- Hermes `state.db` is read-only. Node-side code must never open it; read session
  history through the bridge's `getHistory`/`getOutput` instead.
- `services/hermes/group-chat/`, `lib/context-compressor/`, and
  `services/hermes/context-engine/` are the chat chain: changes require a
  `docs/chat-chain-changes/<date>-<slug>.md` fragment.
- `packages/desktop` and `packages/website` are removed; do not reintroduce them.
  The current Electron runtime lives in root `electron/`; see `docs/electron.md`.
- This repo is a reimplementation. A few upstream service addresses are load-bearing
  and are deliberately kept, each with a whitelist entry in
  `scripts/harness-check.mjs`: the global-agent relay (`api.hermes-studio.ai`), the
  OpenRouter referer, and the sidebar website link. Do not "clean them up" as legacy
  brand text — removing them breaks those features. Do not read the relay address as
  project identity: this deployment is not affiliated with the upstream operator.
- The upstream ESP32 / MCU device feature was removed on purpose (no UI entry, no REST
  routes, no store, no locale strings). Do not reintroduce it. Its "purchase" affordance
  was the only part that merely advertised the upstream site; the rest was real device
  management, and the whole thing is gone because the hardware is out of scope here.
- The online-update channel (`runtime-version-manager.ts`) has no default URL. It reads
  `HERMES_WEB_UI_VERSION_MANIFEST_URL` / `HERMES_WEB_UI_DOWNLOAD_BASE_URL` /
  `HERMES_WEB_UI_GITHUB_REPO` and degrades with a named error when unset. Do not
  reintroduce a hardcoded upstream URL.
- ArkScope vendor (`packages/client/src/vendor/arkscore/`) is decorative only:
  login-page title, Journey graph background, first-load / empty states. Never in
  chat, forms, tables, or click-dense areas. Decorative layers must be
  `pointer-events: none` and carry no information or interaction.

## When The Agent Gets Stuck

Improve the harness instead of repeating the same prompt. Add missing docs,
tests, logs, scripts, or CI checks so the next agent can see and verify the
constraint directly.