Tutorial

Previous Next

This tutorial walks through creating and managing a knowledge vault from capture through enrichment. Every command example is verified against the Click command source.

Step 1: Initialize Your Vault

ztlctl init --path research-vault --name "Research Notes" --profile obsidian --topics "ml,systems,papers"
cd research-vault

This creates the directory structure, config file, SQLite database, generated identity files, and the selected workspace scaffold. With --profile obsidian, init also writes the first-party Obsidian starter kit, creates the human-owned garden/ layer, and prints a checklist for installing the curated Obsidian community plugins. After that scaffold, .obsidian/ is yours to customize in Obsidian.

Options: - --path TEXT — Vault directory (default: current directory) - --name TEXT — Vault display name - --profile TEXT — Workspace profile used by initialization and self/workflow generation; core is always available and installed profile ids are discovered dynamically - --tone [research-partner|assistant|minimal] — Agent personality for self/ files - --topics TEXT — Comma-separated topic directories - --no-workflow — Skip workflow template setup

Anti-Pattern: Interactive init without --no-interact

Running ztlctl init in a scripted or CI environment will block on interactive prompts unless you pass --no-interact. Always use --no-interact in automation and provide all required flags explicitly.

Step 2: Capture Knowledge

Create a note — your primary unit of knowledge:

ztlctl create note "Transformer Architecture" \
  --tags ml/transformers --tags concept/architecture \
  --topic ml

Create a reference — capture an external source:

ztlctl create reference "Attention Is All You Need" \
  --url "https://arxiv.org/abs/1706.03762" \
  --subtype article \
  --tags ml/transformers --tags papers/seminal

Ingest text directly — useful when an agent or another tool already has the source text:

ztlctl ingest text "Transformer reading notes" --target-type reference

Quick capture with garden seed — when you want minimal friction:

ztlctl garden seed "Idea: attention mechanisms for code review" \
  --tags "ml/attention" --topic ml

Seeds start at seed maturity and can grow to sprout then evergreen as you develop them.

Anti-Pattern: Creating notes without tags

Notes without tags are harder to find, harder to reweave, and harder to group into topic packets. Tags drive both the tag-Jaccard reweave signal and the query list --tag filter. Always add at least one domain-scoped tag when creating a note or reference.

Step 3: Work with Tasks

ztlctl create task "Read BERT paper" --priority high --impact high --effort low
ztlctl create task "Implement attention visualization" --priority medium

View your prioritized work queue:

ztlctl query work-queue

Tasks are scored by priority x impact / effort and presented in actionable order.

Step 4: Connect Knowledge

Discover and apply connections — reweave analyzes all content and creates links above the score threshold:

ztlctl reweave run

Dry run to preview what would change:

ztlctl reweave run --dry-run

Target a specific note:

ztlctl reweave run --content-id ztl_a1b2c3d4

Reweave uses a 4-signal scoring algorithm: 1. BM25 (35%) — lexical similarity between content bodies 2. Tag Jaccard (25%) — tag overlap between items 3. Graph Proximity (25%) — existing network distance 4. Topic Match (15%) — shared topic directory

Tip

The Reweave plugin runs automatically after every create note and create reference operation, so you rarely need to run ztlctl reweave run manually. See Built-in Plugins for Reweave plugin configuration.

Step 5: Query and Explore

Full-text search:

ztlctl query search "transformer attention" --rank-by relevance
ztlctl query search "python async" --rank-by recency --type note
ztlctl query search "architecture" --rank-by graph  # PageRank-boosted
ztlctl query search "architecture" --rank-by review # review-oriented rerank
ztlctl query search "oauth" --rank-by garden        # enrichment-oriented rerank

List with filters:

ztlctl query list --type note --status draft
ztlctl query list --tag "ml/transformers" --sort recency
ztlctl query list --maturity seed --since 2025-01-01
ztlctl query list --include-archived --sort title

Get a specific item:

ztlctl query get ztl_a1b2c3d4

Decision support — aggregate context for a decision:

ztlctl query decision-support --topic architecture
ztlctl query packet architecture --mode learn
ztlctl query draft architecture --target note

Step 6: Analyze the Graph

Find related content via spreading activation:

ztlctl graph related ztl_a1b2c3d4 --depth 2 --top 10

Discover topic clusters:

ztlctl graph themes

Find the most important nodes (PageRank):

ztlctl graph rank --top 20

Find the shortest path between two ideas:

ztlctl graph path ztl_a1b2c3d4 ztl_e5f6g7h8

Find structural gaps — orphan notes with no connections:

ztlctl graph gaps --top 10

Find bridge nodes — key connectors between clusters:

ztlctl graph bridges --top 10

Step 7: Update and Evolve

Update metadata:

ztlctl update ztl_a1b2c3d4 --title "New Title" --tags new/tag
ztlctl update ztl_a1b2c3d4 --status linked
ztlctl update ztl_a1b2c3d4 --maturity sprout  # Grow a garden note

Archive — soft-delete that preserves graph edges:

ztlctl archive ztl_a1b2c3d4

Supersede a decision:

ztlctl supersede ztl_old_decision ztl_new_decision

Anti-Pattern: Updating status directly without valid transitions

ztlctl enforces lifecycle rules: a note in draft status cannot jump to connected in a single update. Attempting invalid transitions fails with INVALID_TRANSITION. Use the work queue (ztlctl query work-queue) to understand the right next action for each item.

Step 8: Export and Share

Export markdown — portable copy of all content:

ztlctl export markdown ./export/

Generate indexes — type and topic groupings:

ztlctl export indexes ./indexes/

Export the knowledge graph:

ztlctl export graph --format dot --output graph.dot  # For Graphviz
ztlctl export graph --format json --output graph.json # For D3.js / vis.js

Export a dashboard for enrichment work:

ztlctl export dashboard ./dashboard/ --viewer obsidian

This dashboard is an external review workbench. It helps you review machine-layer work queues, stale/orphan signals, and topic dossiers before doing human-led garden work in Obsidian.

This export includes:

  • dashboard.md
  • review-queue.json
  • decision-queue.json
  • garden-backlog.json
  • topic-review-summary.json
  • topics/<topic>.md and topics/<topic>.json dossiers for the busiest recent topics

Step 9: Maintain Integrity

Check vault health:

ztlctl check check

Auto-fix detected issues:

ztlctl check fix
ztlctl check fix --level aggressive  # More thorough repairs

Full rebuild — re-derive the entire database from files:

ztlctl check rebuild

Rollback to the last backup:

ztlctl check rollback

Anti-Pattern: Skipping regular integrity checks

Running ztlctl check check before large operations (bulk import, manual file edits) prevents silent corruption. Regular checks are especially important after manually editing .md files outside ztlctl, as frontmatter changes can desync the database.

Next Steps

Index Core Concepts