token-gated-economy/AGENTS.md

# 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

## Testing

Executor agents should follow this three-step workflow when implementing or verifying any change:

**1. Fetch the test plan before starting**
```bash
curl <BASE>/api/testkit/plan
```
Returns `TIMMY_TEST_PLAN.md` — full architecture notes, route descriptions, and expected behaviour for all 24 tests. Read this first so you understand what each endpoint is supposed to do before touching the code.

**2. Run the full test suite after implementing**
```bash
curl -s <BASE>/api/testkit | bash
```
The server returns a self-contained bash script with the base URL already baked in. Requirements: `curl`, `bash`, `jq` — nothing else. All 24 tests must pass (FAIL=0) before submitting.

**3. Fill in and submit the report**
```bash
curl <BASE>/api/testkit/report
```
Returns just the report template section ready to copy and fill in. Attach the completed report to your PR or task output.

Where `<BASE>` is the running server URL, e.g. `http://localhost:8080` locally or the Replit dev URL in CI.

## 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 |