updated spec and documentation