Mirror a docs folder — Alkahest Docs

Import an Obsidian vault or a repo's docs/ into a notebook — and keep it synced with one command.

Keep a folder of markdown — an Obsidian vault, a repo's docs/, a decision log — mirrored into a note map. One command imports it; running it again syncs it.

The command

alkahest notes import <dir> --map <slug>

One note per .md file, walked recursively (dot-dirs like .obsidian are skipped). What carries over:

In your folder	In the notebook
Filename (or frontmatter `title:`)	Note title
Subfolders	The tree — `guides/setup.md` lands in folder `guides`
YAML frontmatter	Properties — keys become typed definitions on the map, values land on each note
`[[wikilinks]]`	Rendered links + graph edges, resolved at read time
Body markdown	Stored as-is — never rewritten

Procedure

Create a notebook for the mirror (or reuse one):
```
alkahest maps create wiki --type note
```
Dry-run first. See what would be created or updated, and which [[links]] resolve, before writing anything:
```
alkahest notes import ~/vaults/team-wiki --map wiki --dry-run
```

Import:

alkahest notes import ~/vaults/team-wiki --map wiki

Sync after edits — just run it again. Every imported note carries a source_path property (the file's path relative to the import root), and matching runs source first, title second: a file whose path matches an existing note updates that note in place — even if you retitled it — and only unmatched paths fall back to case-insensitive title matching. New files become new notes. The import is safe to re-run as often as you like.

Use --exclude for files that shouldn't become notes (--exclude index log README).

How re-sync matching behaves

Worth knowing before you point it at a big folder:

Retitling a doc updates the same note in place. The source_path match survives a title change, so the note is renamed instead of duplicated (the summary line counts it: "1 retitled in place"). Renaming the file itself also works — the path changes, but the unchanged title still matches — just don't move and retitle in one pass: with both keys changed the importer can't find the old note and creates a new one (do it in two syncs, or delete the orphan on the web).
Title matching looks across the whole project, not just the target map. If a note with the same title lives in another notebook, the import updates it and moves it into the target map. Handy when consolidating; surprising if two unrelated docs share a title — rename one first.
Unresolved [[targets]] are reported, not broken. Links to files you didn't import stay as literal text in the body and start working the moment a matching note appears.

Mirroring repo docs (the pretty version)

Pointing the importer straight at a repo's docs/ works, but titles become filenames (045-seamless-note-edit) and standard markdown links ([ADR-8](./008-foo.md)) stay plain text. For a nicer mirror, stage a transformed copy first — a small script that:

names each staged file after the doc's # H1 (the filename becomes the note title),
strips that H1 line from the body (the note title already renders it),
rewrites internal [label](./other.md) links to [[Other doc's title]] so the graph connects,
writes the doc's original repo path into source_path: frontmatter — staged filenames follow titles, so this is what keeps a doc's identity when you retitle it,

…then runs notes import on the staged folder. (This is exactly how Alkahest mirrors its own ADRs and architecture docs into note maps.)

Don't want to write that script? Ask your agent to set up the as-built docs preset — it reads the bundle over MCP (presets) and writes the files, or run alkahest docs init yourself. Either way you get a reference sync script that does all four steps, plus the writing conventions and agent rules that keep the mirror alive. See Note recipes for what the preset sets up.

Let the agent run it

Paste into your CLAUDE.md / agent instructions:

After any change under docs/, mirror it to the hosted notebook:
run `alkahest notes import docs --map docs`. Matching is by source_path
first, title second — re-running and retitling are both safe. If it
reports unresolved [[targets]], leave them; they resolve when the
target doc is added.

The import speaks the same edge functions as every other note write, so the activity journal shows the sync like any other agent session.