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.

Project bootstrap

Before treating this repo as a real project, replace the starter placeholders and initial project values.

Derive these values from the real repo path gitbase.de/ORG/REPO:

• PROJECT_NAME: use the repo name in kebab-case.

• TIBI_NAMESPACE: set it equal to PROJECT_NAME, i.e. use the same repo name in kebab-case.

• STAGING_PATH: use the real repo org and repo name, i.e. /staging/ORG/REPO/dev.

• .env: replace PROJECT_NAME=__PROJECT_NAME__, TIBI_NAMESPACE=__TIBI_NAMESPACE__, STAGING_PATH=/staging/__ORG__/__PROJECT__/dev, STAGING_URL=https://dev-__PROJECT_NAME__.staging.testversion.online, and CODING_URL=https://__PROJECT_NAME__.code.testversion.online.

• api/config.yml: replace namespace: __TIBI_NAMESPACE__.

• frontend/.htaccess: replace both __TIBI_NAMESPACE__ proxy targets.

• api/hooks/config-client.js: replace https://__PROJECT__.code.testversion.online with the real origin URL.

• package.json: adapt starter metadata like name and repository when creating the real project repo.

• Docker and local URLs derive from .env, so PROJECT_NAME and TIBI_NAMESPACE must be correct before make docker-up.

• Playwright seed/API tests read CODING_URL from .env first. Use the configured host from .env whenever it serves both / and /api/..., even in starter-style local bootstrap setups.

• Recommended check: search for remaining starter placeholders with rg '__[A-Z0-9_]+__' ..

Setup commands

• Install deps: yarn install
• Start dev: make docker-up or make docker-start
• Restart frontend watcher/dev-server: make docker-restart-frontend
• View logs: make docker-logs or make docker-logs-X
• Start with mock data: set MOCK=1 in .env, then use the normal Docker start command
• Build frontend/admin bundle: 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.
• 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/. Missing mock endpoints return 404.
• Frontend code is automatically rebuilt by the watcher/BrowserSync stack; backend hooks reload 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/.
• 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
• Before running Playwright, ensure the CODING_URL from .env actually serves both / and /api/... for this repo.
• 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 when a configured token with the required permissions is needed.
• Collection permissions for user: apply to JWT-authenticated users (X-Auth-Token), not to the static Token: header.
• If a collection should allow writes via ADMIN_TOKEN, define an explicit permission block like "token:${ADMIN_TOKEN}": with the required methods.

Required secrets and credentials

Secret	Location	Purpose
ADMIN_TOKEN	api/config.yml.env	Access token for configured API/admin permissions
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)

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:

"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 by phase instead of treating them as an unsorted reference list.

1. Project start and solution design

Skill	When to use
tibi-project-setup	Setting up a new project from scratch
website-solution-architecture	Translating website requirements into a complete solution across content, admin, SSR, and workflows
security-hardening-and-token-strategy	Applying secure token, secret, permission, and hook-capability decisions

2. Content model and editor UX

Skill	When to use
content-authoring	Adding new pages, content blocks, or collections
nova-pagebuilder-modeling	Designing editor-friendly block systems, nested block schemas, and pagebuilder UX
nova-navigation-modeling	Modeling multilingual header/footer/navigation trees with current Nova navigation features
admin-ui-config	Configuring collection admin views, field widgets, layouts
media-seo-publishing	Modeling media, SEO, and publication workflows for website projects
permissions-and-editor-workflows	Designing safe editorial permissions, field rules, and role-aware admin workflows
nova-ai-editor-features	Applying AI and LLM capabilities in editor workflows and media authoring responsibly

3. Backend behavior and integrations

Skill	When to use
tibi-hook-authoring	Writing or debugging server-side hooks
tibi-actions-and-forms	Building contact forms, workflow endpoints, and other action-based website features
scheduled-jobs-and-automation	Building cron-based background tasks, cleanups, reports, and sync workflows
realtime-and-live-workflows	Designing SSE-based live updates, notifications, previews, and status workflows

4. Frontend runtime and delivery

Skill	When to use
frontend-architecture	Routing, state management, Svelte 5 patterns, API layer, error handling
tibi-ssr-caching	SSR rendering and cache invalidation
playwright-testing	Extending or debugging seeded Playwright API, desktop, mobile, or visual tests

Quickstart roadmap for a new website

Use this order when building a project from scratch on this starter:

1. Foundation. Start with tibi-project-setup until Docker, URLs, build, and validate are green.

2. Solution design. Use website-solution-architecture first, then security-hardening-and-token-strategy, before writing components or hooks.

3. Content and admin model. Use the skills from Content model and editor UX to shape api/collections/content.yml, api/collections/navigation.yml, reusable domain collections, and Nova authoring UX.

4. Frontend and runtime. Use frontend-architecture plus nova-pagebuilder-modeling when wiring routing, i18n, content loading, frontend/src/blocks/BlockRenderer.svelte, and shared types.

5. Backend behavior. Use the skills from Backend behavior and integrations for hooks, forms/actions, jobs, and realtime only where the project actually needs them.

6. SSR and publishing. Use tibi-ssr-caching once routes, navigation, and page-critical data are defined, and use media-seo-publishing plus permissions-and-editor-workflows where publication, SEO, and editorial restrictions matter.

7. Optional AI editor features. Use nova-ai-editor-features only when there is a concrete editorial workflow for it.

8. Final verification. Use playwright-testing for deterministic API/E2E coverage, confirm public site, admin authoring, pagebuilder rendering, navigation/media resolution, forms/actions, and SSR all work, then run yarn build, yarn build:server, and yarn validate.

For one-off tasks, use the phase tables above as the lookup index instead of maintaining a second skill matrix here.

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