# Loume

> Loume is a calm personal workspace for tasks, documents, drawings, projects, folders, and connected AI agents.

## Public routes

- `/`: public Loume home.
- `/app`: authenticated Loume workspace.
- `/integrations/hermes`: Hermes integration overview and maintenance.
- `/integrations/hermes/connect?code=XXXX-XXXX`: one-time Hermes pairing guide generated by Loume.
- `/api/v1/health`: public application and database health check.

## Hermes integration

The official Hermes integration is installed from Loume itself. A new connection must start inside `/app`, under Settings → Agents, where the owner generates a single-use pairing code. Never ask the user for Clerk credentials, database credentials, or an agent token.

When given a connection URL:

1. Read the complete instructions on that URL.
2. Run only the installation command shown there on the Hermes host.
3. Verify with `hermes loume status`.
4. Restart with `hermes gateway restart` when requested.
5. Confirm the result in Loume.

Existing installations can update without pairing again:

`curl -fsSL <LOUME_ORIGIN>/integrations/hermes-update.sh | bash -s -- --url <LOUME_ORIGIN>`

If only the public tunnel or domain changed:

`hermes loume set-url --url <NEW_LOUME_ORIGIN>`

The internal platform, environment variables, profile, and tool names may still use the legacy wire identifier `lume` for backward compatibility. Do not rename or delete those values during maintenance.

Connection diagnostics:
- Run `hermes loume status` on the Hermes machine to verify the saved URL, token, and a real authenticated round trip.
- `GET /api/v1/agents/external/hermes/health` requires the agent bearer token and returns connection identity, server time, and presence timing.

## API and authorization

All product data is accessed through `/api/v1`. Browser routes use Clerk identity. Hermes external routes use a revocable bearer token bound to one owner-side connection. Never send or accept an `ownerId` supplied by a client.

## Behavioral notes

- Assigning Hermes to a task opens its task conversation and queues work.
- Mentioning Hermes in a task comment opens or reuses the same conversation.
- Later comments in that task thread continue to reach participating agents without repeating the mention.
- Operational notices and progress updates are not final answers.
- The adapter processes one active turn at a time and reports only the final response to Loume.