feat: add benefits documentation for users and contributors, and update navigation

Author: dataGriff

docs/benefits.md

@@ -0,0 +1,23 @@
+# Benefits
+
+Benefits can be broken down per codebase audience type as they have been defined up-front. This is a benefit in itself as it allows to be considerate and then specific about the needs of each audience.
+
+## Users
+
+- Users expect to interact with the codebase via a specific entry point that is the README.
+- Users get a consistent experience across codebases and have expectations that can either be met or missed.
+- Users understanding when expectations are missed promotes feedback and improvement.
+- Users should be able to interact with the service based on the good user interface provided by the codebase.
+
+## Contributors
+
+- Contributors expect to interact with the codebase via a specific entry point that is the README.
+- Contributors get a consistent experience across codebases and have expectations that can either be met or missed.
+- Contributors understanding when expectations are missed promotes feedback and improvement.
+- Contributors should be able to make changes to the code base based on the good contributor interface provided by the codebase.
+
+## Operators
+
+## AI Agents
+
+## Build Agents

docs/index.md

@@ -10,28 +10,3 @@
 6. Do not be constrained by current technology and tools - provoke change to how we would like to interact with codebases over current constraints.
 7. Utilise cross platform and cross IDE tools and technologies to provide the interfaces.
 8. Empathise with your own future self who could become any of the audience perspectives at any time.
-
-## Benefits
-
-Benefits can be broken down per codebase audience type as they have been defined up-front. This is a benefit in itself as it allows to be considerate and then specific about the needs of each audience.
-
-### Users
-
-- Users expect to interact with the codebase via a specific entry point that is the README.
-- Users get a consistent experience across codebases and have expectations that can either be met or missed.
-- Users understanding when expectations are missed promotes feedback and improvement.
-- Users should be able to interact with the service based on the good user interface provided by the codebase.
-
-### Contributors
-
-- Contributors expect to interact with the codebase via a specific entry point that is the README.
-- Contributors get a consistent experience across codebases and have expectations that can either be met or missed.
-- Contributors understanding when expectations are missed promotes feedback and improvement.
-- Contributors should be able to make changes to the code base based on the good contributor interface provided by the codebase.
-
-### Operators
-
-### AI Agents
-
-### Build Agents
-

mkdocs.yml

@@ -16,6 +16,7 @@ theme:
     - search.share
     - content.code.copy
     - content.action.edit
+    - toc.integrate
   palette:
     - scheme: default
       primary: blue
@@ -32,6 +33,8 @@ theme:
 
 nav:
   - Home: index.md
+  - Benefits: benefits.md
+
 
 plugins:
   - search