Test and diagnose

When something fails, establish four independent facts: selected source, declared contract, local runtime, and visible/callable surface. One green step never implies the others.

Quick triage

Symptom	First commands	Likely layer
Scaffold missing files	Re-run `create`; `find` tree	Package source
"Failed DSL validation"	`arc dsl validate <dir>`	AUP/DSL sources
`format_changed` on lint	`arc dsl format --write <dir>`	Formatting only
Profile check fails	`arc blocklet check --profile <recipe>`	Missing recipe assets
Port already in use	Named instance (auto port) or `--port`. Do not `stop` a seed daemon you did not start	Local daemon
No blocklet found at path	Ensure `blocklet.yaml`, `.aup/`, or convention entry	Discovery
HTTP not 200 / blank host	Use printed `Host` / `?blocklet=` URL	Routing
Build ok, page wrong	Browser accept + source path check	Surface, not package zip
Stateful write fails	Confirm `/instance` binding; not seed-only	Instance data
Remote publish fails	Auth, secrets, network — see publish page	Release path

Diagnostic recipes

1. Package identity

arc blocklet inspect ./my-app
arc blocklet list .
cat ./my-app/blocklet.yaml

Confirm id, did, version, and that you are looking at the directory you think you are.

2. Contract

arc dsl validate ./my-app
arc blocklet check ./my-app --profile minimal-app   # or basic
arc blocklet dev ./my-app

dev reports detected content type and convention mounts. It does not serve traffic.

3. Artifact

arc blocklet build ./my-app
# read the "instance:" line and file count
ls ./my-app/dist/.afs/manifest.json ./my-app/dist/blocklet.dist.json

4. Local surface

export ARC_INSTANCES_DIR=/tmp/arc-instances-demo
arc service start --instance demo --home /tmp/arc-home-demo --blocklet ./my-app
arc service url --instance demo --print url
# probe the printed host/port; do not assume 4900

Then open the same URL in a real browser. Check console errors if the shell loads but content does not.

5. Service status

arc service status --instance demo
arc service stop --instance demo    # only if this is your temporary named instance

Failure modes seen on `2.0.0-beta.28`

Observation	Evidence	Documentation stance
`arc blocklet run` errors with port in use	Seed port 4900 occupied	Named instance (auto port) or explicit `--port`. `ARC_SERVICE_PORT` only affects the seed instance
`arc dsl lint` fails on fresh `minimal-app` with `format_changed`	Scaffold emits unformatted DSL	Document `dsl format --write`; do not treat as broken recipe alone
`arc deploy <path> --publish` without snapshot secret	Error: Snapshot V2 requires `AFS_DID_SPACE_SNAPSHOT_SECRET` (or scope secret)	Document as local-publish prerequisite — not a Blocklet source bug
`arc deploy <path>` daemon register returned `missing 'dir'` in one isolated trial	CLI posts parent dir to `/api/blocklets/dirs/add`	Prefer `blocklet run` / `service start --blocklet` for local accept; treat bare `deploy` register as environment-sensitive

What not to conclude

Evidence	Invalid conclusion
`check` passed	Users saw the correct page
`build` passed	Remote deploy works
Local HTTP 200	`/instance` writes and auth flows work
Historical product name in a path	Feature parity with that product

CLI man page: arc blocklet
AFS inspection: Local inspection
Web Device diagnose patterns: Web Device board publish/diagnose pages