Skip to main content
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:

​
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:
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:
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:
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.
Last modified on August 24, 2026