Qubit Field 1.2.5 Documentation

Download and Links

Windows Setup

Run the Windows installer to download Qubit Field, install dependencies, create the app environment, and add the desktop shortcut.

Download Qubit Field Installer

Source Repository

Open the repository for source access, issue tracking, release notes, and partner evaluation.

github.com/QuantalityFX/QubitMCP

Manual

Continue below for setup, workflows, viewport controls, node coverage, pipelines, and troubleshooting.

Read the manual

Overview

What Qubit Field does: connect nodes, process text and AI workflows, assemble 3D scenes, drive automation, process mocap, generate grooming assets, and export results from a single graph.

Node graph editor with links, grouping, and per node info cards.
3D viewport with camera controls, grid, wireframe, and gizmos.
AI stack with Local Server, LLM Prompt, Chatbot, Voice Actor, Audio Capture, Mediator, Database, Librarian, and Qubit Deck control.
3D stack with import, FBX ingest, mocap ingest, Gen-X video mocap, retargeting, primitives, curves, modeler selection, lighting, texturing, masks, normals, transforms, scene assembly, render, post-process, and export nodes.
Character and hair stack with groom guides, guide deformation, guide pose/simulation, guide tubes, skinned volume collision meshes, and skinned splat render proxies.
Automation stack with Keyboard Sequence actions, Serial COM/Pico HID support, and voice-driven Qubit Deck commands.
Configurable hotkeys saved in hotkeys.json.

Latest Updates

Data Nexus Sales Prep Loop

skills, data_nexus, mediator_agent, and task now support a guided Sales Agent preparation workflow.
Task Run Step checks the approved Skills template and connected Data Nexus facts; with task.mediator connected, Sales Agent AI semantically reviews the newest points, open questions, and slide readiness.
If a manually added point already answers an open prep question, Task can link that existing point back to the question with answers_question instead of asking again.
Task Write Questions uses the Mediator Sales Agent LLM when connected, creates genuinely new prep_question points only when needed, updates changed questions, and removes stale Task-owned questions.
Question references are stored as source_point_ids metadata and can be shown or hidden with short Needs? and Refine? toggles.
Data Nexus now distinguishes normal points, yellow refinement questions, orange needs-answer questions, and neon-green slide points with different dot sizes and matching connection gradients.
Newly added points receive a white review ring that stays through arrange/cluster operations and clears only when newer points are added.

Task to HTML Deck Output

task owns the Sales Agent step loop: readiness, Mediator AI review, question writing, draft generation, manual status, approve, and dismiss state.
Generate Draft asks the Mediator Sales Agent LLM for slide copy, allows a conservative draft even when some slides need validation, and writes a versioned HTML deck under Skills/generated_decks/.
Refresh HTML rebuilds the current generated deck with the latest style without rewriting the slide copy.
Index Slides reads the generated deck and creates or updates neon-green slide points in a Slides folder.
Indexed slide points are linked in slide order with next_slide and connected back to their supporting Data Nexus points with uses_source.
Generated deck folders now include index.html, styles.css, and manifest.json.
Connected html_preview.path inputs refresh to the generated index.html after draft generation.
HTML Preview can export the deck to PDF with the cover and each slide paged separately for review or sharing.

Skills Library Review

skills scans human templates, agent templates, task guides, and agent guides from the local Skills/ library.
The browser marks latest, active approved, older, draft, deprecated, and warning states for template families.
Validation now checks required metadata, slide/slot counts, and local package references such as source templates and conversion reports.
Review Diff compares the selected agent template or task guide against the active approved or latest comparable version.
Generate Deck can still generate directly from an approved Sales Agent template when a Data Nexus node is connected.

Voice Actor Send Modes

voice_actor now supports Auto Respond, Ask First, and Manual response modes per node.
Auto Respond sends after speech pauses, Ask First confirms before sending, and Manual sends only when Stop is pressed.
Voice Actor can read chatbot output or Mediator output, including Mediator output passed through a Python cleanup node.

Mediator Agent Integration

mediator_agent replaces the older legacy node kind while preserving aliases for existing workflows.
Mediator only processes on fresh Voice Actor send events, avoiding accidental reruns when a node is selected, moved, loaded, or reconnected.
Chatbot can now read a connected Mediator as an agent layer while still using llm_prompt for DeepSeek/Ollama conversation.
When the Chatbot model emits a controlled tool request, the raw control tag is handed to Mediator for Tanya/Security Guard popups and Codex-backed execution.
The Qubit Deck controller profile can append <user_feedback>...</user_feedback> text for spoken status updates.
A Python-node helper can extract only the feedback tag when the full Mediator JSON should not be spoken aloud.
Mediator prompt logs are capped and console logs are kept to a managed tail so log files do not grow without limit.

Chatbot Tool Handoff

chatbot now has a mediator_input pin for agent profiles and controlled tool requests.
voice_actor connected to Chatbot owns spoken chat output; Mediator stays silent on Chatbot-origin execution results.
codex_sandbox is available as a future execution-policy node for Mediator sandbox settings.

Qubit Deck Controller

qubit_deck_controller can list deck context or execute button actions from structured Mediator JSON.
Executor mode supports invoke, highlight on/off, list buttons, health ping, and debugger launch actions.
The new visible input is mediator_input; older medigator_input workflows still load.

Mocap Retargeting System

fbx_import, mocap_import, and anim_retarget support a source/target retargeting workflow.
FBX import validates rest geometry, capture pose, and animated pose roles.
Mocap import validates BVH sources and reports skeleton/clip summaries.
Anim Retarget connects a mocap or FBX animation source to a target FBX rig with joint mapping and preview controls.

Render, Post Process, and MP4 Export

post_process applies image-sequence effects such as ordered dithering to render or video frame sequences.
sequence_to_mp4 converts image sequences to MP4 through ffmpeg with codec, FPS, and bitrate controls.
video_player and render can be used with these nodes for review and delivery pipelines.

Keyboard Auto Runner

keyboard_sequence builds timed keyboard action sequences from the graph.
Actions include configurable lead-in, per-key hold time, action delay, and injection mode.
Use it for repeatable app-control steps after Qubit Field brings the target app into focus.

Gantt Multi-Note Groups

Gantt now supports multiple connected note sources at once.
Each note node becomes a collapsible group using the note node name as the group header.
Group expand or collapse state is saved and restored with the workflow.
Gantt can consume an append node input and preserve append order as group order.

Gantt Copy/Paste Scheduling

Copy captures task names, completion percentages, and assigned day ranges.
Copy writes a CSV transfer log in gantt_chart/transfer_logs.
Paste maps by task name and applies schedule/progress to matching tasks on another Gantt node.
Transfer works even when the destination chart has additional note groups connected.

Gen-X Video Mocap

genx_video_mocap runs the GEM-X/GEN-X video mocap pipeline from a video file.
Rig export targets include SOMA BVH and Unitree G1 output options.
Successful runs can create a connected mocap_import node from the generated BVH.

Modeling and Instancing Helpers

modeler adds an outliner for object, point, edge, and face selection groups.
curve generates line, circle, and spiral scene assets.
copy_to_points instances copy geometry onto point inputs with optional material or texture propagation.

Grooming Pipeline

mask paints mesh masks used to seed groom_guides.
groom_deform, groom_guide_pose, and groom_guide_sim bind, pose, and simulate guide curves.
groom_guide_tube converts guide curves into tube geometry with radius, caps, smoothing, and profile controls.

Skinned Mesh and Splat Proxies

skinned_volume_mesh builds voxel-derived collision meshes from rigged FBX or retargeted character data.
skinned_splat_proxy creates skinned splat render proxies from FBX, retarget, or guide tube sources.
Generated proxy manifests and caches are stored beside the workflow or in the configured output folder.

Image-GS Splat Node

image_gs_splat converts a local image path or HTTP image URL into a viewport-ready Gaussian splat PLY.
Exact Pixel mode writes a deterministic front-facing splat sheet with one splat per visible pixel for filled single-image coverage.
Image-GS mode keeps the optional optimizer runtime, Auto HQ progressive optimization, QC reporting, node preview, debug report capture, setup controls, and a bottom Stop button while processing.

Serial and Pico HID Control

serial_com stores COM port, baud rate, and timeout settings for downstream automation.
Keyboard automation can use connected Pico serial sessions for key taps, key-down/release, and mouse commands.
The node can prompt for pyserial when the runtime dependency is missing.

Audio Capture Sources

audio_capture captures output-device, input-device, or application audio.
Controls include backend selection, sample rate, threshold, silence window, and phrase duration.
Use it to feed speech/audio workflows that need captured system or microphone audio.

Quick Start

Run the Windows installer, or run setup once with .\setup.bat from a source checkout.
Launch with .\Run_QubitMCP.bat or run echograph_app.py from the project venv.
Create nodes with Create - Node or press Tab.
Connect outputs to inputs by dragging from one port to another.
Select a node to edit parameters in the info panel and run its actions.

Setup and Launch

Run from repository root: V:\Source\Repos\QubitMCP.

One time setup

setup.bat

Creates or repairs .venv for the app.
Creates or repairs nodes\librarian\.venv for librarian service dependencies.
Installs requirements.txt and nodes\librarian\requirements.txt.
Upgrades packaging tools in each venv (pip, setuptools, wheel).
Checks bundled ffmpeg support used by sequence_to_mp4.
Installs voice dependencies used by voice_actor, including local Whisper and TTS support when available.
Installs or checks audio capture dependencies used by audio_capture.
Runs a keyboard_sequence sanity check so Keyboard Auto Runner can load its runtime.
Checks Serial COM dependencies used by Pico/COM automation paths.
Checks Mediator runtime support for tools\codex.ps1, Node.js, and npx.
Checks or prompts for Autodesk FBX SDK runtime files used by full FBX import and retargeting workflows.
Downloads and prepares the optional Image-GS runtime under %QUBITMCP_HOME%\third_party\image-gs for image-to-splat workflows, including the Image-GS Python dependencies, fused-ssim, and bundled gsplat package.

Optional Gen-X video mocap setup

Mocap\setup.bat

Use the Mocap setup when genx_video_mocap needs the GEM-X runtime and its dedicated environment.

Optional Image-GS setup

nodes\image_gs\setup_image_gs.bat

The main setup calls this automatically. It clones https://github.com/NYU-ICL/image-gs.git into the writable app home, creates a separate Image-GS environment, and installs the runtime used by image_gs_splat; set QUBITMCP_SKIP_IMAGE_GS=1 before setup to skip it.

Optional FBX SDK setup

setup.bat full "C:\path\to\fbx_runtime"

FBX runtime source folders can contain either fbx-*.whl plus FbxCommon.py, or fbx*.pyd plus FbxCommon.py and optional libfbxsdk.dll.

Launch app

Run_QubitMCP.bat

or

.\.venv\Scripts\python.exe .\echograph_app.py

Optional venv activation

.\.venv\Scripts\Activate.ps1

Activation is optional because scripts call the venv python directly.

UI Tour

Top Bar

File: New, Open, Open Recent, New Project, Save, Save As.
Edit: Preferences for ModernGL gizmo tip overlays and tip scale.
Create: open the node creation dialog.
Panels: Timeline, Audio, Profiler, Shelf, and Save Layout.
Settings: viewport, lighting, shadow, audio, layout, and debug tuning.
Hotkeys, Help, Frame, Debug, and the active 2D / Split / 3D view mode button.

Main Areas

Graph Canvas: nodes, wires, and comment frames.
3D Viewport: asset preview and scene assembly.
Info Panel: parameters, buttons, previews, and node tools.

Top Bar Menus

File

New: launch a fresh Qubit Field window.
Open: load a workflow JSON file.
Open Recent: choose from recent workflow files.
New Project: create a project folder for the next workflow save.
Save and Save As: write the current graph to the current or a new JSON file.

Edit and Create

Edit -> Preferences -> MGL Guizmo Tips: show or hide the stable ModernGL gizmo tips overlay.
Tips Size: scales the ModernGL gizmo tips and scale cubes.
Create -> Node: open Create Node with kind and parameter entry.

Panels

Timeline: show or hide the animation timeline in the viewport area.
Audio: show or hide the audio waveform panel above the timeline.
Profiler: show or hide the profiler panel above the 2D graph.
Shelf: show or hide the tool shelf row below the top bar.
Save Layout: store current view mode and panel visibility as the app default layout.

Utilities

Settings: opens the full settings panel documented below.
Hotkeys: edit keyboard and mouse bindings stored in hotkeys.json.
Help: opens this documentation page from Doc\index.html.
Frame: fits the graph view to all nodes.
Debug: opens debug path location, toggles EchoGraph logging, and toggles viewport debug.
View Mode: cycles 2D View -> 2D / 3D -> 3D View.

Top Shelf

The shelf is the row directly below the top bar and can be shown or hidden from Panels -> Shelf.
Use the Add shelf tool button to add Python Script, Python Code, Current Workflow, Selected Nodes, or Copied Nodes.
Shelf tools can run code, open saved workflows, or paste graph snippets depending on tool type.
Right-click a shelf item for Run/Open/Paste, Edit, Duplicate, Move Left, Move Right, and Remove.
Drag shelf items to reorder them; shelf configuration is stored in shelf_tools.json.
Missing tool paths are shown with warning styling so broken script/workflow shortcuts can be repaired from Edit.

Workflows

Workflows are saved as JSON.
Open Recent provides quick access to recently edited workflow files.
Save preserves graph layout, parameters, links, and related state.
Hotkey overrides are stored in project root hotkeys.json.

Graph Basics

Mouse Controls

Left click: select nodes and start links.
Middle drag: pan graph.
Right drag: zoom graph.
Alt + Left click on a wire: remove wire.

Editing

Use Tab to open Create Node.
Copy and paste with standard shortcuts.
Use comment groups to organize complex graphs.

3D Viewport

Used by Import, Scene, and scene related processing nodes.
Supports camera frame, reset, fly mode, and focus workflows.
Displays mesh and splat assets through the active graph path.
Scene workflows support per asset transforms and visibility states.

Gizmos and Transforms

Translate (T), Rotate (R), Scale (E).
Applies to selected items in the viewport and scene workflows.
Transform data participates in scene assembly and export chains.

Viewport Controls

Left viewport toolbar includes quick icons for Frame, Snapshot, Gizmo Space (World/Local), mesh selection tools, Grid, Zoom Mode, transform tools, Camera Orbit, Fly Mode, and Stats with Copy Stats.
Transform tools (Translate/Rotate/Scale) are available in viewport workflows and map to T, R, and E.
Grid toggle provides orientation and scale reference.
Wireframe toggle, default hotkey H.
Gizmo visibility toggle for clean previews.
Snapshot capture tools for scene reviews.
Stats overlay toggle in the 3D viewport side controls shows FPS and render/debug details, with a copy-stats action for quick reporting.
Viewport lighting is controlled from the top bar Settings panel: Shadow Quality, Cast Shadows, Self Shadows, Ambient Light, Work Light, Unlit View, and 2-Sided Shadows.

Viewport Left Panel

The left panel is a fast-access icon strip for camera/view actions and viewport toggles.
Object, Point, Edge, and Face selection modes are mutually toggled selection tools for mesh inspection and modeler workflows.
Box Select enables rectangular element selection; right-click it for front/back face selection policy.
Point Numbers overlays point IDs for debugging selections, groom bindings, and point-based workflows.
Zoom toggle uses GizmoZoom_On_Icon.png / GizmoZoom_Off_Icon.png for Infinite vs Legacy zoom mode.

Frame Selection

Snapshot

Gizmo Space World/Local

Object Select

Point Select

Edge Select

Face Select

Box Select + Face Policy Menu

Point Numbers

Grid Toggle

Zoom Mode Toggle

Translate / Rotate / Scale Tools

Camera Orbit Lock/Free

Fly Mode Toggle

Stats Overlay

Copy Stats

Animation Timeline

Open from top bar Panels -> Timeline.
If you enable timeline while in 2D mode, Qubit Field auto-switches to Split view.
Keyframing channels include Px, Py, Pz, Rx, Ry, and Rz.
Use ply_sequence for frame-by-frame PLY playback workflows that sync well with timeline scrubbing.
Use mocap_import, fbx_import, and anim_retarget for skeleton/animation retargeting workflows before scene preview or render.
Timeline sessions are context-aware and load per active scene (and selected scene owner when applicable).
Use [ and ] controls for start/end range and the loop control for playback looping.

Play/Pause

Set Key

Delete Selected Keys

Curves Mode

Straight Handles

Tied Handles

Untied Handles

Material Live Mode

FX Instances Toggle

Audio Panel

Open from top bar Panels -> Audio (enabling Audio also enables Timeline).
Audio panel appears above the timeline with Load Audio, Clear, and mute controls.
Supported picker filter includes common formats like wav, mp3, ogg, flac, aac, and m4a.
Waveform playhead syncs to timeline frame and FPS during playback and scrubbing.
Audio file path + mute state are persisted per scene context in project-side timeline config files.

Load Audio

Clear Audio

Sound On

Sound Off

Profiler Panel

Open from top bar Panels -> Profiler; the panel appears above the 2D graph.
Start begins a profiler capture and turns into the stop control while recording.
Clear removes the last profiler capture from the panel.
Export writes the latest capture under logs\Profiler.
Processes tab shows process/span timing with calls, total milliseconds, average milliseconds, and max milliseconds.
Python tab shows Python function calls, cumulative time, and self time.
The bottom resize handle lets you adjust the profiler height while keeping the graph usable.

Panel Layout Presets

Use top bar Panels menu for quick panel visibility controls: Timeline, Audio, Profiler, Shelf, and Save Layout.
Save Layout stores current panel visibility as the app-global default layout preset.
Settings menu includes Auto Save Layout to automatically persist panel visibility changes.
Global layout state is persisted in app_settings.json.
Workflow files also store panel visibility under settings.panel_layout and restore it on load.

Animation session files: timeline keys/range/audio settings are stored under <workflow folder>\projects\, for example <scene>_timeline.json, <scene>_timeline_range.json, and <scene>_audio.json.

Hotkeys (Default)

All bindings are editable in the Hotkeys dialog and persisted to hotkeys.json.

Action	Key
Save	Ctrl+S
Undo / Redo	Ctrl+Z / Ctrl+Y
Copy / Paste Node	Ctrl+C / Ctrl+V
Delete Node	Del
Create Node Menu	Tab
Comment Group	C
Open Big Editor	Ctrl+B
View Selected Node (Import/Scene)	V
Frame View	F
Reset 3D View	Shift+R
Gizmo Translate / Rotate / Scale	T / R / E
Wireframe Toggle	H
Grid Toggle	G
Timeline Play / Pause	Space
Timeline Set Key	K
View Mode 2D / Split / 3D	1 / 2 / 3
Add Wire Pin	Ctrl+LeftClick
Remove Wire	Alt+LeftClick

Settings

Viewport Navigation

Local Server Scale: scales Local Server node presentation.
Pan Base, Pan Exp, and Pan Boost: tune graph/viewport panning response.
Gizmo Zoom: adjusts transform gizmo zoom sensitivity.
Fly Speed: scales fly-mode navigation speed.
Wire Color: opens a color swatch for wireframe rendering.

Lighting and Shadows

Shadow Quality: choose Low, Medium, High, or Ultra shadow map quality.
Cast Shadows: enables meshes and splats casting shadows into the scene.
Self Shadows: lets a mesh receive its own shadow; turn it off to keep shadows from other objects while removing self-shadow artifacts.
Ambient Light: toggles the renderer base fill light.
Work Light: keeps normal-based lighting while bypassing viewport shadow darkening and adding fill light for modeling.
Unlit View: draws viewport meshes without light shading or shadow darkening.
2-Sided Shadows: casts shadows from front and back faces, useful for thin or closed geometry.

Debug and Skeleton Display

Debug Log: toggles splat/viewport diagnostic logging.
Joint Names: shows visible skeleton joint names in the 3D view.
The top bar Debug menu separately controls EchoGraph log and viewport debug state.

Layout and Voice Audio

Auto Save Layout: automatically captures panel visibility and view mode as the global default.
Turn-Taking Audio: pauses microphone capture while another actor speaks; disabling it allows bilateral mic and speaker behavior.
Microphone: selects the speech recognition microphone device when available.
The refresh icon at the top of Settings resets settings back to defaults.

Node Catalog

Current kinds available from Create Node and plugin registration. Click a node to open its focused catalog page.

Core and Utility

AI and Knowledge

Automation, Voice, and Control

3D, Rigging, and Scene Processing

Mesh, Materials, and Grooming

Media and Review

Aliases also exist for many node kinds, including scene_assembly, scene_outliner, exportfbx, export fbx animation, video player, bvh_import, retarget, gpt_prompt, copy to points, hair guides, guide_tube, serial_port, and legacy medigator_agent.

Agents

Agent workflows cover the Task, Data Nexus, Mediator, Chatbot, and HTML Preview loop used by guided AI roles. This section is placed with the pipeline examples because agent work is one workflow category, not the only workflow type.

Agents and Supporting Pieces

Sales Agent: the pitch-deck agent role that reviews readiness, writes or updates prep questions, resolves answered questions, and drafts slide copy from Data Nexus facts.
Teacher Agent: the template-building agent role that converts human templates into structured agent templates through the Skills library workflow.
Tanya / Chatbot: the user-facing conversation surface for asking to continue work and answering active questions.
Mediator: the routing and execution layer that hands controlled agent requests to the right workflow and applies Data Nexus updates.
Task node: not an agent. It is the explicit workflow step controller for Run Step, Write Questions, Generate Draft, Refresh HTML, Index Slides, and status.

Language and Reading Agents

Translator Agent: a Mediator profile that translates the latest voice-transcribed input into the downstream Voice Actor target language, or natural English when no target language is provided.
Japanese Reader: converts English, Japanese, or mixed input into natural Japanese plus ASCII romaji pronunciation for someone who cannot read Japanese.
Korean Reader: converts English, Korean, or mixed input into natural Korean plus ASCII romanized pronunciation for someone who cannot read Hangul.
Chinese Reader: converts English, Chinese, or mixed input into Mandarin Chinese plus ASCII pinyin pronunciation for someone who cannot read Chinese characters.
Multilingual speech path: voice_actor handles listening and speaking; the Mediator language profile handles translation or reading output.

Agent Task Preparation Workflow

Create or open a workflow with skills, data_nexus, mediator_agent, task, and optionally html_preview.
Connect skills to task.skills, data_nexus to task.data_nexus, and mediator_agent to task.mediator.
Optional: connect task.artifact to html_preview.path so generated decks preview automatically.
Click Run Step on the Task node to check slide readiness. With Mediator connected, Sales Agent AI reviews the newest Data Nexus points and can mark old prep questions as answered by existing points.
Click Write Questions to create or update only the still-needed prep_question points. If the graph has not changed and the old questions are still valid, the task reuses them instead of creating duplicates.
In Data Nexus, use Needs? and Refine? to show or hide question-source reference lines. These refs are saved as metadata, so they do not need to clutter the graph.
In Chatbot, ask Tanya to continue the Sales Agent or keep working on the pitch deck. She should ask the active open prep question.
Answer naturally in Chatbot. If the answer is coherent, Tanya saves it as a normal Data Nexus point and links it back to the yellow question point.
If you added answer points manually, click Run Step again. Task can link those existing points to open questions using answers_question.
Click Generate Draft when you want to view a deck. The draft can still be generated with weak slides; unsupported sections are written conservatively for review.
Review the generated index.html, styles.css, and manifest.json under Skills/generated_decks/. Task also indexes generated slides as green slide points in Data Nexus.

Answering Prep Questions

Preferred chat flow: ask Tanya continue the Sales Agent for the pitch deck, then answer the one question she asks.
You can still use an exact question ID when needed, for example Answer prep_question slide_03_problem_prep_question: Customers lose time because review work is spread across chat, files, and engine tools.
Data Nexus keeps the yellow question point as a question, creates or updates a normal answer point, and adds an answers_question link.
If you add a normal point yourself instead of answering through chat, Task Run Step can ask Sales Agent AI whether that point resolves an existing prep question and then add the same answers_question link.
After a saved answer, Data Nexus advances the active question to the next open prep question when one exists.
Answered questions improve Task readiness because connected Task nodes rerun readiness after non-Task Data Nexus updates.
Question-source references do not need to clutter the graph. They are saved as source_point_ids metadata and only draw when their toggle is enabled.

Data Nexus Review Tools

Drag the vertical dividers to resize the point list, graph canvas, and point detail columns when text needs more room.
Use Arrange for linked-point layout and Cluster to separate regular points, question points, and slide points into clearer groups.
Normal points, needs-answer questions, refinement questions, and slide points use different colors and dot sizes so the graph is easier to scan.
Newly created points show a white review ring until the next add operation, even if you move, arrange, or cluster the graph.
Delete selected point now asks for confirmation and shows how many links will be removed before the point is deleted.
Use Index Slides on Task after an existing deck changes; slide points update in place and keep ordered next_slide links plus uses_source links to supporting points.

Common Pipelines

Skills + Data Nexus + Task Sales Deck

Use skills to confirm an approved Sales Agent html_deck template and an approved sales pitch deck task guide are available.
Use data_nexus to collect sales facts as normal answer points, such as company profile, problem, workflow outcome, traction, pricing, competition, and team context.
Connect skills -> task.skills, data_nexus -> task.data_nexus, and optionally mediator_agent -> task.mediator for LLM review/question writing.
Click Task Run Step. The Task node resolves the guide/template, reads Data Nexus, reports slide readiness, and asks Sales Agent AI to review when Mediator is connected.
If you added new points manually, Run Step can reconcile them against open prep questions and link existing answer points with answers_question.
Click Task Write Questions to have Sales Agent AI write focused prep_question points into Data Nexus. The write sync adds genuinely new questions, updates changed questions, and removes stale Task-owned questions.
Ask Tanya in Chatbot to continue the Sales Agent/pitch deck. She asks one active open prep question at a time; coherent answers become normal points linked back with answers_question.
Use Data Nexus Needs? and Refine? to show or hide question-source lines while preserving traceability.
Click Generate Draft to create a Mediator-written deck draft. Weak slides are allowed in the draft but are marked conservatively for review.
Review the generated deck folder containing index.html, styles.css, and manifest.json; connect task.artifact to html_preview.path for in-app review.
Use Refresh HTML for style-only deck updates, Index Slides to rebuild green slide points from an existing deck, and HTML Preview Export PDF when you need a paged PDF copy.

Scene Assembly and Export

Create import, fbx_import, primitive, curve, or modeler nodes.
Optional processing: normals, uv_unwrap, texture/texture_pro/texture_layer, material, split_volume, transforms, or anim_retarget.
Use instance or copy_to_points when you need repeated assets.
Add camera and light nodes when the scene needs explicit shot and lighting control.
Connect into scene and review in 3D viewport.
Finish with export_fbx, export_fbx_animation, or export_obj for DCC handoff.

Librarian and LLM Workflow

Create librarian and set docs path.
Build or load librarian index and run search or summarize.
Use llm_prompt or chatbot for response generation.
Attach database for persistence and append plus output for final aggregation.

Chatbot + Mediator Agent Workflow

Configure llm_prompt for Ollama/DeepSeek or OpenAI, then connect it to chatbot llm_prompt.
Connect database to chatbot database so the Chatbot owns conversation history.
Connect a speech-to-text voice_actor to chatbot voice_input.
Set a mediator_agent profile such as assistant_tanya, then connect Mediator to chatbot mediator_input.
For Qubit Deck commands, connect qubit_deck_controller to the Mediator so Mediator can read deck context and execute approved handoffs.
Connect the output Voice Actor after Chatbot for this workflow; Mediator output stays silent for Chatbot-origin execution results.

Task Planning Workflow (Gantt)

Create one or more note nodes with task parameters.
Optional: combine notes through append and use append order to control Gantt group order.
Connect to gantt_chart and assign dates or progress per task row.
Use collapse or expand on note groups to focus planning.
Use copy/paste buttons to transfer schedule + progress into another Gantt chart instance.

Voice-Controlled Qubit Deck

Create voice_actor, set its response mode, and connect its output to mediator_agent voice_input.
Set Mediator prompt profile to qubit_deck_controller.
Connect Mediator output to qubit_deck_controller mediator_input.
Optional: place a python node between Mediator and Voice Actor to extract only <user_feedback> text for speech.
Use qubit_deck_controller in Context mode to list buttons, then Executor mode to invoke or highlight actions.

FBX + Mocap Retargeting

Create fbx_import and assign rest geometry, capture pose, and optional animated pose FBX sources.
Create mocap_import and browse to a BVH file, then validate the clip.
Connect mocap or animated FBX into anim_retarget source.
Connect the target rig fbx_import into anim_retarget target.
Validate mapping, adjust root/scale/rotation settings, preview, then continue to scene/render/export stages.
Use export_fbx_animation when you need a rigged FBX animation file instead of a static scene export.

Video to Mocap

Run Mocap\setup.bat once for the GEM-X/GEN-X environment.
Create genx_video_mocap and browse to an MP4, MOV, AVI, MKV, or WebM source.
Choose the rig export target, such as SOMA BVH or Unitree G1.
Run the node and let it create a mocap_import node from the latest generated BVH.
Retarget that mocap through anim_retarget for viewport, render, or FBX animation export.

Image to Gaussian Splat

Run setup.bat after installing updates, approve the setup prompt when creating image_gs_splat, or use Setup Image-GS in the node InfoCard so the Image-GS checkout and dependencies are ready.
Create image_gs_splat and enter an HTTP image URL or local image path.
Leave Auto HQ enabled for automatic high-quality splat count, progressive optimization, loss weights, render height, radius, alpha, and export-cap selection, or disable it for manual tuning.
Click Generate; the node downloads the image, runs Image-GS, converts the checkpoint to PLY, stores the result under logs\image_gs_splat, and writes QC data into the manifest/debug report.
Click View or connect the node into scene to inspect the generated splat in the viewport.

Render Review and Video Output

Build a scene from import, retarget, transform, material, or texture nodes.
Use render to produce an image sequence.
Optional: connect the sequence to post_process for dither/grayscale style processing.
Preview frames or clips with video_player.
Finish with sequence_to_mp4 for MP4 delivery.

Keyboard Auto Runner

Create keyboard_sequence and add key/action rows.
Set lead-in delay so you have time to focus the target application.
Choose injection mode and per-key hold timing for the target app.
Optional: connect serial_com for Pico-backed HID commands when the target workflow needs hardware input.
Run the sequence, or stop it if the target app state changes.

Audio and Voice Capture

Create audio_capture and choose output-device, input-device, or application source mode.
Select the device/backend and tune threshold, silence window, phrase duration, and sample rate.
Use Test to confirm signal detection.
Route captured audio or transcribed text into voice_actor, chatbot, or mediator_agent workflows as needed.

Mask to Groom Guides

Load a mesh through import, fbx_import, or a compatible processed mesh node.
Connect into mask and paint the scalp or emission region.
Connect mask to groom_guides and set count, length, segments, threshold, and seed.
Use groom_deform to bind guides to a retargeted rig when animated deformation is needed.
Use groom_guide_pose, groom_guide_sim, or groom_guide_tube for posed, simulated, or tube-geometry output.

Skinned Collision and Splat Proxies

Start from fbx_import or anim_retarget so a rig context is available.
Use skinned_volume_mesh to generate a voxel-derived collision mesh for guide simulation.
Use skinned_splat_proxy to generate render proxies from a rig source or from groom_guide_tube.
Connect the generated asset into scene for viewport review or into render/export nodes for delivery.

Troubleshooting

Setup issues: check setup.log at repo root after running setup.bat.
Librarian launch issues: run nodes\librarian\librarianSetup.bat and review nodes\librarian\librarian_child.log and nodes\librarian\librarian_crash.log.
Hotkey mismatch: open Hotkeys dialog and confirm bindings, or regenerate hotkeys.json.
Wireframe default is H; if not, verify gl_wireframe_toggle in hotkeys.json.
Gantt copy/paste debugging: inspect CSV transfer logs under gantt_chart\transfer_logs.
If Gantt group order is stale after append reorder, press Apply Order on the append node so downstream charts refresh.
FBX import or retarget validation issues: run check_fbx_sdk.ps1, or rerun setup.bat full "C:\path\to\fbx_runtime" with the Autodesk FBX runtime folder.
Sequence to MP4 issues: confirm setup reported bundled ffmpeg as ready, or install ffmpeg on PATH.
Voice Actor speech issues: rerun setup.bat so voice dependencies are installed; Local Whisper requires faster-whisper, Tanya/Google voice uses gTTS plus pygame, and Japanese Kokoro-82M requires the bundled unidic-lite MeCab dictionary.
Audio Capture issues: rerun setup.bat; output-device capture needs soundcard plus numpy, and input-device capture needs a working audio backend such as PyAudio.
Mediator issues: confirm Node.js, npx, and tools\codex.ps1 are available; Mediator logs are under logs\mediator_agents.
Chatbot/Mediator handoff issues: confirm chatbot.mediator_input is connected, llm_prompt is set to the intended DeepSeek/Ollama model, and only the active input route owns speech output. Chatbot-origin tool execution should speak through Chatbot output, while direct Mediator voice workflows speak through Mediator output.
Task readiness issues: confirm skills -> task.skills and data_nexus -> task.data_nexus are connected, then press Task Run Step before Generate Draft. Connect mediator_agent -> task.mediator when you want Sales Agent AI review.
Task question-write issues: if Write Questions seems quiet, check data_nexus_write. questions is the active question count; the message shows whether points were added, updated, or deleted. data_nexus_answer_links shows when newer points were linked as answers to old questions.
Prep question visibility issues: yellow/orange prep_question points can exist without visible source lines; enable Data Nexus Needs? or Refine? to show the reference lines.
Prep question answer issues: ask Tanya to continue the Sales Agent for the pitch deck, then answer the active question she asks. Exact IDs still work, for example Answer prep_question slide_03_problem_prep_question: ....
Generated deck issues: after Task Generate Draft, check the Task artifact output and the generated folder under Skills/generated_decks/ for index.html, styles.css, and manifest.json. Use Task Index Slides if the green slide points need to be rebuilt from an existing deck.
Skills validation warnings: open the Skills node details panel. Package warnings usually mean a referenced source template, conversion report, or supporting file listed in front matter is missing from the local Skills/ library.
Qubit Deck control issues: use qubit_deck_controller Context mode first to confirm button names before sending Executor JSON from Mediator.
Keyboard Auto Runner issues: make sure the intended target app has focus before the lead-in delay ends, increase key hold time for apps that miss fast input, and check connected serial_com nodes when Pico HID output is enabled.
Serial COM issues: install pyserial through the node prompt or rerun setup.bat, then confirm the COM port, baud rate, and timeout match the target device firmware.
Gen-X video mocap issues: run Mocap\setup.bat, confirm the selected video exists, and check the configured output root for generated BVH files.
Normals, masks, and grooming issues: confirm the upstream mesh path exists and uses a supported mesh extension (.obj, .fbx, .gltf, or .glb); Groom Guides also needs a painted Mask input.
Skinned volume or splat proxy issues: confirm the upstream fbx_import or anim_retarget source exposes a valid rig context, then regenerate when settings or source files change.

Developer Guide (High Level)

Node specs are registered through nodes/core and plugin bootstrap in nodes/loader.py.
Create Node kinds are defined in echograph/ui/dialogs.py.
Hotkey defaults are in echograph/ui/hotkeys_config.py and merge with root hotkeys.json.
Workflow files persist graph structure and node parameters as JSON.
Librarian service runs out of nodes/librarian/.venv as a separate process.
Voice Actor uses hidden event tokens so downstream automation only reacts to fresh send events.
Mediator prompt profiles live under nodes\mediator_agent\prompts; the Qubit Deck profile emits command JSON plus optional <user_feedback> text.
Python helper scripts in scripts\ can be pasted into Python nodes for output cleanup, including user feedback extraction for voice playback.
Rigging and retargeting helpers live under echograph\rigging and are surfaced through fbx_import, mocap_import, and anim_retarget.
Grooming and skinned proxy helpers also live under echograph\rigging and are surfaced through mask, groom_guides, groom_deform, groom_guide_pose, groom_guide_sim, groom_guide_tube, skinned_volume_mesh, and skinned_splat_proxy.
Gen-X video mocap integration uses the Mocap\GEM-X runtime and can create mocap_import nodes after successful BVH generation.
Serial/Pico automation helpers are exposed through serial_com and consumed by downstream automation paths such as keyboard_sequence.