From c0911307fdddd4571238eae5de533321b4072106 Mon Sep 17 00:00:00 2001 From: Konstantin Fickel Date: Sat, 7 Feb 2026 22:03:45 +0100 Subject: [PATCH] docs: expand README with project overview, concepts, and usage --- README.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2fcf603..fca374d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,34 @@ # streamer -Searching for `@tags` in time-based [streams](https://www.cs.yale.edu/homes/freeman/lifestreams.html). +Streamer is a personal knowledge management and time-tracking CLI tool. It organizes time-ordered markdown files using `@tag` annotations, letting you manage tasks, track time, and query your notes from the terminal. -# Usage +## Core Concepts -Running `streamer` finds all lines with @Task \ No newline at end of file +- **Shards** — Sections of markdown files, organized hierarchically by headings. Each shard can contain markers, tags, and nested child shards. +- **Markers** — Special `@tags` like `@Task`, `@Done`, `@Waiting`, or `@Timesheet` that give shards semantic meaning and place them into dimensions. +- **Dimensions** — Classification axes (e.g. task state, project, timesheet) that categorize shards. Some dimensions propagate to child shards. + +## File Format + +Markdown files are named with a timestamp: `YYYYMMDD-HHMMSS [markers].md` + +For example: `20260131-210000 Task Streamer.md` + +Within files, `@`-prefixed markers at the beginning of paragraphs or headings define how a shard is categorized. + +## Commands + +- `streamer` / `streamer new` — Create a new timestamped markdown entry, opening your editor +- `streamer todo` — Show all open tasks (shards with `@Task` markers) +- `streamer edit [number]` — Edit a stream file by index (most recent first) +- `streamer timesheet` — Generate time reports from `@Timesheet` markers + +## Configuration + +Streamer reads its configuration from `~/.config/streamer/config.yaml` (XDG standard). The main setting is `base_folder`, which points to the directory containing your stream files (defaults to the current working directory). + +## Usage + +Running `streamer` opens your editor to create a new entry. After saving, the file is renamed based on its timestamp and any markers found in the content. + +Running `streamer todo` finds all shards marked as open tasks and displays them as rich-formatted panels in your terminal.