asgard 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d904144543326c15257e4e61584c46fa9b0ab4f1ba522680daa930950361e6a
-  data.tar.gz: fea08260a5db1fdde268eaf4ca930b1e52a07a39f12eaf2ce20e31736319cdff
+  metadata.gz: 839554cd5b16759477245ef561d2769b6d09ea555aa592c8086c2de6bc54450b
+  data.tar.gz: 419b813aaccbd3afbe5bc70be2ada0ba4b99ce3f5fdcc0b5b246b461bc3bd76f
 SHA512:
-  metadata.gz: 9f75f50ba53970998d047e21078b120090ba6c232ac698b0ba705b84a3de542bfef313690e11d2e09989101045323c7cd6549bf51826b316ccf1beeb96ada50d
-  data.tar.gz: 497bee99076f476b8fe680962f59b369898381470b27fd59e0f7e4dc7636e620004660cbcf3ceb10a2678e65ddf78a2a7e24e6571362fc7ad3e7929eeb61a614
+  metadata.gz: 8eb7270b4a6668ea0e111f739de651753e927347dd91d5a85275a6b2e014b01ba4c3fc84261174d97f221bf36ac23a4868f3b56ba3df80041a96bf9fa9115397
+  data.tar.gz: 5fb697c0ac1dd087b1d8b521680a7a3ec277b633dfee7dab612dfce6da6ce4a7d1377b916049913f082c2f233567ef3a311cfe60b6dc1945c891ac122b1add43

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed (round 2)
+
+- **Subcommand deps not validated at startup** — `run!` only called `Tasks.validate_deps!`, so circular dependencies and undefined dep names in subcommand groups (classes that inherit from `Asgard::Base` or `Tasks`) were silently ignored. `run!` now snapshots `Asgard::Base.subclasses` before loading task files and validates every newly defined subclass alongside `Tasks`.
+- **Parallel dep thread orphaned on exception** — when a parallel dep group contained one fast-failing task and one slow task, `threads.each(&:join)` re-raised the first thread's exception and abandoned the remaining threads. The slow thread continued running unsupervised after the caller saw the exception. The join loop now collects all thread exceptions before re-raising the first, ensuring every thread completes before execution exits the group.
+- **Dep with required arguments gave a cryptic runtime error** — `depends_on :build` where `build(name)` has required parameters caused `Thor::InvocationError` at task invocation time with no indication of where the problem was. `validate_deps!` now checks the arity of every dep task via `instance_method.parameters` and raises `Asgard::Error` at startup with the task name and required argument count.
+- **Orphaned `depends_on` silently discarded** — a `depends_on` declaration at the end of a class body (or `.loki` file) with no following `desc`/`def` left `@_pending_deps` non-empty but was ignored by `validate_deps!` due to an early `return if _deps.empty?` guard. `validate_deps!` now checks `@_pending_deps` before that guard and raises `Asgard::Error` naming the orphaned dependencies.
+
+### Fixed
+
+- **Parallel dep race condition** — when two parallel tasks shared a common dependency, the second thread could start before the shared dep finished executing. `_ran_tasks` (a single Set) has been replaced with `_running` / `_done` Sets and a per-task `ConditionVariable`. Threads that arrive at an already-running dep now wait for its completion rather than skipping it; the `ensure` block broadcasts completion whether the task succeeds or raises.
+- **`depends_on` silently dropped before `var` or `no_commands`** — Thor uses an integer counter for `@no_commands` that resets to `0` (truthy in Ruby) after any `no_commands` block. The `method_added` guard now checks `@usage` instead: pending deps are only consumed when a command-defining method is added (one preceded by `desc`), so `var` declarations and `no_commands` helpers placed between `depends_on` and `def` no longer silently steal the dependency.
+- **`shebang` ignored its `silent:` keyword argument** — the parameter was accepted but never referenced; the script body is now echoed to stdout unless `silent: true` is passed, matching the behavior of `sh`.
+- **`var` lambdas re-evaluated on every access** — the accessor method now caches its result in a per-instance variable on first call. Lambdas used for computed values (e.g. `` -> { `git describe --tags`.strip } ``) now run exactly once per instance.
+
+### Changed
+
+- **`validate_deps!` detects undefined dependency names** — `depends_on :nonexistent` previously passed validation silently and produced no error at runtime. `validate_deps!` now raises `Asgard::Error` listing every dep name that does not correspond to a defined task. `run!` catches this alongside `CircularDependencyError` and exits with a clean message.
+
+## [0.2.0] - 2026-05-29
+
+### Changed
+
+- `*.loki` files are no longer auto-loaded by default. Pass `--auto-load` to `asgard` to load all `*.loki` files from the project root alphabetically before `.loki`. This is a breaking change for projects using the multi-file layout.
+- Added `--auto-load` as a built-in CLI flag in `Tasks`, visible in `asgard help`
+
+## [0.1.2] - 2026-05-29
+
+### Added
+
+- `--version` built-in CLI flag — prints `Asgard::VERSION` and exits; implemented as a `_`-prefixed method in `Tasks` per the gem-owned naming convention
+- `--debug` and `--verbose` built-in `class_option` declarations on `Tasks` — set `$DEBUG`/`$VERBOSE` before any task runs via the `invoke_command` hook in `Asgard::Base`
+- `debug?` and `verbose?` private predicate helpers on `Tasks` — thin wrappers around `$DEBUG` and `$VERBOSE` for use inside task bodies
+- `_` prefix convention for gem-owned methods in `Tasks` — built-in methods use `_` prefix to distinguish them from user-defined tasks
+- `run!` guards against direct invocation of `_`-prefixed commands with a clean error message and exit 1
+- `examples/` directory with working `.loki` files:
+  - `kitchen_sink.loki` — demonstrates the full Thor DSL (all option types, `long_desc`, `class_option`, `default_task`, `map`, `depends_on`, `var`, `no_commands`, `private`)
+  - `server_subcommands.loki` — subcommand group for server management
+  - `db_subcommands.loki` — subcommand group for database management with `depends_on` chaining
+- README sections: Helper methods, Subcommands, Thor wrapper callout
+
+### Fixed
+
+- Replaced `warn`/`exit 1` with `abort` throughout `run!` — `Kernel#warn` is silenced when `$VERBOSE = nil`, which is the default in Ruby 4.0; `abort` writes to `$stderr` regardless
+
+### Changed
+
+- `--debug` and `--verbose` promoted from mapped tasks to `class_option` — they now work as modifiers alongside other commands (e.g. `asgard build --debug`) rather than as standalone commands
+- Removed all references to `just` task runner and `recipe` terminology; Asgard uses "task" throughout
+- `depends_on` parameter renamed from `*recipes` to `*tasks` for consistency
+
 ## [0.1.1] - 2026-05-28
 ### Added
 
@@ -52,5 +102,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 100% test coverage enforced via SimpleCov (95% minimum threshold)
 - Quality task in `.loki` runs flog after tests
 
-[Unreleased]: https://github.com/MadBomber/asgard/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/MadBomber/asgard/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/MadBomber/asgard/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/MadBomber/asgard/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/MadBomber/asgard/releases/tag/v0.1.0

data/CLAUDE.md

@@ -29,7 +29,7 @@ Single test: `ruby -Ilib:test test/test_asgard.rb`
 
 `bin/asgard` → `Asgard.run!(ARGV)` (`lib/asgard.rb`):
 1. Walk CWD + ancestors for `.loki` (marker only, not a task file)
-2. Glob + sort `*.loki` files from that dir, `load` each alphabetically
+2. If `--auto-load` is in argv: glob + sort `*.loki` files and load each alphabetically
 3. Load `.loki` itself last
 4. `Tasks.validate_deps!` — build full dep graph, raise `CircularDependencyError` if cyclic
 5. `Tasks._reset_ran!` — clear execution tracking
@@ -114,4 +114,4 @@ class Tasks
 end
 ```
 
-Multiple `*.loki` files in the same directory are all loaded (alphabetically). The bare `.loki` file serves only as the project root marker — its content is loaded last.
+By default, only `.loki` is loaded. Pass `--auto-load` to `asgard` to also load all `*.loki` files in the same directory alphabetically before `.loki` is loaded. The bare `.loki` file serves as the project root marker — its content is always loaded last.

data/README.md

@@ -1,10 +1,33 @@
 # Asgard
 
-A Ruby task runner built on [Thor](https://github.com/rails/thor) for argument handling and [Dagwood](https://github.com/rewindio/dagwood) for dependency ordering.
-
-The name comes from Norse mythology: **Thor** is the CLI framework, **Asgard** is the realm where tasks live, and the task file is named **loki** — because Loki holds all the tricks.
-
-> **Asgard is a wrapper around [Thor](https://github.com/rails/thor).** Anything Thor can do — subcommands, typed options, argument validation, shell completion — is available inside a `.loki` file. Familiarity with Thor's DSL will make you immediately productive with Asgard.
+> [!INFO]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory](examples/) contains working `.loki` files demonstrating the full feature set.
+
+<br>
+<table>
+<tr>
+<td width="40%" align="center" valign="top">
+<img src="docs/assets/images/asgard.jpg" alt="Asgard"><br>
+<em>"Loki writes the tricks. Asgard runs them."</em>
+</td>
+<td width="60%" valign="top">
+<strong>Key Features</strong><br>
+
+- <strong>Thor-Powered CLI</strong> — every Thor DSL feature available inside <code>.loki</code> task files<br>
+- <strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code><br>
+- <strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads<br>
+- <strong>Subcommands</strong> — group related tasks under a named namespace<br>
+- <strong>Variables</strong> — static values and lazy-evaluated lambdas via <code>var</code><br>
+- <strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts<br>
+- <strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code><br>
+- <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
+- <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded on demand with <code>--auto-load</code><br>
+- <strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, and <code>--verbose</code> available on every task<br>
+</td>
+</tr>
+</table>
+
+<p>Asgard is a <a href="https://github.com/rails/thor">Thor</a>-based task runner for Ruby projects. Define tasks in <code>.loki</code> files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do — subcommands, typed options, argument validation — is available inside a <code>.loki</code> file.</p>
 
 ## Installation
 
@@ -55,7 +78,7 @@ asgard hello Alice
 
 ### A task with a formal argument declaration
 
-Use `argument` for richer metadata — type checking, enums, and help text:
+Use `argument` for richer metadata — type checking, enums, and help text. **Warning: `argument` is a class-level declaration that applies to every task in the class**, not just the one below it. It is best suited for single-command CLIs or when every task genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
 
 ```ruby
 class Tasks
@@ -116,7 +139,7 @@ end
 
 `depends_on` declares what must run before a task. Each dependency runs at most once per `asgard` invocation regardless of how many tasks declare it. Circular dependencies are caught at startup.
 
-`desc` and `depends_on` are independent — either can come first, both must appear before `def`.
+`desc` and `depends_on` are independent — either can come first, both must appear before `def`. `var` declarations between `depends_on` and `def` are safe and do not consume the pending dependency.
 
 ### Sequential dependencies
 
@@ -328,10 +351,14 @@ end
 
 Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
 
-Pass `silent: true` to suppress the command echo:
+Pass `silent: true` to both `sh` and `shebang` to suppress the script echo:
 
 ```ruby
-def build = sh "rake build", silent: true
+def build   = sh "rake build", silent: true
+def analyze = shebang :python3, <<~PY, silent: true
+  import json
+  print(json.load(open("data.json")))
+PY
 ```
 
 ---
@@ -443,7 +470,7 @@ Common `method_option` keys: `aliases`, `type`, `default`, `required`, `desc`, `
 
 ## Task files
 
-Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. All `*.loki` files in the same directory are auto-loaded alphabetically before `.loki` is loaded.
+Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. `*.loki` files in the same directory are loaded only when `asgard` is invoked with `--auto-load`.
 
 ### Single file
 
@@ -514,9 +541,9 @@ end
 |---|---|
 | `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
 | `Asgard.find_task_file` | Returns path to `.loki` searching from CWD upward, or nil |
-| `Asgard.load_loki(dir)` | Loads all `*.loki` files in dir alphabetically |
+| `Asgard.load_loki(dir)` | Loads all `*.loki` files in dir alphabetically — called by `run!` only when `--auto-load` is passed |
 
-`run!` handles its own errors — a missing `.loki` or a circular dependency both produce a clean one-line message and exit 1.
+`run!` handles its own errors — a missing `.loki`, a circular dependency, or a `depends_on` that names a task that doesn't exist all produce a clean one-line message and exit 1.
 
 ---
 

data/docs/api.md

@@ -0,0 +1,131 @@
+# API Reference
+
+This page documents the public Ruby API for the Asgard gem. Most users interact with Asgard through the CLI and the task DSL — this page is primarily useful when integrating Asgard into tooling or extending it programmatically.
+
+---
+
+## `Asgard` Module Methods
+
+These class methods are defined on the `Asgard` module itself.
+
+| Method | Signature | Description |
+|---|---|---|
+| `run!` | `Asgard.run!(argv)` | Main entry point. Finds `.loki`, loads all task files, validates the dependency graph, and dispatches via Thor. Handles its own errors: missing `.loki` and circular dependencies both produce a clean one-line message and `exit 1`. |
+| `find_task_file` | `Asgard.find_task_file → String, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns the absolute path string of the first match, or `nil` if none is found. |
+| `load_loki` | `Asgard.load_loki(dir)` | Loads all `*.loki` files in `dir` alphabetically, excluding `.loki` itself. Called by `run!` only when `--auto-load` is present in `argv`. |
+
+### `run!` Details
+
+```ruby
+Asgard.run!(ARGV)
+```
+
+`run!` guards against direct invocation of `_`-prefixed commands before any files are loaded:
+
+```ruby
+abort "asgard: unknown command '#{argv.first}'" if argv.first&.start_with?("_")
+```
+
+After loading task files, it calls `Tasks.validate_deps!` (circular dependency check) and `Tasks._reset_ran!` (clears per-invocation deduplication state) before starting Thor.
+
+---
+
+## `Asgard::Base` DSL Class Methods
+
+`Asgard::Base` is a `Thor` subclass that provides the task DSL. It is the superclass of `Tasks`. All DSL methods are class methods (called in the class body).
+
+| Method | Signature | Description |
+|---|---|---|
+| `depends_on` | `depends_on(*tasks)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. |
+| `var` | `var(name, value = nil, &block)` | Declare a named variable. If `value` responds to `call` (lambda/proc) or a block is given, the value is computed lazily on first access. Accessible in task bodies as a method. |
+| `import` | `import(mod)` | Include a module into the current class (thin alias for `include`). |
+| `dotenv` | `dotenv(path = ".env")` | Load the specified `.env` file into `ENV` using the dotenv gem. Silently skipped if the file does not exist. Called at class-load time. |
+| `sh` | `sh(script, silent: false)` | Instance method. Run a shell command or multiline heredoc. Single-line → `system(script)`; multiline → `system("bash", "-c", script)`. Exits with the command's status on failure. |
+| `shebang` | `shebang(interpreter, script, silent: false)` | Instance method. Write `script` to a tempfile and execute it with `interpreter`. See the [Shell Helpers](shell.md) page for the full interpreter table. |
+| `validate_deps!` | `Tasks.validate_deps!` | Build and topologically sort the full dependency graph using Dagwood. Raises `Asgard::CircularDependencyError` on cycles. Called by `run!` at startup. |
+| `_reset_ran!` | `Tasks._reset_ran!` | Clear the per-invocation task deduplication set. Called by `run!` before dispatching. Thread-safe via Mutex. |
+
+### `depends_on` Argument Shapes
+
+```ruby
+depends_on :build                          # single sequential dep
+depends_on :clean, :build                  # two sequential deps
+depends_on [:lint, :typecheck]             # lint and typecheck run in parallel
+depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently, then test
+```
+
+---
+
+## `Tasks` Built-ins
+
+`Tasks` is pre-defined by the gem as `class Tasks < Asgard::Base`. It adds the following:
+
+| Item | Type | Description |
+|---|---|---|
+| `class_option :debug` | class option | `--debug` flag. Sets `$DEBUG = true` before any task runs. Boolean, default `false`. |
+| `class_option :verbose` | class option | `--verbose` flag. Sets `$VERBOSE = true` before any task runs. Boolean, default `false`. |
+| `_version` | private task method | Implements `--version`. Prints `Asgard::VERSION` and exits. Registered via `map "--version" => :_version`. Uses `_` prefix convention. |
+| `debug?` | private instance method | Returns `$DEBUG`. Available in all task bodies and subcommand classes that inherit from `Tasks`. |
+| `verbose?` | private instance method | Returns `$VERBOSE`. Available in all task bodies and subcommand classes that inherit from `Tasks`. |
+| `--auto-load` | CLI flag (consumed by `run!`) | Triggers loading of all `*.loki` files before the main `.loki` and the requested task. Consumed by `run!` before Thor dispatch. |
+
+---
+
+## `Asgard::Base` Internal Class Methods
+
+These are implementation details exposed for extensibility. Prefer the DSL methods above in normal use.
+
+| Method | Description |
+|---|---|
+| `_deps` | Hash mapping task name symbols to their stage arrays. Set by `depends_on` + `method_added`. |
+| `_vars` | Hash mapping var name symbols to their static values or callables. |
+| `_ran_tasks` | `Set` of task name symbols that have already run in the current invocation. |
+| `_ran_mutex` | `Mutex` protecting `_ran_tasks` for thread-safe deduplication. |
+| `_build_dep_graph(stages)` | Translates the stage array (from `_deps`) into a Dagwood-compatible hash. |
+
+---
+
+## `invoke_command` Hook
+
+`Asgard::Base` overrides Thor's `invoke_command` to implement dependency resolution and deduplication:
+
+1. Sets `$DEBUG` / `$VERBOSE` from `options` if the corresponding flags are present.
+2. Checks `_ran_tasks` — skips if this task has already run.
+3. Marks the task as ran.
+4. Resolves dependency stages from `_deps`, builds the Dagwood graph, and executes groups (parallel groups in threads, sequential groups one at a time).
+5. Calls `command.run(self, *args)` to execute the task itself.
+
+---
+
+## Error Classes
+
+| Class | Superclass | Description |
+|---|---|---|
+| `Asgard::Error` | `StandardError` | Base error class for all Asgard errors. |
+| `Asgard::CircularDependencyError` | `Asgard::Error` | Raised by `validate_deps!` when a cycle is detected in the dependency graph. `run!` catches this and calls `abort` with a clean message. |
+
+```ruby
+begin
+  Asgard.run!(ARGV)
+rescue Asgard::CircularDependencyError => e
+  # This is already handled inside run! — you only need this
+  # if you call validate_deps! directly in your own tooling.
+  abort "circular dependency: #{e.message}"
+end
+```
+
+---
+
+## Dependencies
+
+| Gem | Version | Purpose |
+|---|---|---|
+| [thor](https://github.com/rails/thor) | `~> 1.0` | CLI framework; provides the full task DSL |
+| [dagwood](https://rubygems.org/gems/dagwood) | `~> 1.0` | DAG library for dependency graph resolution and topological sort |
+| [dotenv](https://github.com/bkeepers/dotenv) | `~> 3.0` | `.env` file loading |
+
+---
+
+## Ruby Version Requirement
+
+Asgard requires **Ruby >= 3.2.0**.

data/docs/assets/css/custom.css

@@ -0,0 +1,93 @@
+/* ==========================================================================
+   Asgard documentation — custom styles
+   Material theme handles the heavy lifting; this file adds targeted polish.
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   .loki filename display
+   Used whenever the filename ".loki" or "*.loki" appears inline or in code.
+   -------------------------------------------------------------------------- */
+
+/* Give inline code that looks like a .loki filename a subtle Norse-gold tint */
+code:is([class*="language-"]) .token.string:has-text(".loki"),
+.md-typeset code.loki-file {
+  color: var(--md-accent-fg-color);
+  font-weight: 600;
+}
+
+/* Highlight .loki filenames in directory tree code blocks */
+.md-typeset .highlight .filename {
+  background-color: color-mix(in srgb, var(--md-primary-fg-color) 12%, transparent);
+  border-bottom: 2px solid var(--md-accent-fg-color);
+  border-radius: 4px 4px 0 0;
+  color: var(--md-default-fg-color);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  padding: 0.3rem 0.8rem;
+}
+
+/* --------------------------------------------------------------------------
+   Admonition tweaks — slightly warmer warning border for the "argument"
+   class-level scope warning that appears on the tasks page.
+   -------------------------------------------------------------------------- */
+
+.md-typeset .admonition.warning,
+.md-typeset details.warning {
+  border-left-color: #e6a817;
+}
+
+.md-typeset .admonition.warning > .admonition-title,
+.md-typeset details.warning > summary {
+  background-color: rgba(230, 168, 23, 0.12);
+}
+
+/* --------------------------------------------------------------------------
+   Table of Contents — emphasise the current section a touch more
+   -------------------------------------------------------------------------- */
+
+.md-nav__link--active {
+  font-weight: 600;
+}
+
+/* --------------------------------------------------------------------------
+   Home page feature table (HTML table in index.md)
+   -------------------------------------------------------------------------- */
+
+.md-typeset table:not([class]) td {
+  vertical-align: top;
+}
+
+/* --------------------------------------------------------------------------
+   Execution diagram in dependencies.md — keep it tight and readable
+   -------------------------------------------------------------------------- */
+
+.md-typeset pre code {
+  font-size: 0.85em;
+  line-height: 1.5;
+}
+
+/* --------------------------------------------------------------------------
+   Subtle Norse-shield watermark on the hero block (index page only).
+   Relies on the Material "primary: indigo" palette.
+   -------------------------------------------------------------------------- */
+
+.md-header {
+  box-shadow: 0 2px 8px rgba(63, 81, 181, 0.25);
+}
+
+/* --------------------------------------------------------------------------
+   Code annotations — keep them readable across both light and dark palettes
+   -------------------------------------------------------------------------- */
+
+.md-typeset .md-annotation__index > * {
+  font-size: 0.7rem;
+}
+
+/* --------------------------------------------------------------------------
+   Task-runner specific: distinguish shell prompt lines from output lines
+   in bash code blocks by dimming lines that don't start with '#' or 'asgard'
+   -------------------------------------------------------------------------- */
+
+/* (Future: add targeted styles once MkDocs Material supports per-line
+   highlighting via config; for now this is intentionally minimal.) */

data/docs/changelog.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to Asgard are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asgard adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+## [0.2.0] — 2026-05-29
+
+### Changed
+
+- `*.loki` files are no longer auto-loaded by default. Pass `--auto-load` to `asgard` to load all `*.loki` files from the project root alphabetically before `.loki`. This is a breaking change for projects using the multi-file layout.
+- Added `--auto-load` as a built-in CLI flag in `Tasks`, visible in `asgard help`
+
+---
+
+## [0.1.2] — 2026-05-29
+
+### Added
+
+- `--version` built-in CLI flag — prints `Asgard::VERSION` and exits; implemented as a `_`-prefixed method in `Tasks` per the gem-owned naming convention
+- `--debug` and `--verbose` built-in `class_option` declarations on `Tasks` — set `$DEBUG`/`$VERBOSE` before any task runs via the `invoke_command` hook in `Asgard::Base`
+- `debug?` and `verbose?` private predicate helpers on `Tasks` — thin wrappers around `$DEBUG` and `$VERBOSE` for use inside task bodies
+- `_` prefix convention for gem-owned methods in `Tasks` — built-in methods use `_` prefix to distinguish them from user-defined tasks
+- `run!` guards against direct invocation of `_`-prefixed commands with a clean error message and exit 1
+- `examples/` directory with working `.loki` files:
+  - `kitchen_sink.loki` — demonstrates the full Thor DSL (all option types, `long_desc`, `class_option`, `default_task`, `map`, `depends_on`, `var`, `no_commands`, `private`)
+  - `server_subcommands.loki` — subcommand group for server management
+  - `db_subcommands.loki` — subcommand group for database management with `depends_on` chaining
+  - `concurrent.loki` — demonstrates parallel task execution with interleaved thread output
+- README sections: Helper methods, Subcommands, Thor wrapper callout
+
+### Fixed
+
+- Replaced `warn`/`exit 1` with `abort` throughout `run!` — `Kernel#warn` is silenced when `$VERBOSE = nil`, which is the default in Ruby 4.0; `abort` writes to `$stderr` regardless
+
+### Changed
+
+- `--debug` and `--verbose` promoted from mapped tasks to `class_option` — they now work as modifiers alongside other commands (e.g. `asgard build --debug`) rather than as standalone commands
+- Removed all references to `just` task runner and `recipe` terminology; Asgard uses "task" throughout
+- `depends_on` parameter renamed from `*recipes` to `*tasks` for consistency
+
+---
+
+## [0.1.1] — 2026-05-28
+
+### Added
+
+- Parallel dependency execution — wrap deps in an array to run them concurrently:
+  `depends_on [:build, :lint]` or `depends_on :setup, [:build, :lint], :deploy`
+- `Asgard.run!(argv)` — single entry point encapsulating find, load, validate, and start
+- `Asgard.load_loki(dir)` — auto-loads all `*.loki` files in a directory alphabetically
+- `Tasks` class pre-defined by the gem (`class Tasks < Asgard::Base`) — task files reopen it without restating the superclass
+- `lib/asgard/tasks.rb` — ships the pre-defined `Tasks` class
+
+### Changed
+
+- Replaced `SimpleFlow` dependency with `Dagwood` — purpose-built DAG library with no extra dependencies and no Ruby 4 compatibility issues
+- `bin/asgard` simplified to two lines: `require "asgard"` + `Asgard.run!(ARGV)`
+- Task file convention: `.loki` is the project root marker and entry point; `*.loki` files each reopen `class Tasks` and are auto-loaded before `.loki`
+- `Asgard.find_task_files` renamed to `Asgard.find_task_file` (singular — only `.loki` is the entry point)
+- `depends_on` now accepts mixed sequential/parallel stages; bare symbols run sequentially, arrays within the splat run in parallel
+- `run!` handles its own errors — missing `.loki` and circular dependencies produce a clean one-line message and exit 1 rather than a backtrace
+- Thread-safe dep deduplication via class-level `_ran_tasks` Set + Mutex replaces Thor's `@_invocations`
+- Removed `import` macro — task files use Ruby class reopening instead of modules
+
+### Removed
+
+- `SimpleFlow` dependency (replaced by `Dagwood`)
+- `logger` gem workaround (was only needed for SimpleFlow on Ruby 4)
+- `*.loki` glob fallback in `find_task_file` — only `.loki` is the auto-discovered entry point
+
+---
+
+## [0.1.0] — 2026-05-28
+
+### Added
+
+- `Asgard::Base` — Thor subclass providing the task DSL
+- `depends_on` — declare task dependencies; dependencies run at most once per invocation
+- `var` — declare static or lazy-evaluated variables available to all tasks
+- `import` — flat-merge a task module into the current class
+- `dotenv` — load a `.env` file into the environment
+- `sh` — run a shell command or multiline heredoc script; exits with the command's status on failure
+- `shebang` — write a script body to a tempfile and execute it with a given interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`, or any custom interpreter)
+- `Asgard.find_task_files` — search current directory and ancestors for task files
+- Task file resolution: `.loki` takes priority; falls back to all `*.loki` files sorted alphabetically
+- `asgard` executable — finds task files, validates dependency graph, dispatches via Thor
+- Circular dependency detection via `SimpleFlow::DependencyGraph` at startup
+- 100% test coverage enforced via SimpleCov (95% minimum threshold)
+- Quality task in `.loki` runs flog after tests
+
+[Unreleased]: https://github.com/MadBomber/asgard/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/MadBomber/asgard/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/MadBomber/asgard/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/MadBomber/asgard/releases/tag/v0.1.0