Settings Doctor (color self-heal and reset)

The Settings Doctor is a lightweight check that runs automatically every time the app opens. It looks for color-related problems in your settings and tries to fix them before you ever notice anything is wrong.

What the Doctor checks

Right after the app finishes loading, the Doctor runs two checks:

1. Missing color variables — The app paints itself using a set of CSS color values derived from your chosen color scheme. If any of those values failed to apply (for example, a theme was interrupted mid-apply on a previous session), the Doctor detects the gap and re-applies your appearance settings to restore them.

2. Unknown color scheme name — Only one color scheme name is registered: default, which owns both a light and a dark mode. If your .zudotext.settings.json references anything else — for example default-dark / default-light from before the dual-mode restructure, or a name that was simply renamed or removed — the Doctor resets the colorScheme field to default and saves the updated settings automatically. This does not touch your ramp/mapping customizations in color; only the scheme name is healed.

Both checks happen in the background after the first paint, so they never delay the app from opening.

When the auto-fix works silently

Most of the time the fix succeeds without any visible sign. The app opens, the Doctor runs, detects the issue, corrects it, and you see your workspace with the correct colors. Nothing interrupts you.

When you see the toast

If the Doctor detects a problem it cannot fully resolve on its own, a brief notification appears at the bottom of the screen:

"Settings rendered incorrectly — open Settings → Color → Reset to defaults to fully recover."

This message means the app could not repair the color state automatically in this session. Your content and notes are unaffected — only the visual appearance is involved.

What to do when the toast appears

Open Settings → Color and click the Reset to defaults button at the bottom of the Color tab.

When prompted, confirm the reset. The button:

• Wipes any color customizations you made (custom palette tweaks, per-token overrides).

• Restores the default color scheme and all default CSS color values.

• Takes effect immediately — no restart needed.

If you had custom colors you want to keep, record the current ramp and mapping values before resetting.

Running the check manually

The Doctor also runs on demand. Open the command palette (Mod+K) and search for:

Settings: Run diagnostic and repair

This command (in the General category) runs the same boot-time check immediately and applies any available fixes. It is useful after manually editing .zudotext.settings.json, recovering from an unexpected quit, or any other time the colors look off but no toast appeared.

There is no default keyboard shortcut for this command; you can assign one in Settings → Shortcuts if you use it frequently.

What the Doctor cannot detect

The Doctor is focused on color appearance. It does not detect every possible kind of settings problem.

Specifically: if your .zudotext.settings.json file is truncated, has a parse error, or is otherwise unreadable, the Rust backend silently substitutes defaults for the affected sections when it loads the file. The Doctor never sees the file directly — it only sees the already-loaded, already-defaulted settings. So a corrupted or incomplete file will not trigger the toast or any warning.

The manual "Reset to defaults" button in Settings → Color is your escape hatch for this class of problem as well. It brings the color section back to a known-good state regardless of what happened to the file.

Last resort: reset the settings document from another client

If the Settings dialog itself is inaccessible and the app is genuinely stuck, you can overwrite the settings document from another client and let the stuck app pick up the repaired state.

Your settings are a workspace document at .zudotext.settings.json in the workspace root, not a file on your machine — so this is not something you can fix in Finder, and no client exposes a way to delete the document outright. Instead, from any client that can still open the workspace (another device, or the web editor), open Settings → Raw Settings and replace the JSON with a known-good copy — or with {}, which the sanitizer expands back to full defaults when you Apply (it will warn about the adjusted sections; confirm to proceed).

Be aware that the replacement syncs: the settings document is shared by every device signed into that workspace, so all of them pick up the new contents, not just the stuck one. If you reset to defaults you lose custom shortcuts, color tweaks, and other Settings changes everywhere.

If a single machine is misbehaving while the others are fine, suspect a device override rather than the shared document — overrides are per-device and are the more likely culprit.