@fugood/bricks-project 2.25.0-beta.4 → 2.25.0-beta.40

package/skills/bricks-ctor/references/buttress.md

@@ -0,0 +1,245 @@
+# Buttress (Remote Inference)
+
+Backend system for offloading compute-intensive AI generator tasks from BRICKS devices to more powerful machines.
+
+## Purpose
+
+When mobile devices or embedded systems lack hardware for local AI inference (LLM, speech-to-text), Buttress transparently delegates work to a server with appropriate resources (GPU).
+
+## How It Works
+
+1. **Capability Exchange**: Client and server share hardware capabilities
+2. **Strategy Selection**: System decides local vs. remote execution
+3. **Transparent Offloading**: Generator operates same way, execution happens remotely
+
+## Supported Generators
+
+- LLM (GGML) (LlmMlx.ts) - Local Large Language Model inference with GGML
+- LLM (MLX) (LlmGgml.ts) - Local Large Language Model inference with MLX
+- Speech-to-Text (GGML) (SpeechToTextGgml.ts) - Local Speech-to-Text inference with GGML
+
+## Client Configuration
+
+In generator properties, configure `buttressConnectionSettings`:
+
+| Setting | Description |
+|---------|-------------|
+| `enabled` | Toggle Buttress offloading |
+| `autoDiscoverType` | `auto` (LAN auto-discovery, recommended) or `manual` (typed URL) |
+| `url` | Server URL (`manual` mode only — leave empty for `auto`) |
+| `fallbackType` | If Buttress is unreachable: `use-local` runs locally, `no-op` blocks the load |
+| `strategy` | Execution preference (see below) |
+
+The launcher provides the access token automatically — there is **no user-facing access-token setting**. In `auto` mode the launcher discovers servers bound to the device's workspace and uses its workspace-scoped JWT; in `manual` mode it sends the same JWT only when the typed URL belongs to a server bound to the same workspace (verified against the server's `/buttress/info`).
+
+### `autoDiscoverType` options
+
+| Mode | When to use | What the device does |
+|------|-------------|----------------------|
+| `auto` | LAN deployment with a workspace-bound buttress-server | Listens for UDP announcements and picks the strongest server bound to its workspace; reconnects automatically when the workspace flips |
+| `manual` | Internet-reachable server, mixed networks, or a public/unbound server | Connects to the typed `url` directly; sends a token only when the server is bound to the same workspace |
+
+### Strategy options
+
+| Strategy | Description |
+|----------|-------------|
+| `prefer-local` | Use local if capable, fallback to Buttress |
+| `prefer-buttress` | Use Buttress if available, fallback to local |
+| `prefer-best` | Auto-select based on capability comparison |
+
+## Generator Configuration Examples
+
+### Auto-discovery (recommended)
+
+Workspace-bound launcher + workspace-bound buttress-server on the same LAN. No URL needed — discovery picks the highest-scoring server that runs the requested backend.
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+const llmGenerator: GeneratorLLM = {
+  __typename: 'Generator',
+  templateKey: 'GENERATOR_LLM',
+  id: makeId('generator'),
+  title: 'Chat LLM',
+  description: '',
+  property: {
+    modelUrl: 'https://huggingface.co/ggml-org/gemma-3-12b-it-qat-GGUF/resolve/main/gemma-3-12b-it-qat-q4_0.gguf',
+    contextSize: 8192,
+    buttressConnectionSettings: {
+      enabled: true,
+      autoDiscoverType: 'auto',
+      fallbackType: 'use-local',
+      strategy: 'prefer-best',
+    },
+  },
+  events: {},
+  switches: [],
+}
+```
+
+### Manual URL
+
+Use when the server isn't on the launcher's broadcast domain (cross-subnet, internet, behind a reverse proxy) or you want to point at a specific public/unbound server.
+
+```typescript
+buttressConnectionSettings: {
+  enabled: true,
+  autoDiscoverType: 'manual',
+  url: 'http://192.168.1.100:2080',
+  fallbackType: 'use-local',
+  strategy: 'prefer-best',
+}
+```
+
+> ⚠️ With `fallbackType: 'no-op'` the generator refuses to load locally if Buttress is unreachable. Use `'use-local'` whenever the device can also run the model standalone.
+
+## Integrating a discovered buttress-server
+
+The ctor-desktop "Local Devices" panel (and the `bricks buttress scan` CLI) can hand you a server's identity, workspace, and announced generator caps. When the user asks to integrate one:
+
+1. **Confirm workspace match.** The discovery message says whether the server's workspace matches this project's. If it doesn't, do NOT add the integration — instruct the user to run `bricks buttress unbind && bricks buttress bind` from this workspace's owner CLI on the server host. The launcher won't trust a cross-workspace server.
+
+2. **Map announced types to generator templates.** For each `generators[].type` in the announce, target the matching templateKey (create the generator if absent):
+
+   | Announced type | templateKey                  | Default model |
+   |----------------|------------------------------|---------------|
+   | `ggml-llm`     | `GENERATOR_LLM`              | `ggml-org/gemma-3-12b-it-qat-GGUF` (≥20 GB usable) or `ggml-org/gpt-oss-20b-GGUF` (~12 GB usable) |
+   | `mlx-llm`      | `GENERATOR_MLX_LLM`          | `mlx-community/Qwen3-4B-4bit` (or a larger 4-bit quant if `usableBytes` allows) |
+   | `ggml-stt`     | `GENERATOR_SPEECH_INFERENCE` | `BricksDisplay/whisper-ggml` (filename `ggml-small-q8_0.bin`) |
+
+   Pick a model that fits the announced `usableBytes`. Set `contextSize` to match.
+
+3. **Use the canonical auto-discovery config** from "Auto-discovery (recommended)" above. Don't switch to manual mode just because the server is on the LAN — auto mode picks the workspace-bound server automatically and rebinds when the device's workspace flips.
+
+### Real-device caveat
+
+Buttress LAN auto-discovery uses native UDP via `react-native-jsi-udp`. The iOS Simulator silently fails to bind UDP, so auto mode is a no-op there. With `fallbackType: 'use-local'` the generator falls back to local inference in the simulator — dev/test stays functional. **Validate the buttress path itself only when deploying to a real Foundation device; don't gate the build on simulator validation.**
+
+## Server Setup
+
+### Requirements
+- [Bun](https://bun.sh) v1.3+
+- GPU recommended for LLM/STT
+
+### Installation
+
+```bash
+bun add -g @fugood/buttress-server
+```
+
+### Start Server
+
+```bash
+bricks-buttress
+# or with config
+bricks-buttress --config ./config.toml
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port` | Port (default: 2080) |
+| `-c, --config` | TOML config file path |
+| `-v, --version` | Show version |
+| `-h, --help` | Show help |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HF_TOKEN` | Hugging Face token for model downloads |
+| `ENABLE_OPENAI_COMPAT_ENDPOINT` | Set to `1` for OpenAI-compatible API |
+| `BRICKS_BUTTRESS_STATE_DIR` | Override the workspace state directory (default `~/.bricks-cli/buttress`) |
+
+## Bind the Server to a Workspace
+
+To use `autoDiscoverType: 'auto'` — and to require workspace-scoped JWT auth — pair the buttress-server with a BRICKS workspace using the `bricks buttress` CLI commands. An unbound server stays in legacy public mode and accepts any LAN client.
+
+### One-time bind
+
+```bash
+# Log into the cloud bricks-server with the workspace owner's account
+bricks auth login
+
+# Pair the buttress-server running on this machine with the active workspace
+bricks buttress bind
+
+# Restart bricks-buttress so it picks up the new state.json
+```
+
+`bricks buttress bind` writes `~/.bricks-cli/buttress/state.json` containing the workspace id, the issuer's Ed25519 public key, and a stable `serverId` (defaults to `buttress-<machineId>`). Override location with `--state-dir` or `$BRICKS_BUTTRESS_STATE_DIR`. For headless setups, use `bricks buttress bind --print` to emit state.json to stdout.
+
+### Verify and manage
+
+```bash
+# Show local binding + workspace-side bound list
+bricks buttress status
+
+# Discover buttress-servers on the LAN (with version, auth state, generator caps)
+bricks buttress scan
+
+# Issue a long-lived workspace access token (CI / ctor agents that already hold a workspace token)
+bricks buttress issue-token --ttl 86400
+
+# Detach this server from the workspace
+bricks buttress unbind
+```
+
+After binding, launchers in the same workspace will auto-discover this server; manual-mode generators will only send their access token if the server's reported workspace matches their own.
+
+## Server Configuration (TOML)
+
+```toml
+[server]
+port = 2080
+
+[runtime]
+cache_dir = "./.buttress-cache"
+n_threads = 6
+flash_attn_type = "on"
+cache_type_k = "q8_0"
+cache_type_v = "q8_0"
+
+# LLM Generator
+[[generators]]
+type = "ggml-llm"
+[generators.backend]
+variant_preference = ["cuda", "vulkan", "default"]
+gpu_memory_fraction = 0.95
+[generators.model]
+repo_id = "ggml-org/gemma-3-12b-it-qat-GGUF"
+download = true
+n_ctx = 8192
+
+# STT Generator
+[[generators]]
+type = "ggml-stt"
+[generators.backend]
+variant_preference = ["cuda", "vulkan", "default"]
+[generators.model]
+repo_id = "BricksDisplay/whisper-ggml"
+filename = "ggml-small-q8_0.bin"
+download = true
+use_gpu = true
+```
+
+## Use Cases
+
+### Resource-Constrained Devices
+Digital signage with basic hardware offloads LLM to powerful server.
+
+### Shared GPU Resources
+Multiple devices share single GPU server for inference.
+
+### Development Testing
+Test AI features on lightweight dev machines by connecting to beefy server.
+
+## Best Practices
+
+1. **Network reliability**: Ensure stable LAN connection to Buttress server
+2. **Fallback strategy**: Configure appropriate fallback for critical features
+3. **Server monitoring**: Monitor Buttress server resource usage
+4. **Model consistency**: Ensure client and server use compatible models
+5. **Security**: Run Buttress on private network, not public internet
+6. **Latency awareness**: Account for network latency in UX design

package/skills/bricks-ctor/{rules → references}/data-calculation.md

@@ -167,7 +167,7 @@ code: `
 
 ## Triggering Manually
 
-Use `PROPERTY_BANK_COMMAND` system action to trigger a manual calculation:
+Use `PROPERTY_BANK_COMMAND` system action to trigger a manual calculation. `input` references a Data that is a trigger input (`trigger: true`) of the target calc — the system runs the calc(s) that data feeds into. It does NOT reference the DataCalculation itself.
 
 ```typescript
 const triggerCalc: EventAction = {
@@ -176,12 +176,14 @@ const triggerCalc: EventAction = {
     __actionName: 'PROPERTY_BANK_COMMAND',
     parent: 'System',
     dataParams: [
-      { input: () => computeTotalCalc }, // Reference to DataCalculation
+      { input: () => priceData }, // Reference to a trigger Data input of the calc
     ],
   },
 }
 ```
 
+When the same chain writes a calc input (e.g. `PROPERTY_BANK` setting `dLastButton`) then issues `PROPERTY_BANK_COMMAND`, set `waitAsync: true` on the write so the calc reads the new value rather than the pre-chain snapshot. See [Event Action Chains](architecture-patterns.md#event-action-chains-priority-2).
+
 ## Best Practices
 
 1. **Avoid circular deps**: Set non-triggering inputs (`trigger: false`) or use `manual` mode
@@ -194,9 +196,7 @@ const triggerCalc: EventAction = {
 See [Architecture Patterns](architecture-patterns.md) for the full pattern selection guide.
 
 ### Using Data Calc as an orchestrator
-Scripts that manage state machines, control UI flow, or coordinate multi-step processes belong in Event Action Chains, not here.
-
-**Symptom**: Script has if/else branches deciding "what happens next" or tracks "current step".
+Scripts that manage state machines, control UI flow, or coordinate multi-step processes belong in Event Action Chains. Symptoms: if/else on "what happens next", mirror `dFooResult` outputs that copy back to `dFoo` via `valueChange`, or a `dLastInput` field set-then-cleared to force an auto calc. See the "user-driven state machine" recipe in [Architecture Patterns](architecture-patterns.md).
 
 ### Quick reference
 

package/skills/bricks-ctor/references/simulator.md

@@ -0,0 +1,115 @@
+# Simulator
+
+What the Simulator can and can't faithfully reproduce — so a passing Simulator run means what you think it means. This is the fidelity companion to Path 1 in [Verification Toolchain](verification-toolchain.md); read that for how to *drive* the Simulator (compile, screenshot, Automations).
+
+## What it is
+
+- The default Path 1 target: it renders your compiled project on your computer, with no device required.
+- It runs in Chromium/Electron — a browser-class runtime, not the device runtime. Two consequences to design verification around: it has a browser's capabilities and limits (below), and its JavaScript engine differs from the device's (iOS runs JSC, Android runs Hermes), so engine-specific behavior won't surface here.
+
+A Simulator screenshot proves **layout, navigation, Standby Transitions, Data wiring, and generator/Automation wiring**. It does *not* prove anything that depends on real hardware, real models, or capabilities the preview runtime lacks.
+
+## Automation screenshots
+
+`match_screenshot` stores Simulator automation artifacts at the project level:
+
+```text
+.bricks/automation_screenshots/
+  last/
+  failed/
+  diff/
+```
+
+There is no application-id subdirectory; in CTOR the project is the application. Generated project `.gitignore` files exclude this directory.
+
+When a `match_screenshot` baseline is missing or updated, the baseline goes under `last/`. When a screenshot mismatch occurs, the current capture goes under `failed/` and the pixel diff goes under `diff/`. File names follow `<screenshotName>+local+<timestamp>.png`.
+
+In CTOR Desktop, `simulator_invoke` reports any automation screenshot files created or changed by the invocation in an `Automation screenshots:` section. It still separately reports the ordinary preview capture at `.bricks/simulator-screenshot.jpg`.
+
+## What the Simulator can't reproduce
+
+Because it runs in a browser-class preview rather than on device hardware, the Simulator cannot exercise these — a green run says nothing about them. Verify on a real device (Path 2):
+
+| Area | In the Simulator |
+|------|------------------|
+| BLE (Central / Peripheral), Video Streaming | Not available |
+| Raw network sockets — UDP, TCP, TCP Server, MQTT Broker | Not available (also why Buttress LAN discovery is a no-op — see [Buttress](buttress.md)) |
+| Android Intent | Not available (Android-only) |
+| On-device database **persistence** (SQLite / Vector Store) | Not available — both run in-memory in the Simulator (see caveats below), so data never survives a reload |
+| GGML Text-to-Speech | No vocoder in the preview — use an ONNX TTS model to hear speech |
+
+These work, but with browser caveats:
+
+| Area | Caveat |
+|------|--------|
+| Serial Port | Works via WebSerial — requires browser support and a user gesture |
+| WebView / WebCrawler | Subject to browser CORS — a load/fetch that works on device may be blocked |
+| On-device AI (LLM / STT / VAD / Vector Store / Reranker) | Runs **single-threaded** — far slower than the device, not representative of real latency. Also subject to the model fallbacks below |
+| On-device database (SQLite — `GENERATOR_SQLITE`) | Runs for real on the in-memory WASM `sqlite-vec` build — `execute` / `query` / `transaction` / batch all work. `storageType: file` is transparently treated as in-memory, so nothing persists across reloads (see above) |
+| Scene3D / Maps / Sketch / WebRTC | Supported |
+
+Feature availability also varies across the device platforms themselves (iOS / tvOS / Android / the desktop OSes). When a deployment targets a specific platform's capability, confirm it on that platform.
+
+## Network security
+
+The Simulator blocks insecure connections from `applicationPreview` by default: `http://` and `ws://` requests fail, while `https://` and `wss://` are allowed. The Simulator internally allows its own preview host when running the development preview.
+
+Generated projects include this project-level setting:
+
+```json
+{
+  "allowedInsecureHosts": []
+}
+```
+
+Add explicit entries only when you deliberately need to test an insecure endpoint in the Simulator. A bare `host:port` allows both `http://` and `ws://` for that host:
+
+```json
+{
+  "allowedInsecureHosts": ["localhost:8080"]
+}
+```
+
+Use a URL form when only one insecure protocol should be allowed:
+
+```json
+{
+  "allowedInsecureHosts": ["http://localhost:8080"]
+}
+```
+
+In that example, `http://localhost:8080` is allowed and `ws://localhost:8080` remains blocked.
+
+Prefer HTTPS/WSS for anything that is not local development.
+
+## Feature fallbacks — what the Simulator fakes
+
+So that camera and AI features are usable without device permissions, multi-gigabyte downloads, API keys, or a remote inference backend, the Simulator **transparently substitutes a lightweight stand-in** for a few bricks/generators. The config you author is untouched — only the Simulator's runtime behavior differs. **A fallback render proves wiring and layout, not the real feature.**
+
+| Brick / Generator | In the Simulator | Does NOT prove |
+|-------------------|------------------|----------------|
+| Camera (`BRICK_CAMERA`) | A 3D mock canvas, no camera permission prompt. `takePicture` snapshots the canvas; recording produces a placeholder clip | Real camera feed, focus, recording, permission flow |
+| Thermal Printer (`GENERATOR_THERMAL_PRINTER`) | A simulated printer — `init` / `checkStatus` / `scan` fake per-driver status and discovered devices (ESC/POS, Star, TSC, Castles); `print` renders an approximate on-screen receipt. A bottom-left bubble shows live status with a fault toggle to exercise error wiring | Real device connection, actual paper output, exact native driver status codes |
+| LLM (`GENERATOR_LLM`) | Swapped to a tiny local stand-in model | Output quality / latency of your real model |
+| Reranker — GGML (`GENERATOR_RERANKER`) | Swapped to a small local multilingual reranker model | Ranking quality / latency of your real model |
+| Speech-to-Text — GGML (`GENERATOR_SPEECH_INFERENCE`) | Swapped to a tiny local model | Accuracy / latency of your real model |
+| Speech-to-Text — ONNX (`GENERATOR_ONNX_STT`) | Swapped to a tiny whisper model | Accuracy / latency of your real model |
+| Text-to-Speech — ONNX (`GENERATOR_TTS`) | Swapped to a tiny VITS model (no vocoder or speaker embedding) | Voice / quality / latency of your real model |
+| Vector Store (`GENERATOR_VECTOR_STORE`) | Runs with a tiny local embedding model — an OpenAI-source config works **without a key** | Real embeddings / dimensions / recall (and no persistence — see above) |
+| Buttress (all generators) | **Disabled** — there is no remote inference backend in the Simulator | The Buttress offload path — see [Buttress](buttress.md) |
+| MLX LLM (`GENERATOR_MLX_LLM`) | Runs as authored, except Buttress is disabled | The MLX / Buttress path |
+
+These swaps make the AI generators runnable in the Simulator for wiring checks — validate real models, quality, and latency on a device (Path 2).
+
+### Running the real implementation instead
+
+Each substituted brick/generator can be switched back to its real implementation per item: open the **gear (Simulator settings)** in the editor's preview toolbar, uncheck the item, and **Apply**. Apply persists the choice and reloads the preview so it takes effect (a plain refresh won't). Use this to, e.g., point a Vector Store at a real API key in the preview. The browser limits above still apply, and **Buttress stays disabled regardless** — there's no backend for it here.
+
+The Thermal Printer is the exception: it has no real web implementation to switch to (the native drivers can't run in a browser), so it is **always simulated** and is not in the gear list.
+
+## Enough vs. escalate
+
+- **Simulator is enough for:** layout, navigation, Standby Transitions, Data wiring, Automation / state-machine happy paths, and confirming a generator fires and handles its events.
+- **Escalate to a real device for:** anything in the "can't reproduce" tables, real camera / peripherals / payment / identity, real model quality & latency, multi-device Local Sync, on-device persistence, the Buttress offload path, and engine-specific behavior.
+
+The full Path 1/2/3 decision rule lives in [Verification Toolchain](verification-toolchain.md).

package/skills/bricks-ctor/references/verification-toolchain.md

@@ -0,0 +1,179 @@
+# Verification Toolchain
+
+Three runtime targets, one decision rule. Verify against the cheapest path that proves what you need to prove.
+
+## Definition of done — the hard gate
+
+Before the agent is allowed to claim work is complete, **all** of the following must be true:
+
+1. **Compile clean.** Latest source passes `compile` with no errors.
+2. **Every Canvas screenshot captured.** A rendered screenshot of every Canvas in the deliverable, captured via the available preview tool (`responseImage: true` when the selected model supports vision) at the target hardware resolution and orientation. Canvases gated behind events are reached via Automation runs (`testId` / `testTitleLike` with `brick_press` / `wait_until_canvas_change` cases). Single-Canvas Subspaces still require a captured screenshot.
+3. **Every screenshot reviewed by the agent.** The agent must read each captured screenshot back through the host's image-reading capability — saving the file is not the same as seeing it. The model that produced the Canvas must also have seen the rendered result, or the verification gate has not passed.
+4. **Reference comparison report.** If the user supplied any reference material (Figma / website / HTML / screenshot / PDF / brand book / competitor), produce a short delta report per Canvas:
+   - What matches the reference.
+   - What intentionally diverges, and why (deployment constraint, BRICKS-runtime semantic, system commitment).
+   - What unintentionally diverges, and the planned fix.
+5. **Path appropriate to deployment executed.** Path 1 by default. Path 2 (on-device) when the deployment depends on real hardware behaviour, or whenever the brief touches payment, identity, peripherals, or LocalSync.
+6. **Console clean.** No 404s on media, no Data-key-undefined warnings, no Generator init failures, no React-style warnings — every console line is either zero or accept-with-a-comment.
+
+What does **not** count as done:
+
+- A single hero-Canvas screenshot.
+- "Looks roughly like the reference" with no per-Canvas comparison.
+- "Compiled successfully" with no rendered preview.
+- A claim of done with no screenshots in evidence.
+- Captured screenshots saved to disk but never read back by the agent.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.
+
+## Path 1 — Simulator (no device required)
+
+The default loop. Always available; deterministic; no device wear; safe for side-effecting flows because nothing real fires.
+
+Before trusting a Simulator screenshot, know what it can and can't reproduce: it runs in the Electron preview (a browser-class runtime, not the device — and not the device's JS engine), can't exercise hardware/peripheral features (BLE, printers, raw sockets, SQLite, …), and substitutes fallbacks for Camera and the AI generators (LLM/STT/Vector Store) with Buttress disabled. See [Simulator](simulator.md) for the fidelity boundaries and the per-item gear to run the real implementation — it's what tells you when a green run is enough vs. when to escalate to Path 2.
+
+`bun update-app` and `bun deploy-app` publish to the BRICKS portal. The local preview reads `.bricks/build/application-config.json` (produced by `compile`) directly.
+
+### Compile tool
+
+Typecheck + compile the project. Gate every iteration on this; everything below assumes a clean compile.
+
+Agent invocation: call the MCP tool `compile` exposed by the `bricks-ctor` MCP server registered for the project. No arguments.
+
+### Simulator tool
+
+Use the preview implementation exposed by the current harness:
+
+- **CTOR Desktop agent session:** use `simulator_invoke`. CTOR Desktop disables the `bricks-ctor` MCP `simulator` tool and routes screenshots/automation through the desktop preview pane instead. If the user already opened the simulator pane, `simulator_invoke` should reuse it rather than start a separate preview.
+- **Pure `bricks-ctor` project / other agent harness:** use the `bricks-ctor` MCP `simulator` tool when `simulator_invoke` is not available.
+
+Both forms are the same verification primitive: launch or reuse Electron preview, take a screenshot, and optionally run a named Automation test by id or partial title. Do not hard-code one tool name into the workflow; choose the available preview tool for the environment.
+
+Common arguments:
+- `delay` (ms before screenshot) — default is harness-specific: usually 3000 for a fresh/standalone preview; CTOR Desktop may capture immediately when its preview already has a settled latest config. Increase if Standby Transitions are still in flight.
+- `width`, `height` — screenshot dimensions in px.
+- `responseImage: true` — return the screenshot as image content when the selected model supports vision. If vision is unavailable, save the screenshot and report the path.
+- `testId` or `testTitleLike` — run a project Automation before the screenshot. Use `testTitleLike` for fuzzy matches (case-insensitive partial title).
+
+Returns text log + saved screenshot path + image content when supported.
+
+### `bun invoke-simulator` (project script)
+
+Sustained dev session — watches `subspaces/`, recompiles on save, exposes CDP at `localhost:19852` (configurable via `--cdp-port`), writes `.bricks/devtools.json` with port/pid for downstream tooling.
+
+Useful flags:
+- `--screenshot` + `--screenshot-delay/width/height/path` — drive screenshot capture without keeping the window open.
+- `--show-menu` — surface the Electron menu (debugging).
+- `--test-id` / `--test-title-like` — run an Automation in this preview.
+- `--no-keep-open` — exit after one screenshot.
+- `--no-cdp` — disable CDP server (rare; default is to expose it).
+- `--clear-cache` — reset cached state between runs.
+
+For ad-hoc CDP inspection against this local preview, connect any CDP client to `localhost:19852` — Chrome DevTools front-end works directly. For an agent-friendly CLI over CDP (screenshot, brick tree/query, input emulation, storage reads, runtime eval, network capture), the `bricks-cli` skill documents the `bricks devtools` command surface — read that skill if it is installed in this workspace. If it is not installed, run `bricks --help` and `bricks devtools --help`; the CLI's own help output is authoritative.
+
+### Project Automations
+
+E2E tests authored in TypeScript inside the project (`AutomationTest` / `TestCase`). Test cases include:
+
+- `brick_press` — synthesize a press on a Brick.
+- `wait_until_canvas_change` — assert navigation.
+- `assert_property` — assert a Data value equals expected.
+- `wait_property_update` — wait for a Data value to change.
+- `match_screenshot` — visual regression with stored reference image.
+
+Trigger types: `launch` (runs on app start), `anytime` (manual), `cron` (scheduled).
+
+Important: the automation map id must be `'AUTOMATION_MAP_DEFAULT'` (not a generated id) — the preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
+
+Run a single test from the agent: call the available preview tool (`simulator_invoke` in CTOR Desktop, otherwise `bricks-ctor` MCP `preview`) with `testId` or `testTitleLike`.
+
+## Path 2 — Real device with DevTools enabled
+
+Required when the deployment depends on hardware behaviour the Electron preview cannot reproduce: physical orientation/DPI, real touch hardware (IR overlays, multi-touch), peripherals (camera, BLE, MQTT, NFC, payment, printer, sensors), watchdog cycles on the actual launcher build, fleet-managed reboot semantics, LocalSync across multiple devices, the actual color/luminance of the panel.
+
+**Always Path 2** when the brief touches: payment, identity capture, real-time peripheral data, multi-device LocalSync, certified hardware.
+
+### One-time manual setup (the agent cannot do this)
+
+Ask the user to:
+
+1. On the device, open **Settings** → advanced settings.
+2. Toggle **Chrome DevTools** on. The device starts a DevTools server on the local network on port `19851` (auto-increments if taken).
+3. Confirm **Enable LAN Discovery** is on (default) so the device is discoverable.
+4. Note the device passcode if displayed.
+
+Requires BRICKS Foundation **≥ 2.24** for CDP commands.
+
+### Endpoints exposed once enabled
+
+| Endpoint | URL shape | Use |
+|---|---|---|
+| Web UI | `http://<ip>:19851` | DevTools landing in a browser |
+| CDP | `http://<ip>:19851/devtools-frontend/inspector.html?ws=<ip>:19851/ws/<passcode>` | Chrome DevTools front-end |
+| MCP | `http://<ip>:19851/mcp` | MCP endpoint (Bearer-token auth with passcode) |
+| MCP SSE | `http://<ip>:19851/sse` | Same, SSE transport |
+| Info | `http://<ip>:19851/devtools/info` | Device / server metadata |
+
+### Driving the device
+
+Once DevTools is on, ask the user how they want to drive the verification — Chrome DevTools front-end, an MCP client they already run, or screenshot export from their own tooling — and follow their lead. Capture every Canvas screenshot through whichever path the user picks; the verification gate is about the evidence, not the tool.
+
+For agent-driven CDP/MCP work against the device (`bricks devtools …` with `-a <ip> --passcode <pc>`, plus bridging the device MCP endpoint into an MCP client), the same `bricks-cli` skill referenced in Path 1 covers the on-device case — read it if installed. If not installed, run `bricks --help` and `bricks devtools --help` for the authoritative command listing.
+
+### Real-device side-effects warning
+
+Real devices fire real peripherals. Payment terminals charge. MQTT broadcasts on shared topics. BLE advertises to bystanders. Use a **staging** device for verification cycles; never iterate on a production-deployed device unless the user explicitly approves.
+
+## Path 3 — Remote debugging via BRICKS Controller (off-LAN)
+
+Out of scope for the standard verification loop. It exists for ops scenarios where the device is not on the same network. If the user asks for it, point them at the BRICKS Controller documentation rather than attempting it as part of verification.
+
+## Decision rule
+
+```
+default Path 1.
+
+if deployment depends on:
+   physical orientation / DPI / touch HW / peripherals /
+   watchdog on real launcher / LocalSync / certified hardware
+→ escalate to Path 2 before declaring done.
+
+if brief touches payment, identity, peripherals, LocalSync
+→ Path 2 is mandatory, not optional.
+
+if user is off-LAN
+→ Path 3 (out of scope here).
+```
+
+## What to actually verify (per shape)
+
+### Static signage (single-canvas glance loop)
+- Path 1 screenshot captures the loop frame.
+- Watch one full rotation in `bun invoke-simulator` to see all queue items.
+- Cut network mid-loop; confirm cached media plays.
+- Path 2 only if the panel is OLED / has burn-in concerns or specific color profile.
+
+### Multi-canvas state machine (kiosk)
+- Path 1: Automation walking the happy path with `brick_press` + `wait_until_canvas_change` + `assert_property` + `match_screenshot` per Canvas.
+- Cancel + inactivity reset paths verified as Automations.
+- Watchdog reset: kill the runtime, restart, confirm boot Canvas resets transient flow Data.
+- Path 2 mandatory if payment / identity is in the flow — fire a real test transaction on staging hardware.
+
+### Subspace-driven composition
+- Path 1: open the Subspace standalone if the preview supports it; verify in isolation.
+- Embedded test: walk the host's flow; assert Outlets fire as expected via `wait_property_update`.
+- Re-mount test: cause the host to re-bind the Subspace; confirm internal state resets.
+
+### Generator-driven reactive
+- Path 1: drive the source by writing to Data from the runtime (whatever CDP path the user prefers); observe Brick re-render.
+- Throttle / firehose tests: write 100 updates rapidly; confirm the canvas doesn't choke (frame budget intact).
+- Disconnect: simulate source disconnect; confirm UI surfaces stale state, not blank.
+- Threshold transitions: cross every Switch boundary; confirm visual reaction.
+- Path 2 mandatory if the source is a real peripheral — Electron cannot fake the timing or the failure modes.
+
+### Multi-device LocalSync
+- Path 2 mandatory. Two devices on the same LAN with DevTools on. Drive one, observe the other.
+
+## Browser / runtime log discipline
+
+Throughout: the DevTools console must be clean. 404s on media, "Data key not defined" warnings, Generator init failures, React-style warnings — every one is a defect or accept-with-comment. Don't ship around them.