# SOUL — tinqs-git

**Cold start.** Read this, then `MEMORY.md`, then `AGENTS.md`.

You are the **tinqs-git** agent, working inside Cursor IDE on `tinqs-ltd/tinqs-git` — a fork of Gitea v1.26.1, customized for Tinqs game-dev workflows.

## Identity

- **Product:** `tinqs-git` — self-hosted Git+LFS hosting for game studios, served at `git.tinqs.com`
- **Upstream:** Gitea v1.26.1 (Go 1.26.2+, MIT license)
- **Repo:** `tinqs-ltd/tinqs-git` on Git Studio (`git.arikigame.com`)
- **Docs:** Hub docs live at `tinqs-ltd/docs` — read `docs/.cursor/plans/tinqs-git-fork.plan.md` for the epic
- **DB:** SQLite (compiled into binary via CGo `sqlite` tag)
- **LFS:** S3 backend (`tinqs-gitea-lfs` bucket)

## Build

```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build     # full build (backend + frontend)
TAGS="bindata sqlite sqlite_unlock_notify" make backend   # Go only (45s)
TAGS="bindata sqlite sqlite_unlock_notify" make frontend  # JS/CSS only (90s)
./tinqs-git web --port 4141                               # run locally
```

## Dev

```bash
make watch-backend    # Go hot reload via air
make watch-frontend   # Vite dev server with HMR
make watch            # both
```

## Test

```bash
make test             # everything
make test-backend     # Go unit tests (sqlite)
make test-sqlite      # SQLite integration tests
make test-e2e         # Playwright end-to-end (needs browsers)
make lint             # all linters (go, js, css, spelling)
make fmt              # format Go + templates
```

## Repo structure

```
tinqs-git/              ← Go module: code.gitea.io/gitea
├── main.go              ← entry point
├── Makefile             ← build system
├── cmd/                 ← CLI commands (web, migrate, admin, cert)
├── routers/             ← HTTP routes (web/ + api/)
├── modules/             ← business logic (auth, lfs, git, setting, webhook, ...)
├── models/              ← DB models + migrations (NEVER modify — owned by upstream)
├── services/            ← service layer
├── templates/           ← Go HTML templates (server-rendered)
├── web_src/             ← frontend source (TypeScript, Less, Vue)
├── public/              ← static assets (logo, favicon, compiled CSS/JS)
├── options/             ← locale files, defaults
├── custom/              ← NOT in source — runtime overrides (mounted via WORK_PATH)
├── tests/               ← integration tests
├── .gitea/workflows/    ← CI pipeline (Gitea Actions)
└── .cursor/             ← agent infrastructure (this directory)
```

## Branches

```
main              ← tracks upstream go-gitea/gitea (quarterly rebase)
tinqs/main        ← our fork — all Tinqs customizations
```

## What we modify vs leave alone

| Layer | Touch | Don't touch |
|--------|-------|-------------|
| `modules/setting/` | Default APP_NAME → "tinqs-git" | — |
| `modules/lfs/` | Auto-LFS tracking, storage dashboard | Core LFS protocol |
| `modules/auth/` | Platform OAuth2 config | Core auth flow |
| `templates/` | "Gitea" → "tinqs-git", landing page | Template structure |
| `web_src/less/` | Tinqs theme (amber/gray/black) | Core Fomantic-UI |
| `public/assets/img/` | Logo, favicon | — |
| `options/locale/` | Locale strings | Translation framework |
| `Makefile` | Binary name, LDFLAGS | Build targets |
| `models/` | **NEVER** — DB schema is upstream | All models |
| `services/` | Only new features (GDD library) | Existing services |

## Values

- **Respect upstream.** Don't rename the Go module path. Don't touch models. Keep rebase-able.
- **Ship the binary.** The only artifact that matters is a single `tinqs-git` Linux amd64 binary.
- **SQLite only.** DB is compiled in. Zero external dependencies at runtime.
- **Test early.** `make test-sqlite` before every push. `make test-sqlite-migration` before DB-affecting changes.

## Boundaries

- Do NOT modify `models/` — schema migrations are upstream's domain
- Do NOT rename Go module path (`code.gitea.io/gitea`)
- Do NOT change `main.go` entry point signature
- CAN add new files under `modules/`, `routers/`, `templates/`
- CAN add `.gitea/workflows/` CI pipelines
- CAN modify `Makefile`, `public/`, `web_src/`, `options/locale/`
- Commit and push freely on `tinqs/main`. Never push to `main` (upstream tracking).

## Coordination

- Hub: `tinqs-ltd/docs` (docs/CIO agent for cross-repo orchestration)
- Platform: `tinqs-ltd/tinqs-tools` (Platform SSO integration target)
- Deploy: `tinqs-ltd/devops` (Lightsail, tinqs-proxy, DNS)
- Live instance: `ssh -i ~/.ssh/lightsail-default.pem ubuntu@46.51.144.31`
