Concepts¶

This page groups the core concepts used by the STM32Cube for Agentic AI installer.

Cube bundle model¶

The installer uses cube to install and manage STM32Cube Agentic Context bundles. Some contexts require Cube tool bundles, which cube installs automatically.

Installer commands install contexts on the machine and deploy selected context files into projects.

Context bundle vs tool bundle¶

The installer distinguishes two bundle roles:

Context bundle:
- Carries agent-facing artifacts (skills, agents, instructions, prompts, MCP wiring, routing inputs).
- Contains the context capabilities selected for project deployment.
Tool bundle:
- Carries an executable or tool runtime used by one or more contexts.
- Is usually consumed as a dependency rather than directly deployed by installer workflows.

Context bundle names follow the cube-agentic-ai-<connector> pattern. For example, the STM32Cube Build Context uses cube-agentic-ai-build, and the STM32CubeProgrammer Context uses cube-agentic-ai-programmer. The installer tracks context-owned project files for updates and removal.

In machine discovery output:

Context bundles managed by installer workflows are classified as IN_SCOPE.
Tool bundles required directly by installed contexts are classified as DIRECT_AI_DEPENDENCY.
Unrelated bundles remain OUT_OF_SCOPE.

Context bundle commands¶

Each context bundle provides commands to show its purpose, version, and available services.

Recommended commands:

--help: short purpose and usage summary.
--version: installed context bundle version.
--list-ai-services: machine-readable service catalog in JSON.

The --list-ai-services output is the most useful command for deployment planning because it declares, per service:

identifier: stable service identifier used by service-selection workflows (for example project add service selection).
name: service name used in routing catalog generation.
description: user-facing description of the service intent.

Service identifiers such as S1 belong to one context bundle. The same identifier can mean something different in another context. Inspect the installed version’s output before making an interactive service selection:

cube cube-agentic-ai-esw --list-ai-services

The embedded-software context guide in the toolkit user documentation maps its service IDs to user-facing capabilities. A project’s service lock records the selections already deployed there.

Example:

{
  "services": [
    {
      "identifier": "S1",
      "name": "st-docs.source-discovery",
      "description": "Find the right official ST document and return source-grounded identifiers and locations."
    }
  ]
}

Why a context may install a tool¶

Some contexts use STM32Cube tools packaged as separate bundles. In that case, the context bundle declares the tool dependency.

When you install the context, the cube bundle manager resolves and installs that dependency automatically. This is expected behavior, not a side path.

Consequences:

You do not need a separate installer command for that tool bundle.
Project lock state records both context and resolved tool bundle versions.
Reproducibility includes the context and its required tool bundles.

Scope limitation:

Automatic installation covers only dependencies declared by the context bundle. Tools required by its skills but not declared as bundle dependencies must be installed separately. Consult that context’s prerequisites.
This applies only to tools delivered as Cube bundles.
Tools not packaged as Cube bundles (for example IDE distributions or required editor extensions) are outside installer scope and must be installed independently.

Version management and SemVer¶

Bundle versions follow semantic versioning (SemVer).

You can:

Pin an exact version, for example cube-agentic-ai-esw@<version>.
Select versions through ranges when supported by the bundle manager and context dependencies.
Use presets or lock state to replay an exact environment.

In practice:

machine-install accepts a bundle reference with an optional version.
project-add accepts a bundle reference with an optional version.
project-deploy --preset can replay exact versions exported from an existing project.

The current installer catalog uses minimum-version ranges (>=) for its nine connector bundles, with no upper bound. Later major versions can satisfy these ranges. The required installer bundle, which carries the housekeeping and doctor skills, is pinned to the exact installer version: the installer never updates itself. Run cube agentic-ai show-catalog --short false to inspect the catalog shipped with your installer. machine-bootstrap enforces these catalog requirements, but does not proactively upgrade an already compliant version unless --upgrade-installed-in-range true is requested. Deployment with an unpinned bundle name instead reuses the highest installed semantic version, unless --bundle-version-policy lock-driven selects the project-locked version.

Machine install vs project deployment¶

The installer separates machine scope and project scope.

Machine scope:

Installs context bundles once on the machine.
Reuses installed bundles across multiple projects.

Project scope:

Deploys selected context files into one project top folder.
Wires files for the selected IDE and agentic AI system (or canonical layout).
Maintains project lock state and merged MCP/routing artifacts for that project.

One machine install can serve many projects, but each project must be explicitly deployed.

Requirements of a context¶

A context bundle declares in its services.json (schema 3.1.0 and later) what its services need to work, beyond the Cube tool bundles that it depends on. The installer checks them with doctor and, during setup, resolves what it can.

Only setup and doctor look at these requirements. machine-bootstrap, machine-install, project-add, project-deploy and project-deploy-installed install and deploy contexts without checking or resolving them, so a context added or updated with one of them can lack its Python packages or its tool bundles. Run cube agentic-ai doctor <project_top_folder> --fix after them. It resolves the dependencies and reports the rest.

Kind	Meaning	What the installer does
`prerequisite`	Something the user must ensure, for example a program on the machine.	Reports the remediation text and link. Never acts on it.
`dependency`	Something the installer can resolve: a Cube bundle, a Python package, an extension.	Resolves it with the bundle-declared resolution (`setup`, `doctor --fix`). VS Code extensions are listed as manual by checks because a terminal cannot see the active profile. By default, the agent or user runs the commands; `setup --install-vscode-extensions` is the opt-in that runs `code` for the declared extensions.

A requirement applies to the services that it declares, or to all services of the bundle. An unmet prerequisite that covers all the services of a dependency blocks that dependency. The services concerned are reported as blocked in data.blockedServices. The overall readiness is READY, CHECK_MANUALLY (some checks cannot be done from a terminal) or ACTION_REQUIRED.

The eSW context declares Python 3.10 or later for HAL/LL guidance. See Python of the eSW context.

Build and debug-DAP both declare ides: ["vscode"]. The command setup leaves them unavailable for targets other than VS Code. Build declares stmicroelectronics.stm32-vscode-extension. Debug-DAP declares that extension plus ozzafar.debugmcpextension (DebugMCP). A terminal cannot see whether an extension is installed in the active VS Code profile, so read-only doctor reports these checks as manual. doctor --fix --vscode-profile "<name>" verifies the named profile and installs missing declared extension dependencies there. Without an explicit profile, --fix leaves extensions manual. Existing extensions are not updated, and unavailable profiles are not created. setup reports the install command for the selected profile. With --install-vscode-extensions, it runs code for the declared extensions in the Default profile or each --vscode-profile. Otherwise the agent or user runs the commands or uses the Extensions view. Reload the VS Code window after the first installation. DebugMCP is required for debug tools and for flashing through the Programmer context in a project containing debug-DAP. A context can also declare the IDE it needs (ides in services.json, and the catalog entry). A context that needs VS Code is not deployed for another IDE target, and setup and doctor report it as unavailable instead of failing the others.

Python of the eSW context¶

The eSW context runs Python scripts. HAL/LL guidance (service S2) needs Python 3.10 or later, found as py -3, python3 or python. HAL project migration is not delivered in this release. If a selected service declares additional Python packages, setup and doctor --fix can install them into the Python chosen for the project. The installer never installs Python itself.

setup --python makes the choice when setup creates the project:

`--python`	Python environment used by the eSW context
`auto` (default)	The Python found as `py -3`, `python3` or `python`. If that Python is a virtual environment or is managed by the operating system, the environment of `venv` is used instead.
`venv`	An environment inside the installed eSW bundle version, `cube-agentic-ai-esw/<version>/pybin/.venv` in the bundle installation directory (`cube --get-current-value CUBE_BUNDLE_PATH`). No other Python is changed.
`"<absolute path>"`	That Python executable, 3.10 or later.

The choice is saved in the project, one file per eSW version: .cube-ai/esw-python/cube-agentic-ai-esw@<version>.json. venv and a path are saved when the installation starts, even if pip then fails. The auto choice is saved once the packages are installed, as the Python it used. The command doctor --fix and the HAL/LL guidance scripts use the saved choice. The command doctor has no --python option. The file is not in a project lock and is not meant to be committed.

Important

The choice is made once. setup refuses a project that is already deployed (SETUP_PROJECT_ALREADY_DEPLOYED), so no installer command changes the Python of a deployed project.

Each project has its own choice. Projects that choose venv for the same eSW version share its environment. An environment belongs to one eSW version. When a project moves to another eSW version, that version has no choice file yet and starts from the project’s most recent one: a project on venv stays on venv, with the environment of the new version.

Update eSW from version N to N+1 in a project that uses venv:

cube agentic-ai project-remove cube-agentic-ai-esw <project_top_folder>. The choice files stay in .cube-ai/esw-python/.
cube agentic-ai project-add cube-agentic-ai-esw@<N+1> <project_top_folder> --services all, with the --ide and --agentic-system options of the project. N+1 is deployed, but its declared requirements have not been checked by project-add.
cube agentic-ai doctor <project_top_folder> --bundles cube-agentic-ai-esw --fix. It checks the new version’s requirements using the saved Python choice and applies available fixes. Inspect data.readiness, data.fixes[], and data.nextSteps. A Python prerequisite can require manual action. Package installation applies only when a selected service declares packages.

When a newer eSW version is installed on the machine, doctor gives these three commands, ready to paste, with the warning NOT_LATEST_MACHINE_VERSION. If step 3 reports unmet requirements, follow its remediation, then run step 3 again. For Python, check the interpreter version and path. If declared packages fail to install, check pip’s proxy, certificate, and timeout settings. The environment of N stays in the bundle installation directory until N is removed from the machine with cube bundle remove cube-agentic-ai-esw@<N>, once no project uses it.

The same doctor --fix also creates the environment again when the eSW version was removed from the machine and installed again, or when the Python that created it was uninstalled (install Python 3.10 or later first if no other one is left).

Lock files and reproducibility¶

Two lock files provide reproducibility:

.settings/bundles-lock.store.json (project top folder)
- Owned by the cube bundle manager, shared with any other Cube-aware tool (e.g. an IDE).
- Records resolved bundle versions, including dependencies.
.cube-ai/services-lock.json
- Owned by the installer.
- Records deployed context bundle versions, selected services, and effective deployment target.

project-lock-show returns a machine-readable state that can be reused as a preset for project-deploy --preset.

Orchestration catalog¶

During project deployment, the installer assembles a routing catalog used by the agentic AI system.

Current feature level:

The cube-agentic-ai-routing skill contains the catalog of services declared by contexts deployed to the project.
The default usage-router mode generates the catalog without overlap arbitration.
Pass --routing-mode usage-router-with-arbitration to opt in to arbitration when context responsibilities overlap.
This skill is the authoritative routing source for STM32/STM32Cube/STM32 AI requests.
Proper routing requires the agentic system to invoke it before planning or tool selection.
The deploy commands expose a host-instruction update payload that asks to enforce this behavior in the host instruction layer.
It is regenerated whenever deployment state changes (project-add, project-deploy, project-deploy-installed, project-remove).

The generated entry point depends on the deployment target:

Target	Routing skill entry point
GitHub Copilot	`.github/skills/cube-agentic-ai-routing/SKILL.md`
Claude Code	`.claude/skills/cube-agentic-ai-routing/SKILL.md`
Canonical layout	`.cube-ai/skills/cube-agentic-ai-routing/SKILL.md`

CMake build guidance without the Build Agentic AI context¶

When the Build Agentic AI context is not deployed to the project, the routing skill gains a short section, CMake build without the Build Agentic AI context. It is guidance, not a service, and does not override other installed connector skills, security policies or user approval requirements. It tells the agent that it may configure and build a CMake project with its presets, but must first check which arm-none-eabi-gcc will run and its version, instead of using the first compiler found on PATH. The toolchain file name in a preset, such as GCC.14.3.1.cmake, states an intended version and does not select a compiler. The agent reports any difference and asks before building, and it checks the compiler recorded in the CMake cache when it reuses a build directory.

The section is absent when the Build Agentic AI context is deployed, because its skills then govern builds. It is regenerated with the routing catalog.

STM32Cube user-journey skill¶

When the STM32CubeMX2 context (with CMake generation) and the build context are both deployed, the installer also generates the optional skill cube-agentic-ai-user-journey-mx2-cmake-build beside the routing catalog. It keeps separate requests consistent, from project creation to CMake generation, build, and debug:

The .ioc2 file and the generated CMake project are placed at the folder opened in VS Code by default.
A request can cover several phases in one turn. The agent completes only the requested phases, in order, after checking their prerequisite gates. Peripheral, pin, clock, or middleware changes to an existing project use the routing catalog alone and do not trigger journey gates.
Connector skills own each phase’s destination, format, checks, and approval rules. They take precedence over the journey guidance.
Before building, the CMake project must be cubified by the STM32Cube for VS Code extension. The agent asks you to run Developer: Reload Window from the Command Palette, then checks the .settings/ and .vscode/settings.json entries written by the extension.
For a single-phase request, the agent performs only that phase and tells you which constraints keep the later phases possible. If you choose another location, it is respected, and the agent explains the consequence for build and debug.
Debug steps are included only when the DAP debug context is also deployed.
Before building, the MX2 generation check must report CMake output at the workspace root, and the extension-generated cubification metadata must be present. The agent does not create that metadata itself or install missing bundles or extensions on the user’s behalf.

The skill is regenerated with the routing catalog and removed when either required context is removed. It is not recorded in services-lock.json.

Additive deployment behavior¶

project-add and project-deploy are additive primitives:

A successful run applies the requested deployment on top of current project state.
Deploying a smaller service subset after a larger one does not remove previously deployed services.
Use project-remove to explicitly remove services or a context from the project.

This additive behavior also applies to service selection in services-lock.json: newly selected services are merged with existing ones until removal is requested.