refresh intro chapter of spec and add more examples