| name | kb-ingest |
| description | Ingest documents into the PARA Knowledge Base. Classifies, moves, links, and indexes new documents from Inbox or a specified path. Use when new documents need processing into the vault. |
| argument-hint | [file-or-folder-path] |
KB Ingest — Document Intake + Classification + Linking
Process new documents into the Knowledge Base. Reads content, classifies into the right PARA location, plans a folder-first destination and canonical filename, generates metadata, creates wikilinks, updates related documents, and maintains indexes.
Usage
/kb-ingest # Process all eligible files in Inbox/
/kb-ingest path/to/file.md # Process a specific file
/kb-ingest path/to/folder/ # Process all eligible .md files in a folder
Structural README Exception
- Treat
Inbox/**/README.md as structural guidance notes, not normal ingest candidates.
- Exclude these README files from default Inbox scans and folder-based batch ingest.
- If one of these README files is passed explicitly, stop and ask the user before any move, rename, frontmatter, summary, wikilink, backlink, or index action.
Execution Flow
For each document to ingest:
1. READ
- Read full document content
- Extract existing frontmatter (preserve if present)
- Identify document type: paper, note, reference, meeting, idea, log, etc.
- Note content length (affects summarization decision)
2. ANALYZE
- Read relevant
_index.md files for context (NOT full documents — token-efficient)
- Determine PARA classification:
| Signal | Classification |
|---|
| Has deadline, phases, deliverables | 1. Projects/ → which project? |
| Paper/논문, research, study | 2. Areas/Paper/ |
| Career, Interview/면접, resume | 2. Areas/Career/ |
| Ongoing responsibility, no end date | 2. Areas/ → which area? |
| Tutorial, how-to, reference guide | 3. Resources/ → which category? |
| Completed, historical, inactive | 4. Archive/ |
| Unclear | Ask user |
- Identify related existing documents by topic, tags, or content overlap
- Identify the best existing container folder inside the target category
- Propose a canonical title and filename before moving the file
3. PLAN PLACEMENT
- Decide the full destination before writing anything:
- target PARA category
- target container subdirectory
- canonical filename
- Default to subdirectory-first placement for
1. Projects/, 2. Areas/, 3. Resources/, and 4. Archive/
- Reuse an existing folder when there is a strong semantic match
- If no suitable folder exists, propose a new subdirectory and ask the user before creating it
- Do not place newly ingested files directly in a category root unless:
- the user explicitly prefers a standalone note, or
- no meaningful container exists yet and the user declines creating one
- If the plan includes a rename, show
old name -> new name in the confirmation summary
- When confidence is low or multiple containers are plausible, ask user
4. MOVE
- Move file to the planned subdirectory
- Create the approved subdirectory if needed
- Rename the file during the move when the canonical filename is approved
- If already in the correct container with the correct filename, skip move/rename
5. FRONTMATTER
Add or update frontmatter fields:
---
title: Document Title
created: 2026-04-05
type: paper
tags:
- "#proj/project-name"
- "#type/paper"
- "#topic/kubernetes"
related:
- "[[Related Document]]"
source: https://...
---
Additional rule:
title should normally match the canonical filename without the .md extension
6. SUMMARIZE (long documents only)
For documents over 500 words:
- Generate a concise summary after frontmatter (under 200 words)
- For papers: title, authors, key contribution, method, results
- Format:
> **Summary:** ... callout block
7. WIKILINK — Create Forward Links
Scan document content for existing vault entities:
- Document titles →
[[Document Title]]
- Project names →
[[project-name]]
- Technical terms matching existing docs →
[[term]]
Rules:
- Link first occurrence only per term
- Skip code blocks, URLs, and frontmatter
- Maximum ~10 auto-links per document
- Don't link common words even if a doc exists with that name
8. BACKLINK — Update Related Documents
For each strongly related document (max 3):
- Check if it already references the new doc
- If not, add to its
## Related Documents section (create section if missing; use ## 관련 문서 for Korean vaults)
- Append:
- [[New Document]] — brief context
9. INDEX — Update Indexes
- If the note lives inside a subdirectory, add or refresh the category index entry for that container folder
- If the user explicitly keeps the note as a standalone root note, add or refresh the note entry directly
- Update counts in top-level
0. Common/index.md
- Maintain sort order within index
10. LOG
Append to 0. Common/log.md:
[2026-04-05] ingest | Document Title | → 2. Areas/Paper/ | updated 2 docs
Placement and Naming Rules
Container Selection Rules
1. Projects/: always place documents inside a project folder
2. Areas/: place documents inside an area folder named for an ongoing responsibility or durable life domain
3. Resources/: place documents inside a topic or reference-material folder
4. Archive/: preserve the source container when practical; otherwise propose an archive container first
- New container names should describe a durable theme, not a one-off document title
- Existing loose notes may remain as-is; folder-first applies to new ingest by default
Filename Canonicalization Rules
- Determine the canonical title in this priority order:
- Existing frontmatter
title
- H1 heading
- First meaningful section heading
- Current filename
- Keep an already clear filename when it already matches the canonical title closely
- Rename low-information or temporary filenames such as
Untitled, IMG_1234, meeting notes, copy, final, draft, or date-only names that are missing the actual subject
- Use one of these filename patterns when renaming:
YYYY-MM-DD|Title for date-centric records such as sessions, meetings, letters, logs, and event notes
Title for evergreen concept or reflection notes
Domain|Artifact for reusable prompts, procedures, templates, and reference material
- Keep the note language; do not translate titles just to normalize filenames
- Remove Windows-invalid characters and collapse redundant whitespace or punctuation
- Keep version suffixes only when multiple live variants are intentionally retained
- Ask the user before renaming when the current filename is still meaningful, or when the note may already be referenced from elsewhere in the vault
Confirmation Summary Format
Before executing any move that creates a new folder or renames a file, present a short plan:
Proposed ingest plan
- source: Inbox/...
- target: 2. Areas/<folder>/
- folder action: reuse existing | create new folder
- filename: old-name.md -> new-name.md
- confidence: high|medium|low
- rationale: why this folder and filename fit
Proceed?
Batch Mode
When processing multiple files (Inbox/ or folder):
- Collect all eligible files first for batch classification, excluding
Inbox/**/README.md
- Classify all at once (cross-document decisions are better)
- Build one combined placement plan covering new folders and renames
- Ask once for approval if any new subdirectories or renames are proposed
- Process moves, links, and backlinks after approval
- Update indexes once at end (not per-file)
- Single batch log entry
Obsidian CLI Integration
When available:
obsidian search query="related term"
obsidian backlinks file="Document"
obsidian tags
Fallback (no CLI):
Grep for related terms, Glob for file discovery,
Read frontmatter for existing tags/links
Safety Rules
- Never delete the original file — move only
- Folder-first is the default for new ingest in Projects, Areas, Resources, and Archive
- Never ingest
Inbox/**/README.md during default Inbox scans or folder-based batch processing
- Do not add frontmatter, summaries, backlinks, renames, or moves to
Inbox/**/README.md unless the user explicitly requests that action
- Never create a new subdirectory without explicit user approval
- Ask user before renaming files, unless the filename is clearly temporary or low-information
- Ask user when classification confidence is low or multiple containers are plausible
- Do not reorganize existing PARA notes into folders unless the user asks for cleanup
- Never modify source document content beyond frontmatter and summary
- Preserve all existing wikilinks and formatting
- Perform rename/move decisions before generating new links, backlinks, or index entries