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

```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/_/<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:**

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

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

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

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