feat: separate CLI version from Amber framework version

- Remove hardcoded Amber::VERSION that referenced CLI version
- Add configurable amber_framework_version to generator system
- Update shard.yml.ecr template to use {{amber_framework_version}} variable
- Add built-in template variables: cli_version and amber_framework_version
- Clean up documentation with :nodoc: directives for internal modules
- Hide legacy/internal modules from public documentation
- Reduce documentation from 84 to 39 HTML files (58% reduction)
- Focus documentation on user-facing commands and comprehensive guides

This allows the CLI tool to be versioned independently from the Amber
framework version used when creating new applications. Teams can now:
- Pin projects to specific Amber framework versions
- Test with different framework versions
- Maintain compatibility with existing projects
- Upgrade the CLI tool without changing framework dependencies

Author: crimson-knight

shard.yml

@@ -35,9 +35,6 @@ dependencies:
     github: crystal-loot/exception_page
     version: ~> 0.2.1
 
-  # inflector library has been vendored into src/amber_cli/vendor/inflector/
-  # with improvements and fixes (foot->feet, tooth->teeth, etc.)
-
   # CLI tool item, specifically for when distributing a compiled binary (like the CLI tool will be)
   compiled_license:
     github: elorest/compiled_license

src/amber_cli/commands.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 require "../version"
 require "./config"
 

src/amber_cli/config.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 require "yaml"
 
 module Amber::CLI

src/amber_cli/core/base_command.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 require "option_parser"
 
 module AmberCLI::Core

src/amber_cli/core/configurable_generator_manager.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 require "./generator_config"
 require "./template_engine"
 require "./word_transformer"
@@ -26,7 +27,10 @@ module AmberCLI::Core
 
       begin
         generator_rules.each do |rule|
-          generated_files = @template_engine.generate_file_from_rule(rule, name, template_dir, template_variables, naming_conventions)
+          # Get amber framework version from config, defaulting to current stable version
+          amber_version = template_variables["amber_framework_version"]? || "1.4.0"
+          
+          generated_files = @template_engine.generate_file_from_rule(rule, name, template_dir, template_variables, naming_conventions, amber_version)
 
           generated_files.each do |file_info|
             # Create directory if needed

src/amber_cli/core/generator_config.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 require "json"
 require "yaml"
 

src/amber_cli/core/template_engine.cr

@@ -1,3 +1,6 @@
+# :nodoc:
+require "ecr"
+require "file_utils"
 require "../exceptions"
 require "./word_transformer"
 require "./generator_config"
@@ -24,7 +27,7 @@ module AmberCLI::Core
       result
     end
 
-    def generate_file_from_rule(rule : FileGenerationRule, word : String, template_dir : String, custom_variables : Hash(String, String), naming_conventions : Hash(String, String) = {} of String => String) : Array(NamedTuple(path: String, content: String))
+    def generate_file_from_rule(rule : FileGenerationRule, word : String, template_dir : String, custom_variables : Hash(String, String), naming_conventions : Hash(String, String) = {} of String => String, amber_framework_version : String = "1.4.0") : Array(NamedTuple(path: String, content: String))
       # Check conditions first
       if conditions = rule.conditions
         return [] of NamedTuple(path: String, content: String) unless meets_conditions?(conditions, custom_variables)
@@ -41,6 +44,10 @@ module AmberCLI::Core
       # Build replacement context
       replacements = custom_variables.dup
 
+              # Add built-in variables
+        replacements["cli_version"] = AmberCli::VERSION
+        replacements["amber_framework_version"] = amber_framework_version
+
       # Add word transformations
       if transformations = rule.transformations
         transformations.each do |placeholder, transformation|

src/amber_cli/core/word_transformer.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 require "../vendor/inflector/inflector"
 
 module AmberCLI::Core
@@ -70,6 +71,11 @@ module AmberCLI::Core
       # Note: "feet" -> "foot" is now fixed in our vendored inflector
     }
 
+    # Built-in variables that can be used in templates
+    BUILT_IN_VARIABLES = {
+      "cli_version" => AmberCli::VERSION,
+    }
+
     # Transforms a word using the specified transformation type.
     #
     # Checks for custom conventions first, allowing any transformation to be overridden

src/amber_cli/documentation.cr

@@ -594,6 +594,105 @@ module AmberCLI::Documentation
   #     include:
   #       - "./spec/**/*.cr"
   # ```
+  #
+  # # Configuration Reference
+  #
+  # Amber CLI uses several configuration mechanisms to customize behavior
+  # for different project types and development workflows.
+  #
+  # ## Project Configuration (`.amber.yml`)
+  #
+  # The `.amber.yml` file in your project root configures project-specific settings:
+  #
+  # ```yaml
+  # database: pg                    # Database type: pg, mysql, sqlite
+  # language: slang                 # Template language: slang, ecr
+  # model: granite                  # ORM: granite, jennifer
+  # watch:
+  #   run:
+  #     build_commands:
+  #       - "crystal build ./src/my_app.cr -o bin/my_app"
+  #     run_commands:
+  #       - "bin/my_app"
+  #     include:
+  #       - "./config/**/*.cr"
+  #       - "./src/**/*.cr"
+  # ```
+  #
+  # ## Generator Configuration
+  #
+  # Custom generators can be configured using JSON or YAML files in the
+  # `generator_configs/` directory:
+  #
+  # ### Basic Generator Configuration
+  #
+  # ```yaml
+  # name: "custom_model"
+  # description: "Generate a custom model with validation"
+  # template_directory: "templates/models"
+  # amber_framework_version: "1.4.0"    # Amber framework version for new projects
+  # custom_variables:
+  #   author: "Your Name"
+  #   license: "MIT"
+  # naming_conventions:
+  #   table_prefix: "app_"
+  # file_generation_rules:
+  #   - template_file: "model.cr.ecr"
+  #     output_path: "src/models/{{snake_case}}.cr"
+  #     transformations:
+  #       class_name: "pascal_case"
+  # ```
+  #
+  # ### Framework Version Configuration
+  #
+  # The `amber_framework_version` setting determines which version of the Amber 
+  # framework gets used when creating new applications. This is separate from the
+  # CLI tool version and allows you to:
+  #
+  # - Pin projects to specific Amber versions
+  # - Test with different framework versions
+  # - Maintain compatibility with existing projects
+  #
+  # Available template variables:
+  # - `{{cli_version}}` - Current Amber CLI version
+  # - `{{amber_framework_version}}` - Configured Amber framework version
+  # - All word transformations (snake_case, pascal_case, etc.)
+  #
+  # ### Advanced Generator Features
+  #
+  # #### Conditional File Generation
+  #
+  # ```yaml
+  # file_generation_rules:
+  #   - template_file: "api_spec.cr.ecr"
+  #     output_path: "spec/{{snake_case}}_spec.cr"
+  #     conditions:
+  #       generate_specs: "true"
+  # ```
+  #
+  # #### Custom Transformations
+  #
+  # ```yaml
+  # naming_conventions:
+  #   namespace_prefix: "MyApp::"
+  #   table_prefix: "my_app_"
+  # transformations:
+  #   full_class_name: "pascal_case"  # Will use namespace_prefix
+  # ```
+  #
+  # ## Environment Configuration
+  #
+  # Environment-specific settings go in `config/environments/`:
+  #
+  # ```yaml
+  # # config/environments/development.yml
+  # database_url: "postgres://localhost/myapp_development"
+  # amber_framework_version: "1.4.0"
+  # 
+  # # config/environments/production.yml  
+  # database_url: ENV["DATABASE_URL"]
+  # amber_framework_version: "1.4.0"
+  # ```
   class ConfigurationReference
   end
 

src/amber_cli/exceptions.cr

@@ -1,3 +1,4 @@
+# :nodoc:
 module AmberCLI::Exceptions
   class TemplateError < Exception
     def initialize(message : String)