# 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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash yarn build:server curl "$CODING_TIBISERVER_URL/api/v1/_//ssr?url=/de/..." curl -I "$CODING_TIBISERVER_URL/api/v1/_//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:** ```bash 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:** ```bash 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:** ```bash curl -H "X-Auth-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:** ```bash yarn validate curl "$CODING_TIBISERVER_URL/api/v1/_//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:** ```bash yarn validate ``` Add feature-specific checks only if the feature is enabled. Feature-specific checks can include: - `curl "$CODING_TIBISERVER_URL/api/v1/_//?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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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.