cms/tibi-svelte-starter
Template
3
0
Fork 2
Code Issues Pull Requests Projects Releases Wiki Activity

✨ feat: enhance medialib image handling and add asset URL resolution

Browse Source 
- Implemented `resolveApiAssetUrl` function to normalize asset URLs based on API base.
- Updated `MedialibImage` component to utilize new asset URL resolution and added support for alt text and class properties.
- Enhanced image loading behavior with improved width measurement and focal point handling.
- Added placeholder image handling and improved accessibility with alt text.
- Introduced new test script for auditing broken links in skill documentation.
- Expanded seeded test content to include medialib entries and updated related tests for pagebuilder previews.
- Improved global setup and teardown logging for clarity on seeded content management.
This commit is contained in:
Sebastian Frank
2026-05-17 00:52:41 +00:00
parent 958b45272d
commit 4020ad62c5
44 changed files with 4276 additions and 867 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/BUILD_CHECKLIST.md
+607 -206
View File
@@ -1,248 +1,649 @@
# 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.
> 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.
---
## Phase 0: Project Bootstrap
## How to use this checklist
**Skills:** `tibi-project-setup`
For every phase, complete all five parts:
- [ ] Replace all starter placeholders in ALL files:
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: __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
- `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.
## Phase 1: Solution Architecture
**Validation commands:**
**Skills:** `website-solution-architecture`, `security-hardening-and-token-strategy`
```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
```
- [ ] 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?
**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-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)?
- 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 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?
- 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
## Phase 2: Collection & Admin Model
**Validation commands:**
**Skills:** `content-authoring`, `admin-ui-config`, `nova-pagebuilder-modeling`, `nova-navigation-modeling`, `media-seo-publishing`
```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"
```
- [ ] 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
**Exit criteria:**
## Phase 3: TypeScript Types
- [ ] 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.
**Skills:** `content-authoring` (types section)
## Phase 2 — Collection model and Nova admin ergonomics
- [ ] 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
**Required skills:** `content-authoring`, `admin-ui-config`, `nova-pagebuilder-modeling`, `nova-navigation-modeling`, `media-seo-publishing`
## Phase 4: Frontend Components
**Required project artifacts:**
**Skills:** `frontend-architecture`, `nova-pagebuilder-modeling`
- `api/config.yml`
- `api/collections/content.yml`
- `api/collections/navigation.yml`
- `api/collections/medialib.yml`
- domain collection YAML files
- [ ] 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
**Implementation checks:**
## Phase 5: SSR Setup
- [ ] 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.
**Skills:** `tibi-ssr-caching`
**Validation commands:**
- [ ] 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
```bash
yarn validate
```
## Phase 6: Backend Hooks & Actions
Admin validation should also cover:
**Skills:** `tibi-hook-authoring`, `tibi-actions-and-forms`, `scheduled-jobs-and-automation`, `realtime-and-live-workflows`
- 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
- [ ] 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
**Exit criteria:**
## Phase 7: Permissions & Security
- [ ] 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.
**Skills:** `permissions-and-editor-workflows`, `security-hardening-and-token-strategy`
## Phase 3 — Type contracts and API typing
- [ ] 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
**Required skills:** `content-authoring`
## Phase 8: Media & SEO
**Required project artifacts:**
**Skills:** `media-seo-publishing`, `nova-ai-editor-features` (optional)
- `types/global.d.ts`
- `frontend/src/lib/api.ts`
- [ ] 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
**Implementation checks:**
## Phase 9: Testing
- [ ] 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.
**Skills:** `playwright-testing`
**Validation commands:**
- [ ] 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
```
```bash
yarn validate
```
## Phase 10: Video Tours (optional)
**Exit criteria:**
- [ ] 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
```
- [ ] The current project types describe the collection and block model accurately.
- [ ] Validation passes cleanly.
## Phase 11: Final Verification
## Phase 4 — Frontend blocks, routing, and admin registry
**Skills:** `tibi-project-setup` (build steps), `playwright-testing` (test suite)
**Required skills:** `frontend-architecture`, `nova-pagebuilder-modeling`
- [ ] `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`
**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.