Developer guide

This is the place to start for building a desktop application on VexelRay, whether a coding agent writes most of it, you do, or the two of you take turns. Every other document on the stack is linked from here, so if you are looking for something, look in the table below first.

I want to…

I want to…	Read
Know what I am signing up for	What you are signing up for, below
Install the stack	Getting started §1–2: one script, `bootstrap.sh`
Make a new project and run it	Getting started §3–4
Find my way around a generated project	Getting started §5
Add a part, a setting, or replace a default	Getting started §5, then overview.md for the order parts are built in
Work with a coding agent	Building with an LLM
Write code by hand	Coding in Vex, or any Java IDE
Build a view the widgets don’t have (a timeline, a map, a board)	Building a custom view
Make changes animate instead of jump	Making it move
Run something in the background without freezing the window	Threading conventions, and the generated README’s Threading, in one paragraph
Drive the app, take screenshots, test it end to end	Getting started §7, then the ottermate guide
Look up an ottermate verb	The automation reference, or `ottermate help`
Log, and find the log	Getting started §8
Build the executable and an installer	Shipping it
Look up a widget or a GUI API	Its javadoc: Ctrl+Enter in Vex, or your IDE. The GUI’s design documents are indexed here
Know which repository does what	The repositories
Understand how the framework works	Overview, then Architecture for the deep version
Tell a gap in the framework from a mistake of mine	TODO.md, and what v1 means
Report something missing or wrong	Write it in your project’s `docs/framework-notes.md`, then open an issue
Look back at a finished milestone	Looking back at a milestone: the retrospective, in your project’s `docs/retrospective.md`

What you are signing up for

Java 25, compiled to a native executable with GraalVM. The window is drawn with Vulkan, so anything you can draw, you can put in it.
Windows or Linux. Windows is the most complete; Linux builds, runs and ships. macOS is a skeleton.
Before v1. This is 0.1.x, an experimental prerelease. Names still change between versions, and TODO.md is honest about what is missing. What v1 means says what will stop changing.
Not on Maven Central. You clone the stack and install it to your own Maven repository, once, with one script. It takes about half an hour, most of it the first build.

The way through

	Step	Where
1	Install the tools and build the stack	Getting started §1–2
2	Generate a project from the template, and run it	Getting started §3–4
3	Learn your way around what was generated	Getting started §5
4	Turn it into your application:
	with a coding agent	Building with an LLM
	by hand, in Vex	Coding in Vex
	when it needs a view of its own	Building a custom view and Making it move
5	Check it the way a person would, with `ottermate`	Getting started §7, and the ottermate guide
6	At the end of each milestone, read it back and write down what it showed	Looking back at a milestone
7	Build the executable and give people a one-line installer	Shipping it

Steps 4 to 6 repeat once per milestone. Most people do step 4 both ways: an agent for the large, well-described changes, and an editor for reading what it wrote and for the small fixes that are quicker to make than to explain.

What the template gives you

The template, vexel-desktop, does not generate an empty window. It generates a small but complete text editor: tabs, a file navigator, Markdown in colour, a question before closing with unsaved work, and a session that comes back the next time. An editor is the smallest real application that reaches every part of the framework, so the project starts out showing you how each part is done. You keep its shape and replace what it does.

Vex, Calculator, MainFrame and Scheduler all started as this template. Their source is the best guide to what a generated project grows into:

Application	Read it for
text-editor-vexel-demo	Grammars and highlighting off the GUI thread, the OS file dialogs, a second mode of the same panel
calculator-vexel-demo	A computation engine behind a small window, and plots drawn on the canvas
mainframe	A native process (ConPTY) behind the window, and workspaces
`vexelray-scheduler` (not yet published)	A view of its own (lanes of bars placed on a timeline), and motion: nothing on screen changes in one frame

Where to ask

Something did not build, a step here was wrong, or the framework is missing something you needed: open an issue. Your project’s docs/framework-notes.md is where you write down each gap as you find it, so when you report one you will already have written it up.