# AGENTS.md — Timmy Tower World

Development conventions and workflows for agents and contributors.

## One-time setup

```bash
make install
```

This activates git hooks that run `typecheck` and `lint` before every commit and push.

## Quality checks

```bash
pnpm run typecheck   # TypeScript type-checking (tsc --build across all packages)
pnpm run lint        # ESLint across all TypeScript source files
make check           # Run both in sequence (same as CI)
```

## Pushing to Gitea

All pushes go through the bore tunnel helper script (see replit.md for full docs):

```bash
bash scripts/push-to-gitea.sh [PORT]
```

- First call after bore starts: pass the port once — it's saved for the session
- Subsequent calls: no argument needed, reads from `.bore-port`
- Bore port changes every restart — pass the new port to update

Set `GITEA_TOKEN` or write the token to `.gitea-credentials` (gitignored). Never commit credentials.

## Branch and PR conventions

- **Never push directly to `main`** — Gitea enforces branch protection
- Every change lives on a feature branch: `feat/<slug>`, `fix/<slug>`, `chore/<slug>`
- Open a PR on Gitea and squash-merge after review
- CI runs `pnpm typecheck && pnpm lint` on every PR automatically

## Stub mode

The API server starts without Lightning or AI credentials:

- **LNbits stub**: invoices are simulated in-memory. Mark paid via `POST /api/dev/stub/pay/:hash`
- **AI stub**: Anthropic credentials absent → canned AI responses. Set `AI_INTEGRATIONS_ANTHROPIC_API_KEY` for real AI

## Workspace structure

```
artifacts/api-server/    — Express 5 API server (@workspace/api-server)
lib/db/                  — Drizzle ORM schema + PostgreSQL client (@workspace/db)
lib/api-spec/            — OpenAPI spec + Orval codegen
lib/api-zod/             — Generated Zod schemas (do not edit by hand)
lib/api-client-react/    — Generated React Query hooks (do not edit by hand)
scripts/                 — Utility scripts (@workspace/scripts)
```

## Running the API server

```bash
pnpm --filter @workspace/api-server run dev
```

## Gitea repos

| Repo | Purpose |
|---|---|
| `replit/token-gated-economy` | This repo — TypeScript API |
| `perplexity/the-matrix` | Three.js 3D world frontend |