teahub/AGENTS.md

AGENTS.md — Teahub v1 (Green Tea)

You are on prod: https://teahub.xyz, Gitea 28 on Fly (app green-tea, configured by gitea/fly.toml, its look in gitea/custom). Everything here is the factory's own record; nothing here is scaffolding from before 2026-10-14.

 you (any agent) ──MCP──▶ mcp.teahub.xyz ──as the signed-in user──▶ teahub.xyz (Gitea)
                                                                     │
                 login: GitHub (now), nostr (next)                   ├── teahubxyz/teahub   the spine (this repo)
                                                                     ├── teahubxyz/time     Time: the clock (Gitea Actions on the Fly runner)
                                                                     └── <your repos>
 Time = the automation layer. It lives here, on prod (teahubxyz/time); the GitHub copy is an archived proof of concept.
 Time acts as the Gitea user `time` (its own token, TIME_TOKEN) for every write except comments and commit statuses,
 which stay with the Actions identity (`gitea-actions`); code goes in as git pushes.
 Rhythm: Astra (daily, 13:13 UTC) queues cards; the heartbeat (hourly) builds them one at a time with a seat, gets a
 review, and merges on approve + green CI. PRs under .github/ (Time's own engine) never merge themselves: the steward,
 a scheduled Claude session every 6 hours, reads and merges them.
 Seats: Claude (haiku / sonnet / opus / fable, ANTHROPIC_API_KEY, user-level secret) by default; Venice wired but idle.
 Spend: every model call is booked to time/ledger/<YYYY-MM>.jsonl; TIME_DAILY_USD=5, TIME_MONTHLY_USD=100 stop the
 clock and open an `andon` issue. No model decides whether to spend.
 hb-5 (the Mac) is NOT part of prod: it is the operator's playground and the old instance (matcha.teahub.xyz).
 Boring (ops MCP) lives on the Mac and may reach prod as a client; prod never depends on it.

Moves

• Read first: this file, docs/decisions.md (why things are the way they are), docs/rebuild.md (what it took).
• Work is an issue with a DONE: line. Open it, do it, receipt it on the issue, close it. Label it queued and Time runs it when its turn comes (oldest first, Depends on #N respected); ready runs it on the next beat, beside whatever else is running; spec has Time split it into cards.
• Before a task, find its route in SKILLS.md and load only the skills it names, by path. No model decides which skill to load.
• You act as yourself (Time too: it is the time user). There is no shared service token on prod. If you can't do something, your Gitea permissions are the reason; ask the owner (teahubxyz) on the issue.
• Porting from the old instance: only when a card needs it, only after reading it, one piece per commit, and a line in docs/rebuild.md saying what it took.
• Secrets: prod holds Gitea's own keys, the GitHub OAuth client, the MCP's OAuth client, and the seat keys listed in docs/decisions.md. Nothing else. Do not add one without a decision there. A temporary admin token is deleted (sqlite3 on the Fly box) and the deletion checked before you write that it's gone.
• Be boring by default; get clever only on an ANDON. Deterministic scripts before cheap inference before expensive inference.
• Cost ladder for seats: Luna = haiku, Sol = sonnet, Astra = opus. Fable is for the operator's own maths, not the factory.

Where things are

• MCP source: mcp/ (FastMCP, deploy with fly deploy).
• Decisions: docs/decisions.md (append-only, dated).
• Rebuild log: docs/rebuild.md.
• Skills: SKILLS.md (routes, ledger, belts); the vendored folders are in .agents/skills/.
• Time's engine: teahubxyz/time .github/time/ (time.py the clock, venture.py the venture loop, astra.py the daily planner, seats.json the seats). The planner and the steward both write to the "Astra log" issue there.