@fias/create-fias-plugin 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -175,7 +175,7 @@ function AISummarizer() {
 
   async function summarize(text: string) {
     await invoke({
-      entityId: 'ent_fias_ai', // the AI model capability
+      entityId: { capability: 'text-standard' }, // a platform text capability — see "Choosing a text model" below
       input: text, // what to process
       systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
     });
@@ -198,7 +198,44 @@ function AISummarizer() {
 }
 ```
 
-The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+
+#### Choosing a text model
+
+The `entityId` parameter accepts three forms. **Prefer the capability selector** over a hardcoded model id: the platform's models evolve and get retired, and a capability lets your plugin pick up the current best model automatically without a code edit. When the platform retires the model behind a capability, it re-points the capability — your plugin keeps working.
+
+```tsx
+// 1. By capability (recommended) — resolved to the platform's current model
+//    for that tier, and re-pointed automatically if that model is retired.
+await invoke({
+  entityId: { capability: 'text-standard' }, // 'text-fast' | 'text-standard' | 'text-advanced'
+  input,
+  systemPrompt: '...',
+});
+
+// 2. AI router — let the platform pick a model per request based on the
+//    query's complexity. Optionally bias the tier with routingPreference.
+await invoke({
+  entityId: 'ent_fias_ai',
+  input,
+  systemPrompt: '...',
+  routingPreference: 'cost', // 'auto' (default) | 'speed' | 'cost' | 'balanced' | 'performance'
+});
+
+// 3. A specific model id (back-compat) — pins one model. It will stop working
+//    if that model is retired; use a capability for retirement resilience.
+await invoke({ entityId: 'ent_modeldef_haiku_45', input, systemPrompt: '...' });
+```
+
+The text capabilities:
+
+| Capability      | Use it for                                                                   |
+| --------------- | ---------------------------------------------------------------------------- |
+| `text-fast`     | Cheapest, fastest — classification, extraction, short responses, high volume |
+| `text-standard` | Balanced, general-purpose text generation (the sensible default)             |
+| `text-advanced` | Most capable — complex reasoning, nuanced writing, long-form output          |
+
+Browse specific models with `npx fias-dev entities`.
 
 ### `useImageGeneration()` — Generate images via AI models
 

package/templates/default/CLAUDE.md

@@ -175,7 +175,7 @@ function AISummarizer() {
 
   async function summarize(text: string) {
     await invoke({
-      entityId: 'ent_fias_ai', // the AI model capability
+      entityId: { capability: 'text-standard' }, // a platform text capability — see "Choosing a text model" below
       input: text, // what to process
       systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
     });
@@ -198,7 +198,44 @@ function AISummarizer() {
 }
 ```
 
-The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+
+#### Choosing a text model
+
+The `entityId` parameter accepts three forms. **Prefer the capability selector** over a hardcoded model id: the platform's models evolve and get retired, and a capability lets your plugin pick up the current best model automatically without a code edit. When the platform retires the model behind a capability, it re-points the capability — your plugin keeps working.
+
+```tsx
+// 1. By capability (recommended) — resolved to the platform's current model
+//    for that tier, and re-pointed automatically if that model is retired.
+await invoke({
+  entityId: { capability: 'text-standard' }, // 'text-fast' | 'text-standard' | 'text-advanced'
+  input,
+  systemPrompt: '...',
+});
+
+// 2. AI router — let the platform pick a model per request based on the
+//    query's complexity. Optionally bias the tier with routingPreference.
+await invoke({
+  entityId: 'ent_fias_ai',
+  input,
+  systemPrompt: '...',
+  routingPreference: 'cost', // 'auto' (default) | 'speed' | 'cost' | 'balanced' | 'performance'
+});
+
+// 3. A specific model id (back-compat) — pins one model. It will stop working
+//    if that model is retired; use a capability for retirement resilience.
+await invoke({ entityId: 'ent_modeldef_haiku_45', input, systemPrompt: '...' });
+```
+
+The text capabilities:
+
+| Capability      | Use it for                                                                   |
+| --------------- | ---------------------------------------------------------------------------- |
+| `text-fast`     | Cheapest, fastest — classification, extraction, short responses, high volume |
+| `text-standard` | Balanced, general-purpose text generation (the sensible default)             |
+| `text-advanced` | Most capable — complex reasoning, nuanced writing, long-form output          |
+
+Browse specific models with `npx fias-dev entities`.
 
 ### `useImageGeneration()` — Generate images via AI models