Troubleshooting

Start with the exact release version, the command output, and any local validation evidence. Avoid mixing assets from latest and a versioned release directory.

For divergent prompts, templates, manifests, materialized output, or partially upgraded workspace metadata, use Upgrade prompt and template customizations before authorizing force or migration.

For legacy planning roots, interrupted repository transactions, or write-lock evidence, start with Migrate an existing workspace and Transaction and operational recovery. Do not manually rearrange .day-shift/ while diagnosis is incomplete.

The command is not found

Confirm that the installer placed the command directory on PATH. Open a new shell so startup files are reloaded, then run day-shift --help. If the installer reported a destination outside your current PATH, add that directory according to its output.

Checksums or manifest metadata do not match

Stop using the artifact. Download the archive or installer, manifest, and checksum file from the same exact /downloads/<version>/ directory, then verify again. Do not treat a mutable latest pointer as immutable evidence.

The wrong license is selected

Run:

day-shift license status --format json

Inspect the resolved user-local license path. Use --license-file <path> for a one-off check without writing configuration.

Managed reminder regions remain

First confirm that the installed license verifies and suppresses reminders. Then preview and apply cleanup:

day-shift license cleanup-reminders --dry-run
day-shift license cleanup-reminders

The CLI appears to need the website

Normal installed CLI behavior is local-first and offline-capable. Website access is needed for public downloads, purchases, signed-file delivery or recovery, and documentation—not for ordinary repository workflows.

Migration planning is blocked

Run day-shift workspace migrate --check --format json, then inspect every work unit and finding. Ambiguous Basic, Structured, or Governed classification needs an explicit mapping. Root-order or parent-local task-sequence collisions need new explicit selections. Unsafe paths, duplicate identities, incomplete pairs, or unsupported artifacts must be repaired or dispositioned before apply; do not bypass them with manual moves.

If a previously reviewed plan is stale, generate a new --plan result and reauthorize its exact planDigest. A changed file, destination-presence condition, mapping, or order invalidates the old apply decision.

A repository write lock exists

Do not delete .day-shift/state/write.lock. An active owner or unknown liveness means wait. Expiry alone is not proof that takeover is safe; a stale lock needs disproven owner liveness and matching retained transaction evidence. If the lock belongs to another transaction, stop and inspect both identities.

A transaction is incomplete

Preserve .day-shift/state/transactions/<transaction-id>/ and the command’s JSON result. Identify each target as before, intended, retired, missing, or diverged, and keep the returned recovery fingerprint. Choose only an action the owning command reports as safe: roll-forward completes verified intended writes, while restore replays verified before-bytes.

A live lock, stale fingerprint, diverged target, missing staged content, unsafe restore, wrong transaction kind, or conflicting recovery receipt is a no-write recovery rejection. Reinspect instead of retrying or cleaning state manually. After verified recovery, retain the sanitized receipt and rerun the relevant no-write status, plan, or review.

For account, purchase, entitlement, recovery, or promised response questions, use the website’s support entry point; those policies are not defined by this troubleshooting guide.