# Console — operational setup (server state, not in git)

Records the OS-level setup the admin console depends on. Reproduce this on any
new server; none of it lives in the repo.

## Agent runtime
- **OS user** `carlos-arias-agent` — system user, `/usr/sbin/nologin`, **no sudo**.
  The headless agent runs as this user. Never as root.
- **HOME** `/var/lib/carlos-arias-agent` (0700). Contains `.claude.json` with
  `hasTrustDialogAccepted: true` for the repo path (headless can't click the
  trust dialog).
- **Claude binary** relocated to `/usr/local/bin/claude` (self-contained 257M
  ELF). `/root` is `0750`, so the agent could not reach root's install.
- **Token** in `agents/.env` → `CLAUDE_CODE_OAUTH_TOKEN` (git-ignored, 0600).
  A `claude setup-token` value (`sk-ant-oat01-…`). Rotate it — it passed through
  a chat transcript during setup.

## Permissions model (no chown-to-www needed)
- Shared group **`caweb`**; members: `carlos-arias-agent` + `www`.
- `app/`, `brand/`, `api/db`, `api/cli`, `agents/` → group `caweb`, `g+rwX`,
  setgid on dirs (new files inherit the group).
- `public/` and `public-preview/` → group `caweb`, `g+rwX`, setgid, world-read.
  nginx (`www`) only needs **read** to serve, so the agent can own build output
  and nginx still serves it — no privileged chown step.

## Build model
- Isolated preview: `PREVIEW_OUT=../public-preview/<jobId>`
  `PREVIEW_BASE=/_preview/<jobId>` then `cd app && npm run build`
  (supported natively by `app/astro.config.mjs`).
- Publish: normal build to `public/`, then `git commit` (rollback point).

## Verified working (2026-07-23)
Confined agent, as `carlos-arias-agent` with the token: reads the repo, writes
source, runs a 24-page isolated preview build (~7.5s), output servable by nginx.
Full edit→preview→serve loop proven end to end.

## Still to build (Phase 1 remainder)
- Runner service `agents/console/server.mjs` (Node, binds `127.0.0.1:3011`):
  `run` / `preview` / `publish` / `discard` / `ping` / `auth` / `logout`.
- nginx: `/devconsole/*` + `/admin/*` → `auth_request` against a PHP admin-session
  check → proxy to `127.0.0.1:3011`. Runner never exposed directly.
- Wire `DevConsole.astro` to the runner.
- systemd unit to keep the runner alive.