Until we provide more documentation please refer to a builtin mode with similar language characteristics to choose the right scope for your states and keywords.
You can also have a look at ScopeDoc.html - it is preliminary but a good starting point for understanding scopes.
Description forthcoming.