Welcome and Onboarding Issues

The first launch is the most fragile moment in any vault product — multiple plugins loading at once, multiple settings being initialized, multiple pieces of data being written. This page is the troubleshooting flow for things that go wrong during or after welcome.

---

"Welcome doesn't appear at all"

The Celestial welcome should fire on first launch. If you're seeing the empty tab (or a generic Obsidian start state) without going through welcome:

Step 1 — Check That The Plugin Is Enabled

Settings → Community Plugins → make sure Celestial Plugin is toggled on.

If it isn't: toggle it on, reload Obsidian, welcome should fire.

Step 2 — Check That You Trusted Plugins

If you clicked "No" when Obsidian asked to trust the author and enable plugins, the celestial-plugin never loaded:

• Restart Obsidian
• The trust dialog appears again
• Click Yes
• Welcome fires

Step 3 — Check The Welcome Flag

The welcome only fires if celestialWelcomeComplete: false in the plugin data. If a previous Obsidian session set the flag but didn't actually run welcome (rare but possible), reset it:

Settings → Celestial Vault → Journal Widget → Reset onboarding → click → reload Obsidian.

If the settings tab itself isn't loading: open .obsidian/plugins/celestial-plugin/data.json directly, set "celestialWelcomeComplete": false, save, reload.

Step 4 — Check You Opened The Right Folder

If you accidentally opened the wrapper folder instead of the inner Celestial Vault/, the vault is missing its plugin folder and welcome can't run. You'll see a ✦ WRONG FOLDER…txt file at the top of your file explorer in Obsidian.

Fix: in Obsidian, "Open another vault" → "Open folder as vault" → pick the inner Celestial Vault/. (See Unzipping & Opening.)

---

"Welcome appears but never completes"

The welcome flow is a multi-step overlay. If you're stuck on one step:

License Step Stuck

See License Issues for the full flow. Most common cause: license key issue (typo, slot count exceeded, internet outage).

Nickname Step Won't Save

The nickname field accepts any text. If the Continue button isn't responding:

1. Make sure the field has actual text in it
2. Try clicking inside the field, then somewhere else, then back into the field
3. Try pressing Enter instead of clicking Continue

If still stuck: open the developer console (Cmd+Option+I on Mac, Ctrl+Shift+I on Windows / Linux), look for red errors, report them.

Import Vault Step Hangs

If you clicked "Import an existing vault" and it never finished:

• The import scans every file in your old vault. Big vaults take time — a 10,000-note vault with thousands of images can take a couple minutes
• If it's been longer than 10 minutes, it's likely stuck. Click Skip to abandon the import (you can re-run from settings later — see Importing Your Old Vault)

Tutorial Cards Step Won't Click

Tutorial card clicks open YouTube links externally. If clicking does nothing:

• Try clicking again — sometimes the first click is absorbed by the overlay focus
• Manually open the URLs in your browser if needed
• The tutorials aren't required to complete welcome — click Done / Begin to dismiss

---

"I see the standard Obsidian welcome / Time Garden welcome instead of Celestial's"

You should see only the Celestial welcome. If you're seeing one of the others:

Standard Obsidian Welcome

This appears when you open a vault that has no plugins enabled. If you see Obsidian's "Welcome to Obsidian" screen instead of Celestial's:

• The celestial-plugin isn't loading (back to "Welcome doesn't appear at all")
• Or you opened a different folder than the Celestial Vault

Time Garden's Own Welcome

This shouldn't happen — Celestial pre-sets hasSeenWelcomePopup: true in TG's data so its modal never fires. If you see TG's modal:

1. Close it without going through it
2. Open .obsidian/plugins/time-garden-plugin/data.json
3. Set "hasSeenWelcomePopup": true
4. Save, reload

This suppresses TG's welcome at the source. The Celestial welcome will still own onboarding.

---

"The Journal Widget isn't visible after welcome"

The widget should be in your left sidebar at ~38% height. If it's missing:

Check The Sidebar

• Make sure the left sidebar is open (Cmd/Ctrl + B toggles it)
• Look for a square widget area near the middle of the sidebar
• If the calendar pane is taking the full sidebar height, drag the divider to make room

Reset The Workspace

The shipping vault has a canonical layout (37% local graph / 38% widget / 24% calendar). If you've drag-resized things and lost the layout:

1. Quit Obsidian
2. Open .obsidian/workspace.json in a text editor
3. (Or: use Karl's Reset workspace command if you've got it bound)

If the shipping workspace.shipping.json is in your vault, you can cp .obsidian/workspace.shipping.json .obsidian/workspace.json to restore the canonical layout. (Most users don't have this file — it gets cleaned up at export.)

The Widget Just Won't Render

If the widget area is visible but blank:

1. Reload Obsidian (Cmd/Ctrl + P → "Reload app without saving")
2. Toggle the celestial-plugin off and on
3. If still blank, report it with your OS and Obsidian version

---

"The empty tab atmosphere isn't appearing"

After welcome dismisses, you should see stars + greeting on empty tabs. If the empty tab is plain:

1. Settings → Celestial Vault → Polish & atmosphere → Empty-state atmosphere → make sure it's on
2. Try closing all tabs and re-checking
3. Reload Obsidian

If still plain: the celestial-plugin's empty-state setup may not be running. See "The Journal Widget isn't visible" above for the broader plugin diagnostic.

---

"The first-launch shimmer / nudge isn't appearing"

The first-launch nudge is one-shot. If you're past the moment, it won't appear again unless you reset.

To Re-Trigger It

Settings → Celestial Vault → Journal Widget → Reset onboarding → reload Obsidian → complete welcome again → wait 3 seconds after welcome dismisses → the shimmer + Notice should fire.

The nudge fires only on the first launch after the welcome flow successfully completes.

---

"I want to roll back to factory state"

If you want a completely clean slate:

1. Quit Obsidian
2. Delete .obsidian/plugins/celestial-plugin/data.json
3. Delete .obsidian/plugins/time-garden-plugin/data.json
4. Optionally: delete .obsidian/workspace.json (loses your tab arrangement)
5. Reopen the vault

The plugins regenerate their data files with default values. Welcome runs from step one. You'll need to re-enter your license.

---

When To Reach Out

For Celestial-specific welcome / onboarding issues that aren't covered here, the feedback form is the fastest path to Karl.

Include:

• Your OS and Obsidian version
• Which step of welcome failed
• Any error messages from the developer console
• A screenshot if relevant

---

Up Next

• License Issues — license-specific problems
• Veils and Animation Issues — for animation-side problems
• The Welcome Experience — what welcome is supposed to look like when it's working