apairon
491f495c66
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
220 lines
6.5 KiB
Markdown
220 lines
6.5 KiB
Markdown
---
|
|
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.
|