kb-import

KB Import — Skill

Purpose

Guide an agent (with its operator) through importing an external corpus that does not follow Cartographer/OKF patterns — an Obsidian vault, a plain docs folder, an exported wiki — into a Cartographer KB. The core principle (D74, consistent with D28: no server-side ingest tool):

• Mechanical work is free: layout mapping, frontmatter synthesis and link rewriting go through the cartographer import CLI scaffold — zero LLM tokens, cost proportional to corpus size.
• Semantic work is agentic and incremental: archive mapping, dedup and content curation are done by the agent, in small batches across sessions, driven by the imported_draft lint finding. Never rewrite a whole wiki in one session.
• Human checkpoint before any write: the mapping plan is approved by the operator first.

Steps

1. Recon the source (read-only)

Inventory the corpus without modifying it: file count and formats, directory structure, link style ([[wiki]] vs [text](path.md)), presence/shape of existing frontmatter, obvious non-content (assets, templates, daily notes, trash). Produce a short summary for the operator.

Secrets check. Grep the source for credentials/PII (password, token, BEGIN.*KEY, etc.) before anything is written to a KB that will be pushed. Anything found is excluded or moved to the SOPS flow — git history is forever.

2. Mapping plan — human checkpoint

Propose, and get the operator's explicit approval on:

• target Maps (existing ones, or new via map_create: entities/, topics/, notes/, incidents/, or custom) and the mapping source directory → map[/expanded concept];
• what to exclude (assets, templates, generated files, empty stubs);
• whether the target is an existing KB or a new one (create it first with the kb-create skill).

No write happens before this checkpoint.

3. Mechanical scaffold (CLI, no tokens)

On a machine with the cartographer binary and a local clone of the KB repo: