# CLAUDE.md

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

## What This Project Is

`edu` is an [mdbook](https://rust-lang.github.io/mdBook/)-based static site called **Vibed Learning** — a collection of self-guided courses and technical references. There is no Rust code here; all content is Markdown. The generated `book/` directory is gitignored.

## Commands

```sh
# Build the static site
mdbook build

# Serve locally with live reload (default: http://localhost:3000)
mdbook serve

# Enter the Nix dev shell (provides mdbook + nbd)
nix develop
# or automatically via direnv: cd into the directory
```

## Content Structure

- `src/SUMMARY.md` — mdbook table of contents; controls site navigation. **Every new page must be listed here.**
- `src/<page>.md` — individual course or reference pages
- `book.toml` — site title, theme (navy), and source directory

To add a new page: create `src/<name>.md`, then add it to `src/SUMMARY.md` under the appropriate section heading.

## Task Tracking with nbd

`nbd` is a CLI tool for managing work tickets, designed for agent workflows.

### Initialisation

```sh
nbd init
```

Run once in the project root. Creates `.nbd/tickets/`. Safe to run multiple times.

### Core commands

```sh
# Create a new ticket (use --ftype md for a human-readable body)
nbd create --title "Add OAuth login" --type feature --priority 7 --ftype md --json

# List all open tickets (sorted by priority)
nbd list --json

# Read a specific ticket
nbd read <id> --json

# Update a ticket
nbd update <id> --status in_progress --json
nbd update <id> --status done --json
```

### Finding what to work on

```sh
# All tickets that are unblocked and ready to start
nbd ready --json

# The single highest-priority unblocked ticket
nbd next --json
```

### Workflow

1. **Before starting** — create a ticket: `nbd create --title "..." --ftype md --json`
2. **When starting** — mark it in progress: `nbd update <id> --status in_progress --json`
3. **When done** — mark it complete: `nbd update <id> --status done --json`

### Guidelines

- **Always pass `--json`** to every command for structured, unambiguous output.
- **Always pass `--ftype md`** when creating tickets — markdown format keeps the body human-readable.
- Use `jq` to parse and transform JSON output when needed.
- Priority scale 0–10: use **7–9** for bugs, **5** for normal tasks, **3** for nice-to-haves.
- `--type` choices: `project`, `feature`, `task`, `bug`.
- Use `--deps id1,id2` to express blockers — tickets that must be done first.
- Create tickets *before* starting non-trivial tasks, not after.

Ticket IDs appear in commit messages in `[<id>]` format.

## Conventions

Inherits all Git and general conventions from the parent [`../CLAUDE.md`](../CLAUDE.md) (Conventional Commits, dual Apache-2.0/MIT license, Nix for dev, etc.).

Scope for commit messages: `edu` (e.g., `docs(edu): write §3 transition matrices`).

Stub sections in content are marked with 🚧 and reference an nbd ticket — fill in content and close the ticket when complete.