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:

  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:

  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:

  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