Obsidian Vault Import — Design

The inverse of Obsidian Export; depends on Native Wikilinks so vault links are kept as written. Canonical spec: docs/superpowers/specs/2026-10-01-obsidian-vault-import-design.md.

Flow

1. Import Obsidian vault… (sidebar, beside Export, and the command palette) for users with createPages.
2. Upload a zip → a plan: pages new / skipped / failing, attachments, clusters and hubs to create or join, grouped warnings. Option: folders become clusters (default), one fixed cluster, or none.
3. Import runs as a background job with progress, then a per-page result. Closing the dialog does not cancel it.

Key decisions

• Never overwrites: names that already exist are skipped; links to them resolve to the existing page. Re-running an import is safe.
• Plan then apply with a plan hash: apply re-uploads the zip and is refused (409) if the vault or wiki changed since the reviewed plan.
• Asynchronous apply, because every page save runs filters, events and reindexing and prod sits behind a 100-second edge timeout. Jobs are in memory, one per user, one at a time by default.
• Zip safety from scratch: zip-slip, absolute/backslash names, bomb ratio, entry and size caps.
• Mapping: note names made legal (original kept as title/alias), duplicate names disambiguated by folder, readonly and export-only frontmatter dropped, inline #tags merged into tags, folder notes become hubs (or a hub is generated), depth folded to the one-level sub-cluster limit.
• Links: Obsidian path/basename resolution; renamed targets keep their original text as alias; markdown links to notes become [[ ]]; block refs and %% comments %% stripped with a warning.
• Attachments: only referenced files, owned by the first referencing page; blocked types and upload-policy violations reported.

Limits

wikantik.import.maxUploadBytes 100 MB, maxUncompressedBytes 500 MB, maxEntries 20,000, maxPages 2,000, maxConcurrent 1.