edu claude.md

edu/CLAUDE.md

@@ -0,0 +1,94 @@
+# 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.