🚧 Early alpha — building the foundation. See the roadmap →

Import wizard

Updated Nov 13, 2026

Crosswalker’s import experience lives in the Crosswalker workspace tab — a dedicated pane you keep open, not a modal you reopen every time. The classic “Import structured data” modal (command palette, or the settings hub) still works and runs the exact same flow; the workspace tab is just the wider, primary way to use it.

Status last verified — record filter, unfiltered-preview note, missing-value properties, and the Step 1 preset guide and Escape behavior only: 2026-09-14, on an unmerged working branch. The Step 1 preset guide and the Escape close were verified on 2026-09-14 against src/import/import-wizard.ts, src/import/import-preset-guide.ts, and a real-Obsidian run of tests/e2e/visual-launchpad-and-header.spec.ts that passed 3 of 3. The missing-value behavior is verified against tests that read back the written note produced by generateNotes() with a populated classic mapping, on both first import and refresh. The record filter and the unfiltered-preview sentence were verified in the running app on 2026-09-09 by a targeted run of tests/e2e/visual-wizard-formats.spec.ts: a filtered JSON import wrote exactly one note, a filter naming a field the source does not have reached the results screen with one error and zero notes, and the preview sentence was read on fresh light and dark captures (details). That run covered those screens only — it is not a visual verification of this page as a whole, and other claims on this page were not re-verified by this update. A “Tier 2 projection failed” warning was present throughout that run and is unresolved, so it is no evidence about query freshness.

Not yet verified in real Obsidian (2026-09-21): the vault scan and the worksheet suggestion described below shipped on an unmerged branch without a screenshot run.

Not yet verified in real Obsidian (2026-09-22): the nested-record picker and nested-row controls described below shipped on an unmerged branch without a screenshot run.

The workspace tab

Open it from the network-shaped ribbon icon, the status bar count, the “Open workspace” command, or by right-clicking a CSV, XLSX, or JSON file in the file explorer and choosing “Import into vault with Crosswalker” (the file arrives pre-selected, so you skip straight to configuring it). A one-time notice after you enable the plugin points at the tab too.

The tab opens on a home screen:

A launchpad: “Import structured data,” “Manage saved configs,” and, when draft auto-save is on, “Resume a draft.”
An installed frameworks list — every subfolder under your output path, each with a live note and link count and, for sources Crosswalker recognizes, an “Import again” button that reruns the same built-in configuration without re-detecting anything.

Click “Import structured data” and the flow below takes over the tab, wide, with your source and destination visible side by side.

Selecting a source

Step 1 opens with Browse built-in import presets, a collapsible list sitting above the file picker. It names every source Crosswalker recognizes on sight and, for each one, links to the publisher’s download page and to the matching import instructions, so you can go and fetch the right file without losing your place. The same guide is on the settings launchpad and the workspace tab’s launchpad.

If source files already sit in the vault, Find sources in this vault opens from the workspace launchpad, the settings mirror, or Crosswalker: Find framework sources in this vault. The scan is the way into deeper reification, and the wizard is where the user decides, column by column, what becomes real. Each row shows the matched source and score, its worksheet and header row when relevant, and whether its byte digest is not imported, imported unchanged, imported with changed source bytes, or still checking the vault index. From the results, Import selected creates new sets in order, Create drafts for selected saves offer-only resume points, and the row action opens the source in the wizard or offers Refresh without preselecting a set. An unchanged import uses Open instead. Recognition only offers a source and binding; it never auto-imports, auto-refreshes, or chooses a recipe for the user.

Pick a CSV, XLSX, or JSON file. Crosswalker reads each differently:

CSV — every row becomes a note; large files parse through a streaming reader so multi-megabyte exports don’t stall.
XLSX — pick the worksheet, then the header row (raise it to skip banner rows sitting above the real headers).
JSON — Crosswalker finds the lists of records nested inside the file and shows them as selectable cards (list name, path, record count, field names); pick the one to import. An advanced path field is there if your records live somewhere unusual, but you rarely need it.

When one JSON record list owns another, the picker makes deeper reification and the user’s control one decision: it summarizes the chain as Records inside records, then offers Nested: groups, controls, parts (21 notes) to make one note per record at every level or Only groups (3 notes) to keep the existing flat import (labels are built from the source’s own list names and counts). The offer appears once, on the top-level list, and the flat choice stays selected until you choose nesting.

Under the record cards, “Keep only matching records (optional)” narrows the import: write field=value to keep matches or field!=value to drop them, and combine rules with commas. On an unmerged working branch this filter is now carried into generation on both the classic and workbench paths; previously it took effect only in the beta workbench. A filter that names a field your source does not have, or that matches nothing, reports an error at generation time rather than quietly importing the wrong set of records. The unknown-field case was observed in the running app on 2026-09-09: the results screen showed one error and zero created notes, and the message named the missing field and listed the fields the source does have. The “matches nothing” case is established from the engine and its tests, not from a run of the app.

Any drafts you left mid-import from a previous session are listed here too, with Resume and Delete — see pause and resume.

Pressing Escape closes the wizard whenever no file picker, menu, or popover is open. When one of those is open, Escape closes that first and leaves the wizard where it was.

Recognized sources: the fast path

When a file’s columns closely match one of Crosswalker’s built-in configurations, the wizard leads with a calm “Recognized source” card instead of asking you to configure anything. Today that covers NIST CSF 2.0, MITRE ATT&CK, CIS Controls v8, the Secure Controls Framework, NIST 800-53, CRI Profile, and crosswalk/mapping files — matched against the file’s actual columns, not its filename.

For a recognized workbook, the wizard suggests the worksheet and zero-based header row from the observed columns. The line beneath the controls names the source, sheet, and row, both controls stay editable, and changing either switches the line to Using your choice with Use suggestion to restore the pair. A suggestion never advances the wizard or selects a recipe.

The card shows what it recognized, how many rows become how many notes, which shapes it produces (folders, tags, links, properties), and where it would land. Three choices:

“Import with this configuration” — jumps straight to the review screen.
“Customize” — opens the same configuration in map the shapes so you can adjust anything before generating.
“Start from scratch” — dismisses the card for this file and falls back to ordinary detection.

An unedited recognized source is labeled Built-in; the moment you change something after Customize, it honestly relabels as Custom (based on the source).

Map the shapes

When there’s no confident match, or you chose Customize, you land on the mapping screen. Two modes exist today:

The classic column table (the default): every column listed with its detected type, sample values, and a “Use as” role — frontmatter property, hierarchy level, folder tree from an id, note title, a crosswalk link, body content, or skip — plus a live “in the vault” preview per row. A filter box and a collapsible tail keep very wide sources manageable.
Live mapping workbench (beta — turn it on under Settings → Import behavior): one screen, three zones, updating together as you work.
- What we found (left) — your columns with detection badges (a hierarchy packed into one id, a chain of level columns, a shared-value facet, a parent-id link, long text that reads like a document body, or a file that’s really a set of relationships between two other sources) and an evidence card explaining why each one fired.
- How it lands (center) — a preset picker, then one card per detected shape with six toggles for the ways your data can live in the vault (folders, file names, tags, headings, links, properties) and a combined “your mix on one row” preview. An “Arrange levels” panel lets you merge or split levels, choose how each is named, and decide what happens when a level is missing.
- Live preview (right) — a real folder tree and one fully rendered note, both recomputed as you change anything, plus a banner stating plainly whether every row fits the pattern you’ve built.

When a column appears to contain identifiers from another framework, or a loaded recipe already declares that destination, the workbench shows a Crosswalks card. This crosswalk column role (plain: one source column names concepts in another framework) is where the user controls deeper reification: Framework names the target from the registry or Other, and Predicate names the relationship. Leaving the framework unnamed blocks Generate with Column "<column>" is marked as a crosswalk but no framework is named. Pick the framework on the Crosswalks card, or turn the card off. Generation writes separate edge notes in their own import set under _crosswalker/mappings/<source>-to-<target> and writes nothing into the concept note.

On a nested import the mapping card opens with a Depth select, the coarsest control on the card. Choosing 1 folder on a groups, controls, parts source reads Each group becomes a folder; each control becomes a note; part is left out of this import. and rewrites every level’s destination below it; a hand edit that no depth can express shows Custom and says how to reset. The parse notice and every sample on the card come from the expanded records (Parsed 21 records across 3 levels: groups (3), controls (6), parts (12)., samples ac, ac-1, ac-1_smt.md), not from the flat top-level rows.

On a nested record level, the workbench adds a sub-row with two small selects. Own note chooses Yes, as a folder note or No, folder only; Identified by chooses Its own identifier or Its path from the top level. No, folder only keeps that level as a folder and keeps its name in each child’s parent lineage, but creates no note for the level itself; the Depth select sets the same value on every level below the note. Merge and Split are absent on these rows because the source already declares separate record types; combining children into sections inside the parent is a different body-projection capability and is not in this build.

Review and confirm

Before you generate, the review screen answers where it lands, what gets made, and why you should trust it:

Destination — an editable breadcrumb path, with a button to reveal the target folder in the file explorer without leaving the tab.
Your shape map — a table recapping “from your file → becomes → count” for every mapping.
Headline counts — notes, folders, and links (in the sampled rows), so a link-dead import is visible before you commit to it.
A deviation notice — the same conversion Crosswalker will actually run at generate time, checked against your rows in advance. A clean run says so in one line; when some rows don’t fit the pattern you’ve built, it lists which ones and why, in plain language, before you generate rather than after.
Provenance — one line naming what you’re using: Built-in (an unedited built-in configuration), Yours (a saved configuration you applied), or Custom (edited from either).

One honest limit, stated on screen when it applies: the preview samples your source unfiltered, so a previewed row may not survive a record filter you set. The filter is applied during generation, which is the authoritative pass. The screen says so rather than predicting a count it cannot yet promise.

What generation produces

Clicking Generate writes real files:

Folders, one per hierarchy level you mapped.
Notes, one per row, with YAML frontmatter for every column you kept, WikiLinks for anything mapped as a link, and body content for anything mapped as body text. When a record simply doesn’t have one of the fields you mapped as a property, that property is left off that note rather than failing the row — which is what makes uneven real-world exports importable. This is branch behavior that is not yet merged or released, and it is checked against the YAML of an actual generated note, not just a rendered preview. A false or a 0 is a value, not an absence, and is kept. Anything Crosswalker needs to place the note — its file name, its identity, its folder levels — still stops the import with an error when it’s missing, and a row is never silently skipped.
Parent-child links and hub notes — when your import has a clear parent/child id relationship, parent notes automatically get a managed list of their children; any column with a handful of shared values (like a category) gets its own hub note listing every note that carries that value, and your own writing under that note’s heading survives a re-import. This currently happens when you go through the live mapping workbench or a built-in configuration — the classic column table doesn’t produce children lists or hub notes yet.
A small _crosswalker metadata block on every note recording where it came from, so a re-import updates rather than duplicates.

See the generation engine page for the full detail on what lands in each note.

Pause and resume

If you close the tab mid-import, Crosswalker auto-saves a draft (toggle in settings) about half a second after your last edit. Drafts show up on the workspace home screen and at the top of source selection, with the file re-read from your vault automatically when possible, so you resume exactly where you left off, mapping decisions included. One current gap: XLSX sheet choices and JSON record-list selections don’t yet persist across a resume — CSV imports are fully covered.

Escape hatches

Saved configurations — after you’ve mapped a source once, save it. The config browser lets you browse, preview mappings, duplicate, delete, and export or import configurations as JSON files to share with a teammate or another vault.
Customize on any recognized-source card, whenever you don’t want the built-in default.
The classic column table, whenever you’d rather not turn on the beta workbench.

Config system — saving, matching, and sharing configurations
Generation engine — what happens after you click Generate
UI lexicon — the plain-language names used throughout this page, and what they map to internally
Terminology — full glossary
Hierarchy primitives — the five ways data can live in a vault, that the mapping workbench’s shape toggles are built on
ETL and import — why imports are built this way
Ordinary import repairs — the decisions behind the record filter, the unfiltered-preview note, and missing-value properties, and exactly how far their verification has got