Common Mistakes

1) Forgetting backend prefix on install

Symptom:

• package lands in unexpected backend block, or
• install command fails validation.

Fix:

declarch install aur:bat
# or
declarch install bat --backend aur

2) Running sync directly on first setup

Symptom:

• unexpected changes, or confusion about what will happen.

Fix: always preview first.

declarch --dry-run sync
declarch sync

3) Backend configured but binary not installed

Symptom:

• errors like Package manager error: <binary> not found.

Fix:

declarch info <nameofthebackend>
// example
declarch info aur

Install missing binary or temporarily remove/disable that backend.

4) Editing KDL without validation

Symptom:

• parse error at sync/lint time.

Fix:

declarch lint --mode validate

5) Confusing config path vs state path

Symptom:

• editing one file while declarch reads another path.

Fix:

declarch info --doctor -v

Use the reported paths as source of truth.

6) Trying too many advanced flags at once

Symptom:

• hard to debug whether issue is from profile/host/modules/hooks.

Fix:

• start with plain declarch --dry-run sync
• add one flag at a time (--profile, then --host, then modules)