docs: document the codebase with descriptive comments

Add class/module and method-level comments explaining the resolution
pipeline (CLI -> TaskFactory -> Tasks -> Commands -> Executor), the config
merge engine and its macros, directory conventions, and the config models.
Keeps the existing :nodoc: markers since this is an application, not a library.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: n-rodriguez

src/admiral_patch.cr

@@ -1,3 +1,7 @@
+# Monkey-patch on Admiral's base command adding uniform handling for unknown
+# subcommands/flags: run the block, and on any `Admiral::Error` print the error
+# (only when arguments were actually given) followed by the help text and exit 1.
+# Every command's `run` wraps its `super` in this.
 class Admiral::Command
   def rescue_unknown_cmd(&)
     begin

src/squarectl.cr

@@ -19,29 +19,42 @@ require "./admiral_patch"
 # Load squarectl
 require "./squarectl/**"
 
+# Top-level namespace and configuration holder.
+#
+# The parsed configuration is kept in class-level state (`@@config`,
+# `@@environments`, `@@environment_all`) so that any component can reach it via
+# `Squarectl.config` without threading it through. Because this state is global,
+# specs must call `reset_config!` between examples (see `spec/spec_helper.cr`).
 module Squarectl
   VERSION = {{ `shards version #{__DIR__}`.chomp.stringify }}
   GIT_REF = {{ `git log -n 1 --format="%H" | head -c 8`.chomp.stringify }}
 
   @@environment_all : Squarectl::Config::SquarectlEnvironment?
 
+  # Human-readable version string, e.g. `1.6.0 (7347781a)`.
   def self.version
     "#{VERSION} (#{GIT_REF})"
   end
 
+  # Reads the config file, renders it as a Crinja (Jinja) template with the
+  # current process environment exposed as `ENV`, then parses the result as YAML.
+  # This is why `{{ ENV.FOO }}` works inside `squarectl.yml`.
   def self.load_config(config_path)
     config_file = File.read(config_path)
     rendered = Crinja.render(config_file, {"ENV" => env_vars_to_hash})
     self.config = Squarectl::Config::SquarectlConfig.from_yaml(rendered)
     self.environments = config.environments
   end
 
+  # Clears the cached config so a fresh one can be loaded. Used by the test suite.
   def self.reset_config!
     @@config = nil
     @@environments = nil
     @@environment_all = nil
   end
 
+  # Snapshot of the process environment as a plain hash, injected into the
+  # Crinja template context.
   def self.env_vars_to_hash
     hash = Hash(String, String).new
     ENV.each { |k, v| hash[k] = v }
@@ -64,10 +77,16 @@ module Squarectl
     @@environments || [] of Squarectl::Config::SquarectlEnvironment
   end
 
+  # The special `all` environment holding global defaults that `TaskFactory`
+  # merges into every other environment. Returns `nil` when not defined.
   def self.environment_all
     @@environment_all ||= environments.not_nil!.find { |e| e.name == "all" } # ameba:disable Lint/NotNil
   end
 
+  # Resolves the environment selected on the command line for the given target.
+  # Matching is substring-based (`name.includes?`), so `prod` matches `production`.
+  # Raises on an unknown target/environment, and forbids any non-`compose` target
+  # on the `development` environment.
   def self.find_environment(environment, target)
     raise "Target not found: #{target}" if !%w[compose swarm kubernetes].includes?(target)
     env = environments.not_nil!.find(&.name.includes?(environment)) # ameba:disable Lint/NotNil
@@ -76,6 +95,8 @@ module Squarectl
     env
   end
 
+  # Whether the config requests Compose v1 (`docker-compose`) instead of v2
+  # (`docker compose`). Drives the command prefix in `Commands::Compose`.
   def self.compose_v1?
     config.compose["version"] == 1
   end
@@ -84,28 +105,40 @@ module Squarectl
     config.app
   end
 
+  # Project directory conventions, all relative to the current working directory:
+  #   root_dir/                       # the project (cwd)
+  #   root_dir/kubernetes/<env>/      # generated Kubernetes manifests
+  #   root_dir/squarectl/             # data_dir: base.yml lives here
+  #   root_dir/squarectl/targets/     # per-target compose files (<target>/common.yml, <target>/<env>.yml)
+  #   root_dir/squarectl/targets/common/  # extra compose files referenced by config
   def self.root_dir
     Path.new(Dir.current)
   end
 
+  # :ditto:
   def self.kubernetes_dir
     root_dir.join("kubernetes")
   end
 
+  # :ditto:
   def self.data_dir
     root_dir.join("squarectl")
   end
 
+  # :ditto:
   def self.targets_dir
     data_dir.join("targets")
   end
 
+  # :ditto:
   def self.targets_common_dir
     targets_dir.join("common")
   end
 end
 
-# Start the CLI
+# Start the CLI, unless we are running under the spec suite (which requires the
+# module without wanting the command dispatcher to fire). Any uncaught exception
+# is reported as a message and turned into a non-zero exit code.
 unless Crystal.env.test?
   begin
     Squarectl::CLI.run

src/squarectl/cli.cr

@@ -1,4 +1,12 @@
 module Squarectl
+  # Root of the Admiral command tree and the program entry point.
+  #
+  # Each top-level subcommand (defined under `cli/`) registers its own leaf
+  # commands. Every leaf follows the same shape: load the config, resolve the
+  # environment for its target, build a `Task`, and hand off to a `Tasks::*`
+  # class. `rescue_unknown_cmd` (see `admiral_patch.cr`) prints help instead of
+  # crashing on an unknown subcommand.
+  #
   # :nodoc:
   class CLI < Admiral::Command
     define_version Squarectl.version

src/squarectl/cli/completion.cr

@@ -1,6 +1,8 @@
 module Squarectl
   class CLI < Admiral::Command
     class Completion < Admiral::Command
+      # Prints the embedded Bash completion script so it can be sourced, e.g.
+      # `source <(squarectl completion bash)`.
       class Bash < Admiral::Command
         def run
           file = Squarectl::ShellCompletion.get("bash.sh")

src/squarectl/commands/compose.cr

@@ -1,12 +1,19 @@
 module Squarectl
   module Commands
+    # Builds and runs `docker compose` (or `docker-compose` on v1) commands.
+    # Mixed into `Task`; used directly by the `compose` target and reused by the
+    # `kube` target to render the merged compose config before conversion.
     module Compose
+      # docker-compose global flags that must appear *before* the action verb.
+      # `PRE_ARGS_BOOL` take no value; `PRE_ARGS_FLAGS` take a following value (or
+      # `--flag=value`). Everything else is treated as a post-action argument.
       PRE_ARGS_BOOL = [
         "--all-resources",
         "--compatibility",
         "--dry-run",
       ]
 
+      # :ditto:
       PRE_ARGS_FLAGS = [
         "--ansi",
         "--env-file",
@@ -31,12 +38,19 @@ module Squarectl
         @executor.exec_command(tuple[:cmd], args: tuple[:args], env: task_env_vars)
       end
 
+      # Assembles the full argv:
+      #   <compose> --project-name <name> --file ... <pre-args> <action> <post-args>
+      # On v2 the command is `docker` with a `compose` prefix arg; on v1 it is
+      # `docker-compose` with no prefix (dropped via `compact`).
       def build_docker_compose_command(action, args)
         cmd, prefix = Squarectl.compose_v1? ? {"docker-compose", nil} : {"docker", "compose"}
         pre_args, post_args = extract_docker_args(args)
         {cmd: cmd, args: [prefix, "--project-name", project_name, compose_files_args(prefix: "--file"), pre_args, action, post_args].compact.flatten}
       end
 
+      # Splits user-supplied args into those that belong before the action verb
+      # (matched against `PRE_ARGS_BOOL`/`PRE_ARGS_FLAGS`, consuming a value for
+      # the latter) and everything else, which goes after.
       def extract_docker_args(args)
         pre_args = [] of String
         post_args = [] of String

src/squarectl/commands/configs.cr

@@ -1,5 +1,7 @@
 module Squarectl
   module Commands
+    # Creates/removes Docker Swarm configs on the deploy server, piping each
+    # source file into `docker config create` via stdin. Mixed into `Task`.
     module Configs
       def create_docker_configs(args)
         deploy_configs.each do |key, file|

src/squarectl/commands/info.cr

@@ -1,5 +1,8 @@
 module Squarectl
   module Commands
+    # Renders the fully resolved task (paths, env vars, files, certs, configs,
+    # secrets) as YAML for the `info` command — the introspection view of what
+    # squarectl would actually run. Mixed into `Task`.
     module Info
       def squarectl_environment
         {

src/squarectl/commands/kompose.cr

@@ -1,5 +1,8 @@
 module Squarectl
   module Commands
+    # Runs `kompose` to convert a Compose configuration into Kubernetes
+    # manifests. `run_kompose_convert` feeds it the already-rendered compose
+    # config via a tempfile. Mixed into `Task`.
     module Kompose
       def run_kompose_convert(config, args)
         tempfile = File.tempfile("docker-compose", &.print(config))

src/squarectl/commands/kubectl.cr

@@ -1,5 +1,8 @@
 module Squarectl
   module Commands
+    # Applies the generated Kubernetes manifests (`kubectl apply -f`) and runs
+    # setup commands inside pods, resolving the pod name from the
+    # kompose-generated `io.kompose.service` label. Mixed into `Task`.
     module Kubectl
       def run_kubectl_apply
         args = ["apply", "-f", environment.kubernetes_dir.to_s]

src/squarectl/commands/networks.cr

@@ -1,5 +1,7 @@
 module Squarectl
   module Commands
+    # Creates/removes the external Docker networks declared for the task
+    # (before `compose up`, torn down on `clean`). Mixed into `Task`.
     module Networks
       def create_docker_networks
         compose_networks.each do |net|