@fugood/bricks-ctor 2.25.0-beta.6 → 2.25.0-beta.60

package/compile/util.ts

@@ -1,4 +1,4 @@
-import { makeId } from '../utils/id'
+import { makeSeededId } from '../utils/id'
 
 type ScriptConfig = {
   title?: string
@@ -18,30 +18,152 @@ const errorMsg = 'Not allow duplicate set property id between inputs / outputs /
 export const validateConfig = (config: ScriptConfig) => {
   // Skip input/output overlap validation in manual mode (allows same data node in both)
   if (config.trigger_mode === 'manual') return
-  if (config.error && config.inputs[config.error]) {
+  // `inputs` is keyed by data-node id with the OBJECT_SET path as the *value*. The overlap
+  // check is "is this id also an input?" — a key-existence question — so test key presence,
+  // not the path's truthiness. An empty path ('' = OBJECT_SET's default "set whole object")
+  // is a legitimate input value that would otherwise slip the overlap guard.
+  const isInput = (id: string) => Object.prototype.hasOwnProperty.call(config.inputs, id)
+  if (config.error && isInput(config.error)) {
     throw new Error(`${errorMsg}. key: error`)
   }
-  if (config.output && config.inputs[config.output]) {
+  if (config.output && isInput(config.output)) {
     throw new Error(`${errorMsg}. key: output`)
   }
-  if (Object.values(config.outputs).some((value) => value.some((id) => config.inputs[id]))) {
+  if (Object.values(config.outputs).some((value) => value.some(isInput))) {
     throw new Error(`${errorMsg}. key: outputs`)
   }
+  // The same data-node id reused across the output-side targets (output / error / outputs)
+  // also collides: generateCalulationMap spreads their node objects last-wins, so the later
+  // one silently overwrites the earlier wiring (e.g. error == output drops the error change
+  // link). The checks above only compare against `inputs`, so guard the output-side pairs
+  // too. (The same id appearing in multiple `outputs` entries is a supported last-wins case
+  // and stays allowed.)
+  if (config.error && config.output && config.error === config.output) {
+    throw new Error(`${errorMsg}. key: error/output`)
+  }
+  const outputsIds = Object.values(config.outputs).flat()
+  if (config.output && outputsIds.includes(config.output)) {
+    throw new Error(`${errorMsg}. key: output/outputs`)
+  }
+  if (config.error && outputsIds.includes(config.error)) {
+    throw new Error(`${errorMsg}. key: error/outputs`)
+  }
 }
 
 const padding = 15
 const layerXInterval = 300
 const layerYInterval = 150
 
-export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMode?: boolean }) => {
+// Direction A — first-class script node (see local-plan/PLAN-data-calculation-refactor.md).
+//
+// `generateCalulationMap` keeps emitting the legacy OBJECT_SET → SANDBOX_RUN_JAVASCRIPT →
+// SANDBOX_GET_*/OBJECT_GET expansion in `map` (consumed by older runtimes). In parallel,
+// `generateScriptMap` derives an equivalent single-node graph in `script_map` that a newer
+// runtime prefers: one `command-node-script` node that assembles `inputs` from keyed input
+// ports and fans out `error` / `output` / each `outputs` path directly to the target data
+// nodes. Both are byte-stable functions of `script_config`, so codegen (which only reads
+// `script_config`) round-trips losslessly and recompiling unchanged source re-derives an
+// identical `script_map`.
+//
+// Trigger semantics stay edge-level (`disable_trigger_command` on the script node's input
+// edges, same as the legacy OBJECT_SET inputs) so the circular-reference check and the
+// manual-trigger overlay keep working unchanged — only the node count collapses N+3 → 1.
+const generateScriptMap = (config: ScriptConfig, calcId: string) => {
+  const scriptId = makeSeededId('property_bank_command', `${calcId}:script`)
+  const map: Record<string, any> = {}
+
+  // Compiled run-time config for the script node. `inputs` maps each input port name (the
+  // source data-node id) to its OBJECT_SET path; `outputs` maps each fan-out port name to the
+  // OBJECT_GET path it extracts from the return value. The runtime reads these from
+  // properties.args, keeping the node `value` reserved purely for incoming input-port values.
+  const inputArgs: Record<string, string> = {}
+  const outputArgs: Record<string, string> = {}
+
+  const scriptIn: Record<string, any> = {}
+  const scriptOut: Record<string, any> = {}
+
+  // One in-port per input, keyed by the source data-node id (unique per input, so each input
+  // keeps its own `disable_trigger_command` flag — a shared path could not). Manual mode
+  // disables every input edge; auto mode honours per-key `disabled_triggers`.
+  Object.entries(config.inputs).forEach(([dataNodeId, path]) => {
+    inputArgs[dataNodeId] = path
+    scriptIn[dataNodeId] = [
+      {
+        id: dataNodeId,
+        port: 'value',
+        disable_trigger_command:
+          config.trigger_mode === 'manual' || config.disabled_triggers?.[dataNodeId] || undefined,
+      },
+    ]
+    map[dataNodeId] = {
+      type: 'data-node',
+      properties: {},
+      in: { change: null },
+      out: { value: [{ id: scriptId, port: dataNodeId }] },
+    }
+  })
+
+  // Wire an output target data-node's `change` port back from a script out-port, preserving
+  // any `out.value` it already has (a node reused as both input and output — allowed in manual
+  // mode). Mirrors the last-wins reuse handling in generateCalulationMap's outputs section.
+  const wireOutputTarget = (dataNodeId: string, scriptPort: string) => {
+    const existing = map[dataNodeId]
+    map[dataNodeId] = {
+      type: 'data-node',
+      properties: {},
+      in: { change: [{ id: scriptId, port: scriptPort }] },
+      out: { value: existing?.out?.value ?? null },
+    }
+  }
+
+  if (config.error) {
+    scriptOut.error = [{ id: config.error, port: 'change' }]
+    wireOutputTarget(config.error, 'error')
+  }
+  if (config.output) {
+    scriptOut.output = [{ id: config.output, port: 'change' }]
+    wireOutputTarget(config.output, 'output')
+  }
+  // `out:`-prefixed port names keep `outputs` paths from colliding with the reserved
+  // `error` / `output` ports (a path could legitimately be the string "output").
+  Object.entries(config.outputs).forEach(([path, pbList]) => {
+    const portName = `out:${path}`
+    outputArgs[portName] = path
+    scriptOut[portName] = pbList.map((pb) => ({ id: pb, port: 'change' }))
+    pbList.forEach((pb) => wireOutputTarget(pb, portName))
+  })
+
+  map[scriptId] = {
+    type: 'command-node-script',
+    title: 'Command: SCRIPT_RUN',
+    properties: {
+      command: 'SCRIPT_RUN',
+      args: {
+        code: config.code,
+        enable_async: config.enable_async,
+        inputs: inputArgs,
+        outputs: outputArgs,
+      },
+    },
+    in: scriptIn,
+    out: scriptOut,
+  }
+
+  return map
+}
+
+// `calcId` (the owning script calc's stable id) seeds every derived command-node id, so an
+// unchanged calc recompiles to identical ids and editing one calc never shifts another's —
+// keeping the compiled config byte-stable for change detection. See makeSeededId in utils/id.
+export const generateCalulationMap = (config: ScriptConfig, calcId: string) => {
   validateConfig(config)
-  const sandboxId = makeId('property_bank_command', opts)
-  const sandboxErrorId = makeId('property_bank_command', opts)
-  const sandboxResultId = makeId('property_bank_command', opts)
+  const sandboxId = makeSeededId('property_bank_command', `${calcId}:sandbox-run`)
+  const sandboxErrorId = makeSeededId('property_bank_command', `${calcId}:sandbox-error`)
+  const sandboxResultId = makeSeededId('property_bank_command', `${calcId}:sandbox-result`)
 
   const inputs = Object.entries(config.inputs).reduce(
     (acc, [key, value], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:input:${key}`)
       acc.map[key] = {
         type: 'data-node',
         properties: {},
@@ -123,7 +245,7 @@ export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMod
   let y = 0
   const outputs = Object.entries(config.outputs).reduce(
     (acc, [key, pbList], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:output:${key}`)
       acc.commandIdList.push(commandId)
       acc.map[commandId] = {
         type: 'command-node-object',
@@ -195,6 +317,8 @@ export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMod
   )
 
   return {
+    // Newer runtimes prefer this single-node graph; older runtimes fall back to `map` below.
+    script_map: generateScriptMap(config, calcId),
     map: {
       ...inputs.map,
       [sandboxId]: {

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.6",
+  "version": "2.25.0-beta.60",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.25.0-beta.6",
+    "@babel/generator": "7.28.5",
+    "@babel/parser": "7.28.5",
+    "@babel/traverse": "7.28.5",
+    "@babel/types": "7.28.5",
+    "@fugood/bricks-cli": "^2.25.0-beta.60",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -25,5 +29,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "d8a3bbd695e9118cf725b7226866d804bbe56bbe"
+  "gitHead": "c0dd2ea071f45382808ad55acfc9837217d683ca"
 }

package/skills/bricks-ctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bricks-ctor
-description: Advanced BRICKS configuration knowledge. Covers Standby Transition, Automations (E2E testing), Data Calculation (JS sandbox libraries), Local Sync, Remote Data Bank, Media Flow, and Buttress (remote inference). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, or canvas transitions.
+description: Advanced BRICKS configuration knowledge. Covers Standby Transition, Automations (E2E testing), Data Calculation (JS sandbox libraries), Local Sync, Remote Data Bank, Media Flow, Buttress (remote inference), and the verification toolchain (compile, harness-specific preview tool, on-device DevTools, definition-of-done gate). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, canvas transitions, or verifying project work before declaring done.
 ---
 
 # BRICKS Ctor - Advanced Features
@@ -11,22 +11,28 @@ This skill covers advanced BRICKS features not in the main project instructions.
 
 | Rule | Description |
 |------|-------------|
-| [Architecture Patterns](rules/architecture-patterns.md) | **Read first** — decompose flows and select patterns |
-| [Animation](rules/animation.md) | Animation system for brick transforms and opacity |
-| [Standby Transition](rules/standby-transition.md) | Canvas enter/exit animations |
-| [Automations](rules/automations.md) | E2E testing and scheduled tasks |
-| [Data Calculation](rules/data-calculation.md) | JS sandbox libraries (25+ available) |
-| [Local Sync](rules/local-sync.md) | LAN device synchronization |
-| [Remote Data Bank](rules/remote-data-bank.md) | Cloud data sync and API access |
-| [Media Flow](rules/media-flow.md) | Media asset management |
-| [Buttress](rules/buttress.md) | Remote inference for AI generators |
+| [Architecture Patterns](references/architecture-patterns.md) | **Read first** — decompose flows and select patterns |
+| [Source-Editing Tools](references/source-editing-tools.md) | MCP tools for editing entries and data-calcs by AST (new/edit/remove, value grammar, verify) |
+| [Animation](references/animation.md) | Animation system for brick transforms and opacity |
+| [Standby Transition](references/standby-transition.md) | Canvas enter/exit animations |
+| [Automations](references/automations.md) | E2E testing and scheduled tasks |
+| [Data Calculation](references/data-calculation.md) | Wiring contract, trigger semantics, JS sandbox (25+ libraries) |
+| [Local Sync](references/local-sync.md) | LAN device synchronization |
+| [Remote Data Bank](references/remote-data-bank.md) | Cloud data sync and API access |
+| [Media Flow](references/media-flow.md) | Media asset management |
+| [Buttress](references/buttress.md) | Remote inference for AI generators |
+| [Verification Toolchain](references/verification-toolchain.md) | Definition of done, compile, preview tool selection, on-device DevTools, Path 1/2/3 decision rule |
+| [Simulator](references/simulator.md) | Path 1 fidelity — Simulator feature support, fallbacks (Camera/LLM/STT/Vector Store, Buttress disabled), when a green run is enough vs. Path 2 |
 
 ## Quick Reference
 
-- **Complex flows**: See [Architecture Patterns](rules/architecture-patterns.md) for decomposing multi-step workflows
-- **Multi-device**: See [Local Sync](rules/local-sync.md) for LAN coordination
-- **Cloud data**: See [Remote Data Bank](rules/remote-data-bank.md) for sync and API access
-- **Media assets**: See [Media Flow](rules/media-flow.md) for centralized asset management
-- **AI offloading**: See [Buttress](rules/buttress.md) for GPU server delegation
-- **E2E testing**: See [Automations](rules/automations.md) for test automation
-- **Enter animations**: See [Standby Transition](rules/standby-transition.md) for canvas transitions
+- **Complex flows**: See [Architecture Patterns](references/architecture-patterns.md) for decomposing multi-step workflows
+- **Editing entries/data-calcs**: See [Source-Editing Tools](references/source-editing-tools.md) — prefer the MCP editing tools over hand-editing `subspaces/**`
+- **Multi-device**: See [Local Sync](references/local-sync.md) for LAN coordination
+- **Cloud data**: See [Remote Data Bank](references/remote-data-bank.md) for sync and API access
+- **Media assets**: See [Media Flow](references/media-flow.md) for centralized asset management
+- **AI offloading**: See [Buttress](references/buttress.md) for GPU server delegation
+- **E2E testing**: See [Automations](references/automations.md) for test automation
+- **Enter animations**: See [Standby Transition](references/standby-transition.md) for canvas transitions
+- **Verification before done**: See [Verification Toolchain](references/verification-toolchain.md) for the definition-of-done gate and Path 1/2/3 decision rule
+- **Simulator fidelity**: See [Simulator](references/simulator.md) for what the Simulator fakes (Camera, AI generators, Buttress) and when to escalate to a real device

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

@@ -41,12 +41,13 @@ const bounce: AnimationDef = {
     toValue: 1,
     friction: 7,
     tension: 40,
-    speed: 12,
-    bounciness: 8,
   },
 }
 ```
 
+Use one spring parameter family per config: `tension/friction`, `speed/bounciness`, or
+`stiffness/damping/mass`.
+
 ### Decay Animation
 Velocity-based deceleration animation.
 

package/skills/bricks-ctor/{rules → references}/architecture-patterns.md

@@ -25,11 +25,20 @@ The primary way to orchestrate multi-step flows. A single event can contain an a
 - Use `waitAsync: true` to await async actions before the next step
 - Use `dataParams` + `mapping` to pass event data downstream
 - This is the "glue" that wires generators, state, and UI together
+- For Generator result UI: await Generator, write done/version Data; route/current Data stays identity.
+
+Sequential `PROPERTY_BANK` / `PROPERTY_BANK_EXPRESSION` actions in one chain read the data values that existed when the chain started. If a later action needs to read what an earlier action wrote, set `waitAsync: true` on the earlier action.
 
 ### System Actions (Priority 3)
 Built-in commands for direct state and UI changes.
 - **PROPERTY_BANK**: set data value
 - **PROPERTY_BANK_EXPRESSION**: inline JS expression for simple compute
+  - The expression engine folds statements into a single expression: only expression
+    statements, simple `const`/`let` declarations, and a final return/expression are
+    supported — **no `if`/`for`/`while`/`switch`** (use ternaries). The same limit
+    applies inside a zero-arg IIFE body. Unsupported statements fail at runtime with
+    the error visible only in a DevTools session, so prefer ternary chains or move the
+    logic to a DataCalculationScript.
 - **CHANGE_CANVAS**: navigate to another canvas
 - **DYNAMIC_ANIMATION**: trigger animation
 - **ALERT / MESSAGE**: system feedback
@@ -67,3 +76,13 @@ Only actual data derivation maps to Data Calculation:
 
 ### Step 4: Wire with Event Action Chains
 Connect the pieces through events on generators and bricks.
+
+## Recipe: user-driven state machine (calculator, form wizard, picker)
+
+A brief like "state vars X, Y, Z; button A updates X from X+Y; button B resets" is a state machine. The shape:
+
+- Each state variable is its own `Data` entity. Displays read it via `linkData(() => data.dFoo)`.
+- Each button's `onPress` is an Event Action Chain. For every state var that changes, append one `PROPERTY_BANK_EXPRESSION` whose `expression` reads the current state and returns the new value.
+- Use `Data Calculation` only for reusable pure derivations referenced as inputs to those expressions.
+
+A 10-button calculator with 4 state vars is ~10 small chains of 1–4 inline expressions. If you find yourself writing a single auto-mode `DataCalculationScript` that consumes all state vars and emits all-new state through mirror `dFooResult` data — or pinging a `dLastInput` field to force an auto calc to re-run — the chain shape was the right answer.

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

@@ -118,6 +118,16 @@ const testLoginFlow: AutomationTest = {
 | `match_screenshot`           | `[name, threshold?, maxRetry?]`                  | Screenshot compare   |
 | `delay`                      | `[subspace?, property?, defaultValue?]`          | Delay execution      |
 
+In project TypeScript source, pass entity getters for BRICKS entities:
+
+```typescript
+run: ['brick_press', () => mainSubspace, () => bricks.bSubmitButton]
+run: ['wait_until_canvas_change', () => mainSubspace, () => canvases.cDone, 5000]
+run: ['assert_property', () => mainSubspace, () => data.dStep, 'done']
+```
+
+The compiler resolves these getters to the current generated IDs.
+
 ### execute_action Params
 
 The `params` object in `execute_action` uses **runtime event property keys** from `event-props.ts`, NOT the action config `input` names from type definitions.
@@ -208,6 +218,7 @@ Automations work with Modules. Use Manual Run in Preview mode for module testing
 
 - **Automation map key**: Always use `'AUTOMATION_MAP_DEFAULT'` as the automation map ID (not `makeId()`). The preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
 - **Valid makeId types**: Use `'test'` for AutomationTest, `'test_case'` for TestCase, `'test_var'` for TestVariable. Do NOT use `'automation_test'` or `'automation_test_map'`.
+- **Entity references in run arrays**: Use getter references (`() => subspace`, `() => bricks.bButton`, `() => data.dValue`) in TypeScript source so compile resolves fresh IDs.
 - **handler in execute_action**: Pass the entity's `.id` string (e.g., `bricks.bInput.id`), not a getter function.
 
 ## Best Practices

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