index

Pour Documentation

For LLMs: Start here. Navigate to a directory index for scoped exploration, or jump directly to a core document below.

For Humans: See above… but use the graph to guide your exploration!
BACKLOG.kanban is a good place to see where you can help :)

The Vision: Writing More About What Matters

We don't log data just to have data.

We log coffee (`pour coffee`) because we are chasing the perfect extraction, and we want to remember how that Ethiopian light roast tasted at a 1:15 ratio.

We log music (pour music) because the energy of a live set and the people we shared it with are memories worth keeping.

We log ourselves (`pour me`) because our passing thoughts, midnight epiphanies, and daily anxieties deserve a place to rest outside our own heads.

We want to write more about the things that bring us joy. To do that, the tool must get out of the way entirely.

Vault Structure

Directory Index Contents
00 index/ this note Root navigation hub for the vault
01 concepts/ CONCEPTS Atomic concept notes and durable project knowledge
02 references/ REFERENCES Library API references and external docs
03 guides/ GUIDES Developer workflow and implementation guides
04 architecture/ ARCHITECTURE Design spec, ADRs
05 notes/ NOTES Legacy fleeting notes and pre-atomic working notes
06 reports/ - Sprint reports and progress snapshots
07 stories/ STORIES Vision and manifesto
08 specs/ SPECS Feature and component specifications
09 milestones/ - Release and milestone summaries — v0.2.0-Foundation, v1.0.0-Release
10 PRs/ PRS Plaintext persisted GitHub PRs with Context and linking
99 meta/ - Templates and vault maintenance material

.obsidian/ is vault configuration and snippet state, not part of the documentation corpus.

Core Documents

The Ethos of Pour

Pour is not a workspace. It is a reflex.

It is a capture tool that meets you where you already are — terminal at the desk, PWA in your pocket — designed to be as fluid and instantaneous as the gesture that invokes it.

  • Velocity is a Feature: The time between having a thought and executing the capture must be near zero. pour lives where you already are — your terminal at the desk, your phone in the wild — and is just the tool you need at the moment you need it. No cold-start app launch, no folder to find, no schema to format by hand. The phone surface costs more friction than the terminal; that cost is worth paying when the alternative is forgetting the thought entirely. See Capture-Reflex.
  • Capture First, Synthesize Later: pour separates the act of recording from the act of organizing. You pour the raw data into the vault flawlessly formatted. You can open Obsidian on Sunday to make sense of it all.
  • Plaintext is Forever: We reject proprietary databases. A memory should not be locked behind a subscription or a specific app version. Everything pour generates is strict, portable Markdown and YAML — see field-types for the full vocabulary. It belongs to you.
  • Fluidity: The name is the instruction. You don't "execute a script" or "insert a database row." You pour a V60. You pour your thoughts. Type the verb at the desk, drag the gesture in your pocket — the act is the same. It is a continuous, natural motion.

Quick Reference

Common Commands

cargo build              # compile
cargo run                # run dashboard
cargo run -- coffee      # run a specific module
cargo test               # run all tests
cargo clippy             # lint
cargo fmt                # format

Key File Locations

Area File
Entry point src/main.rs
Config schema ~/.pour/config.toml
Cache ~/.pour/cache/state.json

Architecture Overview

Pour writes to Obsidian via a __hybrid transport layer__:

  1. API — HTTPS via reqwest to Obsidian Local REST API (https://127.0.0.1:27124, accepts self-signed certs)
  2. File System — Direct std::fs fallback if API unavailable. In append mode, this fallback materialises as an atomic timestamped note rather than a destructive in-place write.

Dynamic Data Fetching (3-tier fallback)

API query -> disk scan -> ~/.pour/cache/state.json cache -> freetext input. Novel values entered into `dynamic_select` fields trigger inline note creation back into the vault.

Last Updated: 2026-04-29
Documentation Version: v0.1.0