hiiro 0.1.366 → 0.1.368

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97e9a140ccea0c61c6efe48395bda803e10bec8c0a933a95efb4a949a8788cdf
-  data.tar.gz: 24c45d70c07d018be4cca31368d91d55b8c8caa89d326e65803c512dcdf3b93e
+  metadata.gz: 975c627734daa28e7efa5c45802cd3f296ec3f338c7e2ad73835e22d219223e6
+  data.tar.gz: bcd42f9f3b2ca7bbaf33b67e1535aa4729d3701f353d313bfe3a7f64c27b3e19
 SHA512:
-  metadata.gz: e1b139bc6a4286240311b0106413abed936ebef51771b267d4284ecff70783c5df7a4a0a7b368251e481c8f72ed0cc5d0bc094fe513cffa1563df08123fa65dc
-  data.tar.gz: 37b32e60d486151dad01c08fdff82db9e9cff23506c8dad72636421b91e77c9e2e7a342b145770d86c615cc982035c4dcc80f3039ec3e457809e431f0bcc5aa2
+  metadata.gz: 22b19c645b77356da44007ab866f00f769ef875444b9ad5b4d00ae080ff5797b3b4cc3c500b65118ba3801f025c061f8ef01bb885aff7a63692c83c3b1ee09cc
+  data.tar.gz: aad14264c543596424e10c301401e618e13adbef8dd7e6088b9d1b6c3e9374a357040d2886843057c290f0dda65a6f6100992bfbf3bdd3d1049eb914984ea8c5

data/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## [Unreleased]
 
+## [0.1.368] - 2026-09-14
+
+### Added
+- `h herdr`: Herdr plugin exposing `t` through keybound popups for fuzzy task switching, todo capture, todo copying, task shell, and nvim access; `h herdr install` copies and links the plugin, `h herdr keys` prints keybindings
+
+### Changed
+- Task CLI grammar converted to command-first: `t COMMAND [TASK] [ARGS...]` matching the legacy `h task` rule where the first positional word is the task when it names one (exact or unique prefix), otherwise the current task is used and the word stays in the payload
+
+### Removed
+- `Hiiro::TaskScope` class; task resolution logic integrated into `Hiiro::TaskCli`
+
+## [0.1.367] - 2026-09-14
+
+### Added
+- `t use TASK` (alias `pin`) saves the fallback task; `t current` now only prints
+- `-t TASK` / `-f` task options on every `t` command that acts on a task
+- `h herdr`: a Herdr plugin (`herdr-plugin/herdr-plugin.toml`) with actions `hiiro.switch`, `hiiro.todo-add`, `hiiro.todos`, `hiiro.shell`, and `hiiro.nvim` that open a popup running `t`; `h herdr install` copies and links it, `h herdr keys` prints keybindings
+- `Hiiro::TestHarness` understands `add_cmd`, `add_option`, `add_flag`, and `opts`
+- `t TASK todo show ID` and `tt TASK show ID` print one todo's text; `todo ls --plain` prints text only
+- Add `h env add NAME VALUE` and `h alias add NAME COMMAND...` to append safely quoted shell definitions, preferring existing zsh module files and falling back to the root dotfiles. Use native Hiiro options, including `opts.global` and `--`.
+- Add `h bin add NAME [COMMAND ...]` to generate executable `Hiiro.run` templates with optional empty `add_cmd` blocks. Serialize command names as Ruby symbols and refuse existing files or symlinks.
+- `t ls` and `t list` root commands list tasks like bare `t`
+- `Hiiro::Error`: `Hiiro#run` prints only `ERROR: message` for it, no backtrace
+- `builtin_commands: false` option for `Hiiro.run`/`run_child` to skip the automatic `pry` and `edit` commands
+- `Hiiro#open_default(target)` opens a path or URL with `open`/`xdg-open`
+- `t` and `tt` are gem executables (`exe/t`, `exe/tt`) installed with Hiiro
+- `t TASK tree new|rm|resume`, `t TASK tree`, `t TASK path`, `t TASK branch`, `t TASK sh`, and `t TASK cd` bring worktree and shell commands from `h task` into `t`; subtasks are `parent/child` names
+- `Hiiro::CurrentTask`: one resolver for the current task (Herdr workspace, working directory, saved pin) used by `t` and by `Environment#task`
+- `Hiiro::Git.repo_dir` so worktree commands work when `~/work/.git` is a gitfile pointing at the bare repo
+
+### Fixed
+- `h task start` and worktree listing failed with "Not a directory" when `~/work/.git` is a gitfile; git now runs in the parent directory
+
+### Changed
+- `t` grammar is now command-first, `t COMMAND [TASK] [ARGS...]`, matching the old `h task` rule: the first positional word is the task when it names one (exact or unique prefix), otherwise the current task is used and the word stays in the payload. `.` is the current task, `-` selects orphan todos. `tt ...` is `t todo ...`. `Hiiro::TaskScope` is removed
+- `t todo add` no longer creates tasks; only `t new NAME` does
+- Move the task CLI into `lib/hiiro/task_cli.rb` (`Hiiro::TaskCli`); `exe/t` and `exe/tt` are thin `Hiiro.run` launchers and `bin/t`, `bin/tt` are symlinks
+- `t` requires `hiiro` like other bins instead of editing the load path; `task_scope` and `task_sessions` load with `hiiro`
+- `t` errors print without a backtrace; task, scope, and session errors subclass `Hiiro::Error`
+- `t` saves the current task through the `PinRecord` model and resolves resources, documents, tabs, and panes with `Hiiro::Matcher`, accepting unique prefixes and offering fuzzyfind when no reference is given
+- `tt` runs the todo scope in-process instead of exec'ing `t`
+- `h task` is now a symlink to `t` (`bin/h-task` -> `exe/t`); the inline `h task` and `h subtask` subcommands are gone, and `h task start|stop|resume|switch|sh|cd|path|branch|todo` map to `t` commands (see docs/h-task.md)
+- `Environment#task` also matches the working directory against task homes, primary directories, and registered directories
+- `TaskManager#start_task` uses the extracted `create_tree`
+- Task listing prints aligned columns with the open todo count after each name, e.g. `prez (3)`, plus `next:`/`waiting:` text
+- `ls` and `list` are now reserved root words in `t`; tasks with those exact names need a unique prefix
+
 ## [0.1.366] - 2026-09-14
 
 ### Changed

data/CLAUDE.md

@@ -508,6 +508,7 @@ ALWAYS update `README.md` and any files in `docs/` or other markdown files that
 ## Key Files
 
 - `exe/h` - Entry point that loads lib/hiiro.rb
+- `exe/t`, `exe/tt` - Task CLI launchers over `Hiiro::TaskCli` (`lib/hiiro/task_cli.rb`)
 - `bin/h-*` - External subcommands (tmux wrappers, git helpers, jumplist, etc.)
 - `plugins/*.rb` - Reusable plugin modules (Pins, Project, Tasks, Notify)
 - `lib/hiiro.rb` - Main Hiiro class and Runners

data/README.md

@@ -61,67 +61,56 @@ h ping
 
 ### Task CLI
 
-The repository's `bin/t` contains the task commands and helpers, using Hiiro's
-`add_cmd` DSL and existing task records. `~/bin/t` and `~/bin/tt` are symlinks to
-the repository launchers; installing the gem does not install them. `t NAME new`
-creates a task and its notes directory without creating a Git worktree.
-
-Use `t TASK COMMAND...`. Bare `t` lists every task, including done and archived
-tasks. `t TASK` shows a task. Only exact root `t help` displays generic usage and
-native scoped help without looking up a task. Other first words are task
-references, even `new`, `show`, `edit`, or `he`.
-
-Task references prefer an exact name, then a unique case-sensitive prefix.
-Ambiguous prefixes fail. `t NAME new` creates the exact name instead of resolving
-a prefix. An unknown name is otherwise an error, except that `t NAME todo add`
-can create the task with its first todo.
-
-Use `.` for the current task. Selection checks the calling Herdr workspace,
-then the current directory, then the saved task. Stale or ambiguous context is
-an error. `t TASK current` saves a named selection without focusing a terminal;
-`t . current` only prints it. `t TASK switch` and `t TASK workspace` focus or
-create the task workspace and save a named selection only after success.
-`--show` inspects without changing focus or the saved task.
+`t` and `tt` are gem executables in `exe/`, installed alongside `h`. They are thin
+`Hiiro.run` launchers over `Hiiro::TaskCli` in `lib/hiiro/task_cli.rb`, which uses
+the `add_cmd` DSL and existing task records. `bin/t` and `bin/tt` are symlinks to
+the `exe/` files for running from a checkout with `ruby -Ilib bin/t`. `t new NAME`
+creates a task and its notes directory; `t tree new NAME` adds a Git worktree.
+
+Use `t COMMAND [TASK] [ARGS...]`. Bare `t`, `t ls`, or `t list` lists every task,
+including done and archived tasks, with the count of open todos after each name.
+Commands that act on a task take it from the first positional argument when
+that word names a task (exact or unique case-sensitive prefix); otherwise the
+current task is used and the word stays in the payload, exactly like the old
+`h task` commands. `-t TASK` forces a task, `-f` picks one with a fuzzy finder,
+`.` is the current task, and `-` selects orphan todos. Ambiguous prefixes fail.
+
+The current task is the calling Herdr workspace, then the current directory
+inside a task home, code directory, worktree, or registered directory, then the
+task saved with `t use TASK`. `t switch TASK` focuses or creates the task
+workspace and also saves it. `t current` only prints.
 
 ```sh
-t investigation new
-t investigation next "Inspect the failing request"
-t investigation todo add Compare the retry settings
-tt investigation add Inspect --help output
-t investigation doc new findings
-t investigation doc open findings
-t investigation
-t investigation todo rm 42 # Use an item ID printed by show or todo list.
-t investigation current
-t investigation switch
-t investigation workspace --show
-t . next "Write the handoff"
+t new investigation
+t next investigation "Inspect the failing request"
+t todo add investigation Compare the retry settings
+tt add Inspect --help output          # current task
+t doc new investigation findings
+t show investigation
+t todo rm 42                          # an ID printed by show or todo list
+t use investigation
+t switch investigation
+t switch --show
+t next . "Write the handoff"
+t tree new investigation
 ```
 
-A task has one `next_action` and can have multiple independent todos. `t TASK`
-and `t TASK todo` print todos with their IDs, statuses, and text in ID order.
-`t TASK todo rm ID` deletes only that exact decimal ID in the selected scope.
-`tt TASK ...` delegates to `t TASK todo ...`; bare `tt` means `t . todo`, and
-`tt help` displays todo help. Use `t - todo` or `tt -` for orphan todos, including
-`add` and `rm`. `-` is not a task and is invalid outside todo commands.
+A task has one `next_action` and can have multiple independent todos. `t show`
+and `t todo` print todos with their IDs, statuses, and text in ID order.
+`t todo show ID` prints one todo's text and `t todo rm ID` deletes it.
+`tt ...` is `t todo ...`. Use `t todo -` and `tt add - TEXT` for orphan todos.
 
-Every argument after `todo add` is literal text, including flags and `--`,
-except that leading `add -h` or `add --help` displays help. Empty text fails
-without creating a task.
+Every argument after the task in `todo add` is literal text, including flags and
+`--`, except a leading `-h` or `--help`. Empty text fails. Only `t new NAME`
+creates tasks.
 
 Todos share the existing `todos` table with `h todo`. `t` writes only to the
 database and does not rewrite `todo.yml`. Adding or removing a todo does not
 change the task's next action, status, or saved selection. Task completion and
-archival preserve todos; `h task` behavior is unchanged.
+archival preserve todos. `h task` is a symlink to `t`, so both share one grammar.
 
-`t TASK omp`, `t TASK codex` or `cdx`, and `t TASK claude` or `cld` start fresh
+`t omp [TASK]`, `t codex` or `cdx`, and `t claude` or `cld` start fresh
 native CLI sessions in new focused Herdr tabs. Claude always runs `claude`.
-Only a nonempty prefix of `resume` as the first tool argument changes mode.
-Bare `resume` focuses the unique running instance of that tool in the task
-workspace, or launches the native resume picker if none is running. Multiple
-running matches are an error. With an ID or any other arguments after `resume`,
-the command always opens a new tab and passes those arguments to the native CLI.
-All other arguments, including `--help`, are tool flags, not `t` flags.
 
 Tasks can share an existing directory, including a worktree. `t` does not change
 Git state or promise task-isolated persisted AI sessions in shared directories.
@@ -139,18 +128,21 @@ See the [task command reference](docs/t.md) for all commands and the [workflow i
 | `h setup` | Install plugins and subcommands to system paths |
 | `h edit` | Open the h script in your editor |
 | `h alert` | macOS desktop notifications via terminal-notifier |
-| `h task` | Task management across git worktrees, including existing external worktrees (via Tasks plugin) |
-| `h subtask` | Subtask management within tasks (via Tasks plugin) |
+| `h herdr` | Herdr plugin for `t`: fuzzy task switcher, todo capture, todo copy, task shell and nvim popups (`h herdr install`) |
+| `h task` | Same program as `t`: task records, todos, worktrees (`t NAME tree new`), and Herdr workspaces |
 
 ### External Subcommands
 
 | Command | Description |
 |---------|-------------|
+| `h alias` | Append safely quoted zsh aliases |
 | `h app` | Manage app directories within tasks/projects |
+| `h bin` | Create, list, and edit Hiiro executables |
 | `h branch` | Git branch management with fuzzy selection and copy |
 | `h claude` | Claude CLI wrapper with Herdr split support |
 | `h commit` | Select commits using fuzzy finder |
 | `h config` | Open config files (vim, git, Herdr, zsh, starship, claude) |
+| `h env` | Append safely quoted environment variables |
 | `h link` | Manage saved links with URL, description, and shorthand |
 | `h pane` | Herdr pane management |
 | `h plugin` | Manage hiiro plugins (list, edit, search) |
@@ -168,6 +160,33 @@ See the [task command reference](docs/t.md) for all commands and the [workflow i
 
 `h claude agents|commands|skills -a` prints the absolute file path for each matching `.claude` tool, including `SKILL.md` for skills.
 
+### Shell helpers
+
+```sh
+h env add exam ple
+h alias add ll 'ls -al'
+h alias add --global PAGER '| less'
+h bin add scratch
+h bin add josh list show
+```
+
+`h env add NAME VALUE` appends a literal `export NAME="VALUE"` to
+`~/.zshenv.d/vars.zsh` when that file exists, otherwise to `~/.zshenv`.
+`h alias add NAME COMMAND...` similarly prefers `~/.zshrc.d/aliases.zsh`,
+falling back to `~/.zshrc`. Existing contents are preserved. A single quoted
+command string preserves shell syntax; separate command arguments retain their
+argument boundaries. Use `--global` or `-g` for a global zsh alias.
+
+These commands use native Hiiro option parsing and help. Use `--` before
+flag-like data, for example `h env add LABEL -- --literal` or
+`h alias add inspect -- tool --help`. Start a new shell or source the relevant
+configuration file to apply additions.
+
+`h bin add NAME [COMMAND ...]` creates an executable `~/bin/h-NAME` using
+`Hiiro.run`. Without commands its block is empty; each command adds an empty
+`add_cmd` block with a Ruby symbol. Existing files and symlinks are never
+overwritten. See the [bin command reference](docs/h-bin.md).
+
 ## Abbreviations
 
 Any subcommand can be abbreviated as long as the prefix uniquely matches:
@@ -187,7 +206,7 @@ Plugins are Ruby modules loaded from `~/.config/hiiro/plugins/`:
 |--------|-------------|
 | Pins | Per-command YAML key-value storage |
 | Project | Project directory navigation with Herdr workspace management |
-| Tasks | Task lifecycle management across git worktrees with external-worktree registration and subtask support |
+| Tasks | `Hiiro::TaskManager` worktree creation and current-task environment used by `t`, `h service`, `h run`, and `h file` |
 | Notify | Herdr desktop notifications |
 
 ## Adding Subcommands
@@ -294,6 +313,13 @@ shared with nested groups without consuming its name again.
 For a CLI that should dispatch only registered blocks, pass
 `external_commands: false` to `Hiiro.run` and its `run_child` or `make_child` calls. This
 prevents unrelated same-prefix executables on `PATH` from taking precedence.
+Pass `builtin_commands: false` as well to skip the automatic `pry` and `edit`
+commands, for CLIs whose first word is data rather than a command name.
+
+Raise `Hiiro::Error` (or a subclass) for expected user-facing failures such as
+bad arguments or missing records. `Hiiro#run` prints `ERROR: message` to stderr
+and exits 1 without a backtrace; any other exception still prints its backtrace.
+`open_default(target)` opens a path or URL with the OS handler (`open` or `xdg-open`).
 
 ## Writing Plugins
 

data/bin/h-alias

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+  add_flag :global, short: :g, desc: 'Create a global zsh alias'
+
+  add_cmd :add, args: ['NAME', 'COMMAND...'], opts: [:global] do
+    abort 'Usage: h alias add [--global|-g] NAME COMMAND...' unless opts.args.length >= 2
+    name, *command_args = opts.args
+    abort 'Invalid alias name' unless /\A[A-Za-z0-9_.][A-Za-z0-9_.-]*\z/.match?(name)
+    command = command_args.length == 1 ? command_args.first : Shellwords.join(command_args)
+    quoted = "'" + command.gsub("'") { "'\\''" } + "'"
+
+    home = ENV.fetch('HOME')
+    path = File.join(home, '.zshrc.d', 'aliases.zsh')
+    path = File.join(home, '.zshrc') unless File.file?(path)
+
+    File.open(path, 'a+', 0o600) do |file|
+      unless file.size.zero?
+        file.seek(-1, IO::SEEK_END)
+        file.write("\n") unless file.read(1) == "\n"
+      end
+      file.write("alias #{opts.global ? '-g ' : ''}#{name}=#{quoted}\n")
+    end
+    puts "Added alias to #{path}"
+  end
+end

data/bin/h-bin

@@ -3,6 +3,26 @@
 require 'hiiro'
 
 Hiiro.run do
+  add_cmd :add, args: ['NAME', 'COMMAND...'] do
+    name, *commands = opts.args
+    name = name&.delete_prefix('h-')
+    abort 'Use a command name containing letters, digits, underscores, or hyphens' unless name&.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+    abort 'Subcommand names cannot be empty' if commands.any?(&:empty?)
+
+    path = File.join(Dir.home, 'bin', "h-#{name}")
+    body = commands.map { |command| "  add_cmd #{command.to_sym.inspect} do\n  end" }.join("\n\n")
+    template = "#!/usr/bin/env ruby\n\nrequire 'hiiro'\n\nHiiro.run do\n"
+    template << "#{body}\n" unless body.empty?
+    template << "end\n"
+
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o755) do |file|
+      file.write(template)
+      file.chmod(0o755)
+    end
+    puts path
+  end
+
   add_subcmd(:list) do |*subcmd_names|
     patterns = subcmd_names.flatten.compact.map { |sc|
       sc.sub(/^(?!h-)/, '{h-,}')

data/bin/h-env

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+  add_cmd :add, args: %i[NAME VALUE] do
+    abort 'Usage: h env add NAME VALUE' unless opts.args.length == 2
+    name, value = opts.args
+    abort 'Invalid environment variable name' unless /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(name)
+
+    home = ENV.fetch('HOME')
+    path = File.join(home, '.zshenv.d', 'vars.zsh')
+    path = File.join(home, '.zshenv') unless File.file?(path)
+    escaped = value.gsub(/["\\$`]/) { |char| "\\#{char}" }
+
+    File.open(path, 'a+', 0o600) do |file|
+      unless file.size.zero?
+        file.seek(-1, IO::SEEK_END)
+        file.write("\n") unless file.read(1) == "\n"
+      end
+      file.write("export #{name}=\"#{escaped}\"\n")
+    end
+    puts "Added environment variable to #{path}"
+  end
+end

data/bin/h-herdr

@@ -0,0 +1,156 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+require 'fileutils'
+
+# Herdr plugin glue for the t task CLI. The plugin manifest lives in the gem's
+# herdr-plugin/ directory; `h herdr install` copies it to ~/.config/hiiro/herdr-plugin
+# and links it with `herdr plugin link`. Actions run headless behind keybindings and
+# open the plugin popup; `h herdr popup` runs inside that popup with a real TTY.
+
+PLUGIN_ID = 'hiiro'
+ACTIONS = %w[switch todo-add todos shell nvim].freeze
+INSTALL_DIR = Hiiro::Config.config_dir('herdr-plugin')
+SOURCE_DIR = File.expand_path('../herdr-plugin', File.dirname(File.realpath(__FILE__)))
+KEYS_SNIPPET = <<~TOML
+  # Hiiro task actions (h herdr keys)
+  [[keys.command]]
+  key = "prefix+t"
+  type = "plugin_action"
+  command = "hiiro.switch"
+  description = "switch to task"
+
+  [[keys.command]]
+  key = "prefix+shift+a"
+  type = "plugin_action"
+  command = "hiiro.todo-add"
+  description = "add todo"
+
+  [[keys.command]]
+  key = "prefix+shift+y"
+  type = "plugin_action"
+  command = "hiiro.todos"
+  description = "copy a todo"
+
+  [[keys.command]]
+  key = "prefix+shift+s"
+  type = "plugin_action"
+  command = "hiiro.shell"
+  description = "task shell popup"
+
+  [[keys.command]]
+  key = "prefix+shift+e"
+  type = "plugin_action"
+  command = "hiiro.nvim"
+  description = "task notes in nvim"
+TOML
+
+def herdr_bin
+  ENV['HERDR_BIN_PATH'] || 'herdr'
+end
+
+def source_dir
+  return SOURCE_DIR if File.exist?(File.join(SOURCE_DIR, 'herdr-plugin.toml'))
+  gem_root = Gem.loaded_specs['hiiro']&.full_gem_path
+  gem_root && File.join(gem_root, 'herdr-plugin')
+end
+
+Hiiro.run(*ARGV, external_commands: false) do
+  add_cmd(:install) do
+    no_args = opts.args.empty?
+    raise Hiiro::Error, 'h herdr install takes no arguments' unless no_args
+    src = source_dir
+    raise Hiiro::Error, 'Plugin manifest not found; reinstall the hiiro gem' unless src
+    FileUtils.mkdir_p(File.dirname(INSTALL_DIR))
+    FileUtils.rm_rf(INSTALL_DIR)
+    FileUtils.cp_r(src, INSTALL_DIR)
+    puts "Copied plugin to #{INSTALL_DIR}"
+    linked = system(herdr_bin, 'plugin', 'link', INSTALL_DIR)
+    puts(linked ? 'Linked plugin "hiiro" in Herdr' : 'Plugin already linked or link failed; run: herdr plugin list')
+    puts "\nAdd keybindings to ~/.config/herdr/config.toml (h herdr keys prints them), then run:"
+    puts '  herdr server reload-config'
+  end
+
+  add_cmd(:uninstall) do
+    system(herdr_bin, 'plugin', 'unlink', PLUGIN_ID)
+    FileUtils.rm_rf(INSTALL_DIR)
+    puts "Removed #{INSTALL_DIR}"
+  end
+
+  add_cmd(:keys) { puts KEYS_SNIPPET }
+
+  add_cmd(:actions) { ACTIONS.each { |name| puts "hiiro.#{name}" } }
+
+  # Headless: bound to a key, opens the popup with the chosen action.
+  add_cmd(:action, args: %i[name]) do
+    name = opts.args.first
+    raise Hiiro::Error, "Unknown action #{name}; one of #{ACTIONS.join(', ')}" unless ACTIONS.include?(name)
+    size = %w[shell nvim].include?(name) ? %w[--width 90% --height 90%] : []
+    system(herdr_bin, 'plugin', 'pane', 'open', '--plugin', PLUGIN_ID, '--entrypoint', 'popup',
+           '--env', "HIIRO_HERDR_ACTION=#{name}", *size, '--focus')
+  end
+
+  # Runs inside the popup pane (real TTY, HERDR_WORKSPACE_ID set by Herdr).
+  add_cmd(:popup) do
+    name = ENV['HIIRO_HERDR_ACTION'] || opts.args.first
+    raise Hiiro::Error, "Set HIIRO_HERDR_ACTION to one of #{ACTIONS.join(', ')}" unless ACTIONS.include?(name)
+    run_popup(name)
+  end
+
+  def tasks
+    Hiiro::TaskRecord.all_as_list.reject { |task| %w[done archived].include?(task.task_status) }
+  end
+
+  def current_task_name
+    Hiiro::CurrentTask.new(herdr: -> { herdr_client }, pin: true).resolve&.name
+  end
+
+  def pick_task(prompt_current: true)
+    current = prompt_current && current_task_name
+    names = tasks.map(&:name)
+    names = [current, *names.reject { |n| n == current }] if current
+    raise Hiiro::Error, 'No tasks; create one with t NAME new' if names.empty?
+    choice = fuzzyfind(names)
+    raise Hiiro::Error, 'No task selected' if choice.nil? || choice.strip.empty?
+    choice.strip
+  end
+
+  def pause(message)
+    $stderr.puts message
+    sleep 2
+  end
+
+  def run_popup(name)
+    case name
+    when 'switch'
+      task = pick_task(prompt_current: false)
+      system('t', 'switch', task) || pause("t switch #{task} failed")
+    when 'todo-add'
+      task = pick_task
+      print "Todo for #{task}: "
+      text = $stdin.gets.to_s.strip
+      raise Hiiro::Error, 'No todo text' if text.empty?
+      system('t', 'todo', 'add', '-t', task, text) || pause('todo add failed')
+      sleep 1
+    when 'todos'
+      task = current_task_name || pick_task
+      items = Hiiro::TodoItem.where(task_name: task, subtask_name: nil).exclude(status: %w[done skip]).order(:id).all
+      raise Hiiro::Error, "No open todos for #{task}" if items.empty?
+      text = fuzzyfind_from_map(items.to_h { |item| ["#{item.id}  #{item.text}", item.text] })
+      raise Hiiro::Error, 'No todo selected' unless text
+      Hiiro::Shell.pipe(text, 'pbcopy')
+      puts "Copied: #{text}"
+      sleep 1
+    when 'shell'
+      exec('t', 'sh')
+    when 'nvim'
+      task = Hiiro::CurrentTask.new(herdr: -> { herdr_client }, pin: true).resolve!
+      FileUtils.mkdir_p(task.home)
+      Dir.chdir(task.home)
+      exec(ENV['EDITOR'] || 'nvim', '.')
+    end
+  rescue Hiiro::Error => e
+    pause("ERROR: #{e.message}")
+    exit 1
+  end
+end

data/bin/h-task

@@ -0,0 +1 @@
+../exe/t

data/bin/t

@@ -0,0 +1 @@
+../exe/t

data/bin/tt

@@ -0,0 +1 @@
+../exe/tt

data/docs/h-bin.md

@@ -1,8 +1,8 @@
 # h-bin
 
-List and edit hiiro bin scripts (`h-*` executables found in PATH).
+Create, list, and edit Hiiro bin scripts.
 
-`h bin` uses `Hiiro::Bins` to scan the current `PATH` for executable files.
+`h bin add` creates executables in `~/bin`. The `list` and `edit` commands use `Hiiro::Bins` to scan the current `PATH`.
 
 ## Synopsis
 
@@ -14,9 +14,56 @@ h bin <subcommand> [names...]
 
 | Subcommand | Description |
 |------------|-------------|
+| `add NAME [COMMAND ...]` | Create an executable template without overwriting an existing file |
 | `list [names]` | List matching bin files |
 | `edit [names]` | Open matching bin files in editor |
 
+### add
+
+Create `~/bin/h-NAME`. An optional `h-` prefix is accepted. Executable names must
+start with a letter or digit and contain only letters, digits, underscores, or
+hyphens.
+
+```sh
+h bin add scratch
+```
+
+With no command arguments, the generated file contains:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+end
+```
+
+To include empty command blocks:
+
+```sh
+h bin add josh list show
+```
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+  add_cmd :list do
+  end
+
+  add_cmd :show do
+  end
+end
+```
+
+Command names are serialized as Ruby symbols, including quoted symbols for
+names such as `hello-world`. Generated files are executable. Existing files
+and symlinks are refused, and no editor or generated command is launched.
+Native Hiiro options handle `--help` and the `--` end-of-options marker.
+
 ### edit
 
 Open matching `h-*` bin files in your editor. With no arguments, opens `h-bin` itself.

data/docs/h-herdr.md

@@ -0,0 +1,41 @@
+# h herdr
+
+Expose the `t` task CLI inside Herdr as keybound actions. Each action opens a session-modal popup that runs `h herdr popup`, so fuzzy pickers and editors get a real TTY without disturbing the tiled layout.
+
+## Install
+
+```bash
+h herdr install              # copies herdr-plugin/ to ~/.config/hiiro/herdr-plugin and runs herdr plugin link
+h herdr keys                 # prints [[keys.command]] entries to paste into ~/.config/herdr/config.toml
+herdr server reload-config
+```
+
+`h herdr uninstall` unlinks the plugin and removes the copied directory. Requires Herdr 0.7.4 or newer, and `sk` or `fzf` on `PATH`.
+
+## Actions
+
+| Action | Default key | Popup behavior |
+|---|---|---|
+| `hiiro.switch` | `prefix+t` | Fuzzy-pick an active or waiting task, then `t NAME switch` |
+| `hiiro.todo-add` | `prefix+shift+a` | Fuzzy-pick a task (current task first), type the todo text, then `t NAME todo add TEXT` |
+| `hiiro.todos` | `prefix+shift+y` | Fuzzy-pick an open todo of the current task and copy its text to the clipboard |
+| `hiiro.shell` | `prefix+shift+s` | 90% popup running `t sh` in the current task's start directory |
+| `hiiro.nvim` | `prefix+shift+e` | 90% popup running `$EDITOR` (default `nvim`) in the current task's notes home |
+
+The current task resolves through `Hiiro::CurrentTask`: the popup's Herdr workspace, then the working directory, then the task saved with `t use TASK`. Errors print in the popup for two seconds before it closes.
+
+## Subcommands
+
+| Command | Behavior |
+|---|---|
+| `h herdr install` | Copy the manifest from the gem, link it in Herdr, print next steps |
+| `h herdr uninstall` | Unlink and remove the copy |
+| `h herdr keys` | Print the keybinding snippet |
+| `h herdr actions` | List action ids |
+| `h herdr action NAME` | Headless: open the popup for NAME (what the manifest binds) |
+| `h herdr popup` | Runs inside the popup; reads `HIIRO_HERDR_ACTION` |
+
+## Files
+
+- `herdr-plugin/herdr-plugin.toml` in the gem: manifest with five `[[actions]]` and one `[[panes]]` popup entrypoint
+- `bin/h-herdr`: actions, popup logic, install and keys helpers