@filsilva/helios-cli 0.10.0

package/skills/helios-cli/references/networks.md

@@ -0,0 +1,53 @@
+# Networks
+
+The CLI works with Helios portable network formats:
+
+- `.bxnet`
+- `.zxnet`
+- `.xnet`
+
+The daemon infers format from file extension when `format` is omitted.
+
+## Start With A File
+
+```sh
+helios session start --renderer webgpu --network ./graph.bxnet
+```
+
+## Load Or Replace In A Running Session
+
+```sh
+helios call "$SESSION" network.load --json '{"path":"./graph.xnet"}'
+```
+
+or:
+
+```sh
+helios call "$SESSION" network.replace --json '{"path":"./graph.bxnet","options":{"keepCamera":false}}'
+```
+
+## Synthetic Network
+
+Synthetic networks are useful for smoke tests when no dataset is available:
+
+```sh
+helios call "$SESSION" network.replace --json '{
+  "synthetic": {
+    "nodeCount": 1000,
+    "mode": "2d",
+    "layout": "gpu-force"
+  }
+}'
+```
+
+## Save
+
+```sh
+helios call "$SESSION" network.save --json '{"format":"bxnet","outputPath":"./out.bxnet"}'
+```
+
+When `outputPath` is omitted, the response contains a base64 payload.
+
+## WASM Buffer Rule
+
+When writing code that creates Helios networks before loading them into the CLI, allocate first and take WASM-backed typed-array views second. Use `withBufferAccess(...)` for direct buffer writes so allocation-prone calls cannot silently invalidate views.

package/skills/helios-cli/references/persistence.md

@@ -0,0 +1,136 @@
+# Persistence
+
+Helios CLI sessions persist sparse overrides and a readable change journal through `helios.states` and `helios.storage`. The CLI daemon owns durable storage; browser localStorage and IndexedDB are not used for CLI session persistence. The CLI mirrors sparse runtime state for agents:
+
+```text
+~/.helios/runtime/session-state/<sessionId>.json
+```
+
+Durable session records live under `~/.helios/sessions`. Session envelopes are JSON, network side records are saved as `.zxnet`/`.bxnet`/`.xnet`, and position side records are saved as binary files. Use `--storage-dir <path>` or `HELIOS_CLI_STORAGE_DIR` for another root.
+
+The persistence id is the raw CLI session id:
+
+```text
+<sessionId>
+```
+
+## Automatic Saves And Journaling
+
+State writes are recorded with `source: "cli"` before the response is returned. Manual UI changes are recorded with `source: "ui"` when the underlying Helios behavior emits a durable state change.
+
+Runtime events also schedule lightweight saves:
+
+- behavior, mode, filter, camera, mapper, and layout changes schedule sparse override snapshots
+- page unload attempts a final lightweight storage flush
+
+Read changes since the last agent checkpoint:
+
+```sh
+helios call <sessionId> persistence.changes
+```
+
+Read all recent CLI-origin changes:
+
+```sh
+helios call <sessionId> persistence.changes --json '{"source":"cli","sinceCheckpoint":false,"limit":25}'
+```
+
+Mark the current journal position as seen by the agent:
+
+```sh
+helios call <sessionId> persistence.checkpoint
+```
+
+Inspect sparse overrides and dirty state:
+
+```sh
+helios state get <sessionId>
+helios state set <sessionId> appearance.shaded.enabled true
+helios state reset <sessionId> appearance.shaded.enabled
+helios call <sessionId> persistence.overrides
+helios call <sessionId> persistence.status
+helios session state <sessionId>
+```
+
+Reset a single override or a section:
+
+```sh
+helios call <sessionId> persistence.reset --json '{"path":"appearance.nodeStyle.sizeScale"}'
+helios call <sessionId> persistence.reset --json '{"scope":"appearance.nodeStyle"}'
+```
+
+## Manual Save
+
+Use `persistence.save` before reloads, screenshots, handoff points, or multi-step workflows where recovering exactly the current state matters:
+
+```sh
+helios call <sessionId> persistence.save --json '{"fullSession":true}'
+```
+
+`fullSession: true` writes the network plus sparse visualization state through CLI filesystem storage. `fullSession: false` writes only sparse overrides. To force `helios.storage` to flush pending state and optionally save the network blob:
+
+```sh
+helios call <sessionId> persistence.flush --json '{"includeNetwork":true}'
+```
+
+## Reload Recovery
+
+In a managed headed or headless browser session, reload the page and wait for the bridge to reconnect:
+
+```sh
+helios call <sessionId> browser.reload
+helios call <sessionId> scene.getState
+```
+
+On page load, Web Next restores the active CLI session through the remote storage client backed by the daemon filesystem store. Reload recovery does not depend on browser storage.
+
+## Explicit Restore And Clear
+
+Restore the current checkpoint without reloading:
+
+```sh
+helios call <sessionId> persistence.restore
+```
+
+Clear the saved CLI session:
+
+```sh
+helios call <sessionId> persistence.clear
+```
+
+Inspect the persistence id and storage status:
+
+```sh
+helios call <sessionId> persistence.get
+```
+
+## Daemon Storage API
+
+Managed and server sessions expose the remote storage API used by the browser client:
+
+```text
+GET    /api/storage/sessions
+POST   /api/storage/session
+GET    /api/storage/session/<id>
+DELETE /api/storage/session/<id>
+GET    /api/storage/unfinished?workspaceId=<workspaceId>
+PUT    /api/storage/unfinished
+```
+
+The API is loopback-only with the session daemon and writes into the active storage root. It stores normal session envelopes under `sessions/records`, network side records under `sessions/networks`, and position side records under `sessions/positions`.
+
+Use server mode plus `--storage-dir` for fast persistence API checks that do not need a browser bridge:
+
+```sh
+helios --storage-dir /tmp/helios-store session start --mode server
+```
+
+## What Persists
+
+Sparse overrides cover changed values only, using stable paths such as `appearance.nodeStyle.sizeScale`, `appearance.shaded.enabled`, `layout.parameters.outputScale`, and `mappers.node.channels.color`. Full checkpoints additionally cover the network data, mode, camera, layout and behavior state, mapper descriptors, filters, density, labels, legends, and other Helios Web visualization state exposed by `serializeVisualizationState`.
+
+Layout runtime is persisted separately from sparse overrides. It captures current positions from the active source, including delegate-backed and GPU-force layouts, plus layout type, run state, temperature/alpha, center, and encoded positions. Restore writes positions back to the active delegate when possible and mirrors them to the hidden network position attribute so interpolation, renderer buffers, and saved files agree.
+
+When saving a network with visualization state, Helios stores sparse config and layout runtime in the graph-private `_helios_visualization_state` attribute and mirrors current positions in the node-private `_helios_visuals_position` attribute. The private convention is the leading underscore.
+
+For function-backed mappers and custom code descriptors, persist the descriptor source that created them. A browser reload can restore function-like mapper descriptors that are serializable, but external closures or runtime-only JavaScript objects cannot be reconstructed from storage.

package/skills/helios-cli/references/positions.md

@@ -0,0 +1,63 @@
+# Positions
+
+Inspect the active position source:
+
+```sh
+helios call "$SESSION" positions.get
+```
+
+Snapshot positions. Delegate-backed GPU layouts are read back when possible:
+
+```sh
+helios call "$SESSION" positions.snapshot --json '{"limit":10}'
+```
+
+## Set Custom Positions
+
+Write explicit 3D positions into `_helios_visuals_position` and apply them:
+
+```sh
+helios call "$SESSION" positions.set --json '{
+  "values": [[0, 0, 0], [10, 5, 0], [20, 10, 0]],
+  "dimension": 3,
+  "stopLayout": true
+}'
+```
+
+For large arrays, use a flat array and set `dimension`:
+
+```sh
+helios call "$SESSION" positions.set --json '{
+  "values": [0, 0, 0, 10, 5, 0, 20, 10, 0],
+  "dimension": 3,
+  "indexBy": "auto"
+}'
+```
+
+## Build Positions From Code
+
+Create a position attribute using a JS-like callback, then apply it:
+
+```sh
+helios call "$SESSION" network.attributeSet --json '{
+  "scope": "node",
+  "name": "agent_position",
+  "functionCode": "return [ordinal * 2, Math.sin(ordinal / 10) * 50, 0];",
+  "options": { "type": "float", "dimension": 3 }
+}'
+
+helios call "$SESSION" positions.fromAttribute --json '{
+  "attribute": "agent_position",
+  "stopLayout": true
+}'
+```
+
+## Positions From Existing Attributes
+
+Any numeric 2D or 3D node attribute can seed layout positions:
+
+```sh
+helios call "$SESSION" positions.fromAttribute --json '{"attribute":"umap_position"}'
+```
+
+Use `layout.start` after applying an attribute when the layout should continue from the custom seed.

package/skills/helios-cli/references/rendering-export.md

@@ -0,0 +1,56 @@
+# Rendering And Export
+
+## Session Modes
+
+- `--mode headless`: managed bundled Chromium, suitable for automated tests and exports.
+- default / `--mode server --open`: serves the client and opens the OS/default browser, suitable for interactive visual inspection.
+- `--mode server --no-open`: serves the client and control socket without launching or opening a browser.
+- `--mode headed`: managed visible bundled Chromium, intended only for Playwright-managed debugging.
+
+Plain `helios session start` uses the platform browser opener instead of Playwright's bundled "Chrome for Testing". Managed browser sessions use Playwright's bundled Chromium by default. Add `--browser-channel chrome` only when you explicitly need an installed Chrome channel. UI-triggered downloads from managed sessions are copied to `~/Downloads` using the suggested filename.
+
+Initialize the default managed browser once with:
+
+```sh
+helios browser install
+```
+
+This installs bundled Chromium. On Linux, use `helios browser install --with-deps` if system browser dependencies are missing.
+
+## Renderer
+
+Use:
+
+```sh
+helios session start --mode headless --renderer webgpu
+```
+
+Renderer options:
+
+- `webgpu`: require hardware WebGPU, except headless sessions may fall back to hardware WebGL2 when WebGPU is unavailable.
+- `webgl`: require hardware WebGL2.
+- `auto`: accept the initialized hardware backend.
+
+By default, software-only rendering is rejected. Use `--no-gpu` only when explicitly acceptable for the task.
+
+## Figure Export
+
+```sh
+helios call "$SESSION" export.figure --json '{
+  "format": "png",
+  "preset": "window",
+  "outputPath": "./figure.png"
+}'
+```
+
+Call `scene.getState` first to confirm renderer, camera, layout, filters, density, labels, legends, and mappers before exporting.
+
+## Events
+
+Stream events while another process manipulates a session:
+
+```sh
+helios events "$SESSION"
+```
+
+Useful event types include `browser.console`, `browser.pageerror`, `browser.gpu`, `helios.layoutStart`, `helios.layoutStop`, `helios.cameraMove`, and `helios.networkReplaced`.

package/skills/helios-cli/references/rpc-methods.md

@@ -0,0 +1,83 @@
+# RPC Methods
+
+Call methods with:
+
+```sh
+helios call <sessionId> <method> --json '<payload>'
+```
+
+Omit `--json` when the method takes no payload.
+
+## Scene
+
+- `scene.getState`: returns mode, renderer, network stats, camera, labels, legends, density, filter, layout, and mapper snapshots.
+- `scene.requestRender`: requests a render and returns scene state.
+- `scene.setMode`: payload `{ "mode": "2d" }` or `{ "mode": "3d" }`.
+
+## Network
+
+- `network.stats`: returns node count, edge count, node attributes, and edge attributes.
+- `network.load`: daemon-side file load. Payload `{ "path": "./graph.bxnet", "format": "bxnet" }`.
+- `network.attributeSet`: writes node, edge, or network attributes. Supports scalar values, arrays, and `functionCode`.
+- `network.replace`: accepts either a file payload like `network.load` or a synthetic descriptor:
+
+```json
+{
+  "synthetic": {
+    "nodeCount": 500,
+    "mode": "2d",
+    "layout": "gpu-force"
+  }
+}
+```
+
+- `network.save`: payload `{ "format": "bxnet", "outputPath": "./out.bxnet" }`.
+
+## Camera
+
+- `camera.getPose`: returns the current camera pose.
+- `camera.setPose`: payload `{ "pose": { ... }, "options": { ... } }`.
+- `camera.transition`: payload `{ "pose": { ... }, "options": { "durationMs": 750 } }`.
+- `camera.frame`: payload can include `{ "animate": true, "durationMs": 500, "resetOrientation": true }`.
+- `camera.controls`: reads controls with `{}` or patches controls, for example `{ "orbit": false, "autoFit": true }`.
+- `camera.targetNodes`: get or set target nodes with `{ "nodeIndices": [1, 2, 3], "options": { "follow": true } }`.
+
+## Layout
+
+- `layout.get`: returns current layout key, run state, and parameter descriptor.
+- `layout.set`: payload `{ "layout": "gpu-force" }`, `{ "layout": "static" }`, `{ "layout": "d3force3d" }`, `{ "layout": "worker:jitter" }`, or `{ "layout": "worker:force3d" }`.
+- `layout.setParameters`: patches writable parameters exposed by `layout.get`, for example `{ "outputScale": 7, "linkDistance": 1.2 }`.
+- `layout.applyPositionAttribute`: copies a numeric 2D/3D node attribute into current layout positions.
+- `layout.start`: starts layout execution.
+- `layout.stop`: payload `{ "reason": "agent" }`.
+
+## Visual State
+
+- `mappers.get`, `mappers.set`, `mappers.reset`
+- `behaviors.get`, `behaviors.use`, `behaviors.update`, `behaviors.setEnabled`, `behaviors.detach`, `behaviors.restore`, `behaviors.call`
+- `positions.get`, `positions.snapshot`, `positions.set`, `positions.fromAttribute`
+- `filters.get`, `filters.set`, `filters.clear`
+- `labels.get`, `labels.set`
+- `legends.get`, `legends.set`
+- `density.get`, `density.set`
+- `metrics.measure`, `aesthetic.measure`: run graph/aesthetic measurements such as degree, strength, clustering, coreness, centralities, connected components, dimension, and Leiden.
+
+## Persistence
+
+- `state.get`, `state.set`, `state.reset`: read, write, or reset Web Next tracked state paths through `helios.states` with CLI-origin writes.
+- `persistence.get`: returns the CLI persistence id, storage status, and availability.
+- `persistence.save`: payload can include `{ "fullSession": true, "networkFormat": "bxnet", "captureThumbnail": true }`. Full saves persist network data plus sparse visualization state and capture a PNG thumbnail by default; lightweight saves persist sparse overrides only and use throttled automatic thumbnail capture.
+- `persistence.restore`: restores the current session checkpoint without reloading the page.
+- `persistence.clear`: removes the CLI filesystem session checkpoint.
+- `persistence.changes`: returns journal entries since the last checkpoint by default. Payload can include `{ "since": 12, "limit": 25, "source": "user", "sinceCheckpoint": false }`.
+- `persistence.checkpoint`: marks changes through a sequence id as seen. Omit `seq` to checkpoint through the latest entry.
+- `persistence.overrides`: returns sparse overrides and dirty state.
+- `persistence.reset`: payload `{ "path": "appearance.nodeStyle.sizeScale" }` or `{ "scope": "appearance.nodeStyle" }`.
+- `persistence.flush`: payload `{ "includeNetwork": true, "captureThumbnail": "auto" }` writes pending overrides and optionally network data if size limits allow. Use `captureThumbnail: false` to preserve the existing thumbnail or provide a `thumbnail` object with a `dataUrl`.
+- `persistence.status`: returns session id, override counts, journal counts, dirty state, and network persistence status.
+- `browser.reload`: reloads the managed browser page, waits for the Helios runtime and bridge to reconnect, then returns runtime and session metadata.
+
+## Picking And Export
+
+- `picking.pick`: payload `{ "x": 400, "y": 300 }`.
+- `export.figure`: payload `{ "format": "png", "preset": "window", "outputPath": "./figure.png" }`.