ztlctl uses a two-layer model instead of collapsing every knowledge method into one workflow. The first layer — capture and synthesis — is where agents and humans work together to collect sources, build references, and develop rough understanding. The second layer — enrichment — is where the human user takes over to deepen, reorganize, and mature that foundation. Second-brain and knowledge-garden approaches are not competing methods: they map naturally to these two layers, and ztlctl supports both simultaneously.

Second-Brain vs Knowledge Garden¶

At a Glance¶

Both approaches coexist in a single vault. Content captured in the machine layer (notes/, ops/) is indexed, searchable, and reweaved automatically. Garden content lives in garden/ — ztlctl never indexes or mutates that directory. The two layers complement rather than replace each other.

Choose Your Path¶

"I want to research a new technology or topic"

Use the second-brain capture-first approach. Start a focused session, ingest sources and create synthesis notes as understanding develops, and let reweave connect the material automatically.

→ See Scenario 1: Researching a New Technology

"I have captured material and want to deepen my understanding"

Use the knowledge-garden enrichment-first approach. Surface seed notes waiting for attention, review the work queue for stale or actionable items, and promote notes as understanding matures.

→ See Scenario 2: Tending Existing Knowledge

"I want both — capture now, tend later"

They coexist by design. Capture in the machine layer (notes/, ops/) using create, ingest, and session. Tend in the garden layer (garden/) using Obsidian or ztlctl update. ztlctl never indexes or mutates garden/ content, so the two workflows never interfere.

→ See Scenario 3: Agent-Assisted Hybrid

Scenario 1: Researching a New Technology (Second-Brain Approach)¶

You're investigating OAuth security. Start a focused session to keep context anchored, ingest sources as you find them, and build synthesis notes as understanding develops.

# Start a focused research session
ztlctl agent session start "oauth security"

The session creates a coordination log and anchors all subsequent work to the oauth security topic context.

# Ingest sources as references
ztlctl ingest text "RFC 6749 notes" --stdin --as reference --tags "auth/oauth"

Each ingested source becomes a reference in the machine layer with a stored source bundle under sources/.

# Create synthesis notes as understanding develops
ztlctl create note "OAuth 2.0 threat model" \
  --tags "auth/oauth,security" \
  --topic auth

Notes start at draft status and progress through linked → connected as reweave adds links.

# Build a learning packet from captured material
ztlctl query packet --topic auth --mode learn

The learning packet aggregates your captured references and notes into a structured context block for review or agent handoff.

# Draft a synthesis note from the packet
ztlctl query draft --topic auth --target note

# Close session — triggers reweave, orphan sweep, and integrity check automatically
ztlctl agent session close --summary "Mapped OAuth threat surface"

Scenario 2: Tending Existing Knowledge (Knowledge-Garden Approach)¶

You have a vault with captured material and want to deepen your understanding of the auth topic. Surface what needs attention, review the work queue, and promote notes as understanding matures.

# Surface seed notes waiting for enrichment
ztlctl query list --maturity seed --sort recency

Seed notes are raw captures — garden seeds you planted but haven't developed yet.

# Review the work queue for stale or actionable items
ztlctl query work-queue

The work queue scores all actionable items by priority, impact, and effort, presenting them in the order most worth your attention.

# Get a review packet for the topic you're tending
ztlctl query packet --topic auth --mode review

The review packet surfaces stale notes, weakly connected items, and decision-support context for the topic — machine-layer signals to guide where human tending is most valuable.

# Promote a note as understanding deepens
ztlctl update ZTL-0001 --maturity budding

Maturity tiers — seed → budding → evergreen — track how thoroughly a note has been developed.

# Export a dashboard for visual review in Obsidian
ztlctl export dashboard --viewer obsidian --output ./dashboard

Scenario 3: Agent-Assisted Hybrid (Both Paradigms)¶

You're working alongside an agent. The agent captures research in the machine layer; you tend connections and deepen notes in the garden layer. Neither workflow disrupts the other.

# Agent captures research in the machine layer
ztlctl create note "Distributed consensus trade-offs" --tags "systems/consensus" --topic systems

# Human reviews agent-captured seeds and promotes them
ztlctl query list --maturity seed --sort recency
ztlctl update ZTL-0042 --maturity budding

# Human tends connections in Obsidian's garden/ layer (no ztlctl command needed)
# ztlctl does not index or mutate garden/ content

How The Paradigms Map¶

What ztlctl Does Not Claim¶

• It does not force PARA or any other organizational method as the canonical ontology.
• It does not treat garden work as fully automatable.
• It does not treat operational session state as equivalent to durable knowledge artifacts.

Anti-Patterns¶

Avoid these common mistakes when setting up a ztlctl workflow.

Intended Flow¶

1. Capture sources and rough synthesis quickly.
2. Use search, packets, and reweave to stabilize the foundation knowledge layer.
3. Use packets, drafts, and dashboard dossiers to turn captured evidence into reviewable work.
4. Enrich that foundation through slower, human-led garden work.

Next Steps¶

• Follow the Tutorial to build your first vault end-to-end
• Read Core Concepts for the full content type, ID format, and lifecycle state reference
• Read Best Practices for workflow patterns and anti-pattern deep dives
• See Agentic Workflows for session lifecycle, recipe walkthroughs, and MCP integration
• See Plugin Authoring to extend paradigm support with custom note types