feat(docs): refine documentation content and structure for clarity and consistency

Author: vp

README.md

@@ -52,7 +52,7 @@ the [CHANGELOG](https://raw.githubusercontent.com/bridgingIT/bITdevKit/main/CHAN
 
 ## Documentation
 
-The public documentation site is available at
+The documentation site is available at
 [bridgingit-gmbh.github.io/bITdevKit](https://bridgingit-gmbh.github.io/bITdevKit/).
 
 The best entry point into the current documentation set is the

docs/site/architecture.md

@@ -93,8 +93,3 @@ sequenceDiagram
 - [Requester and Notifier](reference/features-requester-notifier.md)
 - [Modules](reference/features-modules.md)
 - [Presentation Endpoints](reference/features-presentation-endpoints.md)
-
-## Related decisions
-
-- [Messaging vs Queueing](decisions-messaging-vs-queueing.md)
-- [Repository vs ActiveEntity](decisions-repository-vs-activeentity.md)

docs/site/examples.md

@@ -50,11 +50,4 @@ Path:
 Best for:
 
 - a lighter-weight example
-- fast experimentation with less surface area
-
-## Suggested progression
-
-1. Start with [Getting Started](getting-started.md)
-2. Run the `GettingStarted` example
-3. Read the [DDD Introduction](reference/introduction-ddd-guide.md)
-4. Move to `DoFiesta` or `EventSourcingDemo` depending on the scenario of interest
+- fast experimentation with less surface area

docs/site/index.md

@@ -54,7 +54,7 @@ hide:
   </a>
   <a class="gateway-card" href="reference/">
     <h3>Read the docs</h3>
-    <p>Browse the full public documentation map by capability area and feature-specific guide.</p>
+    <p>Browse the documentation map by capability area and feature-specific guide.</p>
   </a>
 </div>
 

docs/site/why.md

@@ -61,12 +61,4 @@ structure to be more intentional and more repeatable.
 | Modular boundaries | Manual conventions | First-class module composition patterns |
 | Queueing and messaging | Usually added separately | Integrated concepts with related operational support |
 | Operational endpoints | Typically custom | Reusable patterns for inspection and control |
-| Onboarding | Team-specific | Templates, examples, and aligned docs |
-
-## Good next pages
-
-- [Architecture](architecture.md)
-- [Packages](packages.md)
-- [Examples](examples.md)
-- [Messaging vs Queueing](decisions-messaging-vs-queueing.md)
-- [Repository vs ActiveEntity](decisions-repository-vs-activeentity.md)
+| Onboarding | Team-specific | Templates, examples, and aligned docs |

docs/specs/spec-gh-pages-landing-page.md

@@ -151,7 +151,7 @@ The public site content shall be curated rather than directly exposing all repos
 That means:
 
 - landing-page content is authored specifically for the site
-- public documentation pages are selected, adapted, or synchronized from suitable repository docs
+- Documentation pages are selected, adapted, or synchronized from suitable repository docs
 - internal or low-signal documentation remains outside the public site
 
 The public site is therefore a curated documentation product, not just a renderer over arbitrary repository files.

mkdocs.yml

@@ -17,10 +17,10 @@ nav:
   - Architecture: architecture.md
   - Packages: packages.md
   - Examples: examples.md
-  - Decisions:
-      - Overview: decisions.md
-      - Messaging vs Queueing: decisions-messaging-vs-queueing.md
-      - Repository vs ActiveEntity: decisions-repository-vs-activeentity.md
+  # - Decisions:
+  #     - Overview: decisions.md
+  #     - Messaging vs Queueing: decisions-messaging-vs-queueing.md
+  #     - Repository vs ActiveEntity: decisions-repository-vs-activeentity.md
   - Documentation:
       - Overview: reference/index.md
       - Common Infrastructure: