> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure EMBEDDER.md
> Run /init to discover project workflows, verify them with five required questions, and maintain the root EMBEDDER.md guide with rules and commands.
`EMBEDDER.md` is the project guide that Embedder adds to the agent's instructions. Keep it at the repository root. It records the hardware target, exact developer commands, project rules, and safety constraints that source code alone cannot establish reliably.
Run `/init` to create the file or refresh its generated section:
```text theme={"system"}
/init
```
## What /init discovers
`/init` switches the session to Act mode and starts with read-only discovery. When a background discovery snapshot is available, the agent reuses it and inspects only missing, conflicting, or truncated evidence.
Discovery can include:
* repository structure, README files, build manifests, CI workflows, and debugger launch files;
* the MCU, board, SDK or RTOS, toolchain, build system, commands, and output artifacts;
* repository instructions such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, formatter settings, and analyzer configuration;
* selected platforms, peripherals, parsed schematics, and indexed hardware documents;
* serial, RTT, ITM, xSCOPE, debug probe, bridge, and supported bench-instrument status;
* `.embedder/mcp.json`, `.embedder/lsp.json`, `.embedder/models.json`, project skills, memory, and reusable hardware scripts;
* coding-standard, compliance, generated-code, vendor-code, and report requirements.
The flow may use non-mutating executable checks such as `command -v`, `which`, or `where`. Finding an executable proves only that it exists. It does not prove that a build, test, flash, or debug command works.
Default discovery does not authorize dependency installation, a build, programming a target, live hardware control, catalog changes, a full compliance scan, or product-code edits. The flow must ask before any optional validation action with those effects.
## Verify the detected setup
Before any write to `EMBEDDER.md`, the agent must call the question tool and wait for your answers. The first checkpoint contains exactly these five headers, in this order:
1. **Target hardware**
2. **Build & test**
3. **Debug & deploy**
4. **Bench & integrations**
5. **Quality & rules**
Each question shows two to four selectable choices. The detected recommendation appears first, and every question includes a **Not sure — guide me** path. You can use custom text to correct a detected value, but the default path does not require typing.
The checkpoint separates recording a workflow from running it. For example, you can confirm a build command without authorizing the agent to execute it. If an answer leaves a material conflict unresolved, the agent asks another batch before writing.
File tools enforce this checkpoint. They reject a write or edit to `EMBEDDER.md` until all five required areas have an answer.
## Optional validation
After the checkpoint, `/init` runs only the validation actions you selected.
For a build or host test, the agent runs the exact discovered command and checks the expected artifact or output. If it fails, the agent asks whether to apply a stated recovery, use another detected setup, or record the workflow as unavailable.
Flash validation can start only after a successful build produced the expected image. The flow identifies the target, probe or bridge, MCU, artifact, power state, and exact command, then asks for the normal destructive hardware confirmation. It uses the dedicated flash tool so target arbitration, verification, reset, and early boot capture apply.
Debug validation checks the full path: server startup, target attachment, safe halt or breakpoint, state inspection, and a clean resume or disconnect. A debugger server that starts without attaching to the target is not a verified debug workflow.
## Generated file format
`/init` creates or updates one managed block:
```markdown theme={"system"}
...generated project guide...
```
Rerunning `/init` refreshes that block and preserves content you wrote outside it. Keep manual notes outside the markers because content inside the block is managed by the setup flow. The markers must each occur exactly once.
### Required compatibility fields
The generated block keeps these field names because runtime integrations read them:
```text theme={"system"}
# EMBEDDER PROJECT CONTEXT
Name =
Target MCU =
Board =
Toolchain =
Toolchain Path =
Debug Interface =
RTOS / SDK =
Project Summary =
build_command =
clean_command =
test_command =
lint_command =
format_command =
flash_command =
gdb_server_command =
gdb_server_host = localhost
gdb_server_port =
target_connection = remote
serial_port =
serial_baudrate =
serial_monitor_command =
serial_monitor_interactive = false
serial_encoding = ascii
serial_startup_commands = []
```
Do not rename these keys when editing the file manually. Use `unknown` only after discovery and your answers cannot resolve a required value.
### Project guide sections
After the compatibility fields, the generated block contains:
* **Architecture:** modules, execution model, memory layout, and generated-code boundaries.
* **Hardware and Peripherals:** target hardware, interfaces, pins, power constraints, and schematic or datasheet sources.
* **Debug and Bench Setup:** probes, transports, bridge targets, power setup, instruments, peer connections, safe limits, and reusable scripts.
* **Developer Workflows:** Build, Test, Flash/Deploy, Debug, Logs/Telemetry, and Hardware Validation.
* **Compliance and Quality:** standards, analyzers, exclusions, deviations, coverage, and report requirements.
* **Rules and Conventions:** enforceable coding, formatting, testing, review, documentation, and safety rules with their source paths.
* **Customizations and Integrations:** skills, MCP servers, LSP settings, memory, and optional setup.
* **Agent Safety Boundaries:** actions that require confirmation, forbidden operations, secret handling, and target-selection rules.
* **Open Setup Items:** unresolved facts that materially affect a workflow or agent behavior.
Each developer workflow records:
```text theme={"system"}
status = verified | user-confirmed | inferred | unavailable | not configured
prerequisites =
command =
expected_result =
evidence =
troubleshooting =
safety =
```
The statuses are exclusive:
* `verified` means the workflow succeeded during initialization or has existing CI evidence that you confirmed;
* `user-confirmed` means you confirmed it, but `/init` did not execute it;
* `inferred` means repository evidence supports it, but you did not confirm it;
* `unavailable` means an attempted workflow failed or a dependency is absent;
* `not configured` means no workflow exists.
## Edit the file safely
Keep `EMBEDDER.md` concise and specific. Put exact commands and observable results in it, not general advice that is already visible in the repository.
Never store credentials, tokens, private keys, or secret environment values in the file. Name the required variable or credential source instead.
When hardware differs between developer setups, record the intended target and the selection rule. Do not present every detected USB device as project equipment.
Changes made with Embedder's file tools refresh the project-instruction cache. If you edit the file with another program and the active session still uses old instructions, start a new conversation.