further refinements to samples and docs