lux-hammer 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62eaadbe6e088375e7762d4b16050df8b17f3242a5e92bf611776ff58b3c3e91
-  data.tar.gz: 765045381a51f5e6cea55f8250ed0543ead5ba67f765241a3e8db3faa108d92b
+  metadata.gz: 7e19b144891467fd0209c27265352a153f340820d14384d8deacb46e8ef58532
+  data.tar.gz: 279c7ac83d6f597d28e42b799e5cfdc917b0ce10f88d2950d9f0fe562ed674de
 SHA512:
-  metadata.gz: 9de3baba0031948bb5e11c37f282b6d8e0af7a33d703d69f4d6c7026473f1985207c186882a19c313454cdc6e0eea310a109f708a393b269e1c043695d4daf0d
-  data.tar.gz: ff7e9f42651d68b8ba7f3f649693fc66171dc758d9b98f3ff58859f16419ebbeee976bae4931b4d4008acaad9b7635f5250a24d6e2f49df823ce47ea5e882c46
+  metadata.gz: e9baea7eb17ad8b98ec3f7778431c603a03283e029a95e9140f83026aa88f587e01a4e87bf7dc09b6538a95f463f067293daf147df02e3454f161d737c9e6bad
+  data.tar.gz: 4b41c8875111734dfbe6402b97eaa03be209081f3086096cde94343eacbb1c5fd18d2933575ad1818ca08e6ffae363fd695cb107d5ddb7068610580bd04b7289

data/.version

@@ -1 +1 @@
-0.3.6
+0.3.7

data/AGENTS.md

@@ -45,7 +45,7 @@ lib/hammer/loader.rb        # `*_hammer.rb` fragment loader (auto/glob/file)
 lib/hammer/builder.rb       # Block-DSL context (Hammerfile / Hammer.run)
 lib/hammer/command_builder.rb # `task :name do ... end` context
 lib/hammer/recipe.rb        # Recipe discovery (gem + user dir, desc, stub)
-lib/hammer/builtins.rb      # Lazy-loaded `self:` namespace (recipe, ai, update)
+lib/hammer/builtins.rb      # Built-in tasks (recipes, update, agents, version, init, ...)
 recipes/                    # Bundled recipes (each `<name>.rb` -> a bin via stub)
 test/dsl_test.rb            # DSL surface, dispatch, help formatting
 test/load_test.rb           # `load` / `*_hammer.rb` fragment loader
@@ -143,11 +143,20 @@ Runtime cross-invocation:
   (`bin/hammer`).
 * `Hammer.cli(argv = ARGV)` - internal entry for `bin/hammer` only:
   walks up from `Dir.pwd` for a `Hammerfile`, chdirs into its dir,
-  errors if none found anywhere up the tree. Also lazy-registers the
-  `self:` namespace when argv shows the user wants help or a
-  `self:`-prefixed command. Not part of the user-facing surface -
-  don't recommend it in examples; `Hammer.run` is what library users
-  should reach for.
+  errors if none found anywhere up the tree (unless the invocation
+  routes to a built-in - see `dispatches_to_builtin?` /
+  `looks_like_builtin?`, true for bare invocation / leading flag /
+  explicit help / a built-in task name). After evaluating the
+  Hammerfile, registers the always-on core built-ins (`:default`,
+  `:help`, `:update`, `:agents`, `:version`) via
+  `Hammer::Builtins.register_core` - each guarded by
+  `unless commands.key?(...)` so a user-defined task wins silently.
+  No-project-only built-ins (`:recipes`, `:init`) are NOT registered
+  when a Hammerfile loaded - reach them with `--system`. The
+  `--system` flag is peeled off argv at the top and forces the
+  no-Hammerfile branch. Not part of the user-facing surface - don't
+  recommend it in examples; `Hammer.run` is what library users should
+  reach for.
 * `Hammer.recipe(name, argv = ARGV)` - entry for recipe stubs in PATH.
   Loads `<gem>/recipes/<name>.rb` (or its user-dir override), runs as
   a standalone CLI with `program_name = name`. No Hammerfile lookup,
@@ -186,7 +195,9 @@ explicit ADR-level discussion. Keys:
   actually picked when fuzzy matching kicks in. Only options that
   differ from their default are listed; booleans render as `--flag`
   / `--no-flag`. Help paths (`-h`, bare namespace) short-circuit
-  before the banner.
+  before the banner. Set `HAMMER_QUIET=1` to suppress the banner
+  globally - useful when a task writes machine-readable output to
+  stdout (e.g. a JSON-emitting Claude Code / Codex hook).
 * There is **no per-level dispatch**. A namespace is a container, not a
   CLI of its own. Do not reintroduce `subclass.start(remaining_argv)`.
 * `start(argv)` is a two-step pipeline: `split_chain(argv)` (private)
@@ -206,11 +217,57 @@ explicit ADR-level discussion. Keys:
   is the whole API. `Hammer.cli` warms the cache before chdir-ing into
   the Hammerfile's directory so the resolved name stays relative to the
   cwd the user invoked from.
-* `hammer` (no args) prints just the command listing (with a top gray
-  `lux-hammer VERSION - <homepage>` banner for the hammer binary).
-* `hammer -h` / `hammer --help` adds global flags, a small Hammerfile
-  example, and the footer link on top of the same listing.
+* `hammer` (no args) routes to the `:default` built-in task, which
+  falls through to `print_help(extended: false)` - the brief command
+  listing with a top gray `lux-hammer VERSION - <homepage>` banner.
+* `hammer -h` / `--help` / `help [TARGET]` routes to the `:help`
+  built-in task, which calls `print_help(target, extended: true)` -
+  adds global flags (rendered from `:default`'s declared opts),
+  `Recipes:` section (hammer binary only), a small Hammerfile example,
+  and the footer link.
 * `hammer COMMAND -h` / `--help` prints per-command help (reserved on every command).
+
+## Built-in tasks (user-overridable)
+
+`Hammer::Builtins` defines two registration entry points; both register
+**after** Hammerfile evaluation and skip each task when the user
+already defined it (`unless klass.commands.key?(name)` - no
+redefinition warning).
+
+* `register_core(klass)` - always called. Registers `:default`,
+  `:help`, `:update`, `:agents`, `:version`. These coexist with
+  Hammerfile tasks.
+* `register_no_project(klass)` - called only on the no-Hammerfile
+  branch of `Hammer.cli` (which `--system` also routes through).
+  Registers `:recipes` and `:init` - tasks that would collide too
+  easily with user tasks inside a project.
+
+No reserved namespace. Names like `:self`, `:recipes`, `:update` can
+all be defined freely in a Hammerfile; the built-ins yield.
+
+Task contracts:
+
+* `:default` - hidden (no desc). Just prints `self.class.root.print_help`
+  (brief). Fires for bare `hammer` and leading-flag invocations where
+  the first token starts with `-` and isn't `-h` / `--help` (see
+  `Hammer.dispatch`). User overrides typically declare flag opts and
+  fall through to `hammer :help` when none matched.
+* `:help` - has a desc, shows in listings. Calls
+  `self.class.root.print_help(opts[:args].first, extended: true)`.
+  Fires for `help` / `-h` / `--help` at the top level.
+* `:update` / `:agents` / `:version` - thin wrappers around
+  `Hammer.self_update` / `Hammer.print_ai_help` / `puts Hammer::VERSION`.
+* `:recipes` - all recipe-management actions on one task, picked via
+  boolean opts: `--install [NAME [TARGET]]`, `--show NAME`,
+  `--path NAME`, `--edit NAME`, `--run NAME [ARGS]` (use `--` to
+  forward flags through). Bare invocation lists.
+* `:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
+  refuses if one exists.
+
+Both `:default` and `:help` are invoked via `run_command(cmd, argv,
+full: name, quiet: true)` - the gray `> prog cmd ...` banner is
+suppressed because the user didn't type `hammer default` /
+`hammer help` literally.
 * Commands listed flat with colon paths, grouped by top-level namespace.
 * Bare namespace (`hammer db`) prints the same listing scoped to that
   namespace.

data/README.md

@@ -73,7 +73,7 @@ Clones into `~/.local/share/lux-hammer` (override with `LUX_HAMMER_DIR=`),
 builds the gem, and installs it. Re-run any time, or use:
 
 ```sh
-hammer --update   # git pull main + rebuild + reinstall
+hammer update   # git pull main + rebuild + reinstall
 ```
 
 ## Quick start
@@ -483,10 +483,6 @@ hammer :                  # trailing colon at root: full help for every command
 Namespaces nest to any depth. There is no per-level dispatch - the root
 parses the whole colon path and walks the namespace tree.
 
-The `self:` namespace is reserved for hammer's own built-in commands
-(see [Recipes](#recipes-shareable-mini-clis-shipped-with-hammer)
-below). Defining `namespace :self` in a Hammerfile raises an error.
-
 ## Pre-hooks (`before`)
 
 A `before do ... end` block at the root scope or inside a `namespace`
@@ -541,6 +537,78 @@ end
 `hammer` and `hammer db` won't list `env`, but `hammer env`,
 `hammer :env` from another proc, and `before { hammer :env }` all work.
 
+## Built-in tasks (all overridable)
+
+The `hammer` binary auto-registers a small set of built-in tasks at
+the root of your CLI. Each one is guarded by `unless commands.key?` -
+defining your own `task :name` in a Hammerfile silently replaces the
+built-in.
+
+Always available (with or without a Hammerfile):
+
+* `:default` - fires on bare `hammer` and on leading-flag invocations.
+  Hidden from listings. Just prints the brief help by default; override
+  to wire up your own global flags.
+* `:help` - `hammer help [TARGET]`, `hammer -h`, `hammer --help`. Prints
+  the extended help view; `TARGET` accepts a command path or a `ns:`
+  prefix.
+* `:update` - rebuild + reinstall lux-hammer from main.
+* `:agents` - dump AGENTS.md (AI-friendly Hammerfile authoring docs).
+* `:version` - print the lux-hammer version.
+
+Only when no Hammerfile is loaded (or `--system` is passed - see below):
+
+* `:recipes` - list / install / show / edit recipes.
+* `:init` - write a starter Hammerfile in cwd (refuses if one exists).
+
+These two are skipped inside a project so they don't shadow user tasks.
+To reach them from inside a project, pass `--system`:
+
+```sh
+hammer --system recipes              # list recipes from anywhere
+hammer --system recipes --install srt ~/bin/srt
+```
+
+`--system` forces the no-Hammerfile branch - the Hammerfile in the
+current tree (if any) isn't loaded for that invocation.
+
+Customize bare `hammer` by replacing `:default`:
+
+```ruby
+# Hammerfile
+
+task :default do
+  opt :version, type: :boolean, alias: :v
+  opt :status,  type: :boolean, alias: :s
+
+  proc do |opts|
+    if opts[:version]
+      say "myapp #{MyApp::VERSION}"
+    elsif opts[:status]
+      sh 'bin/myapp status'
+    else
+      hammer :help                # fall through to help
+    end
+  end
+end
+```
+
+Or replace `:help` to add a banner:
+
+```ruby
+task :help do
+  desc 'Show help (with a banner)'
+  proc do |opts|
+    say.cyan "MyApp #{MyApp::VERSION} - https://internal/docs"
+    say ''
+    self.class.root.print_help(opts[:args].first, extended: true)
+  end
+end
+```
+
+`-h` / `--help` stay reserved on every command - you can't shadow them
+with an `opt`.
+
 ## Prereqs (`needs`)
 
 Declare commands that must run before this one (Rake-style task deps):
@@ -1003,19 +1071,29 @@ A **recipe** is a standalone Hammerfile-style script bundled inside the
 top-level binary in your `PATH` - so `srt` becomes a real command, not
 `hammer srt:shift`.
 
+Recipe management lives under the `recipes` task. From inside a
+project the task isn't registered (so it can't shadow user tasks);
+pass `--system` to reach it from anywhere.
+
 Listing what's available:
 
 ```sh
-$ hammer self:recipe
+$ hammer recipes                    # from any non-project dir
+$ hammer --system recipes           # from inside a project
 gem:
   srt  # Subtitle (.srt) toolkit - shift timestamps, show stats
-         [install: hammer self:recipe install srt]
+         [install: hammer recipes --install srt]
+  llm  # personal LLM utility CLI (memory store, prompt-token expander, ...)
+         [install: hammer recipes --install llm]
 ```
 
-Installing one (you control the path; nothing is written for you):
+Installing one. With no TARGET, the stub is printed to stdout (you
+redirect it yourself); with a TARGET path, lux-hammer writes the file
+and chmods +x in one step:
 
 ```sh
-$ hammer self:recipe install srt > ~/bin/srt && chmod +x ~/bin/srt
+$ hammer recipes --install srt ~/bin/srt    # write + chmod
+$ hammer recipes --install srt > ~/bin/srt && chmod +x ~/bin/srt
 $ srt --help
 Usage: srt COMMAND [ARGS]
 
@@ -1032,8 +1110,8 @@ so the recipe always runs the version currently in the gem.
 ### Authoring your own
 
 Drop a plain `.rb` file in `~/.config/hammer/recipes/`. The first
-`# desc: ...` comment is what shows in `hammer self:recipe`. The file
-body uses the same DSL as a Hammerfile - `task`, `namespace`, `before`,
+`# desc: ...` comment is what shows in `hammer recipes`. The file body
+uses the same DSL as a Hammerfile - `task`, `namespace`, `before`,
 `load`. Example `~/.config/hammer/recipes/json.rb`:
 
 ```ruby
@@ -1052,20 +1130,22 @@ end
 Install it the same way:
 
 ```sh
-$ hammer self:recipe install json > ~/bin/json && chmod +x ~/bin/json
+$ hammer recipes --install json ~/bin/json
 ```
 
 User-dir recipes override gem recipes with the same name, so you can
 fork without forking.
 
-### Other `self:recipe` actions
+### Other `recipes` actions
 
 ```sh
-hammer self:recipe              # list all
-hammer self:recipe install      # interactive picker, then prints stub
-hammer self:recipe show <NAME>  # cat the recipe source
-hammer self:recipe path <NAME>  # absolute path
-hammer self:recipe edit <NAME>  # open in $EDITOR (copies gem -> user dir first)
+hammer recipes                            # list all
+hammer recipes --install                  # interactive picker, then prints stub
+hammer recipes --show NAME                # cat the recipe source
+hammer recipes --path NAME                # absolute path
+hammer recipes --edit NAME                # open in $EDITOR (copies gem -> user dir first)
+hammer recipes --run  NAME [ARGS]         # run without installing its bin
+hammer recipes --run  NAME -- --help      # `--` forwards flags to the recipe
 ```
 
 ## Programmatic use

data/lib/hammer/builtins.rb

@@ -1,78 +1,166 @@
 class Hammer
-  # Lazy-loaded "built-ins" attached under the reserved `self:` namespace
-  # of the `hammer` binary. Hosts management commands (recipes, AGENTS.md
-  # dump, self-update) that should not appear on every user-command run.
-  # `Hammer.cli` only calls `register` when argv shows the user is
-  # asking for help or invoking a `self:`-prefixed command.
+  # Built-in tasks of the `hammer` binary - all live at the root level
+  # (no reserved namespace). Two registration entry points:
+  #
+  # * register_core - tasks always available (subject to user override
+  #   via the `unless commands.key?(...)` guard): :default, :help,
+  #   :update, :agents, :version. These coexist with Hammerfile tasks.
+  #
+  # * register_no_project - tasks meaningful only when no Hammerfile is
+  #   loaded (or `--system` was passed): :recipes, :init. These would
+  #   collide too easily with user tasks if always registered, so the
+  #   Hammerfile branch skips them.
   module Builtins
     module_function
 
-    # Wire the `self:` namespace into `klass`. Idempotent - safe to call
-    # twice; the second call replaces the existing subclass.
-    def register(klass)
-      Thread.current[:hammer_builtins_loading] = true
-      klass.namespace(:self) do
-        task :ai do
-          desc 'Print AGENTS.md (AI-friendly Hammerfile authoring docs)'
-          proc { Hammer.print_ai_help }
+    def register_core(klass)
+      register_help(klass)    unless klass.commands.key?('help')
+      register_default(klass) unless klass.commands.key?('default')
+      register_update(klass)  unless klass.commands.key?('update')
+      register_agents(klass)  unless klass.commands.key?('agents')
+      register_version(klass) unless klass.commands.key?('version')
+    end
+
+    def register_no_project(klass)
+      register_recipes(klass) unless klass.commands.key?('recipes')
+      register_init(klass)    unless klass.commands.key?('init')
+    end
+
+    def register_help(klass)
+      klass.class_eval do
+        task :help do
+          desc <<~TXT
+            Show help. Optional TARGET = command name or namespace (`ns:`).
+
+            Without TARGET prints the extended top-level help (commands,
+            recipes, global flags, examples). With a command path prints
+            per-command help; with a namespace prefix prints that
+            namespace's command listing.
+          TXT
+          example 'help'
+          example 'help build'
+          example 'help db:'
+          proc do |opts|
+            self.class.root.print_help(opts[:args].first, extended: true)
+          end
         end
+      end
+    end
+
+    # `:default` fires on bare `hammer` and on leading-flag invocations
+    # (other than -h/--help). Hidden from listings (no desc). All it
+    # does now is print help - the old flag opts (--update, --ai, ...)
+    # moved to dedicated tasks (:update, :agents, ...).
+    def register_default(klass)
+      klass.class_eval do
+        task :default do
+          proc { self.class.root.print_help }
+        end
+      end
+    end
 
+    def register_update(klass)
+      klass.class_eval do
         task :update do
-          desc 'Update lux-hammer from github main (requires install.sh checkout)'
+          desc 'Rebuild + reinstall lux-hammer from main'
           proc { Hammer.self_update }
         end
+      end
+    end
 
-        task :recipe do
+    def register_agents(klass)
+      klass.class_eval do
+        task :agents do
+          desc 'Print AGENTS.md (Hammerfile authoring docs for AI assistants)'
+          proc { Hammer.print_ai_help }
+        end
+      end
+    end
+
+    def register_version(klass)
+      klass.class_eval do
+        task :version do
+          desc 'Print lux-hammer version'
+          proc { puts Hammer::VERSION }
+        end
+      end
+    end
+
+    def register_init(klass)
+      klass.class_eval do
+        task :init do
+          desc 'Write a starter Hammerfile in the current directory'
+          proc { Hammer::Builtins.write_starter_hammerfile }
+        end
+      end
+    end
+
+    # `:recipes` rolls all recipe-management actions into one task. Bare
+    # invocation lists; opts pick the action and positional args carry
+    # the recipe name (and optional target path for --install). Run via
+    # `--run NAME [ARGS]` - use `--` to forward flags to the recipe
+    # itself (e.g. `hammer recipes --run srt -- --help`).
+    def register_recipes(klass)
+      klass.class_eval do
+        task :recipes do
           desc <<~TXT
-            Manage recipes. First positional argument is the action.
-
-              (no args)              list all recipes
-              install [NAME] [PATH]  install stub. No PATH: print to stdout. With PATH: write + chmod +x.
-              show    NAME           cat recipe source
-              path    NAME           print recipe abs path
-              edit    NAME           open recipe in $EDITOR
-              run     NAME [ARGS]    run a recipe without installing its bin
+            Manage recipes - the standalone Hammerfile-style scripts
+            bundled with the gem (and under ~/.config/hammer/recipes).
+            Bare invocation lists; flags pick the action.
           TXT
-          example 'self:recipe'
-          example 'self:recipe install srt ~/bin/srt        # write + chmod in one shot'
-          example 'self:recipe install srt > ~/bin/srt && chmod +x $_'
-          example 'self:recipe show srt'
-          example 'self:recipe run srt extract movie.mp4'
-          example 'self:recipe run srt -- --help            # -- forwards flags to the recipe'
+          opt :install, type: :boolean, desc: 'install recipe stub (picker if no NAME). With TARGET path: write + chmod.'
+          opt :show,    type: :boolean, desc: 'cat recipe source'
+          opt :path,    type: :boolean, desc: 'print recipe abs path'
+          opt :edit,    type: :boolean, desc: 'open recipe in $EDITOR (copies gem -> user dir first)'
+          opt :run,     type: :boolean, desc: 'run a recipe without installing its bin (forwards remaining args)'
+          example 'recipes'
+          example 'recipes --install srt ~/bin/srt    # write + chmod in one shot'
+          example 'recipes --install srt > ~/bin/srt && chmod +x $_'
+          example 'recipes --show srt'
+          example 'recipes --run srt extract movie.mp4'
+          example 'recipes --run srt -- --help        # -- forwards flags to the recipe'
           proc do |opts|
-            action, name, *rest = opts[:args]
-            Hammer::Builtins::Recipes.dispatch(action, name, rest)
+            args = opts[:args]
+            if opts[:install]
+              Hammer::Builtins::RecipesActions.install(args[0], args[1])
+            elsif opts[:show]
+              Hammer::Builtins::RecipesActions.show(Hammer::Builtins::RecipesActions.require_name!(args[0], 'show'))
+            elsif opts[:path]
+              Hammer::Builtins::RecipesActions.path(Hammer::Builtins::RecipesActions.require_name!(args[0], 'path'))
+            elsif opts[:edit]
+              Hammer::Builtins::RecipesActions.edit(Hammer::Builtins::RecipesActions.require_name!(args[0], 'edit'))
+            elsif opts[:run]
+              name = Hammer::Builtins::RecipesActions.require_name!(args[0], 'run')
+              Hammer.recipe(name, args[1..])
+            else
+              Hammer::Builtins::RecipesActions.list
+            end
           end
         end
       end
-    ensure
-      Thread.current[:hammer_builtins_loading] = nil
     end
 
-    # Implementations of the `self:recipe <action>` sub-commands, plus
-    # the no-action listing view. Kept in its own module so the
-    # namespace definition above stays small and skimmable.
-    module Recipes
-      module_function
-
-      def dispatch(action, name, rest = [])
-        case action
-        when nil       then list
-        when 'install' then install(name, rest.first)
-        when 'show'    then show(require_name!(name, 'show'))
-        when 'path'    then path(require_name!(name, 'path'))
-        when 'edit'    then edit(require_name!(name, 'edit'))
-        when 'run'     then Hammer.recipe(require_name!(name, 'run'), rest)
-        else
-          Shell.print_error "unknown action: #{action}"
-          Shell.say 'valid: install, show, path, edit, run (or omit for list)', :yellow
-          exit 1
-        end
+    # Writes ./Hammerfile with the canonical starter template. Refuses
+    # if one already exists - `init` must not clobber.
+    def write_starter_hammerfile
+      target = File.join(Dir.pwd, 'Hammerfile')
+      if File.exist?(target)
+        Shell.print_error "Hammerfile already exists at #{target}"
+        exit 1
       end
+      File.write(target, Hammer::STARTER_HAMMERFILE)
+      Shell.say "created #{target}", :green
+    end
+
+    # Implementations of the `recipes` task's action flags, plus the
+    # no-flag listing view. Separate module so the task definition above
+    # stays small.
+    module RecipesActions
+      module_function
 
       def require_name!(name, action)
         return name if name
-        Shell.print_error "missing recipe name (usage: self:recipe #{action} NAME)"
+        Shell.print_error "missing recipe name (usage: recipes --#{action} NAME)"
         exit 1
       end
 
@@ -94,7 +182,7 @@ class Hammer
           Shell.say "#{source}:", :yellow
           items.each_key do |name|
             _n, desc, installed = rows.find { |r| r.first == name }
-            status = installed ? "(installed: #{installed})" : "[install: hammer self:recipe install #{name}]"
+            status = installed ? "(installed: #{installed})" : "[install: hammer recipes --install #{name}]"
             line = "  #{name.ljust(width)}  # #{desc}"
             Shell.say line
             Shell.say "  #{' ' * width}    #{status}", :gray
@@ -144,7 +232,7 @@ class Hammer
       end
 
       # For a gem recipe, offer to copy to user dir first so edits
-      # survive `hammer self:update`. Then exec $EDITOR on the file.
+      # survive `hammer update`. Then exec $EDITOR on the file.
       def edit(name)
         path = Hammer::Recipe.path(name) or fail_unknown(name)
         editor = ENV['EDITOR'] || ENV['VISUAL']

data/lib/hammer/recipe.rb

@@ -49,14 +49,14 @@ class Hammer
       ''
     end
 
-    # Ruby wrapper text printed by `hammer self:recipe install`. User
+    # Ruby wrapper text printed by `hammer recipes --install`. User
     # redirects it to a file in PATH and chmods +x. The leading comment
     # documents the canonical install command. Name is passed as a
     # string literal so hyphenated names (`git-helper`) work too.
     def stub(name)
       <<~RUBY
         #!/usr/bin/env ruby
-        # install: hammer self:recipe install #{name} > ~/bin/#{name} && chmod +x $_
+        # install: hammer recipes --install #{name} > ~/bin/#{name} && chmod +x $_
         require 'lux-hammer'
         Hammer.recipe('#{name}', ARGV)
       RUBY

data/lib/lux-hammer.rb

@@ -188,12 +188,7 @@ class Hammer
     #     namespace :users do ... end
     #   end
     #
-    # `:self` is reserved for the `hammer` binary's built-ins (see
-    # Hammer::Builtins). User code that tries to open it raises.
     def namespace(name, &block)
-      if name.to_s == 'self' && !Thread.current[:hammer_builtins_loading]
-        raise Error, "namespace 'self' is reserved for hammer's built-in commands"
-      end
       sub = Class.new(Hammer)
       # Track the top-level CLI class so cross-invocation
       # (`hammer 'ns:cmd'`) from inside a namespaced command dispatches
@@ -369,13 +364,18 @@ class Hammer
       argv = argv.dup
       name = argv.shift
 
-      if name.nil?
-        return print_help
+      # Bare invocation OR leading flag (other than -h/--help) -> :default
+      # task. Re-prepend the flag so :default's option parser sees it.
+      # If no :default is defined, fall back to top-level help.
+      if name.nil? || (name.start_with?('-') && name != '-h' && name != '--help')
+        argv.unshift(name) if name
+        return dispatch_to_builtin('default', argv) { print_help }
       end
 
+      # Explicit help requests -> :help task. Remaining positionals (e.g.
+      # `help build`, `help db:`) reach :help via opts[:args].
       if name == 'help' || name == '-h' || name == '--help'
-        target = argv.shift
-        return print_help(target, extended: true)
+        return dispatch_to_builtin('help', argv) { print_help(argv.first, extended: true) }
       end
 
       # Trailing colon ("db:") -> namespace listing. Bare ":" lists root.
@@ -404,6 +404,16 @@ class Hammer
       exit 1
     end
 
+    # Run a built-in routing task (:default or :help) if defined,
+    # otherwise yield to the fallback block. The implicit run banner
+    # is suppressed (the user typed `hammer --version`, not `hammer
+    # default --version` - no point echoing the rewritten form).
+    def dispatch_to_builtin(name, argv)
+      cmd = commands[name]
+      return yield unless cmd
+      run_command(cmd, argv, full: name, quiet: true)
+    end
+
     public
 
     # Find a command by canonical name or alt within this class. Falls
@@ -526,14 +536,14 @@ class Hammer
       end
     end
 
-    def run_command(cmd, argv, full: nil)
+    def run_command(cmd, argv, full: nil, quiet: false)
       # -h / --help is reserved on every command. Anywhere before a `--`
       # stop-marker, it short-circuits to per-command help.
       return print_command_help(cmd, full) if help_requested?(argv)
 
       positional, opts = Parser.new(cmd.options).parse(argv)
       opts[:args] = positional
-      print_run_banner(cmd, full || cmd.name, positional, opts)
+      print_run_banner(cmd, full || cmd.name, positional, opts) unless quiet || ENV['HAMMER_QUIET']
       instance = new
       run_before_hooks(instance, opts)
       run_needs(cmd)
@@ -652,7 +662,7 @@ class Hammer
       entries.each do |name, file|
         desc = Hammer::Recipe.desc(file)
         installed = Hammer::Recipe.installed_path(name)
-        suffix = installed ? "(installed: #{installed})" : "[install: #{program_name} self:recipe install #{name}]"
+        suffix = installed ? "(installed: #{installed})" : "[install: #{program_name} recipes --install #{name}]"
         Shell.say "  #{name.ljust(width)}  # #{desc}"
         Shell.say "  #{' ' * width}    #{suffix}", :gray
       end
@@ -661,8 +671,8 @@ class Hammer
     # `extended:` is accepted for parity with `print_help` but intentionally
     # not used here - the global-flags / Hammerfile-example / footer block
     # is root-help-only. A namespace listing is just the commands under
-    # that prefix; tool-meta noise (self:, Recipes:, --update alias) is
-    # reserved for `hammer --help` at the top level.
+    # that prefix; tool-meta noise (Recipes: section) is reserved for
+    # `hammer --help` at the top level.
     def print_namespace_help(prefix, ns, full: false, extended: false)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
       rows = []
@@ -707,14 +717,16 @@ class Hammer
       print_footer unless hammer_bin
     end
 
-    # Global flags only exist when invoked via the `hammer` binary
-    # (see `Hammer.cli`), not for user-built CLIs that call `start`
-    # on their own subclass.
+    # Listed under `Default task options:` in `--help` so users see what
+    # flags fire on bare-flag invocation (`hammer --version` etc).
+    # Re-rendered from the live `:default` task so user-defined
+    # overrides surface their own flags here automatically.
     def print_global_flags
-      return unless root.instance_variable_get(:@hammer_binary)
+      default = root.commands['default']
+      return unless default && !default.options.empty?
       Shell.say ''
-      Shell.say 'Global:', :yellow
-      Shell.say '  --update  # alias for `self:update`'
+      Shell.say 'Default task options:', :yellow
+      default.options.each { |o| Shell.say "  #{o.usage}" }
     end
 
     def print_footer
@@ -722,35 +734,13 @@ class Hammer
       Shell.say "powered by hammer - #{HOMEPAGE}", :gray
     end
 
-    # Small Hammerfile cheat-sheet shown under `hammer --help`. Touches
-    # the main surface area (task/desc/example/opt, namespace, before,
-    # needs, sh, say) without trying to be exhaustive - that's --ai's job.
+    # Hammerfile cheat-sheet shown under `hammer --help`. Same content
+    # as `hammer --init` writes - single source of truth via
+    # `Hammer::STARTER_HAMMERFILE`. For exhaustive docs see `hammer agents`.
     def print_hammerfile_example
       Shell.say ''
       Shell.say 'Hammerfile example:', :yellow
-      Shell.say <<~RUBY
-          desc 'My project tools - build, deploy, test'
-
-          task :hello do
-            desc    'Greet someone'
-            example 'hello world --loud'
-            opt :loud, type: :boolean, alias: :l
-            proc do |opts|
-              msg = "hello \#{opts[:args].first || 'world'}"
-              say(opts[:loud] ? msg.upcase : msg, :cyan)
-            end
-          end
-
-          namespace :db do
-            before { hammer :env }
-
-            task :migrate do
-              desc  'Run migrations'
-              needs 'db:check'
-              proc  { sh 'bin/rails db:migrate' }
-            end
-          end
-      RUBY
+      Shell.say Hammer::STARTER_HAMMERFILE
     end
 
     def print_command_list(klass, prefix = nil)
@@ -896,7 +886,7 @@ class Hammer
       Shell.print_error "unknown recipe: #{name}"
       Shell.say 'available recipes:', :yellow
       Recipe.all.keys.sort.each { |n| Shell.say "  #{n}" }
-      Shell.say 'try `hammer self:recipe` to list with descriptions', :gray
+      Shell.say 'try `hammer recipes` to list with descriptions', :gray
       exit 1
     end
 
@@ -919,12 +909,45 @@ class Hammer
     end
   end
 
-  # Default install dir used by install.sh and `hammer --update`.
+  # Canonical starter Hammerfile. Written verbatim by `hammer --init`
+  # and shown inline by `print_hammerfile_example` (the `Hammerfile
+  # example:` block in `hammer --help`) - one source of truth for both.
+  # Annotated as a mini tutorial of the common DSL surface in one task.
+  # Single-quoted heredoc so file contents pass through unescaped.
+  STARTER_HAMMERFILE ||= <<~'RUBY'
+    desc 'My project tools'
+
+    # `namespace :name do ... end` groups tasks under a colon prefix.
+    # Address as `hammer demo:greet`.
+    namespace :demo do
+      # run before every task - global, or on a namespace
+      before { say.gray "[demo] booting in #{Dir.pwd}" }
+
+      task :greet do
+        desc    'Demo task - shows the common DSL features in one place'
+        example 'demo:greet world --from=alice --loud --times=3'
+        alt     :hi                     # `hammer demo:hi` also dispatches here
+
+        opt :from,  default: 'anon',              desc: 'who is greeting'
+        opt :loud,  type: :boolean, alias: :l,    desc: 'shout the greeting'
+        opt :times, type: :integer, default: 1,   desc: 'repeat N times'
+
+        proc do |opts|
+          who = opts[:args].first || 'world'
+          msg = "hello #{who} from #{opts[:from]}"
+          msg = msg.upcase if opts[:loud]
+          opts[:times].times { say msg, :cyan }
+        end
+      end
+    end
+  RUBY
+
+  # Default install dir used by install.sh and `hammer update`.
   SELF_UPDATE_DIR  ||= File.expand_path('~/.local/share/lux-hammer')
   SELF_UPDATE_REPO ||= 'https://github.com/dux/hammer.git'
   SELF_INSTALL_URL ||= 'https://raw.githubusercontent.com/dux/hammer/main/install.sh'
 
-  # `hammer --update`: pull main in the install-script checkout and
+  # `hammer update`: pull main in the install-script checkout and
   # reinstall the gem. Assumes the install.sh layout - if the dir is
   # missing, point the user at the curl-pipe installer.
   def self.self_update
@@ -959,31 +982,25 @@ class Hammer
   # finds a Hammerfile, evaluates it as the block DSL, then dispatches
   # ARGV against the resulting CLI.
   #
-  # The `self:` namespace (recipe management, AGENTS.md dump, self-
-  # update) is registered on-demand when the user invokes help or
-  # types a `self:` path - see `builtins_triggered?`.
+  # `--system` forces the no-Hammerfile branch even from inside a
+  # project - the escape hatch for reaching `recipes`/`init` when a
+  # user-defined task tree would otherwise own the root.
   def self.cli(argv = ARGV)
-    # `--update` is a back-compat alias for `self:update`. Rewrite so
-    # normal dispatch handles it (after builtins registration).
-    if (i = argv.index('--update'))
-      argv = argv.dup
-      argv.delete_at(i)
-      argv.unshift('self:update')
-    end
-
-    wants_builtins = builtins_triggered?(argv)
+    argv = argv.dup
+    force_system = !!argv.delete('--system')
 
-    path = find_hammerfile(Dir.pwd)
+    path = force_system ? nil : find_hammerfile(Dir.pwd)
     unless path
-      # No Hammerfile - still allow `hammer self:*` commands to run
-      # (they don't depend on a project). Otherwise print the help-ish
-      # "create one" message.
-      if wants_builtins
+      # No Hammerfile (or --system) - all built-ins are reachable. Bare
+      # `hammer`, `hammer recipes`, `hammer update`, `hammer agents`,
+      # `hammer version`, `hammer init` all work.
+      if force_system || dispatches_to_builtin?(argv) || looks_like_builtin?(argv)
         klass = Class.new(Hammer)
         klass.instance_variable_set(:@hammer_binary, true)
         klass.program_name
         require_relative 'hammer/builtins'
-        Hammer::Builtins.register(klass)
+        Hammer::Builtins.register_core(klass)
+        Hammer::Builtins.register_no_project(klass)
         klass.start(argv)
         return
       end
@@ -1004,24 +1021,17 @@ class Hammer
 
       Shell.say "create one - example:"
       puts
-      Shell.say <<~RUBY
-        desc 'My project tools'
-
-        task :hello do
-          desc 'say hello'
-          proc do |opts|
-            say.green "hello \#{opts[:args].first || 'world'}"
-          end
-        end
-      RUBY
+      Shell.say STARTER_HAMMERFILE
       Shell.say ''
-      Shell.say "tip: run `#{File.basename($PROGRAM_NAME)} self:ai` for AI-friendly Hammerfile authoring docs", :gray
+      bin = File.basename($PROGRAM_NAME)
+      Shell.say "tip: run `#{bin} init` to drop the example above into ./Hammerfile", :gray
+      Shell.say "tip: run `#{bin} agents` for AI-friendly Hammerfile authoring docs", :gray
       exit 1
     end
 
     klass = Class.new(Hammer)
     # Mark this class as the `hammer` binary's root so help output can
-    # surface binary-only sections (`Recipes:`, `self:` namespace).
+    # surface binary-only sections (`Recipes:` listing).
     klass.instance_variable_set(:@hammer_binary, true)
     # Resolve before chdir so paths like `bin/foo` stay relative to the
     # cwd the user actually invoked from. `program_name` memoizes.
@@ -1036,24 +1046,37 @@ class Hammer
     # are NOT visible during Hammerfile evaluation, only inside handlers.
     Hammer::Dotenv.load(Dir.pwd) if klass.dotenv_enabled?
 
-    if wants_builtins
-      require_relative 'hammer/builtins'
-      Hammer::Builtins.register(klass)
-    end
+    # Core built-ins register AFTER Hammerfile eval so user-defined
+    # tasks win (the `unless commands.key?(...)` guards in register_core
+    # skip the built-in when overridden - no redefinition warning).
+    # `register_no_project` (:recipes, :init) is intentionally NOT
+    # called here - those would clash too easily with user tasks. Use
+    # `hammer --system recipes` to reach them from inside a project.
+    require_relative 'hammer/builtins'
+    Hammer::Builtins.register_core(klass)
 
     klass.start(argv)
   end
 
-  # True if argv references the `self:` namespace or asks for help -
-  # any of which means the user wants to see / invoke the built-ins.
-  # Bare `hammer` (empty argv) does NOT trigger - the no-args listing
-  # stays a clean project-command view without `self:` or `Recipes:`.
-  # Cheap scan, runs once per invocation.
-  def self.builtins_triggered?(argv)
-    argv.any? do |a|
-      a == '--help' || a == '-h' || a == 'help' ||
-        a == 'self' || a.start_with?('self:')
-    end
+  # True if argv goes through a built-in dispatch path (`:default` or
+  # `:help`) - meaning bare `hammer`, leading-flag invocations like
+  # `hammer -h`, or explicit help requests. These don't need a project
+  # Hammerfile to run.
+  def self.dispatches_to_builtin?(argv)
+    return true if argv.empty?
+    first = argv.first
+    first == 'help' || first == '-h' || first == '--help' || first.start_with?('-')
+  end
+
+  # True if argv names a built-in task (`recipes`, `update`, `agents`,
+  # `version`, `init`). Used in the no-Hammerfile branch to wake up the
+  # built-ins for invocations like `hammer recipes` that aren't a flag
+  # or help request.
+  BUILTIN_TASKS ||= %w[recipes update agents version init].freeze
+  def self.looks_like_builtin?(argv)
+    first = argv.first
+    return false unless first
+    BUILTIN_TASKS.include?(first) || BUILTIN_TASKS.any? { |t| first.start_with?("#{t}:") }
   end
 
   # Walk up the directory tree looking for a Hammerfile.

data/recipes/llm.rb

@@ -0,0 +1,434 @@
+# desc: personal LLM utility CLI (memory store, prompt-token expander, ...)
+
+desc <<~TXT
+  llm - personal LLM utility CLI
+
+  Namespaces:
+    memory   persistent memory store (backs the Claude Code memory plugin)
+    prompt   token-prefix prompt expander (UserPromptSubmit hook + CLI)
+TXT
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'set'
+
+STORE        ||= ENV['CLAUDE_MEMORY_STORE'] || File.expand_path('~/dev/skills/memory')
+VALID_TYPES  ||= %w[user feedback project reference].freeze
+
+FileUtils.mkdir_p(STORE)
+
+namespace :memory do
+  # Helpers are defined inside the namespace block (class_eval'd on the
+  # namespace's anonymous Hammer subclass) so the task procs reach them.
+  # Top-level `helpers do` would land on the recipe's root class, which
+  # namespace subclasses do not inherit from.
+  private
+
+  def memory_path(name)
+    File.join(STORE, "#{name}.md")
+  end
+
+  # Minimal frontmatter reader. Handles one level of nesting (good enough for
+  # `metadata: { type: ... }`). Returns [meta_hash, body_string].
+  def parse_memory(path)
+    raw = File.read(path)
+    return [{}, raw] unless raw.start_with?("---\n")
+    _, fm, body = raw.split(/^---\s*$/m, 3)
+    meta = {}
+    current_nested = nil
+    fm.each_line do |line|
+      next if line.strip.empty?
+      if (m = line.match(/^([\w-]+):\s*(.*)$/))
+        key, val = m[1], m[2].strip
+        if val.empty?
+          meta[key] = {}
+          current_nested = key
+        else
+          meta[key] = val
+          current_nested = nil
+        end
+      elsif current_nested && (m = line.match(/^\s+([\w-]+):\s*(.*)$/))
+        meta[current_nested][m[1]] = m[2].strip
+      end
+    end
+    [meta, body.to_s.sub(/\A\n+/, '')]
+  end
+  task :list do
+    desc 'List stored memories with type and one-line description'
+    example 'llm memory list'
+
+    proc do
+      files = Dir[File.join(STORE, '*.md')].sort
+      if files.empty?
+        say '(no memories)', :gray
+        next
+      end
+      files.each do |f|
+        name    = File.basename(f, '.md')
+        meta, _ = parse_memory(f)
+        type    = meta.dig('metadata', 'type') || '?'
+        dsc     = meta['description'] || 'no description'
+        say "- #{name} [#{type}] - #{dsc}"
+      end
+    end
+  end
+
+  task :read do
+    desc 'Print the full content of a memory (frontmatter + body)'
+    example 'llm memory read user-role'
+
+    proc do |opts|
+      name = opts[:args].first
+      error 'usage: llm memory read <name>' unless name
+      path = memory_path(name)
+      error "memory not found: #{name}" unless File.file?(path)
+      print File.read(path)
+    end
+  end
+
+  task :write do
+    desc <<~DESC
+      Write or update a memory. The body is read from stdin.
+
+      Memory types: user, feedback, project, reference.
+    DESC
+    example %(echo "deep Go expertise, new to React" | llm memory write user-role --type=user --description="user profile")
+    opt :type,        desc: 'memory type (user|feedback|project|reference)', req: true
+    opt :description, desc: 'one-line summary stored in frontmatter'
+
+    proc do |opts|
+      name = opts[:args].first
+      error 'usage: llm memory write <name> --type=<type> [--description="..."] < body' unless name
+      error "unknown type: #{opts[:type]} (valid: #{VALID_TYPES.join(', ')})" unless VALID_TYPES.include?(opts[:type])
+
+      body = $stdin.read
+      error 'body is empty (pipe content on stdin)' if body.strip.empty?
+
+      path = memory_path(name)
+      File.open(path, 'w') do |io|
+        io.puts '---'
+        io.puts "name: #{name}"
+        io.puts "description: #{opts[:description]}" if opts[:description]
+        io.puts 'metadata:'
+        io.puts "  type: #{opts[:type]}"
+        io.puts '---'
+        io.puts
+        io.puts body.chomp
+      end
+      say "wrote: #{path}", :green
+    end
+  end
+
+  task :delete do
+    desc 'Delete a memory by name'
+    example 'llm memory delete old-fact'
+
+    proc do |opts|
+      name = opts[:args].first
+      error 'usage: llm memory delete <name>' unless name
+      path = memory_path(name)
+      error "memory not found: #{name}" unless File.file?(path)
+      File.delete(path)
+      say "deleted: #{name}", :yellow
+    end
+  end
+
+  task :search do
+    desc 'Search memory bodies for a query string (case-insensitive)'
+    example 'llm memory search react'
+
+    proc do |opts|
+      query = opts[:args].first
+      error 'usage: llm memory search <query>' unless query
+      hits = Dir[File.join(STORE, '*.md')].sort.select do |f|
+        File.read(f).downcase.include?(query.downcase)
+      end
+      if hits.empty?
+        say '(no matches)', :gray
+      else
+        hits.each { |f| say File.basename(f, '.md') }
+      end
+    end
+  end
+
+  task :path do
+    desc 'Print the storage path (where memory files live)'
+    proc { say STORE }
+  end
+end
+
+namespace :prompt do
+  TOKEN_PATTERN        ||= /[a-z0-9_-]+/.freeze
+  TOKEN_LINE_RE        ||= /\A(?:\s*:[a-z0-9_-]+)+\s*\z/.freeze
+  HOOK_EVENT           ||= 'UserPromptSubmit'
+  VERBATIM_INSTRUCTION ||= "INSTRUCTION TO ASSISTANT: Do not answer the user's prompt. Print the message below verbatim to the user, preserving every line exactly as written. Do not summarize, truncate, or paraphrase."
+  QUESTION_RULE        ||= <<~RULE.strip
+    rule (applies ONLY to the current user message, not to subsequent turns in this session):
+    * answer only
+    * do not modify files
+    * ask before making changes
+  RULE
+
+  private
+
+  def folders
+    [
+      ['local',  File.join(Dir.pwd, 'doc', 'command')],
+      ['global', File.expand_path('~/dev/skills/command')]
+    ]
+  end
+
+  def tokens_in(input)
+    out = []
+    scanner = input.to_s.strip
+    while (m = scanner.match(/\A(?::(?<pre>#{TOKEN_PATTERN})|(?<post>#{TOKEN_PATTERN}):)(?=\s|$)/))
+      out << (m[:pre] || m[:post])
+      scanner = scanner[m[0].length..].to_s.lstrip
+    end
+    out.uniq
+  end
+
+  def find_command_path(token)
+    folders.map { |_label, folder| File.join(folder, "#{token}.md") }.find { |c| File.file?(c) }
+  end
+
+  def display_path(path)
+    Pathname.new(path).cleanpath.to_s.sub(%r{\A#{Regexp.escape(Dir.home)}/}, '~/')
+  end
+
+  def first_line_description(path)
+    File.foreach(path).first.to_s.strip.sub(/\A#+\s*/, '')
+  end
+
+  def grouped_listing
+    ordered = folders.sort_by { |label, _| label == 'global' ? 0 : 1 }
+    ordered.map do |label, folder|
+      toks = Dir.glob(File.join(folder, '*.md')).map { |p| File.basename(p, '.md') }.sort
+      items = toks.empty? ? '(none)' : toks.map { |t| ":#{t}" }.join(', ')
+      "Available #{label} in #{display_path(folder)} -> #{items}"
+    end.join("\n")
+  end
+
+  def help_listing
+    ordered = folders.sort_by { |label, _| label == 'global' ? 0 : 1 }
+    sections = ordered.map do |label, folder|
+      files = Dir.glob(File.join(folder, '*.md')).sort
+      header = "#{label} (#{display_path(folder)}):"
+      if files.empty?
+        "#{header}\n  (none)"
+      else
+        width = files.map { |p| File.basename(p, '.md').length }.max
+        entries = files.map do |path|
+          name = File.basename(path, '.md')
+          dscr = first_line_description(path)
+          dscr = '(no description)' if dscr.empty?
+          "  :#{name.ljust(width)}  #{dscr}"
+        end
+        "#{header}\n#{entries.join("\n")}"
+      end
+    end
+    "Available commands:\n\n#{sections.join("\n\n")}"
+  end
+
+  def agents_listing
+    cwd  = Pathname.new(Dir.pwd)
+    home = Pathname.new(Dir.home)
+
+    dirs = [home]
+    if cwd != home && cwd.to_s.start_with?("#{home}/")
+      current = home
+      cwd.relative_path_from(home).to_s.split('/').each do |part|
+        current += part
+        dirs << current
+      end
+    elsif cwd != home
+      dirs << cwd
+    end
+
+    found = dirs.filter_map { |d| (d + 'AGENTS.md').to_s if (d + 'AGENTS.md').file? }
+
+    if found.empty?
+      msg = "No AGENTS.md files found from #{display_path(home.to_s)} to #{display_path(cwd.to_s)}"
+      warn msg
+      return msg
+    end
+
+    content = found.each_with_index.map do |path, i|
+      lines = []
+      lines << '---' if i.positive?
+      lines << "Loaded #{display_path(path)}"
+      lines << ''
+      lines << File.read(path)
+      lines.join("\n")
+    end.join("\n")
+
+    approx_tokens = (content.bytesize / 4.0).round
+    label = found.size == 1 ? 'file' : 'files'
+    summary = "Loaded #{found.size} AGENTS.md #{label} (~#{approx_tokens} tokens): #{found.map { |p| display_path(p) }.join(', ')}"
+    warn summary
+
+    instruction = "INSTRUCTION TO ASSISTANT: The AGENTS.md files below have been loaded into your context - apply them to all subsequent work in this session. If the user's current message contains no other request, reply with exactly this one line and nothing else: \"#{summary}\"."
+    "#{instruction}\n\n#{content}"
+  end
+
+  def transform_strip_title(content)
+    return content unless content.lstrip.start_with?('#')
+    content.sub(/\A\s*#[^\n]*\n?/, '').lstrip
+  end
+
+  def transform_expand_command_prefix(content, seen)
+    prefix_tokens = []
+    remaining = content
+
+    loop do
+      line, rest = remaining.split("\n", 2)
+      break unless line
+      stripped = line.strip
+
+      if stripped.empty?
+        break if prefix_tokens.empty?
+        remaining = rest.to_s
+        next
+      end
+
+      break unless stripped =~ TOKEN_LINE_RE
+      prefix_tokens.concat(stripped.scan(/:(#{TOKEN_PATTERN})/).flatten)
+      remaining = rest.to_s
+    end
+
+    return content if prefix_tokens.empty?
+
+    expanded = prefix_tokens.map { |t| load_command_content(t, seen) }.join("\n\n")
+    remaining = remaining.lstrip
+    remaining.empty? ? expanded : "#{expanded}\n\n#{remaining}"
+  end
+
+  def transform_expand_file_includes(content)
+    content.gsub(/^[ \t]*@(\S+)[ \t]*$/) do
+      raw = Regexp.last_match(1)
+      expanded = File.expand_path(raw)
+      error "missing include #{raw}" unless File.file?(expanded)
+      File.read(expanded)
+    end
+  end
+
+  def load_command_content(token, seen)
+    error "circular include of :#{token}" if seen.include?(token)
+    path = find_command_path(token)
+    error %(custom token ":#{token}" not found.\n\n#{grouped_listing}) unless path
+
+    child_seen = seen + [token]
+    content = File.read(path)
+    content = transform_strip_title(content)
+    content = transform_expand_command_prefix(content, child_seen)
+    content = transform_expand_file_includes(content)
+    content
+  end
+
+  def verbatim_response(body, fail_open:)
+    return body unless fail_open
+    "#{VERBATIM_INSTRUCTION}\n\n#{body}"
+  end
+
+  def append_question_rule(input, context)
+    return context unless input.to_s.strip.end_with?('?')
+    context.to_s.empty? ? QUESTION_RULE : "#{context}\n\n---\n#{QUESTION_RULE}"
+  end
+
+  def build_context(input, fail_open: false)
+    toks = tokens_in(input)
+    return '' if toks.empty?
+    return verbatim_response(help_listing, fail_open: fail_open) if toks.include?('help')
+    return agents_listing if toks.include?('agents')
+
+    seen = Set.new
+    loaded = toks.map do |token|
+      path = find_command_path(token)
+      error %(custom token ":#{token}" not found.\n\n#{grouped_listing}) unless path
+      [token, Pathname.new(path).cleanpath.to_s, load_command_content(token, seen)]
+    end
+
+    loaded.each_with_index.map do |(_token, path, content), index|
+      lines = []
+      lines << '---' if index.positive?
+      lines << "Loaded #{display_path(path)}"
+      lines << ''
+      lines << (content.to_s.empty? ? '(empty custom command file)' : content)
+      lines.join("\n")
+    end.join("\n")
+  rescue Hammer::Error => e
+    raise unless fail_open
+    verbatim_response("ERROR: #{e.message}", fail_open: true)
+  end
+
+  def load_context(input, fail_open: false)
+    append_question_rule(input, build_context(input, fail_open: fail_open))
+  end
+
+  def hook_json(context)
+    context = context.to_s.strip
+    return { continue: true } if context.empty?
+    {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: HOOK_EVENT,
+        additionalContext: "<llm_command_context>\n#{context}\n</llm_command_context>"
+      }
+    }
+  end
+
+  task :list do
+    desc 'List available prompt commands, one line per folder'
+    proc { say grouped_listing }
+  end
+
+  task :help do
+    desc 'List available prompt commands with their first-line descriptions'
+    proc { say help_listing }
+  end
+
+  task :agents do
+    desc 'Load all AGENTS.md from home down to cwd and print the combined content'
+    proc { say agents_listing }
+  end
+
+  task :expand do
+    desc 'Expand prompt token(s) and print the resulting context'
+    example 'llm prompt:expand :foo :bar'
+    example 'llm prompt:expand foo:'
+
+    proc do |opts|
+      input = opts[:args].join(' ')
+      error 'usage: llm prompt:expand :token [:token ...]' if input.empty?
+      out = load_context(input)
+      say out unless out.empty?
+    end
+  end
+
+  task :hook do
+    desc <<~D
+      UserPromptSubmit hook entry. Reads {"prompt": ...} JSON on stdin,
+      expands any token prefix, and emits hookSpecificOutput JSON on stdout.
+
+      Pair with HAMMER_QUIET=1 in the hook command so the runtime banner
+      doesn't pollute stdout.
+    D
+    opt :claude, type: :boolean, default: false, desc: 'Claude Code hook mode'
+    opt :codex,  type: :boolean, default: false, desc: 'Codex hook mode'
+
+    proc do |opts|
+      error '--claude or --codex required' unless opts[:claude] || opts[:codex]
+
+      raw = $stdin.read
+      prompt = begin
+        JSON.parse(raw).fetch('prompt', raw)
+      rescue JSON::ParserError
+        raw
+      end
+
+      context = load_context(prompt.to_s, fail_open: true)
+      puts JSON.generate(hook_json(context))
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.7
 platform: ruby
 authors:
 - Dino Reic
@@ -48,6 +48,7 @@ files:
 - "./lib/hammer/shell.rb"
 - "./lib/lux-hammer.rb"
 - "./recipes/git-helper.rb"
+- "./recipes/llm.rb"
 - "./recipes/srt.rb"
 - bin/hammer
 homepage: https://github.com/dux/hammer