# Create — New Knowledge Unit

Synthesize the content from the current note into a clean knowledge unit written as a fresh document. There is no existing unit to preserve or reference.

Do not add inline citations anywhere in the body. All content originates from this note; the Sources section is the sole record.

---

## Content organization

You have full freedom to choose and name sections. Let the entity dictate the structure — a person, a book, a company, and a technique each call for different organization. There is no prescribed template.

Ask yourself: what does the author need to know about this entity when they return to it later? What is their current understanding, and how should it be organized to grow?

**One principle**: a knowledge unit should contain only what's most important. Source notes are the permanent record — the unit is a living distillation.

---

## Two required sections

**`## Related Knowledge`** — wikilinks to other knowledge units with a brief note on the relationship. Omit if there are no meaningful connections.

**`## Sources`** — always the **last section** in the file. Initialize with `- [[<current-note-stem>]]` where stem is the source note's filename without path or extension (e.g. `/notes/2024-01-15 Weekly Review.md` → `- [[2024-01-15 Weekly Review]]`).

If the vault language is not English, translate section headings accordingly (e.g. `## 来源`).

---

## Frontmatter

```yaml
---
kind: knowledge
title: <Title>
entity_type: <freeform label>
tags: [tag1, tag2]
source_notes:
  - /path/to/current-note.md
created_at: YYYY-MM-DDTHH:MM:SSZ
last_compiled_at: YYYY-MM-DDTHH:MM:SSZ
compile_count: 1
---
```

Set `created_at` and `last_compiled_at` to today. `compile_count: 1`.

---

## Tag normalization

Before assigning tags, run:

```bash
vaultr tag list
```

First determine the tags that accurately describe the unit. Then, for each tag, check the existing list for a semantically equivalent entry (same concept, different language or spelling — e.g. `独立开发` ↔ `indie-dev`). If one exists, replace your tag with it. Only keep a new tag when no equivalent exists.

---

## Write output

Create `<knowledge-dir>/<Title>.md` with the full unit content.

# Extract — Partial Note Reading

`vaultr extract` reads parts of a note without loading the full content. Use it whenever the full note is not needed.

## Subcommands

**Outline** — heading structure only:
```bash
vaultr extract outline <path-or-name>
```

**Section** — one named section and its content (ends at the next heading of equal or higher level):
```bash
vaultr extract section <path-or-name> "<heading>"   # case-insensitive
vaultr extract section today.md "## meeting notes"
```

**Segment** — line range:
```bash
vaultr extract segment <path-or-name> --head 20        # first N lines
vaultr extract segment <path-or-name> --tail 10        # last N lines
vaultr extract segment <path-or-name> --start 5 --end 30  # specific range (1-based, inclusive)
```

**Tags** — front-matter tags only:
```bash
vaultr extract tag <path-or-name>
```

**Code blocks** — all fenced code blocks:
```bash
vaultr extract code <path-or-name>
```

**Lists** — all bullet and numbered lists:
```bash
vaultr extract list <path-or-name>
```

**Links** — all links (wikilinks and markdown links); each result shows type and target:
```bash
vaultr extract link <path-or-name>
```

## Path rules

Same as `vaultr read`: accepts vault-absolute paths (`/journal/today.md`) or bare filenames (resolves to most recently updated match).

# Update — Existing Knowledge Unit

Your goal is not to append — it is to produce the best current distillation of the existing unit plus the new note.

Treat the update as editorial work:

- **Integrate, don't append.** Weave new content into the structure where it belongs — no section-appending, no "Updates" blocks.
- **Cite by paragraph.** After each paragraph introducing new content, append `[[note-stem]]`. For paragraphs drawing from multiple sources, list all relevant citations.
- **Reorganize when the weight has shifted.** If new content changes what's most important, restructure sections accordingly.
- **Merge redundancies.** When old and new content overlap, keep only the sharper version.
- **Remove what no longer earns its place.** Cut points that are superseded, contradicted, or outweighed by richer content. The unit is not a historical record — source notes are.
- **Rewrite for coherence.** The final unit should read as one document, not layered deposits from different dates.

Test: does the unit give the clearest possible picture of where the author's understanding stands today?

---

## Content organization

You have full freedom to choose and name sections. Let the entity dictate the structure — a person, a book, a company, and a technique each call for different organization. There is no prescribed template.

Ask yourself: what does the author need to know about this entity when they return to it later? What is their current understanding, and how should it be organized to grow?

**One principle**: a knowledge unit should contain only what's most important. Source notes are the permanent record — the unit is a living distillation.

---

## Two required sections

**`## Related Knowledge`** — wikilinks to other knowledge units with a brief note on the relationship. Omit if there are no meaningful connections.

**`## Sources`** — always the **last section** in the file. Append `- [[<current-note-stem>]]` only if not already listed — never duplicate. Stem is the source note's filename without path or extension (e.g. `/notes/2024-01-15 Weekly Review.md` → `- [[2024-01-15 Weekly Review]]`).

If the vault language is not English, translate section headings accordingly (e.g. `## 来源`).

---

## Frontmatter

```yaml
---
kind: knowledge
title: <Title>
entity_type: <freeform label>
tags: [tag1, tag2]
source_notes:
  - /path/to/note.md
created_at: YYYY-MM-DDTHH:MM:SSZ
last_compiled_at: YYYY-MM-DDTHH:MM:SSZ
compile_count: 1
---
```

Add the current note path to `source_notes`. Update `last_compiled_at` to today. Increment `compile_count`.

---

## Tag normalization

Before assigning tags, run:

```bash
vaultr tag list
```

First determine the tags that accurately describe the unit. Then, for each tag, check the existing list for a semantically equivalent entry (same concept, different language or spelling — e.g. `独立开发` ↔ `indie-dev`). If one exists, replace your tag with it. Only keep a new tag when no equivalent exists.

---

## Pre-write review

Before writing, review the integrated unit against four criteria:

1. **Relevance** — Does every paragraph belong to this unit's core subject? Cut anything that drifted in from adjacent topics.

2. **Currency** — Is any content outdated or superseded by the new note? Cut or correct it. The unit reflects current understanding, not accumulated strata.

3. **Coherence** — Does it read as one document? Are section order and transitions immediately navigable?

4. **Concision** — Is everything load-bearing? Cut anything that restates what is already clear elsewhere.

Resolve all issues before writing.

---

## Write output

Overwrite the existing file with the full updated content.