IngaBoard User Manual

1. Setup

IngaBoard is distributed as a PKG file. Open the package and follow the standard macOS installation prompts to install the application to your system. Once installed, you can launch the executable directly from your Applications folder.

Upon the first launch, you will be presented with the End User License Agreement (EULA). You must read and agree to these terms to proceed and begin using the application.

2. Starting a Board

The options available to you depend on how you begin your work:

• When launching the app: You will be prompted to either:
  • Load an existing .ingaboard.json file, a DOT (digraph), or Mermaid (graph) file.
  • Start a new board by selecting a template. You can start a new board by selecting one of the two templates:
    • Incident-centered: Best for causal chains (Cause → Effect) and post-incident prevention. Includes support for FTA (Fault Tree Analysis) structure.
    • Operation-centered: Best for process chains (Pre-process → Post-process), operational design, and FTA structures.
• When adding a new tab: You can start a new board by selecting one of the two templates above.

3. Editing and Modeling

• Registration: Enter causal fragments in the registration panel. The engine automatically generates the layout based on your input.
  • Cyclic Paths: IngaBoard does not enforce DAG constraints, enabling you to map feedback loops and circular processes effectively.
• Editing: Select nodes to modify labels or shapes (Box, Ellipse, Diamond etc). Nodes use invariable IDs, so causal connections are preserved even if labels are changed.
• Tags & Focus:
  • Use tags to categorize nodes.
  • Select a node to trigger the focus feature, which visually highlights the node itself, its ancestors, and its descendants, isolating the entire connected causal path.
• Undo/Redo: Use Cmd/Ctrl+Z to undo and Cmd/Ctrl+Shift+Z to redo actions.
• Full-screen: If the window becomes stuck in full-screen mode, click the "Full-screen Toggle" button.

4. Loading and Exporting

• Saving/Loading: Use .ingaboard.json as your primary format for saving and loading projects.
• Importing: IngaBoard supports importing DOT (digraph) and Mermaid (graph) files.
  • Caution: When importing these files, note that descriptions exceeding IngaBoard's native rendering capabilities may be modified or simplified by the engine.
• Exporting: You can export your diagrams in the following formats:
  • PNG
  • JPEG
  • SVG
  • DOT
  • Mermaid

5. CLI

While IngaBoard provides an intuitive visual interface for modeling and exploration, the CLI (ingaboard_text_cli) allows you to harness the power of the engine directly from your terminal. This is designed for power users who need to integrate structural analysis into automated documentation pipelines, CI/CD workflows, or large-scale batch processing. By processing data at the command line, you can transform complex raw data into standardized graph formats or high-quality visuals without ever opening the GUI.

normalize

Normalizes the input text by cleaning up whitespace and control characters, then outputs the result to standard output.

echo '  A   B  ' | ./build/ingaboard_text_cli normalize
# A B

json-to-dot

Reads JSON text equivalent to .ingaboard.json and outputs the corresponding DOT file.

cat examples/state_max.json | ./build/ingaboard_text_cli json-to-dot

json-to-mermaid

Reads JSON text equivalent to .ingaboard.json and outputs the corresponding Mermaid file.

cat examples/state_max.json | ./build/ingaboard_text_cli json-to-mermaid

json-to-svg / json-to-png / json-to-jpeg

Reads JSON text equivalent to .ingaboard.json and outputs image data. If a file path is provided as an argument, the data is saved directly to that file (recommended).

cat examples/state_max.json | ./build/ingaboard_text_cli json-to-svg out.svg
cat examples/state_max.json | ./build/ingaboard_text_cli json-to-png out.png
cat examples/state_max.json | ./build/ingaboard_text_cli json-to-jpeg out.jpeg

6. Troubleshooting

This document is built from source-code terms and literals.

When loading a file, IngaBoard assumes the file is encoded in UTF-8.

Use the log panel and error payload (error.code, error.debug) to identify issues quickly.

UI messages

• Cannot load because bridge is not connected.
  • Typical cause: UI/host bridge not ready or broken
  • What to do: Restart the app, then try again.
• Cannot save because bridge is not connected.
  • Typical cause: Same as above
  • What to do: Restart the app; retry Save/Save As.
• Cannot export because bridge is not connected.
  • Typical cause: Same as above
  • What to do: Restart the app; retry export.
• Failed to sync: {error}
  • Typical cause: Exception during UI↔host sync
  • What to do: Retry once; if repeated, restart and capture the log text.
• Invalid response (doc_json not found).
  • Typical cause: Host response missing result.doc_json
  • What to do: Retry operation; if reproducible, report with logs.
• Failed to load.
  • Typical cause: Open flow failed
  • What to do: Check file format/path/permissions; then retry.
• Failed to save.
  • Typical cause: Save flow failed
  • What to do: Check destination permissions/free space/path.
• Failed to toggle fullscreen: {error}
  • Typical cause: Window manager / platform fullscreen issue
  • What to do: Retry toggle; restore window and retry.
• Partially failed:\n{errors}
  • Typical cause: Multi-export where one or more targets failed
  • What to do: Review each listed error and retry failed targets only.
• Warnings while loading:\n... / (warnings: {count})
  • Typical cause: Open succeeded with data normalization drops
  • What to do: See warning section below; verify imported graph.

Host error codes

Use error.code as primary key. error.debug usually contains the precise failing condition.

Request / protocol

• BAD_VERSION
  • Debug clues from source: req.v=...
  • Typical cause: Protocol version mismatch
  • What to do: Ensure UI/host are from the same build.
• BAD_REQUEST
  • Debug clues from source: missing args.doc_json, gate_type must be AND or OR, invalid request id
  • Typical cause: Missing/invalid request shape
  • What to do: Re-run through normal UI flow; avoid malformed manual requests.
• UNSUPPORTED_CMD
  • Debug clues from source: cmd=...
  • Typical cause: Unknown command name
  • What to do: Update caller to supported commands only.
• NOT_IMPLEMENTED
  • Debug clues from source: open dialog hook is not implemented
  • Typical cause: Open dialog hook not wired in current runtime
  • What to do: Use standard UI build/runtime where dialog integration exists.

File open / import

• UNSUPPORTED_FORMAT
  • Debug clues from source: unsupported extension: ...
  • Typical cause: Extension is not .ingaboard.json, .dot, .mmd, .mermaid
  • What to do: Use supported extensions only.
• IO_ERROR
  • Debug clues from source: failed to open: ...
  • Typical cause: File path missing/inaccessible
  • What to do: Check path, permissions, mount state.
• BAD_FILE (NormalizeOpenProjectJson: Unsupported file version)
  • Typical cause: Unsupported file version
  • What to do: Open with compatible/newer app version.
• BAD_FILE (NormalizeOpenProjectJson: Invalid intervention)
  • Typical cause: Invalid intervention shape
  • What to do: Fix data structure in file or use known-good source file.
• BAD_FILE (LoadFromJsonString: ...)
  • Typical cause: Invalid .ingaboard.json payload
  • What to do: Validate JSON structure/content.
• BAD_FILE (from_dot_subset: DOT import supports digraph only.)
  • Typical cause: DOT is not digraph subset
  • What to do: Convert input to supported digraph form.
• BAD_FILE (from_mermaid_subset: Mermaid import supports flowchart/graph only.)
  • Typical cause: Mermaid type unsupported
  • What to do: Use flowchart / graph only.

Document state / edit operations

• NO_DOCUMENT / NO_DOC
  • Debug clues from source: call set_doc first / doc not found. doc_id=...
  • Typical cause: No active document for command
  • What to do: Set/open a document first.
• NO_HISTORY
  • Debug clues from source: undo stack empty / redo stack empty
  • Typical cause: No undo/redo entries available
  • What to do: Continue editing to create history.
• BAD_ARGS
  • Debug clues from source: missing cause_label/effect_label, missing node_id/node_label, bad arg types, bad format: ...
  • Typical cause: Missing or wrong argument type/value
  • What to do: Provide all required args with correct types.
• NODE_NOT_FOUND
  • Debug clues from source: node_id not found, node_label not found
  • Typical cause: Target node missing
  • What to do: Re-select valid node and retry.
• EDGE_NOT_FOUND
  • Debug clues from source: edge not found: ...
  • Typical cause: Target edge missing
  • What to do: Verify edge exists before deletion.
• DUPLICATE_LABEL
  • Debug clues from source: duplicate label: ...
  • Typical cause: Rename to already-used label
  • What to do: Choose a unique label.
• GATE_RENAME_FORBIDDEN
  • Debug clues from source: attempted to rename gate node
  • Typical cause: Attempted rename on AND/OR gate node
  • What to do: Do not rename gate nodes directly.
• FAILED
  • Debug clues from source: apply_gate_by_child_label returned false
  • Typical cause: Gate insertion preconditions not met
  • What to do: Ensure merge-point target and valid gate insertion context.

Export / render / internal

• GRAPHVIZ_FAILED
  • Debug clues from source: dot exit code: ..., dot terminated by signal: ...
  • Typical cause: Graphviz execution failure
  • What to do: Verify bundled/system dot availability and runtime access.
• IO_ERROR
  • Debug clues from source: missing svg, missing tmp path, failed to open: ...
  • Typical cause: Generated artifact missing/unreadable
  • What to do: Retry export; verify temp/output path accessibility.
• INTERNAL
  • Debug clues from source: SaveToJsonString..., dispatcher exception: ...
  • Typical cause: Unexpected internal failure
  • What to do: Restart app; if reproducible, report with logs and steps.
• CANCEL / CANCELLED
  • Debug clues from source: open file dialog cancelled
  • Typical cause: User canceled dialog
  • What to do: No recovery needed; retry action if desired.

Warning messages on load

These are non-fatal; load can still succeed.

• Duplicate node id ignored: {id}
  • Meaning: Later duplicate node ID was dropped
  • Suggested action: Inspect imported graph; fix duplicated IDs in source data if needed.
• Edge ignored: unknown node reference ({from} -> {to})
  • Meaning: Edge references a node that does not exist
  • Suggested action: Repair broken node references, then reload.

Startup / EULA related strings

• Failed to load assets/eula_en.txt / Failed to load assets/eula_ja.txt
  • Meaning: EULA text asset missing/unreadable
  • Suggested action: Reinstall app/package and verify Contents/assets/eula_*.txt.
• Failed to persist EULA consent. The app will quit.
  • Meaning: Could not write consent config (/eula/agreed)
  • Suggested action: Check user config directory write permission and free space.
• Disagree (Quit)
  • Meaning: User selected quit path
  • Suggested action: Relaunch and select Agree to continue.

Quick triage flow

1. Check UI message (English locale string).
2. Check error.code.
3. Check error.debug for exact failing condition.
4. If load succeeded with warnings, inspect warnings[].
5. If reproducible with INTERNAL/GRAPHVIZ_FAILED, collect logs + steps and report.