add examples
improve error message for read-only states