my attempt to disentagle repository and registry 

@metalivedev can we commit this as an improvement to the existing docs and then continue to to work on it? 

(Issue #1439)