if it ain't documented, it ain't permanent

On the matter of README files... (caution: it's a long one)