Generate, lint, and migrate

These commands answer different questions. A green command is useful evidence, but it is not a substitute for running the app in its intended renderer.

arc dsl format ./hello-aup --write
arc dsl lint ./hello-aup
arc dsl validate ./hello-aup
arc dsl generate ./hello-aup --check

Read each result correctly

Command	What it examines	Does it write?	What a green result does not prove
`format --write`	DSL source formatting	Yes	That the source is valid or runnable
`format --check`	Whether formatting would change files	No	That generated artifacts are current
`lint`	Authoring-level DSL problems	No	That the full app configuration and target renderer agree
`validate`	Parsed DSL/configuration semantics	No	That a browser/device presents the intended interaction
`generate --check`	Whether compatibility artifacts would change	No	That a source-first app must keep JSON on disk
`generate --write`	The same artifacts	Yes	That the generated app passed a runtime acceptance test

On a fresh minimal-app scaffold in ARC 2.0.0-beta.25, format --write rewrites three DSL sources. format_changed is the diagnostic from format --check when formatting would alter files; it is not the normal success result of the --write command.

Treat generated JSON as compatibility work

DSL-first apps can expose compatible JSON virtually. A project only needs physical JSON when a specific compatibility consumer asks for materialized files. Use the following decision order:

Keep the .aup source authoritative.
Run generate --check in CI or before handing the project to a consumer that expects generated files.
Run generate --write only when that consumer actually needs the physical artifact, then review the diff like any other derived output.
Do not delete a JSON-first app merely to make it look DSL-first; JSON remains a supported source form.

For an AUP app configuration, a present .aup/app.aup takes precedence. If it is absent, ARC can read .aup/app.json as source. If the DSL file exists but is invalid, ARC fails rather than silently falling back to old JSON. That makes an invalid source visible instead of masking it with a stale artifact.

Use a narrow migration loop

When converting an existing source, do not change source language, UI behavior, and deployment boundary in one step:

Format, lint, and validate the current source.
Generate in check mode and inspect what would differ.
Materialize only if a real downstream consumer needs it.
Run arc blocklet check for the declared profile, then run the blocklet locally and inspect the actual target.

See CLI diagnostics for the command boundary and Sources, artifacts, and JSON compatibility for loader priority.