tibi-svelte-starter/.agents/skills/tibi-project-setup/SKILL.md

name, description

name	description
tibi-project-setup	Set up a new tibi project from the tibi-svelte-starter template. Covers cloning, placeholder replacement, environment config, Docker startup, mock mode, demo cleanup, and build verification. Use when creating a new project or onboarding into this template.

tibi-project-setup

When to use this skill

Use this skill when:

• Creating a new project from the tibi-svelte-starter template
• Onboarding into a freshly cloned starter project where placeholders haven't been replaced yet
• The user asks to "set up", "initialize", or "bootstrap" a new tibi project

Goal: a new website project should end up as a fully working tibi-server + tibi-admin-nova project, not just a renamed starter clone.

Prerequisites

• Code-Server environment at *.code.testversion.online
• git, yarn, make, docker compose available
• Traefik reverse proxy running on the host (manages *.code.testversion.online subdomains automatically via Docker labels)

Step 1 — Clone and set up remotes

Skip this step if already inside a cloned project.

# In the workspace directory (e.g. /WM_Dev/src/gitbase.de/cms/)
git clone https://gitbase.de/cms/tibi-svelte-starter.git my-project
cd my-project
git remote rename origin template
# Create a new remote repo (e.g. on gitbase.de) and add as origin:
# git remote add origin https://gitbase.de/org/my-project.git

Verify: git remote -v shows template pointing to the starter and optionally origin pointing to the new repo.

Step 2 — Replace placeholders and starter values

Replace the starter placeholders and starter-derived values in the correct files:

Placeholder	Files	Format	Example
__PROJECT_NAME__	.env	kebab-case (used for URLs, Docker containers, subdomains)	my-project
__TIBI_NAMESPACE__	.env, api/config.yml, frontend/.htaccess	kebab-case, same value as PROJECT_NAME	my-project

PROJECT=my-project        # kebab-case
NAMESPACE=my-project      # same kebab-case value as PROJECT

sed -i "s/__PROJECT_NAME__/$PROJECT/g" .env
sed -i "s/__TIBI_NAMESPACE__/$NAMESPACE/g" .env api/config.yml frontend/.htaccess

Also update the starter-derived values that are not placeholder tokens anymore, especially STAGING_PATH, STAGING_URL, CODING_URL, CODING_TIBIADMIN_URL, api/hooks/config-client.js, and starter metadata in package.json.

Important: The file api/hooks/config-client.js contains a separate placeholder __PROJECT__ (not __PROJECT_NAME__):

# api/hooks/config-client.js has: const originURL = "https://__PROJECT__.code.testversion.online"
sed -i "s/__PROJECT__/$PROJECT/g" api/hooks/config-client.js

Verify all placeholders:

grep -n '__PROJECT_NAME__\|__TIBI_NAMESPACE__\|__PROJECT__\|__ORG__' .env api/config.yml frontend/.htaccess api/hooks/config-client.js
# Expected: no output (all placeholders replaced)

Result in .env:

PROJECT_NAME=my-project
TIBI_NAMESPACE=my-project
CODING_URL=https://my-project.code.testversion.online
STAGING_URL=https://dev-my-project.staging.testversion.online

Common mistakes

• Using different values for PROJECT and NAMESPACE: In this starter, TIBI_NAMESPACE must match PROJECT_NAME and use the same kebab-case value.
• Forgetting frontend/.htaccess: Contains the namespace for API rewrite rules. If missed, API calls from the frontend will fail silently.
• Forgetting api/config.yml: First line is namespace: __TIBI_NAMESPACE__. If not replaced, tibi-server won't start correctly.

Step 3 — Page title

The page title is set dynamically via <svelte:head> in frontend/src/App.svelte. The demo app uses the constant SITE_NAME for this. In a new project, App.svelte is typically rewritten completely — just make sure <svelte:head> with a <title> is present. SSR automatically injects it via the <!--HEAD--> placeholder in spa.html.

Also verify that SSR still renders meaningful page content and not just the shell after the rewrite.

Step 4 — Admin token and config.yml.env

How config.yml.env works: The file api/config.yml.env is not a standard .env file. It is an env-file that the tibi-server reads from the same directory as config.yml. The server resolves ${ADMIN_TOKEN} and ${ADMIN_ASSET_VERSION} variables in the YAML config from this file. This is separate from the project-root .env which serves Docker Compose and the Makefile.

api/config.yml.env ships with a default ADMIN_TOKEN. For production projects, generate a secure one:

token=$(openssl rand -hex 20) && sed -i "s/^ADMIN_TOKEN=.*/ADMIN_TOKEN=$token/" api/config.yml.env

This updates only ADMIN_TOKEN and keeps the other env keys in the file intact.

Verify: cat api/config.yml.env shows a 40-character hex token while preserving entries such as ADMIN_ASSET_VERSION.

Note: The ADMIN_ASSET_VERSION in the same file is used for cache-busting the admin bundle (frontend/dist/admin.mjs). It is auto-generated on build — but if missing, the admin bundle may not load correctly.

Step 5 — Install, upgrade, and start

yarn install
make docker-up      # Start stack in background
# or
make docker-start   # Start stack in foreground (CTRL-C to stop)

Do not blindly run a full dependency upgrade as part of project bootstrap unless the task explicitly includes dependency maintenance. First get the starter running as-is, then upgrade intentionally and validate.

Important: After changing .env or api/config.yml.env, you must run make docker-down && make docker-up for the changes to take effect. Docker Compose reads .env at startup time; tibi-server reads config.yml.env at reload. A simple make docker-restart-frontend is not sufficient for environment variable changes.

Verify containers are running:

make docker-ps      # All containers should be "Up"
make docker-logs    # Check for errors

Step 6 — Verify URLs

Traefik picks up Docker labels automatically — no manual config needed. After make docker-up, these URLs become available:

Service	URL
Website (BrowserSync)	https://{PROJECT_NAME}.code.testversion.online/
Tibi Admin	https://{PROJECT_NAME}-tibiadmin.code.testversion.online/
Tibi Server API	https://{PROJECT_NAME}-tibiserver.code.testversion.online/
Maildev	https://{PROJECT_NAME}-maildev.code.testversion.online/

The subdomains are registered via the Docker label online.testversion.code.subdomain=${PROJECT_NAME}. Traefik watches Docker events and creates routes dynamically.

Verify: curl -sI https://{PROJECT_NAME}.code.testversion.online/ | head -1 returns HTTP/2 200.

Step 7 — Mock mode (optional)

For frontend development without a running tibi-server backend:

# Set in .env:
MOCK=1
# Then full restart (env change requires docker-down first):
make docker-down && make docker-up

When to use mock mode: Early UI prototyping, frontend-only work, CI environments without a database.

Step 8 — Remove demo content

For a real project, remove or replace the demo files:

File/Folder	Content
frontend/src/blocks/	Demo block components (HeroBlock, RichtextBlock, etc.)
frontend/mocking/content.json	Demo mock data for content
frontend/mocking/navigation.json	Demo mock data for navigation
api/collections/content.yml	Content collection config
api/collections/navigation.yml	Navigation collection config
tests/e2e/	Demo E2E tests
video-tours/tours/	Demo video tour

Then adapt frontend/src/App.svelte (header, footer, content loading) to your own data model.

But do not delete starter structures blindly. For a serious project build-out, first decide which parts remain useful foundations:

• SSR pipeline
• i18n route model
• pagebuilder-based content collection
• navigation collection
• media library and image handling
• tests / tours as scaffolding

The goal is not "delete the demo". The goal is "reshape the starter into a project architecture that editors can use productively".

Decision guide:

• Keep demo content if you want to use it as a reference while building your own components.
• Delete immediately if you're starting with a completely custom design and the demo files would only cause confusion.

Step 9 — Build and validate

yarn build          # Frontend bundle for modern browsers
yarn build:server   # SSR bundle (for tibi-server goja hooks)
yarn validate       # TypeScript + Svelte checks (must show 0 errors and 0 warnings)

These commands must succeed before the project is considered set up.

Step 10 — Shape the project for real editor workflows

For a complete website on this starter, setup is not done when Docker runs. It is done when the project has a coherent content/admin model.

Inspect and adapt at least these areas:

• api/collections/content.yml: page types, block schema, SEO, i18n, pagebuilder config
• api/collections/navigation.yml: header/footer structure and editor UX
• frontend/src/blocks/: real block set for the website, not just demo showcase blocks
• frontend/src/blocks/BlockRenderer.svelte: final block registry
• types/global.d.ts: actual project data model
• frontend/src/App.svelte: final shell, content-loading, SSR-safe behavior

For Nova specifically, use current capabilities where they improve the website build process:

• preview for readable row, breadcrumb, and foreign-key display
• sidebar groups for publication/SEO/settings
• containerProps.layout for usable forms
• dependsOn for block-specific fields
• drillDown for complex arrays
• pagebuilder for heterogeneous page content
• subNavigation, singleton, viewHint, and foreign previews where appropriate

For tibi-server specifically, decide early whether the site also needs:

• actions: for forms, newsletter, calculators, imports, or webhooks
• publication-aware SSR invalidation
• field-level permissions
• AI/LLM integration for admin/editor workflows

SSR debugging: manual project reload

After changing collection YAML files, hook code, or config.js (SSR route validation), you may need to trigger a project reload for tibi-server to pick up the changes. Hook files auto-reload, but structural changes (new collections, config changes) require explicit reload:

curl -X POST "$CODING_URL/api/v1/_/$TIBI_NAMESPACE/_/admin/reload" \
  -H "Token: $ADMIN_TOKEN"

The starter's api/config.yml has allowReload: true for the admin token by default. Response {"message": "ok"} confirms the reload.

Use this when:

• A new collection was added to api/config.yml but the API doesn't see it
• Hook files changed but the server hasn't picked them up
• SSR route validation (api/hooks/config.js) was updated and the old behavior persists

Step 11 — Functional verification for a real website project

After the first project shaping pass, verify more than just TypeScript:

yarn build
yarn build:server
yarn validate

Then also verify:

• the public site loads via the website URL
• the Nova admin loads via the admin URL
• pages can be created and edited in admin
• pagebuilder blocks are usable in admin
• SSR renders real page content, not only the shell
• navigation and media references render correctly
• forms/actions work if the project uses them

If the goal is "LLM can build a complete website automatically", the project setup skill must lead to a fully functional content/admin/runtime stack, not merely a placeholder replacement.