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.

New project from this template? Follow the step-by-step guide in README.md.

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

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

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

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.

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

tibi-types is included via tsconfig.json:

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

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

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.

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

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