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. Matching is by title (case-insensitive): a file whose title matches an existing note updates that note's body in place; 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:

Renaming a file (or its title:) creates a new note — the old title no longer matches, so the previous note stays behind. Delete it on the web (node menu → Delete note).
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,

…then runs notes import on the staged folder. Because sync matches by title, keep the transform deterministic — same input, byte-identical titles — or a re-run will create duplicates instead of updating. (This is exactly how Alkahest mirrors its own ADRs and architecture docs into note maps.)

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`. It updates by title —
re-running is 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.