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 starter.

This file is the project-delivery checklist. It is not the maintenance plan for aligning the starter itself against upstream tibi changes or a stronger reference project. For starter-maintenance work, begin with .agents/STARTER_ALIGNMENT_STATUS.md and .agents/STARTER_ALIGNMENT_PLAN.md.

---

How to use this checklist

For every phase, complete all five parts:

1. Required skills
2. Required project artifacts
3. Implementation checks
4. Validation commands
5. Exit criteria

Do not mark a phase done only because code exists. A phase is done only when its outputs and validations are both complete.

Phase 0 — Bootstrap and project registration

Required skills: tibi-project-setup

Required project artifacts:

• README.md
• .env
• api/config.yml
• api/config.yml.env
• api/hooks/config-client.js
• frontend/.htaccess when the deployment path uses the shipped Apache rewrite/proxy file
• package.json
• optional operator-owned root config.yml for the tibi-server instance when the current stack expects server-level config outside the project config

Implementation checks:

• Replace all starter placeholders in every affected file:
  • .env: __PROJECT_NAME__, __TIBI_NAMESPACE__, __ORG__, __PROJECT__
  • api/config.yml: namespace
  • frontend/.htaccess: namespace placeholders when Apache rewrite/proxy is actually used
  • api/hooks/config-client.js: project placeholder
• Replace or remove visible starter identity leftovers in README.md, package.json, and other project-facing metadata.
• Set all required project identity and URL values in .env:
  • PROJECT_NAME
  • TIBI_NAMESPACE
  • LIVE_URL
  • CODING_URL
  • STAGING_URL
  • CODING_TIBIADMIN_URL
  • CODING_TIBISERVER_URL only if the current setup exposes a dedicated raw tibi-server host
• Update package.json project metadata such as package name and repository/default starter references.
• Generate a real ADMIN_TOKEN in api/config.yml.env.
• Ensure ADMIN_ASSET_VERSION exists in api/config.yml.env.
• Decide explicitly which bootstrap path applies:
  • local starter Docker stack from docker-compose-local.yml and Makefile
  • shared or operator-managed tibi-server with explicit server-level config/project registration
• For the local starter Docker path, confirm the repo is mounted into /data and the project serves through the repo-local api/config.yml; do not invent a separate root config.yml or /api/v1/project step.
• For the shared/external tibi-server path, create the root config.yml, register the project, and reload it.
• Confirm local/dev assumptions for Docker, reverse proxy, and any required basic-auth files only when the current environment actually uses them.
• If audit logging or transaction-sensitive features are planned, confirm the MongoDB/replica-set prerequisite for the target environment instead of assuming the local Docker setup is enough.

Validation commands:

rg '__[A-Z0-9_]+__' . --glob '*.{yml,js,env,htaccess,json,md,ts,svelte}'
yarn install
make docker-up
curl -I "$CODING_URL"
curl -I "$CODING_TIBIADMIN_URL"
curl -I "$CODING_URL/api/content?limit=1"
if [ -n "${CODING_TIBISERVER_URL:-}" ]; then curl -I "$CODING_TIBISERVER_URL/api/v1/version"; fi
yarn build
yarn build:server
yarn validate

Exit criteria:

• No unresolved placeholders remain.
• The project no longer advertises starter-default identity in visible metadata.
• The active operator path is explicit and complete.
• If the current stack requires project registration, that registration succeeded.
• Build, SSR build, and validate succeed with 0 warnings.
• Website, admin, and API all respond on the expected URLs.

Phase 1 — Solution architecture and delivery decisions

Required skills: website-solution-architecture, security-hardening-and-token-strategy

Required project artifacts:

• docs/solution-architecture.md or plans/solution-architecture.md
• optional companion notes such as docs/permissions.md or docs/content-model.md when the project is large enough to need them

Implementation checks:

• Create one primary architecture document with explicit sections for:
  • context and scope
  • route and i18n model
  • collections and ownership
  • navigation and pagebuilder
  • forms, actions, jobs, and realtime
  • SSR, publication, and cache behavior
  • permissions and integrations
  • decision matrix
• Document the content model:
  • page types
  • reusable entities
  • singleton/config collections
  • page-local vs reusable data
• Document the route model:
  • language prefix strategy
  • content.path expectations
  • route translations
  • alias/canonical handling
• Document the i18n strategy explicitly:
  • single-language or multilingual
  • field-level i18n or entry-level i18n
  • default language
  • supported languages
  • localized slug/path strategy
• Document forms and workflows:
  • which features are CRUD collections
  • which features are actions
  • whether jobs or realtime are required
  • whether persistence is required
• Document SSR requirements:
  • which routes must SSR
  • which collections are page-critical
  • whether publication windows exist
• Document permissions strategy:
  • human roles
  • token-based integrations
  • hidden/readonly needs
• Make an explicit decision whether the project is single-tenant or needs org/team support.
• Make an explicit decision whether AI/editor assistance, classic search, or embeddings/search are in scope.
• Record a searchable yes/no decision matrix for at least:
  • single-language vs multilingual
  • field-level vs entry-level i18n
  • single-tenant vs org/team
  • AI/editor assistance
  • classic search or embeddings
  • actions/jobs/realtime usage
  • publication scheduling

Validation commands:

arch_doc=$(test -f docs/solution-architecture.md && echo docs/solution-architecture.md || echo plans/solution-architecture.md)
test -f "$arch_doc"
rg 'Route and i18n model|Collections and ownership|Navigation and pagebuilder|SSR, publication, and cache behavior|Permissions and integrations|Decision matrix' "$arch_doc"
rg 'single-language|multilingual|field-level i18n|entry-level i18n' "$arch_doc"
rg 'single-tenant|org/team|AI|search|embedding|actions|jobs|realtime' "$arch_doc"

Exit criteria:

• A later agent can open the architecture document and answer the route, content, SSR, permissions, and i18n questions without guessing.
• The architecture document contains explicit recorded choices for single-language vs multilingual and field-level vs entry-level i18n.
• The project has an explicit yes/no decision recorded for org/team support, AI/editor assistance, and search/embeddings scope.

Phase 2 — Collection model and Nova admin ergonomics

Required skills: content-authoring, admin-ui-config, nova-pagebuilder-modeling, nova-navigation-modeling, media-seo-publishing

Required project artifacts:

• api/config.yml
• api/collections/content.yml
• api/collections/navigation.yml
• api/collections/medialib.yml
• domain collection YAML files

Implementation checks:

• Create or update all required collections in api/collections/.
• Include every collection in api/config.yml.
• Configure meaningful meta.preview for each collection.
• Configure the right meta.viewHint for each collection.
• Configure usable forms with layout, sidebar groups, drillDown, dependsOn, and widget overrides where needed.
• Use pagebuilder plus blockRegistry for block-driven collections.
• Use readable foreign-key previews instead of raw IDs.
• Configure field validators, file acceptance, and image constraints.
• If the project benefits from grouped collection navigation or project-level admin i18n, configure those contracts deliberately instead of leaving them implicit.
• If a collection is effectively single-document config, use singleton deliberately.

Validation commands:

yarn validate

Admin validation should also cover:

• collection sidebar labels and icons
• list previews and columns
• entry-form usability
• foreign-reference readability
• pagebuilder block chooser availability
• pagebuilder preview rendering for at least one representative block when pagebuilder is used

Exit criteria:

• Every collection has a clear admin presentation model.
• Editors can identify and edit entries without raw-ID workflows.
• Pagebuilder-driven collections have a complete block registry and editable block forms.

Phase 3 — Type contracts and API typing

Required skills: content-authoring

Required project artifacts:

• types/global.d.ts
• frontend/src/lib/api.ts

Implementation checks:

• Model all block and domain-entry types in types/global.d.ts.
• Add or update EntryTypeSwitch coverage in frontend/src/lib/api.ts.
• When a block or collection participates in public rendering or admin preview, update all affected types in the same change.
• Keep API and block types aligned with the collection YAML definitions.
• Avoid type drift between the CMS config and the frontend assumptions.

Validation commands:

yarn validate

Exit criteria:

• The current project types describe the collection and block model accurately.
• Validation passes cleanly.

Phase 4 — Frontend blocks, routing, and admin registry

Required skills: frontend-architecture, nova-pagebuilder-modeling

Required project artifacts:

• frontend/src/blocks/*
• frontend/src/blocks/BlockRenderer.svelte
• frontend/src/admin.ts
• routing/i18n files under frontend/src/lib/

Implementation checks:

• Implement every required block component.
• Register every block in BlockRenderer.svelte.
• Register every pagebuilder block in frontend/src/admin.ts.
• Keep blocks SSR-safe.
• Ensure the route layer, i18n layer, and content lookup logic agree on the public URL model.
• If blocks or pages render foreign media/references, confirm lookup expectations explicitly instead of assuming resolved data is present.
• Treat public rendering and admin-preview rendering as the same contract whenever possible.

Validation commands:

yarn build
yarn validate

Exit criteria:

• All configured block types render in the site and in the admin registry.
• Navigation, i18n, and media references behave correctly in the browser.

Phase 5 — SSR, publication model, and cache invalidation

Required skills: tibi-ssr-caching, tibi-hook-authoring

Required project artifacts:

• api/hooks/config.js
• api/hooks/clear_cache.js
• SSR-related hook files under api/hooks/ssr/

Implementation checks:

• Update ssrValidatePath() for the real public route model.
• Ensure publishedFilter matches the actual publication model.
• Ensure ssrPublishCheckCollections covers all time-sensitive collections.
• Confirm page-critical collections are loaded in an SSR-safe way.
• Confirm mutations to content, navigation, media, and publication-critical data invalidate SSR as intended.
• Verify at least one representative mutation path against the SSR response instead of only checking static SSR HTML.
• If lookups are needed for page-critical references, ensure SSR data loading uses them deliberately.

Validation commands:

yarn build:server
curl "$CODING_TIBISERVER_URL/api/v1/_/<namespace>/ssr?url=/de/..."
curl -I "$CODING_TIBISERVER_URL/api/v1/_/<namespace>/ssr?url=/de/..."

Check all of these on the SSR response:

• HTTP status is correct.
• HTML contains the expected page content.
• HTML contains navigation labels.
• window.__SSR_CACHE__ is present.
• a repeated request can return an SSR cache hit where expected.
• after a representative mutation, the next SSR response reflects the change or expected invalidation behavior.

Exit criteria:

• SSR returns correct HTML for valid routes.
• Publication and invalidation behavior is verified, not assumed.

Phase 6 — Hooks, actions, jobs, and realtime

Required skills: tibi-hook-authoring, tibi-actions-and-forms, scheduled-jobs-and-automation, realtime-and-live-workflows

Required project artifacts:

• collection hook files in api/hooks/
• action files in api/actions/ when applicable
• job config/hooks when applicable

Implementation checks:

• Implement public read hooks where public filtering differs from raw CRUD reads.
• Implement cache invalidation hooks for page-critical mutations.
• Use actions for endpoint-like workflows instead of fake CRUD collections.
• For each endpoint-style workflow, record why it is an action and not a collection.
• Respect current action-hook behavior, especially context.data timing.
• If jobs or realtime are used, document why they belong in the project and what they affect.
• Register every hook/action/job in the project config.

Validation commands:

yarn validate

Add targeted API or Playwright checks for:

• anonymous vs token-backed public filtering
• valid vs invalid action submissions
• cache-clear side effects
• job/realtime behavior when those features exist

Exit criteria:

• Backend behavior matches the modeled workflows.
• Endpoint-style features are implemented as actions when appropriate.

Phase 7 — Permissions and security hardening

Required skills: permissions-and-editor-workflows, security-hardening-and-token-strategy

Required project artifacts:

• collection/action permission sections in YAML
• security-relevant config in server/project config
• optional docs/permissions.md for larger projects

Implementation checks:

• Configure collection permissions for public, user, and any custom roles.
• Add explicit token permission sets where machine access is required.
• Use bulk permissions only when there is a real operational need.
• Write down representative permission actors and workflow states before finalizing the YAML.
• Configure readonlyFields, hiddenFields, and any field-level overrides deliberately.
• Use eval-based field rules where editorial state transitions require them.
• Review CORS for real cross-origin requirements instead of weakening it by default.
• Review login rate limiting and secure-cookie expectations for the target environment.
• Review risky hook capabilities such as outbound fetch or command execution and document why they are necessary when used.
• Ensure production secrets come from proper sources rather than committed literals.

Validation commands:

yarn validate

Add targeted API checks for:

• public vs authenticated vs token-backed access
• readonly/hidden enforcement on read and write
• eval-based permission behavior for representative entry states
• at least one allowed and one denied write for each important workflow state

Exit criteria:

• Permissions reflect the real editor/integration model.
• Security-sensitive config and risky capabilities were reviewed explicitly.

Phase 8 — Audit and compliance readiness

Required skills: audit-and-compliance, tibi-hook-authoring

Required project artifacts:

• audit config in the active tibi-server config
• collection-level audit settings when relevant
• audit.return hooks where sensitive data must be stripped

Implementation checks:

• Decide whether audit logging is required for the project.
• If enabled, configure server-level audit settings deliberately.
• If sensitive fields can land in snapshots, add audit.return hooks.
• If hooks/jobs/actions mutate important collections, account for the resulting audit source semantics.
• If audit is required in production, confirm retention/TTL expectations with operations.

Validation commands:

curl -H "X-Auth-Token: <jwt-token>" "$CODING_TIBISERVER_URL/api/v1/audit?limit=5"

Exit criteria:

• The project has an explicit audit decision: enabled with rules, or deliberately not used.
• Sensitive audit exposure has been considered, not ignored.

Phase 9 — Media, SEO, and publication

Required skills: media-seo-publishing, nova-ai-editor-features when AI-assisted media workflows are in scope

Required project artifacts:

• api/collections/medialib.yml
• SEO/publication fields in content or domain collections
• any image-filter configuration used by the frontend or admin

Implementation checks:

• Configure medialib fields, filters, alt/caption handling, and admin widgets.
• Treat the shared media widget/helper boundary as canonical for public, SSR, and admin-preview image rendering.
• Add SEO fields with sensible admin placement.
• Configure social/share image handling where needed.
• Configure the publication model explicitly.
• If publication windows exist, define representative current, future, and expired states.
• Ensure the chosen publication model matches publishedFilter, SSR logic, and editor workflows.

Validation commands:

yarn validate
curl "$CODING_TIBISERVER_URL/api/v1/_/<namespace>/ssr?url=/de/..."

Check for:

• expected media URLs
• expected SEO/meta output in SSR HTML
• expected social/share metadata when used
• expected publication visibility behavior
• representative current/future/expired publication states when timing is used

Exit criteria:

• Media and SEO behavior is verified from schema through SSR/public output.
• Publication state is enforced consistently across schema, public reads, and SSR output.

Phase 10 — Optional AI, search, and enterprise branches

Required skills: nova-ai-editor-features, search-and-embeddings, multi-tenancy-and-orgs

Required project artifacts:

• explicit architecture note even when the answer is “not used”
• AI/action config when enabled
• org/team config or rollout notes when enabled
• embedding/search config when enabled

Implementation checks:

• Record whether editor AI is enabled.
• Record whether embeddings/search are enabled.
• Record whether org/team support is enabled.
• Record whether the project is explicitly single-tenant or org/team-aware.
• If AI is enabled, define provider, model, budget, target fields or action contracts, and failure behavior.
• If org/team support is enabled, define org visibility, team working rights, project assignment rules, and permission ownership.
• If search/embeddings are enabled, define provider setup, search mode, index/search contracts, regeneration expectations, and operator ownership.

Validation commands:

yarn validate

Add feature-specific checks only if the feature is enabled.

Feature-specific checks can include:

• curl "$CODING_TIBISERVER_URL/api/v1/_/<namespace>/<collection>?q=...&qName=..."
• representative org/team visibility or permission checks with the intended auth model

Exit criteria:

• The project has an explicit yes/no decision for AI, search/embeddings, and enterprise org/team support.
• The project has an explicit single-tenant vs org/team-aware decision.
• Enabled optional branches have concrete contracts and not just ideas.

Phase 11 — Operations, deployment, and observability

Required skills: deployment, monitoring-and-performance, mongodb-and-indexes, security-hardening-and-token-strategy

Required project artifacts:

• deployment workflow files
• deploy scripts
• environment and secret configuration
• optional monitoring/operations notes

Implementation checks:

• Configure staging and production deployment paths and URLs.
• Configure CI or other deployment automation.
• Confirm admin reload and SSR cache clear behavior on deploy.
• If Sentry or other observability tooling is used, wire it deliberately.
• If external operators need OpenAPI or metrics, confirm the requirement and the exposure model.
• Confirm MongoDB version, replica-set, persistence, and backup assumptions for the target environment.
• Confirm backup/media persistence assumptions and collection upload paths.

Validation commands:

yarn build
yarn build:server

Operator checks when applicable:

• staging deploy works
• production deploy flow is documented
• admin reload works
• SSR cache clear works
• health endpoints and metrics/OpenAPI exposure behave as expected

Exit criteria:

• The project has a concrete deploy path, not just local Docker success.
• Operational dependencies and visibility expectations are documented.

Phase 12 — Testing and regression coverage

Required skills: playwright-testing, tibi-ssr-caching when SSR-specific checks are needed

Required project artifacts:

• seeded data helpers in tests/api/helpers/
• Playwright specs in the appropriate test slice

Implementation checks:

• Use deterministic seed data for content and any other collections needed by tests.
• Keep seed identity explicit, preferably with hidden _testdata markers.
• Record which seed data was reused or extended for the committed test slice.
• Add API tests for critical collection and action behavior.
• Add desktop E2E tests for core public journeys.
• Add admin smoke tests for stable admin contracts.
• For pagebuilder-driven projects, include committed admin coverage for block chooser/registry behavior and at least one real preview rendering path.
• If SSR is critical, include SSR-specific verification through targeted checks or dedicated tests.
• Record whether SSR proof comes from direct endpoint checks, committed tests, or both.

Validation commands:

npx playwright test tests/api/health.spec.ts --project=api
npx playwright test tests/e2e/home.spec.ts --project=chromium

Add affected project/spec commands for the current project, for example:

• admin smoke specs
• pagebuilder preview specs
• action-specific API specs
• mobile or visual slices when relevant

Leave behind repo-local evidence of which commands were actually used for sign-off.

Exit criteria:

• The test suite reflects the real project contracts, not demo content.
• Critical public, admin, and backend paths have executable regression coverage.
• A later agent can see which specs and SSR checks were used for sign-off.

Phase 13 — Video tours (optional)

Required skills: none mandatory

Required project artifacts:

• tour files in video-tours/tours/ when the project uses them

Implementation checks:

• Add or update tour scripts for the intended training/demo flows.
• Keep desktop and mobile variants aligned when both exist.

Validation commands:

yarn tour
yarn tour:mobile

Exit criteria:

• Tours run successfully when the project uses them.

Phase 14 — Final verification and production readiness

Required skills: tibi-project-setup, playwright-testing

Required project artifacts:

• all previously generated project artifacts
• any remaining project-polish assets

Implementation checks:

• Build and validation are clean.
• Placeholder scan is clean.
• Public site loads.
• Nova admin loads.
• Pages are creatable and editable.
• SSR renders real content.
• Forms/actions work.
• Project polish is complete when the project is meant for real delivery:
  • project image in api/config.yml points to a real project-specific asset
  • prefer a fresh project screenshot captured via Playwright MCP over placeholders or generic graphics
  • resize/compress the chosen project image to a small admin-friendly file size before wiring meta.imageUrl
  • replace starter or temporary collection icons with project-specific icons
  • use thematically fitting free Unsplash/stock images where real customer/project imagery is not yet available; avoid irrelevant placeholders
• Any intentionally deferred items are documented.

Validation commands:

yarn build
yarn build:server
yarn validate
rg '__[A-Z0-9_]+__' . --glob '*.{yml,js,env,htaccess,json,ts,svelte}'

Add the project's affected Playwright command set and any deploy/operator checks required for sign-off.

Exit criteria:

• The project is buildable, testable, and operable.
• No critical checklist phase was skipped implicitly.
• A later agent can continue from the project repository without reconstructing hidden assumptions.