Project Anatomy

An Embedr project is an ordinary folder. embedr.yaml at its root marks it as a project and tells Embedr which parts it has. Everything else is plain files you can open in any editor, track with Git and move between machines.

A complete project

A project created as Electronics + firmware that has grown a board, an enclosure and a plan looks like this:

plant-monitor/
├── embedr.yaml                 # project manifest
├── platformio.ini              # firmware build environments
├── .gitignore
├── src/
│   └── main.cpp                # firmware entry point
├── include/                    # optional headers
├── lib/                        # project-local libraries
├── pcb/
│   ├── pcb.toml                # PCB workspace settings
│   ├── main.zen                # schematic source
│   ├── .gitignore
│   └── layout/
│       ├── layout.kicad_pcb    # board layout
│       └── layout.kicad_pro    # KiCad project and design rules
├── mechanical/
│   ├── enclosure.cad.json      # mechanical design manifest
│   ├── enclosure.py            # generator source
│   ├── imports/                # STEP and other files designs import
│   └── assembly/
│       └── enclosure-v1.json   # assembly guide
├── specs/
│   └── plant-monitor.md        # Plan Mode spec
└── .embedr/                    # Embedr's local project state

No project has to contain all of this. Each part appears when you or the agent create it.

What each project type starts with

Created as	Files
Electronics + firmware	embedr.yaml, platformio.ini, src/main.cpp (or main.c), lib/, .gitignore, and the pcb/ workspace
Electronics only	embedr.yaml (with project.kind: electronics), .gitignore, and the pcb/ workspace
Import KiCad	An electronics project whose pcb/ holds Zen sources converted from your KiCad design
Open Folder / Clone Repository	Your existing files. If there is no embedr.yaml, click Initialise Agent in the chat and the agent writes one without replacing your source.

New projects go to ~/EmbedrProjects/<name>/. Names keep letters, digits, - and _.

The firmware entry file depends on the target's framework:

Framework	File	Entry point
Arduino	src/main.cpp	setup() and loop()
ESP-IDF	src/main.c	app_main()
Zephyr	src/main.c	main()
Mbed	src/main.cpp	main()
STM32Cube, CMSIS, libopencm3, SPL	src/main.c	main()

embedr.yaml

The manifest names the project and describes its firmware target, custom build commands and component list. A new Arduino Uno project starts with:

manifest_version: 1
name: plant-monitor
version: 0.1.0
board:
  platform: atmelavr
  board: uno
  framework: arduino
build:
  build_flags: []
  lib_deps: []
  monitor_speed: 115200
components: []
connections: []

Embedr adds to it as you work: picking a target writes a capabilities.firmware block, processing a datasheet adds a datasheets list, and sharing the project adds a project.id. See Project manifest for every field.

Firmware: platformio.ini, src/, include/, lib/

Firmware builds use PlatformIO. platformio.ini holds one [env:...] section per build environment, and default_envs names the one the toolbar selects:

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

[platformio]
default_envs = esp32

Picking a target in the toolbar adds or updates its environment here. Target Settings (upload speed, monitor speed and so on) are written into the active environment. You can also edit the file by hand; Embedr reads it as the source of truth for PlatformIO projects. See Targets and environments.

• src/: your firmware sources.
• include/: headers, if you keep them separate.
• lib/: libraries that belong to this project. Libraries from the PlatformIO registry go in lib_deps instead. See Dependencies and libraries.
• .pio/: created by the first build. It holds downloaded libraries and build output, and is ignored by Git.

Projects that build with Make, CMake, Zephyr west or another tool instead of PlatformIO declare their commands in embedr.yaml; see custom firmware actions.

Hardware: pcb/

The pcb/ folder is the electronics workspace.

File	Purpose
pcb.toml	Workspace settings, including which .zen file is the board ([board] path)
main.zen	The circuit in Zen, Embedr's hardware description language. The Schematics tab draws it. A new workspace starts with Board(name="main", layout_path="layout", layers=2).
Other .zen files	Modules and sub-circuits the board imports
layout/layout.kicad_pcb	The board layout, generated from the schematic and then placed and routed. Open it in the Board tab or in KiCad.
layout/layout.kicad_pro	KiCad project settings, including the design rules for your fabricator
.pcb/	Build cache for the PCB tools. Ignored by Git.

Larger projects can keep boards in subfolders (for example pcb/boards/main/); pcb.toml says which one is active. See Schematics and PCB and Board and KiCad.

Next to the board file, Embedr keeps a .embedr-board/ folder with check results, cached 3D models, generated documents (deliverables/) and manufacturing readiness. It is regenerated as needed and ignored by Git. Fabrication files you export for ordering are described in Manufacturing and ordering.

Mechanical: mechanical/

Path	Purpose
mechanical/<design>.cad.json	The design manifest: name, parameters (with units and limits), assumptions, checks, and the board or files it builds around
mechanical/<design>.py	The generator that builds the 3D model
mechanical/imports/	STEP, STL, DXF, image and other files a generator reads, or an imported STEP model used directly
mechanical/assembly/<guide>-v<N>.json	Step-by-step assembly guides. Each new version is a new file; older versions are kept.

Built revisions of a design (STEP, previews, drawings) are stored with your account, so the Mechanical tab can show history without filling the project folder. See Mechanical design.

Plans: specs/

Plan Mode keeps one Markdown spec per plan under specs/, with the intent, requirements marked confirmed, assumed or open, decisions, what is out of scope and the build plan. It is the only place the agent writes while in Plan Mode. Commit specs alongside the code they describe. See Plan Mode.

Embedr's local state: .embedr/

.embedr/ in the project holds state Embedr and the agent keep for this project:

Path	Contents
.embedr/datasheets.json	The list of datasheets processed for this project
.embedr/component-assets.json	Where installed component symbols, footprints and 3D models came from
.embedr/agents/	Your own helper profiles for this project. See Helpers.
.embedr/agent-artifacts/	Files the agent saved for itself, such as long pasted requests or backups it made before an edit

The default .gitignore ignores all of .embedr/. If you want teammates to share helper profiles or the component provenance file, add exceptions:

.embedr/
!.embedr/agents/
!.embedr/component-assets.json

Chat threads are not in the project folder. On desktop they live in ~/EmbedrProjects/.embedr/<project-name>/, outside every project.

What to commit

Commit:

• embedr.yaml, platformio.ini, src/, include/, lib/
• pcb/ sources: pcb.toml, .zen files, layout/*.kicad_pcb, layout/*.kicad_pro, and any .kicad_dru rule files
• mechanical/: manifests, generators, imports/ and assembly/
• specs/ and your own docs

Leave out (the default .gitignore already does):

• .pio/, .pcb/, .embedr/, .embedr-board/
• KiCad local files: *.kicad_prl, *.lck, fp-info-cache, *-backups/, *.bak
• .env files (.env.example and .env.template are kept)
• Editor and OS files: .vscode/, .idea/, .DS_Store
• build/, dist/, out/, node_modules/

When you share a project, Embedr also skips secret-looking files and anything your .gitignore excludes. See Sharing projects.

Managed and linked projects

The home screen tracks two kinds of project:

Kind	How it got there	Rename on the home screen	Trash button
Managed	Created by Embedr in ~/EmbedrProjects/	Yes (Rename project)	Delete project: deletes the folder from disk. This cannot be undone.
Linked	Open Folder on an existing folder	No	Remove from Embedr: removes it from the list. "The folder will stay where it is on disk."

Either way, removing a project from Embedr also deletes its chat history. Commit or copy anything you need first.

In the browser, projects are cloud copies rather than folders. See Embedr in the browser.

Older projects

Projects from early versions of Embedr have a root .ino file and no embedr.yaml. The toolbar shows Migrate Project ("Migrate legacy .ino project to embedr.yaml") for them; Compile and Flash are hidden until you migrate. Migration creates embedr.yaml and a src/ layout PlatformIO can build. Commit first so you can review the change.

Older projects may also have a datasheets/ folder with converted Markdown datasheets, or an .embedr_chat/ folder of old chat transcripts. Both are safe to keep.