first (partial) cut of docs

plus assorted fixes for consistency / correctness