tibi-svelte-starter/.agents/BUILD_CHECKLIST.md

# Build Checklist — Autonomous Website Project

> Navigate this checklist **in order** when building a complete website project from the `tibi-svelte-starter`. Each phase produces concrete artifacts. Do not skip phases — earlier decisions constrain later ones.

---

## Phase 0: Project Bootstrap

**Skills:** `tibi-project-setup`

- [ ] Replace all starter placeholders in ALL files:
  - `.env`: `__PROJECT_NAME__`, `__TIBI_NAMESPACE__`, `__ORG__`, `__PROJECT__`
  - `api/config.yml`: `namespace: __TIBI_NAMESPACE__`
  - `frontend/.htaccess`: both `__TIBI_NAMESPACE__` entries
  - `api/hooks/config-client.js`: `__PROJECT__` (not `__PROJECT_NAME__`)
- [ ] Configure `.env` URLs: `CODING_URL`, `STAGING_URL`, `CODING_TIBIADMIN_URL`
- [ ] Update `package.json` metadata (name, repository)
- [ ] Run `grep -n '__[A-Z0-9_]\+__' . --include='*.{yml,js,env,htaccess,json}'` to verify no placeholder remains
- [ ] Generate secure `ADMIN_TOKEN` in `api/config.yml.env`
- [ ] Verify `ADMIN_ASSET_VERSION` exists in `api/config.yml.env` (re-generate if missing: `echo "ADMIN_ASSET_VERSION=$(node -e "process.stdout.write(require('crypto').randomBytes(6).toString('hex'))")-dirty-${Date.now()}" >> api/config.yml.env`)
- [ ] `yarn install` — must succeed
- [ ] `make docker-up` — verify all containers "Up"
- [ ] Verify URLs respond: website, tibiadmin, tibiserver API
- [ ] `yarn build && yarn build:server && yarn validate` — 0 errors, 0 warnings

## Phase 1: Solution Architecture

**Skills:** `website-solution-architecture`, `security-hardening-and-token-strategy`

- [ ] Document the website's content model:
  - Which page types exist?
  - Which data is page-local vs. reusable?
  - Which domain collections exist (team, products, events, etc.)?
  - Is content multilingual? Entry-level or field-level i18n?
- [ ] Document the navigation model:
  - Header, footer, utility navigation?
  - Language-specific or shared?
  - Max nesting levels per tree?
- [ ] Document the route model:
  - Language-prefixed URLs (`/{lang}/{path}`)?
  - Content `path` stored without language prefix?
  - Route translations needed?
- [ ] Document forms/workflows:
  - Contact form, newsletter, booking, etc.?
  - Action endpoints or collections?
  - Persistence needed (inquiries collection)?
- [ ] Document SSR requirements:
  - Which routes are SSR-valid?
  - Which collections are page-critical (content, navigation)?
  - Publication windows needed?
- [ ] Document permissions:
  - Who can CRUD which collections?
  - Field-level readonly/hidden for editors?
  - Token-based integrations?

## Phase 2: Collection & Admin Model

**Skills:** `content-authoring`, `admin-ui-config`, `nova-pagebuilder-modeling`, `nova-navigation-modeling`, `media-seo-publishing`

- [ ] Create/modify collection YAML files in `api/collections/`:
  - `content.yml` with pagebuilder blocks
  - `navigation.yml` with `viewHint.navigation`
  - `medialib.yml` with media library
  - Domain collections (team, products, events, etc.)
  - `ssr.yml` (SSR cache — keep as-is)
- [ ] Include all collections in `api/config.yml`
- [ ] Configure admin ergonomics for EVERY collection:
  - `meta.preview` for row/breadcrumb/FK display
  - `meta.viewHint` (table, cards, media, navigation)
  - `sidebar` groups for publication/SEO/settings
  - `containerProps.layout` for multi-column forms
  - `drillDown` for complex `object[]` arrays
  - `dependsOn` for conditional fields
  - `pagebuilder` + `blockRegistry` for block-based collections
  - `singleton` for single-document config collections
  - `choices`, `foreign`, `widget` overrides as needed
- [ ] Configure field validators:
  - `required`, `maxLength`, `min`, `max` where appropriate
  - `accept` MIME types for file fields
  - `image` dimension constraints for image fields
  - `format: "email" | "url" | "slug"` for string fields
- [ ] Verify in Nova admin:
  - Collection sidebar labels, icons, groups
  - List views show meaningful previews
  - Entry forms are usable (not one long scrolling column)
  - Sidebar groups and sections are coherent
  - Foreign references show readable previews
  - Pagebuilder blocks are selectable and editable

## Phase 3: TypeScript Types

**Skills:** `content-authoring` (types section)

- [ ] Create/modify `types/global.d.ts`:
  - `ContentBlockEntry` fields matching collection YAML subFields
  - Domain collection entry types (e.g. `TeamEntry`, `ProductEntry`)
  - `Ssr` type for SSR config interface
- [ ] Wire collection types into `EntryTypeSwitch` in `frontend/src/lib/api.ts`
- [ ] `yarn validate` — 0 errors, 0 warnings

## Phase 4: Frontend Components

**Skills:** `frontend-architecture`, `nova-pagebuilder-modeling`

- [ ] Create block components in `frontend/src/blocks/`:
  - Each block type gets a Svelte 5 component
  - Accept `block: ContentBlockEntry` as props
  - SSR-safe (guard browser APIs with `typeof window !== "undefined"`)
- [ ] Register blocks in `frontend/src/blocks/BlockRenderer.svelte`:
  - Add `import` and `{:else if}` case for each type
- [ ] Register pagebuilder blocks in admin bundle:
  - Add each block to `blockRegistry` in `frontend/src/admin.ts`
  - `yarn build` to regenerate `frontend/dist/admin.mjs`
- [ ] Verify frontend rendering:
  - `yarn build` succeeds
  - Page loads in browser
  - All block types render
  - Navigation and media references work
  - Language switching works

## Phase 5: SSR Setup

**Skills:** `tibi-ssr-caching`

- [ ] Update `api/hooks/config.js`:
  - `ssrValidatePath()` validates all public routes
  - `publishedFilter` matches the publication model
  - `ssrPublishCheckCollections` includes all time-sensitive collections
- [ ] Verify SSR endpoint directly:
  ```bash
  curl "http://tibiserver:8080/api/v1/_/<namespace>/ssr?url=/de/..."
  ```
  - HTTP status correct
  - Page content present in HTML
  - Navigation labels present in HTML
  - `window.__SSR_CACHE__` present
  - Second request returns `X-SSR-Cache: true`
  - `yarn build:server` succeeds

## Phase 6: Backend Hooks & Actions

**Skills:** `tibi-hook-authoring`, `tibi-actions-and-forms`, `scheduled-jobs-and-automation`, `realtime-and-live-workflows`

- [ ] Create/update public read hooks (`api/hooks/<collection>/get_read.js`):
  - Filter inactive/unpublished entries for public users
  - Use `filter_public.js` pattern
- [ ] Create/update cache invalidation hooks (`api/hooks/clear_cache.js`):
  - Clear SSR cache on content/navigation/medialib changes
  - Handle `POST`, `PUT`, `DELETE` for each collection that affects SSR
- [ ] Create action endpoints in `api/actions/`:
  - Contact form, newsletter, etc.
  - Hook chain: bind → validate → handle → return
  - Permissions per action (public vs. authenticated)
  - Wire into `api/config.yml` under `actions:`
- [ ] Register all hooks in collection/action YAML files
- [ ] Verify hooks work:
  - Public API returns only active entries
  - Actions respond correctly to valid/invalid submissions
  - Cache clears on content mutation

## Phase 7: Permissions & Security

**Skills:** `permissions-and-editor-workflows`, `security-hardening-and-token-strategy`

- [ ] Configure collection permissions:
  - `public` read methods where appropriate
  - `user` write methods for editors
  - `"token:${ADMIN_TOKEN}"` for seed/test access
- [ ] Configure field-level permissions:
  - `readonlyFields` at collection or permissionSet level
  - `hiddenFields` for sensitive internal data
  - `readonly`/`hidden` with eval for dynamic rules
- [ ] Secure sensitive config:
  - Production `ADMIN_TOKEN` uses a real random value
  - Hook `http.fetch` and `exec.command` used with caution
- [ ] Verify: non-admin users see only permitted fields/collections
- [ ] Verify CORS if external origins access the API

## Phase 8: Media & SEO

**Skills:** `media-seo-publishing`, `nova-ai-editor-features` (optional)

- [ ] Configure `api/collections/medialib.yml`:
  - File field with `widget: image`
  - Alt text, caption fields
  - Image filters for thumbnails, cards, heroes
- [ ] Add SEO fields to content/page collections:
  - `meta.title`, `meta.description`
  - Social share image reference
  - Sidebar placement for SEO fields
- [ ] Configure publication model:
  - `active` boolean
  - `publication.from` / `publication.to` if time-based
  - SSR-aware cache invalidation for publication changes
- [ ] Verify: SSR HTML includes SEO meta tags

## Phase 9: Testing

**Skills:** `playwright-testing`

- [ ] Extend seed data in `tests/api/helpers/seed-data.ts`:
  - Seeded pages for all public routes
  - Seeded navigation entries
  - Hidden `_testdata: true` marker for seed identity
- [ ] Write API tests for collections:
  - Public reads return expected data
  - Auth-required writes are enforced
  - Actions respond correctly
- [ ] Write E2E tests for critical user journeys:
  - Homepage loads
  - Language switching works
  - SPA navigation works
  - Each block type renders
  - 404 for non-existent pages
- [ ] Write admin smoke tests if admin workflows are stable:
  - Login works
  - Core collections are reachable
- [ ] Run affected tests:
  ```bash
  npx playwright test tests/api/health.spec.ts --project=api
  npx playwright test tests/e2e/home.spec.ts --project=chromium
  ```

## Phase 10: Video Tours (optional)

- [ ] Update/create tour files in `video-tours/tours/`:
  - Key user flows for documentation/training
  - Desktop and mobile variants
- [ ] Run tours and verify output:
  ```bash
  yarn tour && yarn tour:mobile
  ```

## Phase 11: Final Verification

**Skills:** `tibi-project-setup` (build steps), `playwright-testing` (test suite)

- [ ] `yarn build` — success
- [ ] `yarn build:server` — success
- [ ] `yarn validate` — 0 errors, 0 warnings
- [ ] `rg '__[A-Z0-9_]\+__' . --include='*.{yml,js,env,htaccess,json,ts,svelte}'` — no placeholder remains
- [ ] All Playwright tests pass (or known failures documented)
- [ ] Public site loads at website URL
- [ ] Nova admin loads at admin URL
- [ ] Pages are creatable and editable in admin
- [ ] SSR renders real page content
- [ ] Forms/actions work (if applicable)
- [ ] `config.yml.env` has production-ready `ADMIN_TOKEN`