make directive more semantic, add known issues and roadmap