@fias/arche-sdk 1.9.0 → 1.12.0

package/templates/default/AGENTS.md

@@ -220,10 +220,10 @@ function ImageMaker() {
       <button
         onClick={() =>
           generate({
-            entityId: 'ent_modeldef_dalle3',
+            entityId: 'ent_modeldef_gpt_image_1_5',
             prompt: 'A serene mountain landscape at sunset',
             size: '1024x1024',
-            quality: 'hd',
+            quality: 'high',
           })
         }
         disabled={isLoading}
@@ -237,6 +237,56 @@ function ImageMaker() {
 }
 ```
 
+### `useFiasFiles()` — User-files filesystem (SDK ≥ 1.9.0)
+
+**Permissions:** `files:read` for `list`/`read`/`getDownloadUrl`; add `files:write` for `write`/`update`/`delete`
+**Returns:** `FiasFilesApi`
+
+Access the user's Fias filesystem, scoped to files this arche owns. Files written through this hook (and images created via `useImageGeneration()`) appear in MyData under `/My-Fias/{ArcheName}/`. Listing is by ownership — moving a file in MyData doesn't hide it from the arche.
+
+The most common use is `getDownloadUrl(fileId)` to refresh the presigned URL on a generated image after the original (~1h) expires:
+
+```tsx
+import { useFiasFiles, useImageGeneration } from '@fias/arche-sdk';
+
+function PortraitGallery({ savedFileId }: { savedFileId: string }) {
+  const { getDownloadUrl } = useFiasFiles();
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    getDownloadUrl(savedFileId).then((r) => {
+      if (!cancelled) setUrl(r.url);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [savedFileId, getDownloadUrl]);
+
+  return url ? <img src={url} alt="" /> : null;
+}
+```
+
+**Store the `fileId`, not the `imageUrl`.** Image-generation results include both, but `imageUrl` is a short-lived presigned link. Persist `fileId` in your data store and resolve to a fresh URL on render via `getDownloadUrl`.
+
+**Same-name writes overwrite.** Calling `write({ name: 'save.json', content })` twice with the same name reuses the existing `fileId` and replaces the content — useful for periodic snapshots.
+
+**`read()` is text-only.** It rejects binary content types with HTTP 415. Use `getDownloadUrl(fileId)` and pass the URL to `<img>`, `fetch`, etc. for binaries.
+
+```tsx
+const files = useFiasFiles();
+
+await files.write({
+  name: 'save.json',
+  content: JSON.stringify(state),
+  contentType: 'application/json',
+});
+const { content } = await files.read(fileId);
+const { files: page, nextCursor } = await files.list({ limit: 20 });
+await files.update(fileId, { tags: ['draft'] });
+await files.delete(fileId);
+```
+
 ### `useFiasNavigation()` — In-plugin routing
 
 **Permission:** None required
@@ -337,6 +387,12 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 
 These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
 
+### Hitting a limit? Tell the user about Entity requests
+
+Don't just say "can't do that" when the user asks for something blocked by these rules — most often a direct external API call, a third-party service, or a capability the platform hasn't surfaced yet. The Fias team adds new **Entities** on request: platform-managed wrappers that hold credentials, handle auth, and expose the capability to plugins through `useEntityInvocation()` (or `useImageGeneration()` for image models). The plugin never bypasses the sandbox — it invokes the new Entity like any other model.
+
+When you hit a constraint, say so AND tell the user: file an Entity request on the Customer Support arche at `https://platform.fias.io/a/arche_customer_support`. Describe the service, endpoints, and auth method needed; once the Entity ships, the plugin can call it via `useEntityInvocation` with no sandbox change. Then propose a fallback that works inside the current sandbox (mock data, a simpler path, deferring the call) so the build keeps moving while the request is in flight.
+
 ### Sandboxing
 
 - Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin allow-downloads"`
@@ -390,6 +446,18 @@ If newer package versions are available, tell the user and ask if they want to u
 
 If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
 
+#### UI cache after a harness upgrade
+
+The harness pulls its host-page UI (toolbar, mode toggle, sign-in modal) from a CDN and caches it in `~/.fias/harness-cache/`. The cached UI takes priority over the bundled copy that ships in the npm package.
+
+When you upgrade `@fias/plugin-dev-harness` but the CDN hasn't been redeployed yet, the cached UI can be older than the CLI. fias-dev now detects this case automatically and falls back to the bundled UI — look for this line in the startup log:
+
+```
+ℹ Cached harness UI v1.14.3 is older than CLI v1.18.0 — using bundled UI.
+```
+
+That message means everything is fine; the bundled UI exactly matches your CLI version. If you ever see stale behavior persist across an upgrade (and the line above didn't appear), delete `~/.fias/harness-cache/` and restart.
+
 ### Starting Development
 
 ```bash
@@ -423,9 +491,42 @@ npx fias-dev login --env production   # Authenticate with production
 npx fias-dev entities                              # List all
 npx fias-dev entities --search "image"             # Search by keyword
 npx fias-dev entities --type "model-definition"    # Filter by type
-npx fias-dev entities --detail ent_modeldef_dalle3 # Full entity details (capabilities, sizes, pricing)
+npx fias-dev entities --detail ent_modeldef_gpt_image_1_5 # Full entity details (capabilities, sizes, pricing)
 ```
 
+### Debugging — Read the Browser's View Directly
+
+The harness mirrors every browser-side event to a per-port log file at `/tmp/fias-dev-<port>.log` (so usually `/tmp/fias-dev-3200.log`). The file path is also printed at startup:
+
+```
+Browser dev-log mirror: /tmp/fias-dev-3200.log
+```
+
+What's captured:
+
+- Every Dev Console entry (`send` / `recv` / `info` / `error` / `toast` / `cost` / `nav`)
+- Every uncaught JS error (`window.error`)
+- Every unhandled promise rejection (`unhandledrejection`)
+- Bridge requests + responses with payload previews
+
+Format is one line per event:
+
+```
+2026-05-24T07:14:33.123Z [ERROR] window.error {"message":"...","file":"...","line":42}
+2026-05-24T07:14:35.456Z [SEND]  image_generate {"entityId":"ent_modeldef_..."}
+2026-05-24T07:14:36.789Z [RECV]  response       {...}
+```
+
+**For AI agents pair-debugging with a developer:** tail this file instead of asking the developer to open DevTools and copy-paste output. Reproduce the failing action in the browser, then read the file — you'll see exactly what the iframe and harness exchanged.
+
+```bash
+tail -f /tmp/fias-dev-3200.log
+```
+
+The file is truncated on every `fias-dev` start, so it always reflects the current session.
+
+The mirror uses `navigator.sendBeacon` (with a `fetch` fallback) so there's a sub-second delay before the most recent events land in the file. If you're chasing a race, give it a beat before reading.
+
 ### Validating the Manifest
 
 ```bash

package/templates/default/CLAUDE.md

@@ -220,10 +220,10 @@ function ImageMaker() {
       <button
         onClick={() =>
           generate({
-            entityId: 'ent_modeldef_dalle3',
+            entityId: 'ent_modeldef_gpt_image_1_5',
             prompt: 'A serene mountain landscape at sunset',
             size: '1024x1024',
-            quality: 'hd',
+            quality: 'high',
           })
         }
         disabled={isLoading}
@@ -237,6 +237,56 @@ function ImageMaker() {
 }
 ```
 
+### `useFiasFiles()` — User-files filesystem (SDK ≥ 1.9.0)
+
+**Permissions:** `files:read` for `list`/`read`/`getDownloadUrl`; add `files:write` for `write`/`update`/`delete`
+**Returns:** `FiasFilesApi`
+
+Access the user's Fias filesystem, scoped to files this arche owns. Files written through this hook (and images created via `useImageGeneration()`) appear in MyData under `/My-Fias/{ArcheName}/`. Listing is by ownership — moving a file in MyData doesn't hide it from the arche.
+
+The most common use is `getDownloadUrl(fileId)` to refresh the presigned URL on a generated image after the original (~1h) expires:
+
+```tsx
+import { useFiasFiles, useImageGeneration } from '@fias/arche-sdk';
+
+function PortraitGallery({ savedFileId }: { savedFileId: string }) {
+  const { getDownloadUrl } = useFiasFiles();
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    getDownloadUrl(savedFileId).then((r) => {
+      if (!cancelled) setUrl(r.url);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [savedFileId, getDownloadUrl]);
+
+  return url ? <img src={url} alt="" /> : null;
+}
+```
+
+**Store the `fileId`, not the `imageUrl`.** Image-generation results include both, but `imageUrl` is a short-lived presigned link. Persist `fileId` in your data store and resolve to a fresh URL on render via `getDownloadUrl`.
+
+**Same-name writes overwrite.** Calling `write({ name: 'save.json', content })` twice with the same name reuses the existing `fileId` and replaces the content — useful for periodic snapshots.
+
+**`read()` is text-only.** It rejects binary content types with HTTP 415. Use `getDownloadUrl(fileId)` and pass the URL to `<img>`, `fetch`, etc. for binaries.
+
+```tsx
+const files = useFiasFiles();
+
+await files.write({
+  name: 'save.json',
+  content: JSON.stringify(state),
+  contentType: 'application/json',
+});
+const { content } = await files.read(fileId);
+const { files: page, nextCursor } = await files.list({ limit: 20 });
+await files.update(fileId, { tags: ['draft'] });
+await files.delete(fileId);
+```
+
 ### `useFiasNavigation()` — In-plugin routing
 
 **Permission:** None required
@@ -337,6 +387,12 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 
 These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
 
+### Hitting a limit? Tell the user about Entity requests
+
+Don't just say "can't do that" when the user asks for something blocked by these rules — most often a direct external API call, a third-party service, or a capability the platform hasn't surfaced yet. The Fias team adds new **Entities** on request: platform-managed wrappers that hold credentials, handle auth, and expose the capability to plugins through `useEntityInvocation()` (or `useImageGeneration()` for image models). The plugin never bypasses the sandbox — it invokes the new Entity like any other model.
+
+When you hit a constraint, say so AND tell the user: file an Entity request on the Customer Support arche at `https://platform.fias.io/a/arche_customer_support`. Describe the service, endpoints, and auth method needed; once the Entity ships, the plugin can call it via `useEntityInvocation` with no sandbox change. Then propose a fallback that works inside the current sandbox (mock data, a simpler path, deferring the call) so the build keeps moving while the request is in flight.
+
 ### Sandboxing
 
 - Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin allow-downloads"`
@@ -390,6 +446,18 @@ If newer package versions are available, tell the user and ask if they want to u
 
 If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
 
+#### UI cache after a harness upgrade
+
+The harness pulls its host-page UI (toolbar, mode toggle, sign-in modal) from a CDN and caches it in `~/.fias/harness-cache/`. The cached UI takes priority over the bundled copy that ships in the npm package.
+
+When you upgrade `@fias/plugin-dev-harness` but the CDN hasn't been redeployed yet, the cached UI can be older than the CLI. fias-dev now detects this case automatically and falls back to the bundled UI — look for this line in the startup log:
+
+```
+ℹ Cached harness UI v1.14.3 is older than CLI v1.18.0 — using bundled UI.
+```
+
+That message means everything is fine; the bundled UI exactly matches your CLI version. If you ever see stale behavior persist across an upgrade (and the line above didn't appear), delete `~/.fias/harness-cache/` and restart.
+
 ### Starting Development
 
 ```bash
@@ -423,9 +491,42 @@ npx fias-dev login --env production   # Authenticate with production
 npx fias-dev entities                              # List all
 npx fias-dev entities --search "image"             # Search by keyword
 npx fias-dev entities --type "model-definition"    # Filter by type
-npx fias-dev entities --detail ent_modeldef_dalle3 # Full entity details (capabilities, sizes, pricing)
+npx fias-dev entities --detail ent_modeldef_gpt_image_1_5 # Full entity details (capabilities, sizes, pricing)
 ```
 
+### Debugging — Read the Browser's View Directly
+
+The harness mirrors every browser-side event to a per-port log file at `/tmp/fias-dev-<port>.log` (so usually `/tmp/fias-dev-3200.log`). The file path is also printed at startup:
+
+```
+Browser dev-log mirror: /tmp/fias-dev-3200.log
+```
+
+What's captured:
+
+- Every Dev Console entry (`send` / `recv` / `info` / `error` / `toast` / `cost` / `nav`)
+- Every uncaught JS error (`window.error`)
+- Every unhandled promise rejection (`unhandledrejection`)
+- Bridge requests + responses with payload previews
+
+Format is one line per event:
+
+```
+2026-05-24T07:14:33.123Z [ERROR] window.error {"message":"...","file":"...","line":42}
+2026-05-24T07:14:35.456Z [SEND]  image_generate {"entityId":"ent_modeldef_..."}
+2026-05-24T07:14:36.789Z [RECV]  response       {...}
+```
+
+**For AI agents pair-debugging with a developer:** tail this file instead of asking the developer to open DevTools and copy-paste output. Reproduce the failing action in the browser, then read the file — you'll see exactly what the iframe and harness exchanged.
+
+```bash
+tail -f /tmp/fias-dev-3200.log
+```
+
+The file is truncated on every `fias-dev` start, so it always reflects the current session.
+
+The mirror uses `navigator.sendBeacon` (with a `fetch` fallback) so there's a sub-second delay before the most recent events land in the file. If you're chasing a race, give it a beat before reading.
+
 ### Validating the Manifest
 
 ```bash