### Install and Launch XGEE Example Application

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Clone the example application, install the XGEE launcher via pip, and start the integrated EOQ model and web server.

```bash
# Clone the example application (includes submodules)
git clone --recurse-submodules https://gitlab.com/xgee/xgee-example-app.git

# Install the XGEE launcher
pip install XGEE

# Start the EOQ model server + web server
cd xgee-example-app
xgee

# Open in browser
# http://localhost:8080
```

--------------------------------

### Clone XGEE Example App and Install Framework

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/gettingStarted.md

Clone the XGEE example application repository and install the XGEE framework using pip. Ensure your SSH key is set up for GitLab.

```bash
git clone --recurse-submodules https://gitlab.com/xgee/xgee-example-app.git
pip install XGEE
```

--------------------------------

### Set up Local Documentation Environment

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Commands to clone the XGEE documentation repository, set up a virtual environment, and install dependencies using pip.

```bash
# Set up local documentation environment
git clone git@gitlab.com:xgee/xgee.gitlab.io.git
cd xgee.gitlab.io
python -m venv venv
source venv/bin/activate          # Linux/macOS
pip install -r requirements.txt

```

--------------------------------

### Install Dependencies

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/README.md

Install all required Python packages for building the documentation using pip. Ensure your virtual environment is activated.

```sh
pip install -r requirements.txt
```

--------------------------------

### Launch XGEE Server

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/gettingStarted.md

Start the XGEE server from the xgee-example-app directory. This command initiates the EOQ server and the web server necessary for XGEE.

```bash
xgee-example-app> xgee
```

--------------------------------

### Clone XGEE Repository

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/README.md

Clone the XGEE documentation repository to your local machine. Navigate into the cloned directory to proceed with setup.

```sh
git clone git@gitlab.com:xgee/xgee.gitlab.io.git
cd xgee.gitlab.io
```

--------------------------------

### Configure XGEE Plugin Autostart

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/xgee_example_app.md

Add this entry to the XGEE application's startup configuration in App/index.html to ensure your custom plugin is loaded automatically when the editor starts.

```javascript
'editor.oaam.myfunctions': {
    enabled: true,
    pluginPath: 'plugins/'
},
```

--------------------------------

### Example EOQ2 Python Action

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/eoq_actions.md

Define an EOQ2 action in Python, including type hints for arguments and return values, which will be displayed in the XGEE Actions menu.

```python
'''
  Automatic signal routing using Dijkstra
'''

from oaamUtils import autorouter

def autoroute(domain : 'Domain',
        hardware : 'Hardware: The OAAM hardware element.',
        functions : 'Functions: The OAAM functions element.',
        allocation: 'Allocations: The OAAM allocations element.'
        ) -> "Bool:Whether the generation succeeded or not.":

    res=autorouter.run(domain,hardware,functions,allocation)
    print(res)
    pass
```

--------------------------------

### Clone XGEE Eclipse Projects

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/modeling_with_xgee.md

Clone the XGEE Eclipse projects repository to start your development. This repository contains the necessary meta-model definitions.

```bash
git clone git@gitlab.com:xgee/xgee-development/xgee-eclipse-projects.git
```

--------------------------------

### Regenerate Ecore Documentation

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/README.md

Update the documentation generated from Ecore metamodels. This script requires the 'pyecore' package to be installed separately.

```bash
python export_ecore_docu.py
```

--------------------------------

### Set EOQ Query Target

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Define the starting point for EOQ queries using the `queryTarget` attribute. Common values include PARENT, EDITORROOT, MODELROOT, RESOURCE, and ROOT.

```xml
<!-- PARENT: query starts at the Task object itself — fetches /name -->
<displayableObjects xsi:type="xgeeDisplayObjects:Vertex"
    queryStr="/tasks"
    queryTarget="PARENT"/>      <!-- PARENT of a top-level Vertex = EDITORROOT -->

<!-- EDITORROOT: explicitly start at the Functions root -->
<displayableObjects xsi:type="xgeeDisplayObjects:Vertex"
    queryStr="/tasks"
    queryTarget="EDITORROOT"/>

<!-- CUSTOM alias: reference a named alias from an ancestor object -->
<subVertices xsi:type="xgeeDisplayObjects:SubVertex"
    queryStr="/inputs"
    queryTarget="CUSTOM"
    queryTargetAlias="MYTASK"/>  <!-- alias exposed by a parent Vertex -->
```

--------------------------------

### Regenerate Metamodel Reference Pages

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Command to regenerate Markdown files for presentation and layout models from .ecore metamodels using the 'export_ecore_docu.py' script. Requires pyecore to be installed.

```bash
# Regenerate metamodel reference pages after editing .ecore files
pip install pyecore
python export_ecore_docu.py

```

--------------------------------

### Build Documentation Locally with Sphinx

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Commands to build the XGEE documentation locally using Sphinx. Includes options for a standard build and a strict build that fails on warnings.

```bash
# Local preview build
sphinx-build . public

# Strict build — must produce zero warnings before merging
sphinx-build --fresh-env --nitpicky --fail-on-warning . public

```

--------------------------------

### Build Documentation with Nitpicky Checks

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/README.md

Perform a thorough documentation build with strict checking for warnings and inconsistencies. Use this before committing to ensure quality.

```sh
sphinx-build --fresh-env --nitpicky --fail-on-warning . public
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/README.md

Create a Python virtual environment named 'venv' to isolate project dependencies. Activation commands vary by operating system.

```sh
python -m venv venv
```

```sh
source venv/bin/activate
```

```bat
venv\Scripts\activate.bat
```

```powershell
venv\Scripts\Activate.ps1
```

--------------------------------

### Build Documentation Locally

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/README.md

Generate the documentation locally using Sphinx. This command builds the documentation into the 'public' directory.

```sh
sphinx-build . public
```

--------------------------------

### Configure Plugin Loading in index.html

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/editor_integration.md

Add an entry to the jsApplication plugin configuration in your XGEE application's index.html to load your custom editor plugin at startup.

```javascript
'ExampleEditor' : {enabled: true}
```

--------------------------------

### Configure Palette and Categories

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Organize tools into named categories for the XGEE sidebar. Categories and their tools appear in the order they are defined.

```xml
<!-- Inside <xgee:Editor ...> -->

<palette xsi:type="xgeePalette:Palette" name="Functions Palette">

  <!-- Category for task creation tools -->
  <categories name="Tasks"
      tools="//@tools.0"/>  <!-- reference to the first DragAndDrop tool -->

  <!-- Category for failure condition tools -->
  <categories name="Failure Conditions"
      tools="//@tools.1"/>  <!-- reference to the second DragAndDrop tool -->
</palette>
```

--------------------------------

### Initialize XGEE Editor Plugin

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/xgee_example_app.md

This JavaScript code initializes the XGEE editor plugin, specifying the path to the editor model and requiring necessary core plugins like 'ecore' and 'editor'.

```javascript
export async function init(pluginAPI) {
        pluginAPI.implement('xgee.models',{
        modelPath: pluginAPI.getPath()+'MyFunctions.editorModel'
    })
    return true
};

export var meta={
    "id":"editor.oaam.myfunctions",
    "requires":["ecore","editor"]
};
```

--------------------------------

### Define Task Creation Command

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/xgee_example_app.md

Configure a Drag and Drop Tool to create a new Task instance. This command specifies the model URI and the type of object to be created, enabling drag-and-drop functionality for tasks.

```default
CRN 'http://www.oaam.de/oaam/model/v160/functions' Task 1
```

--------------------------------

### Define Plugin Meta Information

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/editor_integration.md

Provide essential metadata for your jsApplication plugin, including its ID, description, author, version, and dependencies.

```javascript
export var meta={
    "id":"ExampleEditor",
    "description":"Example Editor from the XGEE tutorial",
    "author":"Your Name",
    "version":"1.0.0",
    "requires":["xgee"]
};
```

--------------------------------

### Check Model Loading in EOQ3 XGEE

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/faq.md

Use this query in the developer web interface to verify that your usermodels are loaded correctly. A 'n0' result indicates a loading issue.

```default
GET (/*M1MODELS*:l0/*OBJECTS*:l0/resources*/content)
```

--------------------------------

### Register XGEE Editor Model via Plugin

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Implement the `xgee.models` extension point in a jsApplication plugin to register the editor model path with XGEE. Ensure the plugin is also listed in `index.html` for autostart.

```javascript
// App/core/plugins/editor.oaam.functions/plugin.js

export async function init(pluginAPI) {
    // Register the editor model with XGEE
    pluginAPI.implement('xgee.models', {
        modelPath: pluginAPI.getPath() + 'Functions.editorModel'
    });
    return true;
}

export var meta = {
    "id": "editor.oaam.functions",
    "description": "Functions Layer Editor for OAAM",
    "author": "ILS Stuttgart",
    "version": "1.0.0",
    "requires": ["ecore", "editor"]   // jsApplication plugin dependencies
};

// App/index.html — PLUGIN CONFIG block:
// 'editor.oaam.functions': { enabled: true, pluginPath: 'plugins/' },
```

--------------------------------

### Connect to EOQ2 Domain via WebSocket

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Python script to connect directly to a running EOQ2 WebSocket domain. Requires 'eoq2' and 'websocket-client' libraries. Used for batch processing, testing, or automation.

```python
# dependencies: pip install eoq2 websocket-client
from eoq2 import Cls, Get
from eoq2.domain.remote import WebSocketDomain
from eoq2.serialization import JsonSerializer

# Connect to the EOQ2 domain started by `xgee`
domain = WebSocketDomain("ws://localhost:8000/ws/eoq.do", 10, JsonSerializer())

# Fetch the names of all loaded ModelResources
result = domain.Do(Get(Cls("ModelResource").Pth('name')))
print(result)
# Expected output: ['LightControllerExample.oaam', 'newModel.oaam']

domain.Close()

```

--------------------------------

### Access XGEE in Browser

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/gettingStarted.md

Open XGEE in your web browser by navigating to localhost on the specified port. The default port is 8080.

```bash
localhost:8080
```

--------------------------------

### Activate eoq.actions Plugin Configuration

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/eoq_actions.md

Enable the eoq.actions plugin and configure its menu settings in your application's configuration.

```javascript
{
  "eoq.actions": {
    "enabled": true,
    "config": {
      "menuId": "ACTIONS_MENU",
      "menuName": "Actions",
      "appendBefore": true,
      "appendMenuId": "HELP_MENU"
    }
  }
}
```

--------------------------------

### Configure Actions Directory in config.yaml

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/eoq_actions.md

Specify the directory for EOQ actions in your application's config.yaml file.

```yaml
app:
name: OAAM Toolbox
port: 8080
eoq:
  port: 8000
  workspace: ./workspace
  actions: ./actions
  meta: ./meta
```

--------------------------------

### Define a Vertex with Shape, Labels, and SubVertices

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Configure a Vertex to display model objects. It requires a query string and target, and can include visual shapes, labels, and nested sub-vertices for ports or other elements. User interaction properties like `isMovable` are also configurable.

```xml
<!-- Inside <xgee:Editor ...> -->

<!-- Displays all Task instances under the Functions root -->
<displayableObjects xsi:type="xgeeDisplayObjects:Vertex"
    id="task"
    name="Task"
    queryStr="/tasks"
    queryTarget="PARENT"
    sizeX="60" sizeY="60"
    isMovable="true"
    isDeletable="true"
    isResizable="true">

  <!-- Rectangle shape with fill and border color -->
  <shape xsi:type="xgeeDisplayStyles:Rectangle"
      fillColor="#AED6F1"
      strokeColor="#1A5276"
      strokeWidth="2"
      rotation="0.0"/>

  <!-- Floating label showing the task name via EOQ placeholder -->
  <labels xsi:type="xgeeDisplayObjects:FloatingLabel" name="TaskLabel">
    <segments content="Task: {TASKNAME}" color="#000000">
      <!-- Resolves {TASKNAME} by querying /name on the current object -->
      <queries alias="TASKNAME" queryStr="/name" queryTarget="PARENT"/>
    </segments>
  </labels>

  <!-- Input port as a nested sub-vertex -->
  <subVertices xsi:type="xgeeDisplayObjects:SubVertex"
      name="Input"
      queryStr="/inputs"
      queryTarget="PARENT"
      sizeX="12" sizeY="12"
      positioning="WEST">
    <shape xsi:type="xgeeDisplayStyles:Rectangle"
        fillColor="#FFFFFF"
        strokeColor="#000000"
        strokeWidth="1"/>
  </subVertices>
</displayableObjects>
```

--------------------------------

### Configure DragAndDrop Tool

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Define a drag-and-drop tool for creating new model elements. The `factoryCmd` specifies the command to instantiate the object, typically using CRN.

```xml
<!-- Inside <xgee:Editor ...> -->

<tools xsi:type="xgeeTools:DragAndDrop"
    id="failureconditiontool"
    name="Failure Condition"
    tooltip="Create a new failure condition"
    icon="icons/fc_preview.svg"
    providesTemplate="true">

  <!-- CRN creates a new FailureCondition instance -->
  <factoryCmd>
    <cmds alias="_CREATEFC"
        cmdStr="CRN 'http://www.oaam.de/oaam/model/v160/functions' FailureCondition 1"/>
  </factoryCmd>
</tools>
```

--------------------------------

### Configure jsApplication Plugin for Actions Menu

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Configure the 'eoq.actions' plugin to enable and customize the actions menu in the XGEE web UI. This configuration controls menu visibility and filtering of actions.

```javascript
// jsApplication plugin config — enable the actions menu
{
  "eoq.actions": {
    "enabled": true,
    "config": {
      "menuId": "ACTIONS_MENU",
      "menuName": "Actions",
      "appendBefore": true,
      "appendMenuId": "HELP_MENU",
      // Only show actions NOT tagged "advanced" unless ?advanced in URL
      "actionFilterFunction": "(action) => !action.tags.includes('advanced') || window.location.search.includes('advanced')"
    }
  }
}
```

--------------------------------

### Add First Task Representation

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/xgee_example_app.md

Manually add a first task to the XGEE model by defining it within the `<functions><tasks>` XML structure. This is a foundational step before modeling tasks in the editor.

```xml
<functions>
<tasks name="myTask"/>
</functions>
```

--------------------------------

### Configure FailureCondition Vertex Properties

Source: https://gitlab.com/xgee/xgee.gitlab.io/-/blob/master/tutorial/modeling_with_xgee.md

Set the Name, Query Str, Query Target, Size, and deletability/movability/resizability properties for the FailureCondition vertex.

```text
Name: FailureCondition
Query Str: /failureConditions
Query Target: PARENT
Size X: 50
Size Y: 50
Is Deletable: true
Is Moveable: true
Is Resizeable: true
```

--------------------------------

### Implement Automatic Signal Routing Action

Source: https://context7.com/xgee/xgee.gitlab.io/llms.txt

Python script for the 'autoroute' action, utilizing Dijkstra's algorithm for automatic signal routing. This script is intended to be called from the EOQ2 developer console.

```python
# actions/autoroute.py
"""
Automatic signal routing using Dijkstra
"""
from oaamUtils import autorouter

def autoroute(domain: 'Domain',
              hardware: 'Hardware: The OAAM hardware element.',
              functions: 'Functions: The OAAM functions element.',
              allocation: 'Allocations: The OAAM allocations element.'
              ) -> "Bool: Whether generation succeeded.":
    res = autorouter.run(domain, hardware, functions, allocation)
    print(res)

# Debug via EOQ2 developer console at http://xgee.de:9001/
# List actions:  GAA
# Call action:   CAL 'autoroute'

```