---
title: KMS Obsidian Import Wizard
---

# KMS Obsidian Import Wizard

## What it is

A guided wizard that copies an Obsidian vault into the Omniscio KMS Vault. Desktop-only (requires a folder picker). The original Obsidian files are never modified or deleted.

**Location:** Settings → Features → KMS → **Import from Obsidian**. Gated on `nothariEnabled`, a configured vault root, and desktop (not browser/mobile).

## Where to find it

**Settings → Features → KMS → Import from Obsidian**. It needs KMS switched on, a vault root configured, and the desktop app — the folder picker it starts with does not exist on mobile or in the browser.

## How it behaves

### What transfers

- Markdown notes (`.md` files)
- Folder structure (recreated in the KMS vault)
- Supported images (PNG, JPG, JPEG, GIF, WebP, SVG, AVIF) via the content-addressed asset store with SHA-256 dedup
- Wiki-links (`[[note]]`) preserved as-is
- Callouts (`> [!type]`) preserved as-is

### What does not transfer

- Plugins, community extensions, themes, CSS snippets
- Canvas files (`.canvas`) — listed as skipped
- Obsidian settings and configuration (`.obsidian/` skipped)
- Non-image attachments (PDFs, videos) — listed as skipped
- Files over 5 MB — listed as skipped

### How it works

The wizard has five steps:

1. **Welcome** — lists what transfers and what doesn't.
2. **Source folder** — folder picker (`DIALOG_OPEN_FOLDER`). The scan validates `.obsidian/` exists.
3. **Preview** — shows note/folder/image/size counts, collision warnings, and skipped-file disclosure before committing.
4. **Import progress** — real-time progress bar via `KMS_OBSIDIAN_IMPORT_PROGRESS` push events. Cancellable mid-flight (already-imported files stay in the vault).
5. **Report** — stats grid (notes, folders, images, duration) plus skipped/error disclosures.

### Link rewriting

Obsidian image embeds (`![[image.png]]`) are rewritten to standard Markdown image syntax (`![](assets/<sha>.ext)`) using the image map built during the image import phase. Non-image embeds (`![[note]]`, `![[note#heading]]`, `![[note|alias]]`) are converted to wiki-links (`[[...]]`), stripping the `!` prefix. Plain wiki-links are not modified.

### Collision handling

If a note's relative path already exists in the KMS vault, the import appends a numbered suffix (`note (2).md`, `note (3).md`, etc.) via `pickAvailableNoteRelativePath` instead of overwriting.

### Cancellation

The user can cancel mid-import. The backend checks an abort signal between files. Already-imported notes and images remain in the vault.

## For agents

### IPC channels

| Channel | Direction | Purpose |
|---|---|---|
| `kms:obsidian-import-scan` | invoke | Preview a source folder — returns counts and skipped files |
| `kms:obsidian-import-start` | invoke | Run the import — returns final stats |
| `kms:obsidian-import-progress` | push | Live progress updates during import |
| `kms:obsidian-import-cancel` | invoke | Request cancellation of an in-flight import |

All handlers are gated by `withKmsEnabled`. Schemas: `kmsObsidianImportScanSchema`, `kmsObsidianImportStartSchema`.

### File map

- **Backend service:** [`src/main/services/kms/obsidian-import-service.ts`](/src/main/services/kms/obsidian-import-service.ts) — scan, import, link-rewrite, cancel
- **IPC handlers:** [`src/main/ipc/kms/obsidian-import.ts`](/src/main/ipc/kms/obsidian-import.ts)
- **Wizard container:** [`src/renderer/src/features/kms/obsidian-import/ObsidianImportWizard.tsx`](/src/renderer/src/features/kms/obsidian-import/ObsidianImportWizard.tsx)
- **Step components:** `WelcomeStep.tsx`, `SourceFolderStep.tsx`, `PreviewStep.tsx`, `ImportProgressStep.tsx`, `ReportStep.tsx` (same directory)
- **Settings card:** [`src/renderer/src/features/settings/sections/features/KmsObsidianImportCard.tsx`](/src/renderer/src/features/settings/sections/features/KmsObsidianImportCard.tsx)
- **Tests:** [`tests/unit/obsidian-import-service.test.ts`](/tests/unit/obsidian-import-service.test.ts) — 14 tests for `rewriteObsidianLinks`

## Related

- [kms.md](kms.md) — the parent KMS vault editor
- [kms-vault-overview.md](kms-vault-overview.md) — the searchable note inventory