tibi-svelte-starter/AGENTS.md

# AGENTS.md

Tibi CMS starter template — Svelte 5 SPA with esbuild, SSR via goja, and Playwright tests.

## Project overview

- **Frontend**: Svelte 5 SPA in `frontend/src/`, bundled with esbuild, styled with Tailwind CSS 4.
- **Backend**: tibi-server with API hooks in `api/hooks/`, collections in `api/collections/`.
- **SSR**: Server-side rendering via goja (Go JS runtime) in `api/hooks/ssr/`.
- **Tests**: Playwright for E2E, API, mobile, and visual regression tests in `tests/`.
- **Types**: Shared TypeScript types in `types/global.d.ts`. Keep `tibi-types/` read-only.

## Setup commands

- Install deps: `yarn install`
- Start dev: `make docker-up && make docker-start`
- Start with mock data: set `MOCK=1` in `.env`, then `make docker-up && make docker-start`
- Build frontend: `yarn build`
- Build SSR bundle: `yarn build:server`
- Validate types: `yarn validate`

## Development workflow

- **Dev servers always run in Docker** — never use `yarn dev` or `yarn start` locally; web access only works through the Docker reverse proxy.
- Docker/Makefile commands: `make docker-up`, `make docker-start`, `make docker-logs`, `make docker-restart-frontend`.
- Local `yarn` is only for standalone tasks: `yarn build`, `yarn build:server`, `yarn validate`.
- **Mock mode**: Set `MOCK=1` to run the frontend without a tibi-server. API calls are served from JSON files in `frontend/mocking/`. Enable in Docker via `MOCK=1` in `.env`, then `make docker-up && make docker-start`. Missing mock endpoints return 404.
- Frontend code is automatically built by watcher and BrowserSync; backend hooks are automatically reloaded on change.
- Read `.env` for environment URLs and secrets.
- `webserver/` is for staging/ops only; use BrowserSync/esbuild for day-to-day dev.
- If development environment is running, access the website at: `https://${PROJECT_NAME}.code.testversion.online/`.
- To force a restart of the frontend build and dev-server: `make docker-restart-frontend`.
- To show last X lines of docker logs: `make docker-logs-X`.
- Esbuild watches for file changes and rebuilds automatically.
- For a11y testing use MCP a11y tools if available.
- For quick interactive browser testing, ask the user to connect Playwright MCP (preferred) or Browser MCP (only in non-autonomous/chat mode).

## Testing

- Run all tests: `yarn test`
- E2E tests: `yarn test:e2e`
- API tests: `yarn test:api`
- Visual regression: `yarn test:visual`
- After code changes, run only affected spec files: `npx playwright test tests/e2e/filename.spec.ts`.
- Write unit tests for new functionality and ensure existing tests pass.

## Video tours

- Video tours are Playwright-based screen recordings (not tests) in `video-tours/`.
- Run all tours (desktop): `yarn tour`
- Run all tours (mobile): `yarn tour:mobile`
- Videos are saved to `video-tours/output/` (git-ignored).
- Tour files use `.tour.ts` suffix in `video-tours/tours/`.
- Helpers: `injectVisibleCursor()`, `moveThenClick()`, `moveThenType()`, `smoothScroll()` in `video-tours/helpers.ts`.
- Fixtures provide a `tourPage` with visible cursor overlay via `video-tours/tours/fixtures.ts`.

## API access

- API access to collections uses the reverse proxy: `CODING_URL/api/<collection>` (e.g. `CODING_URL/api/content`).
- Auth via `Token` header with ADMIN_TOKEN from `api/config.yml.env`.

## Required secrets and credentials

| Secret | Location | Purpose |
| --- | --- | --- |
| `ADMIN_TOKEN` | `api/config.yml.env` | API admin auth + tibi-admin login |
| `SENTRY_AUTH_TOKEN` | Gitea repo secrets | Sourcemap upload to Sentry (CI only) |
| `.basic-auth-web` | project root (git-ignored) | Basic auth for BrowserSync dev server |
| `.basic-auth-code` | project root (git-ignored) | Basic auth for Code-Server / admin |
| `RSYNC_PASS` | Gitea secrets (`github.token`) | rsync deployment password (CI only) |

**Note:** `.basic-auth-web` and `.basic-auth-code` are plain text files in `user:password` format (htpasswd). They are required by Docker Traefik labels for dev environment access. Curl and Playwright requests are let through without basic auth via Traefik label configuration.

## Infrastructure prerequisites

- **Code-Server environment** — This project is designed for development on a Code-Server instance at `*.code.testversion.online` with a **Traefik reverse proxy** managing HTTPS and auto-routing via Docker labels.
- **Without Code-Server/Traefik** — The Docker stack starts but the website is not reachable via hostname. Workaround: access BrowserSync directly via `http://localhost:3000` (requires exposing the port in `docker-compose-local.yml`).
- **Docker + Docker Compose** — Required for all development. Never run `yarn dev` or `yarn start` locally.
- **MongoDB** — Runs as a Docker service (`mongo`). Data persists in `tmp/mongo-data/`.
- **Production** — Deployed via rsync to an existing server running tibi-server + MongoDB. The frontend is a static SPA served by a Node.js webserver (`webserver/webserver.js`) or directly by tibi-server.
- **Staging** — Docker Compose builds a `www` container that connects to an external tibi-server at `dev-tibi-server.staging.testversion.online`.

## Reference repositories

These sibling repos in the workspace provide documentation, types, and reference implementations:

| Repository | Path | Purpose |
| --- | --- | --- |
| **tibi-types** | `../../cms/tibi-types` | TypeScript type definitions for hooks, collections, permissions, etc. Included via `tsconfig.json` — **read-only, do not modify**. Key file: `index.d.ts`. JSON schemas in `schemas/api-config/`. |
| **tibi-server** | `../../cms/tibi-server` | Go source code of the server. `docs/` has detailed documentation (16 files), `examples/` has sample projects. |
| **tibi-admin-nova** | `../../cms/tibi-admin-nova` | Admin UI reference project. Key file: `types/admin.d.ts` (1147 lines — all admin types: `AdminCollection`, `AdminCollectionField`, `AdminCollectionMeta`, `AdminDashboard`, etc.). Use as reference for collection field configs, dashboard setup, and fieldLists. |

### When to consult which repo

- **Write collection YAML** → `tibi-server/docs/04-collections.md` + `tibi-types/schemas/api-config/collection.json` (JSON schema)
- **Write/debug hooks** → `tibi-server/docs/06-hooks.md` + `tibi-types/index.d.ts` (context types)
- **Configure admin UI** → `tibi-admin-nova/types/admin.d.ts` (field types, meta, dashboard) + `tibi-admin-nova/api/collections/` (real examples)
- **Permissions** → `tibi-server/docs/05-authentication.md`
- **Realtime/SSE** → `tibi-server/docs/07-realtime.md`
- **Images/uploads** → `tibi-server/docs/08-file-upload-images.md`
- **LLM integration** → `tibi-server/docs/09-llm-integration.md`

### TypeScript types

`tibi-types` is included via `tsconfig.json`:

```json
"include": ["frontend/src/**/*", "types/**/*", "./../../cms/tibi-types", "api/**/*"]
```

Project-specific types (e.g. `Ssr`, `ApiOptions`, `ContentEntry`) live in `types/global.d.ts`.

## Code style

- Follow the existing code style and conventions used in the project.
- Write clear and concise comments where necessary to explain complex logic.
- Ensure code is modular and reusable where possible.
- Avoid introducing new dependencies unless absolutely necessary.
- Respect a11y and localization best practices; optimize for WCAG AA standards.
- Check the problems tab for any errors or warnings in the code.
- **Zero warnings policy**: After making changes, always run `yarn validate` and check the IDE problems tab. Fix all TypeScript, Svelte, and Tailwind warnings — the codebase must stay warning-free.
- When Tailwind `suggestCanonicalClasses` warnings appear, always fix the **source** `.svelte`/`.ts`/`.css` file — never the compiled output.

### Architecture skills (loaded on demand)

These skills provide deep-dive documentation. Use them when working on the respective area:

| Skill | When to use |
| --- | --- |
| `content-authoring` | Adding new pages, content blocks, or collections |
| `frontend-architecture` | Routing, state management, Svelte 5 patterns, API layer, error handling |
| `admin-ui-config` | Configuring collection admin views, field widgets, layouts |
| `tibi-hook-authoring` | Writing or debugging server-side hooks |
| `tibi-ssr-caching` | SSR rendering and cache invalidation |
| `tibi-project-setup` | Setting up a new project from scratch |

### Tailwind CSS 4 canonical classes

This project uses Tailwind CSS 4. Always use the canonical v4 syntax:

| Legacy (v3)            | Canonical (v4)         |
| ---------------------- | ---------------------- |
| `bg-gradient-to-*`     | `bg-linear-to-*`       |
| `aspect-[4/3]`         | `aspect-4/3`           |
| `!bg-brand-600`        | `bg-brand-600!`        |
| `hover:!bg-brand-700`  | `hover:bg-brand-700!`  |
| `!rounded-xl`          | `rounded-xl!`          |

Rules:

- Gradient directions use `bg-linear-to-{direction}` instead of `bg-gradient-to-{direction}`.
- Bare-ratio aspect values like `aspect-4/3` replace arbitrary `aspect-[4/3]`.
- The `!important` modifier is a **suffix** (`class!`) instead of a **prefix** (`!class`).