tmux-rc: Instructions file for Codex

AGENTS.md — working conventions for tmux-rc

Conventions for AI agents (and humans) working in this repo. The philosophy notes in the harness/session prompt still apply (minimize LOC, DRY, KISS, why-focused docs); this file captures repo-specific workflow that isn't obvious from the code.

This repository is public

Everything committed here is readable by anyone, forever. Agents see the user's private work all day; none of it belongs in this repo.

• Test fixtures, eval samples (research/eval/samples), demo data and screenshots are invented from scratch. Renaming or redacting a real capture is not sanitizing: its shape, wording and details still describe the private work it came from. Rebuild only the structure that triggers the bug, around an unrelated invented topic, as short as it can be. tests/test_public_data.py rejects the usual tells (identity and credential shapes, provenance words like "real capture", an oversized capture), but it is no proof.
• Never commit session transcripts, the user's prompts, costs or usage, product or client details, internal hostnames, or anything copied from a real pane, log, or private repo.
• Before every push, read your own added lines for real content. A local pre-push hook may block a push for private terms; never bypass it. Rewrite the content and tell the user what it caught.

The repo root is the live deploy — and it is always the integration branch

The daemon is a systemd --user unit (tmux-rc.service, installed by make install-units) whose WorkingDirectory is the repo root. The root is checked out detached at origin/integration: origin/main plus every open, non-draft PR merged together. That merge is what the phone runs, so several in-flight PRs get field-tested at once without merging any of them prematurely, and two PRs that fight each other show up here before either lands.

• Never git checkout / switch / reset in the root to try one PR. That silently drops every other PR under test. Try a single PR alone in its own worktree.
• To make a PR (or a new push to one) live, rebuild integration: in a worktree, reset the integration branch to origin/main and merge each open PR branch (gh pr list), most conflict-prone last. Its history is disposable — rebuild from main rather than piling merges on the old tip, or a PR that was dropped or reworked lingers in the merge. Resolve conflicts in the merge commit only, never on the PR branch. make test, force-push integration, then in the root git checkout --detach origin/integration and systemctl --user restart tmux-rc (the unit runs with reload off, so nothing applies until the restart). Leave a PR out only when its conflict is not mechanical, and say so — its author fixes it against main.
• Integration is never merged to main. PRs land one at a time, via review and the user's explicit go.
• Never edit files in the root. All changes go through worktrees cut from origin/main (below); the root's only writes are the detached checkout and .env.
• .env (gitignored) lives in the root. Provider API keys do not: they go in ~/.config/tmux-rc/openai.env, outside every checkout, so no worktree or commit can carry one. Logs: journalctl --user -fu tmux-rc. make dev (StatReload) is for iterating in a worktree, never the root.
• The live instance is reached through the tunnel client (tmux-rc-tunnel.service). A momentary "no tunnel connected" is the relay's ~1h connection cap; the client reconnects within ~1min.
• To show the user a preview (mock, build, report), put it in a subfolder of the directory TMUXRC_SCRATCH_DIR names (served at /scratch/<folder>/) rather than starting a server or tunnel; see docs/deploy/previews.md. A UI mock is variants of the real app in the shared harness (make mock, make mock-check; its "Mocks" section), never a hand-built page, and the decision it leads to is recorded in docs/design/.