File formats — Docs

The rules

Plain files only. The most a file does is grow while it records — a stream's records.jsonl, its media file, a run's members.jsonl. There are no hidden databases, pointer files or bundles.
References are paths and ids. A run uses the asset at its path now; nothing pins a hash.
The folder is the project. Nothing about a project's layout is hard-coded into the workbench.
Levels. Every definition, world and setting can exist in the cloud or locally, at the global, user and project level, and they merge from broad to specific.

Devices

devices/<id>/definition.tsx, with its assets beside it in devices/<id>/assets/ (for example model.glb). A definition is code: the workbench runs it and reads the <device> it declares.

A definition names the machine (name, manufacturer, model_number, product_url …), its 3D model, and its channels:

tsx

export default () => (
  <device name="CNC 3018" manufacturer="…">
    <channel id="gcode" dir="duplex" medium="records" format="gcode-chat" dialect="grbl" transport="serial" baud={115200} />
  </device>
);

dir is in, out or duplex; medium is records, video, audio or bytes. A unit in a world can override a channel.

Worlds

worlds/<id>/world.tsx, code that declares one <world>:

tsx

export default () => (
  <world name="Shop floor" kind="physical">
    <space origin_mm={[0, 0, 0]} size_mm={[6000, 4000, 3000]} />
    <unit uid="mill-1" name="Mill" device="../../devices/cnc-3018/definition.tsx" position={[1200, 800, 0]} rotation={0} />
  </world>
);

Each edit in the workbench is written back into the code as the smallest change.

kind is physical or simulation. A world may name a 3D scene (model, a .3d.tsx) and, if it is a simulation, a simulation file (sim, a .sim.json). A world is not a 3D model, and a run is not a world.

Runs and streams

runs/<run>/ is one run in one world:

file	holds
`run.json`	`id`, `world`, `kind` (`session`, `recipe` or `thread`), `started`, `ended`, `from` (the run and time it was forked from)
`members.jsonl`	who and what took part, appended as they join
`steps.jsonl`	a recipe's steps
`streams/<uid>.<channel>/`	one stream: `stream.json` plus its data — `records.jsonl`, or one `video.webm`/`.mp4`, `audio.webm`/`.mp4`, or `data.bin`
`streams/chat/`	a thread's conversation
`streams/sim/`, `streams/sim-input/`	a simulation's frames and the inputs applied to it
`evidence/`	files kept as evidence

A record is one line of JSON:

json

{ "t": 7.180, "seq": 41, "src": "operator", "kind": "note", "text": "agent:night-shift: run_program", "by": "agent:night-shift" }

src is device, sim or operator; kind is command, event, ack, reply, state, evidence or note; seq strictly increases. An unknown state is written { "kind": "state", "status": "unknown" }.

Documents

Each editor document is one JSON file — { "format": "commandagi-document", "kind", "title", "meta", "body" } — with large assets in a <name>.assets/ folder beside it.

extension	opens in
`.3d.tsx`	3D design (parts, assemblies, scenes)
`.cam.tsx`, `.slice.tsx`	3D design in CAM and slicing mode; programs are saved beside them as `.gcode`
`.nest.tsx`	the vector app's nesting mode (laser and sheet jobs), in code
`.draw.tsx`, `.paint.tsx`, `.img.tsx`	drawing, painting and image editing, in code; pixels stay image files beside them
`.vid.tsx`	the video editor, in code; media stay files beside it
`.mus.tsx`	music, in code
`.geo.tsx`	geoeconomics workspaces

Other formats

file	what it is
`<name>.sch.tsx` + `<name>.pcb.tsx`	a circuit in code: the schematic, and its board that names it
`<name>.sheet.tsx`, `<name>.page.tsx`, `<name>.deck.tsx`	a workbook, a page and a slide deck, written as code: the sheets, docs and decks editors write each edit into the file
`<name>.sim.json`	a simulation
`<name>.trials.json`	an experiment: many simulated runs over a parameter sweep
`<name>.graph.json`	a graph (knowledge, memory)
`<name>.dashboard.tsx`	a dashboard in code: panes and the files they show
`<name>.geo.tsx`	a geoeconomics project in code
`<name>.opgraph.tsx`	a node graph in code
`<name>.task.tsx`, `<name>.project.tsx`	a task and a project, in code
`<name>.market.jsonl`	a market's tape, book, orders and positions
`calendar/<calendar>/<event>.ics`, `contacts/<email>.vcf`	calendars and contacts
`.xlsx`, `.md`, `.pdf`, `.ipynb`, `.gcode`, `.step`, `.stl`, `.glb` …	opened as they are, in the editor for their kind

Settings

Settings are VS Code–style settings.json files (comments allowed), one per level, merged from broad to specific: the cloud and local global levels, your organizations, your account, then this computer (~/.commandagi/settings.json) and this project (.commandagi/settings.json).