@fias/arche-sdk 1.1.9 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/dist/types.d.ts +2 -0
  2. package/dist/types.d.ts.map +1 -1
  3. package/package.json +1 -1
  4. package/templates/default/AGENTS.md +43 -32
  5. package/templates/default/CLAUDE.md +43 -32
  6. package/templates/default/fias-plugin.json +1 -2
  7. package/templates/default/package.json +2 -2
package/dist/types.d.ts CHANGED
@@ -88,6 +88,8 @@ export interface EntityInvocationParams {
88
88
  entityId: string;
89
89
  input: string;
90
90
  parameters?: Record<string, unknown>;
91
+ /** System prompt to send to the AI model. The arche/plugin provides context; the entity provides the capability. */
92
+ systemPrompt?: string;
91
93
  }
92
94
  /**
93
95
  * Navigation API available via useFiasNavigation() hook.
package/dist/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,iBAAiB,GACjB,iBAAiB,GACjB,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;IACF,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,UAAU,EAAE;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP,QAAQ,GACR,OAAO,GACP,UAAU,GACV,WAAW,GACX,cAAc,GACd,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,UAAU,GACV,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,IAAI,EAAE,uBAAuB,GAAG,uBAAuB,CAAC;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,gBAAgB,EAAE,CAAC;QAChC,KAAK,EAAE,SAAS,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,iBAAiB,GACjB,iBAAiB,GACjB,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;IACF,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,UAAU,EAAE;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oHAAoH;IACpH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP,QAAQ,GACR,OAAO,GACP,UAAU,GACV,WAAW,GACX,cAAc,GACd,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,UAAU,GACV,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,IAAI,EAAE,uBAAuB,GAAG,uBAAuB,CAAC;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,gBAAgB,EAAE,CAAC;QAChC,KAAK,EAAE,SAAS,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fias/arche-sdk",
3
- "version": "1.1.9",
3
+ "version": "1.2.1",
4
4
  "description": "SDK for building FIAS platform plugin arches",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/templates/default/AGENTS.md CHANGED
@@ -93,11 +93,13 @@ const files = await listFiles('data/'); // string[]
93
93
  await deleteFile('data/old.json');
94
94
  ```
95
95
 
96
- ### `useEntityInvocation()` — Invoke AI entities
96
+ ### `useEntityInvocation()` — Invoke AI models
97
97
 
98
98
  **Permission:** `entities:invoke`
99
99
  **Returns:** `EntityInvocationApi`
100
100
 
101
+ Entities are shared capabilities (model access). Your plugin provides the context (system prompt, input) at invoke time.
102
+
101
103
  ```tsx
102
104
  import { useEntityInvocation } from '@fias/arche-sdk';
103
105
 
@@ -105,7 +107,11 @@ function AISummarizer() {
105
107
  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
106
108
 
107
109
  async function summarize(text: string) {
108
- await invoke({ entityId: 'ent_abc123', input: text });
110
+ await invoke({
111
+ entityId: 'ent_model_sonnet_45', // the AI model capability
112
+ input: text, // what to process
113
+ systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
114
+ });
109
115
  }
110
116
 
111
117
  return (
@@ -121,7 +127,7 @@ function AISummarizer() {
121
127
  }
122
128
  ```
123
129
 
124
- The `entityId` references a published entity on the platform. Browse available entities with `npx fias-dev entities`.
130
+ 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.
125
131
 
126
132
  ### `useFiasNavigation()` — In-plugin routing
127
133
 
@@ -178,38 +184,28 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
178
184
  "pricing": { "model": "free", "currency": "usd" },
179
185
  "permissions": ["theme:read", "entities:invoke"],
180
186
  "sdk": "^1.0.0",
181
- "dependencies": { "recharts": "2.15.0" },
182
- "aiConfigs": [
183
- {
184
- "configId": "summarizer",
185
- "label": "Text Summarizer",
186
- "entityId": "ent_abc123",
187
- "systemPrompt": "Summarize the input concisely.",
188
- "parameters": { "temperature": 0.3, "maxTokens": 500 }
189
- }
190
- ]
187
+ "dependencies": { "recharts": "2.15.0" }
191
188
  }
192
189
  ```
193
190
 
194
191
  **Fields:**
195
192
 
196
- | Field | Required | Description |
197
- | -------------- | -------- | --------------------------------------------- | ------- | --------- | ----------- |
198
- | `name` | Yes | Plugin identifier (lowercase, hyphens) |
199
- | `version` | Yes | Semver (e.g., `"1.0.0"`) |
200
- | `description` | Yes | Short marketplace description |
201
- | `main` | Yes | Entry point source file |
202
- | `archeType` | Yes | `"tool"` or `"site"` |
203
- | `tags` | No | Discovery tags |
204
- | `pricing` | Yes | `{ model: "free" | "fixed" | "per_use" | "tiered" }` |
205
- | `permissions` | Yes | Array of permission scopes |
206
- | `sdk` | Yes | SDK version range |
207
- | `dependencies` | No | npm packages with **exact** versions (max 20) |
208
- | `aiConfigs` | No | AI entity configurations (see below) |
193
+ | Field | Required | Description |
194
+ | -------------- | -------- | --------------------------------------------------------- |
195
+ | `name` | Yes | Plugin identifier (lowercase, hyphens) |
196
+ | `version` | Yes | Semver (e.g., `"1.0.0"`) |
197
+ | `description` | Yes | Short marketplace description |
198
+ | `main` | Yes | Entry point source file |
199
+ | `archeType` | Yes | `"tool"` or `"site"` |
200
+ | `tags` | No | Discovery tags |
201
+ | `pricing` | Yes | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
202
+ | `permissions` | Yes | Array of permission scopes |
203
+ | `sdk` | Yes | SDK version range |
204
+ | `dependencies` | No | npm packages with **exact** versions (max 20) |
209
205
 
210
206
  **Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
211
207
 
212
- **AI Configs:** Declare entity invocations the plugin will use. Each config's `entityId` must reference a published prompt entity. Browse entities with `npx fias-dev entities`. Requires `entities:invoke` permission.
208
+ **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
213
209
 
214
210
  ## Plugin Constraints
215
211
 
@@ -259,19 +255,25 @@ These are hard limits enforced by the platform. Code that violates these will fa
259
255
  npx fias-dev login # Opens browser to sign in, saves API key automatically
260
256
  ```
261
257
 
258
+ This opens the FIAS platform in your browser. If you're already signed in, the API key is created and saved automatically. If not, you'll need to sign in (or sign up for a FIAS account if you don't have one — an invite code is required for new accounts). The URL is also printed in the terminal if the browser doesn't open automatically.
259
+
262
260
  ### Step 2: Start development
263
261
 
262
+ **With real AI (recommended — requires login first):**
264
263
  ```bash
265
264
  npm start # Starts both Vite + dev harness with real AI (uses credits)
266
265
  ```
267
266
 
268
- Or for offline development without credits (AI calls return canned responses):
269
-
267
+ **Without AI (offline, for UI-only work):**
270
268
  ```bash
271
- npm run start:mock # Starts both Vite + dev harness with mock AI
269
+ npm run start:mock # Starts both Vite + dev harness with mock responses
272
270
  ```
273
271
 
274
- Open http://localhost:3200 in your browser.
272
+ `npm start` will fail with "Not logged in" if `npx fias-dev login` hasn't been run. If that happens, run the login command first, then retry `npm start`.
273
+
274
+ **IMPORTANT:** Always tell the user to open **http://localhost:3200** in their browser to see the plugin running. Port 3200 is the dev harness that wraps the plugin in the platform iframe. Port 3100 is just the raw Vite server and won't work correctly on its own.
275
+
276
+ **IMPORTANT:** `npm start` uses real AI and costs credits. `npm run start:mock` returns canned responses and does NOT call real AI models. If the user wants actual AI-powered features to work during testing, they MUST use `npm start` (not `start:mock`).
275
277
 
276
278
  **Advanced:** If you prefer separate terminals, use `npm run dev` (Vite on port 3100) and `npm run dev:harness` or `npm run dev:mock` (harness on port 3200) independently.
277
279
 
@@ -333,7 +335,16 @@ function AIChat() {
333
335
  return (
334
336
  <div>
335
337
  <textarea value={input} onChange={(e) => setInput(e.target.value)} />
336
- <button onClick={() => invoke({ entityId: 'ent_abc', input })} disabled={isLoading}>
338
+ <button
339
+ onClick={() =>
340
+ invoke({
341
+ entityId: 'ent_model_sonnet_45',
342
+ input,
343
+ systemPrompt: 'You are a helpful assistant.',
344
+ })
345
+ }
346
+ disabled={isLoading}
347
+ >
337
348
  Send
338
349
  </button>
339
350
  <div>{isLoading ? streamingText : result?.output}</div>
package/templates/default/CLAUDE.md CHANGED
@@ -93,11 +93,13 @@ const files = await listFiles('data/'); // string[]
93
93
  await deleteFile('data/old.json');
94
94
  ```
95
95
 
96
- ### `useEntityInvocation()` — Invoke AI entities
96
+ ### `useEntityInvocation()` — Invoke AI models
97
97
 
98
98
  **Permission:** `entities:invoke`
99
99
  **Returns:** `EntityInvocationApi`
100
100
 
101
+ Entities are shared capabilities (model access). Your plugin provides the context (system prompt, input) at invoke time.
102
+
101
103
  ```tsx
102
104
  import { useEntityInvocation } from '@fias/arche-sdk';
103
105
 
@@ -105,7 +107,11 @@ function AISummarizer() {
105
107
  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
106
108
 
107
109
  async function summarize(text: string) {
108
- await invoke({ entityId: 'ent_abc123', input: text });
110
+ await invoke({
111
+ entityId: 'ent_model_sonnet_45', // the AI model capability
112
+ input: text, // what to process
113
+ systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
114
+ });
109
115
  }
110
116
 
111
117
  return (
@@ -121,7 +127,7 @@ function AISummarizer() {
121
127
  }
122
128
  ```
123
129
 
124
- The `entityId` references a published entity on the platform. Browse available entities with `npx fias-dev entities`.
130
+ 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.
125
131
 
126
132
  ### `useFiasNavigation()` — In-plugin routing
127
133
 
@@ -178,38 +184,28 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
178
184
  "pricing": { "model": "free", "currency": "usd" },
179
185
  "permissions": ["theme:read", "entities:invoke"],
180
186
  "sdk": "^1.0.0",
181
- "dependencies": { "recharts": "2.15.0" },
182
- "aiConfigs": [
183
- {
184
- "configId": "summarizer",
185
- "label": "Text Summarizer",
186
- "entityId": "ent_abc123",
187
- "systemPrompt": "Summarize the input concisely.",
188
- "parameters": { "temperature": 0.3, "maxTokens": 500 }
189
- }
190
- ]
187
+ "dependencies": { "recharts": "2.15.0" }
191
188
  }
192
189
  ```
193
190
 
194
191
  **Fields:**
195
192
 
196
- | Field | Required | Description |
197
- | -------------- | -------- | --------------------------------------------- | ------- | --------- | ----------- |
198
- | `name` | Yes | Plugin identifier (lowercase, hyphens) |
199
- | `version` | Yes | Semver (e.g., `"1.0.0"`) |
200
- | `description` | Yes | Short marketplace description |
201
- | `main` | Yes | Entry point source file |
202
- | `archeType` | Yes | `"tool"` or `"site"` |
203
- | `tags` | No | Discovery tags |
204
- | `pricing` | Yes | `{ model: "free" | "fixed" | "per_use" | "tiered" }` |
205
- | `permissions` | Yes | Array of permission scopes |
206
- | `sdk` | Yes | SDK version range |
207
- | `dependencies` | No | npm packages with **exact** versions (max 20) |
208
- | `aiConfigs` | No | AI entity configurations (see below) |
193
+ | Field | Required | Description |
194
+ | -------------- | -------- | --------------------------------------------------------- |
195
+ | `name` | Yes | Plugin identifier (lowercase, hyphens) |
196
+ | `version` | Yes | Semver (e.g., `"1.0.0"`) |
197
+ | `description` | Yes | Short marketplace description |
198
+ | `main` | Yes | Entry point source file |
199
+ | `archeType` | Yes | `"tool"` or `"site"` |
200
+ | `tags` | No | Discovery tags |
201
+ | `pricing` | Yes | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
202
+ | `permissions` | Yes | Array of permission scopes |
203
+ | `sdk` | Yes | SDK version range |
204
+ | `dependencies` | No | npm packages with **exact** versions (max 20) |
209
205
 
210
206
  **Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
211
207
 
212
- **AI Configs:** Declare entity invocations the plugin will use. Each config's `entityId` must reference a published prompt entity. Browse entities with `npx fias-dev entities`. Requires `entities:invoke` permission.
208
+ **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
213
209
 
214
210
  ## Plugin Constraints
215
211
 
@@ -259,19 +255,25 @@ These are hard limits enforced by the platform. Code that violates these will fa
259
255
  npx fias-dev login # Opens browser to sign in, saves API key automatically
260
256
  ```
261
257
 
258
+ This opens the FIAS platform in your browser. If you're already signed in, the API key is created and saved automatically. If not, you'll need to sign in (or sign up for a FIAS account if you don't have one — an invite code is required for new accounts). The URL is also printed in the terminal if the browser doesn't open automatically.
259
+
262
260
  ### Step 2: Start development
263
261
 
262
+ **With real AI (recommended — requires login first):**
264
263
  ```bash
265
264
  npm start # Starts both Vite + dev harness with real AI (uses credits)
266
265
  ```
267
266
 
268
- Or for offline development without credits (AI calls return canned responses):
269
-
267
+ **Without AI (offline, for UI-only work):**
270
268
  ```bash
271
- npm run start:mock # Starts both Vite + dev harness with mock AI
269
+ npm run start:mock # Starts both Vite + dev harness with mock responses
272
270
  ```
273
271
 
274
- Open http://localhost:3200 in your browser.
272
+ `npm start` will fail with "Not logged in" if `npx fias-dev login` hasn't been run. If that happens, run the login command first, then retry `npm start`.
273
+
274
+ **IMPORTANT:** Always tell the user to open **http://localhost:3200** in their browser to see the plugin running. Port 3200 is the dev harness that wraps the plugin in the platform iframe. Port 3100 is just the raw Vite server and won't work correctly on its own.
275
+
276
+ **IMPORTANT:** `npm start` uses real AI and costs credits. `npm run start:mock` returns canned responses and does NOT call real AI models. If the user wants actual AI-powered features to work during testing, they MUST use `npm start` (not `start:mock`).
275
277
 
276
278
  **Advanced:** If you prefer separate terminals, use `npm run dev` (Vite on port 3100) and `npm run dev:harness` or `npm run dev:mock` (harness on port 3200) independently.
277
279
 
@@ -333,7 +335,16 @@ function AIChat() {
333
335
  return (
334
336
  <div>
335
337
  <textarea value={input} onChange={(e) => setInput(e.target.value)} />
336
- <button onClick={() => invoke({ entityId: 'ent_abc', input })} disabled={isLoading}>
338
+ <button
339
+ onClick={() =>
340
+ invoke({
341
+ entityId: 'ent_model_sonnet_45',
342
+ input,
343
+ systemPrompt: 'You are a helpful assistant.',
344
+ })
345
+ }
346
+ disabled={isLoading}
347
+ >
337
348
  Send
338
349
  </button>
339
350
  <div>{isLoading ? streamingText : result?.output}</div>
package/templates/default/fias-plugin.json CHANGED
@@ -7,6 +7,5 @@
7
7
  "tags": [],
8
8
  "pricing": { "model": "free", "currency": "usd" },
9
9
  "permissions": ["theme:read"],
10
- "sdk": "^1.0.0",
11
- "aiConfigs": []
10
+ "sdk": "^1.0.0"
12
11
  }
package/templates/default/package.json CHANGED
@@ -3,8 +3,8 @@
3
3
  "version": "1.0.0",
4
4
  "private": true,
5
5
  "scripts": {
6
- "start": "vite & fias-dev --live",
7
- "start:mock": "vite & fias-dev",
6
+ "start": "fias-dev check-auth && vite & sleep 2 && fias-dev --live",
7
+ "start:mock": "vite & sleep 2 && fias-dev",
8
8
  "dev": "vite",
9
9
  "build": "vite build",
10
10
  "validate": "tsc --noEmit",