---
name: nova-ai-editor-features
description: Use current AI and LLM capabilities in tibi-admin-nova and tibi-server responsibly. Covers media AI assist, LLM provider setup, token budgets, editor-facing AI workflows, and where AI should or should not be used in website projects.
---

# nova-ai-editor-features

## When to use this skill

Use this skill when:

- A website project should use AI-assisted editor workflows
- You want AI help for media metadata, alt texts, captions, or editorial helper flows
- You need to design LLM-backed actions or admin features on top of tibi-server
- You need to decide whether AI belongs in the admin, in actions, or nowhere

## Goal

The goal is to help an LLM build **useful and controllable** AI features for editors.

Use AI where it improves editorial throughput or content quality. Do not add AI just because it exists.

## Source of truth

Use these sources when implementing or reviewing AI-backed website features:

- `tibi-server/docs/09-llm-integration.md`
- `tibi-admin-nova/docs/collection-config.md`
- `tibi-admin-nova/types/admin.d.ts`
- `api/config.yml`
- the project's actual Nova runtime config when such a file exists

## Two AI surfaces in this stack

### 1. Nova media/editor assistance

Nova supports editor-facing AI assistance, especially around media workflows.

Typical pattern:

```yaml
meta:
    viewHint:
        media:
            ai:
                targetField: alt
                prompt: Beschreibe das Bild kurz und sachlich für einen Alt-Text.
                image:
                    maxWidth: 1280
                    maxHeight: 1280
                    quality: 0.82
```

Use this when editors benefit from assisted metadata generation directly in the admin.

### 2. tibi-server LLM proxy and actions

tibi-server provides an LLM proxy with:

- provider configuration
- model whitelisting
- streaming support
- user and org token budgets
- usage logging

This is the right foundation when a project needs controlled backend LLM usage.

## Recommended AI use cases for websites

Good use cases:

- alt text suggestions for uploaded images
- caption or summary suggestions for media-heavy content
- internal editorial helper actions
- controlled rewrite or classification helpers for structured content
- AI support in specialized admin workflows where output is reviewed by humans

Weak or risky use cases:

- auto-publishing public text without review
- replacing the content model with one giant AI prompt field
- hiding important business logic inside opaque prompts
- bypassing permissions or audit trails through AI shortcuts

## AI for media collections

For image-heavy collections, prefer AI as **assistive autofill**, not as a silent overwrite mechanism.

Use Nova media AI when:

- the editor already works inside a media-oriented screen
- the target field is explicit
- the generated text is reviewable
- existing manual values are not overwritten automatically

Prefer explicit target fields such as:

- `alt`
- `caption`
- `localizedCaption.de`

## LLM provider architecture

When enabling server-side LLM usage, define:

- which providers are configured
- which models are allowed
- which model is default
- max tokens per request
- which users or orgs have budgets

Never assume arbitrary models are available. Model choice must stay inside the configured whitelist.

## Token budget design

Use budgets deliberately.

If a project adds editor-facing AI features, define:

- which users may use them
- per-provider token budgets
- org-level budgets if multiple editors share a pool
- expected failure behavior when budgets are exhausted

An editor-facing AI workflow is incomplete if the quota/failure path is not planned.

## Where AI logic should live

Choose the surface intentionally:

- **Nova media AI** for direct editor assistance in image/media workflows
- **Action endpoint** for reusable backend AI workflows with validation and auditing
- **Collection config only** when Nova already provides the needed behavior declaratively

Do not push provider credentials or prompt orchestration into the browser.

## Prompting rules for serious projects

Prompts should be:

- narrow in purpose
- reviewable by humans
- tied to an explicit target field or action contract
- stable enough that editors know what the feature does

Avoid vague prompts such as “improve this content” when the output target and editorial rules are unclear.

## AI + permissions + audit

AI features must still respect:

- field-level permissions
- hidden/readonly fields
- action permissions
- org/user budget boundaries
- logging/auditing expectations

Do not let AI become a side channel around your normal content governance.

## Recommended implementation patterns

### Media alt-text assist

Recommended shape:

- media-oriented collection or view
- `viewHint.media.ai.targetField`
- prompt focused on accessibility and factual image description
- human review before publishing

### Editorial helper action

Recommended shape:

- authenticated action endpoint
- input validation
- provider/model chosen from allowed config
- stable structured response for the admin/frontend
- logging and budget-aware failure handling

### AI-backed enrichment workflow

Recommended shape:

- action reads current entry state
- generates suggestion only
- stores result in explicit reviewable fields or returns suggestion to editor
- never silently mutates unrelated content

## Anti-patterns

- Enabling AI without provider/budget planning
- Using AI for public content generation without editorial review
- Letting AI write into fields that editors should not modify manually
- Hiding core business logic inside prompts instead of code/config
- Treating AI as a replacement for structured content modeling

## Verification checklist

After adding AI-backed editor features, verify all of these:

1. Provider and model configuration are valid.
2. Token budgets and failure modes are defined.
3. The AI target field or action contract is explicit.
4. Editors can review the result before publication when appropriate.
5. Permissions and audit expectations still hold.
6. `yarn validate` stays clean.

## What an LLM should inspect first

When asked to add AI to a website project on this starter, inspect in this order:

1. `tibi-server/docs/09-llm-integration.md`
2. current collection meta for media/admin workflows
3. whether the use case fits Nova media AI, an action, or both
4. user/org budget expectations
5. the exact target field or response contract

This prevents random “AI features” that have no operational boundaries.