byre/AGENTS.md

Rules for agents working on byre

These are requirements, not preferences. Changing one needs the owner's agreement first.

Workflow

• Deploy before handing off. Any change that affects the running server or the web UI is deployed to the service before you stop and report, so the owner can look at it immediately: go generate ./web if web sources changed, then go install ./cmd/byre && launchctl kickstart -k gui/$(id -u)/run.fc.byre, always as that one command, never go install on its own. Then confirm it came up: the tail of ~/Library/Logs/byre.log, and GET /api/admin/status through the tailscale serve URL (tailscale serve status shows it). Report what you deployed and what you checked.
  • go install does not restart the service. If byre restarts after your install without your kickstart, another agent deployed its own branch, and the running binary is theirs, not yours.
  • You run inside byre, so the kickstart kills your own turn partway through the command. That is expected, not a reason to skip it. Make the deploy the last action of the turn. You resume with a "byre restarted while you were mid-turn" message; do the checks then, and confirm the service started after your kickstart.
  • The restart can cut off the record of the last tool call before the kickstart, or the kickstart itself, so you may resume with no memory of having deployed. Before concluding that another agent restarted byre, compare the service's start time (started_at in /api/admin/status, or the last listening line in the log) with your most recent go install: a restart right after your own install is most likely your kickstart.
• docs/operations.md describes the layout, data, service and APIs; keep it current with every change.

Web UI layout

• Exactly two panes, side by side, each exactly half the width, at every window size. Never three or more columns, never a sidebar, never a resizable or collapsible split.
• One navbar, across the top.
• The left pane is the user's lead agent and nothing else. The right pane always shows one task, through tabs of that task's views; the lead sets the task, which tabs come first and which one is selected, and the human can switch the task (⌘K) and tabs too. A new view is a new tab in the right pane, never a new column or region.
• Overlays (the task switcher, the Status and Settings modals) are allowed; they sit above the panes and don't change the layout.

Web UI look

• One font everywhere: Atkinson Hyperlegible Mono, self-hosted from web/fonts/. No font CDNs.
• High contrast means readable text, not harshness. Body text is at least 7:1 against its background and secondary text at least 4.5:1, on soft backgrounds (off-white, dark slate; never pure black or white). Keep the frame quiet: 1px borders in a subtle tone, no dashed or heavy borders, no inverted blocks for selection, colour used sparingly for state and accent. The palette lives in the custom properties at the top of web/style.css; change it there.
• Never show agent cost, turn duration, or turn counts anywhere in the UI. They stay in the event log for the API, not on screen.

Web UI code

• Frameworkless. TypeScript in web/src/, compiled file-by-file to ES modules in web/dist/ with tsc. No bundler, no framework, no runtime dependencies. The one exception is vendored Mermaid, lazy-loaded: web/vendor/mermaid.min.js, loaded only when a diagram appears.
• API types come from api/openapi.yaml via openapi-typescript (web/src/api.gen.ts); call the API through the typed client in web/src/api.ts, never raw fetch.
• web/dist/ is committed so go install needs no Node. Regenerate it with go generate ./web whenever web/src/ or the spec changes.
• Every view mounted into a pane returns a dispose function that removes its state subscriptions.