my-notes-viewer/.agents/skills/tibi-project-setup/SKILL.md

---
name: tibi-project-setup
description: 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.

```sh
# 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` |

```sh
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__`):

```sh
# 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:**

```sh
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`:**

```dotenv
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:

```sh
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

```sh
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:**

```sh
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:

```sh
# 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

```sh
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:

```bash
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:

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