Application Setup

Initialize your application for rngo by running:

> rngo init

This will create a .rngo directory, with a spec.yml file. This serves as a minimal simulation spec that you will now flesh out.

Simulation Spec

A complete simulation spec primarily defines entities, which model any logical dataset that your application interacts with.

For even a small application, modeling all those datasets would be tedious, which is why you should delegate this to an LLM.

The best way to do so is to first define a system, which models where your application maintains state, and from which entities can be inferred.

For example, if your application uses SQLite, you might add the following at .rngo/systems/sqlite.yml:

output:
  type: sql
import:
  command: sqlite3 db.sqlite
infer:
  context:
    description: sqlite schema
    command: sqlite3 db.sqlite '.schema'

Let's say that you're using Claude Code - you can ask it to infer the application entities by running:

> rngo infer prompt | claude

Claude will generate one entity per table in the SQLite database, and write each to a file in the .rngo/entities directory, e.g.:

> ls .rngo/entities
users.yml
posts.yml
comments.yml

You should commit everything in the.rngo/systems and.rngo/entities directories to source control. The next step is to run a simulation.

Simulation Output

Now when you run rngo sim, it will construct a spec based on the contents of the .rngo directory.

For any entity inferred from a system, the CLI will attempt to stream the data directly into the system, based upon its import.command configuration.

For entities not associated with a system, the CLI will write the data to files in a dedicated simulation directory, e.g.:

> ls .rngo/simulations/hLpmFg0qFW2idopyd8NAq
users.jsonl
posts.jsonl
comments.jsonl

The directory name is the ID of the simulation. It also contains metadata such assimulation.json, which is the API representation of the constructed simulation.

The.rngo/simulations directory should be ignored by source control - rngo init will configure this.

Next Steps

From here, you can iterate on your entity defintions. Go to any of these pages to learn how:

• Entity
• Stream
• System