Upgrade and clean wiki project

I have configured this repository to mirror its associated wiki so that we can have better control and use pull-requests.

I would like to add all the things the repo should have like README, LICENSE file etc. However I also want those files to play "nice" with the generated wiki so I am not sure how to do that properly (probably have those files without any extension name).

I also would like to upgrade the content to a better more thought-through structure. Again, I am not sure what are the possibilities, but we should take inspiration in other projects.

Inspiration as generated by our AI overlord :):

🔍 Good Real-World Examples & Resources

Here are some wikis / examples / guides to see how people organize theirs well:

Example / Resource	What’s Good / Highlights
MyHoneyBadger / awesome-github-wiki	A curated list of “awesome wikis” with links to many projects with well-maintained wikis. Good for seeing what established projects do. (GitHub)
PracticalSeries / GitHub Wiki Design and Implementation	This is a guide and a working wiki template. It covers file/folder layout, sidebars & footers, conventions, how to organize navigation etc. (GitHub)
Almanac blog: “How to Use Github as a Wiki: Examples & Templates”	Offers example layouts from real projects (e.g. Hystrix, Titan, D3.js) and shows how they structure their pages. (get.almanac.io)
Compass by Nimble — GitHub Wiki Documentation	This is internal but publicly documented by Nimble; it shows a clean structure: “Home / Getting Started / Architecture / Infrastructure / Operations”, with sub-pages. (Nimble)

---

🧰 What Makes a Good Wiki Structure

From those examples plus general experience, here are patterns and best practices people use to make a wiki usable, maintainable, and navigable:

1. Clear top-level structure (“Home” / “Getting Started” / etc.)

   • The Home page acts as a “portal” / overview.

   • “Getting Started” helps new users or new contributors.

   • Architecture, Infrastructure, Operations (or equivalent) cover technical details. (See the Nimble example.) (Nimble)

2. Logical subdivisions

   • Group related topics under sections. For example under Architecture: Authentication, Data Flow, Caching, etc.

   • Under Infrastructure: Deployment process, Environment Variables, Monitoring, etc.

3. Standardized naming & conventions

   • Page titles are consistent (e.g. “Project Setup”, not “Setup for Project”), so navigation is predictable.

   • Use logical filenames like getting-started.md, architecture/authentication-flow.md, etc.

4. Navigation aids

   • Use a sidebar (Wiki allows a _Sidebar.md) to link pages hierarchically.

   • Possibly a footer for meta information (contributors, last updated, version).

   • Cross-link between pages where relevant.

5. Keep content scoped and concise

   • Don’t put absolutely everything into one page; split when content gets long.

   • For example, one page per service, one per strong boundary in the system.

6. Living documentation

   • Mark pages with “last updated” so people know whether content might be stale.

   • Have a process or responsibility for maintaining parts. Sometimes tie this to workflow or reviews. (Mentioned in Nimble’s docs: “Documentation Review”.) (Nimble)

7. Useful entry points / index

   • Use the Home page to guide different kinds of users: developers, operations, new contributors.

   • Use TOCs (Table of Contents) in longer pages.

8. Use images / diagrams where helpful

   • Architectural diagrams, flowcharts, environment diagrams make understanding easier.

9. Support for onboarding

   • Include setup instructions, prerequisites, how to run locally, how to contribute.

   • Possibly include style guides or code norms if many people contribute.

10. Versioning / Releases / Change Log

    • If your project has versions or releases, include docs for what changed.

    • Might have a page for “Upgrade guide” etc.

Start by reviewing the repository's wiki mirror and how generated wiki content handles repository files such as README and LICENSE. Compare the current structure with the suggested Home, Getting Started, Architecture, Infrastructure, Operations, and _Sidebar.md organization. Done means an agreed structure, compatible repository metadata, and reorganized, navigable documentation.