# Palace Monitor

## What It Is

The monitor shows each palace's Claude usage — cost, tokens, and sessions — broken down by channel, domain, and model across configurable time windows.

Each master opens the monitor from their own palace and sees only their palace's data. Junwon sees manglasabang's usage. Elizabeth sees whitehall's. No palace sees another's.

## What It Tracks

Every Claude session produces a usage record when it completes. Each record captures:

- When it happened (date, time)
- Which palace it belonged to
- Which master and butler were involved
- What triggered it (channel)
- What model was used
- What domain the work belonged to
- How much it cost (cost_usd)
- How many tokens were consumed (tokens_in, tokens_out)
- How many turns the session took
- How long it ran (duration_ms)

## Storage

Usage records go in the `usage` table in Postgres. This is one of the few things that belongs in SQL rather than files: the schema is fixed, records accumulate at scale, and the monitor needs to filter and aggregate efficiently. A WHERE clause is the right tool.

See `direction/palaceplatform/database.md` for the full schema.

## Time Windows

Eight time windows: 1H, 3H, 6H, 12H, 24H, 3D, 7D, 1M. 24H is the default. The master can drill into any window to see the breakdown by each dimension.

## Dimensions

Three dimensions, each drillable:

- **By channel** — what triggered the session (email, slack, heartbeat, direct, etc.)
- **By domain** — what the work was about (junwonhome, palacefund, palaceapp, etc.)
- **By model** — which Claude model was used (opus, sonnet, haiku)

## Data Source

Usage is written by the SDK (`@palace/sdk/usage`) at the end of every Claude session. The SDK POSTs to `/api/usage/log` on the running palacering instance, including the palace name from env. The monitor fetches from `/api/usage?period=<window>`, which filters by the palace of the logged-in master.

For Junwon's sessions (originating on the Mac), the SDK includes `palace=manglasabang`, `master=junwon`, `butler=ace` from env vars. For other masters on the VM, these values come from their session context.

If the POST fails (palacering unreachable), the SDK falls back to appending to a local JSONL file. Degraded mode only — Postgres is the source of truth.

## Palace Isolation

The GET endpoint resolves the palace from the logged-in master's session. No query parameter override is accepted. A master cannot query another palace's usage by manipulating the request.