vibed/edu/CLAUDE.md

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-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

# 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

nbd init

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

Core commands

# 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

# 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 (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.