@fias/create-fias-plugin 1.0.0

package/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+var TEMPLATE_DIR = path.resolve(__dirname, 'templates/default');
+
+function copyDir(src, dest, replacements) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  var entries = fs.readdirSync(src, { withFileTypes: true });
+  for (var i = 0; i < entries.length; i++) {
+    var entry = entries[i];
+    var srcPath = path.join(src, entry.name);
+    var destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, replacements);
+    } else {
+      var content = fs.readFileSync(srcPath, 'utf-8');
+      var keys = Object.keys(replacements);
+      for (var k = 0; k < keys.length; k++) {
+        content = content.replace(new RegExp('\\{\\{' + keys[k] + '\\}\\}', 'g'), replacements[keys[k]]);
+      }
+      fs.writeFileSync(destPath, content);
+    }
+  }
+}
+
+var projectName = process.argv[2];
+
+if (!projectName) {
+  console.error('Usage: npm create @fias/fias-plugin <project-name>');
+  process.exit(1);
+}
+
+var targetDir = path.resolve(process.cwd(), projectName);
+
+if (fs.existsSync(targetDir)) {
+  console.error('Error: Directory "' + projectName + '" already exists.');
+  process.exit(1);
+}
+
+console.log('Creating FIAS plugin project: ' + projectName);
+
+copyDir(TEMPLATE_DIR, targetDir, { name: projectName });
+
+console.log('\nPlugin created at ./' + projectName + '\n');
+console.log('Next steps:');
+console.log('  cd ' + projectName);
+console.log('  npm install');
+console.log('  npx fias-dev login        # Authenticate with FIAS platform (opens browser)');
+console.log('  npm start                 # Start dev server + real AI harness (uses credits)');
+console.log('');
+console.log('  Or for offline development without credits:');
+console.log('  npm run start:mock        # Start dev server + mock AI harness');
+console.log('');
+console.log('  Open http://localhost:3200 in your browser.');
+console.log('\nAI assistants: See CLAUDE.md (or AGENTS.md) for full SDK reference.\n');

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@fias/create-fias-plugin",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Scaffold a new FIAS plugin arche project",
+  "bin": {
+    "create-fias-plugin": "index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "keywords": [
+    "fias",
+    "plugin",
+    "arche",
+    "create",
+    "scaffold"
+  ],
+  "license": "MIT"
+}

package/templates/default/.cursorrules

@@ -0,0 +1 @@
+Read CLAUDE.md in this project root for complete FIAS plugin development instructions, SDK API reference, manifest format, constraints, and patterns.

package/templates/default/.github/copilot-instructions.md

@@ -0,0 +1 @@
+Read CLAUDE.md in this project root for complete FIAS plugin development instructions, SDK API reference, manifest format, constraints, and patterns.

package/templates/default/AGENTS.md

@@ -0,0 +1,375 @@
+# FIAS Plugin Development Guide
+
+This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
+
+For other AI tool instruction files, see `CLAUDE.md` (identical content).
+
+## Project Structure
+
+```
+fias-plugin.json          # Plugin manifest (required) — name, permissions, pricing, AI configs
+package.json              # Dependencies and scripts
+src/
+  index.tsx               # Entry point — must render into #root with <FiasProvider> wrapper
+  App.tsx                 # Main component
+vite.config.ts            # Vite dev server config (port 3100)
+```
+
+## SDK API Reference
+
+All hooks require the app to be wrapped in `<FiasProvider>`:
+
+```tsx
+import { FiasProvider } from '@fias/arche-sdk';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <FiasProvider>
+    <App />
+  </FiasProvider>,
+);
+```
+
+### `useFiasTheme()` — Platform theme tokens
+
+**Permission:** `theme:read`
+**Returns:** `FiasTheme | null` (null while loading)
+
+```tsx
+import { useFiasTheme } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div
+      style={{
+        color: theme.colors.text,
+        backgroundColor: theme.colors.background,
+        fontFamily: theme.fonts.body,
+        padding: theme.spacing.md,
+        borderRadius: theme.components.cardRadius,
+      }}
+    >
+      {theme.mode === 'dark' ? 'Dark mode' : 'Light mode'}
+    </div>
+  );
+}
+```
+
+**FiasTheme shape:**
+
+- `mode`: `'light' | 'dark'`
+- `colors`: `{ primary, primaryText, secondary, accent, background, surface, card, cardText, text, textSecondary, muted, mutedText, border, error, warning, success, info }`
+- `spacing`: `{ xs, sm, md, lg, xl }` (CSS values like `'8px'`)
+- `fonts`: `{ body, heading, mono }` (font-family strings)
+- `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
+
+### `useFiasUser()` — Current user profile
+
+**Permission:** `user:profile:read`
+**Returns:** `FiasUser | null`
+
+```tsx
+import { useFiasUser } from '@fias/arche-sdk';
+
+const user = useFiasUser();
+// { userId: string, displayName: string, avatar: string | null }
+```
+
+### `useFiasStorage()` — Sandboxed file storage
+
+**Permission:** `storage:sandbox`
+**Returns:** `FiasStorageApi`
+
+```tsx
+import { useFiasStorage } from '@fias/arche-sdk';
+
+const { readFile, writeFile, listFiles, deleteFile } = useFiasStorage();
+
+await writeFile('data/settings.json', JSON.stringify(settings));
+const content = await readFile('data/settings.json'); // string | null
+const files = await listFiles('data/'); // string[]
+await deleteFile('data/old.json');
+```
+
+### `useEntityInvocation()` — Invoke AI models
+
+**Permission:** `entities:invoke`
+**Returns:** `EntityInvocationApi`
+
+Entities are shared capabilities (model access). Your plugin provides the context (system prompt, input) at invoke time.
+
+```tsx
+import { useEntityInvocation } from '@fias/arche-sdk';
+
+function AISummarizer() {
+  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
+
+  async function summarize(text: string) {
+    await invoke({
+      entityId: 'ent_model_sonnet_45', // the AI model capability
+      input: text, // what to process
+      systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
+    });
+  }
+
+  return (
+    <div>
+      <button onClick={() => summarize('...')} disabled={isLoading}>
+        Summarize
+      </button>
+      {isLoading && <p>{streamingText}</p>}
+      {result && <p>{result.output}</p>}
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+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.
+
+### `useFiasNavigation()` — In-plugin routing
+
+**Permission:** None required
+**Returns:** `FiasNavigationApi`
+
+```tsx
+import { useFiasNavigation } from '@fias/arche-sdk';
+
+const { navigateTo, currentPath } = useFiasNavigation();
+navigateTo('/settings');
+```
+
+### `useStepNavigation()` — Multi-step workflows
+
+**Returns:** `StepNavigationApi`
+
+```tsx
+import { useStepNavigation } from '@fias/arche-sdk';
+
+const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+```
+
+### `usePersistentState()` — Auto-saving state
+
+**Permission:** `storage:sandbox`
+
+```tsx
+import { usePersistentState } from '@fias/arche-sdk';
+
+const [count, setCount] = usePersistentState<number>('counter', 0);
+// Automatically persists to storage on change
+```
+
+### `fias` — Imperative utilities
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+fias.resize(800); // Resize iframe height
+fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' | 'error'
+```
+
+## Manifest Reference (`fias-plugin.json`)
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What this plugin does",
+  "main": "src/index.tsx",
+  "archeType": "tool",
+  "tags": ["utility"],
+  "pricing": { "model": "free", "currency": "usd" },
+  "permissions": ["theme:read", "entities:invoke"],
+  "sdk": "^1.0.0",
+  "dependencies": { "recharts": "2.15.0" }
+}
+```
+
+**Fields:**
+
+| Field          | Required | Description                                               |
+| -------------- | -------- | --------------------------------------------------------- |
+| `name`         | Yes      | Plugin identifier (lowercase, hyphens)                    |
+| `version`      | Yes      | Semver (e.g., `"1.0.0"`)                                  |
+| `description`  | Yes      | Short marketplace description                             |
+| `main`         | Yes      | Entry point source file                                   |
+| `archeType`    | Yes      | `"tool"` or `"site"`                                      |
+| `tags`         | No       | Discovery tags                                            |
+| `pricing`      | Yes      | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
+| `permissions`  | Yes      | Array of permission scopes                                |
+| `sdk`          | Yes      | SDK version range                                         |
+| `dependencies` | No       | npm packages with **exact** versions (max 20)             |
+
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
+
+**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`.
+
+## Plugin Constraints
+
+These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
+
+### Sandboxing
+
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin"`
+- **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
+- **No access** to parent DOM, cookies, or localStorage
+- **No external scripts or stylesheets** — everything must be bundled
+- All platform communication goes through the bridge (SDK hooks)
+
+### Size and File Limits
+
+- **Bundle size:** Max 5 MB compressed
+- **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
+- Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`
+
+### Rate Limits
+
+- `entity_invoke`: 60/minute
+- `storage_write`: 120/minute
+- `storage_read`: 300/minute
+- `storage_list`, `storage_delete`: 60/minute
+
+### Security Rules (enforced during review)
+
+- No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
+- No attempts to escape the iframe sandbox
+- No credential collection or dark patterns
+- No obfuscated code
+- No accessing `window.parent`, `window.top`, or `document.cookie`
+
+## Styling Guidelines
+
+- Always use `useFiasTheme()` for colors, fonts, and spacing — never hardcode
+- Support both light and dark modes (check `theme.mode`)
+- Use `theme.components.cardRadius`, `theme.components.shadowMd`, etc. for consistent component styling
+- The plugin renders at full width inside the platform layout
+
+## Development Workflow
+
+### Starting Development
+
+```bash
+npm start              # Starts both Vite + dev harness
+```
+
+This starts the plugin in **mock mode** (free, offline). Open **http://localhost:3200** in your browser to see the plugin running inside the harness.
+
+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.
+
+### Switching to Live Mode (Real AI)
+
+In the harness toolbar, click the **MOCK** badge to switch to **LIVE** mode. If you haven't authenticated yet, a login popup will open automatically. Sign in with your FIAS account and the harness will switch to live mode.
+
+You can choose between **Staging** and **Production** environments using the dropdown in the toolbar. Each environment requires separate authentication.
+
+**IMPORTANT:** Live mode uses real AI and costs credits. Mock mode returns canned responses and does NOT call real AI models. If you want actual AI-powered features to work during testing, you MUST switch to live mode.
+
+### CLI Authentication (Alternative)
+
+You can also authenticate via the command line:
+
+```bash
+npx fias-dev login                    # Authenticate with staging (default)
+npx fias-dev login --env production   # Authenticate with production
+```
+
+### Browsing Available Entities
+
+```bash
+npx fias-dev entities                    # List all
+npx fias-dev entities --search "text"    # Search by keyword
+npx fias-dev entities --type "prompt"    # Filter by type
+```
+
+### Validating the Manifest
+
+```bash
+npx fias-dev validate
+```
+
+### Submitting to the Arche Store
+
+```bash
+npm run submit
+# Builds, validates, packages, uploads, submits for AI review
+# First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
+```
+
+## Common Patterns
+
+### Theme-Aware Card Component
+
+```tsx
+function Card({ children }: { children: React.ReactNode }) {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div
+      style={{
+        backgroundColor: theme.colors.card,
+        color: theme.colors.cardText,
+        borderRadius: theme.components.cardRadius,
+        boxShadow: theme.components.shadowMd,
+        border: `${theme.components.borderWidth} solid ${theme.colors.border}`,
+        padding: theme.spacing.lg,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+### Streaming AI Response
+
+```tsx
+function AIChat() {
+  const { invoke, isLoading, streamingText, result } = useEntityInvocation();
+  const [input, setInput] = useState('');
+
+  return (
+    <div>
+      <textarea value={input} onChange={(e) => setInput(e.target.value)} />
+      <button
+        onClick={() =>
+          invoke({
+            entityId: 'ent_model_sonnet_45',
+            input,
+            systemPrompt: 'You are a helpful assistant.',
+          })
+        }
+        disabled={isLoading}
+      >
+        Send
+      </button>
+      <div>{isLoading ? streamingText : result?.output}</div>
+    </div>
+  );
+}
+```
+
+### Persistent Settings
+
+```tsx
+function Settings() {
+  const [settings, setSettings] = usePersistentState('settings', {
+    notifications: true,
+    fontSize: 14,
+  });
+
+  return (
+    <label>
+      <input
+        type="checkbox"
+        checked={settings.notifications}
+        onChange={(e) => setSettings({ ...settings, notifications: e.target.checked })}
+      />
+      Notifications
+    </label>
+  );
+}
+```

package/templates/default/CLAUDE.md

@@ -0,0 +1,375 @@
+# FIAS Plugin Development Guide
+
+This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
+
+For other AI tool instruction files, see `AGENTS.md` (identical content).
+
+## Project Structure
+
+```
+fias-plugin.json          # Plugin manifest (required) — name, permissions, pricing, AI configs
+package.json              # Dependencies and scripts
+src/
+  index.tsx               # Entry point — must render into #root with <FiasProvider> wrapper
+  App.tsx                 # Main component
+vite.config.ts            # Vite dev server config (port 3100)
+```
+
+## SDK API Reference
+
+All hooks require the app to be wrapped in `<FiasProvider>`:
+
+```tsx
+import { FiasProvider } from '@fias/arche-sdk';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <FiasProvider>
+    <App />
+  </FiasProvider>,
+);
+```
+
+### `useFiasTheme()` — Platform theme tokens
+
+**Permission:** `theme:read`
+**Returns:** `FiasTheme | null` (null while loading)
+
+```tsx
+import { useFiasTheme } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div
+      style={{
+        color: theme.colors.text,
+        backgroundColor: theme.colors.background,
+        fontFamily: theme.fonts.body,
+        padding: theme.spacing.md,
+        borderRadius: theme.components.cardRadius,
+      }}
+    >
+      {theme.mode === 'dark' ? 'Dark mode' : 'Light mode'}
+    </div>
+  );
+}
+```
+
+**FiasTheme shape:**
+
+- `mode`: `'light' | 'dark'`
+- `colors`: `{ primary, primaryText, secondary, accent, background, surface, card, cardText, text, textSecondary, muted, mutedText, border, error, warning, success, info }`
+- `spacing`: `{ xs, sm, md, lg, xl }` (CSS values like `'8px'`)
+- `fonts`: `{ body, heading, mono }` (font-family strings)
+- `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
+
+### `useFiasUser()` — Current user profile
+
+**Permission:** `user:profile:read`
+**Returns:** `FiasUser | null`
+
+```tsx
+import { useFiasUser } from '@fias/arche-sdk';
+
+const user = useFiasUser();
+// { userId: string, displayName: string, avatar: string | null }
+```
+
+### `useFiasStorage()` — Sandboxed file storage
+
+**Permission:** `storage:sandbox`
+**Returns:** `FiasStorageApi`
+
+```tsx
+import { useFiasStorage } from '@fias/arche-sdk';
+
+const { readFile, writeFile, listFiles, deleteFile } = useFiasStorage();
+
+await writeFile('data/settings.json', JSON.stringify(settings));
+const content = await readFile('data/settings.json'); // string | null
+const files = await listFiles('data/'); // string[]
+await deleteFile('data/old.json');
+```
+
+### `useEntityInvocation()` — Invoke AI models
+
+**Permission:** `entities:invoke`
+**Returns:** `EntityInvocationApi`
+
+Entities are shared capabilities (model access). Your plugin provides the context (system prompt, input) at invoke time.
+
+```tsx
+import { useEntityInvocation } from '@fias/arche-sdk';
+
+function AISummarizer() {
+  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
+
+  async function summarize(text: string) {
+    await invoke({
+      entityId: 'ent_model_sonnet_45', // the AI model capability
+      input: text, // what to process
+      systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
+    });
+  }
+
+  return (
+    <div>
+      <button onClick={() => summarize('...')} disabled={isLoading}>
+        Summarize
+      </button>
+      {isLoading && <p>{streamingText}</p>}
+      {result && <p>{result.output}</p>}
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+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.
+
+### `useFiasNavigation()` — In-plugin routing
+
+**Permission:** None required
+**Returns:** `FiasNavigationApi`
+
+```tsx
+import { useFiasNavigation } from '@fias/arche-sdk';
+
+const { navigateTo, currentPath } = useFiasNavigation();
+navigateTo('/settings');
+```
+
+### `useStepNavigation()` — Multi-step workflows
+
+**Returns:** `StepNavigationApi`
+
+```tsx
+import { useStepNavigation } from '@fias/arche-sdk';
+
+const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+```
+
+### `usePersistentState()` — Auto-saving state
+
+**Permission:** `storage:sandbox`
+
+```tsx
+import { usePersistentState } from '@fias/arche-sdk';
+
+const [count, setCount] = usePersistentState<number>('counter', 0);
+// Automatically persists to storage on change
+```
+
+### `fias` — Imperative utilities
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+fias.resize(800); // Resize iframe height
+fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' | 'error'
+```
+
+## Manifest Reference (`fias-plugin.json`)
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What this plugin does",
+  "main": "src/index.tsx",
+  "archeType": "tool",
+  "tags": ["utility"],
+  "pricing": { "model": "free", "currency": "usd" },
+  "permissions": ["theme:read", "entities:invoke"],
+  "sdk": "^1.0.0",
+  "dependencies": { "recharts": "2.15.0" }
+}
+```
+
+**Fields:**
+
+| Field          | Required | Description                                               |
+| -------------- | -------- | --------------------------------------------------------- |
+| `name`         | Yes      | Plugin identifier (lowercase, hyphens)                    |
+| `version`      | Yes      | Semver (e.g., `"1.0.0"`)                                  |
+| `description`  | Yes      | Short marketplace description                             |
+| `main`         | Yes      | Entry point source file                                   |
+| `archeType`    | Yes      | `"tool"` or `"site"`                                      |
+| `tags`         | No       | Discovery tags                                            |
+| `pricing`      | Yes      | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
+| `permissions`  | Yes      | Array of permission scopes                                |
+| `sdk`          | Yes      | SDK version range                                         |
+| `dependencies` | No       | npm packages with **exact** versions (max 20)             |
+
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
+
+**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`.
+
+## Plugin Constraints
+
+These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
+
+### Sandboxing
+
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin"`
+- **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
+- **No access** to parent DOM, cookies, or localStorage
+- **No external scripts or stylesheets** — everything must be bundled
+- All platform communication goes through the bridge (SDK hooks)
+
+### Size and File Limits
+
+- **Bundle size:** Max 5 MB compressed
+- **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
+- Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`
+
+### Rate Limits
+
+- `entity_invoke`: 60/minute
+- `storage_write`: 120/minute
+- `storage_read`: 300/minute
+- `storage_list`, `storage_delete`: 60/minute
+
+### Security Rules (enforced during review)
+
+- No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
+- No attempts to escape the iframe sandbox
+- No credential collection or dark patterns
+- No obfuscated code
+- No accessing `window.parent`, `window.top`, or `document.cookie`
+
+## Styling Guidelines
+
+- Always use `useFiasTheme()` for colors, fonts, and spacing — never hardcode
+- Support both light and dark modes (check `theme.mode`)
+- Use `theme.components.cardRadius`, `theme.components.shadowMd`, etc. for consistent component styling
+- The plugin renders at full width inside the platform layout
+
+## Development Workflow
+
+### Starting Development
+
+```bash
+npm start              # Starts both Vite + dev harness
+```
+
+This starts the plugin in **mock mode** (free, offline). Open **http://localhost:3200** in your browser to see the plugin running inside the harness.
+
+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.
+
+### Switching to Live Mode (Real AI)
+
+In the harness toolbar, click the **MOCK** badge to switch to **LIVE** mode. If you haven't authenticated yet, a login popup will open automatically. Sign in with your FIAS account and the harness will switch to live mode.
+
+You can choose between **Staging** and **Production** environments using the dropdown in the toolbar. Each environment requires separate authentication.
+
+**IMPORTANT:** Live mode uses real AI and costs credits. Mock mode returns canned responses and does NOT call real AI models. If you want actual AI-powered features to work during testing, you MUST switch to live mode.
+
+### CLI Authentication (Alternative)
+
+You can also authenticate via the command line:
+
+```bash
+npx fias-dev login                    # Authenticate with staging (default)
+npx fias-dev login --env production   # Authenticate with production
+```
+
+### Browsing Available Entities
+
+```bash
+npx fias-dev entities                    # List all
+npx fias-dev entities --search "text"    # Search by keyword
+npx fias-dev entities --type "prompt"    # Filter by type
+```
+
+### Validating the Manifest
+
+```bash
+npx fias-dev validate
+```
+
+### Submitting to the Arche Store
+
+```bash
+npm run submit
+# Builds, validates, packages, uploads, submits for AI review
+# First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
+```
+
+## Common Patterns
+
+### Theme-Aware Card Component
+
+```tsx
+function Card({ children }: { children: React.ReactNode }) {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div
+      style={{
+        backgroundColor: theme.colors.card,
+        color: theme.colors.cardText,
+        borderRadius: theme.components.cardRadius,
+        boxShadow: theme.components.shadowMd,
+        border: `${theme.components.borderWidth} solid ${theme.colors.border}`,
+        padding: theme.spacing.lg,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+### Streaming AI Response
+
+```tsx
+function AIChat() {
+  const { invoke, isLoading, streamingText, result } = useEntityInvocation();
+  const [input, setInput] = useState('');
+
+  return (
+    <div>
+      <textarea value={input} onChange={(e) => setInput(e.target.value)} />
+      <button
+        onClick={() =>
+          invoke({
+            entityId: 'ent_model_sonnet_45',
+            input,
+            systemPrompt: 'You are a helpful assistant.',
+          })
+        }
+        disabled={isLoading}
+      >
+        Send
+      </button>
+      <div>{isLoading ? streamingText : result?.output}</div>
+    </div>
+  );
+}
+```
+
+### Persistent Settings
+
+```tsx
+function Settings() {
+  const [settings, setSettings] = usePersistentState('settings', {
+    notifications: true,
+    fontSize: 14,
+  });
+
+  return (
+    <label>
+      <input
+        type="checkbox"
+        checked={settings.notifications}
+        onChange={(e) => setSettings({ ...settings, notifications: e.target.checked })}
+      />
+      Notifications
+    </label>
+  );
+}
+```

package/templates/default/fias-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{name}}",
+  "version": "1.0.0",
+  "description": "A FIAS plugin arche",
+  "main": "src/index.tsx",
+  "archeType": "tool",
+  "tags": [],
+  "pricing": { "model": "free", "currency": "usd" },
+  "permissions": ["theme:read"],
+  "sdk": "^1.0.0"
+}

package/templates/default/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>FIAS Plugin</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/templates/default/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{name}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "vite & sleep 2 && fias-dev",
+    "dev": "vite",
+    "build": "vite build",
+    "validate": "tsc --noEmit",
+    "dev:harness": "fias-dev",
+    "submit": "fias-dev submit"
+  },
+  "dependencies": {
+    "@fias/arche-sdk": "^1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@fias/plugin-dev-harness": "^1.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "typescript": "^5.3.3",
+    "vite": "^6.0.0"
+  }
+}

package/templates/default/src/App.tsx

@@ -0,0 +1,12 @@
+import { useFiasTheme } from '@fias/arche-sdk';
+
+export function App() {
+  const theme = useFiasTheme();
+
+  return (
+    <div style={{ padding: theme?.spacing.md, fontFamily: theme?.fonts.body }}>
+      <h1>My FIAS Plugin</h1>
+      <p>Edit src/App.tsx to get started.</p>
+    </div>
+  );
+}

package/templates/default/src/index.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { FiasProvider } from '@fias/arche-sdk';
+import { App } from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <FiasProvider>
+      <App />
+    </FiasProvider>
+  </React.StrictMode>,
+);

package/templates/default/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/default/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    outDir: 'dist',
+    rollupOptions: {
+      input: 'index.html',
+    },
+  },
+  server: {
+    port: 3100,
+    cors: true,
+    headers: { 'Access-Control-Allow-Origin': '*' },
+    hmr: { host: 'localhost' },
+  },
+});