streamd/README.md

# strea.md

![The Strea.md-Logo: A tag on an endless paper roll](./streamd.svg)

Strea.md 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.

## Installation

### Debian/Ubuntu (.deb package)

Download and install the latest release:

```bash
wget https://git.konstantinfickel.de/kfickel/streamd/releases/download/vX.Y.Z/streamd_X.Y.Z_amd64.deb
sudo dpkg -i streamd_X.Y.Z_amd64.deb
```

This includes shell completions for bash, zsh, and fish.

### Static Binary

Download the statically-linked binary:

```bash
wget https://git.konstantinfickel.de/kfickel/streamd/releases/download/vX.Y.Z/streamd-X.Y.Z-linux-x86_64
chmod +x streamd-X.Y.Z-linux-x86_64
sudo mv streamd-X.Y.Z-linux-x86_64 /usr/local/bin/streamd
```

### Nix

Using the flake directly:

```bash
nix run git+https://git.konstantinfickel.de/kfickel/streamd
```

Or add to your NixOS/Home Manager configuration using the provided `homeManagerModules.default`.

## Core Concepts

- **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 Streamd.md`

An optional `_file_type` segment can follow the timestamp to classify the file:

```
YYYYMMDD-HHMMSS_<file_type> [markers].md
```

For example: `20260413-083000_daily.md` — the `daily` prefix is stored as the `file_type` dimension and propagates to all child shards.

Within files, `@`-prefixed markers at the beginning of paragraphs or headings define how a shard is categorized.

## Commands

- `streamd` / `streamd new` — Create a new timestamped markdown entry, opening your editor
- `streamd daily [YYYYMMDD]` — Open today's daily file (or create it if missing); pass a date to open that day's file instead
- `streamd todo` — Show all open tasks (shards with `@Task` markers), numbered for easy reference
- `streamd todo N edit` — Edit task N in your editor, jumping to the task's line
- `streamd todo N done` — Mark task N as done by inserting `@Done` after `@Task`
- `streamd todo --show-future` — Include tasks with future dates in the listing
- `streamd edit [number]` — Edit a stream file by index (most recent first)
- `streamd timesheet` — Generate time reports from `@Timesheet` markers
- `streamd lsp` — Start the LSP server (stdin/stdout transport; see [Editor Integration](#editor-integration) below)

## Configuration

### User Configuration

Streamd reads its user configuration from `~/.config/streamd/config.toml` (XDG standard). The main setting is `base_folder`, which points to the directory containing your stream files (defaults to the current working directory).

### Repository Configuration

For timesheet reporting, create a `.streamd.toml` file in your stream files directory:

```toml
timezone = "Europe/Berlin"  # Optional: timezone for day boundaries

[timesheet]
[[timesheet.periods]]
start = "2026-01-01"
end = "2026-06-30"
hours_per_week = 38.0

[[timesheet.periods]]
start = "2026-07-01"
end = "2026-12-31"
hours_per_week = 40.0
```

The timesheet command will calculate expected vs actual working hours based on these periods, showing:
- Daily breakdown with expected/actual hours
- Special day types (sick leave, vacation, holidays, flex days)
- Warnings for missing entries and overlapping timecards
- Monthly and cumulative balance

## Usage

Running `streamd` 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 `streamd todo` finds all shards marked as open tasks and displays them numbered in your terminal. Tasks with future dates are hidden by default (use `--show-future` to include them). Tasks are sorted by date with oldest first (task 1 is the oldest).

You can quickly edit or complete tasks by number:
- `streamd todo 1 edit` opens task 1 in your editor at the correct line
- `streamd todo 1 done` marks task 1 as done by inserting `@Done` after `@Task`

## Editor Integration

`streamd lsp` starts a Language Server Protocol server that provides IDE features for your stream markdown files. The server communicates over **stdin/stdout** and auto-activates only when a `.streamd.toml` file is present in the workspace root.

### Features

| Feature | Description |
|---|---|
| `@` completions | Suggests known markers from your config; conditional suggestions (e.g. `@Done` when `@Task` is on the line) |
| Temporal snippets | `@` followed by a digit offers `YYYYMMDD` / `HHMMSS` format snippets |
| Diagnostics | File-name format warnings (R15); timesheet errors (overlapping timecards, unclosed days) |
| Document symbols | Shard tree exposed as outline symbols |
| "Mark task as done" | Quick-fix code action: inserts `@Done` after `@Task` |
| Workspace symbols | Search shards across all `.md` files |
| References | Find all occurrences of an `@Marker` across the workspace |
| Rename | Rename an `@Marker` across all files |

### Zed

Add to `~/.config/zed/settings.json`:

```json
{
  "languages": {
    "Markdown": {
      "language_servers": ["streamd-lsp", "..."]
    }
  },
  "lsp": {
    "streamd-lsp": {
      "binary": {
        "path": "streamd",
        "arguments": ["lsp"]
      }
    }
  }
}
```

The `"..."` keeps Zed's default Markdown servers (e.g. `marksman`) active alongside streamd.

### Neovim (nvim-lspconfig)

**1. Register the server** — add to your Neovim config (e.g. `~/.config/nvim/init.lua` or a plugin file):

```lua
local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

if not configs.streamd then
  configs.streamd = {
    default_config = {
      cmd = { 'streamd', 'lsp' },
      filetypes = { 'markdown' },
      root_dir = lspconfig.util.root_pattern('.streamd.toml'),
      single_file_support = false,
    },
  }
end

lspconfig.streamd.setup {}
```

The server activates automatically when Neovim opens a Markdown file inside a directory that contains a `.streamd.toml` file.

**2. Using LSP features** — standard Neovim LSP keymaps apply (`:help lsp`):

| Action | Default keymap | Notes |
|---|---|---|
| Trigger `@` completions | `<C-x><C-o>` (insert mode) | Or via your completion plugin (`nvim-cmp`, `blink.cmp`, …) |
| Show diagnostics for current line | `<C-w>d` / `gl` | File-name format warnings, timesheet errors |
| Jump to next / previous diagnostic | `]d` / `[d` | Navigate between warnings |
| Code actions (mark task as done) | `<leader>ca` (Neovim ≥ 0.10) | Place cursor on a line with `@Task` |
| Rename marker across all files | `<leader>cr` / `grn` | Renames the `@Marker` under the cursor everywhere |
| Find all references to a marker | `grr` / `<leader>fr` | Lists every occurrence of `@Marker` across the workspace |
| Document outline (shard tree) | `:lua vim.lsp.buf.document_symbol()` | Or via Telescope: `:Telescope lsp_document_symbols` |
| Workspace symbol search | `:lua vim.lsp.buf.workspace_symbol()` | Or via Telescope: `:Telescope lsp_workspace_symbols` |

> **Note:** default keymaps (`grn`, `grr`, `<C-w>d`, `]d`/`[d`) are available from Neovim 0.10+. On older versions use `:lua vim.lsp.buf.*` commands or set up keymaps manually in your `on_attach` callback.

### VS Code (tasks.json / manual)

Use any extension that lets you configure custom LSP servers, pointing `cmd` to `streamd lsp`.