docs: document file_type prefix convention and streamd daily command
This commit is contained in:
parent
bf700a15af
commit
b8a73bfb3e
2 changed files with 34 additions and 2 deletions
|
|
@ -49,11 +49,20 @@ 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`
|
||||
|
|
|
|||
|
|
@ -275,13 +275,18 @@ This allows conditional placements to override base placements.
|
|||
|
||||
### R15: File Name Format
|
||||
|
||||
Files follow the pattern: `YYYYMMDD-HHMMSS [markers].md`
|
||||
Files follow the pattern: `YYYYMMDD-HHMMSS[_file_type] [markers].md`
|
||||
|
||||
- `YYYYMMDD`: Date (8 digits, required)
|
||||
- `HHMMSS`: Time (4-6 digits, optional, pads with zeros)
|
||||
- `_file_type`: Optional alphanumeric prefix identifying the file type (e.g. `_daily`)
|
||||
- `[markers]`: Space-separated marker names extracted from file content
|
||||
|
||||
**Extraction regex:** `^(?P<date>\d{8})(?:-(?P<time>\d{4,6}))?.+\.md$`
|
||||
**Extraction regex for datetime:** `^(?P<date>\d{8})(?:-(?P<time>\d{4,6}))?.+\.md$`
|
||||
|
||||
**Extraction regex for file type:** `^\d{8}(?:-\d{4,6})?_([a-zA-Z0-9]+)`
|
||||
|
||||
When a `_file_type` prefix is present it is stored in the `file_type` dimension of the root shard and propagates to all child shards.
|
||||
|
||||
### R16: Temporal Markers
|
||||
|
||||
|
|
@ -387,6 +392,7 @@ Provide recursive search through the shard tree:
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `streamd new` | Create new timestamped file, open editor, rename with markers on close |
|
||||
| `streamd daily [YYYYMMDD]` | Open the earliest daily file for the given date (default: today in configured timezone), or create a new `_daily` file if none exists |
|
||||
| `streamd todo` | List all shards with `task: "open"`, numbered, hiding future tasks |
|
||||
| `streamd todo --show-future` | Include tasks with future dates in the todo listing |
|
||||
| `streamd todo N edit` | Edit task N in editor, cursor positioned at task line |
|
||||
|
|
@ -395,6 +401,23 @@ Provide recursive search through the shard tree:
|
|||
| `streamd timesheet` | Generate formatted timesheet report with expected/actual hours |
|
||||
| `streamd completions <shell>` | Generate shell completions (bash, zsh, fish, elvish, powershell) |
|
||||
|
||||
### R21a: Daily Command Behavior
|
||||
|
||||
`streamd daily [YYYYMMDD]` provides quick access to the daily journal entry for a given date.
|
||||
|
||||
**Date resolution:**
|
||||
- If a `YYYYMMDD` argument is provided, it is parsed as the target date.
|
||||
- If no argument is given, today's date is used, interpreted in the repository timezone (from `.streamd.toml`, defaulting to UTC).
|
||||
|
||||
**File lookup:**
|
||||
- All markdown files in the base folder are localized.
|
||||
- Files with `file_type = "daily"` whose root shard `moment` falls within the target date (in the configured timezone) are collected.
|
||||
- The file with the earliest `moment` is opened in `$EDITOR` (defaults to `vi`).
|
||||
|
||||
**File creation:**
|
||||
- If no matching file is found, a new file is created at `<now_local>_daily.md` (e.g. `20260413-083000_daily.md`) containing `# ` and opened in the editor.
|
||||
- The `_daily` suffix is permanent — it identifies the file type and is not renamed after editing.
|
||||
|
||||
### R21: Todo Command Behavior
|
||||
|
||||
**Task Numbering:**
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue