@fias/arche-sdk 1.11.0 → 1.12.0

package/templates/default/AGENTS.md

@@ -446,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
@@ -482,6 +494,39 @@ npx fias-dev entities --type "model-definition"    # Filter by type
 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

@@ -446,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
@@ -482,6 +494,39 @@ npx fias-dev entities --type "model-definition"    # Filter by type
 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