feat: enhance documentation setup with MkDocs and add beginner-friendly validation configuration

Author: dataGriff

.codebase-validation.yml

@@ -0,0 +1,61 @@
+# Beginner-Friendly Configuration
+# Perfect for developers just starting with codebase validation
+# Gentle introduction with helpful explanations and relaxed standards
+
+validation:
+  agents:
+    # 📚 Essential Files - Start with the basics
+    essential-files:
+      enabled: true
+      require_readme: true           # Every project needs a welcoming README
+      require_contributing: false    # Optional for personal projects
+      require_docs_directory: false # Can add documentation later
+      
+    # ⚙️ Git Configuration - Keep things tidy
+    git-configuration:
+      enabled: true
+      require_gitignore: true        # Essential - keeps junk out of your repo
+      require_gitattributes: false   # Advanced feature, skip for now
+      require_editorconfig: false    # Nice to have, not required initially
+      
+    # 📝 Development Standards - Learn good habits gradually
+    development-standards:
+      enabled: true
+      check_commit_history: true
+      commit_history_depth: 5        # Check only recent commits
+      require_conventional_commits: false  # Learn this later
+      validation_threshold: 0.3      # Very forgiving - 30% is enough to start
+
+  # 🎨 Output settings - Keep it simple and encouraging
+  output:
+    format: "table"                  # Pretty, human-readable output
+    verbose: false                   # Don't overwhelm with details
+
+  # 📊 Scoring - Encouraging for beginners
+  scoring:
+    pass_threshold: 0.5              # 50% score is passing - you've got this!
+    warning_threshold: 0.3           # Only warn if really struggling
+
+# 🎯 What this config does:
+# - Checks for a README (the most important file!)
+# - Makes sure you have a .gitignore (prevents common mistakes)
+# - Gently encourages good development practices
+# - Celebrates your progress rather than focusing on what's missing
+#
+# 🌱 As you grow:
+# - Enable CONTRIBUTING.md when you want collaborators  
+# - Add docs/ directory when your project gets complex
+# - Turn on conventional commits to learn industry standards
+# - Gradually increase thresholds as you improve
+#
+# 🎉 Perfect starting point for:
+# - Personal projects and learning exercises
+# - First-time open source contributors
+# - Teams adopting validation tools gradually
+# - Anyone who wants to start simple and grow
+
+# Expected minimal project structure:
+# my-awesome-project/
+# ├── README.md        # Tells people what your project does
+# ├── .gitignore       # Keeps build files and secrets safe
+# └── src/            # Your actual code

.gitignore

@@ -27,6 +27,9 @@ go.work.sum
 # env file
 .env
 
+# MkDocs build output
+site/
+
 # Editor/IDE
 # .idea/
 # .vscode/

Taskfile.yml

@@ -40,7 +40,7 @@ tasks:
 
   setup:
     desc: Set up development environment
-    deps: [install-gotestsum, install-golangci-lint]
+    deps: [install-gotestsum, install-golangci-lint, docs:install]
     cmds:
       - go mod download
 
@@ -69,27 +69,40 @@ tasks:
     deps: [build, test]
 
   docs:serve:
-    desc: Serve documentation locally using Python's built-in server
-    dir: docs
+    desc: Serve documentation using MkDocs
     cmds:
       - |
-        echo "📚 Serving documentation at http://localhost:8000"
+        echo "📚 Serving documentation with MkDocs at http://localhost:8000"
         echo "Press Ctrl+C to stop the server"
-        python3 -m http.server 8000 || python -m SimpleHTTPServer 8000
+        mkdocs serve
+
+  docs:build:
+    desc: Build static documentation site
+    cmds:
+      - mkdocs build
+      - echo "📦 Documentation built in site/ directory"
 
   docs:open:
-    desc: Open documentation in the browser
-    deps: [docs:serve]
+    desc: Serve documentation and open in browser
     cmds:
       - |
-        sleep 2
-        if command -v xdg-open > /dev/null 2>&1; then
-          xdg-open http://localhost:8000
-        elif command -v open > /dev/null 2>&1; then
-          open http://localhost:8000
-        else
-          echo "Please open http://localhost:8000 in your browser"
-        fi
+        echo "🚀 Starting MkDocs server and opening browser..."
+        (sleep 3 && (
+          if command -v xdg-open > /dev/null 2>&1; then
+            xdg-open http://localhost:8000
+          elif command -v open > /dev/null 2>&1; then
+            open http://localhost:8000
+          else
+            echo "Please open http://localhost:8000 in your browser"
+          fi
+        )) &
+        mkdocs serve
+
+  docs:install:
+    desc: Install MkDocs and required plugins
+    cmds:
+      - pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
+      - echo "📚 MkDocs installed successfully"
 
   docs:check:
     desc: Check documentation for common issues (links, formatting)

bin/codebase-cli

@@ -1,8 +1,8 @@
-site_name: Codebase Interface
-site_description: A documented set of principles that aim to promote the ease of use of codebases across languages and frameworks
-site_url: https://codebaseinterface.org
-repo_url: https://github.com/codebase-interface/codebaseinterface
-repo_name: codebase-interface/codebaseinterface
+site_name: Codebase Interface CLI
+site_description: A command-line tool for validating codebase structure and development standards
+site_url: https://cli.codebaseinterface.org
+repo_url: https://github.com/codebase-interface/cli
+repo_name: codebase-interface/cli
 edit_uri: edit/main/docs/
 
 theme:
@@ -32,7 +32,17 @@ theme:
         name: Switch to light mode
 
 nav:
-  - Welcome: README.md
+  - Home: README.md
+  - Getting Started: usage.md
+  - Configuration: configuration.md
+  - Validation Agents: agents.md
+  - Examples:
+    - Overview: examples/README.md
+    - Beginner: examples/beginner.yml
+    - Basic: examples/basic.yml
+    - Go Project: examples/go-project.yml
+    - Open Source: examples/open-source.yml
+    - Strict Standards: examples/strict.yml
 
 plugins:
   - search