Here's a suggestion for a formal documentation structure to help Lenya users grok the directory hierarchy and the interaction of files in Lenya. Ideally, each file gets a comment header and each directory contains a README file that will list the following information for files and directories respectively:

parsed during
build | servlet start | page request handling (cached) | page request handling (uncached)
parsed by
(link to lenya/cocoon component or docs)
scope
servlet-wide | per-publication (static) | per-publication (fallback-enabled) (=inherited by pubs using this one as a template)
overrides
(/path/to/higher/level/file)
can be overriden by

<derived_pub>/some/path/some.xml | pubs/somepub/some/path/some.xml

manual modification
mandatory | optional | not recommended (use GUI at someurl?someusecase) | you are on your own | here be dragons
manual modification implies
changes to foo.jx | changes to /path/to/bar.java
modified/generated by

"some gui component at <pub_name>/authoring/somepage?someusecase" | helper script /path/to/script | some code snippet at... | admin | build.sh

If we can agree on a scheme like this, we might eventually apply it to solve the mysteries of DirectoryStructureLenya2.0-HEAD.