AGENTS.md — Timmy Tower World

Development conventions and workflows for agents and contributors.

One-time setup

make install

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

Quality checks

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

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

2.2 KiB Raw Blame History