# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Test Commands

```bash
nix develop              # Enter dev shell with Rust toolchain
nix build                # Build the package
nix flake check          # Run all checks (clippy, fmt, tests, pre-commit)

# Inside nix develop:
cargo test               # Run all tests
cargo test test_name     # Run a specific test
cargo clippy             # Lint
cargo fmt                # Format
```

After finishing tests, always check the package with `nix flake check`.

## Architecture

Streamd parses markdown files into hierarchical **Shards**, then **localizes** them by assigning temporal moments and dimensional placements based on `@Tag` markers.

**Data flow:** Markdown → `extract::parser` → `Shard` tree → `localize::shard` → `LocalizedShard` tree

**Key modules:**
- `models/` — Core types: `Shard`, `LocalizedShard`, `Dimension`, `Marker`, `Timecard`
- `extract/` — Tag extraction (`tag_extraction.rs`) and markdown parsing (`parser.rs`)
- `localize/` — DateTime extraction, configuration merging, shard localization
- `timesheet/` — State machine that converts localized shards into timecards
- `query/` — Recursive search functions for finding shards by predicate
- `cli/` — Clap-based CLI commands

## Requirements

`REQUIREMENTS.md` contains the formal specification. Update it along with the `README.md` whenever implementing or changing features.