✨ feat: enhance project setup and architecture documentation
- 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.
This commit is contained in:
@@ -0,0 +1,219 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user