Fixes and the beginner level

archec knows how to fix the mistakes a newcomer makes most. Each fix is a set of text edits computed from the checked model (src/fixes.ts); applied, its diagnostic is gone — the tests apply every kind of fix and check again.

Where the fixes are#

In VS Code: the light bulb on a diagnostic (Ctrl+. / Cmd+.). The first, preferred fix is the one Fix all and Auto Fix apply. Every diagnostic also has Explain [code], which opens what archec explain <code> says beside the editor.
archec fix <main.arche>: applies the preferred fix of each diagnostic, one per place, then checks again — until nothing more applies. It prints each fix and the diff. --dry-run writes nothing; --only unresolved,missing-unit limits it to those codes; style findings (archec vet) only with --vet.
The MCP server (archec mcp): the fix tool gives the fixes of each diagnostic as edits by line and column, so an assistant applies them rather than guessing; apply: true does what archec fix does.

What is fixed#

Code	The fix
`unresolved`	The closest name in scope, by edit distance: a part or port of that part for a link end, a definition, a type, a message, a state. Declaring the missing name is the second choice.
`unknown-property`	The closest property of that kind of declaration (removing it: offered, not applied).
`property-value`	The closest allowed value (`buffer smaple` → `sample`); a name where a text goes is quoted.
`missing-unit` / `bad-unit`	The time unit: `10` → `10ms`, `10sec` → `10s`.
`unknown-unit`	The closest unit of the catalog (declaring it: offered).
`direction`	The port's direction made to match what it does (`in` that sends → `inout`).
`link-direction`	The two ends of the link swapped — when that puts both on the right side; else the port made `inout`.
`wrong-side`	`buffer`, `depth`, `overflow`, `stale-after` moved from the `out` port to the one link that leaves it.
`duplicate`	The second one renamed (`cmd` → `cmd2`).
`missing-separator`	A `;` before the property glued to the Python.
`include-not-found`	The file created, empty.
`naming`	Renamed to the convention with every use (offered; the editor's rename also follows the Python; `archec fix --only naming` renames the model's uses).
`unused`	Removed (offered, not applied).
`no-system`, `empty-system`	A system with a part of each definition; a part, or a component and a part of it (offered, not applied).
`requirement-no-text`	`text "The system shall …"` to complete (offered, not applied).
`arche-body`	A Python body that says only what the action language says, written as a ```arche body: `self.state == "Ready"` → `state == Ready`, `await goto("Auto")` → `goto Auto`, `send(self.p, M(f=1))` → `send p M { f: 1 }`. Refused when the body does more (a list, a library call, a name the model lacks). A style finding: `archec fix --vet` or `--only arche-body` applies it.
`advanced`	`level full` in the project (offered, not applied).

A fix that guesses what to write, or removes something, is offered in the editor and left by archec fix: read it, then choose it.

archec fix never leaves the model worse: when the fixes of a pass add errors (a rename that misses a use), each one is tried on its own, and those that add an error are dropped.

In plain words#

archec check --beginner (or ARCHE_LEVEL=beginner, or the VS Code setting arche.level set to beginner) rewrites the common messages in plain words and lists what exists:

main.arche:14:11 error You used `cdm` but `b` has no port called that. Did you mean `cmd`? Its ports are: cmd, st. [unresolved]

The simple level#

A project can say how much of the language it uses:

project "Pump" {
  level simple
}

At level simple, completion offers the core of the core — system, component/part, port, links, fn, var, states, requirement, messages and types, include, tests — and their usual properties (a board's chip, driver and hardware among them, the project's uses). Everything else still reads and builds; a declaration beyond the simple set is a hint, advanced, saying to set level full to use it. With no level in the project, the VS Code setting arche.level decides: beginner is the simple level, expert (the default) everything.