tibi-svelte-starter/AGENTS.md

AGENTS.md

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

Skill auto-improvement

Skills in .agents/skills/ are automatically updated when the agent discovers patterns, gotchas, or workflows that are:

• Generic enough to apply across projects (not project-specific workarounds)
• Missing from the current skill documentation
• Important enough to prevent the same mistake in future projects

If you see an agent updating a skill file, it is capturing reusable knowledge. Review skill diffs to stay informed about evolving conventions.

Token header distinction

• System-level API (raw tibi-server project CRUD, raw admin reload, server ops): use X-Admin-Token header
• Collection-level API (CRUD on content, navigation, etc.): use the header name defined by the collection permission key. In this starter that is typically Token via permission entries such as token:${ADMIN_TOKEN}.
• User-level API (JWT-authenticated requests): use X-Auth-Token header

Medialib image URL pattern

In this starter, medialib URLs are derived from the entry ID plus the stored relative file.src value. If file.src is file/example.jpg, the project-local URL is /api/medialib/{entryId}/file/example.jpg. Shared widgets such as MedialibImage append responsive filters as query params, for example /api/medialib/{entryId}/file/example.jpg?filter=l-webp. These /api/... URLs are starter-local proxy URLs. Do not hardcode file/file.

Project overview

• Frontend: Svelte 5 SPA in frontend/src/, esbuild, Tailwind CSS 4.
• Backend: tibi-server with hooks in api/hooks/, collections in api/collections/.
• SSR: goja (Go JS runtime) in api/hooks/ssr/.
• Tests: Playwright in tests/ (API, E2E, mobile, visual).
• Types: types/global.d.ts (project), tibi-types/ (read-only, from sibling repo).

Key constraints

• Dev servers always run in Docker — never yarn dev or yarn start locally.
• yarn is for standalone tasks: build, build:server, validate.
• Bootstrap details (placeholder replacement, docker setup) → tibi-project-setup skill.
• Build checklist for full website projects → .agents/BUILD_CHECKLIST.md.
• Starter maintenance current state → .agents/STARTER_ALIGNMENT_STATUS.md.
• Starter maintenance and upstream/reference alignment workflow → .agents/STARTER_ALIGNMENT_PLAN.md.

Project delivery workflow

When building a new website project from this starter, work through .agents/BUILD_CHECKLIST.md phase by phase. Do not skip phases, even when individual checklist items are already satisfied by the starter defaults.

For each phase:

1. Load the required skills listed in that phase.
2. Create or update the required project artifacts.
3. Work through every [ ] implementation check.
4. Run the listed validation commands. A phase is not done until all validations pass.
5. Mark each [ ] as [x] only when the concrete check is satisfied and its validation command passes cleanly.
6. Confirm all exit criteria before moving to the next phase.

The checklist covers the full delivery lifecycle: bootstrap → architecture → collections → types → frontend → SSR → hooks/actions → permissions → audit → media/SEO → optional branches → ops/deploy → tests → final verification.

Quick reference

Action	Command
Start dev stack	make docker-up or make docker-start
Restart frontend	make docker-restart-frontend
Logs	make docker-logs
Build frontend	yarn build
Build SSR	yarn build:server
Validate	yarn validate
Run all tests	yarn test
Run E2E tests	yarn test:e2e
Run API tests	yarn test:api

Testing notes

• Tests read CODING_URL from .env. Ensure it serves both / and /api/....
• After changes, run only affected specs: npx playwright test tests/e2e/filename.spec.ts.
• CI runs yarn validate but not Playwright (needs MongoDB + tibi-server).

API access

• Token header with ADMIN_TOKEN from api/config.yml.env when the collection permission key is token:${ADMIN_TOKEN}.
• Collection user: permissions apply to JWT auth (X-Auth-Token), not static Token:.
• For write access via ADMIN_TOKEN, add "token:${ADMIN_TOKEN}": { methods: { post: true, put: true } } to the collection permissions.
• The current deploy scripts call the reverse-proxied reload endpoint on LIVE_URL or STAGING_URL with Authorization: Bearer ${ADMIN_TOKEN}. Treat that as a separate project-local proxy surface from raw tibi-server project CRUD APIs.

Required secrets

Secret	Location	Purpose
ADMIN_TOKEN	api/config.yml.env	API/admin access token
ADMIN_ASSET_VERSION	api/config.yml.env	Cache-busting for admin bundle (auto-generated)
.basic-auth-web	project root (git-ignored)	BrowserSync basic auth
.basic-auth-code	project root (git-ignored)	Code-Server basic auth

Generated dev defaults in api/config.yml.env may be committed. Production values are overwritten in CI/CD via secrets.

TypeScript

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

• Domain types (entities, block props, API responses) be strict. any/[key: string]: any OK for inherently dynamic data (MongoDB filters, CMS fields, hook payloads).
• No @ts-ignore — use /** @type {…} */ cast instead.
• Zero warnings policy: always run yarn validate after changes; fix all warnings.
• Svelte 5 with Runes: $props(), $state(), $derived(), $effect().

Svelte 5 patterns

• Prop destructuring: Destructuring block from $props() into local variables triggers state_referenced_locally warnings. The values capture initial state and lose reactivity. Either access through the parent object (block.headline) or use $derived for each value.
• $derived.by(): Use for multi-statement derived values: let filtered = $derived.by(() => { if (x) return a; return b; })
• class: directive: Invalid with / in class names like class:text-white/85. Use ternary in class attribute instead: class={condition ? 'text-white/85' : ''}.

Reference repositories (sibling repos)

Repo	Path	Key file
tibi-types	../tibi-types	index.d.ts (context types), schemas/config/collection.schema.json
tibi-server	../tibi-server	docs/ (20 files: collections, hooks, auth, actions, SSE, jobs, etc.)
tibi-admin-nova	../tibi-admin-nova	types/admin.d.ts (all admin config types)

When to consult which repo

• Collection YAML → tibi-server/docs/04-collections.md + tibi-types/schemas/config/collection.schema.json
• Hooks → tibi-server/docs/06-hooks.md + tibi-types/index.d.ts
• Admin UI config → tibi-admin-nova/types/admin.d.ts + tibi-admin-nova/docs/collection-config.md
• Permissions → tibi-server/docs/05-authentication.md
• Actions/forms → tibi-server/docs/19-actions.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
• Field-level permissions → tibi-server/docs/17-field-level-permissions.md

API lookup für aufgelöste Referenzen

Beim Laden von Collections können Fremdschlüssel via lookup-Parameter automatisch aufgelöst werden:

// entries mit aufgelösten medialib-Bildern laden
const entries = await getCachedEntries<"content">("content", {
	filter: { active: true },
	sort: "sort",
	lookup: "blocks.heroImage.image:medialib"
})
// Ergebnis: entry._lookup enthält die aufgelösten Referenzen

Der lookup-Parameter wird im Optionen-Objekt an getCachedEntries übergeben. Ohne lookup bleiben Referenzfelder reine ID-Werte ohne _lookup.

Tailwind CSS 4

Canonical v4 syntax — no v3 legacy classes:

v3	v4
bg-gradient-to-*	bg-linear-to-*
aspect-[4/3]	aspect-[4/3] (v4 hat nur aspect-square/aspect-video als Built-in-Utilities; benutzerdefinierte Ratios bleiben arbitrary)
!bg-brand-600	bg-brand-600!
hover:!bg-brand-700	hover:bg-brand-700!

Architecture skills (loaded on demand)

Use these tables as the lookup index. Each skill is a deep-dive for its domain.

1. Project start and solution design

Skill	When
tibi-project-setup	Bootstrap a new project from scratch
website-solution-architecture	Translate requirements into collections, blocks, SSR, workflows
security-hardening-and-token-strategy	Token strategy, secrets, hook risk surfaces, CORS

2. Content model and editor UX

Skill	When
content-authoring	Add pages, block types, collections, and required type/registry wiring
nova-pagebuilder-modeling	Block schemas, preview, drillDown, dependsOn
nova-navigation-modeling	Header/footer trees, viewHint.navigation, declaredTrees
admin-ui-config	Field widgets, sidebar, layout, choices, foreign refs
media-seo-publishing	Image fields, alt/caption, SEO, publication model
permissions-and-editor-workflows	Field-level readonly/hidden, 3-layer cascade, custom roles
nova-ai-editor-features	AI-assisted alt text, LLM actions, token budgets

3. Backend behavior

Skill	When
tibi-hook-authoring	Write/debug server-side hooks (goja)
tibi-actions-and-forms	Contact forms, newsletter, webhooks, action endpoints
scheduled-jobs-and-automation	Cron tasks, cleanup, reports, sync
realtime-and-live-workflows	SSE channels, live notifications, preview refresh
audit-and-compliance	Audit logging, retention, audit.return filtering, source semantics

4. Frontend and delivery

Skill	When
frontend-architecture	SPA router, stores, Svelte 5 patterns, API layer
tibi-ssr-caching	SSR rendering, cache invalidation, 404 signaling
playwright-testing	Deterministic seed data, API/E2E/admin/visual tests
deployment	Production deployment setup, Basispanel subdomains, CI, rsync, staging

5. Operations and diagnostics

Skill	When
mongodb-and-indexes	Mongo prerequisites, replica set, indexes, persistence, backup assumptions
monitoring-and-performance	OpenAPI, metrics, Sentry, reachability and observability checks
troubleshooting-and-debugging	Common stack failures, hook/runtime debugging, config/auth diagnosis

6. AI, search, and enterprise

Skill	When
search-and-embeddings	Search modes, embedding providers, regeneration, semantic retrieval
multi-tenancy-and-orgs	Org/team isolation, enterprise permissions, visibility vs working rights